Notify Adapters

Wake workers in other processes the moment jobs are scheduled instead of polling, and the NotifyAdapter interface every backend implements.

Notify adapters handle pub/sub notifications for efficient job scheduling. When a job is created, workers in every process are notified immediately instead of polling. This reduces latency from seconds to milliseconds.

PostgreSQL

Uses PostgreSQL's built-in LISTEN/NOTIFY. No additional infrastructure beyond your existing PostgreSQL database.

  • Package@queuert/postgres
  • TransportLISTEN / NOTIFY
  • Driverspg · postgres.js · Bun SQL

Redis

recommended

Uses Redis pub/sub, publishing each batch from one Lua script.

  • Package@queuert/redis
  • Transportpub/sub
  • Driversnode-redis · ioredis · Bun

NATS

experimental

Uses NATS core pub/sub. The adapter takes the NatsConnection directly.

  • Package@queuert/nats
  • Transportcore pub/sub
  • Drivers@nats-io/transport-node

IPC

experimental

For processes on one host, such as workers sharing a SQLite file. No server: processes find each other through a shared directory.

  • Package@queuert/ipc
  • TransportUnix sockets · named pipes
  • AdapterNotifyAdapter<"sync">

Custom

A NotifyAdapter of your own, for another message broker.

  • Packageyour own
  • Transportany broker
  • Checked byqueuert/conformance

Without a notify adapter

A client created without notifyAdapter delivers notifications in memory to itself: the worker runners created from it and its awaitChain calls wake the moment a transaction commits. Nothing crosses the process, or even the client: a worker runner in another process, or one built from a second client in the same process, polls the database every pollIntervalMs. No additional packages or infrastructure are required. To let several clients in one process wake each other, pass them one shared createInProcessNotifyAdapter() from queuert. Its default "sync" mode works over either kind of state adapter; mode: "async" is optional.

Tip

A single process with one client needs no notify adapter. Once workers run in other processes, polling is still a valid choice for low-throughput workloads where millisecond latency is not critical; pass a shared adapter when it is.

The NotifyAdapter interface

NotifyAdapter is exported from queuert. It has three notification channels, each with a batched notify* method and a listen* method, plus close:

NotifyAdapter

  • Job scheduled
    Jobs of the given types are available for processing; wakes the workers that process them. Every listener receives each notification.
    notifyJobsScheduled listenJobScheduled
  • Chain completed
    The given chains have completed; wakes whoever is waiting on one of them.
    notifyChainsCompleted listenChainCompleted
  • Attempt lost
    The given jobs lost their attempts: they were reclaimed from a worker whose lease expired or that stopped, completed workerless, or their chain was deleted.
    notifyJobAttemptsLost listenJobAttemptLost
  • Lifecycle
    close releases internal resources (shared subscriptions, listener registries) and cascades into the underlying provider, when there is one. [Symbol.asyncDispose] calls close, so an adapter can be held with await using. On a "sync" adapter, close returns nothing and [Symbol.dispose] calls it, so it is held with using.
    close [Symbol.asyncDispose] [Symbol.dispose]

A transport that never waits, such as in-process listeners or local sockets, can implement NotifyAdapter<"sync"> instead: the same members, each returning its result directly and throwing on failure, plus sync: true, and a close that returns nothing, with [Symbol.dispose] in place of [Symbol.asyncDispose], so the adapter is held with using. createClient takes either kind over an async state adapter, and only a sync one over a sync state adapter.

How adapters behave

  • Notifications are hints. The system works correctly even if they are lost or duplicated; workers fall back to polling.
  • One notification per item. notify* methods take a non-empty batch of unique items and publish each item as its own notification.
  • Delivery may be synchronous. A notify* call may run its listeners before it returns.
  • Listeners are isolated. A listener that throws does not keep other listeners from receiving the notification, and its error does not reach the notify* caller.
  • Listeners return a dispose function that unsubscribes.
  • close is idempotent. The second call is a no-op; after close, notify* and listen* calls fail, while dispose functions returned before close still work. On shutdown, stop the workers, close the notify adapter, close the state adapter, then close the clients and pools you own. Holding each with await using (using for a "sync" adapter), declared in the order they are created, closes them in this order.

For multi-worker coordination via notifications, see Horizontal Scaling.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open