Queues
What it is
nodabase.que is how a Node.js application publishes and consumes messages. Nodabase uses NATS underneath, and the parts that need durability use JetStream, NATS's persistence layer.
The client gives you two consumption styles on purpose:
- publish goes through JetStream — the message is persisted and acknowledged, and the subject has to be covered by a stream.
- subscribe uses core NATS — simple, works for any subject, at-most-once delivery.
Messages are JSON in both directions: what you publish is encoded as JSON, and what arrives in your callback is decoded back into an object.
How it works
Node.js application
|
v
nodabase.que
|
v
NATS
(JetStream)One connection is opened lazily on first use and shared by every call. Streams hold messages on the NATS server; consumers read from them with explicit acknowledgement.
Configuration
NODABASE_QUE_URL=nats://localhost:4222
NODABASE_QUE_URL must be set for nodabase.que to exist — the provider refuses to start without it. When your application runs inside the Nodabase platform, the binding is provided for you.
Basic usage
Create a stream, then publish to a subject it covers:
import { nodabase } from "nodabase";await nodabase.que.createStream({name: "MY_STREAM",subjects: ["myapp.>"],storage: "file",});await nodabase.que.publish("myapp.link.saved", { id, title });
storage is optional and defaults to "file". The subject pattern myapp.> matches any subject under myapp.. publish resolves to { stream, sequence } once JetStream has acknowledged the message.
Subscribe with core NATS — no stream required:
const subscription = await nodabase.que.subscribe("myapp.link.saved",async ({ data }) => console.log(data));await subscription.close();
The callback receives { data, subject }, and subscription.close() stops it.
Common operations
The whole surface at a glance:
| Method | Returns | Notes |
|---|---|---|
publish(subject, data) | { stream, sequence } | JetStream; the subject must be covered by a stream |
subscribe(subject, callback) | { close() } | core NATS; works for any subject |
createStream({ name, subjects, storage }) | { name, subjects, storage } | storage defaults to "file" |
deleteStream(name) | true / false | false when the stream did not exist |
streams.list() | array of streams | |
consumer({ stream, name, subject, ackPolicy }) | consumer with consume(callback) | durable consumer |
consumers.list(stream) / consumersList(stream) | array of consumers | the same list under two names |
close() | drains the connection |
Managing streams
await nodabase.que.streams.list();// [{ name: "MY_STREAM", subjects: ["myapp.>"], storage: "file" }]await nodabase.que.deleteStream("MY_STREAM"); // true, or false if it was not there
List what exists before creating a stream — names are global, and publishing to a subject that no stream captures fails.
Durable consumers
For consumption that has to survive restarts, create a durable consumer on a stream and consume from it:
const consumer = await nodabase.que.consumer({stream: "MY_STREAM",name: "link-processor",subject: "myapp.link.saved", // optional per-consumer filter});const handle = await consumer.consume(async (message) => {console.log(message.data, message.sequence);await message.ack();});await handle.close();
Each message carries more than a subscribe callback does:
message.data; // decoded JSON payloadmessage.subject;message.sequence;await message.ack(); // done with itawait message.nack({ delay: 5 }); // put it back after a delayawait message.term(); // stop redelivering it
ackPolicy defaults to "explicit", which is what makes ack() meaningful. List a stream's consumers with nodabase.que.consumers.list("MY_STREAM") — each entry has name, stream, ackPolicy and filterSubject.
Closing the connection
await nodabase.que.close();
Long-running servers keep the connection open for the life of the process. Scripts and one-shot jobs should call close() when they are done.
Important notes
- Publishing to a subject that no stream captures fails — that is JetStream working as intended.
streams.list()first, then create the stream you are missing. - Everything is JSON. Payloads must be JSON-serializable in both directions.
subscribeis at-most-once: if the process is down, those messages are not redelivered. When a message must be processed exactly once across restarts, use a durable consumer withack().- Without
NODABASE_QUE_URL,nodabase.queis absent from the client — the same pattern asdbandcache.
Next steps
- Storage — S3-compatible object storage through MinIO
- Jobs — scheduled HTTP requests through the Job Runner
- Overview — how the client and the services fit together
- Quickstart — run the platform