Lowmq-client NPM

LowMQ Client for Node.js

A Node.js client library for interacting with the LowMQ message broker. LowMQ is a simple, HTTP-based message broker for easily managing message queues with both synchronous and asynchronous patterns.

Installation

To install the lowmq-client package, use npm or yarn:

npm install lowmq-client

yarn add lowmq-client

Setup and Usage

Import and Initialize the Client

You can import the client, set the server URL and authentication key, and start interacting with LowMQ:

import LowmqClient from 'lowmq-client'

const lowmq = new LowmqClient({
  host: 'localhost', // Default: 0.0.0.0
  port: 8788,        // Default: 8788
  authKey: 'your-auth-key', // Default: 'woof'
  tls: false,        // Enable TLS (HTTPS) if needed
})

Add a Packet

To add a new packet (message) to a queue:

const packet = await lowmq.add('test-queue', { message: 'Hello, world!' }, { freezeTimeMin: 10 })
console.log(packet)  // Packet is frozen for 10 minutes

Get a Packet

To retrieve a packet from a queue:

const packet = await lowmq.get('test-queue')
console.log(packet)  // Packet will be frozen for 5 minutes by default

Delete a Packet

To delete a packet from a queue:

await lowmq.delete('test-queue', packet._id)

Get and Delete a Packet

To get a packet and delete it in one operation:

const packet = await lowmq.get('test-queue', { delete: true })
console.log(packet)  // This packet has been deleted

Freeze a Packet

To freeze a specific packet:

await lowmq.freeze('test-queue', packet._id)

Unfreeze a Packet

To unfreeze a specific packet:

await lowmq.unfreezeOne('test-queue', packet._id)

Update a Packet

To update a packet's contents:

const updatedPacket = await lowmq.update('test-queue', packet._id, { message: 'Updated message' })
console.log(updatedPacket)

Error Handling

LowMQ client throws detailed errors based on RFC 7807 (Problem Details). The errors include types such as:

LowmqGetError
LowmqAddError
LowmqDeleteError
LowmqUpdateError
LowmqFreezeError

Each error contains the following properties:

type: The type of error (e.g., invalid-token, no-messages-found)
title: A short description of the error
status: The HTTP status code
detail: Detailed information about the error

Example:

try {
  const packet = await lowmq.get('non-existent-queue')
} catch (err) {
  if (err instanceof LowmqError) {
    console.error(`Error Type: ${err.type}, Message: ${err.problemDetails.detail}`)
  }
}

TLS Support

LowMQ supports TLS for secure communication. To enable TLS, pass in the necessary certificates when initializing the client:

const lowmq = new LowmqClient({
  host: 'your-host',
  port: 8788,
  authKey: 'your-auth-key',
  tls: true,
  tlsCert: '/path/to/cert.pem',
  tlsKey: '/path/to/key.pem',
  tlsCA: '/path/to/ca.pem'
})

Server Initialization Check

By default, the client performs an initial connection check to verify if the server is reachable. If you'd like to disable this behavior:

const lowmq = new LowmqClient({
  host: 'localhost',
  port: 8788,
  disableInitConnection: true
})

API Reference

LowmqClient

`new LowmqClient(config: object)`

host (optional): The LowMQ server host (default: 0.0.0.0)
port (optional): The LowMQ server port (default: 8788)
authKey (optional): The authorization key to access the LowMQ server (default: 'woof')
tls (optional): Enable TLS for secure communication (default: false)
tlsCert, tlsKey, tlsCA (optional): Paths to TLS certificate, key, and CA
retryTimeoutMs (optional): Time in milliseconds to retry a failed network request (default: 10000)

Methods

add<TPayload>(key: string, payload: TPayload, options?: { freezeTimeMin?: number }): Promise<LowmqMessage<TPayload>>
get<TPayload>(key: string, options?: { delete?: boolean }): Promise<LowmqMessage<TPayload>>
freeze(key: string, packetId: string): Promise<LowmqMessage>
unfreezeOne(key: string, packetId: string): Promise<LowmqMessage>
unfreezeAll(key: string): Promise<LowmqMessage[]>
update<TPayload>(key: string, packetId: string, payload: TPayload): Promise<LowmqMessage<TPayload>>
delete(key: string, packetId: string): Promise<LowmqMessage>