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-node

Requires 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 required
    NatsConnection
    Used 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 scheduled
    payload · job type name
    Published when jobs become pending. Wakes idle workers.
  • {prefix}.chainc chain completed
    payload · chain id
    Published when a chain completes. Wakes clients awaiting results.
  • {prefix}.atls attempt lost
    payload · job id
    Published 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

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open