NATS Notify Adapter
Wake workers with NATS core pub/sub over a single NatsConnection.
createNatsNotifyAdapter uses NATS core pub/sub for job notifications. Like Redis, NATS is used exclusively as a notification adapter — it does not store job state; that stays in your state adapter.
Experimental
@queuert/nats is experimental: its API may change in a minor release.Install
Terminal
npm install @queuert/nats @nats-io/nats-core @nats-io/transport-nodeRequires NATS 2.2 or later.
Setup
src/index.ts
// Create NATS connection
await using nc = await connect(connectionOptions);
// Create the notify adapter
await using notifyAdapter = createNatsNotifyAdapter({
nc,
subjectPrefix: "queuert.example",
});The connection and the notify adapter are held with await using, so when the scope ends the notify adapter closes before the connection, in the shutdown order.
Configuration
createNatsNotifyAdapter options
- nc requiredNatsConnectionUsed for both publishing and subscribing.
- string · default "queuert"Prefix for the three subject names.
Conformance
The example's src/adapter.spec.ts runs notifyAdapterConformanceCases and is a working template. To run it under another test runner, see Custom Notify Adapter.
src/adapter.spec.ts
describe("postgresql/notify-nats adapter conformance", () => {
let nats: AcquiredNats;
let nc: NatsConnection;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
nats = await acquireNats("nats:2");
nc = await connect(nats.connectionOptions);
context = {
createNotifyAdapter: async () =>
createNatsNotifyAdapter({
nc,
subjectPrefix: `queuert.spec.${Date.now()}.${Math.random().toString(36).slice(2)}`,
}),
};
}, 60_000);
afterAll(async () => {
await nc.close();
await nats[Symbol.asyncDispose]();
});
for (const conformanceCase of notifyAdapterConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
for (const conformanceCase of notifyAdapterEndToEndConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});Subjects
Three NATS subjects carry notifications (configurable prefix, default queuert):
- {prefix}.sched job scheduledpayload · job type namePublished when jobs become pending. Wakes idle workers.
- {prefix}.chainc chain completedpayload · chain idPublished when a chain completes. Wakes clients awaiting results.
- {prefix}.atls attempt lostpayload · job idPublished when a running job's attempt is lost. Notifies attempt loss.
NATS core pub/sub is fire-and-forget — messages are delivered to currently connected subscribers only.
Connection model
NATS uses a single connection (NatsConnection) for both publishing and subscribing — unlike Redis, there is no need for separate connections. The adapter accepts the connection directly.
Examples
@queuert/nats
- GitHub NATS core pub/sub notifications.
$ pnpm --filter example-postgresql-notify-nats startsrc/index.ts