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

env
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:

js
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:

js
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:

MethodReturnsNotes
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 / falsefalse 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 consumersthe same list under two names
close()drains the connection

Managing streams

js
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:

js
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:

js
message.data; // decoded JSON payload
message.subject;
message.sequence;
 
await message.ack(); // done with it
await message.nack({ delay: 5 }); // put it back after a delay
await 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

js
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.
  • subscribe is 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 with ack().
  • Without NODABASE_QUE_URL, nodabase.que is absent from the client — the same pattern as db and cache.

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