@relaybus/core 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,8 @@
-import { D as Duration, E as EventEnvelope, a as DomainEvent, S as StandardSchemaV1, P as PayloadOf, C as ClaimedDelivery, b as EventHeaders, c as EventStoreStatistics, d as ErrorInfo, e as PurgeResult, f as EventStore, T as Transport, g as EventReference, h as Clock, A as AppendEntry, i as AppendResult, j as ClaimRequest, L as LeaseReference, k as DeliveryQuery, l as DeliveryRecord, m as PurgeRequest, n as EventClass } from './transport-DIFdeXQY.cjs';
-export { o as AttemptsExhaustedError, p as CloseOptions, q as ConfigurationError, r as DELIVERY_STATUSES, s as DefineEventKeyOptions, t as DefineEventOptions, u as DeliveryStatus, v as DispatcherStoppedError, w as DrainIncompleteError, x as EventKeyFunction, y as EventStoreTransactionOptions, z as EventValidationError, H as HandlerTimeoutError, I as InvalidEnvelopeError, B as InvalidTransportMessage, F as LeaseLostError, G as LifecycleError, M as MAX_TIMER_DELAY_MS, N as NewDelivery, J as NonRetryableError, R as RelayBusError, K as TransactionRequiredError, O as TransactionTimeoutError, Q as TransportMessage, U as TransportMessageHandler, V as TransportSubscriptionHooks, W as ValidationIssue, X as assertEventType, Y as defineEvent, Z as systemClock, _ as toErrorInfo, $ as toMilliseconds, a0 as validatePayload } from './transport-DIFdeXQY.cjs';
+import { D as Duration, E as EventEnvelope, a as DomainEvent, S as StandardSchemaV1, P as PayloadOf, C as ClaimedDelivery, b as EventHeaders, c as EventStoreStatistics, d as ErrorInfo, e as PurgeResult, f as EventReference, g as EventStore, T as Transport, h as Clock, i as TransactionIsolationLevel, A as AppendEntry, j as AppendResult, k as ClaimRequest, L as LeaseReference, l as DeliveryQuery, m as DeliveryRecord, n as PurgeRequest, o as EventClass } from './transport-CXoZgh5u.cjs';
+export { p as AttemptsExhaustedError, q as CloseOptions, r as ConfigurationError, s as DELIVERY_STATUSES, t as DefineEventKeyOptions, u as DefineEventOptions, v as DeliveryStatus, w as DispatcherStoppedError, x as DrainIncompleteError, y as DuplicateRouteEventError, z as EventKeyFunction, B as EventStoreTransactionOptions, F as EventValidationError, H as HandlerTimeoutError, I as InvalidEnvelopeError, G as InvalidTransportMessage, J as LeaseLostError, K as LifecycleError, M as MAX_TIMER_DELAY_MS, N as NewDelivery, O as NonRetryableError, R as RelayBusError, Q as TRANSACTION_ISOLATION_LEVELS, U as TransactionIsolationConflictError, V as TransactionRequiredError, W as TransactionTimeoutError, X as TransportMessage, Y as TransportMessageHandler, Z as TransportSubscriptionHooks, _ as UnknownCatalogEventError, $ as ValidationIssue, a0 as WireTypeCollisionError, a1 as WireTypesUnsupportedError, a2 as assertEventType, a3 as defineEvent, a4 as systemClock, a5 as toErrorInfo, a6 as toMilliseconds, a7 as validatePayload } from './transport-CXoZgh5u.cjs';
+
+/** Wire names by catalog event name, for the events that have one. */
+type WireNames<TName extends string = string> = Readonly<Partial<Record<TName, string>>>;
 
 /**
  * How the delay between attempts is randomized.
@@ -172,12 +175,20 @@ interface CatalogEventSelection<TName> {
     readonly events?: readonly TName[];
 }
 /** Options of {@link defineCatalog}. */
-interface DefineCatalogOptions {
+interface DefineCatalogOptions<TCatalog extends Catalog = Catalog> {
     /**
      * Name of the catalog, used in boot-check messages and as the default prefix
      * of the handler ids that `subscribeCatalog` registers.
      */
     readonly name?: string;
+    /**
+     * Names the wire format uses for events instead of their event types, by catalog event name:
+     * `{ OrderPlaced: 'Order Placed' }`. A route of the catalog (`route(produce(...))`) hands them
+     * to its transport's codec, which writes and reads the event under that name, exactly as the
+     * `wireTypes` of `jsonEnvelope` would; a `wireTypes` of the route wins for its events. Events
+     * without a name travel under their event type.
+     */
+    readonly wireTypes?: WireNames<Extract<keyof TCatalog, string>>;
 }
 /**
  * Options of `RelayBus.subscribeCatalog`: {@link SubscribeOptions} for every
@@ -225,9 +236,10 @@ interface CatalogDescription {
  *
  * 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.
+ * or two entries with the same event type; `UnknownCatalogEventError` for a wire name of an
+ * event the catalog does not have, `WireTypeCollisionError` for one wire name given twice.
  */
-declare function defineCatalog<const TCatalog extends Catalog>(events: TCatalog, options?: DefineCatalogOptions): Readonly<TCatalog>;
+declare function defineCatalog<const TCatalog extends Catalog>(events: TCatalog, options?: DefineCatalogOptions<TCatalog>): Readonly<TCatalog>;
 /**
  * Describes a catalog created by {@link defineCatalog}. The description and its
  * entries are frozen. Throws {@link ConfigurationError} for any other object,
@@ -348,6 +360,55 @@ declare function consume<TCatalog extends Catalog, const TName extends keyof TCa
  */
 declare function produce<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogDeclaration<TCatalog, TName>;
 
+/**
+ * Options of {@link route}: a {@link RouteOptions} without `event`, because the route sends every
+ * event of its catalog declaration, each as a route of its own with these settings.
+ */
+interface CatalogRouteOptions<TName extends string = string> extends Omit<RouteOptions, 'event'> {
+    /**
+     * Names the wire format uses for these events instead of their event types, by catalog event
+     * name. They override the `wireTypes` of the catalog and reach the codec of `transport`, which
+     * writes and reads the events under those names, as the `wireTypes` of `jsonEnvelope` would.
+     * Needs a codec that maps type names (`jsonEnvelope`) and a transport that accepts them.
+     */
+    readonly wireTypes?: WireNames<TName>;
+}
+/** The routes of a catalog declaration, created by {@link route}. */
+interface CatalogRoute {
+    readonly declaration: CatalogDeclaration;
+    readonly options: CatalogRouteOptions;
+    /** The checked `wireTypes` of the route, by catalog event name. */
+    readonly wireNames: ReadonlyMap<string, string>;
+}
+/**
+ * Routes the events of a `produce(...)` declaration to one transport with shared settings. Each
+ * event becomes a route to `destination` (default: its own event type), so several events of a
+ * catalog reach one topic or queue without a route apiece, in commit order per key. Pass it in
+ * `routes` next to plain routes; a plain route per event keeps working.
+ *
+ * ```ts
+ * routes: [
+ *   route(produce(OrderEvents, { events: ['OrderPlaced', 'OrderShipped'] }), {
+ *     transport: 'kafka',
+ *     destination: 'orders',
+ *     wireTypes: { OrderPlaced: 'Order Placed' },
+ *   }),
+ * ]
+ * ```
+ *
+ * @throws ConfigurationError for anything but a `produce(...)` declaration, and
+ * `UnknownCatalogEventError` or `WireTypeCollisionError` for bad `wireTypes`.
+ */
+declare function route<TCatalog extends Catalog, TName extends keyof TCatalog>(declaration: CatalogDeclaration<TCatalog, TName>, options: CatalogRouteOptions<Extract<TName, string>>): CatalogRoute;
+/**
+ * Event type to wire name of the events of `catalog` that have one (`wireTypes` of
+ * `defineCatalog`), for the `wireTypes` of a `jsonEnvelope` that reads them: a service that only
+ * consumes a catalog has no route to declare them, and gives its codec these instead.
+ */
+declare function catalogWireTypes(catalog: Catalog): Readonly<Record<string, string>>;
+/** Plain routes and catalog routes, as `RelayBusOptions.routes` accepts them. */
+type RouteDefinition = RouteOptions | CatalogRoute;
+
 /**
  * RFC 9562 UUID version 7: 48-bit Unix millisecond timestamp followed by random
  * bits. Time-ordered, so it keeps B-tree indexes compact, and globally unique,
@@ -526,7 +587,9 @@ interface BacklogEvent {
 interface RelayBusObserver {
     /**
      * Events were written into the publishing transaction. Called before that
-     * transaction commits, so it can still roll back. Duplicates are not reported.
+     * transaction commits, so it can still roll back, except in a `bus.transaction` with an
+     * `isolationLevel`, whose publishes are reported once the attempt that committed is over (an
+     * attempt may be rolled back and rerun). Duplicates are not reported.
      */
     onPublished?(event: {
         readonly envelopes: readonly EventEnvelope[];
@@ -591,6 +654,27 @@ interface RelayBusLogger {
  *   but no longer atomic with business writes made outside that transaction.
  */
 type TransactionMode = 'required' | 'optional';
+/** Options of one `bus.transaction` (and `@RelayBusTransaction()` method). */
+interface TransactionOptions {
+    /**
+     * Runs the transaction at this isolation level; the store must support it, else the call
+     * throws a {@link ConfigurationError} (PostgreSQL stores do; MongoDB and the in-memory store
+     * do not). Without it the transaction runs exactly as before, at the database default.
+     *
+     * With `'repeatable read'` or `'serializable'`, a serialization failure (PostgreSQL SQLSTATE
+     * `40001`) rolls the transaction back and `work` runs again in a new one, up to
+     * {@link TransactionOptions.maxAttempts} times, so **`work` may run more than once**: keep
+     * everything but database writes through the transaction (HTTP calls, broker publishes,
+     * counters, emails) out of it. Events published by a failed attempt are rolled back with it.
+     */
+    readonly isolationLevel?: TransactionIsolationLevel;
+    /**
+     * How many times `work` may run when `isolationLevel` is `'repeatable read'` or `'serializable'`
+     * and the transaction fails with a serialization failure; the last failure is rethrown unchanged.
+     * Each attempt is held to its own `transactionTimeout`. A positive integer. Default 3.
+     */
+    readonly maxAttempts?: number;
+}
 /**
  * What `publish` does with an event that has no handler or route in this
  * process. Deliveries are created from the publisher's registrations, so a
@@ -690,8 +774,12 @@ interface RelayBusOptions<TTransaction = unknown> {
     readonly dispatcher?: DispatcherOptions;
     readonly retention?: RetentionOptions;
     readonly transports?: readonly Transport[];
-    /** Events forwarded to brokers after they commit. */
-    readonly routes?: readonly RouteOptions[];
+    /**
+     * Events forwarded to brokers after they commit: a route per event class or type, or
+     * `route(produce(Catalog, { events }), { transport, destination, ... })` for several events of a
+     * catalog with shared settings.
+     */
+    readonly routes?: readonly RouteDefinition[];
     /** Broker destinations whose events are stored and dispatched to local handlers. */
     readonly subscriptions?: readonly InboundSubscriptionOptions[];
     /** Create tables and indexes on start. Default true. */
@@ -923,14 +1011,26 @@ declare class RelayBus<TTransaction = unknown> {
      * Runs `work` in a new store transaction. `publish` calls inside it join the
      * transaction without passing it explicitly. The transaction is held to `transactionTimeout`
      * and rolled back with a {@link TransactionTimeoutError} when it runs past it.
+     *
+     * With `options.isolationLevel` it runs at that level, and at `'repeatable read'` or
+     * `'serializable'` a serialization failure reruns `work` in a new transaction (see
+     * {@link TransactionOptions}), so `work` may run more than once. Without options nothing
+     * changes. The call always opens a transaction of its own, also inside another one.
      */
-    transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
+    transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
      * The transaction `publish` would join right now: the one of the enclosing `bus.transaction`
      * (or `@RelayBusTransaction()` method, or transactional handler), else the one
      * `transactionResolver` finds. Repositories use it to write in the same transaction.
      */
     currentTransaction(): TTransaction | undefined;
+    /**
+     * The isolation level the transaction `publish` would join was opened at by
+     * `bus.transaction({ isolationLevel })` (or `@RelayBusTransaction({ isolationLevel })`);
+     * undefined for every other transaction, including those without a level and the one of
+     * `transactionResolver`.
+     */
+    currentIsolationLevel(): TransactionIsolationLevel | undefined;
     /**
      * Stores an event received from a broker and schedules it for local handlers.
      * Idempotent on the event id. Transports call it and acknowledge the message
@@ -977,5 +1077,5 @@ declare class RelayBus<TTransaction = unknown> {
     purgeExpired(): Promise<PurgeResult>;
 }
 
-export { AppendEntry, AppendResult, CatalogPublisher, ClaimRequest, ClaimedDelivery, Clock, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DeliveryQuery, DeliveryRecord, DomainEvent, Duration, ErrorInfo, EventClass, EventEnvelope, EventHeaders, EventReference, EventStore, EventStoreStatistics, InMemoryEventStore, InMemoryTransaction, LeaseReference, PayloadOf, PurgeRequest, PurgeResult, RelayBus, StandardSchemaV1, TRACEPARENT_HEADER, TRACESTATE_HEADER, Transport, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, traceContextOf };
-export type { BacklogEvent, Catalog, CatalogDeclaration, CatalogDescription, CatalogEntry, CatalogEventClass, CatalogEventName, CatalogEventSelection, CatalogEvents, CatalogRole, ClaimFinishedEvent, DefineCatalogOptions, DeliveryKind, DispatcherOptions, EventHandler, EventOf, FailureStage, HandlerContext, HandlerDescriptor, HandlerFinishedEvent, HandlerShapeOf, HandlerStartedEvent, HandlersOf, IdentifierGenerator, InMemoryEventStoreOptions, InboundSubscriptionOptions, InvalidMessageEvent, JitterStrategy, MatchingHandlers, NoExtraHandlers, OperationOutcome, PartialHandlersOf, ProcessTraceInput, PublishFinishedEvent, PublishOneOptions, PublishOptions, PublishTarget, PublishTraceInput, ReceiveFinishedEvent, ReceiveOutcome, ReceiveStatus, RelayBusLogger, RelayBusObserver, RelayBusOptions, RelayBusTracer, RetentionOptions, RetryPolicy, RetryPolicyOptions, RouteOptions, SendTraceInput, StopOptions, StopResult, SubscribeCatalogOptions, SubscribeOptions, TraceContext, TransactionMode, TransportSentEvent, UnroutedEventPolicy };
+export { AppendEntry, AppendResult, CatalogPublisher, ClaimRequest, ClaimedDelivery, Clock, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DeliveryQuery, DeliveryRecord, DomainEvent, Duration, ErrorInfo, EventClass, EventEnvelope, EventHeaders, EventReference, EventStore, EventStoreStatistics, InMemoryEventStore, InMemoryTransaction, LeaseReference, PayloadOf, PurgeRequest, PurgeResult, RelayBus, StandardSchemaV1, TRACEPARENT_HEADER, TRACESTATE_HEADER, TransactionIsolationLevel, Transport, catalogWireTypes, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, route, traceContextOf };
+export type { BacklogEvent, Catalog, CatalogDeclaration, CatalogDescription, CatalogEntry, CatalogEventClass, CatalogEventName, CatalogEventSelection, CatalogEvents, CatalogRole, CatalogRoute, CatalogRouteOptions, ClaimFinishedEvent, DefineCatalogOptions, DeliveryKind, DispatcherOptions, EventHandler, EventOf, FailureStage, HandlerContext, HandlerDescriptor, HandlerFinishedEvent, HandlerShapeOf, HandlerStartedEvent, HandlersOf, IdentifierGenerator, InMemoryEventStoreOptions, InboundSubscriptionOptions, InvalidMessageEvent, JitterStrategy, MatchingHandlers, NoExtraHandlers, OperationOutcome, PartialHandlersOf, ProcessTraceInput, PublishFinishedEvent, PublishOneOptions, PublishOptions, PublishTarget, PublishTraceInput, ReceiveFinishedEvent, ReceiveOutcome, ReceiveStatus, RelayBusLogger, RelayBusObserver, RelayBusOptions, RelayBusTracer, RetentionOptions, RetryPolicy, RetryPolicyOptions, RouteDefinition, RouteOptions, SendTraceInput, StopOptions, StopResult, SubscribeCatalogOptions, SubscribeOptions, TraceContext, TransactionMode, TransactionOptions, TransportSentEvent, UnroutedEventPolicy };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { D as Duration, E as EventEnvelope, a as DomainEvent, S as StandardSchemaV1, P as PayloadOf, C as ClaimedDelivery, b as EventHeaders, c as EventStoreStatistics, d as ErrorInfo, e as PurgeResult, f as EventStore, T as Transport, g as EventReference, h as Clock, A as AppendEntry, i as AppendResult, j as ClaimRequest, L as LeaseReference, k as DeliveryQuery, l as DeliveryRecord, m as PurgeRequest, n as EventClass } from './transport-DIFdeXQY.js';
-export { o as AttemptsExhaustedError, p as CloseOptions, q as ConfigurationError, r as DELIVERY_STATUSES, s as DefineEventKeyOptions, t as DefineEventOptions, u as DeliveryStatus, v as DispatcherStoppedError, w as DrainIncompleteError, x as EventKeyFunction, y as EventStoreTransactionOptions, z as EventValidationError, H as HandlerTimeoutError, I as InvalidEnvelopeError, B as InvalidTransportMessage, F as LeaseLostError, G as LifecycleError, M as MAX_TIMER_DELAY_MS, N as NewDelivery, J as NonRetryableError, R as RelayBusError, K as TransactionRequiredError, O as TransactionTimeoutError, Q as TransportMessage, U as TransportMessageHandler, V as TransportSubscriptionHooks, W as ValidationIssue, X as assertEventType, Y as defineEvent, Z as systemClock, _ as toErrorInfo, $ as toMilliseconds, a0 as validatePayload } from './transport-DIFdeXQY.js';
+import { D as Duration, E as EventEnvelope, a as DomainEvent, S as StandardSchemaV1, P as PayloadOf, C as ClaimedDelivery, b as EventHeaders, c as EventStoreStatistics, d as ErrorInfo, e as PurgeResult, f as EventReference, g as EventStore, T as Transport, h as Clock, i as TransactionIsolationLevel, A as AppendEntry, j as AppendResult, k as ClaimRequest, L as LeaseReference, l as DeliveryQuery, m as DeliveryRecord, n as PurgeRequest, o as EventClass } from './transport-CXoZgh5u.js';
+export { p as AttemptsExhaustedError, q as CloseOptions, r as ConfigurationError, s as DELIVERY_STATUSES, t as DefineEventKeyOptions, u as DefineEventOptions, v as DeliveryStatus, w as DispatcherStoppedError, x as DrainIncompleteError, y as DuplicateRouteEventError, z as EventKeyFunction, B as EventStoreTransactionOptions, F as EventValidationError, H as HandlerTimeoutError, I as InvalidEnvelopeError, G as InvalidTransportMessage, J as LeaseLostError, K as LifecycleError, M as MAX_TIMER_DELAY_MS, N as NewDelivery, O as NonRetryableError, R as RelayBusError, Q as TRANSACTION_ISOLATION_LEVELS, U as TransactionIsolationConflictError, V as TransactionRequiredError, W as TransactionTimeoutError, X as TransportMessage, Y as TransportMessageHandler, Z as TransportSubscriptionHooks, _ as UnknownCatalogEventError, $ as ValidationIssue, a0 as WireTypeCollisionError, a1 as WireTypesUnsupportedError, a2 as assertEventType, a3 as defineEvent, a4 as systemClock, a5 as toErrorInfo, a6 as toMilliseconds, a7 as validatePayload } from './transport-CXoZgh5u.js';
+
+/** Wire names by catalog event name, for the events that have one. */
+type WireNames<TName extends string = string> = Readonly<Partial<Record<TName, string>>>;
 
 /**
  * How the delay between attempts is randomized.
@@ -172,12 +175,20 @@ interface CatalogEventSelection<TName> {
     readonly events?: readonly TName[];
 }
 /** Options of {@link defineCatalog}. */
-interface DefineCatalogOptions {
+interface DefineCatalogOptions<TCatalog extends Catalog = Catalog> {
     /**
      * Name of the catalog, used in boot-check messages and as the default prefix
      * of the handler ids that `subscribeCatalog` registers.
      */
     readonly name?: string;
+    /**
+     * Names the wire format uses for events instead of their event types, by catalog event name:
+     * `{ OrderPlaced: 'Order Placed' }`. A route of the catalog (`route(produce(...))`) hands them
+     * to its transport's codec, which writes and reads the event under that name, exactly as the
+     * `wireTypes` of `jsonEnvelope` would; a `wireTypes` of the route wins for its events. Events
+     * without a name travel under their event type.
+     */
+    readonly wireTypes?: WireNames<Extract<keyof TCatalog, string>>;
 }
 /**
  * Options of `RelayBus.subscribeCatalog`: {@link SubscribeOptions} for every
@@ -225,9 +236,10 @@ interface CatalogDescription {
  *
  * 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.
+ * or two entries with the same event type; `UnknownCatalogEventError` for a wire name of an
+ * event the catalog does not have, `WireTypeCollisionError` for one wire name given twice.
  */
-declare function defineCatalog<const TCatalog extends Catalog>(events: TCatalog, options?: DefineCatalogOptions): Readonly<TCatalog>;
+declare function defineCatalog<const TCatalog extends Catalog>(events: TCatalog, options?: DefineCatalogOptions<TCatalog>): Readonly<TCatalog>;
 /**
  * Describes a catalog created by {@link defineCatalog}. The description and its
  * entries are frozen. Throws {@link ConfigurationError} for any other object,
@@ -348,6 +360,55 @@ declare function consume<TCatalog extends Catalog, const TName extends keyof TCa
  */
 declare function produce<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogDeclaration<TCatalog, TName>;
 
+/**
+ * Options of {@link route}: a {@link RouteOptions} without `event`, because the route sends every
+ * event of its catalog declaration, each as a route of its own with these settings.
+ */
+interface CatalogRouteOptions<TName extends string = string> extends Omit<RouteOptions, 'event'> {
+    /**
+     * Names the wire format uses for these events instead of their event types, by catalog event
+     * name. They override the `wireTypes` of the catalog and reach the codec of `transport`, which
+     * writes and reads the events under those names, as the `wireTypes` of `jsonEnvelope` would.
+     * Needs a codec that maps type names (`jsonEnvelope`) and a transport that accepts them.
+     */
+    readonly wireTypes?: WireNames<TName>;
+}
+/** The routes of a catalog declaration, created by {@link route}. */
+interface CatalogRoute {
+    readonly declaration: CatalogDeclaration;
+    readonly options: CatalogRouteOptions;
+    /** The checked `wireTypes` of the route, by catalog event name. */
+    readonly wireNames: ReadonlyMap<string, string>;
+}
+/**
+ * Routes the events of a `produce(...)` declaration to one transport with shared settings. Each
+ * event becomes a route to `destination` (default: its own event type), so several events of a
+ * catalog reach one topic or queue without a route apiece, in commit order per key. Pass it in
+ * `routes` next to plain routes; a plain route per event keeps working.
+ *
+ * ```ts
+ * routes: [
+ *   route(produce(OrderEvents, { events: ['OrderPlaced', 'OrderShipped'] }), {
+ *     transport: 'kafka',
+ *     destination: 'orders',
+ *     wireTypes: { OrderPlaced: 'Order Placed' },
+ *   }),
+ * ]
+ * ```
+ *
+ * @throws ConfigurationError for anything but a `produce(...)` declaration, and
+ * `UnknownCatalogEventError` or `WireTypeCollisionError` for bad `wireTypes`.
+ */
+declare function route<TCatalog extends Catalog, TName extends keyof TCatalog>(declaration: CatalogDeclaration<TCatalog, TName>, options: CatalogRouteOptions<Extract<TName, string>>): CatalogRoute;
+/**
+ * Event type to wire name of the events of `catalog` that have one (`wireTypes` of
+ * `defineCatalog`), for the `wireTypes` of a `jsonEnvelope` that reads them: a service that only
+ * consumes a catalog has no route to declare them, and gives its codec these instead.
+ */
+declare function catalogWireTypes(catalog: Catalog): Readonly<Record<string, string>>;
+/** Plain routes and catalog routes, as `RelayBusOptions.routes` accepts them. */
+type RouteDefinition = RouteOptions | CatalogRoute;
+
 /**
  * RFC 9562 UUID version 7: 48-bit Unix millisecond timestamp followed by random
  * bits. Time-ordered, so it keeps B-tree indexes compact, and globally unique,
@@ -526,7 +587,9 @@ interface BacklogEvent {
 interface RelayBusObserver {
     /**
      * Events were written into the publishing transaction. Called before that
-     * transaction commits, so it can still roll back. Duplicates are not reported.
+     * transaction commits, so it can still roll back, except in a `bus.transaction` with an
+     * `isolationLevel`, whose publishes are reported once the attempt that committed is over (an
+     * attempt may be rolled back and rerun). Duplicates are not reported.
      */
     onPublished?(event: {
         readonly envelopes: readonly EventEnvelope[];
@@ -591,6 +654,27 @@ interface RelayBusLogger {
  *   but no longer atomic with business writes made outside that transaction.
  */
 type TransactionMode = 'required' | 'optional';
+/** Options of one `bus.transaction` (and `@RelayBusTransaction()` method). */
+interface TransactionOptions {
+    /**
+     * Runs the transaction at this isolation level; the store must support it, else the call
+     * throws a {@link ConfigurationError} (PostgreSQL stores do; MongoDB and the in-memory store
+     * do not). Without it the transaction runs exactly as before, at the database default.
+     *
+     * With `'repeatable read'` or `'serializable'`, a serialization failure (PostgreSQL SQLSTATE
+     * `40001`) rolls the transaction back and `work` runs again in a new one, up to
+     * {@link TransactionOptions.maxAttempts} times, so **`work` may run more than once**: keep
+     * everything but database writes through the transaction (HTTP calls, broker publishes,
+     * counters, emails) out of it. Events published by a failed attempt are rolled back with it.
+     */
+    readonly isolationLevel?: TransactionIsolationLevel;
+    /**
+     * How many times `work` may run when `isolationLevel` is `'repeatable read'` or `'serializable'`
+     * and the transaction fails with a serialization failure; the last failure is rethrown unchanged.
+     * Each attempt is held to its own `transactionTimeout`. A positive integer. Default 3.
+     */
+    readonly maxAttempts?: number;
+}
 /**
  * What `publish` does with an event that has no handler or route in this
  * process. Deliveries are created from the publisher's registrations, so a
@@ -690,8 +774,12 @@ interface RelayBusOptions<TTransaction = unknown> {
     readonly dispatcher?: DispatcherOptions;
     readonly retention?: RetentionOptions;
     readonly transports?: readonly Transport[];
-    /** Events forwarded to brokers after they commit. */
-    readonly routes?: readonly RouteOptions[];
+    /**
+     * Events forwarded to brokers after they commit: a route per event class or type, or
+     * `route(produce(Catalog, { events }), { transport, destination, ... })` for several events of a
+     * catalog with shared settings.
+     */
+    readonly routes?: readonly RouteDefinition[];
     /** Broker destinations whose events are stored and dispatched to local handlers. */
     readonly subscriptions?: readonly InboundSubscriptionOptions[];
     /** Create tables and indexes on start. Default true. */
@@ -923,14 +1011,26 @@ declare class RelayBus<TTransaction = unknown> {
      * Runs `work` in a new store transaction. `publish` calls inside it join the
      * transaction without passing it explicitly. The transaction is held to `transactionTimeout`
      * and rolled back with a {@link TransactionTimeoutError} when it runs past it.
+     *
+     * With `options.isolationLevel` it runs at that level, and at `'repeatable read'` or
+     * `'serializable'` a serialization failure reruns `work` in a new transaction (see
+     * {@link TransactionOptions}), so `work` may run more than once. Without options nothing
+     * changes. The call always opens a transaction of its own, also inside another one.
      */
-    transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
+    transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
      * The transaction `publish` would join right now: the one of the enclosing `bus.transaction`
      * (or `@RelayBusTransaction()` method, or transactional handler), else the one
      * `transactionResolver` finds. Repositories use it to write in the same transaction.
      */
     currentTransaction(): TTransaction | undefined;
+    /**
+     * The isolation level the transaction `publish` would join was opened at by
+     * `bus.transaction({ isolationLevel })` (or `@RelayBusTransaction({ isolationLevel })`);
+     * undefined for every other transaction, including those without a level and the one of
+     * `transactionResolver`.
+     */
+    currentIsolationLevel(): TransactionIsolationLevel | undefined;
     /**
      * Stores an event received from a broker and schedules it for local handlers.
      * Idempotent on the event id. Transports call it and acknowledge the message
@@ -977,5 +1077,5 @@ declare class RelayBus<TTransaction = unknown> {
     purgeExpired(): Promise<PurgeResult>;
 }
 
-export { AppendEntry, AppendResult, CatalogPublisher, ClaimRequest, ClaimedDelivery, Clock, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DeliveryQuery, DeliveryRecord, DomainEvent, Duration, ErrorInfo, EventClass, EventEnvelope, EventHeaders, EventReference, EventStore, EventStoreStatistics, InMemoryEventStore, InMemoryTransaction, LeaseReference, PayloadOf, PurgeRequest, PurgeResult, RelayBus, StandardSchemaV1, TRACEPARENT_HEADER, TRACESTATE_HEADER, Transport, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, traceContextOf };
-export type { BacklogEvent, Catalog, CatalogDeclaration, CatalogDescription, CatalogEntry, CatalogEventClass, CatalogEventName, CatalogEventSelection, CatalogEvents, CatalogRole, ClaimFinishedEvent, DefineCatalogOptions, DeliveryKind, DispatcherOptions, EventHandler, EventOf, FailureStage, HandlerContext, HandlerDescriptor, HandlerFinishedEvent, HandlerShapeOf, HandlerStartedEvent, HandlersOf, IdentifierGenerator, InMemoryEventStoreOptions, InboundSubscriptionOptions, InvalidMessageEvent, JitterStrategy, MatchingHandlers, NoExtraHandlers, OperationOutcome, PartialHandlersOf, ProcessTraceInput, PublishFinishedEvent, PublishOneOptions, PublishOptions, PublishTarget, PublishTraceInput, ReceiveFinishedEvent, ReceiveOutcome, ReceiveStatus, RelayBusLogger, RelayBusObserver, RelayBusOptions, RelayBusTracer, RetentionOptions, RetryPolicy, RetryPolicyOptions, RouteOptions, SendTraceInput, StopOptions, StopResult, SubscribeCatalogOptions, SubscribeOptions, TraceContext, TransactionMode, TransportSentEvent, UnroutedEventPolicy };
+export { AppendEntry, AppendResult, CatalogPublisher, ClaimRequest, ClaimedDelivery, Clock, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DeliveryQuery, DeliveryRecord, DomainEvent, Duration, ErrorInfo, EventClass, EventEnvelope, EventHeaders, EventReference, EventStore, EventStoreStatistics, InMemoryEventStore, InMemoryTransaction, LeaseReference, PayloadOf, PurgeRequest, PurgeResult, RelayBus, StandardSchemaV1, TRACEPARENT_HEADER, TRACESTATE_HEADER, TransactionIsolationLevel, Transport, catalogWireTypes, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, route, traceContextOf };
+export type { BacklogEvent, Catalog, CatalogDeclaration, CatalogDescription, CatalogEntry, CatalogEventClass, CatalogEventName, CatalogEventSelection, CatalogEvents, CatalogRole, CatalogRoute, CatalogRouteOptions, ClaimFinishedEvent, DefineCatalogOptions, DeliveryKind, DispatcherOptions, EventHandler, EventOf, FailureStage, HandlerContext, HandlerDescriptor, HandlerFinishedEvent, HandlerShapeOf, HandlerStartedEvent, HandlersOf, IdentifierGenerator, InMemoryEventStoreOptions, InboundSubscriptionOptions, InvalidMessageEvent, JitterStrategy, MatchingHandlers, NoExtraHandlers, OperationOutcome, PartialHandlersOf, ProcessTraceInput, PublishFinishedEvent, PublishOneOptions, PublishOptions, PublishTarget, PublishTraceInput, ReceiveFinishedEvent, ReceiveOutcome, ReceiveStatus, RelayBusLogger, RelayBusObserver, RelayBusOptions, RelayBusTracer, RetentionOptions, RetryPolicy, RetryPolicyOptions, RouteDefinition, RouteOptions, SendTraceInput, StopOptions, StopResult, SubscribeCatalogOptions, SubscribeOptions, TraceContext, TransactionMode, TransactionOptions, TransportSentEvent, UnroutedEventPolicy };