@relaybus/core 0.0.0 → 0.2.0

package/dist/index.cjs

@@ -36,6 +36,15 @@ var InvalidEnvelopeError = class extends NonRetryableError {
 };
 var LeaseLostError = class extends RelayBusError {
   name = "LeaseLostError";
+  /**
+   * 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.
+   */
+  storeConfirmed;
+  constructor(message, options = {}) {
+    super(message);
+    this.storeConfirmed = options.storeConfirmed ?? false;
+  }
 };
 var HandlerTimeoutError = class extends RelayBusError {
   name = "HandlerTimeoutError";
@@ -141,6 +150,261 @@ async function validatePayload(type, schema, payload) {
   return result.value;
 }
 
+// src/catalog.ts
+var EVENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var descriptions = /* @__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 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`
+      );
+    }
+    assertEventType(eventClass.type);
+    const owner = owners.get(eventClass.type);
+    if (owner !== void 0) {
+      throw new ConfigurationError(
+        `${label} entries '${owner}' and '${name}' share the event type '${eventClass.type}'`
+      );
+    }
+    owners.set(eventClass.type, name);
+    return Object.freeze({ name, eventClass, type: eventClass.type, handlerName: `on${name}` });
+  });
+  const catalog = Object.freeze({ ...events });
+  descriptions.set(catalog, Object.freeze({ name: options.name, entries: Object.freeze(entries) }));
+  return catalog;
+}
+function describeCatalog(catalog) {
+  const description = descriptions.get(catalog);
+  if (description === void 0) {
+    throw new ConfigurationError("Expected a catalog created with defineCatalog");
+  }
+  return description;
+}
+function catalogLabel(catalog) {
+  const { name } = describeCatalog(catalog);
+  return name === void 0 ? "the catalog" : `catalog '${name}'`;
+}
+function selectCatalogEntries(catalog, events) {
+  const { entries } = describeCatalog(catalog);
+  if (events === void 0) {
+    return entries;
+  }
+  const label = catalogLabel(catalog);
+  if (events.length === 0) {
+    throw new ConfigurationError(
+      `The events selected from ${label} must name at least one event; omit events to select all of them`
+    );
+  }
+  const selected = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (!entries.some((entry) => entry.name === event)) {
+      throw new ConfigurationError(
+        `${capitalize(label)} has no event named '${String(event)}'; its events are ${entries.map((entry) => entry.name).join(", ")}`
+      );
+    }
+    if (selected.has(event)) {
+      throw new ConfigurationError(`Event '${String(event)}' of ${label} is selected twice`);
+    }
+    selected.add(event);
+  }
+  return entries.filter((entry) => selected.has(entry.name));
+}
+function capitalize(text) {
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+function requireCatalogEntry(catalog, event) {
+  const entry = describeCatalog(catalog).entries.find((candidate) => candidate.type === event.type);
+  if (entry === void 0) {
+    throw new ConfigurationError(
+      `Event type '${String(event.type)}' is not part of ${catalogLabel(catalog)}`
+    );
+  }
+  return entry;
+}
+function resolveCatalogHandlers(catalog, handlers, options) {
+  const { name } = describeCatalog(catalog);
+  const { idPrefix, events, ...subscribeOptions } = options;
+  const entries = selectCatalogEntries(catalog, events);
+  const lookup = handlers;
+  const missing = entries.filter((entry) => typeof lookup[entry.handlerName] !== "function");
+  if (missing.length > 0) {
+    throw new ConfigurationError(
+      `Handlers for catalog ${name === void 0 ? "events" : `'${name}'`} lack methods: ${missing.map((entry) => entry.handlerName).join(", ")}`
+    );
+  }
+  const prefix = idPrefix ?? name ?? classNameOf(handlers);
+  if (prefix === void 0) {
+    throw new ConfigurationError(
+      "Cannot derive handler ids: name the catalog, pass an idPrefix or use a class instance as handlers"
+    );
+  }
+  return entries.map((entry) => {
+    const method = lookup[entry.handlerName];
+    return {
+      eventClass: entry.eventClass,
+      handle: (envelope, context) => method.call(handlers, envelope, context),
+      options: { ...subscribeOptions, id: `${prefix}.${entry.handlerName}` }
+    };
+  });
+}
+function classNameOf(handlers) {
+  const className = handlers.constructor.name;
+  return className === "Object" || className === "" ? void 0 : className;
+}
+function assertExactHandlers(catalog, entries, handlers) {
+  const expected = new Set(entries.map((entry) => entry.handlerName));
+  const present = Object.keys(handlers);
+  const missing = [...expected].filter((handlerName) => !present.includes(handlerName));
+  const extra = present.filter((key) => !expected.has(key));
+  const notFunctions = present.filter(
+    (key) => expected.has(key) && typeof handlers[key] !== "function"
+  );
+  if (missing.length + extra.length + notFunctions.length > 0) {
+    const problems = [
+      ...missing.map((key) => `missing ${key}`),
+      ...extra.map((key) => `unexpected ${key}`),
+      ...notFunctions.map((key) => `${key} is not a function`)
+    ];
+    throw new ConfigurationError(
+      `Handlers do not match ${catalogLabel(catalog)}: ${problems.join(", ")}`
+    );
+  }
+}
+function defineHandlers(catalog, handlers, options = {}) {
+  assertExactHandlers(catalog, selectCatalogEntries(catalog, options.events), handlers);
+  return handlers;
+}
+
+// src/catalog-publisher.ts
+var CatalogPublisher = class {
+  #catalog;
+  #target;
+  #entries;
+  /**
+   * Whether the view publishes the event named `eventName`. Its parameter
+   * makes a view of some events unassignable to a view of more events, which
+   * the bivariant method parameters alone would allow.
+   */
+  #publishes;
+  /**
+   * 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, target, options = {}) {
+    this.#entries = selectCatalogEntries(catalog, options.events);
+    const names = new Set(this.#entries.map((entry) => entry.name));
+    this.#publishes = (eventName) => names.has(eventName);
+    this.#catalog = catalog;
+    this.#target = target;
+  }
+  /** Same as `bus.publish`, limited to the events of the view. */
+  async publish(event, options) {
+    this.#assertPublishable(event);
+    return this.#target.publish(event, options);
+  }
+  /** Same as `bus.publishAll`, limited to the events of the view. Nothing is stored unless every event belongs to it. */
+  async publishAll(events, options) {
+    for (const event of events) {
+      this.#assertPublishable(event);
+    }
+    return this.#target.publishAll(events, options);
+  }
+  #assertPublishable(event) {
+    const { name } = requireCatalogEntry(this.#catalog, event);
+    if (!this.#publishes(name)) {
+      throw new ConfigurationError(
+        `Event type '${event.type}' is not one of the events this view of ${catalogLabel(
+          this.#catalog
+        )} publishes (${this.#entries.map((entry) => entry.name).join(", ")})`
+      );
+    }
+  }
+};
+
+// src/catalog-coverage.ts
+var declarations = /* @__PURE__ */ new WeakSet();
+function consume(catalog, options = {}) {
+  return declare(catalog, "consume", options);
+}
+function produce(catalog, options = {}) {
+  return declare(catalog, "produce", options);
+}
+function declare(catalog, role, options) {
+  const entries = selectCatalogEntries(catalog, options.events);
+  const declaration = Object.freeze({
+    catalog,
+    role,
+    events: Object.freeze(entries.map((entry) => entry.name)),
+    entries
+  });
+  declarations.add(declaration);
+  return declaration;
+}
+function toCatalogRequirement(value) {
+  if (declarations.has(value)) {
+    const declaration = value;
+    return {
+      catalogName: describeCatalog(declaration.catalog).name,
+      entries: declaration.entries,
+      need: declaration.role === "consume" ? "handler" : "route"
+    };
+  }
+  const { name, entries } = describeCatalog(value);
+  return { catalogName: name, entries, need: "handler-or-route" };
+}
+function assertCatalogsCovered(requirements, registrationsOf) {
+  const problems = /* @__PURE__ */ new Set();
+  let onlyBareCatalogs = true;
+  for (const { catalogName, entries, need } of requirements) {
+    for (const entry of entries) {
+      const problem = describeGap(entry, need, registrationsOf(entry.type));
+      if (problem !== void 0) {
+        problems.add(`${catalogName === void 0 ? "" : `${catalogName}.`}${problem}`);
+        onlyBareCatalogs &&= need === "handler-or-route";
+      }
+    }
+  }
+  if (problems.size > 0) {
+    const heading = onlyBareCatalogs ? "Catalog events without a handler or route:" : "Catalog events this service does not cover:";
+    throw new ConfigurationError(
+      `${heading}
+${[...problems].map((line) => `  - ${line}`).join("\n")}`
+    );
+  }
+}
+function describeGap(entry, need, { handlers, routes }) {
+  const subject = `${entry.name} (${entry.type})`;
+  if (need === "handler-or-route") {
+    return handlers + routes > 0 ? void 0 : `${subject}: expected handler method ${entry.handlerName}`;
+  }
+  if (need === "handler") {
+    if (handlers > 0) {
+      return void 0;
+    }
+    const routeNote = routes > 0 ? "; its route to a transport does not handle it here" : "";
+    return `${subject}: consumed here, needs handler method ${entry.handlerName}${routeNote}`;
+  }
+  if (routes > 0) {
+    return void 0;
+  }
+  const handlerNote = handlers > 0 ? "; a local handler does not deliver it to other services" : "";
+  return `${subject}: produced here, needs a route to a transport${handlerNote}`;
+}
+
 // src/event-store.ts
 var DELIVERY_STATUSES = [
   "pending",
@@ -202,7 +466,9 @@ var InMemoryEventStore = class {
   #keySequences = /* @__PURE__ */ new Map();
   /** Row-lock emulation: event ids and ordering keys written by open transactions. */
   #locks = /* @__PURE__ */ new Map();
+  #writes = /* @__PURE__ */ new WeakMap();
   #generateIdentifier;
+  #retainCompleted;
   constructor(options = {}) {
     if (process.env["NODE_ENV"] === "production" && options.allowInProduction !== true) {
       throw new ConfigurationError(
@@ -210,6 +476,7 @@ var InMemoryEventStore = class {
       );
     }
     this.#generateIdentifier = options.generateIdentifier ?? (() => createUuidV7());
+    this.#retainCompleted = options.retainCompleted ?? false;
   }
   async transaction(work) {
     const transaction = new InMemoryTransaction();
@@ -230,13 +497,15 @@ var InMemoryEventStore = class {
         ...entry.event.key === null ? [] : [`key:${entry.event.key}`]
       ])
     );
-    const pendingEventIds = /* @__PURE__ */ new Set();
-    const pendingDeliveryKeys = /* @__PURE__ */ new Set();
+    const written = this.#written(transaction);
+    const pendingEventIds = written.eventIds;
+    const pendingDeliveryKeys = written.deliveryKeys;
     const appendedEventIds = [];
     const duplicateEventIds = [];
     let appendedDeliveryCount = 0;
     for (const entry of entries) {
       const eventId = entry.event.id;
+      const serialized = serializeEnvelope(entry.event);
       const isDuplicate = this.#events.has(eventId) || pendingEventIds.has(eventId);
       if (isDuplicate) {
         duplicateEventIds.push(eventId);
@@ -246,23 +515,26 @@ var InMemoryEventStore = class {
       }
       const newDeliveries = entry.deliveries.filter((delivery) => {
         const deliveryKey = `${eventId}\0${delivery.handler}`;
-        if (pendingDeliveryKeys.has(deliveryKey) || this.#hasDelivery(eventId, delivery.handler)) {
+        if (pendingDeliveryKeys.has(deliveryKey) || this.#events.get(eventId)?.handlers.has(delivery.handler) === true) {
           return false;
         }
         pendingDeliveryKeys.add(deliveryKey);
         return true;
       });
       appendedDeliveryCount += newDeliveries.length;
-      const serialized = serializeEnvelope(entry.event);
       transaction.enqueue(() => {
         if (!isDuplicate) {
           this.#events.set(eventId, {
             envelope: serialized,
-            sequence: this.#nextSequence(serialized.key)
+            sequence: this.#nextSequence(serialized.key),
+            createdAt: now,
+            handlers: /* @__PURE__ */ new Set(),
+            completedAt: null
           });
         }
         const stored = this.#events.get(eventId);
         for (const delivery of newDeliveries) {
+          stored.handlers.add(delivery.handler);
           this.#deliveries.set(delivery.id, {
             id: delivery.id,
             eventId,
@@ -320,14 +592,8 @@ var InMemoryEventStore = class {
     });
   }
   async complete(lease, now, transaction) {
-    const finish = (delivery) => {
-      delivery.status = "completed";
-      delivery.completedAt = now;
-      delivery.updatedAt = now;
-      clearLease(delivery);
-    };
     if (transaction === void 0) {
-      return this.#updateLeased(lease, finish);
+      return this.#updateLeased(lease, (delivery) => this.#finish(delivery, now));
     }
     if (this.#findLeased(lease) === void 0) {
       return false;
@@ -335,11 +601,14 @@ var InMemoryEventStore = class {
     transaction.enqueue(() => {
       const delivery = this.#findLeased(lease);
       if (delivery !== void 0) {
-        finish(delivery);
+        this.#finish(delivery, now);
       }
     });
     return true;
   }
+  async completeMany(leases, now) {
+    return Promise.all(leases.map((lease) => this.complete(lease, now)));
+  }
   async reschedule(lease, availableAt, error, now) {
     return this.#updateLeased(lease, (delivery) => {
       delivery.status = "pending";
@@ -413,9 +682,16 @@ var InMemoryEventStore = class {
     const referencedEventIds = new Set(
       [...this.#deliveries.values()].map((delivery) => delivery.eventId)
     );
+    const cutoffs = [request.completedBefore, request.deadBefore].filter((cutoff) => cutoff !== void 0).map((cutoff) => cutoff.getTime());
+    const orphanCutoff = cutoffs.length === 0 ? Number.NEGATIVE_INFINITY : Math.min(...cutoffs);
+    const completedCutoff = request.completedBefore?.getTime() ?? Number.NEGATIVE_INFINITY;
     let deletedEvents = 0;
-    for (const eventId of touchedEventIds) {
-      if (!referencedEventIds.has(eventId)) {
+    for (const [eventId, event] of [...this.#events]) {
+      if (referencedEventIds.has(eventId) || this.#locks.has(`event:${eventId}`)) {
+        continue;
+      }
+      const expired = event.completedAt === null ? touchedEventIds.has(eventId) || event.createdAt.getTime() < orphanCutoff : event.completedAt.getTime() < completedCutoff;
+      if (expired) {
         this.#events.delete(eventId);
         deletedEvents += 1;
       }
@@ -446,6 +722,15 @@ var InMemoryEventStore = class {
    * until `transaction` finishes, the way a database holds row locks. Sorted
    * acquisition keeps two transactions from waiting on each other.
    */
+  /** The events and deliveries the transaction appended so far, which are not applied before it commits. */
+  #written(transaction) {
+    let written = this.#writes.get(transaction);
+    if (written === void 0) {
+      written = { eventIds: /* @__PURE__ */ new Set(), deliveryKeys: /* @__PURE__ */ new Set() };
+      this.#writes.set(transaction, written);
+    }
+    return written;
+  }
   async #lock(transaction, names) {
     for (const name of [...new Set(names)].sort()) {
       let held = this.#locks.get(name);
@@ -467,14 +752,6 @@ var InMemoryEventStore = class {
       });
     }
   }
-  #hasDelivery(eventId, handler) {
-    for (const delivery of this.#deliveries.values()) {
-      if (delivery.eventId === eventId && delivery.handler === handler) {
-        return true;
-      }
-    }
-    return false;
-  }
   #nextSequence(key) {
     if (key === null) {
       return null;
@@ -505,6 +782,21 @@ var InMemoryEventStore = class {
     }
     return false;
   }
+  /** Deletes a completed delivery, or marks it completed when a history is kept. */
+  #finish(delivery, now) {
+    const event = this.#events.get(delivery.eventId);
+    if (event.completedAt === null || event.completedAt < now) {
+      event.completedAt = now;
+    }
+    if (!this.#retainCompleted) {
+      this.#deliveries.delete(delivery.id);
+      return;
+    }
+    delivery.status = "completed";
+    delivery.completedAt = now;
+    delivery.updatedAt = now;
+    clearLease(delivery);
+  }
   #findLeased(lease) {
     const delivery = this.#deliveries.get(lease.deliveryId);
     if (delivery?.status === "processing" && delivery.leaseToken === lease.leaseToken) {
@@ -562,6 +854,66 @@ function isPurgeable(delivery, request) {
   }
   return false;
 }
+
+// src/completion-batcher.ts
+var CompletionBatcher = class {
+  #store;
+  #clock;
+  #settings;
+  #runningCount;
+  #pending = [];
+  #timer;
+  #closing = false;
+  /**
+   * @param runningCount Number of deliveries the dispatcher is running right
+   * now, including the ones waiting in this batcher.
+   */
+  constructor(store, clock, settings, runningCount) {
+    this.#store = store;
+    this.#clock = clock;
+    this.#settings = settings;
+    this.#runningCount = runningCount;
+  }
+  /**
+   * Queues a completion. Resolves with whether the lease was still held;
+   * rejects with the store error when the batch could not be written.
+   */
+  submit(lease) {
+    return new Promise((resolve, reject) => {
+      this.#pending.push({ lease, resolve, reject });
+      if (this.#closing || this.#pending.length >= this.#settings.maxBatchSize || this.#pending.length >= this.#runningCount()) {
+        this.#flush();
+      } else {
+        this.#timer ??= setTimeout(() => this.#flush(), this.#settings.windowMs);
+      }
+    });
+  }
+  /**
+   * Shutdown has begun (or ended): while closing, nothing waits for company any more, so the completions
+   * already queued are written now and later ones at once.
+   */
+  setClosing(closing) {
+    this.#closing = closing;
+    if (closing && this.#pending.length > 0) {
+      this.#flush();
+    }
+  }
+  #flush() {
+    clearTimeout(this.#timer);
+    this.#timer = void 0;
+    const batch = this.#pending;
+    this.#pending = [];
+    Promise.resolve().then(
+      () => this.#store.completeMany(
+        batch.map((entry) => entry.lease),
+        this.#clock.now()
+      )
+    ).then(
+      (outcomes) => batch.forEach((entry, index) => entry.resolve(outcomes[index])),
+      (error) => batch.forEach((entry) => entry.reject(error))
+    );
+  }
+};
 var storage = new async_hooks.AsyncLocalStorage();
 function runInScope(scope, work) {
   return storage.run({ ...storage.getStore(), ...scope }, work);
@@ -650,18 +1002,51 @@ function isRetryableError(policy, error) {
 
 // src/dispatcher.ts
 var COMPLETION_RETRY_DELAYS_MS = [50, 250, 1e3];
+var WAKE_COOLDOWN_MS = 5;
+var QUIET_REFILL_MS = 10;
+var REFILL_FRACTION = 0.7;
 var defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 var Dispatcher = class {
   #dependencies;
   #sleep;
   #inFlight = /* @__PURE__ */ new Set();
+  #completions;
+  #pending = /* @__PURE__ */ new Map();
+  #recoveryTimer;
+  #recovery;
   #running = false;
   #loop;
   #wakeUp;
-  #wakeRequested = false;
+  /** Free slots the claim the loop was woken for needs at least; undefined while nobody woke it. */
+  #signalledMinimum;
+  /** Free slots a claim needs unless the poll interval or the quiet refill time passed: claims refill in groups. */
+  #refillThreshold;
+  /** Handlers whose last claim got less than it asked for: the store has nothing more for them right now. */
+  #exhaustedHandlers = /* @__PURE__ */ new Set();
+  /** Grows with every wake-up: a claim that started before one must not mark a handler exhausted. */
+  #wakeGeneration = 0;
+  #lastClaimStartedAt = Number.NEGATIVE_INFINITY;
+  #cooldownTimer;
+  #refillScheduled = false;
+  #quietRefillTimer;
+  #unwatch;
+  #watching;
   constructor(dependencies) {
     this.#dependencies = dependencies;
     this.#sleep = dependencies.sleep ?? defaultSleep;
+    const { store, clock, settings } = dependencies;
+    this.#refillThreshold = Math.ceil(
+      Math.min(settings.concurrency, settings.batchSize) * REFILL_FRACTION
+    );
+    const { completionBatchWindowMs: windowMs = 0, completionBatchSize: maxBatchSize = 1 } = settings;
+    if (store.completeMany !== void 0 && windowMs > 0) {
+      this.#completions = new CompletionBatcher(
+        { completeMany: (leases, now) => store.completeMany(leases, now) },
+        clock,
+        { windowMs, maxBatchSize },
+        () => this.#inFlight.size
+      );
+    }
   }
   get isRunning() {
     return this.#running;
@@ -669,29 +1054,93 @@ var Dispatcher = class {
   get inFlightCount() {
     return this.#inFlight.size;
   }
+  /**
+   * True while the store reports new deliveries to this dispatcher by itself (see
+   * {@link EventStore.watchNewDeliveries}), from every process: a publisher then has no reason to wake it.
+   */
+  get watchesNewDeliveries() {
+    return this.#unwatch !== void 0;
+  }
   start() {
     if (this.#running) {
       return;
     }
     this.#running = true;
+    this.#completions?.setClosing(false);
+    this.#watching = this.#watchNewDeliveries();
     this.#loop = this.#runLoop();
   }
-  /** Shortens the wait before the next claim, for example right after a publish. */
+  /**
+   * Asks for a claim soon, for example right after a publish: at once after a quiet period, otherwise
+   * at the end of a short cooldown that merges the wake-ups arriving meanwhile into one claim.
+   */
   wake() {
-    this.#wakeRequested = true;
+    this.#exhaustedHandlers.clear();
+    this.#wakeGeneration += 1;
+    const wait = this.#lastClaimStartedAt + WAKE_COOLDOWN_MS - Date.now();
+    if (wait <= 0) {
+      this.#requestClaim();
+      return;
+    }
+    this.#cooldownTimer ??= setTimeout(() => {
+      this.#cooldownTimer = void 0;
+      this.#requestClaim();
+    }, wait);
+  }
+  /** Ends the current wait of the claim loop, or the next one at once, for a claim once `minimumFree` slots are free. */
+  #signal(minimumFree) {
+    this.#signalledMinimum = Math.min(this.#signalledMinimum ?? minimumFree, minimumFree);
     this.#wakeUp?.();
   }
+  /**
+   * Starts listening to the store's reports of new deliveries. Polling stays the safety net: a store
+   * that cannot listen, or fails to, only costs latency, so a failure is reported and otherwise ignored.
+   */
+  async #watchNewDeliveries() {
+    const { store, notifier } = this.#dependencies;
+    try {
+      const unwatch = await store.watchNewDeliveries?.(() => this.wake());
+      if (unwatch !== void 0 && !this.#running) {
+        await unwatch();
+        return;
+      }
+      this.#unwatch = unwatch;
+      if (unwatch !== void 0) {
+        this.wake();
+      }
+    } catch (error) {
+      notifier.failure("watch", error);
+    }
+  }
+  /** Stops listening to the store's reports of new deliveries. */
+  async #stopWatching() {
+    await this.#watching;
+    const unwatch = this.#unwatch;
+    this.#unwatch = void 0;
+    try {
+      await unwatch?.();
+    } catch (error) {
+      this.#dependencies.notifier.failure("watch", error);
+    }
+  }
   /**
    * Stops claiming, waits up to the shutdown timeout for running handlers,
    * then aborts the rest and releases their deliveries for another process.
    */
   async stop() {
     if (!this.#running) {
+      await this.#closeRecovery(Date.now() + this.#dependencies.settings.shutdownTimeoutMs);
       return;
     }
     this.#running = false;
-    this.wake();
+    this.#completions?.setClosing(true);
+    clearTimeout(this.#cooldownTimer);
+    this.#cooldownTimer = void 0;
+    clearTimeout(this.#quietRefillTimer);
+    this.#quietRefillTimer = void 0;
+    this.#signal(this.#refillThreshold);
     const deadline = Date.now() + this.#dependencies.settings.shutdownTimeoutMs;
+    await this.#waitUntil(this.#stopWatching(), deadline);
     await this.#waitUntil(this.#loop, deadline);
     const settled = Promise.allSettled([...this.#inFlight].map((delivery) => delivery.settled));
     if (await this.#waitUntil(settled, deadline) === "timeout") {
@@ -700,10 +1149,71 @@ var Dispatcher = class {
       }
       await settled;
     }
+    await this.#closeRecovery(deadline);
+    await this.#waitUntil(this.#relinquish(), deadline);
+  }
+  /**
+   * Gives the settlements still pending one last try and forgets them. A pass of the timer may be inside the
+   * store: it ends before the last pass starts. A store that does not answer before the deadline gets no
+   * further call, since it may be closed right after.
+   */
+  async #closeRecovery(deadline) {
+    clearInterval(this.#recoveryTimer);
+    this.#recoveryTimer = void 0;
+    const lastTry = (async () => {
+      await this.#recovery;
+      await this.#recoverSettlements();
+    })();
+    await this.#waitUntil(lastTry, deadline);
+    this.#pending.clear();
+  }
+  /**
+   * Retries every pending settlement once; a pass that is already running is the one returned. A store that
+   * still fails leaves the settlement for the next attempt (it was reported when it first failed).
+   */
+  #recoverSettlements() {
+    this.#recovery ??= this.#recoverAll().finally(() => {
+      this.#recovery = void 0;
+    });
+    return this.#recovery;
+  }
+  async #recoverAll() {
+    for (const [key, entry] of [...this.#pending]) {
+      if (this.#pending.get(key) !== entry) {
+        continue;
+      }
+      try {
+        const applied = await entry.settle();
+        this.#pending.delete(pendingKey(entry.delivery));
+        if (applied) {
+          entry.applied();
+        } else {
+          this.#dependencies.notifier.notify("onLeaseLost", { delivery: entry.delivery });
+        }
+      } catch {
+      }
+    }
+  }
+  #retain(entry) {
+    this.#pending.set(pendingKey(entry.delivery), entry);
+    this.#recoveryTimer ??= setInterval(
+      () => void this.#recoverSettlements(),
+      this.#dependencies.settings.pollIntervalMs
+    );
+    this.#recoveryTimer.unref();
+  }
+  /** Gives lease groups the owner no longer works on back to the store, so other workers need not wait for expiry. */
+  async #relinquish() {
+    const { store, clock, notifier, settings } = this.#dependencies;
+    try {
+      await store.relinquish?.(settings.owner, clock.now());
+    } catch (error) {
+      notifier.failure("relinquish", error);
+    }
   }
   /** Claims one batch and resolves when every claimed delivery settled. Returns how many ran. */
   async processBatch() {
-    const started = await this.#claimAndStart();
+    const { started } = await this.#claimAndStart();
     await Promise.allSettled(started.map((delivery) => delivery.settled));
     return started.length;
   }
@@ -716,44 +1226,102 @@ var Dispatcher = class {
     clearTimeout(timer);
     return outcome;
   }
+  /**
+   * Claims until stopped. A claim that filled its batch is followed by the next one at once while enough
+   * slots are free. Otherwise the loop sleeps until a wake-up (a publish, a store notification, or enough
+   * deliveries settling to refill a group of slots) or the poll interval. Only the poll interval claims
+   * for fewer free slots than the refill threshold, so a busy dispatcher never claims slot by slot.
+   */
   async #runLoop() {
+    let minimumFree = 1;
     while (this.#running) {
-      let claimedCount = 0;
-      try {
-        claimedCount = (await this.#claimAndStart()).length;
-      } catch (error) {
-        this.#dependencies.notifier.failure("claim", error);
+      let round = { requested: 0, claimed: 0 };
+      if (this.#freeSlots() >= minimumFree) {
+        try {
+          round = await this.#claimAndStart();
+        } catch (error) {
+          this.#dependencies.notifier.failure("claim", error);
+        }
       }
-      if (claimedCount > 0 && this.#freeSlots() > 0) {
+      if (round.requested > 0 && round.claimed === round.requested && this.#freeSlots() >= this.#refillThreshold) {
+        minimumFree = this.#refillThreshold;
         continue;
       }
-      await this.#waitForWakeUp();
+      minimumFree = await this.#waitForWakeUp();
+      if (this.#freeSlots() < minimumFree) {
+        this.#requestClaim();
+      }
     }
   }
+  /** Waits for a wake-up or the poll interval. Resolves with the free slots the next claim needs. */
   async #waitForWakeUp() {
-    if (this.#wakeRequested) {
-      this.#wakeRequested = false;
-      return;
+    if (this.#signalledMinimum === void 0) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          this.#signalledMinimum = 1;
+          resolve();
+        }, this.#dependencies.settings.pollIntervalMs);
+        this.#wakeUp = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+      this.#wakeUp = void 0;
+    }
+    const minimumFree = this.#signalledMinimum;
+    this.#signalledMinimum = void 0;
+    return minimumFree;
+  }
+  /**
+   * A delivery settled. Its slot is worth refilling when the store may have more for its handler: a keyed
+   * delivery unblocks the next one of its key, a delivery that did not succeed may be due again at once
+   * (a retry without delay, a release), and a handler whose last claim was full may have a backlog.
+   */
+  #onSettled(delivery, succeeded) {
+    if (delivery.event.key !== null || !succeeded || !this.#exhaustedHandlers.has(delivery.handler)) {
+      this.#requestClaim();
     }
-    await new Promise((resolve) => {
-      const timer = setTimeout(done, this.#dependencies.settings.pollIntervalMs);
-      function done() {
-        clearTimeout(timer);
-        resolve();
+  }
+  /**
+   * Asks the loop for a claim. Once a group of slots is free the claim waits only for the deliveries
+   * settling in the same tick, so they are claimed for together; fewer free slots are refilled when no
+   * claim started for a short while. With no free slot the next settlement asks again.
+   */
+  #requestClaim() {
+    const free = this.#freeSlots();
+    if (free >= this.#refillThreshold) {
+      if (!this.#refillScheduled) {
+        this.#refillScheduled = true;
+        setImmediate(() => {
+          this.#refillScheduled = false;
+          this.#signal(this.#refillThreshold);
+        });
       }
-      this.#wakeUp = done;
-    });
-    this.#wakeUp = void 0;
-    this.#wakeRequested = false;
+    } else if (free > 0) {
+      this.#quietRefillTimer ??= setTimeout(
+        () => {
+          this.#quietRefillTimer = void 0;
+          this.#signal(1);
+        },
+        Math.max(0, this.#lastClaimStartedAt + QUIET_REFILL_MS - Date.now())
+      );
+    }
   }
   #freeSlots() {
     return this.#dependencies.settings.concurrency - this.#inFlight.size;
   }
+  /** Claims for every handler with room and starts what was claimed. */
   async #claimAndStart() {
     const { store, registry, clock, settings } = this.#dependencies;
     const started = [];
+    let requested = 0;
     for (const request of this.#planClaims(registry.all())) {
       const now = clock.now();
+      const wakeGeneration = this.#wakeGeneration;
+      this.#lastClaimStartedAt = Date.now();
+      clearTimeout(this.#quietRefillTimer);
+      this.#quietRefillTimer = void 0;
+      requested += request.limit;
       const claimed = await store.claim({
         handlers: request.handlers,
         limit: request.limit,
@@ -761,11 +1329,18 @@ var Dispatcher = class {
         leaseExpiresAt: new Date(now.getTime() + settings.leaseDurationMs),
         now
       });
+      for (const handler of request.handlers) {
+        if (claimed.length < request.limit && wakeGeneration === this.#wakeGeneration) {
+          this.#exhaustedHandlers.add(handler);
+        } else {
+          this.#exhaustedHandlers.delete(handler);
+        }
+      }
       for (const delivery of claimed) {
         started.push(this.#start(delivery));
       }
     }
-    return started;
+    return { requested, claimed: started.length, started };
   }
   /** One claim for handlers without a concurrency limit, one per limited handler with room. */
   #planClaims(registrations) {
@@ -799,20 +1374,29 @@ var Dispatcher = class {
   }
   #start(delivery) {
     const controller = new AbortController();
+    let succeeded = false;
     const entry = {
       handler: delivery.handler,
       controller,
-      settled: Promise.resolve().then(() => this.#execute(delivery, controller)).catch((error) => this.#dependencies.notifier.failure("dispatch", error)).finally(() => {
+      settled: Promise.resolve().then(async () => {
+        succeeded = await this.#execute(delivery, controller);
+      }).catch((error) => this.#dependencies.notifier.failure("dispatch", error)).finally(() => {
         this.#inFlight.delete(entry);
-        this.wake();
+        this.#onSettled(delivery, succeeded);
       })
     };
     this.#inFlight.add(entry);
     return entry;
   }
+  /** Runs one delivery. Resolves true when its handler succeeded, so the delivery is done for good. */
   async #execute(delivery, controller) {
     const { registry, notifier, clock } = this.#dependencies;
     const registration = registry.get(delivery.handler);
+    for (const key of [...this.#pending.keys()].filter(
+      (pending) => pending.startsWith(`${delivery.deliveryId}\0`)
+    )) {
+      this.#pending.delete(key);
+    }
     notifier.notify("onDeliveryStarted", { delivery });
     const startedAt = clock.now().getTime();
     if (delivery.attempt > registration.retry.attempts) {
@@ -822,26 +1406,35 @@ var Dispatcher = class {
           `Delivery reached attempt ${delivery.attempt} of ${registration.retry.attempts} after its lease expired`
         )
       );
-      return;
+      return false;
     }
     let stopHeartbeat = () => void 0;
     try {
       stopHeartbeat = registration.transactional ? await this.#guardTransactionalLease(registration, delivery, controller) : this.#startHeartbeat(delivery, controller);
       const outcome = await this.#runHandler(registration, delivery, controller);
+      const durationMs = clock.now().getTime() - startedAt;
       if (outcome === "completed") {
-        notifier.notify("onDeliverySucceeded", {
+        notifier.notify("onDeliverySucceeded", { delivery, durationMs });
+      } else {
+        this.#retain({
           delivery,
-          durationMs: clock.now().getTime() - startedAt
+          settle: () => this.#complete(delivery),
+          applied: () => notifier.notify("onDeliverySucceeded", { delivery, durationMs })
         });
       }
+      return true;
     } catch (error) {
       if (error instanceof LeaseLostError) {
         notifier.notify("onLeaseLost", { delivery });
+        if (!error.storeConfirmed) {
+          await this.#giveBack(registration, delivery, error);
+        }
       } else if (error instanceof DispatcherStoppedError) {
         await this.#release(delivery);
       } else {
         await this.#fail(registration, delivery, error);
       }
+      return false;
     } finally {
       stopHeartbeat();
     }
@@ -858,7 +1451,9 @@ var Dispatcher = class {
       await store.transaction(async (transaction) => {
         await this.#invoke(registration, event, delivery, controller, transaction);
         if (!await store.complete(delivery, clock.now(), transaction)) {
-          throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+          throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+            storeConfirmed: true
+          });
         }
       });
       return "completed";
@@ -871,11 +1466,11 @@ var Dispatcher = class {
    * still held. Gives up to lease expiry, which reruns the handler: at-least-once.
    */
   async #confirmCompletion(delivery) {
-    const { store, clock, notifier } = this.#dependencies;
+    const { notifier } = this.#dependencies;
     for (let attempt = 0; ; attempt += 1) {
       let completed;
       try {
-        completed = await store.complete(delivery, clock.now());
+        completed = await this.#complete(delivery);
       } catch (error) {
         const delay = COMPLETION_RETRY_DELAYS_MS[attempt];
         if (delay === void 0) {
@@ -886,11 +1481,18 @@ var Dispatcher = class {
         continue;
       }
       if (!completed) {
-        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+          storeConfirmed: true
+        });
       }
       return "completed";
     }
   }
+  /** Records one completion, grouped with its neighbours when the store can complete many at once. */
+  #complete(delivery) {
+    const { store, clock } = this.#dependencies;
+    return this.#completions === void 0 ? store.complete(delivery, clock.now()) : this.#completions.submit(delivery);
+  }
   async #invoke(registration, event, delivery, controller, transaction) {
     const context = {
       deliveryId: delivery.deliveryId,
@@ -964,7 +1566,9 @@ var Dispatcher = class {
     if (registration.timeoutMs !== null && now.getTime() + registration.timeoutMs >= expiry) {
       expiry = now.getTime() + registration.timeoutMs + settings.leaseDurationMs;
       if (!await store.extendLease(delivery, new Date(expiry), now)) {
-        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+          storeConfirmed: true
+        });
       }
     }
     const timer = setTimeout(
@@ -985,8 +1589,10 @@ var Dispatcher = class {
     const { store, clock, notifier, settings } = this.#dependencies;
     let confirmedExpiry = delivery.leaseExpiresAt.getTime();
     let renewing = false;
-    const abortLeaseLost = () => {
-      controller.abort(new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`));
+    const abortLeaseLost = (storeConfirmed = false) => {
+      controller.abort(
+        new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, { storeConfirmed })
+      );
     };
     const timer = setInterval(
       () => {
@@ -1004,7 +1610,7 @@ var Dispatcher = class {
           if (extended) {
             confirmedExpiry = expiry;
           } else {
-            abortLeaseLost();
+            abortLeaseLost(true);
           }
         }).catch((error) => notifier.failure("extend-lease", error)).finally(() => {
           renewing = false;
@@ -1016,12 +1622,17 @@ var Dispatcher = class {
     return () => clearInterval(timer);
   }
   async #fail(registration, delivery, error) {
-    const { store, clock, random, notifier } = this.#dependencies;
     const policy = registration.retry;
     if (delivery.attempt >= policy.attempts || !isRetryableError(policy, error)) {
       await this.#bury(delivery, error);
       return;
     }
+    await this.#reschedule(registration, delivery, error);
+  }
+  /** Schedules the next attempt with the retry policy's backoff. */
+  async #reschedule(registration, delivery, error) {
+    const { store, clock, random, notifier } = this.#dependencies;
+    const policy = registration.retry;
     const errorInfo = toErrorInfo(error);
     const now = clock.now();
     const availableAt = new Date(
@@ -1032,6 +1643,11 @@ var Dispatcher = class {
       rescheduled = await store.reschedule(delivery, availableAt, errorInfo, now);
     } catch (storeError) {
       notifier.failure("reschedule", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.reschedule(delivery, availableAt, errorInfo, now),
+        applied: () => notifier.notify("onDeliveryRetryScheduled", { delivery, error: errorInfo, availableAt })
+      });
       return;
     }
     if (rescheduled) {
@@ -1048,6 +1664,11 @@ var Dispatcher = class {
       buried = await store.bury(delivery, errorInfo, clock.now());
     } catch (storeError) {
       notifier.failure("bury", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.bury(delivery, errorInfo, clock.now()),
+        applied: () => notifier.notify("onDeliveryDead", { delivery, error: errorInfo })
+      });
       return;
     }
     if (buried) {
@@ -1056,6 +1677,21 @@ var Dispatcher = class {
       notifier.notify("onLeaseLost", { delivery });
     }
   }
+  /**
+   * A worker that only noticed locally that its lease ran out may still own the delivery in the
+   * store, where other deliveries of its lane keep renewing the lane: it must not stay in flight
+   * for ever. The attempt took longer than its lease, so it counts as a failed attempt (an
+   * exhausted delivery is dead-lettered, whatever a custom `retryIf` says): a handler that always
+   * outlives its lease cannot run for ever at attempt 1. If the lease is gone for real the store
+   * refuses and nothing changes. The lost lease was reported already.
+   */
+  async #giveBack(registration, delivery, error) {
+    if (delivery.attempt >= registration.retry.attempts) {
+      await this.#bury(delivery, error);
+    } else {
+      await this.#reschedule(registration, delivery, error);
+    }
+  }
   async #release(delivery) {
     const { store, clock, notifier } = this.#dependencies;
     let released;
@@ -1063,6 +1699,11 @@ var Dispatcher = class {
       released = await store.release(delivery, clock.now());
     } catch (storeError) {
       notifier.failure("release", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.release(delivery, clock.now()),
+        applied: () => notifier.notify("onDeliveryReleased", { delivery })
+      });
       return;
     }
     if (released) {
@@ -1072,6 +1713,9 @@ var Dispatcher = class {
     }
   }
 };
+function pendingKey(delivery) {
+  return `${delivery.deliveryId}\0${delivery.leaseToken}`;
+}
 function rejectOnAbort(signal) {
   return new Promise((_, reject) => {
     signal.addEventListener("abort", () => reject(signal.reason), { once: true });
@@ -1196,6 +1840,8 @@ var DEFAULTS = {
   pollInterval: "1s",
   leaseDuration: "30s",
   shutdownTimeout: "30s",
+  completionBatchWindow: "2ms",
+  completionBatchSize: 200,
   completedRetention: "7d",
   retentionInterval: "1h",
   routeTimeoutMs: 3e4
@@ -1218,6 +1864,7 @@ var RelayBus = class {
   #generateIdentifier;
   #dispatcher;
   #dispatcherEnabled;
+  #catalogRequirements = [];
   #setupStore;
   #retention;
   #retentionTimer;
@@ -1264,6 +1911,9 @@ var RelayBus = class {
         throw new ConfigurationError(`Transport '${transport.name}' cannot subscribe`);
       }
     }
+    for (const catalog of options.catalogs ?? []) {
+      this.registerCatalog(catalog);
+    }
     this.#dispatcherEnabled = options.dispatcher?.enabled ?? true;
     this.#dispatcher = new Dispatcher({
       store: this.#store,
@@ -1305,6 +1955,28 @@ var RelayBus = class {
       this.#defaults
     );
   }
+  subscribeCatalog(catalog, handlers, options = {}) {
+    for (const binding of resolveCatalogHandlers(catalog, handlers, options)) {
+      this.subscribe(binding.eventClass, binding.handle, binding.options);
+    }
+  }
+  /**
+   * 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) {
+    this.#catalogRequirements.push(toCatalogRequirement(catalog));
+  }
+  /**
+   * 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(catalog, options = {}) {
+    return new CatalogPublisher(catalog, this, options);
+  }
   /** Registered handlers and routes, for diagnostics. */
   handlers() {
     return this.#registry.all().map(toDescriptor);
@@ -1370,6 +2042,7 @@ var RelayBus = class {
         this.#state === "stopped" ? "A stopped relaybus cannot be started again; create a new instance" : `Cannot start a relaybus that is ${this.#state}`
       );
     }
+    assertCatalogsCovered(this.#catalogRequirements, (type) => this.#registrationsOf(type));
     this.#state = "starting";
     this.#starting = this.#startComponents();
     try {
@@ -1389,6 +2062,10 @@ var RelayBus = class {
     if (this.#state === "starting") {
       await this.#starting.catch(() => void 0);
     }
+    if (this.#state === "idle") {
+      await this.#dispatcher.stop();
+      return;
+    }
     if (this.#state !== "running") {
       return;
     }
@@ -1581,6 +2258,11 @@ var RelayBus = class {
   #createDelivery(registration, availableAt) {
     return { id: this.#generateIdentifier(), handler: registration.id, availableAt };
   }
+  #registrationsOf(eventType) {
+    const registrations = this.#registry.forEventType(eventType);
+    const routes = registrations.filter((registration) => registration.forwardsToTransport).length;
+    return { handlers: registrations.length - routes, routes };
+  }
   #registerRoute(route) {
     const transport = this.#requireTransport(route.transport);
     const { type } = describeEvent(route.event);
@@ -1608,7 +2290,7 @@ var RelayBus = class {
     return transport;
   }
   #scheduleWake() {
-    if (this.#state !== "running") {
+    if (this.#state !== "running" || this.#dispatcher.watchesNewDeliveries) {
       return;
     }
     setTimeout(() => this.#dispatcher.wake(), WAKE_DELAY_MS).unref();
@@ -1713,6 +2395,14 @@ function createDispatcherSettings(options, generateIdentifier) {
     shutdownTimeoutMs: toTimerMilliseconds(
       options?.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
       "dispatcher.shutdownTimeout"
+    ),
+    completionBatchWindowMs: toMilliseconds(
+      options?.completionBatchWindow ?? DEFAULTS.completionBatchWindow,
+      "dispatcher.completionBatchWindow"
+    ),
+    completionBatchSize: positiveInteger(
+      options?.completionBatchSize ?? DEFAULTS.completionBatchSize,
+      "dispatcher.completionBatchSize"
     )
   };
 }
@@ -1729,6 +2419,7 @@ function createRetentionSettings(options) {
   };
 }
 
+exports.CatalogPublisher = CatalogPublisher;
 exports.ConfigurationError = ConfigurationError;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
 exports.DEFAULT_ROUTE_RETRY_POLICY = DEFAULT_ROUTE_RETRY_POLICY;
@@ -1747,10 +2438,15 @@ exports.RelayBusError = RelayBusError;
 exports.TransactionRequiredError = TransactionRequiredError;
 exports.assertEventType = assertEventType;
 exports.computeRetryDelay = computeRetryDelay;
+exports.consume = consume;
 exports.createRetryPolicy = createRetryPolicy;
 exports.createUuidV7 = createUuidV7;
+exports.defineCatalog = defineCatalog;
 exports.defineEvent = defineEvent;
+exports.defineHandlers = defineHandlers;
+exports.describeCatalog = describeCatalog;
 exports.isRetryableError = isRetryableError;
+exports.produce = produce;
 exports.systemClock = systemClock;
 exports.toErrorInfo = toErrorInfo;
 exports.toMilliseconds = toMilliseconds;