@relaybus/core 0.4.1 → 0.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { ConfigurationError, assertEventType, CompositeKey, Milliseconds, NonRetryableError, DrainIncompleteError, LifecycleError, toErrorInfo, LeaseSettlement, schedule, TransactionTimeoutError, PositiveInteger, DispatcherStoppedError, DeliveryLeaseIdentity, LeaseLostError, AttemptsExhaustedError, validatePayload, HandlerTimeoutError, TransactionRequiredError, keyFromDefinition, InvalidEnvelopeError } from './chunk-NOR5JHVN.js';
-export { AttemptsExhaustedError, ConfigurationError, DispatcherStoppedError, DrainIncompleteError, EventValidationError, HandlerTimeoutError, InvalidEnvelopeError, LeaseLostError, LifecycleError, MAX_TIMER_DELAY_MS, NonRetryableError, RelayBusError, TransactionRequiredError, TransactionTimeoutError, assertEventType, defineEvent, toErrorInfo, toMilliseconds, validatePayload } from './chunk-NOR5JHVN.js';
+import { ConfigurationError, assertEventType, CompositeKey, Milliseconds, NonRetryableError, DrainIncompleteError, LifecycleError, toErrorInfo, UnknownCatalogEventError, WireTypeCollisionError, LeaseSettlement, schedule, TransactionTimeoutError, WireTypesUnsupportedError, PositiveInteger, DispatcherStoppedError, DeliveryLeaseIdentity, LeaseLostError, AttemptsExhaustedError, validatePayload, HandlerTimeoutError, TransactionRequiredError, keyFromDefinition, InvalidEnvelopeError, DuplicateRouteEventError } from './chunk-6PQ673MW.js';
+export { AttemptsExhaustedError, ConfigurationError, DispatcherStoppedError, DrainIncompleteError, DuplicateRouteEventError, EventValidationError, HandlerTimeoutError, InvalidEnvelopeError, LeaseLostError, LifecycleError, MAX_TIMER_DELAY_MS, NonRetryableError, RelayBusError, TransactionIsolationConflictError, TransactionRequiredError, TransactionTimeoutError, UnknownCatalogEventError, WireTypeCollisionError, WireTypesUnsupportedError, assertEventType, defineEvent, toErrorInfo, toMilliseconds, validatePayload } from './chunk-6PQ673MW.js';
 import { randomBytes } from 'crypto';
 import { AsyncLocalStorage } from 'async_hooks';
 import { hostname } from 'os';
@@ -9,28 +9,46 @@ var systemClock = {
   now: () => /* @__PURE__ */ new Date()
 };
 
+// src/catalog-wire-names.ts
+function checkWireNames(wireNames, { events, label }) {
+  const checked = /* @__PURE__ */ new Map();
+  const owners = /* @__PURE__ */ new Map();
+  for (const [event, wire] of Object.entries(wireNames ?? {})) {
+    if (!events.includes(event)) {
+      throw new UnknownCatalogEventError(
+        `${label} has no event named '${event}' to give a wire name; its events are ${events.join(", ")}`
+      );
+    }
+    if (typeof wire !== "string" || wire.length === 0) {
+      throw new ConfigurationError(`${label} needs a non-empty wire name for '${event}'`);
+    }
+    const owner = owners.get(wire);
+    if (owner !== void 0) {
+      throw new WireTypeCollisionError(
+        `${label} gives events '${owner}' and '${event}' the same wire name '${wire}'`
+      );
+    }
+    owners.set(wire, event);
+    checked.set(event, wire);
+  }
+  return checked;
+}
+
 // src/catalog.ts
 var EVENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var descriptions = /* @__PURE__ */ new WeakMap();
+var catalogWireNames = /* @__PURE__ */ new WeakMap();
 function defineCatalog(events, options = {}) {
   const label = options.name === void 0 ? "Catalog" : `Catalog '${options.name}'`;
   const names = Object.keys(events);
   if (names.length === 0) {
     throw new ConfigurationError(`${label} must contain at least one event`);
   }
+  const wireTypes = checkWireNames(options.wireTypes, { events: names, label });
   const owners = /* @__PURE__ */ new Map();
   const entries = names.map((name) => {
     const eventClass = events[name];
-    if (!EVENT_NAME_PATTERN.test(name)) {
-      throw new ConfigurationError(
-        `${label} entry '${name}' must be a valid identifier made of letters, digits and underscores because it names the handler method on${name} and its handler id`
-      );
-    }
-    if (typeof eventClass !== "function" || typeof eventClass.type !== "string") {
-      throw new ConfigurationError(
-        `${label} entry '${name}' must be an event class created with defineEvent`
-      );
-    }
+    assertCatalogEntry(name, { eventClass, label });
     assertEventType(eventClass.type);
     const owner = owners.get(eventClass.type);
     if (owner !== void 0) {
@@ -43,8 +61,25 @@ function defineCatalog(events, options = {}) {
   });
   const catalog = Object.freeze({ ...events });
   descriptions.set(catalog, Object.freeze({ name: options.name, entries: Object.freeze(entries) }));
+  catalogWireNames.set(catalog, wireTypes);
   return catalog;
 }
+function wireNamesOf(catalog) {
+  describeCatalog(catalog);
+  return catalogWireNames.get(catalog);
+}
+function assertCatalogEntry(name, { eventClass, label }) {
+  if (!EVENT_NAME_PATTERN.test(name)) {
+    throw new ConfigurationError(
+      `${label} entry '${name}' must be a valid identifier made of letters, digits and underscores because it names the handler method on${name} and its handler id`
+    );
+  }
+  if (typeof eventClass !== "function" || typeof eventClass.type !== "string") {
+    throw new ConfigurationError(
+      `${label} entry '${name}' must be an event class created with defineEvent`
+    );
+  }
+}
 function describeCatalog(catalog) {
   const description = descriptions.get(catalog);
   if (description === void 0) {
@@ -208,6 +243,9 @@ function consume(catalog, options = {}) {
 function produce(catalog, options = {}) {
   return declare(catalog, { role: "produce", options });
 }
+function isCatalogDeclaration(value) {
+  return typeof value === "object" && value !== null && declarations.has(value);
+}
 function declare(catalog, { role, options }) {
   const entries = selectCatalogEntries(catalog, options.events);
   const declaration = Object.freeze({
@@ -273,6 +311,144 @@ function describeGap(entry, {
   return `${subject}: produced here, needs a route to a transport${handlerNote}`;
 }
 
+// src/route-wire-types.ts
+function mergeRouteWireTypes(declared, routed) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const { transport, type, wire } of declared) {
+    const types = merged.get(transport) ?? /* @__PURE__ */ new Map();
+    merged.set(transport, types);
+    addWireType(types, { type, wire, transport });
+  }
+  for (const [transport, types] of merged) {
+    assertDistinctOnTheWire(types, {
+      transport,
+      routedTypes: routed.filter((item) => item.transport === transport).map((item) => item.type)
+    });
+  }
+  return new Map([...merged].map(([transport, types]) => [transport, Object.fromEntries(types)]));
+}
+function assertDistinctOnTheWire(types, {
+  transport,
+  routedTypes
+}) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const type of /* @__PURE__ */ new Set([...types.keys(), ...routedTypes])) {
+    const name = types.get(type) ?? type;
+    const owner = owners.get(name);
+    if (owner !== void 0) {
+      throw new WireTypeCollisionError(
+        `Event types '${owner}' and '${type}' both travel as '${name}' on transport '${transport}'`
+      );
+    }
+    owners.set(name, type);
+  }
+}
+function addWireType(types, {
+  type,
+  wire,
+  transport
+}) {
+  const current = types.get(type);
+  if (current !== void 0 && current !== wire) {
+    throw new WireTypeCollisionError(
+      `Event type '${type}' has the wire names '${current}' and '${wire}' on transport '${transport}'; a transport writes one`
+    );
+  }
+  const owner = [...types].find(
+    ([otherType, otherWire]) => otherWire === wire && otherType !== type
+  );
+  if (owner !== void 0) {
+    throw new WireTypeCollisionError(
+      `Event types '${owner[0]}' and '${type}' share the wire name '${wire}' on transport '${transport}'`
+    );
+  }
+  types.set(type, wire);
+}
+
+// src/catalog-routes.ts
+var catalogRoutes = /* @__PURE__ */ new WeakSet();
+function route(declaration, options) {
+  if (!isCatalogDeclaration(declaration) || declaration.role !== "produce") {
+    throw new ConfigurationError("route() takes a produce(catalog, { events }) declaration");
+  }
+  const wireNames = checkWireNames(options.wireTypes, {
+    events: declaration.events,
+    label: `The route of ${catalogLabel(declaration.catalog)}`
+  });
+  const created = Object.freeze({
+    declaration,
+    options: Object.freeze({ ...options }),
+    wireNames
+  });
+  catalogRoutes.add(created);
+  return created;
+}
+function catalogWireTypes(catalog) {
+  return Object.fromEntries(
+    describeCatalog(catalog).entries.flatMap((entry) => {
+      const wire = wireNamesOf(catalog).get(entry.name);
+      return wire === void 0 ? [] : [[entry.type, wire]];
+    })
+  );
+}
+function isCatalogRoute(definition) {
+  return catalogRoutes.has(definition);
+}
+function expandRoutes(definitions) {
+  if (!definitions.some(isCatalogRoute)) {
+    return { routes: definitions, wireTypes: /* @__PURE__ */ new Map() };
+  }
+  const expanded = definitions.flatMap(
+    (definition) => isCatalogRoute(definition) ? expandCatalogRoute(definition) : [plainRoute(definition)]
+  );
+  assertNotRoutedTwice(expanded);
+  return {
+    routes: expanded.map((item) => item.route),
+    wireTypes: mergeRouteWireTypes(
+      expanded.flatMap(declaredWireType),
+      expanded.map((item) => ({ transport: item.route.transport, type: item.type }))
+    )
+  };
+}
+function declaredWireType({
+  route: { transport },
+  type,
+  wireType
+}) {
+  return wireType === void 0 ? [] : [{ transport, type, wire: wireType }];
+}
+function plainRoute(definition) {
+  const { event } = definition;
+  const type = typeof event === "string" ? event : event.type;
+  return { route: definition, type, fromCatalog: false, wireType: void 0 };
+}
+function expandCatalogRoute({ declaration, options, wireNames }) {
+  const catalogNames = wireNamesOf(declaration.catalog);
+  const shared = Object.fromEntries(
+    Object.entries(options).filter(([name]) => name !== "wireTypes")
+  );
+  return declaration.entries.map((entry) => ({
+    route: { ...shared, event: entry.eventClass },
+    type: entry.type,
+    fromCatalog: true,
+    wireType: wireNames.get(entry.name) ?? catalogNames.get(entry.name)
+  }));
+}
+function assertNotRoutedTwice(expanded) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of expanded) {
+    const destination = item.route.destination ?? item.type;
+    const key = JSON.stringify([item.route.transport, destination, item.type]);
+    const earlier = seen.get(key);
+    if (earlier !== void 0 && (earlier.fromCatalog || item.fromCatalog)) {
+      throw new DuplicateRouteEventError(
+        `Event type ${item.type} is routed to '${destination}' of transport '${item.route.transport}' twice`
+      );
+    }
+    seen.set(key, item);
+  }
+}
+
 // src/event-store.ts
 var DELIVERY_STATUSES = [
   "pending",
@@ -280,6 +456,11 @@ var DELIVERY_STATUSES = [
   "completed",
   "dead"
 ];
+var TRANSACTION_ISOLATION_LEVELS = [
+  "read committed",
+  "repeatable read",
+  "serializable"
+];
 var UUID_BYTES = 16;
 var TIMESTAMP_BYTES = 6;
 var BYTE_VALUES = 256;
@@ -922,6 +1103,13 @@ var BusLifecycle = class {
   markStopped() {
     this.#state = "stopped";
   }
+  /** Closes the transports a failed start may have connected, within `timeoutMs`. */
+  closeAfterFailedStart(timeoutMs) {
+    return withinDeadline({ clock: this.#parts.clock, timeoutMs }, async (deadline) => {
+      await this.#parts.closeTransports(deadline);
+      return 0;
+    });
+  }
   /** The stop of the bus within `timeoutMs`; a later call shares the first one's. */
   stop(timeoutMs) {
     if (this.#stopping !== void 0) {
@@ -1941,6 +2129,10 @@ function runInIsolatedScope(scope, work) {
 function getCurrentScope() {
   return storage.getStore();
 }
+function getCurrentIsolationLevel() {
+  const scope = storage.getStore();
+  return scope?.isolation !== void 0 && scope.isolation.transaction === scope.transaction ? scope.isolation.level : void 0;
+}
 
 // src/dispatch/handler-invocation.ts
 function rejectOnAbort(signal) {
@@ -2698,49 +2890,49 @@ function createRetentionSettings(options) {
 var TRANSPORT_HANDLER_PREFIX = "relaybus.transport";
 function groupRoutes(routes) {
   const groups = /* @__PURE__ */ new Map();
-  for (const route of routes) {
-    const type = routedType(route.event);
-    const destination = route.destination ?? type;
-    const id = `${TRANSPORT_HANDLER_PREFIX}:${route.transport}:${destination}`;
+  for (const route2 of routes) {
+    const type = routedType(route2.event);
+    const destination = route2.destination ?? type;
+    const id = `${TRANSPORT_HANDLER_PREFIX}:${route2.transport}:${destination}`;
     const group = groups.get(id);
     if (group === void 0) {
-      groups.set(id, createGroup(route, { id, destination, type }));
+      groups.set(id, createGroup(route2, { id, destination, type }));
     } else {
-      addRoute(group, { route, type, destination });
+      addRoute(group, { route: route2, type, destination });
     }
   }
   return [...groups.values()];
 }
-function createGroup(route, {
+function createGroup(route2, {
   id,
   destination,
   type
 }) {
   return {
-    transport: route.transport,
+    transport: route2.transport,
     destination,
     id,
     eventTypes: [type],
     legacyIds: [`${id}:${type}`],
-    route,
-    ...resolveSettings(route, id)
+    route: route2,
+    ...resolveSettings(route2, id)
   };
 }
 function addRoute(group, {
-  route,
+  route: route2,
   type,
   destination
 }) {
   const target = `'${group.destination}' of transport '${group.transport}'`;
-  if (route.transport !== group.transport) {
+  if (route2.transport !== group.transport) {
     throw new ConfigurationError(
-      `Routes to ${target} and to '${destination}' of transport '${route.transport}' would share the handler id '${group.id}'; rename the transport or the destination`
+      `Routes to ${target} and to '${destination}' of transport '${route2.transport}' would share the handler id '${group.id}'; rename the transport or the destination`
     );
   }
   if (group.eventTypes.includes(type)) {
     throw new ConfigurationError(`Event type ${type} is routed to ${target} twice`);
   }
-  const { retry, timeoutMs } = resolveSettings(route, group.id);
+  const { retry, timeoutMs } = resolveSettings(route2, group.id);
   if (timeoutMs !== group.timeoutMs || !sameRetryPolicy(retry, group.retry)) {
     throw new ConfigurationError(
       `Routes to ${target} must share retry and timeout, because their events are sent in one queue per key | types=${group.eventTypes[0]},${type}`
@@ -2749,10 +2941,10 @@ function addRoute(group, {
   group.eventTypes.push(type);
   group.legacyIds.push(`${group.id}:${type}`);
 }
-function resolveSettings(route, id) {
+function resolveSettings(route2, id) {
   return {
-    retry: createRetryPolicy(route.retry, DEFAULT_ROUTE_RETRY_POLICY),
-    timeoutMs: route.timeout === void 0 ? DEFAULTS.routeTimeoutMs : Milliseconds.forTimer(route.timeout, `Timeout of handler '${id}'`)
+    retry: createRetryPolicy(route2.retry, DEFAULT_ROUTE_RETRY_POLICY),
+    timeoutMs: route2.timeout === void 0 ? DEFAULTS.routeTimeoutMs : Milliseconds.forTimer(route2.timeout, `Timeout of handler '${id}'`)
   };
 }
 function sameRetryPolicy(left, right) {
@@ -2766,11 +2958,35 @@ function routedType(event) {
   return type;
 }
 
+// src/bus/transport-claims.ts
+var claims = /* @__PURE__ */ new WeakMap();
+function claimTransports(transports, declaring) {
+  const next = transports.map((transport) => {
+    const current = claims.get(transport) ?? { buses: 0, declared: false };
+    const claim = {
+      buses: current.buses + 1,
+      declared: current.declared || declaring.has(transport.name)
+    };
+    if (claim.buses > 1 && claim.declared) {
+      throw new WireTypesUnsupportedError(
+        `Transport '${transport.name}' is used by more than one bus, and wire names are declared for it; they would change what the other bus writes. Give each bus its own transport`
+      );
+    }
+    return [transport, claim];
+  });
+  return () => {
+    for (const [transport, claim] of next) {
+      claims.set(transport, claim);
+    }
+  };
+}
+
 // src/bus/bus-connections.ts
 var BusConnections = class {
   #parts;
   #transports = /* @__PURE__ */ new Map();
   #subscriptions;
+  #pendingWireTypes;
   constructor(parts, subscriptions) {
     this.#parts = parts;
     this.#subscriptions = subscriptions;
@@ -2787,13 +3003,22 @@ var BusConnections = class {
       }
       this.#transports.set(transport.name, transport);
     }
-    this.#registerRoutes(routes);
+    const { wireTypes } = this.#registerRoutes(expandRoutes(routes));
     for (const subscription of this.#subscriptions) {
       const transport = this.#requireTransport(subscription.transport);
       if (transport.subscribe === void 0) {
         throw new ConfigurationError(`Transport '${transport.name}' cannot subscribe`);
       }
     }
+    this.#pendingWireTypes = this.#prepareWireTypes(wireTypes);
+  }
+  /**
+   * Applies the wire names the routes declared. The bus calls it last, after every check of its
+   * options, so a refused configuration leaves the transports as they were.
+   */
+  commitWireTypes() {
+    this.#pendingWireTypes?.();
+    this.#pendingWireTypes = void 0;
   }
   /** True while every transport reports itself ready. */
   allReady() {
@@ -2838,18 +3063,42 @@ var BusConnections = class {
       }
     };
   }
-  #registerRoutes(routes) {
-    for (const route of routes) {
-      this.#requireTransport(route.transport);
+  #registerRoutes({ routes, wireTypes }) {
+    for (const route2 of routes) {
+      this.#requireTransport(route2.transport);
     }
     for (const group of groupRoutes(routes)) {
       this.#registerRoute(group);
     }
+    return { wireTypes };
+  }
+  /**
+   * Hands the wire names that catalog routes declare to the transports whose codecs write them:
+   * every transport checks its names first, then all apply them. A transport carries one wire
+   * format, so a transport that two buses use cannot take names declared by either of them.
+   */
+  #prepareWireTypes(wireTypes) {
+    const applies = [...wireTypes].map(([name, types]) => {
+      const transport = this.#transports.get(name);
+      if (transport.declareWireTypes === void 0) {
+        throw new WireTypesUnsupportedError(
+          `Transport '${name}' cannot map event types to wire names, but routes or catalogs declare them for: ${Object.keys(types).join(", ")}`
+        );
+      }
+      return transport.declareWireTypes(types);
+    });
+    const claim = claimTransports([...this.#transports.values()], new Set(wireTypes.keys()));
+    return () => {
+      for (const apply of applies) {
+        apply();
+      }
+      claim();
+    };
   }
   /** Registers one handler for every route to a destination, so a key's events reach it in commit order. */
   #registerRoute(group) {
     const transport = this.#transports.get(group.transport);
-    const { route, destination } = group;
+    const { route: route2, destination } = group;
     this.#parts.registry.register(
       {
         eventTypes: group.eventTypes,
@@ -2858,8 +3107,8 @@ var BusConnections = class {
         handle: this.#parts.observation?.sender(transport, destination) ?? ((envelope) => transport.publish(envelope, destination)),
         options: {
           id: group.id,
-          ...route.retry === void 0 ? {} : { retry: route.retry },
-          ...route.timeout === void 0 ? {} : { timeout: route.timeout }
+          ...route2.retry === void 0 ? {} : { retry: route2.retry },
+          ...route2.timeout === void 0 ? {} : { timeout: route2.timeout }
         },
         forwardsToTransport: true
       },
@@ -2992,25 +3241,37 @@ var EventPublisher = class {
     context,
     delayMs
   }) {
-    const { result, committed } = await this.#appendInTransaction(entries, context);
+    const { result, committed, transaction } = await this.#appendInTransaction(entries, context);
     const appended = new Set(result.appendedEventIds);
     const published = entries.map((entry) => entry.event).filter((envelope) => appended.has(envelope.id));
     if (published.length > 0) {
-      this.#parts.notifier.notify("onPublished", {
-        envelopes: published,
-        deliveries: result.appendedDeliveryCount
-      });
-      if (delayMs === 0) {
-        this.#parts.scheduleWake(committed);
+      const report = { envelopes: published, deliveries: result.appendedDeliveryCount };
+      const wake = delayMs === 0 ? committed : void 0;
+      const isolation = context.scope?.isolation;
+      if (!committed && isolation !== void 0 && isolation.transaction === transaction) {
+        isolation.afterCommit.push(() => this.#announce(report, wake));
+      } else {
+        this.#announce(report, wake);
       }
     }
   }
+  /** Tells the observers about a publish, and wakes the dispatcher (`wake` is `committed`) when the events are due now. */
+  #announce(report, wake) {
+    this.#parts.notifier.notify("onPublished", report);
+    if (wake !== void 0) {
+      this.#parts.scheduleWake(wake);
+    }
+  }
   /** Appends in the caller's transaction, else in one of the store's; `committed` tells which. */
   async #appendInTransaction(entries, { options, scope, now }) {
     const { store, transactionMode, transactionResolver } = this.#parts;
     const transaction = options.transaction ?? scope?.transaction ?? transactionResolver?.();
     if (transaction !== void 0) {
-      return { result: await store.append(transaction, entries, now), committed: false };
+      return {
+        result: await store.append(transaction, entries, now),
+        committed: false,
+        transaction
+      };
     }
     if (transactionMode === "required") {
       throw new TransactionRequiredError(
@@ -3020,7 +3281,7 @@ var EventPublisher = class {
     const result = await store.transaction(
       (ownTransaction) => store.append(ownTransaction, entries, now)
     );
-    return { result, committed: true };
+    return { result, committed: true, transaction: void 0 };
   }
   async #createEnvelope(input) {
     const { event, options, id, scope, now, correlationId } = input;
@@ -3147,6 +3408,8 @@ function assembleRelayBus(options, hooks) {
     settings,
     observation: DispatchObservation.create({ ...core, tracer: options.tracer })
   });
+  const inboxAndOutbox = createInboxAndOutbox(core, hooks);
+  connections.commitWireTypes();
   return {
     ...core,
     maintenance,
@@ -3155,7 +3418,7 @@ function assembleRelayBus(options, hooks) {
     dispatcherEnabled,
     shutdownTimeoutMs: settings.shutdownTimeoutMs,
     dispatcher,
-    ...createInboxAndOutbox(core, hooks)
+    ...inboxAndOutbox
   };
 }
 function resolveCore(options) {
@@ -3207,6 +3470,95 @@ function createInboxAndOutbox(core, hooks) {
   };
 }
 
+// src/transaction-budget.ts
+async function runBudgetedTransaction(store, { clock, timeoutMs, work, isolationLevel }) {
+  const startedAt = clock.now().getTime();
+  const overrun = () => clock.now().getTime() - startedAt >= timeoutMs;
+  let committing = false;
+  try {
+    return await store.transaction(
+      async (transaction) => {
+        committing = false;
+        const result = await work(transaction);
+        if (overrun()) {
+          throw createTimeoutError(timeoutMs, void 0);
+        }
+        committing = true;
+        return result;
+      },
+      isolationLevel === void 0 ? { timeoutMs } : { timeoutMs, isolationLevel }
+    );
+  } catch (error) {
+    if (error instanceof TransactionTimeoutError || committing || !overrun()) {
+      throw error;
+    }
+    throw createTimeoutError(timeoutMs, error);
+  }
+}
+function createTimeoutError(timeoutMs, cause) {
+  const message = `The transaction ran past its ${timeoutMs} ms budget (transactionTimeout) and was rolled back. The usual cause is a slow call to another service (HTTP, gRPC, a broker, a lock) inside the transaction: make external calls before the transaction starts or after it commits, or raise transactionTimeout`;
+  return cause === void 0 ? new TransactionTimeoutError(message) : new TransactionTimeoutError(`${message} | cause=${toErrorInfo(cause).message}`, { cause });
+}
+
+// src/isolated-transaction.ts
+var DEFAULT_ISOLATED_ATTEMPTS = 3;
+var RERUN_LEVELS = /* @__PURE__ */ new Set([
+  "repeatable read",
+  "serializable"
+]);
+async function runIsolatedTransaction({ store, clock, transactionTimeoutMs }, { options, work }) {
+  const { isolationLevel } = options;
+  assertSupported(store, options);
+  const maxAttempts = attemptsOf(options);
+  for (let attempt = 1; ; attempt += 1) {
+    const afterCommit = [];
+    let committed;
+    try {
+      committed = {
+        value: await runBudgetedTransaction(store, {
+          clock,
+          timeoutMs: transactionTimeoutMs,
+          isolationLevel,
+          work: (transaction) => runInScope(
+            { transaction, isolation: { transaction, level: isolationLevel, afterCommit } },
+            () => work(transaction)
+          )
+        })
+      };
+    } catch (error) {
+      if (attempt >= maxAttempts || error instanceof TransactionTimeoutError || store.isSerializationFailure?.(error) !== true) {
+        throw error;
+      }
+      continue;
+    }
+    for (const announce of afterCommit) {
+      announce();
+    }
+    return committed.value;
+  }
+}
+function attemptsOf({ isolationLevel, maxAttempts }) {
+  return RERUN_LEVELS.has(isolationLevel) ? maxAttempts ?? DEFAULT_ISOLATED_ATTEMPTS : 1;
+}
+function assertSupported(store, { isolationLevel, maxAttempts }) {
+  if (!TRANSACTION_ISOLATION_LEVELS.includes(isolationLevel)) {
+    throw new ConfigurationError(
+      `Unknown isolationLevel ${JSON.stringify(isolationLevel)}: use ${TRANSACTION_ISOLATION_LEVELS.map((level) => `'${level}'`).join(", ")}`
+    );
+  }
+  if (maxAttempts !== void 0 && !(Number.isInteger(maxAttempts) && maxAttempts >= 1)) {
+    throw new ConfigurationError(
+      `maxAttempts must be a positive integer, got ${String(maxAttempts)}`
+    );
+  }
+  if (store.isolationLevels?.includes(isolationLevel) !== true) {
+    const supported = store.isolationLevels ?? [];
+    throw new ConfigurationError(
+      `The event store does not support isolationLevel '${isolationLevel}' (supported: ${supported.length === 0 ? "none" : supported.join(", ")}). PostgreSQL stores support all levels; MongoDB and the in-memory store run transactions at their own level only`
+    );
+  }
+}
+
 // src/bus/publish-wake-ups.ts
 var FIRST_WAKE_MS = 25;
 var SECOND_WAKE_MS = 100;
@@ -3259,36 +3611,6 @@ var PublishWakeUps = class {
   }
 };
 
-// src/transaction-budget.ts
-async function runBudgetedTransaction(store, { clock, timeoutMs, work }) {
-  const startedAt = clock.now().getTime();
-  const overrun = () => clock.now().getTime() - startedAt >= timeoutMs;
-  let committing = false;
-  try {
-    return await store.transaction(
-      async (transaction) => {
-        committing = false;
-        const result = await work(transaction);
-        if (overrun()) {
-          throw createTimeoutError(timeoutMs, void 0);
-        }
-        committing = true;
-        return result;
-      },
-      { timeoutMs }
-    );
-  } catch (error) {
-    if (error instanceof TransactionTimeoutError || committing || !overrun()) {
-      throw error;
-    }
-    throw createTimeoutError(timeoutMs, error);
-  }
-}
-function createTimeoutError(timeoutMs, cause) {
-  const message = `The transaction ran past its ${timeoutMs} ms budget (transactionTimeout) and was rolled back. The usual cause is a slow call to another service (HTTP, gRPC, a broker, a lock) inside the transaction: make external calls before the transaction starts or after it commits, or raise transactionTimeout`;
-  return cause === void 0 ? new TransactionTimeoutError(message) : new TransactionTimeoutError(`${message} | cause=${toErrorInfo(cause).message}`, { cause });
-}
-
 // src/relay-bus.ts
 var DEFAULT_DRAIN_BATCHES = 1e3;
 var RelayBus = class {
@@ -3380,8 +3702,16 @@ var RelayBus = class {
    * 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.
    */
-  async transaction(work) {
+  async transaction(work, options) {
+    if (options?.isolationLevel !== void 0) {
+      return runIsolatedTransaction(this.#parts, { options, work });
+    }
     return runBudgetedTransaction(this.#parts.store, {
       clock: this.#parts.clock,
       timeoutMs: this.#parts.transactionTimeoutMs,
@@ -3396,6 +3726,15 @@ var RelayBus = class {
   currentTransaction() {
     return getCurrentScope()?.transaction ?? this.#parts.transactionResolver?.();
   }
+  /**
+   * 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() {
+    return getCurrentIsolationLevel();
+  }
   /**
    * 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
@@ -3509,7 +3848,7 @@ var RelayBus = class {
         );
       }
     } catch (error) {
-      await this.#closeAfterFailedStart();
+      await this.#lifecycle.closeAfterFailedStart(this.#parts.shutdownTimeoutMs);
       this.#lifecycle.markStopped();
       throw error;
     }
@@ -3525,16 +3864,6 @@ var RelayBus = class {
       `[RelayBus](startComponents) relaybus started | handlers=${this.#parts.registry.all().length} dispatcher=${this.#parts.dispatcherEnabled}`
     );
   }
-  /** Closes the transports a failed start may have connected, within the shutdown timeout. */
-  #closeAfterFailedStart() {
-    return withinDeadline(
-      { clock: this.#parts.clock, timeoutMs: this.#parts.shutdownTimeoutMs },
-      async (deadline) => {
-        await this.#closeTransports(deadline);
-        return 0;
-      }
-    );
-  }
   #reportUnrouted(envelope) {
     const message = `No handler or route for event type, event not stored | type=${envelope.type} id=${envelope.id}`;
     if (this.#parts.unroutedEvents === "throw") {
@@ -3568,6 +3897,6 @@ var RelayBus = class {
   }
 };
 
-export { CatalogPublisher, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DELIVERY_STATUSES, InMemoryEventStore, InMemoryTransaction, RelayBus, TRACEPARENT_HEADER, TRACESTATE_HEADER, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, systemClock, traceContextOf };
+export { CatalogPublisher, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DELIVERY_STATUSES, InMemoryEventStore, InMemoryTransaction, RelayBus, TRACEPARENT_HEADER, TRACESTATE_HEADER, TRANSACTION_ISOLATION_LEVELS, catalogWireTypes, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, route, systemClock, traceContextOf };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map