Setu-TS — Public API Contract

This document describes how developers use the framework. Implementation details are intentionally omitted.

Table of Contents

• Shared reconnect supervisor (@setu-ts/common)
• Dotenv parser (@setu-ts/common)

1. Installation
2. Full Stack Application
3. Minimal Application
4. Kernel diagnostics (@setu-ts/kernel + @setu-ts/common)
5. createApplication() (@setu-ts/kernel)
6. RuntimePlugin() (@setu-ts/runtime)
7. LoggerPlugin() (@setu-ts/logger-plugin)
8. ConfigPlugin() (@setu-ts/config-plugin)
9. ValidationPlugin() (@setu-ts/validation-plugin)
10. DatabasePlugin() (@setu-ts/database-plugin)
11. AuthPlugin() (@setu-ts/auth-plugin)
12. HttpSecurityPlugin() (@setu-ts/http-security-plugin)
13. CachePlugin() (@setu-ts/cache-plugin)
14. EventsPlugin() (@setu-ts/events-plugin)
15. SsePlugin() (@setu-ts/sse-plugin)
16. WebSocketPlugin() (@setu-ts/websocket-plugin)
17. RealtimeBackplanePlugin() (@setu-ts/realtime-backplane-plugin)
18. SessionPlugin() (@setu-ts/session-plugin)
19. ReactRouterPlugin() (@setu-ts/react-router-plugin)
20. WorkerPoolPlugin() (@setu-ts/worker-pool-plugin)
21. Diagnostics Connector (@setu-ts/diagnostics-plugin)
22. SecretsPlugin() (@setu-ts/secrets-plugin)
23. AuditPlugin() (@setu-ts/audit-plugin)
24. CQRS (@setu-ts/cqrs-plugin)
25. Messaging (@setu-ts/messaging-plugin)
26. Queue (@setu-ts/queue-plugin)
27. Scheduler (@setu-ts/scheduler-plugin)
28. Resilience (@setu-ts/resilience-plugin)
29. Storage (@setu-ts/storage-plugin)
30. MailPlugin() (@setu-ts/mail-plugin)
31. Notifications (@setu-ts/notification-plugin)
32. Feature Flags (@setu-ts/feature-flags-plugin)
33. Multi-Tenancy Plugin (@setu-ts/multi-tenancy-plugin)
34. Health (@setu-ts/health-plugin)
35. Metrics (@setu-ts/metrics-plugin)
36. Telemetry (@setu-ts/telemetry-plugin)
37. OpenAPI (@setu-ts/openapi-plugin)
38. CLI (@setu-ts/cli)
39. REST API Application
40. Microservice Application
41. CQRS Application
42. Plugin Creation
43. Custom Middleware
44. Custom Decorators
45. Service Discovery (@setu-ts/service-discovery-plugin)
46. Programmatic vs Decorator API
47. Developer Ergonomics
48. API Reference: @setu-ts/common
49. API Reference: @setu-ts/kernel
50. API Reference: @setu-ts/runtime
51. API Reference: @setu-ts/exceptions
52. API Reference: @setu-ts/di-plugin
53. API Reference: @setu-ts/decorator-plugin
54. Testing Package (@setu-ts/testing)
55. SDK — Client SDK (@setu-ts/sdk)
56. API Reference: @setu-ts/grpc-plugin
57. API Reference: @setu-ts/cloudflare-plugin
58. GraphQL (@setu-ts/graphql-plugin)
59. Static Files Plugin (@setu-ts/static-plugin)
60. View Plugin (@setu-ts/view-plugin)
61. IdempotencyPlugin() (@setu-ts/idempotency-plugin)
62. Localization Plugin (@setu-ts/localization-plugin)
63. Boundary-Type Compatibility
64. Summary

Installation

Packages are published to npm under the @setu-ts scope and are consumable from every runtime:

# npm (pnpm add / yarn add work the same way)
npm install @setu-ts/kernel @setu-ts/runtime

# bun
bun add @setu-ts/kernel @setu-ts/runtime

# Deno
deno add npm:@setu-ts/kernel npm:@setu-ts/runtime

Add plugins as needed:

npm install @setu-ts/logger-plugin @setu-ts/config-plugin \
            @setu-ts/validation-plugin @setu-ts/database-plugin \
            @setu-ts/auth-plugin @setu-ts/openapi-plugin

Or use a starter bundle:

npm install @setu-ts/rest-starter

Earlier releases were published on JSR (jsr:@setu-ts/…) and stay there; nothing new is published to JSR.

Full Stack Application

A full-featured service with caching, events, scheduling, and more:

import { createFullStackApp } from '@setu-ts/full-stack-starter';

const app = createFullStackApp({
  cache: { store: 'memory' },
  events: {},
  audit: { storage: 'memory' },
  secrets: { provider: 'env' },
  storage: { provider: 'memory' },
  mail: { provider: 'log' },
});

app.router.get('/health', (ctx) => ctx.response.json({ status: 'ok' }));

await app.start({ port: 3002 });

Minimal Application

The smallest possible application — just the kernel and runtime:

import { createApplication } from '@setu-ts/kernel';
import { RuntimePlugin } from '@setu-ts/runtime';

const app = createApplication({
  plugins: [RuntimePlugin()],
});

app.router.get('/', (ctx) => {
  return ctx.response.json({ message: 'Hello, World!' });
});

await app.start({ port: 3000 });

No decorators. No DI. No reflection. Just a router and a runtime.

Kernel diagnostics (@setu-ts/kernel + @setu-ts/common)

An optional, read-only view of application composition and kernel execution. Enable it explicitly per application; an omitted diagnostics option creates no collector, metadata mirror, ring, or timer anywhere in the kernel, and IApplication.diagnostics is absent.

import { createApplication } from '@setu-ts/kernel';

const app = createApplication({
  plugins: [RuntimePlugin()],
  // Explicit activation. `labels` is the disclosure decision: a name leaves
  // the process ONLY when it exactly matches an allowlist entry.
  diagnostics: {
    labels: { plugins: ['catalog'], routes: ['/items'] },
  },
});
await app.start();

const snapshot = app.diagnostics!.snapshot(); // DiagnosticsSnapshot
const batch = app.diagnostics!.read(0, 128); // DiagnosticsBatch

The reader is pull-only. snapshot() and read() are the whole surface: neither registers a callback, resolves a service, invokes application code, or mutates state. Returned data is deeply frozen; a slow or stopped reader cannot backpressure requests. DTOs (DiagnosticsSnapshot, DiagnosticsNode, DiagnosticsEdge, DiagnosticsEvent, DiagnosticsBatch) and IDiagnosticsSource are exported from @setu-ts/common; KernelDiagnosticsOptions and the ApplicationOptions.diagnostics field from @setu-ts/kernel.

Capture minimization. No dynamic request path, query string, header, body, cookie, token, session value, database value, or raw error text is ever recorded. labels is an exact allowlist (≤256 entries per list, ≤160 UTF-8 bytes per entry, no control characters); un-allowlisted names are projected as opaque sequential ids (p1, c1, r1, m1), never truncated into new names. Approving a label is a disclosure decision, not a secret-detection guarantee.

One field is not allowlist-gated. A plugin node’s version is emitted whenever it passes a bounded major.minor.patch semver grammar, independently of labels.plugins — so an application that enables diagnostics with no labels at all still discloses the version of every registered plugin, including the framework’s own through RuntimePlugin. A version that fails the grammar (a git sha, a sentence, any string over 64 characters) is omitted rather than projected.

Bounds. Snapshots are capped at 1,024 nodes, 4,096 edges, and 256 KiB of compact JSON (truncated reports omission). Events are capped at 1,024 retained records and 1,024 bytes each; eviction is reported as lost sequence numbers, and drops as droppedEvents. Startup failure and final shutdown clear retained metadata while preserving the original application error — a reader then sees only the coarse failed/closed state, the failure code, and counters. A retried start() — possible only after a failure before any plugin registered — continues the event numbering, so a later read reports the discarded range as lost. Timing is monotonic from runtime registration; atMs/durationMs are null before that, never fabricated.

The runnable consumer is scripts/inspect-kernel.ts; the paired throughput/latency harness is scripts/benchmark-kernel-diagnostics.ts --mode=disabled|enabled. Network authentication and transport for an external devtool belong to M98b, which consumes this same contract.

createApplication() (@setu-ts/kernel)

The entry point to the framework.

A capability is not resolvable from app.services until start() has run.

Signature

function createApplication(options?: ApplicationOptions): Application;

interface ApplicationOptions {
  plugins?: IPlugin[];
  onError?: (error: Error, ctx: RequestContext) => void;
  onRequest?: (ctx: RequestContext) => void | Promise<void>;
  onResponse?: (ctx: RequestContext) => void | Promise<void>;
  gracefulShutdown?: boolean;
  shutdownTimeout?: number;
}

interface Application {
  register(plugin: IPlugin): Application;
  router: RouterApi;
  middleware: MiddlewareApi;
  services: ServiceRegistry;
  start(options?: StartOptions): Promise<void>;
  stop(): Promise<void>;
  inject(request: InjectRequest): Promise<InjectResponse>;
}

interface StartOptions {
  port?: number;
  hostname?: string;
}

Usage

const app = createApplication();

// Register plugins programmatically
app.register(RuntimePlugin());
app.register(LoggerPlugin({ level: 'info' }));

// Register an inline plugin
app.register({
  name: 'hello-plugin',
  version: '1.0.0',
  register(ctx) {
    ctx.router.get('/hello', (ctx) => ctx.response.json({ hello: 'world' }));
  },
});

await app.start({ port: 3000 });

Startup logging

After adapter.listen succeeds, the kernel logs one info record through CAPABILITIES.LOGGER when one is registered: Server listening with the port, and hostname only when one was supplied. A port: 0 start logs Server listening on an ephemeral port with no port field. With no logger, nothing is logged; a logger that throws never fails start(). Deno also keeps its own native listening banner, so a Deno start shows both lines.

Route Introspection

app.router.listRoutes() returns RouteInfo entries. Each entry has an optional owner: it is the name of the plugin whose register() call created the route, and is absent for a route added directly through app.router. Registering the same method and path twice throws instead of silently replacing the first handler.

Testing Without a Server

const app = createApplication({ plugins: [RuntimePlugin()] });

app.router.get('/users', (ctx) => ctx.response.json([{ id: 1 }]));

await app.start();

const response = await app.inject({ method: 'GET', url: '/users' });
console.log(response.statusCode); // 200
console.log(response.json()); // [{ id: 1 }]

For testing, prefer createTestApp() — it calls start() automatically (without binding a socket), so you can call inject() or fetch() directly. See Testing Package for the full API.

InjectRequest.ip?: string optionally supplies the socket peer as IRequest.ip (M113n). Omitting it leaves the injected request without a peer.

inject() carries the body shapes a request actually has (M95c): a Uint8Array and an ArrayBuffer pass through VERBATIM with no content-type default, since only the caller knows whether those bytes are multipart, JSON, or an image; a Blob also passes through verbatim and defaults content-type to its own type when that is non-empty — exactly what the platform does for new Request(url, { body: blob }) — contributing nothing when the blob has no type; a URLSearchParams is serialised with its own toString() and defaults content-type to application/x-www-form-urlencoded; a plain object is JSON-serialised and a bare string is carried as-is, both defaulting to application/json. An explicitly supplied content type always wins, and the default is written onto a COPY of headers — a Headers instance the caller reuses across two injected requests is never mutated, so the second request still gets its own shape’s default. Any other shape — an array, a Date, a class instance, a number — is refused with a TypeError naming the received type, not silently JSON-stringified: the previous behaviour turned a Uint8Array into {"0":97,…} and every other non-string into {} while answering 200, which made an injected multipart upload parse as an empty form.

Shared reconnect supervisor (@setu-ts/common)

Since 0.10.0, common exports ReconnectSupervisor, ReconnectSupervisorOptions, ReconnectMode and fullJitterDelay(attempt, initialMs, maxMs). Messaging’s RabbitMQ, NATS and Kafka brokers and the RabbitMQ queue adapter share this implementation. Messaging does not re-export these symbols.

ReconnectMode is 'drive' | 'observe'. The options require runtime, mode and attachFaultListener(onFault), which returns a disposer. Drive mode additionally requires reconnect and replay callbacks; reassert is optional. Observe mode can supply attachRecoveryListener(onRecovered). initialMs defaults to 500 and maxMs to 30000. fullJitterDelay returns an integer uniformly distributed from zero through the exponential window’s capped ceiling. Attempts are unbounded.

Call start() to attach listeners, fault() to mark an outage and start drive-mode retries, recovered() to clear a fault, and stop() to cancel scheduled attempts and dispose listeners. faulted reports the current fault window. A stopped supervisor is terminal; construct a new instance to start another lifecycle.

Dotenv parser (@setu-ts/common)

Since 0.11.0, common exports parseEnv(content: string): Readonly<Record<string, string>>, the strict dotenv parser ConfigPlugin loads .env files with. It moved from config-plugin, where it was internal, so that setu workspace deploy builds a member’s Kubernetes Secret from exactly the values the application would read from the same file.

Blank lines and # comment lines are ignored. An entry may start with export . A value may be unquoted (a trailing # comment is dropped), double-quoted (escape sequences decoded) or single-quoted (taken literally). An empty value is the empty string, and a duplicate key keeps its last value. A line without =, an invalid key, or an unterminated quote throws an Error naming the line number.

import { parseEnv } from '@setu-ts/common';

parseEnv('export A="x y"\nB=plain # note\nEMPTY=\n');
// { A: 'x y', B: 'plain', EMPTY: '' }

RuntimePlugin() (@setu-ts/runtime)

Provides runtime-agnostic services (UUID, timers, crypto, env, HTTP server).

Registration

import { RuntimePlugin } from '@setu-ts/runtime';

app.register(
  RuntimePlugin({
    httpAdapter: 'auto', // 'node' | 'deno' | 'bun' | 'auto'
  }),
);

Deno shutdown

Since 0.10.0, Deno adapter close() waits for the first of shutdown() and a 1000 ms grace, catching a rejected shutdown. After the kernel’s bounded drain, shutdown and close hooks can run while a request is still in flight. Register resource cleanup in lifecycle hooks.

Bounding the request body

maxBodyBytes caps the request-body read where the body is actually consumed:

app.register(RuntimePlugin({ maxBodyBytes: 10 * 1024 * 1024 }));

Use it with HttpSecurityPlugin({ requestSize: { maxBodySize } }): that middleware rejects a declared Content-Length before reading, while this option bounds chunked bodies as they are read. Set both to the same value or make maxBodyBytes larger. Omit maxBodyBytes for an unbounded read; 0 refuses every request that carries a body. A non-negative integer is required. An over-limit read rejects with a RequestBodyTooLargeError carrying a 413 status hint, so errorHandler answers 413 Payload Too Large in its configured format.

A component that wraps its own body read in a try must honour that hint rather than reporting its own status: the read can now REJECT, and a catch that assumes a parse failure reports the wrong cause and the wrong remedy. @setu-ts/graphql-plugin’s two HTTP transports answer 413 with extensions.code: 'REQUEST_BODY_TOO_LARGE', and @setu-ts/storage-plugin’s upload middleware serves the hint through respondWithError.

Reporting a failed WebSocket handshake

HttpAdapterOptions.reportError?: (record: Readonly<Record<string, unknown>>) => void (@since 0.10.0) is a last-resort sink for a server-side Node handshake failure: ws is not installed, or it throws while upgrading. RuntimePlugin supplies one resolved at call time — the registered logger’s error, else IRuntimeServices.reportError, with a throwing logger swallowed. The Node adapter reports { level: 'error', msg: 'WebSocket handshake failed', ...serializeError(cause) } at most once per distinct message per handle, then refuses the upgrade with the same 500 and no body as before. Deno, Workers and Bun ignore the option; omitted, the refusal is silent.

Accessing Runtime Services

app.router.get('/info', (ctx) => {
  const runtime = ctx.services.get<IRuntimeServices>('runtime');

  return ctx.response.json({
    platform: runtime.platform(),
    version: runtime.version(),
    hostname: runtime.hostname(),
    requestId: runtime.uuid(),
  });
});

Available Runtime Services

interface IRuntimeServices {
  platform(): 'node' | 'deno' | 'bun' | 'cloudflare-workers';
  version(): string;
  hostname(): string;

  uuid(): string;
  randomBytes(length: number): Uint8Array;
  subtle: SubtleCrypto;

  now(): number;
  hrtime(): number;
  setTimeout(fn: () => void, ms: number): TimerHandle;
  clearTimeout(handle: TimerHandle): void;
  setInterval(fn: () => void, ms: number): TimerHandle;
  clearInterval(handle: TimerHandle): void;

  env: Record<string, string | undefined>;
  exit(code?: number): never;

  fs?: IFileSystem;
  workers?: IWorkerHost;
  dns?: IDnsResolver;
  onSignal?(signal: RuntimeSignal, handler: () => void): void;
}

type RuntimeSignal = 'SIGTERM' | 'SIGINT';

IFileSystem provides readFile/writeFile/stat/readdir/mkdir/rm, plus an optional realPath(path): Promise<string> that canonicalizes a path following symlinks. realPath is implemented by the Node/Deno/Bun runtime adapters and absent on runtimes that cannot canonicalize; callers must degrade gracefully when it is not present (e.g. the React Router plugin’s static-asset handler uses it for symlink-safe containment when available, falling back to lexical containment).

workers is an optional IWorkerHost for spawning worker threads. It is implemented by the Node/Deno/Bun runtime adapters and absent on Cloudflare Workers (no threads on the edge). Callers must degrade gracefully when it is not present — the WorkerPoolPlugin fails run() with a typed WorkerPoolUnavailableError rather than throwing at startup.

interface IWorkerHost {
  spawn(specifier: string): IWorkerHandle;
  availableParallelism(): number;
  // Answerable BEFORE a worker exists, which is why it sits on the host: a
  // consumer that must warn about undetectable worker death needs to know at
  // registration time. A host that omits it is treated as reporting `false`.
  reportsExit?(): boolean;
}

interface IWorkerHandle {
  postMessage(message: unknown): void;
  onMessage(listener: (message: unknown) => void): void;
  onError(listener: (error: Error) => void): void;
  // The worker's THREAD ENDING, however it ended — a clean self-termination
  // included, which raises no error at all. `code` is `null` when the runtime
  // ends the worker without reporting one, and the listener also fires for a
  // host-requested `terminate()` on runtimes that implement it that way.
  onExit?(listener: (code: number | null) => void): void;
  terminate(): Promise<void>;
}

onExit/reportsExit are omitted, not no-ops, on a runtime that cannot report a worker exit: their absence means “this runtime cannot tell me a worker died”, never “no worker has died”. The Node host implements both over node:worker_threads’ 'exit'; the shared web-worker host does when its runtime names an event that fires, which Bun does ('close') and Deno does not — measured, Deno’s Worker emits nothing on self.close() and a later postMessage still resolves.

dns is an optional IDnsResolver for name resolution. It is implemented by the Node, Deno, and Bun runtime adapters and absent on Cloudflare Workers, whose network access is fetch — that resolves names internally and exposes no lookup surface. Callers must degrade gracefully when it is not present; the ServiceDiscoveryPlugin’s 'dns' provider throws a typed DiscoveryUnavailableError during register(), naming the alternatives.

onSignal registers a process-termination handler so an application can run app.stop() — its shutdown hooks, discovery deregistration, and broker disconnects — before the process dies. Handlers are additive and are never removed: a process that received a termination signal is ending.

It is the one member absent for two unrelated reasons, and a caller must treat both the same way (runtime.onSignal?.(...)). Cloudflare Workers omits it because an isolate is evicted rather than signalled, so there is nothing to register for. The Deno adapter omits it on Windows, where registering for SIGTERM throws rather than no-opping — so the presence of the key means “this runtime can register a handler”, never “this platform raises signals”. A no-op was rejected deliberately: it would let a caller conclude its shutdown handler runs when it never would.

interface IDnsResolver {
  resolveSrv(hostname: string): Promise<readonly SrvRecord[]>;
  resolveHost(hostname: string): Promise<readonly string[]>;
}

interface SrvRecord {
  readonly host: string;
  readonly port: number;
  readonly priority: number;
  readonly weight: number;
}

SrvRecord.host is deliberately named that rather than reusing a runtime’s own spelling: Deno calls the field target and Node calls it name, and passing either through unchanged would type-check on both runtimes while producing undefined hostnames on one. resolveHost concatenates A and AAAA results and rejects only when both families fail, because an IPv4-only host has no AAAA record at all. The runtime package exports both resolver factories: createNodeDnsResolver(dns?) (shared by the Node and Bun adapters, over node:dns/promises) and createDenoDnsResolver(host) (over Deno.resolveDns).

The runtime package also exports the worker host factories createWebWorkerHost(globals?) (Deno/Bun, over the web Worker API) and createNodeWorkerHost(mods?) (Node, over node:worker_threads), each behind an injectable seam, plus a @setu-ts/runtime/worker subpath whose sole export is defineWorkerTask (see the WorkerPoolPlugin section).

LoggerPlugin() (@setu-ts/logger-plugin)

LoggerPluginOptions.excludePaths?: readonly PathPattern[] passes strings and regular expressions unchanged to request middleware. Strings match exactly; regular expressions test the request path.

The request logger emits completion with the status predicted by IErrorResponder.statusFor? on a throw, or 500 without that method; normal returns use the response snapshot. It rethrows without a duplicate failure record. errorHandler logs once at warn below 500 and error otherwise. A custom ErrorHandlerOptions.respond hook choosing another status is not reflected in request completion logs. Request logging remains inside telemetry. With no logger, handled 5xx and kernel unhandled errors use the runtime’s default sink; a registered logger is the exclusive destination.

Provides structured logging via a capability token. The plugin depends on RuntimePlugin and registers its ILogger under CAPABILITIES.LOGGER at PLUGIN_PRIORITY.HIGH (100) so logging is available before most other plugins register.

Registration

import { LoggerPlugin } from '@setu-ts/logger-plugin';

app.register(
  LoggerPlugin({
    level: 'info', // minimum level to emit (default 'info')
    transport: 'console', // 'console' | 'pino' | 'noop' | 'custom' (default 'console')
    pretty: false, // pretty-print console output
    redact: ['password', 'token', 'authorization'], // dot-paths to redact
    requestLogging: true, // register request/response middleware
    slowRequestThreshold: 5000, // ms — warn when slower (default 5000)
    excludePaths: ['/health'], // paths excluded from request logging
  }),
);

Transports

LoggerPluginOptions.logger?: ILogger (since 0.11.0) is required with transport: 'custom' and refused with every other transport, including the default. Invalid combinations throw an Error named LoggerConfigurationError when constructing the plugin. The wrapper applies level (default info), error normalization, and the same redaction policy and redact paths as built-in transports before delegating metadata. Default secret patterns apply when redact is omitted; an explicit list replaces them. Children delegate to the supplied logger’s child() with redacted bindings and retain the wrapper. Request logging and trace correlation also apply. The supplied logger controls its own sink and may impose additional filtering.

Usage in Routes

import { CAPABILITIES, ILogger } from '@setu-ts/common';

app.router.get('/users/:id', async (ctx) => {
  const logger = ctx.services.get<ILogger>(CAPABILITIES.LOGGER);

  logger.info('Fetching user', { userId: ctx.params.id });

  const user = await getUser(ctx.params.id);

  logger.debug('User fetched', { userId: user.id });

  return ctx.response.json(user);
});

Trace correlation

When a CAPABILITIES.TELEMETRY provider is registered, every record the plugin’s logger emits carries the active span’s identifiers:

The names are snake_case, departing from this framework’s camelCase metadata convention (requestId), and the departure is deliberate: these fields exist to be read by a log backend, and the OpenTelemetry log-correlation convention that Loki, Elastic and the collector’s own processors key on is snake_case. A camelCase spelling would be internally consistent and would join up in none of the tools the correlation exists for.

Enrichment applies to every level and to child loggers, so logger.child({ requestId }) — what the request-logging middleware does — still carries them. A caller’s own trace_id in the metadata wins over the decorator’s.

Without a telemetry capability the record is byte-identical to before, and so it is when no span is active, when the telemetry service does not implement activeSpanContext, or when reading it throws. The read is guarded end to end: an observability enrichment must never turn logging into the fault.

The plugin does NOT declare CAPABILITIES.TELEMETRY in optionalDependencies. TelemetryPlugin already declares CAPABILITIES.LOGGER in its own, and the two edges together are a cycle the kernel’s plugin resolver refuses at start(). The telemetry capability is therefore resolved at CALL time, which is required rather than merely prudent: the resolver orders LoggerPlugin first, so telemetry is guaranteed absent when the logger registers.

One consequence is visible: the value registered under CAPABILITIES.LOGGER is an internal decorator, not the transport instance, so instanceof ConsoleLogger on the resolved capability no longer holds. ILogger is the contract; the concrete class was never part of it.

Child Loggers

app.middleware.add(async (ctx, next) => {
  const logger = ctx.services.get<ILogger>(CAPABILITIES.LOGGER);
  const requestLogger = logger.child({
    requestId: ctx.id,
    correlationId: ctx.request.headers.get('x-correlation-id') ?? undefined,
  });

  ctx.services.register(CAPABILITIES.LOGGER, requestLogger, { override: true });
  await next();
});

Logger Interface

interface ILogger {
  readonly level: LogLevel;
  fatal(message: string, metadata?: LogMetadata): void;
  error(message: string, metadata?: LogMetadata): void;
  warn(message: string, metadata?: LogMetadata): void;
  info(message: string, metadata?: LogMetadata): void;
  debug(message: string, metadata?: LogMetadata): void;
  trace(message: string, metadata?: LogMetadata): void;
  child(bindings: LogMetadata): ILogger;
}

type LogMetadata = Readonly<Record<string, unknown>>;
type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';

Standalone Logger Implementations

The logger implementations can be used directly without the plugin, e.g. in tests or scripts:

import { ConsoleLogger, NoopLogger, PinoLogger } from '@setu-ts/logger-plugin';

const consoleLogger = new ConsoleLogger(runtime, { level: 'debug', pretty: true });
const noopLogger = new NoopLogger();
// PinoLogger uses async construction (import('pino') is async):
const pinoLogger = await PinoLogger.create({ level: 'info', redact: ['password'] });

Request Logging Middleware

import { createRequestLoggerMiddleware } from '@setu-ts/logger-plugin';

app.middleware.add(
  createRequestLoggerMiddleware({
    slowRequestThreshold: 1000,
    // A string is an EXACT path match; a RegExp is tested against the path (M90a).
    excludePaths: ['/health', /^\/internal\//],
  }),
);

The middleware resolves CAPABILITIES.LOGGER on each request, creates a child logger bound to requestId, and logs:

• request received at debug (method, path — the concrete path as the client sent it, not a route template). Set level: 'debug' to emit this arrival entry; its metadata is not built when the child’s exposed level excludes debug. With no readable level, the middleware calls debug() and lets the logger filter.
• One request completed at info (method, path, status, duration in ms), including a request that threw: the status is the one errorHandler’s responder predicts through statusFor (500 without it), so a custom respond hook that chooses another status is not reflected
• Slow request warning when duration exceeds slowRequestThreshold

It does not log the error itself; errorHandler logs it once (V9-80). The database-plugin scrub covers database errors only, so an identifier in a path segment reaches the log; keep it out with excludePaths, a redaction field redactor for path, or redact (which replaces the default secret patterns, so re-list them).

ConfigPlugin() (@setu-ts/config-plugin)

Provides strongly-typed configuration with environment validation and .env file loading. Configuration is an immutable application-startup snapshot — values are loaded once at startup and never mutated. Hot reload is deferred (the runtime contract has no file-watching abstraction).

Registration

import { ConfigPlugin } from '@setu-ts/config-plugin';
import { CAPABILITIES } from '@setu-ts/common';
import { z } from 'zod';

const AppConfigSchema = z.object({
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  REDIS_URL: z.string().url().optional(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

app.register(
  ConfigPlugin({
    envFilePath: ['.env.local', '.env'],
    validationSchema: AppConfigSchema,
    expandVariables: true,
  }),
);

Usage

app.router.get('/config', (ctx) => {
  const config = ctx.services.get<IConfig>(CAPABILITIES.CONFIG);

  return ctx.response.json({
    port: config.get<number>('PORT'),
    env: config.get<string>('NODE_ENV'),
    hasRedis: config.has('REDIS_URL'),
    redisUrl: config.get<string>('REDIS_URL', { default: 'redis://localhost:6379' }),
  });
});

Config Interface

interface IConfig {
  get<T>(key: string): T | undefined;
  get<T>(key: string, options: { readonly default: T }): T;
  getOrThrow<T>(key: string): T;
  has(key: string): boolean;
}

ConfigPluginOptions

interface ConfigPluginOptions {
  readonly envFilePath?: string | readonly string[];
  readonly envFileOptional?: boolean;
  readonly validationSchema?: StructuralSchema<unknown>;
  readonly sections?: readonly ConfigSection<unknown>[];
  readonly expandVariables?: boolean;
  readonly instance?: IConfig;
  readonly diagnostics?: ConfigDiagnosticsOptions;
}

interface ConfigDiagnosticsOptions {
  readonly enabled: true;
  readonly keys: Readonly<Record<string, string>>;
  readonly files?: Readonly<Record<string, string>>;
}

• envFilePath — Path or paths to .env files. Defaults to no file loading. When supplied, the runtime must provide fs (absent on edge platforms).
• envFileOptional — When true, a path in envFilePath that does not exist is skipped instead of throwing. Defaults to false, which is the behaviour released in 0.1.0. Only ABSENCE is tolerated: a file that exists and cannot be read still throws. This is what a scaffolded project uses, because the dotenv file the CLI emits is gitignored and therefore absent on every fresh clone, in CI, and in a container built from the repository.
• validationSchema — A Zod-compatible schema for startup validation. The schema’s parse() is called once after merging and expansion; the parsed output is stored as the configuration snapshot, preserving Zod coercions and defaults.
• sections — Typed sections validated after validationSchema has parsed the whole snapshot. Each section reads only its declared prefix-plus-key entries, parses them once at startup, and caches the output for getConfigSection. Sections validate even when instance is supplied.
• expandVariables — When true (default), expand ${NAME} references in values using the final merged configuration.
• instance — An already-loaded snapshot to register verbatim. Present → nothing is read from the environment or from disk and envFilePath, envFileOptional, validationSchema, and expandVariables are ignored; declared sections still validate it through named reads. Absent → configuration loads normally. This exists so an application can resolve configuration before its plugins are constructed and then hand the plugin that same object, rather than letting it load a second snapshot a moment later that the composition never saw.
• diagnostics — The opt-in value-free provenance policy, below.

loadConfig()

import { loadConfig } from '@setu-ts/config-plugin';
import { createRuntimeServices } from '@setu-ts/runtime';

const config = await loadConfig(createRuntimeServices(), {
  envFilePath: ['.env.local', '.env'],
});
const port = config.get<number>('PORT', { default: 3000 });

(runtime: IRuntimeServices, options?: ConfigPluginOptions) => Promise<IConfig> — the same implementation ConfigPlugin.register uses, reachable without an application. Use it when configuration must be read before any plugin exists (choosing which plugins to register, for instance); inside an application, resolve CAPABILITIES.CONFIG from the registry instead.

Merging, expansion, and validation behave identically on both paths because there is only one: the plugin delegates to this function and registers what it returns. Pass the result back as ConfigPlugin({ instance: config }) so the application holds exactly one snapshot — createFullStackAppFromConfig does precisely that.

StructuralSchema<T>

interface StructuralSchema<T> {
  parse(input: unknown): T;
}

Minimal schema interface compatible with Zod’s parse(unknown) API. Consumers supply a Zod schema without config-plugin depending on Zod.

Typed Configuration Sections

import { CAPABILITIES, type IConfig } from '@setu-ts/common';
import { ConfigPlugin, defineConfigSection, getConfigSection } from '@setu-ts/config-plugin';
import { z } from 'zod';

const database = defineConfigSection({
  prefix: 'DATABASE_',
  keys: ['URL', 'POOL_SIZE'],
  schema: z.object({
    URL: z.string().url(),
    POOL_SIZE: z.coerce.number().int().positive(),
  }),
});

app.register(ConfigPlugin({ sections: [database] }));

const config = app.services.get<IConfig>(CAPABILITIES.CONFIG);
const settings = getConfigSection(config, database);
// settings.POOL_SIZE is a validated number.

ConfigSection<T> is the typed declaration returned by defineConfigSection. prefix is prepended to every prefix-stripped entry in keys, so the example reads DATABASE_URL and DATABASE_POOL_SIZE while the schema receives { URL, POOL_SIZE }. The explicit key list is required because IConfig intentionally supports named reads but no key enumeration; this also makes an arbitrary ConfigPluginOptions.instance validatable. Missing keys are omitted and the schema decides whether they are optional. A section schema is not reusable as validationSchema: the latter receives the entire flat snapshot and always runs first.

getConfigSection(config, section) returns the exact schema output cached during startup. It throws when that configuration snapshot did not validate the given definition; it never parses a value at read time.

Configuration Precedence

Values are merged in the following order (highest precedence first):

1. Environment variables (runtime.env)
2. Earlier file paths (.env.local overrides .env)
3. Later file paths

undefined entries in runtime.env are filtered out.

Variable references are expanded only after all sources have been merged, so file values may reference runtime.env, runtime values may reference files, and references may cross file boundaries. Cycles or missing references fail startup unless expansion is disabled.

Dotenv Parsing

Configured files use strict parsing. Blank lines, comments, optional export prefixes, quoted and unquoted values, common double-quoted escapes, empty values, and inline comments are supported. Malformed entries, invalid keys, and unterminated quotes fail startup with a line number but do not include rejected values in the error message.

Schema validation failures use a stable, value-free error message so validator diagnostics cannot leak configuration secrets.

Edge Runtimes

On edge platforms where runtime.fs is undefined, envFilePath must not be set. Attempting to do so throws a clear startup error.

Hot Reload

Deferred. Configuration is an immutable application-startup snapshot.

Configuration Provenance (0.8.0)

ConfigDiagnosticsOptions is the explicit opt-in: enabled is the LITERAL true (an absent option is the disabled path; any other value is refused, with fixed messages that never echo a value), keys is the exact configuration-key to display-alias allowlist (at most 128 entries, each alias unique, 1–64 UTF-8 bytes, no control characters), and files optionally allows exact configured .env paths as source aliases (at most eight, same alias rules). When present, the loader records — during the ONE load it already performs — where each approved key’s final value was observed to come from: the source category and approved source aliases, the evidenced precedence displacement (overriddenSourceAliases, lowest first), the ${NAME} expansion evidence (expanded plus the approved referenceAliases, at most 16 per key), and the schema effect derived only from input/output property presence (validated / introduced / removed / not-configured; introduced reports the appearance and never names a mechanism, since a schema default and a transform are indistinguishable by presence).

No configuration value, value hash, value length, raw key name, or file path is ever retained or served. Unapproved keys are never observed — no entry, and no counter disclosing that they exist; an unapproved file path contributes only the category file. loadConfig(runtime, { diagnostics }) builds the record with the snapshot; ConfigPlugin({ instance, diagnostics }) adopts that exact instance’s record (keeping each entry’s real environment/file origin — injection is how the snapshot reached the application, not where its values came from) or, for an opaque injected instance, reports every approved alias with origin and schema effect unknown and NO presence flag, without a single read of it. An adopted record is served exactly as the loader built it, under the loadConfig call’s approvals — the plugin’s own keys and files only enable the source and govern the opaque case, so the same policy belongs on both calls. Provenance adds no read to any configuration object: configured sections perform exactly the same IConfig.get calls with diagnostics disabled and enabled.

The plugin ALWAYS registers the source under the eager CAPABILITIES.CONFIG_DIAGNOSTICS token: absent diagnostics answers disabled; enabled with no approved resolved entries answers no-data; otherwise ready. The Diagnostics Connector serves it at GET /v1/config (see Diagnostics Connector and docs/diagnostics-protocol.md); snapshots are deeply frozen and bounded by the connector’s 256 KiB response ceiling.

Exports

ValidationPlugin() (@setu-ts/validation-plugin)

Provides schema-based request validation with standardized error responses. Schemas are duck-typed via a structural safeParse() interface — no hard Zod dependency in the plugin itself.

Registration

import { ValidationPlugin } from '@setu-ts/validation-plugin';

app.register(
  ValidationPlugin({
    // ValidationPlugin's own ErrorFormat union — distinct from the exceptions
    // package's, which has no 'nestjs' arm.
    errorFormat: 'rfc9457', // 'default' | 'rfc9457' | 'rfc7807' | 'nestjs' | custom function
  }),
);

ValidationPluginOptions

interface ValidationPluginOptions {
  /** Error response format. Defaults to 'default'. */
  readonly errorFormat?: ErrorFormat | ValidationErrorFormatter;

  /**
   * Strip properties the schema does not declare. Applied once per middleware
   * at registration time via the schema's own `.strip()` (Zod-style). A schema
   * without `.strip()` is used unchanged.
   */
  readonly whitelist?: boolean;

  /**
   * Reject payloads carrying properties the schema does not declare. Applied
   * once per middleware at registration time via the schema's own `.strict()`
   * (Zod-style), and takes precedence over `whitelist` when both are set. A
   * schema without `.strict()` is used unchanged.
   */
  readonly forbidNonWhitelisted?: boolean;
}

Programmatic Validation

import { z } from 'zod';
import { CAPABILITIES, IValidationService, validatedStateKey } from '@setu-ts/common';

const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(18).max(120),
  role: z.enum(['admin', 'user', 'guest']).default('user'),
});

app.router.post('/users', {
  middleware: [
    async (ctx, next) => {
      const validation = ctx.services.get<IValidationService>(CAPABILITIES.VALIDATION);
      const body = await ctx.request.json();
      const result = validation.validate(CreateUserSchema, body);

      if (!result.success) {
        return ctx.response.status(400).json({ errors: result.error });
      }

      ctx.state.set(validatedStateKey('body'), result.value);
      await next();
    },
  ],
  handler: async (ctx) => {
    const body = ctx.state.get<z.infer<typeof CreateUserSchema>>(validatedStateKey('body'));
    // body is fully typed and validated
    const user = await createUser(body);
    return ctx.response.status(201).json(user);
  },
});

Validation Middleware Helpers

The helpers resolve IValidationService from the request context automatically. The five validateXxx helpers and createValidationMiddleware return ValidatorMiddleware<ValidatedOutput<S>> — a MiddlewareFunction (so every existing call site type-checks unchanged) with one added member, value(ctx):

import { z } from 'zod';
import {
  validateBody,
  validateCookies,
  validateHeaders,
  validateParams,
  validateQuery,
} from '@setu-ts/validation-plugin';

const listQuery = validateQuery(ListUsersQuerySchema);
const userIdParams = validateParams(z.object({ id: z.string().uuid() }));
const updateBody = validateBody(UpdateUserSchema);

app.router.get('/users', {
  middleware: [listQuery],
  handler: async (ctx) => {
    const query = listQuery.value(ctx); // ValidatedOutput<typeof ListUsersQuerySchema>
  },
});

app.router.put('/users/:id', {
  middleware: [userIdParams, updateBody],
  handler: async (ctx) => {
    const params = userIdParams.value(ctx);
    const body = updateBody.value(ctx);
    // both are validated and typed by their schemas
  },
});

ValidatedOutput<S> is the schema’s parsed output type — coercions and defaults included — inferred from the schema you pass, so the type follows the schema instead of being restated (or cast) in the handler. value(ctx) returns the stored value only when that validator ran on the request; it throws a TypeError naming the target otherwise — when the validator is not in the route’s chain, or a later validator for the same target overwrote it. Validated values are still stored in ctx.state under validatedStateKey(target) — the wire format is unchanged, and the @ValidateBody/@ValidateQuery/@ValidateParams resolvers read through it — so the old ctx.state.get(validatedStateKey('body')) read still works.

Using the Service’s middleware() Method

The IValidationService.middleware() method builds middleware with the formatter chosen at plugin construction time:

import { CAPABILITIES, IValidationService } from '@setu-ts/common';

app.router.post('/users', (ctx, next) => {
  const validation = ctx.services.get<IValidationService>(CAPABILITIES.VALIDATION);
  return validation.middleware(CreateUserSchema, 'body')(ctx, next);
});

Form body validation

validateBody(schema, { forms: true }) and @ValidateBody(schema, { forms: true }) also validate application/x-www-form-urlencoded and multipart/form-data bodies with the same schema they validate a JSON body with. Off by default: a cross-site HTML <form> reaches a route that accepts forms with no CORS preflight, so pair an opted-in route with form CSRF protection (csrfFormMiddleware from @setu-ts/session-plugin). Without the option a form body answers 415 “Unsupported Media Type”. The option is ValidationMiddlewareOptions in @setu-ts/common, the optional third parameter of IValidationService.middleware, and has no effect on any target but body. With it, a server-rendered <form> post validates against the schema a JSON client passes and reads back through value(ctx).

The first-party validation service requires application/json or any application/*+json media type, ignoring case and parameters, or a recognised form type when forms are enabled. Unsupported types, including text/plain and an absent header, answer 415 before any body read, through the application’s error responder. Clients must send Content-Type: application/json for JSON, including on an empty body-validated request. Routes reading ctx.request.json() directly are unchanged; replacement IValidationService implementations own their media-type handling. Cookie-authenticated routes still need csrfMiddleware or csrfFormMiddleware. The 415 takes the error responder’s format, while a 400 validation failure takes ValidationPlugin({ errorFormat }), so set both to the same format; the CLI templates set both to 'rfc9457'.

The form is converted to a record before validation: a field sent once is a single value, a repeated field becomes an array of its values in wire order, and a name ending [] is always an array (kept under the name as written). Values are strings or the framework’s FormFile — NOT a web File, so z.instanceof(File) refuses a file part and a schema checks the FormFile shape instead; numbers and booleans arrive as strings, so schemas use z.coerce for them. A form that carries the session plugin’s _csrf field reaches the schema, where a Zod object strips the unknown key by default and forbidNonWhitelisted (or the schema’s own .strict()) refuses it. A body the runtime refuses for size (RuntimePlugin({ maxBodyBytes })) answers 413 — on a validated route it used to answer 400 — and a form body that cannot be parsed answers the same 400 a malformed body does. The generated OpenAPI document still describes a validated body as application/json.

Sanitization

Sanitization is a standalone export (not a method on IValidationService):

import { SanitizationRules, sanitize } from '@setu-ts/validation-plugin';

const rules: SanitizationRules = {
  htmlEncode: true,
  stripTags: true,
  maxLength: 1000,
  trim: true,
};

const clean = sanitize(userInput, rules);

You can also create a reusable sanitizer function:

import { createSanitizer } from '@setu-ts/validation-plugin';

const sanitizer = createSanitizer({ htmlEncode: true, maxLength: 500 });
const clean1 = sanitizer(inputA);
const clean2 = sanitizer(inputB);

Error Response Formats

Default format

{
  "message": "Validation failed with 2 issue(s).",
  "errors": [{ "field": "email", "message": "Invalid email address", "code": "invalid_string" }]
}

RFC 9457 Problem Details

The 'rfc7807' alias produces a byte-identical body: this formatter’s type is a semantic URI that was never derived from the status code, so it was already valid under RFC 9457.

{
  "type": "https://setu-ts.dev/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains 1 validation error(s).",
  "instance": "/users",
  "errors": [{ "field": "email", "message": "Invalid email address", "code": "invalid_string" }]
}

NestJS format

{
  "statusCode": 400,
  "message": ["email: Invalid email address"],
  "error": "Bad Request",
  "errors": [{ "field": "email", "message": "Invalid email address", "code": "invalid_string" }]
}

Custom Error Formatter

import { ValidationPlugin } from '@setu-ts/validation-plugin';

app.register(
  ValidationPlugin({
    errorFormat: (issues) => ({
      ok: false,
      fields: issues.map((i) => ({ name: i.path, reason: i.message })),
    }),
  }),
);

DatabasePlugin() (@setu-ts/database-plugin)

Portable data refusals and tenant resolution (M119e, since 0.11.0)

UnknownPayloadFieldError is defined in @setu-ts/common and re-exported unchanged here. MissingKeyColumnError(entity: string, column: string) names a missing Drizzle primary-key column and the entities.<Entity>.primaryKey remedy. Explicit configured keys are checked at connect for registered tables; query-only tables without a key override are checked when a repository is requested. TenantColumnUnresolvedError(entity: string, column: string) names a tenant column that resolves to no property or multiple properties, with a ColumnStrategy remedy. Both configuration errors carry no HTTP hint (masked 500). The tenant bridge resolves its own configured column to the Drizzle property once per entity; caller payload keys are never translated.

The database driver’s existing unavailable-errno classification uses the shared isConnectionFaultCode(code) predicate from @setu-ts/common. The eight-code set is module-private; status classification is unchanged.

Provides database access with repository pattern and unit of work.

Migration ledger and schema readiness (M113o)

createMigrationLedger(database: IDatabaseService, options?: MigrationLedgerOptions): IMigrationLedger uses the repository surface. MigrationLedgerOptions.entity defaults to the exported MIGRATION_LEDGER_ENTITY = 'setu_migrations'. IMigrationLedger.applied(): Promise<readonly string[]> reads only id with a 10,001-row limit; more than 10,000 rows throws the exported MigrationLedgerError (reason: 'oversized'). record(name: string, appliedAt: string): Promise<void> inserts { id: name, appliedAt } and propagates duplicate-create errors. remove(name: string): Promise<void> resolves even when absent. Entity options must be non-empty strings.

Every DatabaseConnectionOptions arm accepts readiness?: DatabaseReadinessOptions: { readonly migrations: readonly string[]; readonly ledgerEntity?: string }. Expected names must be unique non-empty strings, at most 10,000; ledgerEntity defaults to MIGRATION_LEDGER_ENTITY, and createMigrationLedger(database) without an explicit entity uses the ledgerEntity that connection was registered with, so the generated runner writes where readiness reads. Invalid readiness options throw TypeError at plugin construction, naming the option without echoing values. Absent readiness preserves the indicator’s status and data. Otherwise, after a non-down result, a separate 5-second cached, 2-second bounded ledger read adds data.migrations: unreadable/rejected/timed-out/oversized → down with { state: 'unreadable' }; missing expected names → degraded with { state: 'pending', pending: count }; current → unchanged status with { state: 'current', applied: count }, adding unknown: count for names this build does not list. Unknown names preserve rolling-deploy readiness. Already-down results bypass the ledger. Only counts, never names, appear in data. See the database-plugin README for application-owned SQL DDL, entity mappings, measured duplicate errors and the process-local memory caveat.

Registration

import { DatabasePlugin } from '@setu-ts/database-plugin';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from './generated/prisma/client.ts';

// Prisma 7 removed the Rust query engine, so a driver adapter is REQUIRED —
// `new PrismaClient()` with no argument does not compile.
const prismaClient = new PrismaClient({
  adapter: new PrismaPg({ connectionString: config.getOrThrow('DATABASE_URL') }),
});

app.register(
  DatabasePlugin({
    type: 'prisma',
    options: {
      prismaClient,
      logQueries: config.get('NODE_ENV') === 'development',
    },
  }),
);

DatabasePluginOptions is a union discriminated on type, and each arm names the options its adapter cannot run without: 'prisma' requires options.prismaClient, 'drizzle' requires both options.drizzleInstance and options.drizzleTables, 'mongodb' requires options.url (or an injected options.client), 'dynamodb' requires options.region (or an injected options.client), and 'custom' requires adapter. Omitting one is a compile error rather than a startup throw. The exported arms are MemoryDatabaseOptions, PrismaDatabaseOptions, DrizzleDatabaseOptions, MongoDatabaseOptions, DynamoDatabaseOptions and CustomDatabaseOptions; BuiltInDatabaseOptions is the union of the five built-in arms and keeps its published name, so an existing annotation carrying a memory configuration still compiles. PrismaAdapterOptions and DrizzleAdapterOptions narrow DatabaseAdapterOptions for their arm; MongoAdapterOptions and DynamoAdapterOptions are their arms’ dedicated driver option bags.

Three Prisma 7 prerequisites are the application’s to supply and are documented in the package README: the driver-adapter package, a prisma.config.ts (Prisma 7 rejects url in schema.prisma), and new PrismaPg({ connectionString }, { schema }) for a non-public PostgreSQL schema.

DatabaseAdapterOptions.transactionTimeout (ms, default 30000) raises Prisma’s ~5 s interactive-transaction default, which is too short for a full Unit of Work. It is read by the Prisma adapter only; Memory and Drizzle ignore it.

Prisma v7 clients are generated into an application-selected output path, so the Prisma adapter requires an application-created options.prismaClient; it never imports or constructs that client. DatabaseAdapterOptions.url remains source-compatible but is deprecated for Prisma configuration. DatabaseAdapterOptions.provider (type PrismaSqlProvider) names the SQL connector the injected client is bound to. Only the contains filter is connector-sensitive: it is escaped on PostgreSQL/MySQL/SQL Server/CockroachDB, passed through unchanged on MongoDB (whose contains compiles to a $regex match, where % and _ are already literal so escaping them would be wrong), and refused on SQLite (see the contains note above). When omitted, the adapter reads the client’s active provider structurally at connect() time; if it cannot be determined, a contains filter throws UnsupportedFilterOperatorError naming this option, so pass it explicitly in that case. Transaction isolation is connector-specific too: when the provider cannot be determined, a requested isolation level is refused by name, so pass provider explicitly. Drizzle requires both options.drizzleInstance and options.drizzleTables. The instance is a opaque DrizzleDatabase<T> configuration created by createDrizzleDatabase(database, transactionBridge); the registry’s tables must carry an id column and the adapter translates every repository field to a real Drizzle column. Drizzle create, update, and delete require a driver with RETURNING support so their results are actual driver rows; an unsupported dialect throws a descriptive error. Promise-aware SQLite Proxy and libsql-shaped Drizzle instances without execute() are accepted for repository, transaction, and typed-builder use. Calling IDatabaseService.query() on such an instance rejects with guidance to use Drizzle’s typed query builder. That refusal is permanent rather than pending: those drivers do expose all(), but on a raw statement the proxy protocol answers with positional rows, because Drizzle has no field map for a statement it did not build — and query<T>() promises row objects.

Synchronous callback drivers (better-sqlite3, Bun SQLite, Expo SQLite, and OP SQLite) are unsupported: their native transaction closes when the callback returns, before awaited UoW work can run. createDrizzleDatabase() rejects those published types at compile time, and startup rejects an unwrapped structural instance. The explicit source-owned bridge is the positive capability that asserts the selected driver awaits its callback Promise; unknown adopting-Promise and thenable wrappers are rejected at startup before native transaction work begins.

PrismaSqlProvider still carries a 'mongodb' member and the PASSTHROUGH_PROVIDERS mechanism that holds it, but that arm is unreachable on Prisma v7: a Prisma client for MongoDB cannot be constructed (generation succeeds, construction fails — Prisma states MongoDB “did not make the Prisma 7 release” and returns in Prisma 8). The 'mongodb' adapter arm above is the supported MongoDB route; the 'mongodb' provider string on the Prisma union is retained only because removing it is a published export (AI_GUIDELINES §9.2), and the contains-to-$regex reasoning behind PASSTHROUGH_PROVIDERS stays correct for any future Prisma-Mongo client.

Transactional idempotency store (M109b)

createDatabaseIdempotencyStore(options?: DatabaseIdempotencyStoreOptions) returns a RegistryFactory<ITransactionalIdempotencyStore> for IdempotencyPlugin’s transactional.store. entity defaults to 'Idempotency'; database selects database.<name>, or the default CAPABILITIES.DATABASE when omitted or 'default'. The factory resolves the database and runtime services at initialization. The record and business work must use the same database.

run creates a claim (id), executes business work through that transaction’s IUnitOfWork, creates the encoded result (${id}.r), and commits. It uses two creates, with no update or delete. find requires both rows with the idempotency kind and their correct roles. purge preserves incomplete, foreign-kind and invalid-envelope records, and deletes a complete record only when an in-transaction re-read still finds it expired. That re-read narrows but does not close one race: two concurrent purges can delete a record a client re-created between them (closed on MongoDB; about one round trip on PostgreSQL READ COMMITTED; the deferred commit on DynamoDB and D1). The portable repository does offer a conditional delete (deleteWhere(id, where), M105), but the purge does not use it: a record is two rows (id and ${id}.r) that must go together, and deferred-write transaction sources omit conditional members. verify runs the two-create pattern and rolls it back before the first call.

TransactionalStoreUnavailableError carries entity and reason: 'cosmos-unsupported', 'bigtable-unsupported', 'mongodb-standalone' or 'entity-unavailable'. An adapter refusal can be retained as its cause. A missing/unreadable entity fails startup.

Not verified: DynamoDB’s overlapping-service TransactionConflictException outcome on DynamoDB Local (M90f). Tier C was driven against a real Prisma 7.10 client on PostgreSQL once, by hand; the committed real-backend suite uses Drizzle.

Repository Pattern

interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

app.router.get('/users', async (ctx) => {
  const db = ctx.services.get<IDatabaseService>('database');
  const userRepo = db.getRepository<User>('User');

  const users = await userRepo.findAll({
    where: { active: true },
    orderBy: { createdAt: 'desc' },
    limit: 20,
    offset: 0,
  });

  return ctx.response.json(users);
});

app.router.get('/users/:id', async (ctx) => {
  const db = ctx.services.get<IDatabaseService>('database');
  const user = await db.getRepository<User>('User').findById(ctx.params.id);

  if (!user) {
    return ctx.response.status(404).json({ error: 'User not found' });
  }

  return ctx.response.json(user);
});

app.router.post('/users', async (ctx) => {
  const db = ctx.services.get<IDatabaseService>('database');
  const body = await ctx.request.json<{ name: string; email: string }>();

  const user = await db.getRepository<User>('User').create({
    name: body.name,
    email: body.email,
  });

  return ctx.response.status(201).json(user);
});

Unit of Work (Transactions)

app.router.post('/orders', async (ctx) => {
  const db = ctx.services.get<IDatabaseService>('database');

  const order = await db.transaction(async (uow) => {
    const orderRepo = uow.getRepository<Order>('Order');
    const inventoryRepo = uow.getRepository<Inventory>('Inventory');
    const paymentRepo = uow.getRepository<Payment>('Payment');

    // All operations in same transaction
    const newOrder = await orderRepo.create(await ctx.request.json());

    const stock = await inventoryRepo.findById(newOrder.productId);
    await inventoryRepo.update(newOrder.productId, {
      quantity: stock!.quantity - newOrder.quantity,
    });

    await paymentRepo.create({ orderId: newOrder.id, amount: newOrder.total });

    return newOrder;
  });

  return ctx.response.status(201).json(order);
});

Isolation

transaction(work, options?) accepts TransactionOptions, whose optional isolation is one of 'read-uncommitted', 'read-committed', 'repeatable-read', or 'serializable'. Omission keeps the adapter default. A requested level is honoured or refused by name; it is never silently downgraded. Database-plugin adapters throw the caller-safe 501 UnsupportedIsolationLevelError. D1 throws its own CloudflareUnsupportedError, since the Cloudflare plugin cannot depend on another plugin’s error class.

withIsolationSupport() is an application declaration that its bridge forwards options. The type system cannot verify its body uses them; an unbranded bridge refuses every requested level rather than silently dropping it.

For a custom adapter, declare transactionIsolationLevels on IDatabaseAdapter; without that explicit capability the database service refuses every requested isolation level rather than assuming a zero-argument beginTransaction() honours it.

Typed Drizzle queries

interface DrizzleDatabase<TDatabase extends object> { /* package-owned typed witness */ }
interface DrizzleDatabaseIdentity { /* erased opaque configuration identity */ }
type DrizzleTransaction<TDatabase extends object> = /* Drizzle transaction callback parameter */;
type DrizzleTransactionBridge<TDatabase extends object> = <T>(
  database: TDatabase,
  work: (transaction: DrizzleTransaction<TDatabase>) => Promise<T>,
) => Promise<T>;

function createDrizzleDatabase<const TDatabase extends object>(
  database: TDatabase,
  transaction: DrizzleTransactionBridge<TDatabase>,
): DrizzleDatabase<TDatabase>;
function getDrizzleDatabase<TDatabase extends object>(
  service: IDatabaseService,
  database: DrizzleDatabase<TDatabase>,
): TDatabase;
function getDrizzleTransaction<TDatabase extends object>(
  unitOfWork: IUnitOfWork,
  database: DrizzleDatabase<TDatabase>,
): DrizzleTransaction<TDatabase>;

Pass the same package-created opaque configuration supplied in options.drizzleInstance. getDrizzleDatabase() infers and returns that complete configured type. getDrizzleTransaction() structurally derives Drizzle’s native transaction callback parameter from it, so schema and selected-row inference survive while outer-only operations (for example SQLite Proxy’s batch()) are absent. Native joins and repository writes still participate in the same commit or rollback:

import { eq } from 'drizzle-orm';
import {
  createDrizzleDatabase,
  getDrizzleDatabase,
  getDrizzleTransaction,
} from '@setu-ts/database-plugin';

const drizzleDatabase = createDrizzleDatabase(drizzleDb, (database, work) =>
  database.transaction(work),
);
const outer = getDrizzleDatabase(db, drizzleDatabase);
const rows = await outer.select().from(users);

await db.transaction(async (uow) => {
  await uow.getRepository<User>('User').create(newUser);

  const tx = getDrizzleTransaction(uow, drizzleDatabase);
  const joined = await tx
    .select({ userId: users.id, teamName: teams.name })
    .from(users)
    .innerJoin(teams, eq(users.teamId, teams.id));
});

The opaque configuration carries compile-time correlation while its database, bridge, and validity remain in package-private storage. It is frozen with a null prototype as defense in depth; mutation, spread, assignment, cloning, prototype inheritance, and cross-instance reuse do not create accepted identities. A caller cannot select a forged generic at the UoW call, and a configuration from another database throws. Use getDrizzleDatabase() for outer-only operations; getDrizzleTransaction() intentionally returns only the transaction-safe callback surface. The distinct functions also keep a service widened structurally to IUnitOfWork runtime-truthful. Memory, Prisma, and custom services/UoWs throw Drizzle query access requires adapter 'drizzle'; configured adapter is '<type>'. A structural service or Unit of Work not created by this package throws Drizzle query access requires a database-plugin service or unit of work.

Health status

Since M90b the database indicator gates on the service’s lifecycle FIRST, uncached — a closed database reads down immediately, never from an outcome cached before close. The gate is re-read after the probe settles as well, so a poll already in flight when close() begins reports down rather than publishing the answer the probe had cached a moment earlier. That gate reads DatabaseService.isClosed, a lifecycle-only member that reaches no adapter, so every IDatabaseAdapter.isReady() call happens behind it, inside a cached, bounded probe — 5-second TTL, 2-second bound, built on createCachedProbe — and an adapter whose readiness performs I/O cannot hang /health past the bound. Repeated polls cost at most one readiness read per TTL; gating on isHealthy() instead read the adapter on the one path deliberately outside that bound, and cost two reads per poll. The consequence is the ordinary TTL trade-off, and it is the same one every other M90b indicator makes: closing the database reads down on the very next poll, while an adapter that loses readiness on its own — a pool that ends itself — is served from the cache for up to the TTL before the indicator reports it. A Drizzle registration that supplies DrizzleAdapterOptions.poolStats — an application-owned callback reading the driver’s own documented pool API — also publishes the returned DatabasePoolCapacity snapshot ({ total, idle, waiting }) under data.capacity. Omitted, the payload carries no capacity fields. Capacity is data, not policy: no threshold is applied, and the snapshot changes one row only. Since M101a, when it shows every connection busy with callers waiting (idle === 0 and waiting > 0), the probe queues no SELECT 1 and the indicator reports up with reachable: 'unknown' while queries through the adapter are still completing (one completed within the last 10 seconds; with none, a full pool is a hung database and reports degraded; once getDrizzleDatabase/getDrizzleTransaction has handed out the native instance, whose queries bypass the adapter, progress is unobservable and a saturated pool reads up) — saturation, not an outage, so /ready does not pull every saturated replica at once. Without poolStats that row cannot be read, so a pool connection timeout or an unanswered probe reports degraded (a pool connection timeout reported down before M101a: the database never answered either way). Caller-facing pool-timeout status mapping is M90f. A snapshot the callback returns in a malformed shape is dropped exactly like an absent one — a broken reading is never published as a number. A callback that throws, or one whose counters violate the documented shape (a negative count, or idle exceeding total, which counts idle + in use), is dropped the same way: capacity is omitted for that poll and the indicator’s own lifecycle and reachability answer stands.

Since M95b the payload also carries reachable whenever the adapter carries a liveness probe (the optional IDatabaseAdapter.isHealthy?()): true — the backend answered; false — down; a probe that exists and did not answer inside the 2-second bound reports 'unknown' and the status degraded, never up — the claim that put a dead-database pod back in rotation (X51-1: the indicator used to read the lifecycle isReady(), which reports that connect() once succeeded and says nothing about the backend now). An adapter that ships NO probe reports up with reachable OMITTED and /ready answering 200 — the deliberate no-change row: a probe that was never written is evidence of nothing, and mapping a missing probe to degraded would fail /ready for every healthy Cosmos, Bigtable and DynamoDB application on upgrade (degraded already answers 503). Shipped probes: MongoDB (db.command({ ping: 1 })), Prisma and Drizzle (SELECT 1; Drizzle omits the probe for instances without execute()), memory (its own connection state — the process is the backend). Cosmos, Bigtable and DynamoDB omit the probe pending one optional member on their own client facades; their payload is unchanged. The concrete DatabaseService exposes the seam the indicator reads: hasReachabilityProbe (a synchronous presence read) and reachability() (Promise<boolean | undefined> — the bounded probe, undefined when no answer was produced), the database twin of IMessageBroker.reachability(). The lifecycle read still gates the probe, so an adapter whose own probe does not re-derive isReady() cannot report up for a connection it has already dropped.

Database Interface

interface IDatabaseService {
  getRepository<Entity>(entity: string): IRepository<Entity>;
  transaction<T>(work: (uow: IUnitOfWork) => Promise<T>): Promise<T>;
  query<T>(sql: string, params?: unknown[]): Promise<T[]>;
  migrate(): Promise<void>;
  isHealthy(): Promise<boolean>;
  close(): Promise<void>;
}

interface IRepository<Entity, Id extends EntityKey = string> {
  findById(id: Id): Promise<Entity | null>;
  findAll(options?: FindOptions): Promise<Entity[]>;
  findOne(options?: FindOptions): Promise<Entity | null>;
  findPage(options: PageOptions): Promise<Page<Entity>>;
  create(data: Partial<Entity>): Promise<Entity>;
  update(id: Id, data: Partial<Entity>): Promise<Entity>;
  delete(id: Id): Promise<boolean>;
  updateWhere?(id: Id, where: WritePrecondition, data: Partial<Entity>): Promise<Entity | null>;
  deleteWhere?(id: Id, where: WritePrecondition): Promise<boolean>;
  exists(id: Id): Promise<boolean>;
  count(options?: CountOptions): Promise<number>;
}

Every member except updateWhere? and deleteWhere? is required — including findPage, which is easy to miss because the sibling IDataSource.findPage? is optional. A class implementing IRepository directly, without extending BaseRepository, must supply findPage; the in-repo reference implementor is packages/database-plugin/test/fixtures/repository-implementor.ts, and the reader-side step is in docs/upgrading.md.

The concrete DatabaseService additionally exposes readonly isClosed: boolean (since 0.5.0) — a lifecycle-only read that reaches no adapter, added for the health indicator’s uncached gate. isHealthy() answers lifecycle AND adapter readiness together; isClosed answers lifecycle alone.

query() is the existing backend-specific raw-SQL escape hatch. It requires a configured Drizzle instance with execute(); typed builders obtained through the Drizzle accessors do not.

Every adapter binds params and never interpolates them, and the statement carries the connector’s own placeholders — $1… on PostgreSQL, ? on MySQL and SQLite. Prisma and D1 forward the text verbatim; the Drizzle adapter splits it at its placeholders and rebuilds it through Drizzle’s own SQL chunks, which emits an ascending-placeholder statement byte-identically. A placeholder count that disagrees with params, a gap in the $N sequence, or both placeholder styles in one statement is refused before the driver is reached, because a mis-bound parameter is silent. On PostgreSQL, ?, ?| and ?& are also jsonb key-containment operators that no scanner can tell from a placeholder; such a statement is refused or fails at the database, never mis-bound — write it with $N placeholders. Programmatic migrate() is unsupported by all current adapters and rejects with UnsupportedMigrationError because each ORM owns migrations through its CLI; it is a permanent framework capability boundary and therefore answers 501 Not Implemented through errorHandler.

FindOptions.filter and CountOptions.filter accept a portable expression tree in addition to the existing equality-only where map. where and filter are conjoined, and every built-in adapter evaluates the same operators: eq, contains, gt, gte, lt, lte, and in, nested with and / or. findOne() applies the same options as findAll() and returns the first match or null.

const users = await userRepo.findAll({
  where: { active: true },
  filter: {
    type: 'or',
    filters: [
      { type: 'comparison', field: 'name', operator: 'contains', value: 'Ada' },
      { type: 'comparison', field: 'age', operator: 'gte', value: 18 },
    ],
  },
});

An in with an empty list matches nothing, and a list containing null matches rows whose column is null — SQL IN never matches NULL by itself, so the SQL adapters emit an explicit null branch. contains is a substring match whose % and _ are always data rather than wildcards; its case sensitivity is the database’s, not the framework’s — Memory, D1 and Mongo match case-sensitively, while a LIKE-based backend follows the column’s collation (case-sensitive on PostgreSQL, case-insensitive on SQLite and most MySQL collations). Mongo compiles to $regex, to which MongoDB does not apply collation, so a case-insensitive collection collation does not make it case-insensitive. Collation control is not part of this contract.

On the Prisma adapter the connector decides how that guarantee is met. On PostgreSQL, MySQL, SQL Server, and CockroachDB the value is escaped and matched literally, because their LIKE defaults its escape character to backslash. On SQLite the guarantee is not expressible through Prisma’s filter API (Prisma emits no ESCAPE clause and SQLite has no default escape character), so a contains filter throws UnsupportedFilterOperatorError rather than return wrong rows; pass a raw query, or use the Memory/Drizzle adapter (both honour contains as a literal substring). When the adapter cannot determine the connector it throws the same error naming the provider option; pass provider (e.g. provider: 'postgresql') in the adapter options to name it explicitly.

The Memory adapter’s guarantees

MemoryAdapter is the default and is never given a schema, which fixes what it can enforce. An unknown select or orderBy field — one that no stored row carries — is refused by name, matching what Drizzle answers for the same call; a field present on at least one row counts as known, and an entity holding no rows accepts anything, since there is nothing to observe and nothing to return. An unknown where or filter field is not refused: without a schema the adapter cannot tell an unknown column from one absent on every row, and matching nothing is a defensible answer.

A create whose caller-supplied primary key is already stored is refused — the key is the one constraint this adapter knows, and a duplicate would leave a row no lookup by id can address; for the same reason an update cannot change a primary-key value (MongoDB’s immutable _id rule). Other uniqueness, column types, foreign keys, checks and defaults are not enforced and cannot be by a schema-less store. Use this adapter for development and tests, and run integration tests against the backend you deploy on.

Custom Adapters (external backends)

DatabasePluginOptions is a union discriminated on type. The 'custom' arm accepts any IDatabaseAdapter from @setu-ts/common, which is how a backend implemented outside this package is registered — no plugin imports another plugin.

import { DatabasePlugin } from '@setu-ts/database-plugin';
import { D1Adapter, type ID1Database } from '@setu-ts/cloudflare-plugin';

app.register(
  DatabasePlugin({
    type: 'custom',
    adapter: new D1Adapter(env.DB as ID1Database),
  }),
);

adapter is required by the union, so a 'custom' registration that omits it is a compile error rather than a startup throw. The plugin calls connect() on the adapter during register() and disconnect() on shutdown; it never constructs or replaces it. name and options apply as usual — logQueries routes a custom adapter’s data sources through the same single logging wrapper every built-in adapter uses.

The port to implement:

interface IDatabaseAdapter extends IOrmAdapter {
  transactionIsolationLevels?: readonly TransactionIsolationLevel[];
  isHealthy?(): Promise<boolean>;
  createDataSource(entity: string): IDataSource;
  beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>;
  rawQuery<T>(sql: string, params?: unknown[]): Promise<T[]>;
}

interface IDataSource {
  findAll(query: NormalizedQuery): Promise<Record<string, unknown>[]>;
  findById(id: EntityKey): Promise<Record<string, unknown> | null>;
  create(data: Partial<Record<string, unknown>>): Promise<Record<string, unknown>>;
  update(id: EntityKey, data: Partial<Record<string, unknown>>): Promise<Record<string, unknown>>;
  delete(id: EntityKey): Promise<boolean>;
  updateWhere?(
    id: EntityKey,
    where: WritePrecondition,
    data: Partial<Record<string, unknown>>,
  ): Promise<Record<string, unknown> | null>;
  deleteWhere?(id: EntityKey, where: WritePrecondition): Promise<boolean>;
  findPage?(query: NormalizedQuery): Promise<PageResult>;
  count(where: Record<string, unknown>, filter?: FilterExpression): Promise<number>;
}

A data source owns query evaluation end to end — it applies where, orderBy, offset/limit and select itself, and BaseRepository must not re-apply any of them.

Conditional writes (M105, since 0.9.0). Both optional members address the supplied key AND require every predicate field to equal its value at the write. updateWhere returns the updated row or null; deleteWhere returns whether a row was deleted. An absent key and a predicate miss have the same outcome and write nothing. The key and predicate remain separate conjunctions even when the predicate names a key field.

WritePrecondition, exported by @setu-ts/common, is Readonly<Record<string, string | number>>. checkWritePrecondition(where, data?) returns a WritePreconditionCheck: { ok: false, problem }, or { ok: true, where, data } carrying private copies of the inputs. It requires a non-empty plain equality object, non-empty field names without a $ prefix or ., string or finite-number values, and, when supplied, a non-empty plain update payload. Each field is read once into the copy and the copy is what gets validated and written, so an input that changes between reads (a Proxy) cannot send something other than what passed. An own __proto__ key is refused, in the predicate and in the payload, because Node and Bun drop it from any object a backend rebuilds by assignment. Every implementation validates direct calls as well as repository calls. checkWritePrecondition’s refusal reasons quote no caller field name or value, and a Prisma validation refusal — whose message renders the whole query — becomes UnknownPayloadFieldError or InvalidFieldValueError with a fixed-message cause, on a direct data-source call as through a repository (M119e; it was UnsupportedQueryFeatureError before 0.11.0). No other guarantee is made about message text: key handling shared with findById/update/delete, adapter mapping and marshalling refusals, and driver or server errors (a type the column rejects, an unknown column) may quote caller keys, field names or values, as for every other repository operation. Responses mask them (X12-3), so they reach server logs only. Invalid inputs reject with UnsupportedQueryFeatureError feature 'write-precondition' (unbranded) — except a direct call to the D1 data source, which rejects with CloudflareUnsupportedError, since cloudflare-plugin cannot import database-plugin’s error. Through a repository the check runs in BaseRepository first, so every backend answers 'write-precondition' there. BaseRepository rejects missing support with UnsupportedQueryFeatureError feature 'conditional-write' (HTTP hint 501), before any I/O. Both members stay optional for implementors.

Deferred transaction sources (memory overlay, D1 batch, DynamoDB buffer, Cosmos batch and Bigtable) omit both members: the result is unknown until commit, so the repository refuses 'conditional-write'. Prisma, Drizzle and MongoDB transaction sources carry them. The tenant and inbox bridges use the conditional path when offered and fall back only on absence or that named refusal. The outbox requires native conditional writes and refuses unsupported sources at startup. Other errors propagate. On that fallback the tenant bridge reads ownership and then writes by key, so a delete-and-recreate under a reused caller-supplied key in between can move the write onto another tenant’s row; generated keys avoid the reuse. Bigtable reads an updated row back separately; the tenant bridge checks the returned tenant on both paths before returning it.

__proto__ fields. The conditional members refuse an own __proto__ field in the predicate and the payload on every adapter. Cosmos DB and DynamoDB also refuse one in a plain create/update payload (DynamoDB at any depth, because the AWS SDK returns such an attribute without a value), and neither lets a stored __proto__ field set a read row’s prototype: Cosmos returns it as an ordinary field, DynamoDB omits the attribute the SDK cannot deliver.

Stored representation. Predicate scalars compare with the stored representation. DynamoDB date attributes encoded as ISO strings require the ISO string; Bigtable’s typed/json codecs use their configured scalar encoding. Neither member translates a Date or allows a document path or operator in the predicate.

Breaking for implementors as of M79. findById/update/delete moved from string | number to EntityKey, which adds a composite-record arm. A parameter is contravariant, so an adapter still declaring the scalar-only form is a compile error; callers passing a scalar are unaffected. The same release widened FilterComparison.field to string | readonly string[] (an array is a nested document path) and the gt/gte/lt/lte value to accept Date, so any code READING those fields must handle both forms.

findPage is optional. Every adapter this framework ships implements it; an adapter that cannot page by cursor omits it, and the repository refuses by name rather than returning an empty page — so absence means “this backend cannot page by cursor”, never “there are no more rows”.

isHealthy? is optional (M95b). It answers “is the backend reachable right now” — the liveness read the inherited lifecycle member isReady() was mistaken for. true means the backend answered; false means it was contacted and refused or failed; an adapter that cannot probe honestly omits the member, and the health indicator then reports up with reachable omitted rather than inventing an answer. The lifecycle read still gates the probe, so an adapter whose own probe does not re-derive isReady() cannot report up for a connection it has already dropped. Shipped probes: MongoDB (db.command({ ping: 1 }) through the optional IMongoDatabase.command? facade member), Prisma and Drizzle (rawQuery('SELECT 1')), memory (its own connection state).

Composite keys, nested paths and cursor pagination (M79)

@setu-ts/common exports the portable data-access contract these three features rest on, and is where a backend author imports it from — the codec lives there because cloudflare-plugin needs the identical encoding and a plugin may not import another plugin (AI_GUIDELINES §2.2).

@setu-ts/database-plugin re-exports the subset its own consumers reach for — EntityKey, PageResult, CursorPayload, CursorValue, encodeCursor, decodeCursor and keysetPredicate. sortFingerprint, mintNextCursor and resolveKeysetSort are not re-exported; import them from @setu-ts/common.

Composite keys

Scoped fingerprints (since 0.11.0). sortFingerprint(orderBy: Readonly<Record<string, OrderDirection>>, scope?: { readonly entity: string; readonly keyColumns: readonly string[] }): string returns the byte-identical legacy field:direction pairs without scope. With scope it returns JSON.stringify([scope.entity, scope.keyColumns, pairs]). Memory, Prisma, Drizzle, MongoDB, DynamoDB, Cosmos DB, Bigtable and D1 pass the resolved entity and key columns on mint and decode. Scope is a correctness check, not authorization; tenant predicates remain required.

Portable refusal classes (@setu-ts/common, since 0.11.0). UnknownPayloadFieldError(entity: string, field: string, options?: ErrorOptions) has name UnknownPayloadFieldError, a capped, single-line field diagnostic and the fixed hint { status: 400, title: 'Bad Request', detail: 'The request names a field this resource does not have.' }. InvalidFieldValueError(entity: string, options?: ErrorOptions) has name InvalidFieldValueError and hint { status: 400, title: 'Bad Request', detail: 'A supplied value does not fit the type of its field.' }. Its message is Entity '<entity>': the database refused a supplied value for its field type. No supplied value, key or field is included. Repository mappings retain a scrubbed driver error as cause. Drizzle PostgreSQL repositories map the four supplied-value SQLSTATE codes; D1 maps STRICT-table type refusals. Prisma validation errors containing Unknown argument `<field>` map to UnknownPayloadFieldError; other validation errors and known-request P2007 errors map to InvalidFieldValueError. This includes conditional writes, which now answer 400 rather than 501 for these refusals. A Prisma refusal cause is a new Error whose copied name and fixed message name only the original name and code, for example Prisma refused the input (PrismaClientKnownRequestError P2007).; the original object, query and payload are discarded.

findById, update and delete accept a composite record. Each adapter learns its key columns from a per-entity mapping whose primary-key field accepts a column list:

// Cloudflare D1
new D1Adapter(env.DB as ID1Database, {
  tables: { Membership: { table: 'memberships', primaryKey: ['tenant_id', 'user_id'] } },
});

// MongoDB — flat top-level key columns (the default for a composite key)
DatabasePlugin({
  type: 'mongodb',
  options: { url },
  mongoEntities: { Membership: { primaryKey: ['tenantId', 'userId'] } },
});

A repository declares its key type and addresses rows with a record:

const repo = db.getRepository<Membership, { tenantId: string; userId: string }>('Membership');
await repo.findById({ tenantId: 't1', userId: 'u1' });

A scalar key against a multi-column entity, or a record missing a column, is refused by name.

MongoDB idType: 'compound' stores the composite key as a subdocument _id. The subdocument is built in the mapping’s declared column order, never the caller’s key-object order: a Mongo subdocument _id is matched by exact, order-sensitive equality, so {userId, tenantId} does not match a document stored as {tenantId, userId}. The default for a composite key is flat top-level columns, which are order-independent and constrained by a unique index.

Prisma addresses a compound key through Prisma’s own compound-key field. The name is derived by joining the key columns with _, matching what Prisma generates for an unnamed @@id. A model declaring a named @@id must set compositeKeyName — Prisma rejects the derived name on such a model, so this is required rather than optional:

DatabasePlugin({
  type: 'prisma',
  options: { prismaClient },
  entities: {
    Membership: { keyColumns: ['tenantId', 'userId'] },
    Enrollment: { keyColumns: ['courseId', 'personId'], compositeKeyName: 'enrollmentKey' },
  },
});

Nested field paths

FilterComparison.field accepts a readonly string[] as a document path. A plain string is a flat field, unchanged. A dotted string is not a path — a column whose name legitimately contains a dot keeps its meaning.

await repo.findAll({
  filter: { type: 'comparison', field: ['address', 'city'], operator: 'eq', value: 'Kolkata' },
});

Every adapter that supports a path translates it natively; none filters in JavaScript. D1 is the explicit exception and refuses one by name. An empty path array is always refused — a filter that quietly matches everything is a data-exposure defect, not a no-op.

Two translation facts are worth knowing before relying on a path filter, both measured rather than inferred:

• in is expanded, not translated. Neither Prisma’s JSON path filter nor any SQL dialect offers a path membership operator, so in becomes an OR of equality legs. An empty list compiles to a match-nothing predicate that binds no values.
• Extraction normalises to text, and an ordered comparison against a number casts back. PostgreSQL’s #>> and MySQL’s JSON_UNQUOTE are text-valued while SQLite’s json_extract preserves the JSON type, so without normalising, one filter would mean two different things. Casting back for gt/gte/lt/lte on a number is what makes age > 9 match 30 — as text, '30' > '9' is false.

A Date is refused on a path filter on every SQL adapter: a JSON document has no date type, so the stored representation is whatever the writer chose. Compare an ISO string, or give the value its own column.

Prisma requires provider and Drizzle may require dialect for a path filter, because the syntax differs per connector and neither library publishes a discriminant the adapter can read reliably. Drizzle detects its dialect from the instance and needs the option only when detection fails; either way, an adapter that cannot determine the syntax refuses by name rather than emitting a guess — a guessed syntax returns wrong rows on the engine it guessed wrong about, where a refusal names the option that fixes it.

DatabasePlugin({
  type: 'drizzle',
  options: { drizzleInstance, drizzleTables, dialect: 'postgresql' },
});

Cursor pagination

let cursor: string | null = null;
do {
  const page = await repo.findPage({ orderBy: { createdAt: 'desc' }, limit: 50, cursor });
  handle(page.rows);
  cursor = page.nextCursor;
} while (cursor !== null);

offset is unchanged and not deprecated; the cursor is additive beside it. A query carrying both a non-zero offset and a cursor is refused, because the two express contradictory positions — “skip this many from the start” and “after this row”.

nextCursor carries one guarantee: it is non-null exactly when a further page exists — including a zero-row page that is not the last — and it is never derived from rows.length. Backends mint it by one of two mechanisms. The row-based adapters fetch limit + 1 rows and answer null precisely when the extra row is absent. The DynamoDB adapter instead carries the server’s own continuation key (LastEvaluatedKey) inside the token and answers null exactly when the server returned none: DynamoDB applies Limit before FilterExpression, so a filtered page can return fewer rows than limit — or none — while further matching rows remain, and a row-count probe would report the walk terminal and silently drop rows.

The cursor is opaque and carries a fingerprint of the sort it was minted under, so presenting it under a different orderBy is refused rather than served a silently wrong page. The resolved sort always ends in the entity’s key columns: over rows sharing a sort value, a walk without that tiebreaker silently loses rows — measured at four of six against live PostgreSQL and MongoDB.

ORDER BY on a Date column requires the Date arm of the ordered comparison, which is why that widening ships alongside. Cloudflare D1 refuses a Date by name: SQLite has no date type, so the adapter cannot know whether the column stores an ISO string or an epoch integer.

MongoDB backend ('mongodb' arm)

MongoAdapter is a document-store backend over the native mongodb driver (mongodb), registered through the same discriminated union as every other backend:

import { DatabasePlugin } from '@setu-ts/database-plugin';

app.register(
  DatabasePlugin({
    type: 'mongodb',
    options: {
      url: 'mongodb://127.0.0.1:27017/app',
      // or inject a constructed client so the driver is never imported:
      // client: new MongoClient(url),
    },
  }),
);

MongoAdapterOptions is the Mongo-specific option bag, and it is a union of two arms: one requires url (the connection string), the other requires client (an already-constructed IMongoClient). Supplying neither is a compile error rather than a connect() throw — the guarantee every other built-in arm gives. MongoAdapterOptionsBase is the half both arms share (objectIdCtor, database, collections). When client is present the lazy import('mongodb') never runs; the injected client is structural, so a driver of a different major that honours the same shapes is accepted. An injected client that uses ObjectId values supplies its objectIdCtor companion, so the adapter can convert 24-hex repository ids without importing the driver. database names the database; when absent the one encoded in url is used, and if neither yields a name connect() fails at startup naming the option. collections is a per-entity override ({ collection?, primaryKey?, idType? }); an unmapped entity uses its own name as the collection and 'id' as the primary key — the D1-shaped two-layer mapping, where the public surface is a per-entity override with a zero-config default and the internal target is unexported.

Identity maps _id to the configured primary key on read and back on write. Because a findOne({_id: "<24-hex>"}) misses when _id is an ObjectId, the driver id is converted with a 24-hex string test for an idType of 'auto' (the default), forced for 'objectId', and forbidden for 'raw'. The string half of that test is load-bearing rather than defensive: the driver’s own ObjectId.isValid answers true for any number while its constructor rejects one, so a collection keyed by application-assigned numbers is passed through verbatim — findById, update and delete accept string | number, and a numeric key must reach the driver unconverted. On read the inverse holds: an ObjectId is rendered as its 24-hex string, while a JSON scalar keeps its own type, so the value create() returns is the value findById() accepts. primaryKey may name _id itself, in which case the row keeps that field rather than having it renamed away. The primary key never travels in an update payload — MongoDB refuses a $set that would change _id, and update moves no row to a new key on any adapter.

find serves orderBy/offset/limit/select natively as sort/skip/limit/projection, and contains compiles to a $regex match with an escaped value (the inverse of the SQL contains), so % and _ in the searched value stay literal. An empty filter group compiles to its boolean identity — an empty and matches every document, an empty or matches none — because MongoDB refuses $and: []/$or: [] outright, and those are the answers Memory and Drizzle give.

rawQuery is refused by name with UnsupportedRawQueryError — MongoDB has no SQL, so an application reaches the injected client directly for native commands, exactly as it does for a Prisma raw query. Transactions use a startSession(); on a deployment that is not a replica set they are refused late, never at connect(). On the real driver the refusal surfaces at the first operation inside the transaction as the driver’s own unwrapped MongoServerError (code: 20, codeName: 'IllegalOperation'), not at beginTransaction() (measured, M107); MongoTransactionUnavailableError wraps only a startTransaction() that itself throws.

IMongoClient and IMongoObjectIdCtor are the exported injection seam, and the real driver implements their structural shapes: IMongoClient.connect() is Promise<unknown> because the driver’s own connect(): Promise<this> is not assignable to Promise<void>, and the adapter binds nothing; the same reconciliation admits the driver’s startTransaction(options?): void (the session member is (options?: unknown) => unknown) and its string-and-array Sort union (sort? is unknown on find/findOne, where the adapter builds a Record). The claim is pinned by a compile-time fixture — packages/database-plugin/test/types/mongo-seam.assert.ts assigns a real new MongoClient(...) to IMongoClient with NO cast under a static import of the driver, and fails pnpm run check the moment the seam drifts again. The types the client’s members reference — IMongoDatabase, IMongoSession, and the IMongoObjectId instance shape — are exported alongside them so the seam’s return types are nameable from the package entry, as are the collection-level shapes IMongoDatabase.collection() reaches (IMongoCollection, IMongoCursor, IMongoCollectionFindOneAndUpdateOptions, and the MongoOptions/MongoWriteOptions option bags).

DynamoDB backend ('dynamodb' arm)

DynamoAdapter is a key-value backend over the native AWS SDK v3 client (@aws-sdk/client-dynamodb), registered through the same discriminated union as every other backend:

import { DatabasePlugin } from '@setu-ts/database-plugin';

app.register(
  DatabasePlugin({
    type: 'dynamodb',
    options: {
      region: 'us-east-1',
      // `endpoint` addresses the local emulator in development and tests; absent
      // in production, where the SDK's own endpoint resolution applies.
      entities: { Order: { partitionKey: 'tenantId', sortKey: 'orderId' } },
    },
  }),
);

DynamoAdapterOptions is the DynamoDB-specific option bag, and it is a union of two arms: one requires region (with an optional endpoint — the emulator address — and credentials), the other requires client, an already-constructed client behind the structural IDynamoClient facade. Supplying neither is a compile error rather than a connect() throw — the guarantee every other built-in arm gives. DynamoAdapterOptionsBase is the half both arms share (entities, maxPageFetches). When client is present the lazy import('@aws-sdk/client-dynamodb') never runs. The adapter owns marshalling and deliberately does not use lib-dynamodb’s DocumentClient: automatic marshalling would hide two facts the adapter must decide — DynamoDB has no date type, so the encoding of a Date comparison is the mapping’s decision, and a DynamoDB N is an arbitrary-precision decimal that Number() degrades.

entities is the per-entity mapping ({ table?, partitionKey, sortKey?, indexes?, dateAttributes? }); an unmapped entity uses its own name as the table and 'id' as the partition key. A scalar key is accepted only for a partition-only entity — against a sort-keyed entity it is refused by name, because a GetItem carrying only the partition key is a server-side ValidationException. A composite key record is projected down to exactly the resolved key columns (an extra attribute is the same server-side refusal), and a record missing a column, or carrying an empty-string value, is refused by name. The key map itself is order-insensitive — the opposite of a Mongo compound _id subdocument — so no canonical ordering is applied.

Both single-row writes are conditional, because the unguarded forms violate the IDataSource contracts silently — both measured against the real emulator. create carries attribute_not_exists(<partitionKey>): an unguarded PutItem on an existing key silently overwrites the item and drops every attribute absent from the new one, answering 200. update carries attribute_exists(<partitionKey>) with ReturnValues: 'ALL_NEW': an unguarded UpdateItem on a missing key upserts a ghost item and returns it as though it were an update, so the conditional failure (ConditionalCheckFailedException) is what produces the documented rejection. delete reads ReturnValues: 'ALL_OLD' for its boolean — no read-before-delete round trip, and no constant true.

The access path is resolved from the caller’s query: an equality on the entity’s partition key (or on a configured index’s partition key, selecting that GSI) is a Query; everything else is a Scan, because a Query without a partition-key equality is a server-side ValidationException — the selection is forced, not an optimisation. Every predicate not folded into the key condition becomes a FilterExpression, and every attribute name is aliased through a generated placeholder, so a reserved word like status cannot reach the server raw. A non-empty select is pushed down as a ProjectionExpression, so the server returns only the projected attributes rather than whole items; repeated and empty field names are dropped first, because DynamoDB refuses a projection naming one path twice (Two document paths overlap with each other, even under distinct aliases) and refuses an empty attribute name outright. Push-down is safe for cursor paging: LastEvaluatedKey is computed independently of the projection, so a projection omitting the key columns still resumes correctly. orderBy is served only when it names exactly the resolved access path’s sort key (as ScanIndexForward); a non-key or multi-field orderBy is refused by name with UnsupportedQueryFeatureError, and a non-zero offset is refused the same way — both because the SDK accepts and silently discards the unrecognised parameter, answering 200 with unordered or unskipped rows, so forwarding one returns confidently wrong rows with no diagnostic anywhere in the stack.

Pagination is the server’s own continuation token carried inside the portable cursor codec, and the invariant is exact: nextCursor is non-null if and only if the response carried a LastEvaluatedKey — never derived from rows.length, because Limit is applied before FilterExpression and a filtered page can return fewer rows than the limit, or zero, and still not be the last. A bounded fill loop (maxPageFetches, default 10) keeps fetching while a page is short and a token remains; at the bound it returns what it has with a non-null cursor, never a terminal page. maxPageFetches must be a positive integer and is validated at construction: the loop runs while fetches < maxPageFetches, so Infinity would silently remove the very bound the option imposes (a findPage whose filter matches nothing would scan the whole partition to exhaustion) and NaN would make the comparison false on the first pass, collapsing the loop to a single server page — neither raises anything on its own, so both are refused by name up front. count() loops to exhaustion for the same reason — a paged COUNT response under-reports past the first page. A Date comparison must be declared per attribute (dateAttributes: { createdAt: 'iso' | 'epochMs' }) or it is refused by name naming the option, and an out-of-range decimal N is preserved on read as its string rather than degraded through Number(). Transactions buffer writes and flush them as one TransactWriteItems at commit — refused by name past 100 items, or on two operations for one item key — and reads inside a transaction see committed state (no read-your-own-writes), documented rather than emulated.

IDynamoClient and DynamoSdkModule are the exported injection seam, with createInjectedDynamoLoader and createLazyDynamoLoader as its two arms. The command and attribute shapes the client’s members reference — DynamoAttributeValue, DynamoEntityMapping, DynamoIndexMapping, DynamoDateEncoding, and the Dynamo*CommandInput/Output/Transact* closure — are exported alongside them so the seam’s return types stay nameable from the package entry. The internal target resolution, expression builder, marshaller and access-path resolver are not exported.

Cosmos DB backend ('cosmos' arm)

CosmosAdapter serves Azure Cosmos DB’s NoSQL (SQL) API over @azure/cosmos, registered through the same discriminated union as every other backend:

import { DatabasePlugin } from '@setu-ts/database-plugin';

app.register(
  DatabasePlugin({
    type: 'cosmos',
    options: {
      endpoint: 'https://my-account.documents.azure.com:443/',
      key: cosmosKey,
      database: 'app',
      containers: { Order: { container: 'orders', partitionKey: 'tenantId' } },
    },
  }),
);

Cosmos DB’s MongoDB API is a different wire protocol; it is served by the 'mongodb' arm pointed at a Cosmos connection string. That route is documented and not verified against a live account: the emulator’s MongoDB endpoint tops out at API version 4.0 (wire version 7) while the mongodb driver this package pins requires wire version 8, so it cannot be exercised there.

CosmosAdapterOptions is a union of two arms: one requires endpoint + key, the other requires client (an already-constructed structural ICosmosClient, which is how an Entra ID or connection-string client reaches the adapter). database is required on BOTH arms, because a Cosmos endpoint encodes no database name and there is nothing to fall back to. CosmosAdapterOptionsBase is the half both arms share (database, containers, logQueries). containers is a per-entity override ({ container?, primaryKey?, partitionKey? }); an unmapped entity uses its own name as the container and 'id' as the primary key — the D1-shaped two-layer mapping.

The adapter provisions nothing. Cosmos creates no database or container implicitly, and throughput, partition-key and indexing choices belong to the application; a missing container is refused by name at first use.

The partition key is discovered from the container definition and read once per container. A declared partitionKey is validated against it and refused by name on a mismatch — a point read carrying the wrong partition key answers 404 rather than an error, so an unvalidated mapping would report “not found” for every row of a healthy container.

Identity. A document is addressed by (partition key, id). findById point-reads when the key carries the partition key, or when the container partitions by the primary-key field; otherwise it resolves the row by a cross-partition query, which costs more request units and is refused by name when the id matches two documents, since an id is unique only within a partition. A primary key must be a string — the service refuses any other type, and converting silently would change the type a caller gets back from create().

update merges through a server-side patch while the payload fits one request and through a read-merge-replace guarded by _etag beyond it, raising CosmosConcurrentModificationError on a lost race. A payload that would change a partition-key value is refused by name, because such a replace answers 404 rather than moving the item.

contains compiles to CONTAINS, a literal substring match (no %/_ escaping, case-sensitive); in compiles to ARRAY_CONTAINS with the list bound as one array parameter, so an empty list matches nothing natively. offset/limit are served natively, with the contract’s -1 sentinel translated rather than passed through (Cosmos refuses LIMIT -1, and refuses OFFSET without LIMIT).

Pagination uses the portable keyset cursor, not a Cosmos continuation token — this adapter’s design choice, matching what the tested backend supports: measured against the emulator, an ORDER BY query returns no continuation token even with maxItemCount passed as a query option. The claim is scoped to that measurement rather than asserted of every Cosmos deployment. On a real account, keyset paging therefore needs a composite index over (sort field, id) for each paged container, because the walk always adds the key column as its tiebreaker.

rawQuery is refused by name with UnsupportedRawQueryError: a Cosmos SQL query is scoped to one container and the signature names none, so an application reaches the injected client directly.

Transactions are a deferred batch. beginTransaction() buffers every write and flushes it as one transactional batch at commit; rollback() discards it and sends nothing. The batch is atomic within one container and one partition-key value and caps at 100 operations, and a write crossing any of those bounds raises CosmosTransactionScopeError at that write. Reads inside a transaction observe committed state only — the deferred-write clause IDataSource documents. A buffered update is sent as a patch, so it writes only the fields its payload names and two updates of one row compose; an update too wide for a single patch request falls back to a whole-document replace, which cannot compose, so buffering one for a row the transaction has already written is refused rather than silently discarding the earlier write. rollback() is idempotent (commit() is not), because the framework rolls back inside the same catch that sees a failed commit — refusing there would replace the batch’s own per-operation diagnostic with a complaint about rollback.

What the arm deliberately cannot do, split by who could close it. Two are platform limits: Cosmos rejects a cross-container join with a 400 (a query addresses one container; its own JOIN unwinds an array inside a single item), and returns no continuation token for an ORDER BY query on the tested emulator. Three are contract limits: grouping is absent from NormalizedQuery, which carries no aggregate beyond count — the Cosmos dialect does support GROUP BY, so closing that is a common widening every adapter must answer; rawQuery is refused because the committed signature names no container; and request units, consistency levels, TTL and index policy are outside the portable contract by design (the M79 exclusion). An application needing any of them reaches the injected client, as it does for a Prisma raw query.

ICosmosClient and the shapes it reaches (ICosmosDatabase, ICosmosContainer, ICosmosItems, ICosmosItem, ICosmosQueryIterator, CosmosQuerySpec, CosmosQueryParameter, CosmosPartitionKeyValue) are the exported injection seam, together with the response and operation shapes those members return and accept (CosmosItemResponse, CosmosFeedResponse, CosmosRequestOptions, CosmosAccessCondition, CosmosPatchOperation, CosmosBatchOperation with its four arms CosmosBatchInsertOperation, CosmosBatchReplaceOperation, CosmosBatchPatchOperation and CosmosBatchDeleteOperation, CosmosBatchResponse, CosmosContainerDefinition) — so the seam’s own signatures are nameable from the package entry. The real SDK implements their structural shapes.

Cloud Bigtable backend ('bigtable' arm)

BigtableAdapter serves Google Cloud Bigtable over @google-cloud/bigtable, registered through the same discriminated union as every other backend:

import { DatabasePlugin } from '@setu-ts/database-plugin';

app.register(
  DatabasePlugin({
    type: 'bigtable',
    options: {
      projectId: 'my-project',
      instance: 'app-instance',
      tables: {
        Order: {
          table: 'orders',
          rowKey: { fields: ['tenantId', 'orderId'], separator: '#' },
          columnFamily: 'o',
          columns: { total: 'metrics:amount' },
        },
      },
    },
  }),
);

Bigtable inverts the DynamoDB problem. Its row key is a single lexicographically-sorted string, so findById fits it natively with no key object at all. What it lacks instead is everything around the key: there is no secondary index of any kind, so a predicate on a non-key column is a scan and orderBy is row-key order or nothing.

BigtableAdapterOptions is a union of two arms: one requires projectId (with an optional apiEndpoint for an emulator), the other requires client (an already-constructed structural IBigtableClient, which is how a client built with non-default credentials reaches the adapter). instance is required on BOTH arms, because a table is addressed as project/instance/table and neither a client nor a project encodes it. BigtableAdapterOptionsBase is the half both arms share (instance, tables, maxPageFetches, logQueries). tables maps each entity name to a BigtableEntityMapping — { table?, rowKey?, columnFamily?, columns?, valueEncoding? }, whose rowKey is a BigtableRowKeyMapping and whose valueEncoding is a BigtableValueEncoding; an unmapped entity uses its own name as the table, ['id'] as the row-key fields, 'cf' as the column family and tagged values. BigtableAdapter’s constructor also takes an optional second parameter, a BigtableClientLoader, which overrides the inject-or-lazy choice and whose owned flag decides whether disconnect() closes the client it produced.

The adapter provisions nothing and connect() issues no RPC. Column families, garbage-collection policies and split points belong to the application’s provisioning, and a missing table or instance is already reported by the service as 5 NOT_FOUND quoting the full resource path — while instance.getTables() is a table-ADMIN call a data-plane service account commonly cannot make, so probing at connect time would refuse a working configuration. Configuration mistakes are refused at construction instead, by name.

The row key is composed from logical fields. BigtableRowKeyMapping is { fields, separator?, prefix? }, defaulting to { fields: ['id'], separator: '#' }. A single-field key accepts a scalar EntityKey; a multi-field key requires a record naming every field and refuses a scalar, which cannot say which field it is. A key field’s type is not part of the row key — a numeric field renders as its decimal text, so 1 and '1' are one physical row and findById('1') answers the row stored under 1, whose id cell still decodes as the number. Choose one type per key field, and zero-pad a numeric one whose lexicographic order matters. A field value containing the separator is refused: two different logical keys would otherwise compose to one row key, so a write would silently overwrite an unrelated row. Composing a row key from several fields is a mapping concern rather than the composite-key contract concern, which is why this arm needs no common change — Bigtable’s key shares no type with DynamoDB’s partition/sort pair.

Key fields are written as ordinary cells AND recovered from the row key on read, with the cells winning. All three parts are load-bearing: a Bigtable row cannot exist with zero cells; the row key is bytes and records no type, so overlaying it would turn a numeric key field into a string; and a table written outside this framework has no key cells at all, which is what the parse-back serves.

Values are tagged by default. BigtableValueEncoding is 'tagged' | 'raw'. Tagged writes <tag>:<payload>, so a number, boolean, null, Date or object round-trips as itself; a cell carrying no recognised tag decodes as its raw string, which is the interop path. 'raw' writes String(value) and reads every cell as a string, removing that residual ambiguity for an application whose table is entirely foreign.

orderBy is the row key or nothing. An empty sort is honoured, and so is one naming exactly the mapped key fields, in order, all ascending — that IS the scan order. Everything else raises UnsupportedQueryFeatureError: a non-key field has no index, and descending is refused deliberately rather than shipped on reversed: true, because the emulator this adapter is tested against silently ignores that option (measured: it answered ascending with no error), so the path could not be verified. A non-zero offset is refused too — Bigtable has no row offset, and discarding scanned rows would read and bill them; findPage is the route.

Three narrowings reach the server, and nothing else. The row set (an eq on every key field is an exact key; an eq pinning a leading prefix is a prefix range with an exclusive successor end; a pinned prefix plus an in on the final field is an explicit key list), byte-exact value equality for each conjunctive non-key eq, and the column projection. Everything else is evaluated by the same evaluator the memory adapter uses as the portable reference, so the six backends cannot drift about what a FilterExpression means. The invariant is that a push-down may only ever match a superset of what the client-side evaluator keeps; every fallback widens. Two details are correctness requirements rather than tuning: a value test is an exact byte RANGE and never the SDK’s string form, which is a regex (measured, { value: 'a.*b' } matched both a.*b and axxb); and it is wrapped in a condition filter rather than chained, because a bare chain strips every non-matching cell and the row would come back carrying only the cell that matched. An ordered comparison on a key field is not pushed down either — the composed key is a string, so a numeric key field does not sort numerically inside it. The projection is interleaved with a one-cell arm rather than emitted bare: a filter that removes every cell of a row removes the row (the service answers with no empty row), so a bare projection would silently drop a row carrying none of the projected columns — unreachable for a row this adapter wrote, reachable for a table written elsewhere. count reuses that projection, restricted to the columns its predicate needs.

Pagination is a start-key cursor over the portable keyset codec, which is exactly Bigtable’s own continuation mechanism. nextCursor is non-null if and only if the page is non-terminal, never derived from rows.length: a client-side filter can empty a whole raw batch, so a page bounded by maxPageFetches (default 10) returns zero rows AND a cursor, minted from the last row scanned.

rawQuery is refused by name with UnsupportedRawQueryError: Bigtable has no query language behind query(sql, params) — its data plane is ReadRows, MutateRow and CheckAndMutateRow.

Transactions are one row. Bigtable’s only atomicity unit is the single row (a multi-row batch is atomic per entry, not as a whole), so beginTransaction() buffers writes, refuses a second row key at the write that crosses the bound with BigtableTransactionScopeError, and commits the buffer as ONE CheckAndMutateRow whose mutation list applies atomically and in order — a buffered delete followed by writes replaces the row wholesale. rollback() discards, sends nothing, and is idempotent. Reads inside a transaction observe committed state only. create and update are conditional writes: Bigtable’s insert is an upsert, so the CheckAndMutateRow match flag is what makes create refuse an existing row and update refuse an absent one — including inside a transaction, where a buffered create whose row turns out to exist is refused at commit.

What the arm deliberately cannot do. Platform limits: no secondary index of any kind, no row offset, no multi-row atomicity, and no descending scan this adapter can verify. Contract limits: grouping and joins are absent from NormalizedQuery, whose only aggregate is count; rawQuery has no Bigtable surface; and cell versioning plus garbage-collection policies are outside the portable contract by design — no other backend has a counterpart, so exposing them would invent a concept for one adapter. An application needing any of them reaches the injected client.

IBigtableClient and the shapes it reaches (IBigtableInstance, IBigtableTable, IBigtableRow, BigtableReadOptions, BigtableReadRow, BigtableRowData, BigtableCell, BigtableRowRange, BigtableRowBoundary, BigtableValueRange, BigtableFilter, BigtableMutation) are the exported injection seam, so an application implementing its own facade can name every signature. createInjectedBigtableLoader and createLazyBigtableLoader build the two loader arms; BigtableClientConfiguration is what the lazy one takes.

Exports

DataSource is retained under AI_GUIDELINES §9.2 — it is already published. It is now an alias of the promoted IDataSource (the same type), and will be removed in the next major version.

DatabaseAdapterType gained 'custom', then 'mongodb', then 'dynamodb', then 'cosmos', then 'bigtable'; DatabasePluginOptions became a union discriminated on type. All are additive for callers — every existing registration compiles unchanged. MongoDatabaseOptions, DynamoDatabaseOptions and CosmosDatabaseOptions each extend DatabaseConnectionOptions and carry their arm’s dedicated option bag (MongoAdapterOptions, DynamoAdapterOptions, CosmosAdapterOptions), as does BigtableDatabaseOptions with BigtableAdapterOptions, so a registration carrying a memory, Prisma, Drizzle or custom configuration still compiles unchanged.

Query refusals answer 501 Not Implemented (M89b, X19-1). The three query-shape errors — UnsupportedQueryFeatureError, UnsupportedFilterOperatorError and UnsupportedRawQueryError — carry an HttpStatusHint from @setu-ts/common, so @setu-ts/exceptions’ errorHandler answers them 501 with a caller-safe sentence naming the feature or operator and the adapter that refused it. Each is a condition the CALLER caused — the query asks for something the active backend does not implement, permanently — which is exactly what 501 states, and it is the shape a developer meets when SWITCHING BACKENDS: before this, an application that worked on Mongo answered 500 Internal Server Error on every ordered endpoint under DynamoDB, and the response said the server was broken.

The served detail is composed from this package’s own structured fields (feature, operator, connector, adapter), never from the error’s message — which remains the full diagnostic, is reachable only in the log, and is what errorHandler records. So the response gains a status and a sentence without gaining a disclosure channel; a hinted error is exempt from maskInternalErrors precisely because there is no driver output in its body to mask.

Driver conditions answer their classified status (M90f, X38-1/X35-2). DatabaseService classifies a driver rejection at its four interception sites (the repository wrappers, the beginTransaction() acquisition, the transaction catch, and query()) and throws SerializationConflictError — answered 409 Conflict, the canonical retry-me signal, for a backend-reported write conflict (PostgreSQL SQLSTATE class 40 including 40001, Prisma’s P2034 mapping of it, MongoDB’s TransientTransactionError label, DynamoDB’s TransactionConflictException name, Bigtable’s gRPC ABORTED, Cosmos 449) — or DatabaseUnavailableError — answered 503 Service Unavailable — for a transiently unreachable backend (SQLSTATE class 08, 57P03, the node-postgres pool timeout, MongoNetworkError/MongoServerSelectionError, gRPC UNAVAILABLE, Cosmos 429/503, and the net errno ECONNREFUSED family the AWS SDK surfaces as a bare error). Both carry the original driver error as cause — the SQLSTATE and the failing statement stay reachable for the log — and serve a fixed sentence, so the masking exemption stays narrow. Neither carries Retry-After: ErrorResponseInit has no header channel, and the framework holds no honest horizon for a pool’s saturation — 503 is itself the retryable signal (RFC 9110). The rate limiter’s Retry-After is the deliberate asymmetry (a fixed window genuinely knows when it resets). An unrecognised error keeps the masked 500, and an already-classified error is passed through untouched rather than wrapped twice. MongoDB’s conflict mapping is verified against a real replica set and PostgreSQL’s against a real server (SQLSTATE 40001 through Drizzle and Prisma’s P2034 alike); DynamoDB’s TransactionConflictException and Cosmos’s 449 are documented-unverified — neither was reproducible against DynamoDB Local or the local emulator, and Cosmos’s connect refusal is a startup failure that never reaches a client.

A timed-out query answers 504 Gateway Timeout (M113g, V9-33). DatabaseService classifies node-postgres’s query_timeout firing — the driver’s Query read timeout rejection — as a new timeout kind and throws DatabaseTimeoutError, branded 504 Gateway Timeout with the fixed detail “The database did not answer in time.”; the scrubbed driver error stays as cause for the log, and errorHandler reads the hint. It is not DatabaseUnavailableError: that class’s contract says the operation did not happen, and a timed-out statement may have run, so a write’s outcome is unknown and a retry of a write must be idempotent. The bound is the driver’s own — node-postgres’s query_timeout and connectionTimeoutMillis on the Pool the application hands Drizzle; the plugin adds no call deadline of its own, for the reasons the README’s Bounding a call section gives. The behaviour of a timed-out statement inside a transaction is measured in this milestone and documented there. Ships in 0.10.0.

A duplicate key answers 409 Conflict. A write that would duplicate a primary key or a unique index is thrown as DuplicateKeyError (exported from @setu-ts/common, so a package that may not import this one can raise or recognise it), where every backend used to reach the client as a masked 500. The signals, each measured against the real engine: PostgreSQL SQLSTATE 23505, Prisma’s P2002, MySQL’s ER_DUP_ENTRY (by probe; CI runs no MySQL), MongoDB code 11000, Cosmos 409, and SQLite’s UNIQUE constraint failed, which is the only signal Cloudflare D1 carries. The memory, DynamoDB and Bigtable adapters raise the class themselves. Numeric codes are read only under their own adapter, as for the conflict class. It is not retryable: the served detail says the conflicting write was rejected, never that it is safe to retry. The class carries the targeted entity when the failing repository call names one. At commit() a duplicate is the one class mapped, because the backends that detect it there (D1’s atomic batch, a Cosmos transactional batch, a DynamoDB TransactWriteItems whose cancellation reason sits on a create’s Put, a buffered memory or Bigtable create) apply nothing when they refuse; any other commit rejection is still rethrown unchanged.

Programmatic migrations answer 501 Not Implemented too. UnsupportedMigrationError names a distinct framework-capability refusal rather than pretending a migration is a raw query or a query shape. Every current adapter lacks programmatic migration support and delegates it to its own CLI, so the refusal is permanent and 501 is the honest response. Its hint carries a fixed sentence, never an operator-facing error message.

Not every UnsupportedQueryFeatureError is branded, and that is deliberate. The class is shared by two kinds of refusal: a caller-caused query shape, and a configuration refusal. Only the former is answered 501; the latter keeps the masked 500 that is correct for an internal fault. Branding the constructor unconditionally made a blank columnFamily — a value the developer wrote — answer every request 501 "Query feature 'mapping' is not supported by the 'bigtable' database adapter.", which is a lie twice over. The split is an allowlist of feature values (attribute-value, composite-key, cursor-pagination, key, nested-path, offset, order-by/orderBy, row-key, update); mapping, endpoint, date-encoding and transaction are excluded, and an unclassified value is not branded — so a feature name added later keeps its masked 500 until someone decides otherwise.

The four transaction and concurrency errors — MongoTransactionUnavailableError, CosmosTransactionScopeError, CosmosConcurrentModificationError and BigtableTransactionScopeError — are deliberately not branded and keep their masked 500: they may legitimately quote backend state, and a concurrency conflict is transient and retryable rather than permanent, which is a different contract statement deserving its own decision.

Transactional outbox store (M107)

createDatabaseOutboxStore(options?) returns a RegistryFactory<IOutboxStore> — the shipped implementation of the IOutboxStore port in @setu-ts/common over IDatabaseService (the M101c createDatabaseTenantDataStore shape). It is passed to the messaging plugin’s outbox.store option, which resolves it in onInit and runs verify() there.

import { createDatabaseOutboxStore } from '@setu-ts/database-plugin';

const store = createDatabaseOutboxStore({ entity: 'Outbox', database: 'orders' });

• Discriminator. Every row carries kind: 'setu-outbox' (OUTBOX_RECORD_KIND); every read (scanPending, failedKeys, stats, purge) requires it, and a lookup by id before a transition treats a row of another kind as missing.
• Conditional transitions. claim(id, { claimVersion, leaseUntil }) requires kind, pending and the read version, increments it by one and sets the lease. markSent/markFailure require the held version, including deleteNow through deleteWhere; a pending version miss is claim-lost. Status misses are not-pending or not-failed; another kind is missing. markInvalid(id, now) uses only kind/status, writes failed/invalid-row, clears the lease and preserves attempts. markFailure and release('retry') clear the lease; release preserves the version. Unexplained misses retry at most three rounds. Native conditional writes are required; no fallback remains. sentBy is only an operator diagnostic, absent from outcomes.
• Columns. The row is the record’s own fields; an absent optional field is written as null and read back as absent. failedKeys selects only tenantId and orderingKey; purge deletes sent then discarded rows with settledAt < before, at most limit per status.
• verify() runs scanPending(undefined, 1), then transaction(uow => uow.getRepository(entity).findAll({ where: { kind, status: 'pending' }, limit: 1 })), then updateWhere('setu-outbox-claim-probe', { kind, status: 'pending', claimVersion: -1 }, { claimVersion: 0 }) and deleteWhere with the same id and predicate — both, because retainSentMs: 0 deletes a sent row conditionally after it is published. No row can carry version -1 (append writes 0 and a claim only increments), so neither probe writes, even to a row appended under the probe id. The old SQL schema without claim_version is refused at the first step, the relay query. A conditional-write refusal is conditional-writes-unsupported. An UnsupportedQueryFeatureError from bigtable is 'bigtable'; one from dynamodb for orderBy is 'dynamodb-index' (a GSI { partitionKey: 'status', sortKey: 'position' }, projection ALL, is required); a cause chain carrying code: 20 with codeName: 'IllegalOperation' — what a standalone MongoDB answers at the first operation inside a transaction — is 'mongodb-replica-set'; anything else is 'entity-unavailable'. On memory and MongoDB a missing entity cannot be detected (both create lazily). Every refusal is a rejected promise.

Consumer inbox store (M108)

createDatabaseInboxStore(options?) returns a RegistryFactory<IInboxStore> — the shipped implementation of the IInboxStore port in @setu-ts/common over IDatabaseService. It is passed to the messaging plugin’s inbox.store option, which resolves it in onInit and runs verify() there.

import { createDatabaseInboxStore } from '@setu-ts/database-plugin';

const store = createDatabaseInboxStore({ entity: 'Inbox', database: 'orders' });

• run opens one transaction, creates the marker FIRST, then runs the work with the unit of work; any rejection rolls both back. A duplicate marker id rejects (the adapter’s DuplicateKeyError, or a write conflict on a MongoDB replica set).
• Discriminator. Every row carries kind: 'setu-inbox' (INBOX_RECORD_KIND); every read (find, parked, stats, purge) requires it, and a row of another kind is missing.
• Conditional writes. recordFailure compares kind and the read attempts value in the write, retrying misses at most five rounds; release requires kind and status: 'parked'. Without conditional support, or for a non-safe-integer count, the two-call fallback can lose an increment under concurrent failures.
• verify() refuses Cosmos DB and Bigtable by adapter arm or class, runs purge(0, 1), then a transaction that creates two probe rows and always rolls back: a BigtableTransactionScopeError at the second row is 'transaction-scope', a cause chain carrying code: 20 with codeName: 'IllegalOperation' is 'mongodb-standalone', anything else 'entity-unavailable'. Nothing the probe writes survives.

Scoped RBAC sources (M110b)

createDatabaseGrantSource(options) and createDatabaseRoleSource(options) return RegistryFactory values for AuthPlugin’s scopedRbac option — the grant source for a { kind: 'custom', source } arm and the role source for customRoles — resolved in AuthPlugin’s onInit, so DatabasePlugin may be registered in either order. Both read the default CAPABILITIES.DATABASE service through the repository surface and portable FilterExpressions, so they run on every adapter; no SQL is written and no value is interpolated.

import { AuthPlugin } from '@setu-ts/auth-plugin';
import { createDatabaseGrantSource, createDatabaseRoleSource } from '@setu-ts/database-plugin';

const auth = AuthPlugin({
  rbac: { roles: { approver: { permissions: ['invoices:approve'] } } },
  scopedRbac: {
    sources: [{ kind: 'custom', source: createDatabaseGrantSource({ entity: 'role_grants' }) }],
    customRoles: createDatabaseRoleSource({ entity: 'tenant_roles' }),
  },
});

A grant row whose scopeType and scopeId are both null is a GLOBAL grant; a row with only one null is passed through and dropped by AuthPlugin’s validator. A chain question is ONE query — the subject, and either a global row or a row in one of the asked scopes; an all question (sign-in timing) reads every row of the subject. Each question reads at most limit + 1 rows, and more than limit matching rows REJECT it — the check then denies — rather than returning an arbitrary subset, which would under-grant unpredictably; AuthPlugin’s own maxGrantsPerPrincipal bounds the union afterwards. The role source groups rows into one definition per (scope, role) and skips a row missing any column. Every field name must be an identifier ([A-Za-z_][A-Za-z0-9_]*), so it can never be read as an operator; an empty entity, a non-identifier field, or an out-of-range limit throws TypeError when the factory is called. A query does not start once the evaluator’s deadline has passed. Verified against real PostgreSQL (Drizzle) and MongoDB.

Multiple Databases

// Each named connection injects its own application-generated Prisma client;
// `options.url` is deprecated and unread — a v7 client carries its own
// connection configuration.
app.register(
  DatabasePlugin({
    type: 'prisma',
    name: 'primary',
    options: { prismaClient: primaryPrismaClient },
  }),
);

app.register(
  DatabasePlugin({
    type: 'prisma',
    name: 'analytics',
    options: { prismaClient: analyticsPrismaClient },
  }),
);

// Access by name
app.router.get('/analytics', async (ctx) => {
  const primaryDb = ctx.services.get<IDatabaseService>('database.primary');
  const analyticsDb = ctx.services.get<IDatabaseService>('database.analytics');
  // ...
});

AuthPlugin() (@setu-ts/auth-plugin)

RedisRateLimitStore.increment/reset wrap recognised connection faults in RateLimitStoreUnavailableError, preserving cause. With errorHandler, clients receive 503 and Rate limiting is temporarily unavailable. Other errors propagate unchanged. The constructor’s commandTimeoutMs defaults to 15000, accepts 0–2147483647, and throws RangeError for invalid values including NaN. Zero omits ioredis’s bound; an injected client keeps its own settings. Configure a larger bound when necessary.

Provides JWT and API-key authentication, local credential verification, RBAC authorization with role hierarchy, and short-circuiting route guards. All cryptography (HS256/RS256 JWT, PBKDF2-SHA256 password hashing) runs through Web Crypto via IRuntimeServices, so no npm package is involved in issuing or verifying a token, or in hashing a password. The package declares one optional driver — RedisRateLimitStore lazy-loads ioredis — which nothing imports unless that store is constructed.

Registers authentication under the existing capability token, JWT only when configured, and authorization when RBAC is configured:

• IJwtService under CAPABILITIES.JWT ('jwt') — sign/verify/decode JWTs, only when jwt is supplied.
• IAuthService under CAPABILITIES.AUTH ('authentication') — passive strategy chain + login.
• IAuthorizationService under CAPABILITIES.AUTHORIZATION ('authorization') — RBAC checks, only when rbac is supplied.
• IAuthorizationPolicyService under CAPABILITIES.AUTHORIZATION_POLICIES ('authorization-policies') — asynchronous, target-aware policy checks (M110a), ALWAYS registered, holding the policies option’s definitions and any class-form policies DecoratorPlugin registers.

JWT time boundaries (M113m). The first-party JwtService.verify, exposed as IJwtService, uses fractional seconds (runtime.now() / 1000) without clock tolerance. It rejects with Token expired once now >= exp, and with Token not yet valid while now < nbf: the not-before boundary is inclusive, and the expiry boundary is exclusive. Previously, a token could remain accepted for up to one second after exp; refresh before exp. The outside-issuer verifier (issuers) uses fractional seconds with clockToleranceSec: expiry is refused once now >= exp + clockToleranceSec (previously >), and not-before is refused while now + clockToleranceSec < nbf (unchanged).

Authorization policies (M110a). definePolicy({ name, abilities, before? }) validates a policy (lowercase kebab-case name, at least one ability, no ability named before) and returns a frozen copy typed by its ability names; register it through AuthPlugin({ policies }), which refuses a malformed policy or a duplicate name when AuthPlugin(...) is called. An ability is a check (principal, target) => boolean | Promise<boolean>, or { anonymous: true, check } to be called with null for an anonymous request. The rules are fixed: an unknown policy or ability REJECTS with UnknownPolicyError; an anonymous principal is denied (401) before a non-anonymous check runs; for a signed-in principal before runs first — true allows, undefined falls through, anything else (null included) denies; only a literal true allows; and a throw or rejection from before or the check denies and is logged once at error with the policy, ability, hook and serialized error — never the target or the principal. requirePolicy(policy, ability, target?) is the route guard: 501 with no policy service, 401 when an anonymous request is denied, 403 when a signed-in principal is denied, otherwise next(); target is a value or an extractor (ctx) => T | undefined | Promise<T | undefined> (a function is ALWAYS treated as an extractor), and an extractor’s throw propagates unchanged. An anonymous request to an ability that needs a principal is refused 401 BEFORE the extractor runs, so it costs no lookup and cannot learn from the extractor whether a record exists. Whether the ability needs a principal is read from the REGISTERED policy on each request, never from the guard’s own policy object, so a guard the startup scan never saw (a route added after start(), a global middleware) behaves the same; a guard naming an unregistered policy or ability rejects without running the extractor. An undefined principal passed to can/authorize is anonymous, exactly like null. A policy or ability name longer than 128 characters is truncated in an UnknownPolicyError’s message and fields, with the removed length noted. It is branded for OpenAPI deriveSecurity as authenticated unless the ability is anonymous; the brand is fixed from the guard’s own policy object when the guard is built, which the startup scan proves agrees with the registered policy only for routes present at start(). The service’s can resolves a boolean and authorize rejects a denial with AuthorizationDeniedError, which carries a 401/403 status hint whose title and detail are the guards’ own, so under errorHandler a thrown denial answers the guard’s exact body (without errorHandler the kernel answers 500). AuthPlugin’s onBootstrap hook scans every registered route and fails start() when a requirePolicy guard names a policy or ability that is not registered, or one whose registered ability disagrees with the guard’s policy object on anonymous (a different policy registered under the same name); it then SEALS the registry, so define after start() throws. Not scanned: a route added after start() and a guard added as global middleware — an unknown name there rejects per request (fail closed). A policy is identified by its NAME. See Authorization.

Scoped RBAC (M110b). scopedRbac (requires rbac) grants a catalogue role IN a scope — a ScopeRef { type, id } naming a tenant, organisation, team or region — rather than everywhere. AuthPlugin defines ONE built-in policy, SCOPED_RBAC_POLICY ('scoped-rbac', a reserved name an application policy may not take), on the M110a evaluator: every catalogue permission is an ability perm:<permission> and every catalogue role an ability role:<role>, and the target is a ScopedRbacTarget { scope, context? } — so no new capability token is added and the M110a rules (only true allows, 401 before the check for an anonymous request, a throw denies) apply unchanged. The wildcard * is never an ability. requireScopedRole(role | roles, { scope? }) is any-of and requireScopedPermission(permission | permissions, { scope? }) is all-of; scope is a ScopeSource — scopeFromTenant() (the default: the resolved ctx.request.tenant), scopeFromParam(param, type), a fixed ScopeRef, null (global grants only) or a function. Both guards answer 501 with no policy service, 401 anonymous BEFORE the scope source runs, 403 on a deny, and are refused at start() by the M110a scan when they name a permission or role outside the catalogue — so a typo is a startup error, never a silent 403. Grants come from sources, UNIONED: { kind: 'static', grants }, { kind: 'claims', map }, and { kind: 'custom', source } (any IGrantSource, or a RegistryFactory resolved at onInit, which is how createDatabaseGrantSource plugs in); one source that rejects, throws or exceeds sourceTimeoutMs DENIES the whole check (fail closed), logged with the source name, the scope TYPE and the error class only — never an id, a principal or a message. A grant applies in its own scope and, through inheritsFrom(scope, signal), in every scope that inherits from it (child requests inherit parent grants, never the reverse); the walk is depth-first with cycle refusal and the maxScopeDepth / maxScopeNodes bounds, any of which denies. A null-scope grant is global unless grantableIn[role] restricts the role to scopeTypes (and global: false, the default). Only grants decide (M113e, V9-28): the roles and permissions a principal carries itself count in no scope unless principalAuthorityIsGlobal: true, which turns each principal role into a global grant (still subject to grantableIn) and lets each principal permission, '*' included, satisfy every scoped permission check — the behaviour before 0.10.0. A non-boolean value is refused at AuthPlugin(...). The unscoped guards are unaffected. Tenant consistency: a check whose OWN scope has tenantScopeType (default 'tenant') and names a tenant other than the resolved request tenant denies — a route parameter cannot reach outside the caller’s tenant. That comparison needs the request: the guards and decorators pass it, and a direct policies.can(...) call made while serving a request must pass it as the target’s context — without it the scope is checked against the grants alone. Per-scope custom roles (customRoles, an IScopedRoleSource) bundle CATALOGUE permissions only, resolve against the roles defined in the grant’s OWN scope, cannot shadow a catalogue role, and are checked through permissions — a guard naming a custom role is refused at startup. timing decides revocation latency for static and custom sources: 'request' (default; memoised per request), { kind: 'cache', ttlMs, maxEntries } (an LRU on the monotonic clock with in-flight coalescing; up to ttlMs) and 'sign-in' (requires signIn; resolved once by IAuthSessionService.signIn, stored under a PRIVATE session key — never in claims, so a token carrying a same-named claim grants nothing — carried through a pending second factor, and in force until sign-out or session expiry; a source failure rejects sign-in with GrantResolutionError, a 503 status hint). A custom source is handed only the principal’s id and iss claim — the fields its shared answer is keyed by — never other claims, roles or permissions. A claims source is mapped on every check from the credential being checked and is never memoised, cached or coalesced, because two tokens for one principal can carry different claims (under 'sign-in' it is mapped once, from the credential that signed in). Every bound refuses an out-of-range value, NaN included, when AuthPlugin(...) is called. Scoped decisions are NOT observed by M98h authorizationDiagnostics — its collector watches only the global RBAC evaluator — so no scope identifier reaches the diagnostics connector. See Authorization.

jwt and rbac are optional. At least one passive strategy must come from jwt, issuers, apiKey, session, or strategies; local alone cannot recognize a later request. A JWT-only registration provides jwt and authentication; it deliberately does not register an authorization service.

What the guards then do (M89b, X18-2). requireAuth(), publicRoute(), and M100d’s requireMfa() resolve nothing and are unaffected: requireMfa() asks only whether the authenticated principal carries otp or pop in claims.amr, which needs no RBAC configuration. The four authorization guards — requireRole, requirePermission, requireAnyRole and requireAllPermissions — answer 501 Not Implemented with Authorization is not configured, short-circuiting before the handler. The status is 501 rather than 403 because nothing is wrong with the caller: the deployment cannot evaluate the policy at all, and the condition is permanent for that deployment. A principal that genuinely fails a policy check still gets 403; that path is unchanged. Before M89b these four resolved the capability unconditionally, so the registry’s throw escaped into the pipeline and the caller received a masked 500 Internal Server Error — a real fault with /health, /ready and /live all reporting up. They still fail closed either way; what changed is that the refusal is legible.

Session authentication and caller-supplied strategies (M73): session takes a SessionAuthOptions whose single required member, toPrincipal(view), maps the opened SessionView to the principal it carries — returning null continues the chain. When present, the plugin appends an internal SessionStrategy after the API-key strategy and requires the session capability (SessionPlugin) to be registered, or register() throws naming both plugins. strategies accepts caller-supplied IAuthStrategys, appended after every built-in in declaration order; a name colliding with any other strategy in the assembled chain throws at register(). The assembled order is fixed — jwt → api-key → session → caller-supplied — and the first non-null principal wins, so a request carrying both a bearer header and a session cookie authenticates by the JWT.

Tokens from an outside issuer (M100b): jwt verifies tokens this application issued; issuers: readonly TrustedIssuer[] verifies access tokens an outside identity provider issued, against its published key set. Each entry is { name, issuer, audience, keys: { jwksUri } | { discovery: true }, algorithms?, clockToleranceSec?, keySet?, toPrincipal } — audience and toPrincipal required. The internal issuers strategy runs immediately after the JWT strategy, reading the same header and scheme; the chain is jwt → issuers → api-key → session → caller-supplied. A token’s iss is read unverified only to select the entry whose issuer equals it exactly. none and HS* are refused before key lookup; keys are filtered by kty/crv/use/alg/key_ops/kid; RS256, PS256, ES256, ES384 and EdDSA (Ed25519) verify through runtime.subtle with zero npm dependencies. iss exact, aud contains audience, exp required, exp/nbf/future iat within clockToleranceSec (default 30, max 300). Expiry is refused at now >= exp + clockToleranceSec; not-before is refused while now + clockToleranceSec < nbf. Key sets are cached on the monotonic clock (keySet.ttlMs 10 min), an unknown kid refetches at most once per keySet.minRefreshIntervalMs (60 s) with concurrent refetches coalesced, the last good set survives fetch failures for keySet.maxStaleMs (24 h) and is then dropped, and each fetch is bounded by keySet.fetchTimeoutMs (5 s), 64 KiB and 64 keys. Every refusal — duplicate name or issuer, empty audience, unsupported algorithm, out-of-range tolerance or timing, a keySet.ttlMs above keySet.maxStaleMs, http without issuers or signIn, non-https non-loopback URL — throws AuthPluginConfigurationError from AuthPlugin(...). http?: IAuthHttp replaces the default fetch seam. The auth health indicator stays up with data.current: boolean and data.issuers carrying per-issuer stale/expired/unfetched states. It performs no I/O. typ: at+jwt (RFC 9068) is not enforced (only a Keycloak typ: "ID" claim is refused), so the API needs an audience distinct from any sign-in client id; multi-tenant Entra ID is not supported. IJwtService remains self-issued only. sub is unique only within its issuer, so whenever an issuer is not the only identity source — another issuer, a self-issued jwt (whose strategy also maps sub to the id), an API key, a session or a custom strategy — toPrincipal should namespace the id (`${claims.iss}|${claims.sub}`) — and every other source too (or keep their ids free of the separator), since namespacing one side does not stop a local id of the same form colliding. keySet.fetchTimeoutMs may not exceed 2147483647, since a larger timer delay overflows.

Sign-in with an outside provider (M100c): signIn: SignInConfig — { basePath?: string (default '/auth'), providers: readonly SignInProvider[], refreshPrincipal? } — makes the application an OAuth 2.0 / OpenID Connect relying party over the authorization-code flow. It requires SessionPlugin (register() throws naming both plugins otherwise), adds CAPABILITIES.AUTH_SESSION to provides and registers the plugin’s IAuthSessionService there, and appends an internal auth-session strategy after the session strategy (chain jwt → issuers → api-key → session → auth-session → caller-supplied) which returns the stored principal with claims.amr set to the recorded methods, overwriting any amr the principal carried. SignInProvider is a union discriminated on kind: OidcProvider (issuer; endpoints and keys from the same issuer-checked discovery document M100b uses; scopes must contain openid; optional rpInitiatedLogout: { postLogoutRedirectUri, idTokenHint?: true }) and OAuth2Provider (authorizationEndpoint, tokenEndpoint, userinfoEndpoint). Both share name (kebab-case), clientId, clientSecret?, tokenEndpointAuth? ('client_secret_basic' — the default with a secret — 'client_secret_post' or 'none'), scopes?, redirectUri (its path must end with <basePath>/<name>/callback; a leading mount prefix is allowed), failureRedirect? (same-origin path), toPrincipal(claims) and onTokens?(tokens: ProviderTokens). Routes: GET <basePath>/<name>/login, GET <basePath>/<name>/callback, and one POST <basePath>/logout. Login stores { state, provider, verifier, nonce?, returnTo, createdAt } in the user’s session (at most 3, 10-minute lifetime), sends PKCE S256 for every provider and never response_mode, and answers 503 provider-unavailable when discovery cannot be read. returnTo is kept only as a same-origin path of at most 256 bytes after percent-encoding non-ASCII (else /) and is never read from the callback URL. The callback refuses with 401 (or a failureRedirect?error=<code> redirect) and one of the fixed codes provider-denied, state-invalid (unknown, replayed, expired, another provider’s, or an RFC 9207 iss naming another issuer), exchange-failed and profile-unavailable, through respondWithError; toPrincipal returning null or throwing answers 403 principal-refused. The attempt is consumed before the exchange. The ID token is verified by the M100b verifier with audience = clientId, plus iss === issuer, nonce equality and, for several audiences, azp === clientId. Discovered endpoints must be https (or loopback http) and printable ASCII — an endpoint with a space, control character or non-ASCII code point answers the login 503 and drops RP-initiated logout to a local one — and the oauth2 userinfo read sends the access token as Authorization: Bearer. On success the callback calls IAuthSessionService.signIn(ctx, principal, { methods: ['fed'] }) (session id regenerated), hands the tokens to onTokens (a throwing onTokens does not undo the sign-in), and redirects to the stored returnTo. Logout calls signOut and redirects to /, or — for the one provider allowed to set rpInitiatedLogout, and only when the session signed in through it (IAuthSessionService.signIn clears that marker) — to its end_session_endpoint with client_id, post_logout_redirect_uri and, only when idTokenHint: true stored one, id_token_hint. refreshPrincipal(stored) re-reads the principal per request (null or a throw → anonymous). What signOut revokes depends on the session strategy: the store strategy deletes the entry, the default cookie strategy leaves a copied cookie valid until its maxAge. A sameSite: 'strict' session cookie is not sent on the provider’s redirect, so every callback fails closed as state-invalid. Every configuration refusal throws AuthPluginConfigurationError from AuthPlugin(...).

Phasing (M16b, shipped): refresh tokens and rate limiting shipped in M16b as standalone additions — RefreshTokenService (app-instantiated; NOT an IAuthStrategy, since a refresh token arrives in the request body, not as a passive header credential) and rateLimitMiddleware (a decoupled middleware factory with no capability token). Neither is an AuthPlugin option. IJwtService still exposes only sign/verify/decode — a refresh token is a signed JWT carrying type: 'refresh' and a jti.

Session and account lifecycle (M124, 0.11.0): signIn.providers may be empty with neither mfa nor passkeys — a password-only sign-in that registers CAPABILITIES.AUTH_SESSION, the auth-session strategy and the logout route only; a non-array providers still throws AuthPluginConfigurationError. signIn.sessionStamp?: SessionStamp, where SessionStamp = (principal: IPrincipal) => string | null | Promise<string | null>, is read once by IAuthSessionService.signIn before any write (a throw, or a value other than a string or null, rejects signIn and records nothing); its base64url SHA-256 digest (or null) is stored as stamp in the signed-in record, or in the pending second-factor record and copied on promotion. On every request the auth-session strategy resolves the principal (snapshot or refreshPrincipal), calls sessionStamp with it, and compares digests in constant time; a mismatch, a throw or a malformed value makes the request anonymous. A record without stamp reads as null, which matches only a user whose stamp is null. The plugin’s passkey registration routes admit through the same re-checks (refreshPrincipal, then the stamp), so a session either has ended cannot enrol a credential; IAuthSessionService.current(ctx) remains the synchronous, un-re-checked snapshot. A non-function sessionStamp throws AuthPluginConfigurationError from AuthPlugin(...). No API bumps the stamp: the application changes it on its own user record. requireAuth(options?: RequireAuthOptions), RequireAuthOptions = { readonly signInPage?: string }: without options, unchanged. With signInPage (a same-origin absolute path that safeReturnTo keeps unchanged, else AuthPluginConfigurationError when the guard is built), an unauthenticated GET/HEAD that is not X-Requested-With: XMLHttpRequest and carries Sec-Fetch-Mode: navigate (or, without that header, an Accept naming text/html or application/xhtml+xml) is answered 302 to signInPage with returnTo=safeReturnTo(path + query) added to its query; every other unauthenticated request, and a request for signInPage’s own path, gets the existing 401. Both unauthenticated answers append Accept, Sec-Fetch-Mode and X-Requested-With to Vary. safeReturnTo(value: string | undefined, fallback = '/'): string is exported unchanged: it returns value when it is a single-leading-slash path with no \, no control character and at most 256 bytes after non-ASCII characters are percent-encoded (the encoded form), else fallback.

Exports