@relaybus/core 0.0.0 → 0.2.0

package/dist/index.d.cts

@@ -14,71 +14,6 @@ declare function toMilliseconds(value: Duration, name: string): number;
 /** Largest delay Node.js timers support. Longer values fire after 1ms instead. */
 declare const MAX_TIMER_DELAY_MS = 2147483647;
 
-/**
- * Base class of every error thrown by relaybus.
- */
-declare class RelayBusError extends Error {
-    name: string;
-}
-/** Invalid options passed to a relaybus component. */
-declare class ConfigurationError extends RelayBusError {
-    name: string;
-}
-/**
- * Thrown by `publish` when no transaction can be found and the bus runs with
- * `transactionMode: 'required'` (the default). Publishing outside a transaction
- * would reintroduce the dual-write problem the outbox exists to prevent.
- */
-declare class TransactionRequiredError extends RelayBusError {
-    name: string;
-}
-/**
- * Throw from a handler to dead-letter the delivery immediately, skipping the
- * remaining retry attempts.
- */
-declare class NonRetryableError extends RelayBusError {
-    name: string;
-}
-/** A payload failed its event schema. Never retried: the payload will not change. */
-declare class EventValidationError extends NonRetryableError {
-    readonly issues: readonly ValidationIssue[];
-    name: string;
-    constructor(message: string, issues: readonly ValidationIssue[]);
-}
-/**
- * A message received from a broker is not a valid event. Never retried:
- * transports should dead-letter it instead of redelivering it forever.
- */
-declare class InvalidEnvelopeError extends NonRetryableError {
-    name: string;
-}
-/** The worker no longer owns the delivery it was processing. */
-declare class LeaseLostError extends RelayBusError {
-    name: string;
-}
-/** A handler did not settle within its configured timeout. Retried like any failure. */
-declare class HandlerTimeoutError extends RelayBusError {
-    name: string;
-}
-/**
- * Reason of a handler's abort signal when the bus stops before the handler
- * finished. The delivery is released and runs again without losing an attempt.
- */
-declare class DispatcherStoppedError extends RelayBusError {
-    name: string;
-}
-interface ValidationIssue {
-    readonly message: string;
-    readonly path?: readonly PropertyKey[] | undefined;
-}
-/** Serializable snapshot of an error, stored with failed deliveries. */
-interface ErrorInfo {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string | undefined;
-}
-declare function toErrorInfo(error: unknown): ErrorInfo;
-
 /**
  * The Standard Schema interface (https://standardschema.dev), copied as the
  * specification recommends so relaybus needs no runtime dependency. Zod,
@@ -151,35 +86,459 @@ interface EventClass<TPayload = unknown> {
     readonly type: string;
     readonly schema: StandardSchemaV1<unknown, TPayload> | undefined;
 }
-/** Payload type of an event class: `PayloadOf<typeof OrderPlaced>`. */
-type PayloadOf<TEvent> = TEvent extends EventClass<infer TPayload> ? TPayload : never;
-/** Anything that names an event type: an event class or the type string itself. */
-type EventReference = {
-    readonly type: string;
-} | string;
-interface DefineEventOptions<TSchema extends StandardSchemaV1> {
-    /** Validates the payload on publish and before every handler call. */
-    readonly schema: TSchema;
+/** Payload type of an event class: `PayloadOf<typeof OrderPlaced>`. */
+type PayloadOf<TEvent> = TEvent extends EventClass<infer TPayload> ? TPayload : never;
+/** Anything that names an event type: an event class or the type string itself. */
+type EventReference = {
+    readonly type: string;
+} | string;
+interface DefineEventOptions<TSchema extends StandardSchemaV1> {
+    /** Validates the payload on publish and before every handler call. */
+    readonly schema: TSchema;
+}
+declare function assertEventType(type: string): void;
+/**
+ * Defines an event type. Extend the returned class to name it:
+ *
+ * ```ts
+ * export class OrderPlaced extends defineEvent<{ orderId: string }>('order.placed.v1') {}
+ * export class OrderShipped extends defineEvent('order.shipped.v1', { schema: orderShippedSchema }) {}
+ * ```
+ */
+declare function defineEvent<TSchema extends StandardSchemaV1>(type: string, options: DefineEventOptions<TSchema>): EventClass<StandardSchemaV1.InferOutput<TSchema>>;
+declare function defineEvent<TPayload>(type: string): EventClass<TPayload>;
+/** Runs a Standard Schema and returns its output, or throws {@link EventValidationError}. */
+declare function validatePayload<TPayload>(type: string, schema: StandardSchemaV1<unknown, TPayload> | undefined, payload: unknown): Promise<TPayload>;
+
+/**
+ * How the delay between attempts is randomized.
+ * - `full`: uniform in [0, delay]. Spreads retries the most (AWS recommendation).
+ * - `equal`: uniform in [delay / 2, delay].
+ * - `none`: exactly `delay`. Synchronized retries can stampede a recovering dependency.
+ */
+type JitterStrategy = 'full' | 'equal' | 'none';
+interface RetryPolicyOptions {
+    /**
+     * Total attempts including the first one. Default 10 for handlers, which
+     * gives up after roughly 17 minutes of failures with the default delays.
+     * `Infinity` retries until the delivery succeeds.
+     */
+    readonly attempts?: number;
+    /** Delay before the second attempt. Default `'1s'`. */
+    readonly initialDelay?: Duration;
+    /** Growth factor of the delay per attempt. Default 2. */
+    readonly factor?: number;
+    /** Upper bound of a single delay. Default `'10m'`. */
+    readonly maxDelay?: Duration;
+    /** Default `'full'`. */
+    readonly jitter?: JitterStrategy;
+    /** Return false to dead-letter an error without retrying it. */
+    readonly retryIf?: (error: unknown) => boolean;
+}
+interface RetryPolicy {
+    readonly attempts: number;
+    readonly initialDelayMs: number;
+    readonly factor: number;
+    readonly maxDelayMs: number;
+    readonly jitter: JitterStrategy;
+    readonly retryIf: ((error: unknown) => boolean) | undefined;
+}
+/** Default policy of handlers. */
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Default policy of routes to transports: a broker outage must only delay
+ * events, so routes retry until the broker accepts them, at most every 5 minutes.
+ */
+declare const DEFAULT_ROUTE_RETRY_POLICY: RetryPolicy;
+declare function createRetryPolicy(options: RetryPolicyOptions | undefined, base?: RetryPolicy): RetryPolicy;
+/**
+ * Delay before the next attempt after `failedAttempts` failures (1-based):
+ * capped exponential backoff with the policy's jitter.
+ */
+declare function computeRetryDelay(policy: RetryPolicy, failedAttempts: number, random?: () => number): number;
+declare function isRetryableError(policy: RetryPolicy, error: unknown): boolean;
+
+/** Passed to every handler call. */
+interface HandlerContext<TTransaction = unknown> {
+    readonly deliveryId: string;
+    readonly handler: string;
+    /** Attempt number, starting at 1. */
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    /** Aborted when the handler times out, the lease is lost or the bus stops. */
+    readonly signal: AbortSignal;
+    /**
+     * Transaction the delivery completes in, for handlers subscribed with
+     * `transactional: true`. Write through it to make the handler's effects and
+     * the completion atomic. Undefined otherwise.
+     */
+    readonly transaction: TTransaction | undefined;
+}
+type EventHandler<TPayload = unknown, TTransaction = unknown> = (event: EventEnvelope<TPayload>, context: HandlerContext<TTransaction>) => unknown;
+interface SubscribeOptions {
+    /**
+     * Stable id of the handler. Deliveries are recorded under it, so renaming it
+     * orphans pending deliveries. Letters, digits and `._:/-`.
+     */
+    readonly id: string;
+    /** Overrides the bus retry policy field by field. */
+    readonly retry?: RetryPolicyOptions;
+    /** Abort and retry when a call takes longer. `false` disables the bus default. */
+    readonly timeout?: Duration | false;
+    /** Maximum concurrent deliveries of this handler in this process. */
+    readonly concurrency?: number;
+    /**
+     * Run the handler inside a store transaction that also completes the
+     * delivery: its writes and the completion commit or roll back together,
+     * so a handler that writes only through `context.transaction` (or through
+     * events it publishes) takes effect exactly once.
+     *
+     * The lease is not renewed while the transaction is open. A transactional
+     * handler must finish within the lease duration (default 30s), or within its
+     * `timeout`, which extends the lease once to cover it; otherwise it is aborted.
+     */
+    readonly transactional?: boolean;
+}
+/** Public description of a registered handler or route. */
+interface HandlerDescriptor {
+    readonly id: string;
+    readonly eventType: string;
+    readonly retry: RetryPolicy;
+    readonly timeoutMs: number | null;
+    readonly concurrency: number | null;
+    readonly transactional: boolean;
+    /** True for routes that forward events to a transport. */
+    readonly forwardsToTransport: boolean;
+}
+
+/**
+ * An event class as a catalog stores it: any class created with `defineEvent`,
+ * whatever its payload type. Use {@link PayloadOf} to recover the payload.
+ */
+interface CatalogEventClass {
+    new (payload: never): DomainEvent;
+    readonly type: string;
+    readonly schema: StandardSchemaV1 | undefined;
+}
+/**
+ * The shape of a catalog: event classes by name. Create one with
+ * {@link defineCatalog}; the name of each entry becomes part of the handler
+ * method that consumes it (`OrderPlaced` is consumed by `onOrderPlaced`).
+ */
+interface Catalog {
+    readonly [eventName: string]: CatalogEventClass;
+}
+/** Names of the events of a catalog, as string literals. */
+type CatalogEventName<TCatalog extends Catalog> = Extract<keyof TCatalog, string>;
+/**
+ * Union of the event instances a catalog can publish, for example
+ * `OrderPlaced | OrderShipped`; with `TName`, only those of the named events.
+ */
+type CatalogEvents<TCatalog extends Catalog, TName extends keyof TCatalog = keyof TCatalog> = InstanceType<TCatalog[TName & CatalogEventName<TCatalog>]>;
+/**
+ * Envelope a handler receives for an event class:
+ * `EventOf<typeof OrderPlaced>` is `EventEnvelope<{ orderId: string }>`.
+ */
+type EventOf<TEvent> = EventEnvelope<PayloadOf<TEvent>>;
+/**
+ * Same as {@link HandlersOf} with a required list of events:
+ * `PartialHandlersOf<typeof OrderEvents, 'OrderPlaced'>` equals
+ * `HandlersOf<typeof OrderEvents, 'OrderPlaced'>`.
+ *
+ * ```ts
+ * class AuditHandlers implements PartialHandlersOf<typeof OrderEvents, 'OrderPlaced'> {
+ *   onOrderPlaced(event: EventOf<typeof OrderPlaced>) {}
+ * }
+ * ```
+ */
+type PartialHandlersOf<TCatalog extends Catalog, TName extends keyof TCatalog, TTransaction = unknown> = {
+    readonly [TKey in TName & string as `on${TKey}`]: (event: EventOf<TCatalog[TKey]>, context: HandlerContext<TTransaction>) => unknown;
+};
+/**
+ * Handler methods for the events of a catalog: one `on${EventName}` method per
+ * event, taking that event's envelope. A class that
+ * `implements HandlersOf<typeof OrderEvents>` fails to compile until it has a
+ * method with the right payload type for each event. `TName` narrows it to the
+ * events a service consumes, which is how a service handles part of a catalog
+ * shared between services:
+ *
+ * ```ts
+ * class BillingHandlers implements HandlersOf<typeof OrderEvents, 'OrderPlaced'> {
+ *   onOrderPlaced(event: EventOf<typeof OrderPlaced>) {}
+ * }
+ * ```
+ *
+ * `TTransaction` types `context.transaction` for transactional handlers.
+ */
+type HandlersOf<TCatalog extends Catalog, TName extends keyof TCatalog = keyof TCatalog, TTransaction = unknown> = PartialHandlersOf<TCatalog, TName, TTransaction>;
+/**
+ * Names of catalog events that an API call is limited to. Every name must be a
+ * key of the catalog, which the compiler checks; duplicates and an empty list
+ * are rejected at runtime with a {@link ConfigurationError}. Omitting the list
+ * means every event of the catalog.
+ */
+interface CatalogEventSelection<TName> {
+    readonly events?: readonly TName[];
+}
+/** Options of {@link defineCatalog}. */
+interface DefineCatalogOptions {
+    /**
+     * Name of the catalog, used in boot-check messages and as the default prefix
+     * of the handler ids that `subscribeCatalog` registers.
+     */
+    readonly name?: string;
+}
+/**
+ * Options of `RelayBus.subscribeCatalog`: {@link SubscribeOptions} for every
+ * handler of the catalog, and optionally the events to subscribe to. The plain
+ * `SubscribeCatalogOptions`, without a catalog, names no events, so it fits
+ * every catalog.
+ */
+type SubscribeCatalogOptions<TCatalog extends Catalog = Catalog, TName extends keyof TCatalog = string extends keyof TCatalog ? never : keyof TCatalog> = Omit<SubscribeOptions, 'id'> & CatalogEventSelection<TName> & {
+    /**
+     * Prefix of the handler ids, which become `${idPrefix}.on${EventName}`.
+     * Default: the catalog name, then the class name of the handlers object.
+     * Deliveries are recorded under these ids, so renaming them orphans pending
+     * deliveries.
+     */
+    readonly idPrefix?: string;
+};
+/** One event of a catalog together with the handler method that consumes it. */
+interface CatalogEntry {
+    /** Name under which the class was registered, for example `OrderPlaced`. */
+    readonly name: string;
+    readonly eventClass: CatalogEventClass;
+    /** Event type string, for example `order.placed.v1`. */
+    readonly type: string;
+    /** Expected handler method, for example `onOrderPlaced`. */
+    readonly handlerName: string;
+}
+/** What {@link describeCatalog} knows about a catalog. */
+interface CatalogDescription {
+    readonly name: string | undefined;
+    readonly entries: readonly CatalogEntry[];
+}
+/**
+ * Groups event classes into a catalog: the complete set of events one service
+ * or domain owns. The catalog is frozen and keeps its keys and classes in its
+ * type, which enables compile-time checks:
+ *
+ * ```ts
+ * export const OrderEvents = defineCatalog({ OrderPlaced, OrderShipped }, { name: 'OrderEvents' });
+ *
+ * class ShippingHandlers implements HandlersOf<typeof OrderEvents> {
+ *   onOrderPlaced(event: EventOf<typeof OrderPlaced>) {}
+ *   // Compile error until onOrderShipped is added.
+ * }
+ * ```
+ *
+ * Throws {@link ConfigurationError} for an empty catalog, an entry that is not
+ * an event class, a name that is not made of letters, digits and underscores,
+ * or two entries with the same event type.
+ */
+declare function defineCatalog<const TCatalog extends Catalog>(events: TCatalog, options?: DefineCatalogOptions): Readonly<TCatalog>;
+/**
+ * Describes a catalog created by {@link defineCatalog}. The description and its
+ * entries are frozen. Throws {@link ConfigurationError} for any other object,
+ * so a hand-written record cannot slip past the checks that rely on it.
+ */
+declare function describeCatalog(catalog: Catalog): CatalogDescription;
+/**
+ * The handler signature of one catalog event, written as a method so that its
+ * parameters are compared bivariantly: a handler may annotate its context as
+ * `HandlerContext<PoolClient>` and still satisfy it. {@link MatchingHandlers}
+ * restores the strict check of the event parameter.
+ */
+type BivariantHandler<TEvent> = {
+    handle(event: EventOf<TEvent>, context: HandlerContext): unknown;
+}['handle'];
+/**
+ * The shape {@link defineHandlers} constrains its handlers to: one method per
+ * selected event, with the context typed loosely enough for any transaction type.
+ */
+type HandlerShapeOf<TCatalog extends Catalog, TName extends keyof TCatalog> = {
+    readonly [TKey in TName & string as `on${TKey}`]: BivariantHandler<TCatalog[TKey]>;
+};
+/**
+ * Checks every key of `THandlers` against the selected events of a catalog:
+ * keys that are no handler of a selected event become `never`, and a handler
+ * whose event parameter does not accept the event's envelope becomes the
+ * expected signature, so the compiler reports the mismatch at that key.
+ */
+type MatchingHandlers<TCatalog extends Catalog, TName extends keyof TCatalog, THandlers> = {
+    readonly [TKey in keyof THandlers]: TKey extends `on${infer TEventName extends TName & string}` ? THandlers[TKey] extends (event: infer TEvent, ...rest: never[]) => unknown ? EventOf<TCatalog[TEventName]> extends TEvent ? THandlers[TKey] : (event: EventOf<TCatalog[TEventName]>, context: HandlerContext) => unknown : (event: EventOf<TCatalog[TEventName]>, context: HandlerContext) => unknown : never;
+};
+/**
+ * Declares the handlers of a catalog as an object: every event, or the events
+ * named in `options.events`. Compilation fails when a handler is missing,
+ * misnamed, extra (including a handler of an event that is not selected) or
+ * takes the wrong payload; the same checks run at runtime for callers without
+ * type checking. A handler may type its context with a transaction type, for
+ * example `HandlerContext<PoolClient>`.
+ *
+ * ```ts
+ * const handlers = defineHandlers(OrderEvents, {
+ *   onOrderPlaced: (event) => reserveStock(event.payload.orderId),
+ *   onOrderShipped: (event) => notify(event.payload.orderId),
+ * });
+ * bus.subscribeCatalog(OrderEvents, handlers, { idPrefix: 'fulfilment' });
+ *
+ * const billing = defineHandlers(
+ *   OrderEvents,
+ *   { onOrderPlaced: (event) => charge(event.payload.orderId) },
+ *   { events: ['OrderPlaced'] },
+ * );
+ * bus.subscribeCatalog(OrderEvents, billing, { events: ['OrderPlaced'] });
+ * ```
+ */
+declare function defineHandlers<TCatalog extends Catalog, THandlers extends HandlerShapeOf<TCatalog, TName>, const TName extends keyof TCatalog>(catalog: TCatalog, handlers: THandlers & MatchingHandlers<TCatalog, TName, THandlers>, options: {
+    readonly events: readonly TName[];
+}): THandlers;
+/** Without `events`, every handler of the catalog is required. */
+declare function defineHandlers<TCatalog extends Catalog, THandlers extends HandlerShapeOf<TCatalog, keyof TCatalog>>(catalog: TCatalog, handlers: THandlers & MatchingHandlers<TCatalog, keyof TCatalog, THandlers>, options?: {
+    readonly events?: undefined;
+}): THandlers;
+/**
+ * Maps every key of `THandlers` that is not a handler of the selected events
+ * of the catalog (default: all of them) to `never`.
+ */
+type NoExtraHandlers<TCatalog extends Catalog, THandlers, TName extends keyof TCatalog = keyof TCatalog> = {
+    readonly [TKey in Exclude<keyof THandlers, keyof HandlersOf<TCatalog, TName>>]: never;
+};
+
+/**
+ * What a service does with the events of a catalog:
+ * - `consume`: it handles them, so each needs a local handler.
+ * - `produce`: it publishes them for other services, so each needs a route to a transport.
+ */
+type CatalogRole = 'consume' | 'produce';
+/**
+ * The part of a catalog that one service consumes or produces, created with
+ * {@link consume} or {@link produce} and passed to the `catalogs` option of the
+ * bus (or `bus.registerCatalog`). `start()` then verifies the role for each
+ * declared event.
+ */
+interface CatalogDeclaration<TCatalog extends Catalog = Catalog, TName extends keyof TCatalog = keyof TCatalog> {
+    readonly catalog: TCatalog;
+    readonly role: CatalogRole;
+    /** Names of the declared events, in catalog order. */
+    readonly events: readonly Extract<TName, string>[];
+    /** The declared events with their types and handler methods, in catalog order. */
+    readonly entries: readonly CatalogEntry[];
+}
+/**
+ * Declares that this service consumes events of a catalog, typically one
+ * shared between services through a contracts package. `start()` fails unless
+ * every declared event has a local handler (`subscribeCatalog`, `subscribe`,
+ * `@EventConsumer`, `@Subscribe`); a route to a transport does not count.
+ * Without `events`, every event of the catalog is declared. Unknown names do
+ * not compile and are rejected at runtime with a {@link ConfigurationError}.
+ *
+ * ```ts
+ * new RelayBus({ store, catalogs: [consume(OrderEvents, { events: ['OrderPlaced'] })] });
+ * ```
+ */
+declare function consume<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogDeclaration<TCatalog, TName>;
+/**
+ * Declares that this service publishes events of a catalog for other services.
+ * `start()` fails unless every declared event has a route to a transport, so
+ * nothing is published without a destination; a local handler does not count.
+ * Combine it with {@link consume} for events the service also handles itself.
+ * Without `events`, every event of the catalog is declared.
+ *
+ * ```ts
+ * new RelayBus({
+ *   store,
+ *   transports: [kafka],
+ *   routes: [{ event: OrderPlaced, transport: 'kafka', destination: 'orders' }],
+ *   catalogs: [produce(OrderEvents, { events: ['OrderPlaced'] })],
+ * });
+ * ```
+ */
+declare function produce<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogDeclaration<TCatalog, TName>;
+
+/**
+ * Base class of every error thrown by relaybus.
+ */
+declare class RelayBusError extends Error {
+    name: string;
+}
+/** Invalid options passed to a relaybus component. */
+declare class ConfigurationError extends RelayBusError {
+    name: string;
+}
+/**
+ * Thrown by `publish` when no transaction can be found and the bus runs with
+ * `transactionMode: 'required'` (the default). Publishing outside a transaction
+ * would reintroduce the dual-write problem the outbox exists to prevent.
+ */
+declare class TransactionRequiredError extends RelayBusError {
+    name: string;
+}
+/**
+ * Throw from a handler to dead-letter the delivery immediately, skipping the
+ * remaining retry attempts.
+ */
+declare class NonRetryableError extends RelayBusError {
+    name: string;
+}
+/** A payload failed its event schema. Never retried: the payload will not change. */
+declare class EventValidationError extends NonRetryableError {
+    readonly issues: readonly ValidationIssue[];
+    name: string;
+    constructor(message: string, issues: readonly ValidationIssue[]);
+}
+/**
+ * A message received from a broker is not a valid event. Never retried:
+ * transports should dead-letter it instead of redelivering it forever.
+ */
+declare class InvalidEnvelopeError extends NonRetryableError {
+    name: string;
+}
+/** The worker no longer owns the delivery it was processing. */
+declare class LeaseLostError extends RelayBusError {
+    name: string;
+    /**
+     * Whether the store said so (a fenced write returned false). A worker that only noticed
+     * locally that its lease ran out may still own the delivery in the store and has to give it back.
+     */
+    readonly storeConfirmed: boolean;
+    constructor(message: string, options?: {
+        readonly storeConfirmed?: boolean;
+    });
+}
+/** A handler did not settle within its configured timeout. Retried like any failure. */
+declare class HandlerTimeoutError extends RelayBusError {
+    name: string;
 }
-declare function assertEventType(type: string): void;
 /**
- * Defines an event type. Extend the returned class to name it:
- *
- * ```ts
- * export class OrderPlaced extends defineEvent<{ orderId: string }>('order.placed.v1') {}
- * export class OrderShipped extends defineEvent('order.shipped.v1', { schema: orderShippedSchema }) {}
- * ```
+ * Reason of a handler's abort signal when the bus stops before the handler
+ * finished. The delivery is released and runs again without losing an attempt.
  */
-declare function defineEvent<TSchema extends StandardSchemaV1>(type: string, options: DefineEventOptions<TSchema>): EventClass<StandardSchemaV1.InferOutput<TSchema>>;
-declare function defineEvent<TPayload>(type: string): EventClass<TPayload>;
-/** Runs a Standard Schema and returns its output, or throws {@link EventValidationError}. */
-declare function validatePayload<TPayload>(type: string, schema: StandardSchemaV1<unknown, TPayload> | undefined, payload: unknown): Promise<TPayload>;
+declare class DispatcherStoppedError extends RelayBusError {
+    name: string;
+}
+interface ValidationIssue {
+    readonly message: string;
+    readonly path?: readonly PropertyKey[] | undefined;
+}
+/** Serializable snapshot of an error, stored with failed deliveries. */
+interface ErrorInfo {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string | undefined;
+}
+declare function toErrorInfo(error: unknown): ErrorInfo;
 
 /**
  * Lifecycle of one handler's delivery of one event.
  * `pending` (waiting or scheduled for retry) -> `processing` (leased by a worker)
  * -> `completed` | `pending` (retry) | `dead` (exhausted or non-retryable).
  * `dead` -> `pending` only through an explicit requeue.
+ *
+ * A completed delivery is deleted. `completed` records exist only in stores
+ * configured to keep a completion history (`retainCompleted` /
+ * `completionHistory`), where they are listed, counted and purged like before.
  */
 type DeliveryStatus = 'pending' | 'processing' | 'completed' | 'dead';
 declare const DELIVERY_STATUSES: readonly DeliveryStatus[];
@@ -205,6 +564,11 @@ interface AppendResult {
  * Lease expiry is compared with the `now` the caller passes, taken from the
  * bus clock. Keep worker clocks synchronized (NTP): a skew larger than a third
  * of the lease duration lets another worker reclaim a delivery that is still running.
+ *
+ * Stores may grant the lease on a group of deliveries (a lane) instead of on
+ * each delivery. The group is exclusive to `leaseOwner` while the lease is
+ * live, so other owners do not see its pending deliveries until it expires or
+ * is relinquished; every delivery of the group carries the group's fencing token.
  */
 interface ClaimRequest {
     /** Only deliveries of these handlers are claimed. */
@@ -292,14 +656,18 @@ interface EventStore<TTransaction = unknown> {
      * Leases up to `limit` deliveries that are due: pending with `availableAt <= now`,
      * or processing with an expired lease. A keyed delivery is only claimable when
      * no earlier delivery of the same handler and key is pending or processing.
-     * Increments the attempt count. Safe to call from many processes at once.
+     * Counts the attempt (`attempt` of the result; a store may persist the count
+     * only when the attempt fails or its lease is lost). Safe to call from many
+     * processes at once.
      */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
     /** Extends a lease the caller still holds. Returns false when the lease was lost. */
     extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
     /**
-     * Marks a leased delivery completed. With `transaction` the change commits
-     * together with the handler's own writes. Returns false when the lease was lost.
+     * Marks a leased delivery completed by deleting it (or moving it to the
+     * completion history, when the store keeps one). With `transaction` the change
+     * commits together with the handler's own writes. Returns false when the lease
+     * was lost.
      */
     complete(lease: LeaseReference, now: Date, transaction?: TTransaction): Promise<boolean>;
     /** Returns a leased delivery to pending, due at `availableAt`. */
@@ -309,6 +677,14 @@ interface EventStore<TTransaction = unknown> {
      * now, attempts decremented. Used when a handler is aborted at shutdown.
      */
     release(lease: LeaseReference, now: Date): Promise<boolean>;
+    /**
+     * Marks many leased deliveries completed with one round trip. Returns, for
+     * every lease in the same order, whether it was completed (false: lease lost
+     * or already finished). Each lease is fenced individually, exactly as in
+     * {@link EventStore.complete}. Optional: the dispatcher falls back to
+     * `complete` when a store does not implement it.
+     */
+    completeMany?(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
     /** Moves a leased delivery to dead. */
     bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
     listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
@@ -316,109 +692,23 @@ interface EventStore<TTransaction = unknown> {
     requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
     purge(request: PurgeRequest): Promise<PurgeResult>;
     statistics(now: Date): Promise<EventStoreStatistics>;
-    /** Releases connections the store opened itself. */
-    close?(): Promise<void>;
-}
-
-/**
- * How the delay between attempts is randomized.
- * - `full`: uniform in [0, delay]. Spreads retries the most (AWS recommendation).
- * - `equal`: uniform in [delay / 2, delay].
- * - `none`: exactly `delay`. Synchronized retries can stampede a recovering dependency.
- */
-type JitterStrategy = 'full' | 'equal' | 'none';
-interface RetryPolicyOptions {
-    /**
-     * Total attempts including the first one. Default 10 for handlers, which
-     * gives up after roughly 17 minutes of failures with the default delays.
-     * `Infinity` retries until the delivery succeeds.
-     */
-    readonly attempts?: number;
-    /** Delay before the second attempt. Default `'1s'`. */
-    readonly initialDelay?: Duration;
-    /** Growth factor of the delay per attempt. Default 2. */
-    readonly factor?: number;
-    /** Upper bound of a single delay. Default `'10m'`. */
-    readonly maxDelay?: Duration;
-    /** Default `'full'`. */
-    readonly jitter?: JitterStrategy;
-    /** Return false to dead-letter an error without retrying it. */
-    readonly retryIf?: (error: unknown) => boolean;
-}
-interface RetryPolicy {
-    readonly attempts: number;
-    readonly initialDelayMs: number;
-    readonly factor: number;
-    readonly maxDelayMs: number;
-    readonly jitter: JitterStrategy;
-    readonly retryIf: ((error: unknown) => boolean) | undefined;
-}
-/** Default policy of handlers. */
-declare const DEFAULT_RETRY_POLICY: RetryPolicy;
-/**
- * Default policy of routes to transports: a broker outage must only delay
- * events, so routes retry until the broker accepts them, at most every 5 minutes.
- */
-declare const DEFAULT_ROUTE_RETRY_POLICY: RetryPolicy;
-declare function createRetryPolicy(options: RetryPolicyOptions | undefined, base?: RetryPolicy): RetryPolicy;
-/**
- * Delay before the next attempt after `failedAttempts` failures (1-based):
- * capped exponential backoff with the policy's jitter.
- */
-declare function computeRetryDelay(policy: RetryPolicy, failedAttempts: number, random?: () => number): number;
-declare function isRetryableError(policy: RetryPolicy, error: unknown): boolean;
-
-/** Passed to every handler call. */
-interface HandlerContext<TTransaction = unknown> {
-    readonly deliveryId: string;
-    readonly handler: string;
-    /** Attempt number, starting at 1. */
-    readonly attempt: number;
-    readonly maxAttempts: number;
-    /** Aborted when the handler times out, the lease is lost or the bus stops. */
-    readonly signal: AbortSignal;
     /**
-     * Transaction the delivery completes in, for handlers subscribed with
-     * `transactional: true`. Write through it to make the handler's effects and
-     * the completion atomic. Undefined otherwise.
-     */
-    readonly transaction: TTransaction | undefined;
-}
-type EventHandler<TPayload = unknown, TTransaction = unknown> = (event: EventEnvelope<TPayload>, context: HandlerContext<TTransaction>) => unknown;
-interface SubscribeOptions {
-    /**
-     * Stable id of the handler. Deliveries are recorded under it, so renaming it
-     * orphans pending deliveries. Letters, digits and `._:/-`.
+     * Hands back every lease group that `leaseOwner` holds without running work,
+     * so other workers can take them at once instead of after lease expiry.
+     * Called at graceful shutdown after the owner's deliveries settled. Groups
+     * with running deliveries stay leased. Optional.
      */
-    readonly id: string;
-    /** Overrides the bus retry policy field by field. */
-    readonly retry?: RetryPolicyOptions;
-    /** Abort and retry when a call takes longer. `false` disables the bus default. */
-    readonly timeout?: Duration | false;
-    /** Maximum concurrent deliveries of this handler in this process. */
-    readonly concurrency?: number;
+    relinquish?(leaseOwner: string, now: Date): Promise<void>;
     /**
-     * Run the handler inside a store transaction that also completes the
-     * delivery: its writes and the completion commit or roll back together,
-     * so a handler that writes only through `context.transaction` (or through
-     * events it publishes) takes effect exactly once.
-     *
-     * The lease is not renewed while the transaction is open. A transactional
-     * handler must finish within the lease duration (default 30s), or within its
-     * `timeout`, which extends the lease once to cover it; otherwise it is aborted.
+     * Calls `listener` soon after a transaction that added deliveries due at once has committed, in this
+     * process or in any other one, so an idle dispatcher claims them without waiting for its next poll.
+     * A hint, never a guarantee: a report may be late, merged with others, or lost (while a connection
+     * is re-established, for instance), and polling still finds every delivery. Resolves with a function
+     * that stops listening, or with `undefined` when this store cannot listen. Optional.
      */
-    readonly transactional?: boolean;
-}
-/** Public description of a registered handler or route. */
-interface HandlerDescriptor {
-    readonly id: string;
-    readonly eventType: string;
-    readonly retry: RetryPolicy;
-    readonly timeoutMs: number | null;
-    readonly concurrency: number | null;
-    readonly transactional: boolean;
-    /** True for routes that forward events to a transport. */
-    readonly forwardsToTransport: boolean;
+    watchNewDeliveries?(listener: () => void): Promise<(() => Promise<void>) | undefined>;
+    /** Releases connections the store opened itself. */
+    close?(): Promise<void>;
 }
 
 /**
@@ -430,45 +720,7 @@ declare function createUuidV7(timestamp?: number): string;
 /** Produces unique identifiers for events, deliveries and lease tokens. */
 type IdentifierGenerator = () => string;
 
-interface InMemoryEventStoreOptions {
-    /** Allow use when `NODE_ENV` is `production`. Data is lost on restart. Default false. */
-    readonly allowInProduction?: boolean;
-    readonly generateIdentifier?: IdentifierGenerator;
-}
-/** Transaction handle of {@link InMemoryEventStore}. Writes apply on commit only. */
-declare class InMemoryTransaction {
-    #private;
-    get state(): 'open' | 'committed' | 'rolled-back';
-    enqueue(operation: () => void): void;
-    /** Runs `finisher` once the transaction commits or rolls back, like a lock release. */
-    onFinish(finisher: () => void): void;
-    commit(): void;
-    rollback(): void;
-}
-/**
- * Event store kept in process memory, with the same semantics as the database
- * stores: transactional appends, leases, fencing and per-key ordering. Payloads
- * are round-tripped through JSON exactly like a database would store them.
- * Meant for tests and local development.
- */
-declare class InMemoryEventStore implements EventStore<InMemoryTransaction> {
-    #private;
-    constructor(options?: InMemoryEventStoreOptions);
-    transaction<T>(work: (transaction: InMemoryTransaction) => Promise<T>): Promise<T>;
-    append(transaction: InMemoryTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
-    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
-    complete(lease: LeaseReference, now: Date, transaction?: InMemoryTransaction): Promise<boolean>;
-    reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
-    release(lease: LeaseReference, now: Date): Promise<boolean>;
-    bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
-    listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
-    requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
-    purge(request: PurgeRequest): Promise<PurgeResult>;
-    statistics(now: Date): Promise<EventStoreStatistics>;
-}
-
-type FailureStage = 'claim' | 'dispatch' | 'complete' | 'reschedule' | 'bury' | 'release' | 'extend-lease' | 'purge' | 'observer';
+type FailureStage = 'claim' | 'dispatch' | 'complete' | 'reschedule' | 'bury' | 'release' | 'relinquish' | 'extend-lease' | 'purge' | 'watch' | 'observer';
 /**
  * Hooks for logging, metrics and tracing. Every method is optional, runs
  * synchronously on the hot path and must not throw; errors it throws are
@@ -580,6 +832,15 @@ interface DispatcherOptions {
     readonly leaseDuration?: Duration;
     /** How long `stop` waits for running handlers before aborting them. Default `'30s'`. */
     readonly shutdownTimeout?: Duration;
+    /**
+     * Longest a finished delivery waits so that deliveries finishing around the
+     * same time are completed with one store call (when the store supports it).
+     * A delivery that finishes while nothing else runs is completed at once.
+     * `0` completes every delivery on its own. Default `'2ms'`.
+     */
+    readonly completionBatchWindow?: Duration;
+    /** Most deliveries completed in one store call. Default 200. */
+    readonly completionBatchSize?: number;
 }
 interface RetentionOptions {
     /**
@@ -643,6 +904,16 @@ interface RelayBusOptions<TTransaction = unknown> {
     readonly clock?: Clock;
     readonly generateIdentifier?: IdentifierGenerator;
     readonly random?: () => number;
+    /**
+     * Catalogs this process is checked against when it starts. `start()` throws a
+     * {@link ConfigurationError} listing every event that is not covered:
+     * - a catalog: every event needs a handler or a route;
+     * - `consume(catalog, { events })`: each declared event needs a local handler;
+     * - `produce(catalog, { events })`: each declared event needs a route to a transport.
+     *
+     * See `registerCatalog`.
+     */
+    readonly catalogs?: readonly (Catalog | CatalogDeclaration)[];
 }
 interface PublishOptions<TTransaction = unknown> {
     /** Transaction to write into. Default: the current scope, then `transactionResolver`. */
@@ -690,6 +961,38 @@ declare class RelayBus<TTransaction = unknown> {
      */
     subscribe<TPayload>(event: EventClass<TPayload>, handler: EventHandler<TPayload, TTransaction>, options: SubscribeOptions): void;
     subscribe(eventType: string, handler: EventHandler<unknown, TTransaction>, options: SubscribeOptions): void;
+    /**
+     * Subscribes the `on${EventName}` methods of `handlers` to the events of
+     * `catalog`, or to the events named in `options.events`, with the stable
+     * handler ids `${prefix}.on${EventName}`. The prefix is `options.idPrefix`,
+     * else the catalog name, else the class name of `handlers`. Methods run with
+     * `this` bound to `handlers`; methods of events that are not selected are
+     * ignored. A missing handler of a selected event fails to compile, and
+     * throws {@link ConfigurationError} at runtime, as does an invalid or taken
+     * id; handlers registered before the failure stay registered.
+     *
+     * ```ts
+     * bus.subscribeCatalog(OrderEvents, new BillingHandlers(), { events: ['OrderPlaced'] });
+     * ```
+     */
+    subscribeCatalog<TCatalog extends Catalog, const TName extends keyof TCatalog>(catalog: TCatalog, handlers: NoInfer<HandlersOf<TCatalog, TName, TTransaction>>, options: SubscribeCatalogOptions<NoInfer<TCatalog>, TName> & {
+        readonly events: readonly TName[];
+    }): void;
+    /** Without a statically known `events` list, every handler of the catalog is required. */
+    subscribeCatalog<TCatalog extends Catalog>(catalog: TCatalog, handlers: HandlersOf<TCatalog, keyof TCatalog, TTransaction>, options?: SubscribeCatalogOptions<NoInfer<TCatalog>>): void;
+    /**
+     * Adds a catalog, or a `consume` / `produce` declaration, to the checks
+     * `start()` runs; `start()` throws a {@link ConfigurationError} naming each
+     * event that is not covered and what it lacks. Equivalent to the `catalogs`
+     * option.
+     */
+    registerCatalog(catalog: Catalog | CatalogDeclaration): void;
+    /**
+     * A view of this bus that publishes only the events of `catalog`, or only
+     * the events named in `options.events` (for example the events this service
+     * produces). Other events fail to compile and are rejected at runtime.
+     */
+    forCatalog<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogPublisher<TCatalog, TTransaction, TName>;
     /** Registered handlers and routes, for diagnostics. */
     handlers(): readonly HandlerDescriptor[];
     /**
@@ -741,4 +1044,82 @@ declare class RelayBus<TTransaction = unknown> {
     purgeExpired(): Promise<PurgeResult>;
 }
 
-export { type AppendEntry, type AppendResult, type ClaimRequest, type ClaimedDelivery, type Clock, ConfigurationError, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DELIVERY_STATUSES, type DefineEventOptions, type DeliveryQuery, type DeliveryRecord, type DeliveryStatus, type DispatcherOptions, DispatcherStoppedError, type DomainEvent, type Duration, type ErrorInfo, type EventClass, type EventEnvelope, type EventHandler, type EventHeaders, type EventReference, type EventStore, type EventStoreStatistics, EventValidationError, type FailureStage, type HandlerContext, type HandlerDescriptor, HandlerTimeoutError, type IdentifierGenerator, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryTransaction, type InboundSubscriptionOptions, InvalidEnvelopeError, type JitterStrategy, LeaseLostError, type LeaseReference, MAX_TIMER_DELAY_MS, type NewDelivery, NonRetryableError, type PayloadOf, type PublishOneOptions, type PublishOptions, type PurgeRequest, type PurgeResult, type ReceiveStatus, RelayBus, RelayBusError, type RelayBusLogger, type RelayBusObserver, type RelayBusOptions, type RetentionOptions, type RetryPolicy, type RetryPolicyOptions, type RouteOptions, StandardSchemaV1, type SubscribeOptions, type TransactionMode, TransactionRequiredError, type Transport, type TransportMessageHandler, type UnroutedEventPolicy, type ValidationIssue, assertEventType, computeRetryDelay, createRetryPolicy, createUuidV7, defineEvent, isRetryableError, systemClock, toErrorInfo, toMilliseconds, validatePayload };
+/** The publishing half of a bus, which a {@link CatalogPublisher} delegates to. */
+interface PublishTarget<TTransaction> {
+    publish<TPayload>(event: DomainEvent<TPayload>, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TPayload>>;
+    publishAll(events: readonly DomainEvent[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
+}
+/**
+ * A view of a bus that publishes only the events of one catalog, or only the
+ * events a service produces from it. Obtain it with `bus.forCatalog(catalog)`
+ * or `bus.forCatalog(catalog, { events: ['OrderPlaced'] })`. Publishing an
+ * event outside the view fails to compile; a mistyped event that gets past the
+ * compiler (a cast, plain JavaScript, or a class with a structurally identical
+ * payload) is rejected with a {@link ConfigurationError} before anything is stored.
+ *
+ * ```ts
+ * const orders = bus.forCatalog(OrderEvents);
+ * await orders.publish(new OrderPlaced({ orderId }));
+ * await orders.publish(new UserRegistered({ userId })); // compile error
+ * ```
+ */
+declare class CatalogPublisher<TCatalog extends Catalog, TTransaction = unknown, TName extends keyof TCatalog = keyof TCatalog> {
+    #private;
+    /**
+     * Throws {@link ConfigurationError} when `catalog` was not created with
+     * `defineCatalog` or `options.events` names no event, an unknown event or
+     * the same event twice.
+     */
+    constructor(catalog: TCatalog, target: PublishTarget<TTransaction>, options?: CatalogEventSelection<TName>);
+    /** Same as `bus.publish`, limited to the events of the view. */
+    publish<TEvent extends CatalogEvents<TCatalog, TName>>(event: TEvent, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TEvent['payload']>>;
+    /** Same as `bus.publishAll`, limited to the events of the view. Nothing is stored unless every event belongs to it. */
+    publishAll(events: readonly CatalogEvents<TCatalog, TName>[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
+}
+
+interface InMemoryEventStoreOptions {
+    /** Allow use when `NODE_ENV` is `production`. Data is lost on restart. Default false. */
+    readonly allowInProduction?: boolean;
+    readonly generateIdentifier?: IdentifierGenerator;
+    /**
+     * Keep a record of completed deliveries (status `completed`, listed, counted
+     * and purged by `retention.completed`). Default false: a completed delivery
+     * is deleted, like in the database stores.
+     */
+    readonly retainCompleted?: boolean;
+}
+/** Transaction handle of {@link InMemoryEventStore}. Writes apply on commit only. */
+declare class InMemoryTransaction {
+    #private;
+    get state(): 'open' | 'committed' | 'rolled-back';
+    enqueue(operation: () => void): void;
+    /** Runs `finisher` once the transaction commits or rolls back, like a lock release. */
+    onFinish(finisher: () => void): void;
+    commit(): void;
+    rollback(): void;
+}
+/**
+ * Event store kept in process memory, with the same semantics as the database
+ * stores: transactional appends, leases, fencing and per-key ordering. Payloads
+ * are round-tripped through JSON exactly like a database would store them.
+ * Meant for tests and local development.
+ */
+declare class InMemoryEventStore implements EventStore<InMemoryTransaction> {
+    #private;
+    constructor(options?: InMemoryEventStoreOptions);
+    transaction<T>(work: (transaction: InMemoryTransaction) => Promise<T>): Promise<T>;
+    append(transaction: InMemoryTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
+    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    complete(lease: LeaseReference, now: Date, transaction?: InMemoryTransaction): Promise<boolean>;
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
+    reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
+    release(lease: LeaseReference, now: Date): Promise<boolean>;
+    bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
+    listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
+    requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
+    purge(request: PurgeRequest): Promise<PurgeResult>;
+    statistics(now: Date): Promise<EventStoreStatistics>;
+}
+
+export { type AppendEntry, type AppendResult, type Catalog, type CatalogDeclaration, type CatalogDescription, type CatalogEntry, type CatalogEventClass, type CatalogEventName, type CatalogEventSelection, type CatalogEvents, CatalogPublisher, type CatalogRole, type ClaimRequest, type ClaimedDelivery, type Clock, ConfigurationError, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DELIVERY_STATUSES, type DefineCatalogOptions, type DefineEventOptions, type DeliveryQuery, type DeliveryRecord, type DeliveryStatus, type DispatcherOptions, DispatcherStoppedError, type DomainEvent, type Duration, type ErrorInfo, type EventClass, type EventEnvelope, type EventHandler, type EventHeaders, type EventOf, type EventReference, type EventStore, type EventStoreStatistics, EventValidationError, type FailureStage, type HandlerContext, type HandlerDescriptor, type HandlerShapeOf, HandlerTimeoutError, type HandlersOf, type IdentifierGenerator, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryTransaction, type InboundSubscriptionOptions, InvalidEnvelopeError, type JitterStrategy, LeaseLostError, type LeaseReference, MAX_TIMER_DELAY_MS, type MatchingHandlers, type NewDelivery, type NoExtraHandlers, NonRetryableError, type PartialHandlersOf, type PayloadOf, type PublishOneOptions, type PublishOptions, type PublishTarget, type PurgeRequest, type PurgeResult, type ReceiveStatus, RelayBus, RelayBusError, type RelayBusLogger, type RelayBusObserver, type RelayBusOptions, type RetentionOptions, type RetryPolicy, type RetryPolicyOptions, type RouteOptions, StandardSchemaV1, type SubscribeCatalogOptions, type SubscribeOptions, type TransactionMode, TransactionRequiredError, type Transport, type TransportMessageHandler, type UnroutedEventPolicy, type ValidationIssue, assertEventType, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineEvent, defineHandlers, describeCatalog, isRetryableError, produce, systemClock, toErrorInfo, toMilliseconds, validatePayload };