Quickstart

Install the client:

npm i queen-mq

yarn add queen-mq

pnpm add queen-mq

bun add queen-mq

Point it at the broker. The constructor accepts a single URL string:

import { Queen } from 'queen-mq'

const client = new Queen('http://localhost:6632')

Push a message. data is your payload, and it must be JSON. The blocks below are extracted verbatim from the files the JavaScript suite executes, which is why the queue names look like test fixtures; substitute your own:

const res = await client
.queue('test-queue-v2')
.push([{ data: { message: 'Hello, world!' } }])

The result is one entry per item, and status is queued when the message was stored. Now consume it. .consume() polls, hands each message to your callback, and acknowledges it when the callback resolves; .limit(1) makes it stop after one message instead of running forever:

await client
.queue('test-queue-v2-consume')
.batch(1)
.limit(1)
.each()
.consume(async msg => {
    msgToReturn = msg
})

If you want the raw pop instead of the managed consumer loop, .pop() returns an array of messages and leaves acknowledgement to you. .wait(true) turns on long-polling, so the call parks until a message arrives or the timeout expires rather than returning empty immediately:

const res = await client
.queue('test-queue-v2-pop-non-empty')
.batch(1)
.wait(true)
.pop()

Push one message. items is an array; queue and payload are required, and partition defaults to Default if you omit it:

curl -i -X POST http://localhost:6632/api/v1/push -H 'Content-Type: application/json' -d '{"items":[{"queue":"orders","partition":"customer-42","payload":{"hello":"world"}}]}'

The response is HTTP 201 and a top-level array, one entry per item, in request order:

[{"index":0,"message_id":"019842f1-...","transaction_id":"019842f1-...","queueName":"orders","status":"queued"}]

You did not supply a transactionId, so the broker minted one from the message id. Supplying your own is what makes a retry of this call idempotent.

Now pop. wait=true long-polls instead of returning immediately, and consumerGroup names the cursor that will remember what you consumed:

curl -i "http://localhost:6632/api/v1/pop/queue/orders?batch=1&wait=true&consumerGroup=demo"

{"success":true,"queue":"orders","partition":"customer-42","partitionId":"6b1c...","leaseId":"019842f1-...","consumerGroup":"demo","messages":[{"id":"019842f1-...","transactionId":"019842f1-...","traceId":null,"data":{"hello":"world"},"producerSub":null,"createdAt":"2026-07-30T09:14:02.117364Z","partitionId":"6b1c...","partition":"customer-42","leaseId":"019842f1-...","consumerGroup":"demo"}]}

That pop took a lease: the span is claimed for this consumer group until you acknowledge it or the lease expires. Acknowledge it with the transactionId and partitionId from the message, plus the leaseId:

curl -i -X POST http://localhost:6632/api/v1/ack -H 'Content-Type: application/json' -d '{"transactionId":"019842f1-...","partitionId":"6b1c...","status":"completed","consumerGroup":"demo","leaseId":"019842f1-..."}'

[{"index":0,"transactionId":"019842f1-...","success":true,"error":null,"leaseReleased":true,"dlq":false,"noop":false}]

The ack response is HTTP 200 even when an individual ack was rejected (a stale lease, an offset already committed), so the per-item success flag is the signal to check, not the status code.