@chidchanun/bcp 0.2.11 → 0.2.13

package/packages/client/src/events.mjs

@@ -0,0 +1,889 @@
+// packages/server/src/events.ts
+import {
+  randomUUID
+} from "node:crypto";
+function createMemoryOutboxStore() {
+  const events = /* @__PURE__ */ new Map();
+  return {
+    async append(_transaction, event) {
+      if (events.has(event.id)) {
+        throw new Error(
+          `BCP Events: outbox event id "${event.id}" already exists.`
+        );
+      }
+      events.set(
+        event.id,
+        cloneEvent(event)
+      );
+    },
+    async claimDue(now, options) {
+      const ownerId = normalizeText(
+        options.ownerId,
+        "dispatcher owner id"
+      );
+      const leaseMs = positiveInteger(
+        options.leaseMs,
+        "leaseMs"
+      );
+      const limit = positiveInteger(
+        options.limit ?? 100,
+        "batch limit"
+      );
+      recoverMemoryStale(
+        events,
+        now,
+        Number.MAX_SAFE_INTEGER
+      );
+      const due = Array.from(events.values()).filter(
+        (event) => event.state === "pending" && event.availableAt <= now && event.attempts < event.maxAttempts
+      ).sort(compareEvents).slice(0, limit);
+      for (const event of due) {
+        event.state = "processing";
+        event.attempts += 1;
+        event.processingAt = now;
+        event.leaseOwner = ownerId;
+        event.leaseUntil = now + leaseMs;
+        event.error = void 0;
+      }
+      return due.map(cloneEvent);
+    },
+    async markPublished(id, publishedAt, ownerId) {
+      const event = events.get(id);
+      if (!event || event.state !== "processing" || event.leaseOwner !== ownerId) {
+        return false;
+      }
+      event.state = "published";
+      event.publishedAt = publishedAt;
+      event.failedAt = void 0;
+      event.error = void 0;
+      clearLease(event);
+      return true;
+    },
+    async markFailed(id, options) {
+      const event = events.get(id);
+      if (!event || event.state !== "processing" || event.leaseOwner !== options.ownerId) {
+        return false;
+      }
+      event.error = options.error;
+      clearLease(event);
+      if (options.retryAt !== void 0 && event.attempts < event.maxAttempts) {
+        event.state = "pending";
+        event.availableAt = options.retryAt;
+        event.processingAt = void 0;
+        return true;
+      }
+      event.state = "failed";
+      event.failedAt = options.failedAt;
+      return true;
+    },
+    async recoverStale(now, limit = 100) {
+      return recoverMemoryStale(
+        events,
+        now,
+        positiveInteger(limit, "recovery limit")
+      );
+    },
+    async get(id) {
+      const event = events.get(id);
+      return event ? cloneEvent(event) : null;
+    },
+    async list() {
+      return Array.from(events.values()).map(cloneEvent).sort(compareEvents);
+    },
+    async cleanup(options) {
+      finiteNumber(
+        options.before,
+        "cleanup before"
+      );
+      let removed = 0;
+      for (const [id, event] of events) {
+        const terminalAt = event.publishedAt ?? event.failedAt;
+        if ((event.state === "published" || event.state === "failed") && terminalAt !== void 0 && terminalAt <= options.before) {
+          events.delete(id);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    async stats() {
+      return calculateStats(
+        Array.from(events.values())
+      );
+    },
+    clear() {
+      events.clear();
+    }
+  };
+}
+function createTransactionalOutbox(options) {
+  if (!options?.store) {
+    throw new TypeError(
+      "BCP Events: transactional outbox requires a store."
+    );
+  }
+  const store = options.store;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const defaultMaxAttempts = positiveInteger(
+    options.defaultMaxAttempts ?? 5,
+    "defaultMaxAttempts"
+  );
+  return {
+    store,
+    async publish(transaction, rawType, payload, publishOptions = {}) {
+      assertTransaction(transaction);
+      const type = normalizeText(
+        rawType,
+        "event type"
+      );
+      const createdAt = now();
+      const delayMs = nonNegativeNumber(
+        publishOptions.delayMs ?? 0,
+        "delayMs"
+      );
+      const event = {
+        id: normalizeText(
+          publishOptions.id ?? idFactory(),
+          "event id"
+        ),
+        type,
+        payload,
+        metadata: {
+          ...publishOptions.metadata ?? {}
+        },
+        state: "pending",
+        attempts: 0,
+        maxAttempts: positiveInteger(
+          publishOptions.maxAttempts ?? defaultMaxAttempts,
+          "maxAttempts"
+        ),
+        createdAt,
+        availableAt: createdAt + delayMs,
+        correlationId: optionalText(
+          publishOptions.correlationId
+        ),
+        causationId: optionalText(
+          publishOptions.causationId
+        ),
+        aggregateId: optionalText(
+          publishOptions.aggregateId
+        )
+      };
+      await store.append(
+        transaction,
+        event
+      );
+      return cloneEvent(event);
+    }
+  };
+}
+function createEventBus() {
+  const handlers = /* @__PURE__ */ new Map();
+  return {
+    on(type, handler) {
+      const normalizedType = normalizeText(type, "event type");
+      if (typeof handler !== "function") {
+        throw new TypeError(
+          "BCP Events: event handler must be a function."
+        );
+      }
+      let group = handlers.get(normalizedType);
+      if (!group) {
+        group = /* @__PURE__ */ new Set();
+        handlers.set(normalizedType, group);
+      }
+      group.add(handler);
+      return () => {
+        group?.delete(handler);
+        if (group?.size === 0) {
+          handlers.delete(normalizedType);
+        }
+      };
+    },
+    async emit(event) {
+      const group = handlers.get(event.type);
+      if (!group || group.size === 0) {
+        return;
+      }
+      for (const handler of group) {
+        await handler({
+          event: cloneEvent(event),
+          payload: event.payload
+        });
+      }
+    },
+    clear() {
+      handlers.clear();
+    }
+  };
+}
+function createOutboxDispatcher(options) {
+  if (!options?.store) {
+    throw new TypeError(
+      "BCP Events: dispatcher requires an outbox store."
+    );
+  }
+  if (!options.queue && !options.publish && !options.eventBus) {
+    throw new TypeError(
+      "BCP Events: dispatcher requires queue, publish or eventBus delivery."
+    );
+  }
+  const store = options.store;
+  const queue = options.queue;
+  const eventBus = options.eventBus;
+  const publish = options.publish;
+  const ownerId = normalizeText(
+    options.ownerId ?? `outbox-${randomUUID()}`,
+    "dispatcher owner id"
+  );
+  const leaseMs = positiveInteger(
+    options.leaseMs ?? 3e4,
+    "leaseMs"
+  );
+  const batchSize = positiveInteger(
+    options.batchSize ?? 100,
+    "batchSize"
+  );
+  const pollIntervalMs = nonNegativeNumber(
+    options.pollIntervalMs ?? 1e3,
+    "pollIntervalMs"
+  );
+  const retryDelay = options.retryDelayMs ?? ((attempt) => Math.min(
+    6e4,
+    1e3 * Math.pow(2, Math.max(0, attempt - 1))
+  ));
+  const queueNamePrefix = String(
+    options.queueNamePrefix ?? "event."
+  );
+  const now = options.now ?? Date.now;
+  const runners = /* @__PURE__ */ new Set();
+  const dispatcher = {
+    store,
+    ownerId,
+    async dispatchBatch() {
+      await store.recoverStale(
+        now(),
+        batchSize
+      );
+      const events = await store.claimDue(
+        now(),
+        {
+          ownerId,
+          leaseMs,
+          limit: batchSize
+        }
+      );
+      let publishedCount = 0;
+      for (const event of events) {
+        try {
+          if (queue) {
+            await queue.enqueue(
+              `${queueNamePrefix}${event.type}`,
+              createEventEnvelope(event),
+              {
+                id: `outbox:${event.id}`,
+                maxAttempts: 1
+              }
+            );
+          }
+          if (eventBus) {
+            await eventBus.emit(event);
+          }
+          if (publish) {
+            await publish(event);
+          }
+          const marked = await store.markPublished(
+            event.id,
+            now(),
+            ownerId
+          );
+          if (marked) {
+            publishedCount += 1;
+          }
+        } catch (error) {
+          const failedAt = now();
+          const retryAt = event.attempts < event.maxAttempts ? failedAt + resolveRetryDelay(
+            retryDelay,
+            event.attempts
+          ) : void 0;
+          await store.markFailed(
+            event.id,
+            {
+              ownerId,
+              error: formatError(error),
+              failedAt,
+              retryAt
+            }
+          );
+          if (options.onError) {
+            await options.onError(
+              error,
+              cloneEvent(event)
+            );
+          }
+        }
+      }
+      return publishedCount;
+    },
+    recoverStale(limit = batchSize) {
+      return store.recoverStale(
+        now(),
+        positiveInteger(
+          limit,
+          "recovery limit"
+        )
+      );
+    },
+    start() {
+      let running = true;
+      let stopPromise = null;
+      const controller = new AbortController();
+      const loop = async () => {
+        while (running && !controller.signal.aborted) {
+          try {
+            await dispatcher.dispatchBatch();
+          } catch (error) {
+            if (options.onError) {
+              await options.onError(error);
+            }
+          }
+          if (running && !controller.signal.aborted) {
+            await sleep(
+              pollIntervalMs,
+              controller.signal
+            );
+          }
+        }
+      };
+      const loopPromise = loop();
+      const runner = {
+        get running() {
+          return running;
+        },
+        stop() {
+          if (!stopPromise) {
+            running = false;
+            controller.abort();
+            stopPromise = loopPromise.catch((error) => {
+              if (!isAbortError(error)) {
+                throw error;
+              }
+            }).then(() => {
+              runners.delete(runner);
+            });
+          }
+          return stopPromise;
+        }
+      };
+      runners.add(runner);
+      return runner;
+    },
+    async close() {
+      await Promise.all(
+        Array.from(
+          runners,
+          (runner) => runner.stop()
+        )
+      );
+      await store.close?.();
+    }
+  };
+  return dispatcher;
+}
+function createSqlOutboxStore(options) {
+  if (!options?.database) {
+    throw new TypeError(
+      "BCP Events: SQL outbox store requires a database."
+    );
+  }
+  const database = options.database;
+  const driver = normalizeDriver(options.driver);
+  const tableName = normalizeIdentifier(
+    options.tableName ?? "bcp_outbox_events"
+  );
+  return {
+    driver,
+    tableName,
+    async append(transaction, event) {
+      assertTransaction(transaction);
+      const values = [
+        event.id,
+        event.type,
+        JSON.stringify(event.payload),
+        JSON.stringify(event.metadata),
+        event.state,
+        event.attempts,
+        event.maxAttempts,
+        event.createdAt,
+        event.availableAt,
+        event.correlationId ?? null,
+        event.causationId ?? null,
+        event.aggregateId ?? null
+      ];
+      await transaction.execute(
+        `INSERT INTO ${tableName} (id, event_type, payload_json, metadata_json, state, attempts, max_attempts, created_at, available_at, correlation_id, causation_id, aggregate_id) VALUES (${placeholders(driver, values.length)})`,
+        values
+      );
+    },
+    async claimDue(now, claimOptions) {
+      const ownerId = normalizeText(
+        claimOptions.ownerId,
+        "dispatcher owner id"
+      );
+      const leaseMs = positiveInteger(
+        claimOptions.leaseMs,
+        "leaseMs"
+      );
+      const limit = positiveInteger(
+        claimOptions.limit ?? 100,
+        "batch limit"
+      );
+      return database.transaction(
+        async (transaction) => {
+          await recoverSqlStale(
+            transaction,
+            driver,
+            tableName,
+            now
+          );
+          const candidates = await transaction.query(
+            `SELECT * FROM ${tableName} WHERE state = ` + bind(driver, 1) + " AND available_at <= " + bind(driver, 2) + ` AND attempts < max_attempts ORDER BY available_at ASC, created_at ASC, id ASC LIMIT ${limit}` + (driver === "sqlite" ? "" : " FOR UPDATE SKIP LOCKED"),
+            ["pending", now]
+          );
+          const claimed = [];
+          for (const row of candidates) {
+            const id = String(row.id ?? "");
+            if (!id) {
+              continue;
+            }
+            const updateValues = [
+              "processing",
+              now,
+              ownerId,
+              now + leaseMs,
+              id,
+              "pending"
+            ];
+            await transaction.execute(
+              `UPDATE ${tableName} SET state = ${bind(driver, 1)}, attempts = attempts + 1, processing_at = ${bind(driver, 2)}, lease_owner = ${bind(driver, 3)}, lease_until = ${bind(driver, 4)}, error_text = NULL WHERE id = ${bind(driver, 5)} AND state = ${bind(driver, 6)}`,
+              updateValues
+            );
+            const rows = await transaction.query(
+              `SELECT * FROM ${tableName} WHERE id = ${bind(driver, 1)} AND state = ${bind(driver, 2)} AND lease_owner = ${bind(driver, 3)}`,
+              [id, "processing", ownerId]
+            );
+            if (rows[0]) {
+              claimed.push(
+                rowToEvent(rows[0])
+              );
+            }
+          }
+          return claimed;
+        }
+      );
+    },
+    async markPublished(id, publishedAt, ownerId) {
+      return conditionalUpdate(
+        database,
+        driver,
+        tableName,
+        id,
+        ownerId,
+        `state = ${bind(driver, 1)}, published_at = ${bind(driver, 2)}, error_text = NULL, lease_owner = NULL, lease_until = NULL`,
+        ["published", publishedAt]
+      );
+    },
+    async markFailed(id, failOptions) {
+      const retry = failOptions.retryAt !== void 0;
+      const setClause = retry ? `state = ${bind(driver, 1)}, available_at = ${bind(driver, 2)}, processing_at = NULL, error_text = ${bind(driver, 3)}, lease_owner = NULL, lease_until = NULL` : `state = ${bind(driver, 1)}, failed_at = ${bind(driver, 2)}, error_text = ${bind(driver, 3)}, lease_owner = NULL, lease_until = NULL`;
+      const values = retry ? ["pending", failOptions.retryAt, failOptions.error] : ["failed", failOptions.failedAt, failOptions.error];
+      return conditionalUpdate(
+        database,
+        driver,
+        tableName,
+        id,
+        failOptions.ownerId,
+        setClause,
+        values
+      );
+    },
+    async recoverStale(now, limit = 100) {
+      const normalizedLimit = positiveInteger(limit, "recovery limit");
+      return database.transaction(
+        async (transaction) => {
+          const rows = await transaction.query(
+            `SELECT id FROM ${tableName} WHERE state = ${bind(driver, 1)} AND lease_until IS NOT NULL AND lease_until <= ${bind(driver, 2)} ORDER BY lease_until ASC, id ASC LIMIT ${normalizedLimit}`,
+            ["processing", now]
+          );
+          for (const row of rows) {
+            const id = String(row.id ?? "");
+            if (!id) {
+              continue;
+            }
+            await transaction.execute(
+              `UPDATE ${tableName} SET state = ${bind(driver, 1)}, processing_at = NULL, lease_owner = NULL, lease_until = NULL WHERE id = ${bind(driver, 2)} AND state = ${bind(driver, 3)} AND lease_until <= ${bind(driver, 4)}`,
+              ["pending", id, "processing", now]
+            );
+          }
+          return rows.length;
+        }
+      );
+    },
+    async get(id) {
+      const rows = await database.query(
+        `SELECT * FROM ${tableName} WHERE id = ${bind(driver, 1)}`,
+        [id]
+      );
+      return rows[0] ? rowToEvent(rows[0]) : null;
+    },
+    async list() {
+      const rows = await database.query(
+        `SELECT * FROM ${tableName} ORDER BY created_at ASC, id ASC`
+      );
+      return rows.map(rowToEvent);
+    },
+    async cleanup(cleanupOptions) {
+      finiteNumber(
+        cleanupOptions.before,
+        "cleanup before"
+      );
+      const rows = await database.query(
+        `SELECT id FROM ${tableName} WHERE (state = ${bind(driver, 1)} AND published_at <= ${bind(driver, 2)}) OR (state = ${bind(driver, 3)} AND failed_at <= ${bind(driver, 4)})`,
+        [
+          "published",
+          cleanupOptions.before,
+          "failed",
+          cleanupOptions.before
+        ]
+      );
+      await database.execute(
+        `DELETE FROM ${tableName} WHERE (state = ${bind(driver, 1)} AND published_at <= ${bind(driver, 2)}) OR (state = ${bind(driver, 3)} AND failed_at <= ${bind(driver, 4)})`,
+        [
+          "published",
+          cleanupOptions.before,
+          "failed",
+          cleanupOptions.before
+        ]
+      );
+      return rows.length;
+    },
+    async stats() {
+      const rows = await database.query(
+        `SELECT state, COUNT(*) AS count FROM ${tableName} GROUP BY state`
+      );
+      const stats = {
+        total: 0,
+        pending: 0,
+        processing: 0,
+        published: 0,
+        failed: 0
+      };
+      for (const row of rows) {
+        const count = Number(row.count ?? 0);
+        if (row.state === "pending" || row.state === "processing" || row.state === "published" || row.state === "failed") {
+          stats[row.state] += count;
+          stats.total += count;
+        }
+      }
+      return stats;
+    }
+  };
+}
+function createOutboxMigrationSql(driver, tableName = "bcp_outbox_events") {
+  const normalizedDriver = normalizeDriver(driver);
+  const table = normalizeIdentifier(tableName);
+  if (normalizedDriver === "mysql") {
+    return `CREATE TABLE IF NOT EXISTS ${table} (
+  id VARCHAR(191) PRIMARY KEY,
+  event_type VARCHAR(191) NOT NULL,
+  payload_json LONGTEXT NOT NULL,
+  metadata_json LONGTEXT NOT NULL,
+  state VARCHAR(32) NOT NULL,
+  attempts INT NOT NULL DEFAULT 0,
+  max_attempts INT NOT NULL,
+  created_at BIGINT NOT NULL,
+  available_at BIGINT NOT NULL,
+  processing_at BIGINT NULL,
+  published_at BIGINT NULL,
+  failed_at BIGINT NULL,
+  error_text TEXT NULL,
+  correlation_id VARCHAR(191) NULL,
+  causation_id VARCHAR(191) NULL,
+  aggregate_id VARCHAR(191) NULL,
+  lease_owner VARCHAR(191) NULL,
+  lease_until BIGINT NULL,
+  INDEX idx_bcp_outbox_due (state, available_at),
+  INDEX idx_bcp_outbox_lease (state, lease_until)
+) ENGINE=InnoDB;`;
+  }
+  const idType = normalizedDriver === "postgresql" ? "VARCHAR(191)" : "TEXT";
+  const textType = normalizedDriver === "postgresql" ? "TEXT" : "TEXT";
+  return `CREATE TABLE IF NOT EXISTS ${table} (
+  id ${idType} PRIMARY KEY,
+  event_type ${idType} NOT NULL,
+  payload_json ${textType} NOT NULL,
+  metadata_json ${textType} NOT NULL,
+  state ${idType} NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL,
+  created_at BIGINT NOT NULL,
+  available_at BIGINT NOT NULL,
+  processing_at BIGINT NULL,
+  published_at BIGINT NULL,
+  failed_at BIGINT NULL,
+  error_text ${textType} NULL,
+  correlation_id ${idType} NULL,
+  causation_id ${idType} NULL,
+  aggregate_id ${idType} NULL,
+  lease_owner ${idType} NULL,
+  lease_until BIGINT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_bcp_outbox_due ON ${table} (state, available_at);
+CREATE INDEX IF NOT EXISTS idx_bcp_outbox_lease ON ${table} (state, lease_until);`;
+}
+function createEventEnvelope(event) {
+  return {
+    eventId: event.id,
+    type: event.type,
+    payload: event.payload,
+    metadata: event.metadata,
+    correlationId: event.correlationId,
+    causationId: event.causationId,
+    aggregateId: event.aggregateId,
+    createdAt: event.createdAt
+  };
+}
+function recoverMemoryStale(events, now, limit) {
+  const stale = Array.from(events.values()).filter(
+    (event) => event.state === "processing" && event.leaseUntil !== void 0 && event.leaseUntil <= now
+  ).sort(
+    (left, right) => (left.leaseUntil ?? 0) - (right.leaseUntil ?? 0) || left.id.localeCompare(right.id)
+  ).slice(0, limit);
+  for (const event of stale) {
+    event.state = "pending";
+    event.processingAt = void 0;
+    clearLease(event);
+  }
+  return stale.length;
+}
+async function recoverSqlStale(transaction, driver, tableName, now) {
+  await transaction.execute(
+    `UPDATE ${tableName} SET state = ${bind(driver, 1)}, processing_at = NULL, lease_owner = NULL, lease_until = NULL WHERE state = ${bind(driver, 2)} AND lease_until IS NOT NULL AND lease_until <= ${bind(driver, 3)}`,
+    ["pending", "processing", now]
+  );
+}
+async function conditionalUpdate(database, driver, tableName, id, ownerId, setClause, setValues) {
+  const idIndex = setValues.length + 1;
+  const stateIndex = idIndex + 1;
+  const ownerIndex = idIndex + 2;
+  await database.execute(
+    `UPDATE ${tableName} SET ${setClause} WHERE id = ${bind(driver, idIndex)} AND state = ${bind(driver, stateIndex)} AND lease_owner = ${bind(driver, ownerIndex)}`,
+    [...setValues, id, "processing", ownerId]
+  );
+  const rows = await database.query(
+    `SELECT state, lease_owner FROM ${tableName} WHERE id = ${bind(driver, 1)}`,
+    [id]
+  );
+  const row = rows[0];
+  return Boolean(
+    row && row.lease_owner !== ownerId && row.state !== "processing"
+  );
+}
+function rowToEvent(row) {
+  return {
+    id: String(row.id ?? ""),
+    type: String(row.event_type ?? ""),
+    payload: parseJson(row.payload_json),
+    metadata: parseMetadata(row.metadata_json),
+    state: normalizeState(row.state),
+    attempts: Number(row.attempts ?? 0),
+    maxAttempts: Number(row.max_attempts ?? 1),
+    createdAt: Number(row.created_at ?? 0),
+    availableAt: Number(row.available_at ?? 0),
+    processingAt: optionalNumber(row.processing_at),
+    publishedAt: optionalNumber(row.published_at),
+    failedAt: optionalNumber(row.failed_at),
+    error: optionalText(row.error_text),
+    correlationId: optionalText(row.correlation_id),
+    causationId: optionalText(row.causation_id),
+    aggregateId: optionalText(row.aggregate_id),
+    leaseOwner: optionalText(row.lease_owner),
+    leaseUntil: optionalNumber(row.lease_until)
+  };
+}
+function calculateStats(events) {
+  const stats = {
+    total: events.length,
+    pending: 0,
+    processing: 0,
+    published: 0,
+    failed: 0
+  };
+  for (const event of events) {
+    stats[event.state] += 1;
+  }
+  return stats;
+}
+function compareEvents(left, right) {
+  return left.availableAt - right.availableAt || left.createdAt - right.createdAt || left.id.localeCompare(right.id);
+}
+function clearLease(event) {
+  event.leaseOwner = void 0;
+  event.leaseUntil = void 0;
+}
+function cloneEvent(event) {
+  return {
+    ...event,
+    metadata: {
+      ...event.metadata
+    }
+  };
+}
+function normalizeState(value) {
+  if (value === "pending" || value === "processing" || value === "published" || value === "failed") {
+    return value;
+  }
+  throw new Error(
+    `BCP Events: invalid outbox state "${String(value)}".`
+  );
+}
+function normalizeDriver(driver) {
+  if (driver === "mysql" || driver === "postgresql" || driver === "sqlite") {
+    return driver;
+  }
+  throw new TypeError(
+    `BCP Events: unsupported database driver "${String(driver)}".`
+  );
+}
+function normalizeIdentifier(value) {
+  const identifier = String(value ?? "").trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+    throw new TypeError(
+      "BCP Events: table name must be a simple SQL identifier."
+    );
+  }
+  return identifier;
+}
+function placeholders(driver, count) {
+  return Array.from(
+    { length: count },
+    (_, index) => bind(driver, index + 1)
+  ).join(", ");
+}
+function bind(driver, index) {
+  return driver === "postgresql" ? `$${index}` : "?";
+}
+function assertTransaction(transaction) {
+  if (!transaction || typeof transaction.query !== "function" || typeof transaction.execute !== "function") {
+    throw new TypeError(
+      "BCP Events: publish requires a BCP transaction database."
+    );
+  }
+}
+function normalizeText(value, field) {
+  const text = String(value ?? "").trim();
+  if (!text) {
+    throw new TypeError(
+      `BCP Events: ${field} must be a non-empty string.`
+    );
+  }
+  return text;
+}
+function optionalText(value) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  const text = String(value).trim();
+  return text || void 0;
+}
+function optionalNumber(value) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  const number = Number(value);
+  return Number.isFinite(number) ? number : void 0;
+}
+function positiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Events: ${field} must be a positive integer.`
+    );
+  }
+  return value;
+}
+function nonNegativeNumber(value, field) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new TypeError(
+      `BCP Events: ${field} must be a non-negative finite number.`
+    );
+  }
+  return Math.floor(value);
+}
+function finiteNumber(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Events: ${field} must be a finite number.`
+    );
+  }
+  return value;
+}
+function resolveRetryDelay(retryDelay, attempt) {
+  const delay = typeof retryDelay === "function" ? retryDelay(attempt) : retryDelay;
+  return nonNegativeNumber(
+    delay,
+    "retry delay"
+  );
+}
+function parseJson(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return JSON.parse(value);
+}
+function parseMetadata(value) {
+  const parsed = parseJson(value);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message || error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error) ?? String(error);
+  } catch {
+    return String(error);
+  }
+}
+function sleep(delayMs, signal) {
+  if (delayMs === 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, delayMs);
+    const abort = () => {
+      clearTimeout(timer);
+      const error = new Error("Outbox dispatcher stopped.");
+      error.name = "AbortError";
+      reject(error);
+    };
+    if (signal.aborted) {
+      abort();
+      return;
+    }
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+export {
+  createEventBus,
+  createMemoryOutboxStore,
+  createOutboxDispatcher,
+  createOutboxMigrationSql,
+  createSqlOutboxStore,
+  createTransactionalOutbox
+};