Custom Notify Adapter

Implement the NotifyAdapter interface for another message broker and validate it with Queuert's conformance suite.

For an entirely different message broker, implement the NotifyAdapter interface yourself. The conformance suite validates that your implementation behaves correctly. It's the same suite Queuert uses internally, exported as lists of cases to register one test each with any test runner. To use another client with PostgreSQL or Redis, write a provider instead: see PostgreSQL or Redis.

Write a notify adapter

Implement the NotifyAdapter type exported from queuert; its members and the rules they follow are in The NotifyAdapter interface.

This adapter from custom/notify-memory delivers notifications to listeners in the same process and passes every case:

src/notify-adapter.ts

/** Creates a notify adapter that delivers notifications to listeners in the same process. */
export const createMemoryNotifyAdapter = (): NotifyAdapter<"async"> => {
  const channels = new Map<string, Set<Listener>>();
  let closed = false;

  const assertOpen = (): void => {
    if (closed) throw new Error("Notify adapter is closed");
  };

  const subscribe = (channel: string, listener: Listener): (() => void) => {
    const listeners = channels.get(channel) ?? new Set<Listener>();
    listeners.add(listener);
    channels.set(channel, listeners);

    return () => {
      const current = channels.get(channel);
      current?.delete(listener);
      if (current?.size === 0) channels.delete(channel);
    };
  };

  const publish = (channel: string): void => {
    // Iterate a copy so a listener can subscribe or unsubscribe while it is being called
    for (const listener of Array.from(channels.get(channel) ?? [])) {
      try {
        listener();
      } catch {
        // A throwing listener must not keep the others from hearing the notification
      }
    }
  };

  const close = async (): Promise<void> => {
    closed = true;
    channels.clear();
  };

  return {
    notifyJobsScheduled: async (typeNames) => {
      assertOpen();
      for (const typeName of typeNames) publish(`job-scheduled:${typeName}`);
    },
    listenJobScheduled: async (typeNames, onNotification) => {
      assertOpen();
      const unsubscribes = typeNames.map((typeName) =>
        subscribe(`job-scheduled:${typeName}`, () => {
          onNotification(typeName);
        }),
      );
      return async () => {
        for (const unsubscribe of unsubscribes) unsubscribe();
      };
    },

    notifyChainsCompleted: async (chainIds) => {
      assertOpen();
      for (const chainId of chainIds) publish(`chain-completed:${chainId}`);
    },
    listenChainCompleted: async (chainId, onNotification) => {
      assertOpen();
      const unsubscribe = subscribe(`chain-completed:${chainId}`, () => {
        onNotification();
      });
      return async () => {
        unsubscribe();
      };
    },

    notifyJobAttemptsLost: async (jobIds) => {
      assertOpen();
      for (const jobId of jobIds) publish(`job-attempt-lost:${jobId}`);
    },
    listenJobAttemptLost: async (jobId, onNotification) => {
      assertOpen();
      const unsubscribe = subscribe(`job-attempt-lost:${jobId}`, () => {
        onNotification();
      });
      return async () => {
        unsubscribe();
      };
    },

    close,

    [Symbol.asyncDispose]: close,
  };
};

Conformance

notifyAdapterConformanceCases from queuert/conformance check your adapter's own contract (delivery, filtering, unsubscribing and concurrent listeners) and run fast. notifyAdapterEndToEndConformanceCases check what an application sees end to end: each case builds a client and worker runners over your adapter and an in-memory state adapter, so no database is needed, and checks worker runners waking up for scheduled jobs, awaitChain returning once a chain completes, and recovery when the adapter's calls fail. They take a few seconds in all, so you may run them apart from the contract cases, such as only in CI.

The suite drives no test runner: your test file registers one test per case, running each against a context with a createNotifyAdapter factory. Each case creates its own adapter from it and closes it when the case ends:

src/notify-adapter.spec.ts

const context: NotifyAdapterConformanceContext = {
  createNotifyAdapter: async () => createMemoryNotifyAdapter(),
};

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);
  });
}

The cases share one context, so run them one at a time. The full API is in the conformance reference.

For a "sync" NotifyAdapter, register the same notifyAdapterConformanceCases and notifyAdapterEndToEndConformanceCases, against the same NotifyAdapterConformanceContext, whose createNotifyAdapter may return the sync adapter directly. The contract cases call it synchronously, fail when a call returns a promise, and still wait for delivery; the end-to-end cases build a client over your adapter and an in-memory sync state adapter. Every case takes its mode from your adapter's sync marker, so over an async adapter it checks that the calls return promises.

A provider for PostgreSQL or Redis has its own cases and a helper that builds the adapter over the provider for you: see PostgreSQL or Redis.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open