Custom State Adapter

Implement the StateAdapter interface for another database engine and validate it with the conformance suite.

For an entirely different database engine, implement the StateAdapter interface yourself. The conformance suite validates that your implementation behaves correctly. To use another client with PostgreSQL, SQLite or MySQL / MariaDB, write a provider instead: see PostgreSQL, SQLite or MySQL / MariaDB, each of which has its own conformance cases for providers.

Write a state adapter

Implement the StateAdapter type exported from queuert. Its members are grouped in The StateAdapter interface, and the rules every implementation follows are in How adapters behave. The TSDoc on each member states its contract.

Your adapter owns the transaction's side effects: onTransactionCommit runs a callback after the context's transaction commits, before the call that opened it settles, and onTransactionRollback runs one synchronously when the transaction, or the savepoint the context belongs to, rolls back. The client and the worker register every notify and observability event through them. Implement them from your database client's transaction events if it has them, or carry TxHooks in your transaction context, create them in withTransaction with withTxHooks, and register the callbacks on them; see Tx Hooks.

custom/state-memory is a complete implementation to start from: it keeps every table in plain in-memory maps, runs transactions one at a time on a copy of the state, carries TxHooks in its transaction context for onTransactionCommit and onTransactionRollback, and passes stateAdapterConformanceCases, stateAdapterEndToEndConformanceCases and their async lists.

Conformance

queuert/conformance exports the same cases Queuert uses internally, as lists to run against your adapter:

  • stateAdapterConformanceCases check the contract every state adapter must meet, calling the adapter's members directly with transactions run one at a time. They run fast.
  • concurrentStateAdapterConformanceCases hold two transactions open at once: blocker races, concurrent deletes, row locks, and reads that must not see uncommitted rows.
  • stateAdapterEndToEndConformanceCases check what an application sees end to end: each case builds a client and worker runners over your adapter and checks chains, continuations, blockers, scheduling, deduplication, deletion, workerless completion, queries, notifications and recovery from errors. They take a few seconds in all, so you may run them apart from the contract cases, such as only in CI.
  • concurrentStateAdapterEndToEndConformanceCases are end-to-end cases that need transactions running in parallel, such as several blocker chains completing at once, or several worker runners on a database that fails.

An async adapter also runs asyncStateAdapterConformanceCases next to the contract cases and asyncStateAdapterEndToEndConformanceCases next to the end-to-end ones: they hold a transaction open across an await, which only an async adapter can do. Run the two concurrent lists as well when your adapter can run transactions in parallel, such as one over a connection pool.

The suite drives no test runner. Your test file sets up the database in its own hooks and registers one test per case. Each case creates its own adapter with the context's createStateAdapter and closes it when it ends, so closing an adapter must leave the database usable for the next one. Each case has a title, and its run(context) resolves when the case passes and rejects when it fails. The cases share one context, so run them one at a time:

src/state-adapter.spec.ts

const context: StateAdapterConformanceContext = {
  createStateAdapter: async () => createMemoryStateAdapter(),
  withNonTransactionContext: async (fn) => fn({ transaction: undefined }),
};

for (const conformanceCase of [
  ...stateAdapterConformanceCases,
  ...asyncStateAdapterConformanceCases,
]) {
  test(conformanceCase.title, async () => {
    await conformanceCase.run(context);
  });
}

for (const conformanceCase of [
  ...stateAdapterEndToEndConformanceCases,
  ...asyncStateAdapterEndToEndConformanceCases,
]) {
  test(conformanceCase.title, async () => {
    await conformanceCase.run(context);
  });
}

The context holds:

StateAdapterConformanceContext

  • createStateAdapter required
    Creates an adapter over a clean state, with no jobs, blockers or workers. Each case calls it once and closes the adapter when it ends.
  • withNonTransactionContext required
    Runs a callback with the root handle, not a transaction, so the suite can check isTransaction rejects it.
  • createNotifyAdapter optional
    Creates the notify adapter every client and worker runner of an end-to-end case shares. Without it, each case gets an in-process notify adapter.

An adapter over a real database sets it up in beforeAll and releases it in afterAll, or before and after under node:test; the SQLite page shows all three runners. The full API is in the conformance reference.

For a "sync" StateAdapter, register only stateAdapterConformanceCases and stateAdapterEndToEndConformanceCases, without the async lists. They call the adapter's members synchronously, the end-to-end ones through a client over it. They run against the same StateAdapterConformanceContext, with a createStateAdapter that returns the adapter directly and a synchronous withNonTransactionContext. Every case takes its mode from your adapter's sync marker and checks the adapter calls it makes against it: a sync adapter fails a case when a call returns a promise or rejects instead of throwing, and an async one when a call returns a plain value. There are no concurrent cases for it: a synchronous transaction never overlaps another one on the same thread.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open