@relaybus/postgres 0.0.0-stage → 0.0.0

package/dist/index.js

@@ -0,0 +1,969 @@
+import { ConfigurationError } from '@relaybus/core';
+import { Pool } from 'pg';
+
+// src/pg-executor.ts
+var PgExecutor = class {
+  #pool;
+  constructor(pool) {
+    this.#pool = pool;
+  }
+  async transaction(work) {
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const result = await work(client);
+      await client.query("COMMIT");
+      client.release();
+      return result;
+    } catch (error) {
+      await this.#rollbackAndRelease(client);
+      throw error;
+    }
+  }
+  async query(sql, parameters, transaction) {
+    const result = await (transaction ?? this.#pool).query(sql, [...parameters]);
+    return result.rows;
+  }
+  /** A client whose rollback fails is in an unknown state, so it is destroyed instead of reused. */
+  async #rollbackAndRelease(client) {
+    try {
+      await client.query("ROLLBACK");
+      client.release();
+    } catch {
+      client.release(true);
+    }
+  }
+};
+var IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_]*$/;
+var MAXIMUM_IDENTIFIER_LENGTH = 63;
+function assertIdentifier(label, value) {
+  if (!IDENTIFIER_PATTERN.test(value) || value.length > MAXIMUM_IDENTIFIER_LENGTH) {
+    throw new ConfigurationError(
+      `${label} '${value}' must match ${String(IDENTIFIER_PATTERN)} and be at most ${MAXIMUM_IDENTIFIER_LENGTH} characters`
+    );
+  }
+}
+function quoteIdentifier(value) {
+  return `"${value}"`;
+}
+
+// src/names.ts
+var DEFAULT_SCHEMA = "public";
+var DEFAULT_TABLE_PREFIX = "relaybus_";
+var TABLE_PREFIX_PATTERN = /^[a-z0-9_]*$/;
+function resolvePostgresNames(options = {}) {
+  const schema = options.schema ?? DEFAULT_SCHEMA;
+  const tablePrefix = options.tablePrefix ?? DEFAULT_TABLE_PREFIX;
+  assertIdentifier("schema", schema);
+  if (!TABLE_PREFIX_PATTERN.test(tablePrefix)) {
+    throw new ConfigurationError(
+      `tablePrefix '${tablePrefix}' must match ${String(TABLE_PREFIX_PATTERN)}`
+    );
+  }
+  const name = (suffix) => {
+    const identifier = `${tablePrefix}${suffix}`;
+    assertIdentifier(`tablePrefix '${tablePrefix}' produces the name`, identifier);
+    return identifier;
+  };
+  const quotedSchema = quoteIdentifier(schema);
+  const table = (suffix) => `${quotedSchema}.${quoteIdentifier(name(suffix))}`;
+  const index = (suffix) => quoteIdentifier(name(suffix));
+  return {
+    schema,
+    quotedSchema,
+    events: table("events"),
+    deliveries: table("deliveries"),
+    keySequences: table("key_sequences"),
+    indexes: {
+      deliveryEventHandler: index("deliveries_event_handler_unique"),
+      deliveryDue: index("deliveries_due_idx"),
+      deliveryDueUnkeyed: index("deliveries_due_unkeyed_idx"),
+      deliveryHandlerCreated: index("deliveries_handler_created_idx"),
+      eventCreated: index("events_created_idx"),
+      deliveryKeyUnfinished: index("deliveries_key_unfinished_idx"),
+      deliveryKeyProcessing: index("deliveries_key_processing_idx"),
+      deliveryStatusCreated: index("deliveries_status_created_idx"),
+      deliveryCompleted: index("deliveries_completed_idx"),
+      deliveryDead: index("deliveries_dead_idx")
+    }
+  };
+}
+
+// src/sql-fragments.ts
+function dueAtExpression(alias) {
+  const prefix = alias === void 0 ? "" : `${alias}.`;
+  return `CASE WHEN ${prefix}status = 'pending' THEN ${prefix}available_at ELSE ${prefix}lease_expires_at END`;
+}
+function isoText(expression) {
+  return `to_char(${expression} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+}
+
+// src/schema.ts
+function createPostgresSchemaStatements(options = {}) {
+  const names = resolvePostgresNames(options);
+  const unfinished = `status IN ('pending', 'processing')`;
+  const statements = [
+    `CREATE TABLE IF NOT EXISTS ${names.events} (
+  id text PRIMARY KEY,
+  type text NOT NULL,
+  source text NOT NULL,
+  key text,
+  sequence bigint,
+  payload jsonb NOT NULL,
+  headers jsonb NOT NULL DEFAULT '{}'::jsonb,
+  correlation_id text,
+  causation_id text,
+  occurred_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL
+)`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.eventCreated} ON ${names.events} (created_at, id)`,
+    `CREATE TABLE IF NOT EXISTS ${names.keySequences} (
+  key text PRIMARY KEY,
+  sequence bigint NOT NULL
+)`,
+    `CREATE TABLE IF NOT EXISTS ${names.deliveries} (
+  id text COLLATE "C" PRIMARY KEY,
+  event_id text NOT NULL REFERENCES ${names.events} (id) ON DELETE CASCADE,
+  handler text NOT NULL,
+  status text NOT NULL CHECK (status IN ('pending', 'processing', 'completed', 'dead')),
+  attempts integer NOT NULL DEFAULT 0,
+  available_at timestamptz NOT NULL,
+  lease_owner text,
+  lease_token text,
+  lease_expires_at timestamptz,
+  last_error jsonb,
+  key text,
+  sequence bigint,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  completed_at timestamptz,
+  CONSTRAINT ${names.indexes.deliveryEventHandler} UNIQUE (event_id, handler)
+)`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryDue} ON ${names.deliveries} ((${dueAtExpression()}), id) WHERE ${unfinished}`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryDueUnkeyed} ON ${names.deliveries} ((${dueAtExpression()}), id) WHERE key IS NULL AND ${unfinished}`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryKeyUnfinished} ON ${names.deliveries} (handler, key, sequence) WHERE key IS NOT NULL AND ${unfinished}`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryKeyProcessing} ON ${names.deliveries} (handler, key) WHERE key IS NOT NULL AND status = 'processing'`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryStatusCreated} ON ${names.deliveries} (status, created_at, id)`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryHandlerCreated} ON ${names.deliveries} (handler, created_at, id)`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryCompleted} ON ${names.deliveries} (completed_at, id) WHERE status = 'completed'`,
+    `CREATE INDEX IF NOT EXISTS ${names.indexes.deliveryDead} ON ${names.deliveries} (updated_at, id) WHERE status = 'dead'`
+  ];
+  if (names.schema !== "public") {
+    statements.unshift(`CREATE SCHEMA IF NOT EXISTS ${names.quotedSchema}`);
+  }
+  return statements;
+}
+function createPostgresSchemaSql(options = {}) {
+  return `${createPostgresSchemaStatements(options).join(";\n\n")};
+`;
+}
+
+// src/row-mapping.ts
+function text(row, column) {
+  return row[column];
+}
+function nullableText(row, column) {
+  return row[column];
+}
+function nullableDate(row, column) {
+  const value = nullableText(row, column);
+  return value === null ? null : new Date(value);
+}
+function readCount(row, column) {
+  return Number(row[column]);
+}
+function mapEventEnvelope(row) {
+  return {
+    id: text(row, "event_id"),
+    type: text(row, "event_type"),
+    source: text(row, "event_source"),
+    key: nullableText(row, "event_key"),
+    payload: JSON.parse(text(row, "event_payload")),
+    headers: JSON.parse(text(row, "event_headers")),
+    correlationId: nullableText(row, "event_correlation_id"),
+    causationId: nullableText(row, "event_causation_id"),
+    occurredAt: new Date(text(row, "event_occurred_at"))
+  };
+}
+function mapClaimedDelivery(row, leaseExpiresAt) {
+  return {
+    deliveryId: text(row, "delivery_id"),
+    leaseToken: text(row, "lease_token"),
+    handler: text(row, "handler"),
+    attempt: readCount(row, "attempts"),
+    leaseExpiresAt,
+    event: mapEventEnvelope(row)
+  };
+}
+function mapDeliveryRecord(row) {
+  const lastError = nullableText(row, "last_error");
+  return {
+    id: text(row, "delivery_id"),
+    handler: text(row, "handler"),
+    status: text(row, "status"),
+    attempts: readCount(row, "attempts"),
+    availableAt: new Date(text(row, "available_at")),
+    leaseOwner: nullableText(row, "lease_owner"),
+    leaseExpiresAt: nullableDate(row, "lease_expires_at"),
+    lastError: lastError === null ? null : JSON.parse(lastError),
+    createdAt: new Date(text(row, "created_at")),
+    updatedAt: new Date(text(row, "updated_at")),
+    completedAt: nullableDate(row, "completed_at"),
+    event: mapEventEnvelope(row)
+  };
+}
+function mapOldestDueAt(rows) {
+  return rows.length === 0 ? null : new Date(text(rows[0], "oldest_due_at"));
+}
+
+// src/statements.ts
+var DEFAULT_LIST_LIMIT = 100;
+function eventColumns(alias) {
+  return `${alias}.id AS event_id,
+    ${alias}.type AS event_type,
+    ${alias}.source AS event_source,
+    ${alias}.key AS event_key,
+    ${alias}.payload::text AS event_payload,
+    ${alias}.headers::text AS event_headers,
+    ${alias}.correlation_id AS event_correlation_id,
+    ${alias}.causation_id AS event_causation_id,
+    ${isoText(`${alias}.occurred_at`)} AS event_occurred_at`;
+}
+function countChanged(dml) {
+  return `WITH changed AS (${dml} RETURNING 1) SELECT count(*)::int AS count FROM changed`;
+}
+var CLAIM_SCAN_WINDOW = 256;
+var UNFINISHED_PREDICATE = (alias) => `${alias}.status IN ('pending', 'processing')`;
+var HANDLER_PREDICATE = `delivery.handler = ANY (ARRAY(SELECT jsonb_array_elements_text($2::jsonb)))`;
+var CLEAR_LEASE = "lease_owner = NULL, lease_token = NULL, lease_expires_at = NULL";
+var PostgresStatements = class {
+  #names;
+  constructor(names) {
+    this.#names = names;
+  }
+  /**
+   * Lock advisory key text for {@link setupLock}. It is derived from the schema
+   * name only, so stores with different table prefixes in one schema also
+   * serialize their `CREATE SCHEMA IF NOT EXISTS`, which is not race-free.
+   */
+  get setupLockKey() {
+    return `relaybus:${this.#names.schema}`;
+  }
+  get setupLock() {
+    return "SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))";
+  }
+  /**
+   * Reserves sequence numbers per key. Parameters: `[{ key, count }]` as JSON.
+   * Keys are locked in sorted order, so publishers cannot deadlock within one
+   * call (across calls of one transaction they can, see the README); each row lock is held until the publishing transaction ends, which makes
+   * sequence order equal commit order for a key.
+   */
+  get reserveSequences() {
+    return `INSERT INTO ${this.#names.keySequences} AS reserved (key, sequence)
+SELECT requested.key, requested.count
+FROM jsonb_to_recordset($1::jsonb) AS requested (key text, count bigint)
+ORDER BY requested.key
+ON CONFLICT (key) DO UPDATE SET sequence = reserved.sequence + EXCLUDED.sequence
+RETURNING reserved.key AS key, reserved.sequence::text AS sequence`;
+  }
+  /** Parameters: `[eventsJson, createdAt]`. Returns the ids that were inserted. */
+  get insertEvents() {
+    return `INSERT INTO ${this.#names.events}
+  (id, type, source, key, sequence, payload, headers, correlation_id, causation_id, occurred_at, created_at)
+SELECT incoming.id, incoming.type, incoming.source, incoming.key, incoming.sequence,
+  COALESCE(incoming.payload, 'null'::jsonb), COALESCE(incoming.headers, '{}'::jsonb),
+  incoming.correlation_id, incoming.causation_id, incoming.occurred_at, $2::timestamptz
+FROM jsonb_to_recordset($1::jsonb) AS incoming (
+  id text, type text, source text, key text, sequence bigint, payload jsonb, headers jsonb,
+  correlation_id text, causation_id text, occurred_at timestamptz)
+ORDER BY incoming.id
+ON CONFLICT (id) DO NOTHING
+RETURNING id`;
+  }
+  /**
+   * Parameters: `[deliveriesJson, createdAt]`. Key and sequence are copied from
+   * the stored event, so a delivery added later to an existing event keeps the
+   * event's position in its key. Returns the ids that were inserted.
+   */
+  get insertDeliveries() {
+    return `INSERT INTO ${this.#names.deliveries}
+  (id, event_id, handler, status, attempts, available_at, key, sequence, created_at, updated_at)
+SELECT incoming.id, incoming.event_id, incoming.handler, 'pending', 0, incoming.available_at,
+  event.key, event.sequence, $2::timestamptz, $2::timestamptz
+FROM jsonb_to_recordset($1::jsonb) AS incoming (id text, event_id text, handler text, available_at timestamptz)
+JOIN ${this.#names.events} AS event ON event.id = incoming.event_id
+ORDER BY incoming.event_id, incoming.handler
+ON CONFLICT (event_id, handler) DO NOTHING
+RETURNING id`;
+  }
+  /**
+   * Fast claim: leases from the first {@link CLAIM_SCAN_WINDOW} due deliveries
+   * in due order, which is everything the claim needs while the front of the
+   * queue is not clogged with blocked followers of busy keys. Parameters:
+   * `[now, handlersJson, limit, leaseOwner, leaseExpiresAt]`.
+   *
+   * Always returns one row per leased delivery, or a single row whose
+   * `delivery_id` is null when nothing was leased. `window_saturated` says
+   * whether the window was full: when it is and fewer than `limit` deliveries
+   * were leased, deliveries beyond the window may still be claimable and the
+   * caller runs {@link claimBehindBlockedKeys}. When the window is not
+   * saturated every due delivery was examined, so the result is complete.
+   *
+   * Candidates are chosen with `FOR UPDATE SKIP LOCKED`, so two claimers never
+   * lock the same row. A keyed delivery is a candidate only when it is the head
+   * of its (handler, key), that is (a) no earlier delivery of that handler and
+   * key is pending or processing, which is the ordering guarantee, and (b) no
+   * other delivery of that handler and key holds a live lease. Rule b covers a
+   * delivery that re-enters the key behind a running one (requeue, or a handler
+   * added to an old event); an expired lease does not count, because its worker
+   * is presumed dead and the key must not stall behind it.
+   *
+   * Why SKIP LOCKED alone is enough for ordering: only the head of a key can
+   * ever be a candidate, and the head is a single row. Two claimers racing
+   * for it either skip it (the other holds the row lock) or, if the other
+   * already committed, re-check the row's new version (now processing and not
+   * due), which excludes it. Followers stay blocked because their predecessor
+   * remains pending or processing in every snapshot until it completes or is
+   * buried, and that commit happens-before the next claim that sees it.
+   */
+  get claim() {
+    const deliveries = this.#names.deliveries;
+    return `WITH due_window AS MATERIALIZED (
+  SELECT delivery.id
+  FROM ${deliveries} AS delivery
+  WHERE ${UNFINISHED_PREDICATE("delivery")}
+    AND ${dueAtExpression("delivery")} <= $1::timestamptz
+    AND ${HANDLER_PREDICATE}
+  ORDER BY ${dueAtExpression("delivery")}, delivery.id
+  LIMIT ${CLAIM_SCAN_WINDOW}
+), candidates AS MATERIALIZED (
+  SELECT delivery.id, ${dueAtExpression("delivery")} AS due_at
+  FROM due_window
+  JOIN ${deliveries} AS delivery ON delivery.id = due_window.id
+  WHERE ${UNFINISHED_PREDICATE("delivery")}
+    AND ${dueAtExpression("delivery")} <= $1::timestamptz
+    AND (
+      delivery.key IS NULL
+      OR NOT (
+        EXISTS (
+          SELECT 1 FROM ${deliveries} AS earlier
+          WHERE earlier.key IS NOT NULL AND earlier.handler = delivery.handler AND earlier.key = delivery.key
+            AND ${UNFINISHED_PREDICATE("earlier")}
+            AND earlier.sequence < delivery.sequence
+        )
+        OR ${this.#liveLeaseElsewhere()}
+      )
+    )
+  ORDER BY due_at, delivery.id
+  LIMIT $3::int
+  FOR UPDATE OF delivery SKIP LOCKED
+), ${this.#leaseCandidates()}
+SELECT (SELECT count(*) FROM due_window) >= ${CLAIM_SCAN_WINDOW} AS window_saturated, leased.*
+FROM (SELECT 1) AS anchor
+LEFT JOIN (${this.#leasedRows()}) AS leased ON true
+ORDER BY leased.due_at, leased.delivery_id`;
+  }
+  /**
+   * Slow claim, run when {@link claim} leased too few deliveries from a full
+   * window: the front of the due queue is mostly followers of blocked keys.
+   * Same parameters, rules and locking as {@link claim}, but heads are found
+   * with `DISTINCT ON (handler, key)` over the unfinished-key index, so the
+   * cost follows the number of unfinished keyed deliveries (one index-only
+   * scan) instead of one probe per due follower.
+   */
+  get claimBehindBlockedKeys() {
+    const deliveries = this.#names.deliveries;
+    return `WITH heads AS MATERIALIZED (
+  SELECT DISTINCT ON (head.handler, head.key) head.id
+  FROM ${deliveries} AS head
+  WHERE head.key IS NOT NULL
+    AND ${UNFINISHED_PREDICATE("head")}
+    AND head.handler = ANY (ARRAY(SELECT jsonb_array_elements_text($2::jsonb)))
+  ORDER BY head.handler, head.key, head.sequence
+), keyed AS MATERIALIZED (
+  SELECT delivery.id, ${dueAtExpression("delivery")} AS due_at
+  FROM heads
+  JOIN ${deliveries} AS delivery ON delivery.id = heads.id
+  WHERE ${UNFINISHED_PREDICATE("delivery")}
+    AND ${dueAtExpression("delivery")} <= $1::timestamptz
+    AND NOT ${this.#liveLeaseElsewhere()}
+  ORDER BY due_at, delivery.id
+  LIMIT $3::int
+  FOR UPDATE OF delivery SKIP LOCKED
+), unkeyed AS MATERIALIZED (
+  SELECT delivery.id, ${dueAtExpression("delivery")} AS due_at
+  FROM ${deliveries} AS delivery
+  WHERE delivery.key IS NULL
+    AND ${UNFINISHED_PREDICATE("delivery")}
+    AND ${dueAtExpression("delivery")} <= $1::timestamptz
+    AND ${HANDLER_PREDICATE}
+  ORDER BY due_at, delivery.id
+  LIMIT $3::int
+  FOR UPDATE OF delivery SKIP LOCKED
+), candidates AS MATERIALIZED (
+  SELECT id, due_at FROM (
+    SELECT id, due_at FROM keyed
+    UNION ALL
+    SELECT id, due_at FROM unkeyed
+  ) AS both_sets
+  ORDER BY due_at, id
+  LIMIT $3::int
+), ${this.#leaseCandidates()}
+SELECT false AS window_saturated, leased.*
+FROM (SELECT 1) AS anchor
+LEFT JOIN (${this.#leasedRows()}) AS leased ON true
+ORDER BY leased.due_at, leased.delivery_id`;
+  }
+  /** True when another delivery of the candidate's handler and key holds a live lease. */
+  #liveLeaseElsewhere() {
+    return `EXISTS (
+          SELECT 1 FROM ${this.#names.deliveries} AS running
+          WHERE running.key IS NOT NULL
+            AND running.handler = delivery.handler AND running.key = delivery.key
+            AND running.status = 'processing' AND running.lease_expires_at > $1::timestamptz
+            AND running.id <> delivery.id
+        )`;
+  }
+  /** The `claimed` CTE: leases every row of `candidates`. */
+  #leaseCandidates() {
+    return `claimed AS (
+  UPDATE ${this.#names.deliveries} AS target
+  SET status = 'processing',
+      attempts = target.attempts + 1,
+      lease_owner = $4::text,
+      lease_token = gen_random_uuid()::text,
+      lease_expires_at = $5::timestamptz,
+      updated_at = $1::timestamptz
+  FROM candidates
+  WHERE target.id = candidates.id
+  RETURNING target.id, target.event_id, target.handler, target.attempts, target.lease_token, candidates.due_at
+)`;
+  }
+  /** Leased deliveries joined with their events, as the claim result columns. */
+  #leasedRows() {
+    return `SELECT claimed.due_at, claimed.id AS delivery_id, claimed.handler, claimed.attempts::int AS attempts, claimed.lease_token,
+  ${eventColumns("event")}
+FROM claimed
+JOIN ${this.#names.events} AS event ON event.id = claimed.event_id`;
+  }
+  /** Parameters: `[deliveryId, leaseToken, leaseExpiresAt, now]`. */
+  get extendLease() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET lease_expires_at = $3::timestamptz, updated_at = $4::timestamptz
+WHERE id = $1::text AND status = 'processing' AND lease_token = $2::text`);
+  }
+  /** Parameters: `[deliveryId, leaseToken, now]`. */
+  get complete() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET status = 'completed', completed_at = $3::timestamptz, updated_at = $3::timestamptz, ${CLEAR_LEASE}
+WHERE id = $1::text AND status = 'processing' AND lease_token = $2::text`);
+  }
+  /** Parameters: `[deliveryId, leaseToken, availableAt, errorJson, now]`. */
+  get reschedule() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET status = 'pending', available_at = $3::timestamptz, last_error = $4::jsonb, updated_at = $5::timestamptz, ${CLEAR_LEASE}
+WHERE id = $1::text AND status = 'processing' AND lease_token = $2::text`);
+  }
+  /** Parameters: `[deliveryId, leaseToken, errorJson, now]`. */
+  get bury() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET status = 'dead', last_error = $3::jsonb, updated_at = $4::timestamptz, ${CLEAR_LEASE}
+WHERE id = $1::text AND status = 'processing' AND lease_token = $2::text`);
+  }
+  /**
+   * Gives a leased delivery back without spending its attempt: pending, due
+   * `now`, attempt count decremented. Parameters: `[deliveryId, leaseToken, now]`.
+   */
+  get release() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET status = 'pending', available_at = $3::timestamptz, attempts = attempts - 1, updated_at = $3::timestamptz, ${CLEAR_LEASE}
+WHERE id = $1::text AND status = 'processing' AND lease_token = $2::text`);
+  }
+  /** Parameters: `[deliveryIdsJson, now]`. */
+  get requeue() {
+    return countChanged(`UPDATE ${this.#names.deliveries}
+SET status = 'pending', attempts = 0, available_at = $2::timestamptz, updated_at = $2::timestamptz
+WHERE id = ANY (ARRAY(SELECT jsonb_array_elements_text($1::jsonb))) AND status = 'dead'`);
+  }
+  /** Builds the filtered, creation-ordered listing. */
+  listDeliveries(query) {
+    const parameters = [];
+    const conditions = [];
+    const bind = (value) => {
+      parameters.push(value);
+      return `$${parameters.length}::${typeof value === "number" ? "int" : "text"}`;
+    };
+    if (query.status !== void 0) {
+      conditions.push(`delivery.status = ${bind(query.status)}`);
+    }
+    if (query.handler !== void 0) {
+      conditions.push(`delivery.handler = ${bind(query.handler)}`);
+    }
+    if (query.eventType !== void 0) {
+      conditions.push(`event.type = ${bind(query.eventType)}`);
+    }
+    if (query.eventId !== void 0) {
+      conditions.push(`delivery.event_id = ${bind(query.eventId)}`);
+    }
+    const where = conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`;
+    const limit = bind(query.limit ?? DEFAULT_LIST_LIMIT);
+    const sql = `SELECT delivery.id AS delivery_id, delivery.handler, delivery.status, delivery.attempts::int AS attempts,
+  ${isoText("delivery.available_at")} AS available_at,
+  delivery.lease_owner,
+  ${isoText("delivery.lease_expires_at")} AS lease_expires_at,
+  delivery.last_error::text AS last_error,
+  ${isoText("delivery.created_at")} AS created_at,
+  ${isoText("delivery.updated_at")} AS updated_at,
+  ${isoText("delivery.completed_at")} AS completed_at,
+  ${eventColumns("event")}
+FROM ${this.#names.deliveries} AS delivery
+JOIN ${this.#names.events} AS event ON event.id = delivery.event_id
+${where}
+ORDER BY delivery.created_at, delivery.id
+LIMIT ${limit}`;
+    return { sql, parameters };
+  }
+  get countByStatus() {
+    return `SELECT status, count(*)::text AS count FROM ${this.#names.deliveries} GROUP BY status`;
+  }
+  /** Parameters: `[now]`. */
+  get oldestDue() {
+    return `SELECT ${isoText("due_at")} AS oldest_due_at FROM (
+  SELECT ${dueAtExpression("delivery")} AS due_at
+  FROM ${this.#names.deliveries} AS delivery
+  WHERE delivery.status IN ('pending', 'processing') AND ${dueAtExpression("delivery")} <= $1::timestamptz
+  ORDER BY due_at
+  LIMIT 1
+) AS oldest`;
+  }
+  /**
+   * Deletes one bounded batch of purgeable deliveries and returns the event id
+   * of each deleted delivery. Parameters: `[cutoff, batchSize]`.
+   * `FOR UPDATE SKIP LOCKED` keeps purge from waiting on, or being waited on by, anything.
+   */
+  purgeCompletedBatch() {
+    return this.#purgeBatch(
+      `status = 'completed' AND completed_at < $1::timestamptz`,
+      "completed_at"
+    );
+  }
+  purgeDeadBatch() {
+    return this.#purgeBatch(`status = 'dead' AND updated_at < $1::timestamptz`, "updated_at");
+  }
+  /**
+   * Selects and locks one bounded batch of events created before the cutoff
+   * that no delivery references. Parameters: `[cutoff, batchSize]`. The ids go
+   * through {@link deleteOrphanEvents}, which re-checks under a fresh snapshot.
+   */
+  get lockOrphanEventsBatch() {
+    return `SELECT event.id FROM ${this.#names.events} AS event
+WHERE event.created_at < $1::timestamptz
+  AND NOT EXISTS (SELECT 1 FROM ${this.#names.deliveries} AS delivery WHERE delivery.event_id = event.id)
+ORDER BY event.created_at, event.id
+LIMIT $2::int
+FOR UPDATE OF event SKIP LOCKED`;
+  }
+  /**
+   * Locks the given events, skipping any that a concurrent transaction is
+   * referencing from a new delivery (a foreign key check holds `FOR KEY
+   * SHARE`, which conflicts with this lock). Parameters: `[eventIdsJson]`.
+   */
+  get lockEvents() {
+    return `SELECT id FROM ${this.#names.events}
+WHERE id = ANY (ARRAY(SELECT jsonb_array_elements_text($1::jsonb)))
+FOR UPDATE SKIP LOCKED`;
+  }
+  /**
+   * Deletes locked events that no delivery references. It must run as a
+   * statement of its own after {@link lockEvents}: it then takes a fresh
+   * snapshot that includes every delivery committed before the lock was
+   * granted, so an event that just gained a delivery is never cascaded away.
+   * Parameters: `[eventIdsJson]`.
+   */
+  get deleteOrphanEvents() {
+    const events = this.#names.events;
+    return countChanged(`DELETE FROM ${events} AS event
+WHERE event.id = ANY (ARRAY(SELECT jsonb_array_elements_text($1::jsonb)))
+  AND NOT EXISTS (SELECT 1 FROM ${this.#names.deliveries} AS delivery WHERE delivery.event_id = event.id)`);
+  }
+  #purgeBatch(condition, orderColumn) {
+    const deliveries = this.#names.deliveries;
+    return `WITH batch AS MATERIALIZED (
+  SELECT id FROM ${deliveries}
+  WHERE ${condition}
+  ORDER BY ${orderColumn}, id
+  LIMIT $2::int
+  FOR UPDATE SKIP LOCKED
+), deleted AS (
+  DELETE FROM ${deliveries} AS delivery USING batch WHERE delivery.id = batch.id RETURNING delivery.event_id
+)
+SELECT event_id FROM deleted`;
+  }
+};
+
+// src/postgres-event-store.ts
+var DEFAULT_PURGE_BATCH_SIZE = 1e3;
+var PostgresEventStore = class {
+  #executor;
+  #statements;
+  #schemaStatements;
+  #setupLockKey;
+  #purgeBatchSize;
+  #ownedPool;
+  constructor(options) {
+    const sources = [options.pool, options.connectionString, options.executor].filter(
+      (source) => source !== void 0
+    );
+    if (sources.length !== 1) {
+      throw new ConfigurationError(
+        "PostgresEventStore needs exactly one of pool, connectionString or executor"
+      );
+    }
+    const purgeBatchSize = options.purgeBatchSize ?? DEFAULT_PURGE_BATCH_SIZE;
+    if (!Number.isInteger(purgeBatchSize) || purgeBatchSize < 1) {
+      throw new ConfigurationError(
+        `purgeBatchSize must be a positive integer, received ${String(purgeBatchSize)}`
+      );
+    }
+    const names = resolvePostgresNames(options);
+    this.#statements = new PostgresStatements(names);
+    this.#schemaStatements = createPostgresSchemaStatements(options);
+    this.#setupLockKey = this.#statements.setupLockKey;
+    this.#purgeBatchSize = purgeBatchSize;
+    if (options.executor !== void 0) {
+      this.#executor = options.executor;
+    } else {
+      const pool = options.pool ?? new Pool({ ...options.poolConfig, connectionString: options.connectionString });
+      if (options.pool === void 0) {
+        const logger = options.logger ?? console;
+        pool.on("error", (error) => {
+          logger.error(
+            `[PostgresEventStore](constructor) Idle connection failed, the pool replaces it | error=${error.message}`
+          );
+        });
+        this.#ownedPool = pool;
+      }
+      this.#executor = new PgExecutor(pool);
+    }
+  }
+  /**
+   * Creates the schema, tables and indexes if they do not exist. Safe to call
+   * from many processes at once: a transaction-scoped advisory lock serializes
+   * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
+   * Skip it (`setupStore: false`) when a migration tool applies
+   * `createPostgresSchemaSql()` instead.
+   */
+  async setup() {
+    await this.#executor.transaction(async (transaction) => {
+      await this.#executor.query(this.#statements.setupLock, [this.#setupLockKey], transaction);
+      for (const statement of this.#schemaStatements) {
+        await this.#executor.query(statement, [], transaction);
+      }
+    });
+  }
+  transaction(work) {
+    return this.#executor.transaction(work);
+  }
+  /**
+   * Writes the entries in `transaction`. Keyed events reserve their sequence
+   * numbers first (locking the key rows in sorted order, so publishers cannot
+   * deadlock inside one call), then events, then deliveries, each in a single
+   * multi-row statement ordered by primary key. Two transactions that append
+   * keys in opposite order across several calls can still deadlock (40P01);
+   * the database rolls one back and the caller retries.
+   * A duplicate event id still consumes a sequence number; gaps are harmless
+   * because only the order of sequences matters.
+   */
+  async append(transaction, entries, now) {
+    const plan = planAppend(entries);
+    const createdAt = now.toISOString();
+    const sequences = await this.#reserveSequences(plan.events, transaction);
+    const insertedEventIds = new Set(
+      plan.events.length === 0 ? [] : (await this.#executor.query(
+        this.#statements.insertEvents,
+        [JSON.stringify(toEventRows(plan.events, sequences)), createdAt],
+        transaction
+      )).map((row) => row["id"])
+    );
+    const insertedDeliveries = plan.deliveries.length === 0 ? [] : await this.#executor.query(
+      this.#statements.insertDeliveries,
+      [JSON.stringify(plan.deliveries), createdAt],
+      transaction
+    );
+    const appendedEventIds = [];
+    const duplicateEventIds = [];
+    for (const { eventId, repeated } of plan.outcomes) {
+      (!repeated && insertedEventIds.has(eventId) ? appendedEventIds : duplicateEventIds).push(
+        eventId
+      );
+    }
+    return {
+      appendedEventIds,
+      duplicateEventIds,
+      appendedDeliveryCount: insertedDeliveries.length
+    };
+  }
+  /**
+   * Leases up to `limit` due deliveries with `FOR UPDATE SKIP LOCKED`. The fast
+   * statement examines the first due deliveries; only when they are mostly
+   * blocked followers of busy keys does a second statement look at the heads of
+   * all keys. See {@link PostgresStatements.claim} for why that keeps a
+   * (handler, key) strictly one-at-a-time and in order.
+   */
+  async claim(request) {
+    if (request.handlers.length === 0 || !(request.limit > 0)) {
+      return [];
+    }
+    const parameters = (limit) => [
+      request.now.toISOString(),
+      JSON.stringify(request.handlers),
+      limit,
+      request.leaseOwner,
+      request.leaseExpiresAt.toISOString()
+    ];
+    const fastRows = await this.#executor.query(this.#statements.claim, parameters(request.limit));
+    const leased = fastRows.filter((row) => row["delivery_id"] !== null);
+    if (leased.length < request.limit && fastRows[0]["window_saturated"] === true) {
+      leased.push(
+        ...(await this.#executor.query(
+          this.#statements.claimBehindBlockedKeys,
+          parameters(request.limit - leased.length)
+        )).filter((row) => row["delivery_id"] !== null)
+      );
+    }
+    return leased.map((row) => mapClaimedDelivery(row, request.leaseExpiresAt));
+  }
+  extendLease(lease, leaseExpiresAt, now) {
+    return this.#changed(this.#statements.extendLease, [
+      lease.deliveryId,
+      lease.leaseToken,
+      leaseExpiresAt.toISOString(),
+      now.toISOString()
+    ]);
+  }
+  complete(lease, now, transaction) {
+    return this.#changed(
+      this.#statements.complete,
+      [lease.deliveryId, lease.leaseToken, now.toISOString()],
+      transaction
+    );
+  }
+  reschedule(lease, availableAt, error, now) {
+    return this.#changed(this.#statements.reschedule, [
+      lease.deliveryId,
+      lease.leaseToken,
+      availableAt.toISOString(),
+      JSON.stringify(error),
+      now.toISOString()
+    ]);
+  }
+  bury(lease, error, now) {
+    return this.#changed(this.#statements.bury, [
+      lease.deliveryId,
+      lease.leaseToken,
+      JSON.stringify(error),
+      now.toISOString()
+    ]);
+  }
+  /** Returns a leased delivery to pending, due now, without counting the attempt. */
+  release(lease, now) {
+    return this.#changed(this.#statements.release, [
+      lease.deliveryId,
+      lease.leaseToken,
+      now.toISOString()
+    ]);
+  }
+  async listDeliveries(query) {
+    const statement = this.#statements.listDeliveries(query);
+    const rows = await this.#executor.query(statement.sql, statement.parameters);
+    return rows.map(mapDeliveryRecord);
+  }
+  async requeue(deliveryIds, now) {
+    const rows = await this.#executor.query(this.#statements.requeue, [
+      JSON.stringify(deliveryIds),
+      now.toISOString()
+    ]);
+    return readCount(rows[0], "count");
+  }
+  /**
+   * Deletes purgeable deliveries in batches of `purgeBatchSize`, one short
+   * transaction per batch, then the events those batches left without any
+   * delivery. Finally, events created before the earliest given cutoff that
+   * have no delivery at all are removed: they are what a publish leaves behind
+   * when its last delivery was purged in the same instant, or when no handler
+   * was subscribed. Events that a concurrent publish is attaching a delivery
+   * to are skipped and kept.
+   */
+  async purge(request) {
+    const total = { deletedDeliveries: 0, deletedEvents: 0 };
+    const batches = [
+      [this.#statements.purgeCompletedBatch(), request.completedBefore],
+      [this.#statements.purgeDeadBatch(), request.deadBefore]
+    ];
+    for (const [sql, cutoff] of batches) {
+      if (cutoff === void 0) {
+        continue;
+      }
+      let deletedInBatch = this.#purgeBatchSize;
+      while (deletedInBatch === this.#purgeBatchSize) {
+        const batch = await this.#purgeBatch(sql, cutoff);
+        deletedInBatch = batch.deletedDeliveries;
+        total.deletedDeliveries += batch.deletedDeliveries;
+        total.deletedEvents += batch.deletedEvents;
+      }
+    }
+    const orphanCutoff = [request.completedBefore, request.deadBefore].filter((cutoff) => cutoff !== void 0).sort((first, second) => first.getTime() - second.getTime())[0];
+    if (orphanCutoff !== void 0) {
+      total.deletedEvents += await this.#purgeOrphanEvents(orphanCutoff);
+    }
+    return total;
+  }
+  async statistics(now) {
+    const counts = {
+      pending: 0,
+      processing: 0,
+      completed: 0,
+      dead: 0
+    };
+    for (const row of await this.#executor.query(this.#statements.countByStatus, [])) {
+      counts[row["status"]] = readCount(row, "count");
+    }
+    const oldestDue = await this.#executor.query(this.#statements.oldestDue, [now.toISOString()]);
+    return { ...counts, oldestDueAt: mapOldestDueAt(oldestDue) };
+  }
+  /** Ends the pool this store created from `connectionString`. Pools and executors you passed in stay open. */
+  async close() {
+    const pool = this.#ownedPool;
+    this.#ownedPool = void 0;
+    await pool?.end();
+  }
+  async #changed(sql, parameters, transaction) {
+    const rows = await this.#executor.query(sql, parameters, transaction);
+    return readCount(rows[0], "count") > 0;
+  }
+  async #reserveSequences(events, transaction) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      if (event.key !== null) {
+        counts.set(event.key, (counts.get(event.key) ?? 0) + 1);
+      }
+    }
+    const firstSequences = /* @__PURE__ */ new Map();
+    if (counts.size === 0) {
+      return firstSequences;
+    }
+    const requested = [...counts].map(([key, count]) => ({ key, count }));
+    const rows = await this.#executor.query(
+      this.#statements.reserveSequences,
+      [JSON.stringify(requested)],
+      transaction
+    );
+    for (const row of rows) {
+      const key = row["key"];
+      firstSequences.set(key, BigInt(row["sequence"]) - BigInt(counts.get(key)) + 1n);
+    }
+    return firstSequences;
+  }
+  async #purgeOrphanEvents(cutoff) {
+    let deletedEvents = 0;
+    let removedInBatch = this.#purgeBatchSize;
+    while (removedInBatch === this.#purgeBatchSize) {
+      removedInBatch = await this.#executor.transaction(async (transaction) => {
+        const locked = await this.#executor.query(
+          this.#statements.lockOrphanEventsBatch,
+          [cutoff.toISOString(), this.#purgeBatchSize],
+          transaction
+        );
+        const removed = await this.#executor.query(
+          this.#statements.deleteOrphanEvents,
+          [JSON.stringify(locked.map((row) => row["id"]))],
+          transaction
+        );
+        return readCount(removed[0], "count");
+      });
+      deletedEvents += removedInBatch;
+    }
+    return deletedEvents;
+  }
+  async #purgeBatch(sql, cutoff) {
+    return this.#executor.transaction(async (transaction) => {
+      const deleted = await this.#executor.query(
+        sql,
+        [cutoff.toISOString(), this.#purgeBatchSize],
+        transaction
+      );
+      if (deleted.length === 0) {
+        return { deletedDeliveries: 0, deletedEvents: 0 };
+      }
+      const eventIds = JSON.stringify([
+        ...new Set(deleted.map((row) => row["event_id"]))
+      ]);
+      const locked = await this.#executor.query(
+        this.#statements.lockEvents,
+        [eventIds],
+        transaction
+      );
+      const removed = await this.#executor.query(
+        this.#statements.deleteOrphanEvents,
+        [JSON.stringify(locked.map((row) => row["id"]))],
+        transaction
+      );
+      return { deletedDeliveries: deleted.length, deletedEvents: readCount(removed[0], "count") };
+    });
+  }
+};
+function planAppend(entries) {
+  const events = [];
+  const deliveries = [];
+  const outcomes = [];
+  const seenEventIds = /* @__PURE__ */ new Set();
+  const seenDeliveries = /* @__PURE__ */ new Set();
+  for (const { event, deliveries: newDeliveries } of entries) {
+    const repeated = seenEventIds.has(event.id);
+    seenEventIds.add(event.id);
+    outcomes.push({ eventId: event.id, repeated });
+    if (!repeated) {
+      events.push(event);
+    }
+    for (const delivery of newDeliveries) {
+      const identity = `${event.id}\0${delivery.handler}`;
+      if (!seenDeliveries.has(identity)) {
+        seenDeliveries.add(identity);
+        deliveries.push({
+          id: delivery.id,
+          event_id: event.id,
+          handler: delivery.handler,
+          available_at: delivery.availableAt.toISOString()
+        });
+      }
+    }
+  }
+  return { events, deliveries, outcomes };
+}
+function toEventRows(events, firstSequences) {
+  const nextSequences = new Map(firstSequences);
+  return events.map((event) => {
+    let sequence = null;
+    if (event.key !== null) {
+      const next = nextSequences.get(event.key);
+      nextSequences.set(event.key, next + 1n);
+      sequence = next.toString();
+    }
+    return {
+      id: event.id,
+      type: event.type,
+      source: event.source,
+      key: event.key,
+      sequence,
+      payload: event.payload,
+      headers: event.headers,
+      correlation_id: event.correlationId,
+      causation_id: event.causationId,
+      occurred_at: event.occurredAt.toISOString()
+    };
+  });
+}
+
+export { PgExecutor, PostgresEventStore, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map