@rotorsoft/act-pg 0.18.5 → 0.19.0

package/dist/index.js

@@ -1,650 +0,0 @@
-// src/PostgresStore.ts
-import {
-  ConcurrencyError,
-  log,
-  SNAP_EVENT,
-  TOMBSTONE_EVENT
-} from "@rotorsoft/act";
-import pg from "pg";
-
-// src/utils.ts
-var ISO_8601 = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\.\d+)?(Z|[+-][0-2][0-9]:[0-5][0-9])?$/;
-var dateReviver = (_key, value) => {
-  if (typeof value === "string" && ISO_8601.test(value)) {
-    return new Date(value);
-  }
-  return value;
-};
-
-// src/PostgresStore.ts
-var logger = log();
-var { Pool, types } = pg;
-types.setTypeParser(
-  types.builtins.JSONB,
-  (val) => JSON.parse(val, dateReviver)
-);
-var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-var PG_UNIQUE_VIOLATION = "23505";
-function assertSafeIdentifier(value, label) {
-  if (!SAFE_IDENTIFIER.test(value))
-    throw new Error(`Unsafe SQL identifier for ${label}: "${value}"`);
-}
-var DEFAULT_CONFIG = {
-  host: "localhost",
-  port: 5432,
-  database: "postgres",
-  user: "postgres",
-  password: "postgres",
-  schema: "public",
-  table: "events"
-};
-var PostgresStore = class {
-  _pool;
-  config;
-  _fqt;
-  _fqs;
-  /**
-   * Create a new PostgresStore instance.
-   * @param config Partial configuration (host, port, user, password, schema, table, etc.)
-   */
-  constructor(config = {}) {
-    this.config = { ...DEFAULT_CONFIG, ...config };
-    assertSafeIdentifier(this.config.schema, "schema");
-    assertSafeIdentifier(this.config.table, "table");
-    const { schema: _, table: __, ...poolConfig } = this.config;
-    this._pool = new Pool(poolConfig);
-    this._fqt = `"${this.config.schema}"."${this.config.table}"`;
-    this._fqs = `"${this.config.schema}"."${this.config.table}_streams"`;
-  }
-  /**
-   * Dispose of the store and close all database connections.
-   * @returns Promise that resolves when all connections are closed
-   */
-  async dispose() {
-    await this._pool.end();
-  }
-  /**
-   * Seed the database with required tables, indexes, and schema for event storage.
-   * @returns Promise that resolves when seeding is complete
-   * @throws Error if seeding fails
-   */
-  async seed() {
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      await client.query(
-        `CREATE SCHEMA IF NOT EXISTS "${this.config.schema}";`
-      );
-      await client.query(
-        `CREATE TABLE IF NOT EXISTS ${this._fqt} (
-          id serial PRIMARY KEY,
-          name varchar(100) COLLATE pg_catalog."default" NOT NULL,
-          data jsonb,
-          stream varchar(100) COLLATE pg_catalog."default" NOT NULL,
-          version int NOT NULL,
-          created timestamptz NOT NULL DEFAULT now(),
-          meta jsonb
-        ) TABLESPACE pg_default;`
-      );
-      await client.query(
-        `CREATE UNIQUE INDEX IF NOT EXISTS "${this.config.table}_stream_ix" 
-        ON ${this._fqt} (stream COLLATE pg_catalog."default", version);`
-      );
-      await client.query(
-        `CREATE INDEX IF NOT EXISTS "${this.config.table}_name_ix" 
-        ON ${this._fqt} (name COLLATE pg_catalog."default");`
-      );
-      await client.query(
-        `CREATE INDEX IF NOT EXISTS "${this.config.table}_created_id_ix" 
-        ON ${this._fqt} (created, id);`
-      );
-      await client.query(
-        `CREATE INDEX IF NOT EXISTS "${this.config.table}_correlation_ix" 
-        ON ${this._fqt} ((meta ->> 'correlation') COLLATE pg_catalog."default");`
-      );
-      await client.query(
-        `CREATE TABLE IF NOT EXISTS ${this._fqs} (
-          stream varchar(100) COLLATE pg_catalog."default" PRIMARY KEY,
-          source varchar(100) COLLATE pg_catalog."default",
-          at int NOT NULL DEFAULT -1,
-          retry smallint NOT NULL DEFAULT 0,
-          blocked boolean NOT NULL DEFAULT false,
-          error text,
-          leased_by text,
-          leased_until timestamptz
-        ) TABLESPACE pg_default;`
-      );
-      await client.query(
-        `CREATE INDEX IF NOT EXISTS "${this.config.table}_streams_fetch_ix" 
-        ON ${this._fqs} (blocked, at);`
-      );
-      await client.query("COMMIT");
-      logger.info(
-        `Seeded schema "${this.config.schema}" with table "${this.config.table}"`
-      );
-    } catch (error) {
-      await client.query("ROLLBACK");
-      logger.error(error);
-      throw error;
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Drop all tables and schema created by the store (for testing or cleanup).
-   * @returns Promise that resolves when the schema is dropped
-   */
-  async drop() {
-    await this._pool.query(
-      `
-      DO $$
-      BEGIN
-        IF EXISTS (SELECT 1 FROM information_schema.schemata
-          WHERE schema_name = '${this.config.schema}'
-        ) THEN
-          EXECUTE 'DROP TABLE IF EXISTS ${this._fqt}';
-          EXECUTE 'DROP TABLE IF EXISTS ${this._fqs}';
-          IF '${this.config.schema}' <> 'public' THEN
-            EXECUTE 'DROP SCHEMA "${this.config.schema}" CASCADE';
-          END IF;
-        END IF;
-      END
-      $$;
-    `
-    );
-  }
-  /**
-   * Query events from the store, optionally filtered by stream, event name, time, etc.
-   *
-   * @param callback Function called for each event found
-   * @param query (Optional) Query filter (stream, names, before, after, etc.)
-   * @returns The number of events found
-   *
-   * @example
-   * await store.query((event) => console.log(event), { stream: "A" });
-   */
-  async query(callback, query) {
-    const {
-      stream,
-      names,
-      before,
-      after,
-      limit,
-      created_before,
-      created_after,
-      backward,
-      correlation,
-      with_snaps = false
-    } = query || {};
-    let sql = `SELECT * FROM ${this._fqt}`;
-    const conditions = [];
-    const values = [];
-    if (query) {
-      if (typeof after !== "undefined") {
-        values.push(after);
-        conditions.push(`id>$${values.length}`);
-      } else {
-        conditions.push("id>-1");
-      }
-      if (stream) {
-        values.push(stream);
-        conditions.push(
-          query.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
-        );
-      }
-      if (names?.length) {
-        values.push(names);
-        conditions.push(`name = ANY($${values.length})`);
-      }
-      if (before) {
-        values.push(before);
-        conditions.push(`id<$${values.length}`);
-      }
-      if (created_after) {
-        values.push(created_after.toISOString());
-        conditions.push(`created>$${values.length}`);
-      }
-      if (created_before) {
-        values.push(created_before.toISOString());
-        conditions.push(`created<$${values.length}`);
-      }
-      if (correlation) {
-        values.push(correlation);
-        conditions.push(`meta->>'correlation'=$${values.length}`);
-      }
-      if (!with_snaps) {
-        conditions.push(`name <> '${SNAP_EVENT}'`);
-      }
-    }
-    if (conditions.length) {
-      sql += " WHERE " + conditions.join(" AND ");
-    }
-    sql += ` ORDER BY id ${backward ? "DESC" : "ASC"}`;
-    if (limit) {
-      values.push(limit);
-      sql += ` LIMIT $${values.length}`;
-    }
-    const result = await this._pool.query(sql, values);
-    for (const row of result.rows) callback(row);
-    return result.rowCount ?? 0;
-  }
-  /**
-   * Commit new events to the store for a given stream, with concurrency control.
-   *
-   * @param stream The stream name
-   * @param msgs Array of messages (event name and data)
-   * @param meta Event metadata (correlation, causation, etc.)
-   * @param expectedVersion (Optional) Expected stream version for concurrency control
-   * @returns Array of committed events
-   * @throws ConcurrencyError if the expected version does not match
-   */
-  async commit(stream, msgs, meta, expectedVersion) {
-    if (msgs.length === 0) return [];
-    const client = await this._pool.connect();
-    let version = -1;
-    try {
-      await client.query("BEGIN");
-      const last = await client.query(
-        `SELECT version
-        FROM ${this._fqt}
-        WHERE stream=$1 ORDER BY version DESC LIMIT 1`,
-        [stream]
-      );
-      version = last.rowCount ? last.rows[0].version : -1;
-      if (typeof expectedVersion === "number" && version !== expectedVersion)
-        throw new ConcurrencyError(
-          stream,
-          version,
-          msgs,
-          expectedVersion
-        );
-      const committed = [];
-      for (const { name, data } of msgs) {
-        version++;
-        const sql = `
-          INSERT INTO ${this._fqt}(name, data, stream, version, meta)
-          VALUES($1, $2, $3, $4, $5) RETURNING *`;
-        const vals = [name, data, stream, version, meta];
-        try {
-          const { rows } = await client.query(sql, vals);
-          committed.push(rows.at(0));
-        } catch (error) {
-          if (error?.code === PG_UNIQUE_VIOLATION) {
-            throw new ConcurrencyError(
-              stream,
-              version - 1,
-              msgs,
-              expectedVersion ?? -1
-            );
-          }
-          throw error;
-        }
-      }
-      await client.query(
-        `
-            NOTIFY "${this.config.table}", '${JSON.stringify({
-          operation: "INSERT",
-          id: committed[0].name,
-          position: committed[0].id
-        })}';
-            COMMIT;
-            `
-      ).catch((error) => {
-        logger.error(error);
-        throw new ConcurrencyError(
-          stream,
-          version,
-          msgs,
-          expectedVersion || -1
-        );
-      });
-      return committed;
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      throw error;
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Atomically discovers and leases streams for reaction processing.
-   *
-   * Uses `FOR UPDATE SKIP LOCKED` to implement zero-contention competing consumers:
-   * - Workers never block each other — locked rows are silently skipped
-   * - Discovery and locking happen in a single atomic transaction
-   * - No wasted polls — every returned stream is exclusively owned
-   *
-   * @param lagging - Max streams from lagging frontier (ascending watermark)
-   * @param leading - Max streams from leading frontier (descending watermark)
-   * @param by - Lease holder identifier (UUID)
-   * @param millis - Lease duration in milliseconds
-   * @returns Leased streams with metadata
-   */
-  async claim(lagging, leading, by, millis) {
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      const { rows } = await client.query(
-        `
-        WITH
-        available AS (
-          SELECT stream, source, at
-          FROM ${this._fqs} s
-          WHERE blocked = false
-            AND (leased_by IS NULL OR leased_until <= NOW())
-            AND (s.at < 0 OR EXISTS (
-              SELECT 1 FROM ${this._fqt} e
-              WHERE e.id > s.at
-                AND e.name <> '${SNAP_EVENT}'
-                AND (s.source IS NULL OR e.stream = COALESCE(s.source, s.stream))
-              LIMIT 1
-            ))
-          FOR UPDATE SKIP LOCKED
-        ),
-        lag AS (
-          SELECT stream, source, at, TRUE AS lagging
-          FROM available
-          ORDER BY at ASC
-          LIMIT $1
-        ),
-        lead AS (
-          SELECT stream, source, at, FALSE AS lagging
-          FROM available
-          ORDER BY at DESC
-          LIMIT $2
-        ),
-        combined AS (
-          SELECT DISTINCT ON (stream) stream, source, at, lagging
-          FROM (SELECT * FROM lag UNION ALL SELECT * FROM lead) t
-          ORDER BY stream, at
-        )
-        UPDATE ${this._fqs} s
-        SET
-          leased_by = $3,
-          leased_until = NOW() + ($4::integer || ' milliseconds')::interval,
-          retry = s.retry + 1
-        FROM combined c
-        WHERE s.stream = c.stream
-        RETURNING s.stream, s.source, s.at, s.retry, c.lagging
-        `,
-        [lagging, leading, by, millis]
-      );
-      await client.query("COMMIT");
-      return rows.map(({ stream, source, at, retry, lagging: lagging2 }) => ({
-        stream,
-        source: source ?? void 0,
-        at,
-        by,
-        retry,
-        lagging: lagging2
-      }));
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      logger.error(error);
-      return [];
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Registers streams for event processing.
-   * Upserts stream entries so they become visible to claim().
-   * Also returns the current max watermark across all subscriptions.
-   * @param streams - Streams to register with optional source.
-   * @returns subscribed count and current max watermark.
-   */
-  async subscribe(streams) {
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      let subscribed = 0;
-      if (streams.length) {
-        const { rowCount } = await client.query(
-          `
-          INSERT INTO ${this._fqs} (stream, source)
-          SELECT s->>'stream', s->>'source'
-          FROM jsonb_array_elements($1::jsonb) AS s
-          ON CONFLICT (stream) DO NOTHING
-          `,
-          [JSON.stringify(streams)]
-        );
-        subscribed = rowCount ?? 0;
-      }
-      const { rows } = await client.query(
-        `SELECT COALESCE(MAX(at), -1) AS max FROM ${this._fqs}`
-      );
-      await client.query("COMMIT");
-      return { subscribed, watermark: rows[0]?.max ?? -1 };
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      logger.error(error);
-      return { subscribed: 0, watermark: -1 };
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Acknowledge and release leases after processing, updating stream positions.
-   *
-   * @param leases - Leases to acknowledge, including last processed watermark and lease holder.
-   * @returns Acked leases.
-   */
-  async ack(leases) {
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      const { rows } = await client.query(
-        `
-      WITH input AS (
-        SELECT * FROM jsonb_to_recordset($1::jsonb)
-        AS x(stream text, by text, at int, lagging boolean)
-      )
-      UPDATE ${this._fqs} AS s
-      SET
-        at = i.at,
-        retry = -1,
-        leased_by = NULL,
-        leased_until = NULL
-      FROM input i
-      WHERE s.stream = i.stream AND s.leased_by = i.by
-      RETURNING s.stream, s.source, s.at, i.by, s.retry, i.lagging
-      `,
-        [JSON.stringify(leases)]
-      );
-      await client.query("COMMIT");
-      return rows.map((row) => ({
-        stream: row.stream,
-        source: row.source ?? void 0,
-        at: row.at,
-        by: row.by,
-        retry: row.retry,
-        lagging: row.lagging
-      }));
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      logger.error(error);
-      return [];
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
-   * @param leases - Leases to block, including lease holder and last error message.
-   * @returns Blocked leases.
-   */
-  async block(leases) {
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      const { rows } = await client.query(
-        `
-      WITH input AS (
-        SELECT * FROM jsonb_to_recordset($1::jsonb)
-        AS x(stream text, by text, error text, lagging boolean)
-      )
-      UPDATE ${this._fqs} AS s
-      SET blocked = true, error = i.error
-      FROM input i
-      WHERE s.stream = i.stream AND s.leased_by = i.by AND s.blocked = false
-      RETURNING s.stream, s.source, s.at, i.by, s.retry, s.error, i.lagging
-      `,
-        [JSON.stringify(leases)]
-      );
-      await client.query("COMMIT");
-      return rows.map((row) => ({
-        stream: row.stream,
-        source: row.source ?? void 0,
-        at: row.at,
-        by: row.by,
-        retry: row.retry,
-        lagging: row.lagging,
-        error: row.error
-      }));
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      logger.error(error);
-      return [];
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Reset watermarks for the given streams to -1, clearing retry, blocked,
-   * error, and lease state so they can be replayed from the beginning.
-   * @param streams - Stream names to reset.
-   * @returns Count of streams that were actually reset.
-   */
-  async reset(streams) {
-    if (!streams.length) return 0;
-    const { rowCount } = await this._pool.query(
-      `UPDATE ${this._fqs}
-       SET at = -1, retry = 0, blocked = false, error = NULL,
-           leased_by = NULL, leased_until = NULL
-       WHERE stream = ANY($1)`,
-      [streams]
-    );
-    return rowCount ?? 0;
-  }
-  /**
-   * Streams subscription positions to a callback, ordered by stream name,
-   * along with the highest event id in the store.
-   *
-   * Filters (`stream`, `source`, `blocked`, `after`, `limit`) are applied
-   * server-side. `stream`/`source` are regex by default (`~`), or exact
-   * with `*_exact: true` — same convention as {@link Store.query}.
-   *
-   * @returns `maxEventId` and the `count` of positions emitted.
-   */
-  async query_streams(callback, query) {
-    const limit = query?.limit ?? 100;
-    const conditions = [];
-    const values = [];
-    if (query?.stream !== void 0) {
-      values.push(query.stream);
-      conditions.push(
-        query.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
-      );
-    }
-    if (query?.source !== void 0) {
-      conditions.push(`source IS NOT NULL`);
-      values.push(query.source);
-      conditions.push(
-        query.source_exact ? `source = $${values.length}` : `source ~ $${values.length}`
-      );
-    }
-    if (query?.blocked !== void 0) {
-      values.push(query.blocked);
-      conditions.push(`blocked = $${values.length}`);
-    }
-    if (query?.after !== void 0) {
-      values.push(query.after);
-      conditions.push(`stream > $${values.length}`);
-    }
-    let sql = `SELECT stream, source, at, retry, blocked, error, leased_by, leased_until FROM ${this._fqs}`;
-    if (conditions.length) sql += " WHERE " + conditions.join(" AND ");
-    values.push(limit);
-    sql += ` ORDER BY stream LIMIT $${values.length}`;
-    const client = await this._pool.connect();
-    try {
-      const [streamsResult, maxResult] = await Promise.all([
-        client.query(sql, values),
-        client.query(
-          `SELECT COALESCE(MAX(id), -1) AS m FROM ${this._fqt}`
-        )
-      ]);
-      let count = 0;
-      for (const row of streamsResult.rows) {
-        callback({
-          stream: row.stream,
-          source: row.source ?? void 0,
-          at: row.at,
-          retry: row.retry,
-          blocked: row.blocked,
-          error: row.error ?? "",
-          leased_by: row.leased_by ?? void 0,
-          leased_until: row.leased_until ?? void 0
-        });
-        count++;
-      }
-      return { maxEventId: Number(maxResult.rows[0].m), count };
-    } finally {
-      client.release();
-    }
-  }
-  /**
-   * Atomically truncates streams and seeds each with a snapshot or tombstone.
-   * @param targets - Streams to truncate with optional snapshot state and meta.
-   * @returns Map keyed by stream name, each entry with `deleted` count and `committed` event.
-   */
-  async truncate(targets) {
-    if (!targets.length) return /* @__PURE__ */ new Map();
-    const streams = targets.map((t) => t.stream);
-    const client = await this._pool.connect();
-    try {
-      await client.query("BEGIN");
-      await client.query(`DELETE FROM ${this._fqs} WHERE stream = ANY($1)`, [
-        streams
-      ]);
-      const result = /* @__PURE__ */ new Map();
-      for (const { stream, snapshot, meta } of targets) {
-        const { rowCount } = await client.query(
-          `DELETE FROM ${this._fqt} WHERE stream = $1`,
-          [stream]
-        );
-        const name = snapshot !== void 0 ? SNAP_EVENT : TOMBSTONE_EVENT;
-        const { rows } = await client.query(
-          `INSERT INTO ${this._fqt}(name, data, stream, version, created, meta)
-           VALUES($1, $2, $3, 0, now(), $4) RETURNING *`,
-          [
-            name,
-            snapshot ?? {},
-            stream,
-            meta ?? { correlation: "", causation: {} }
-          ]
-        );
-        result.set(stream, {
-          deleted: rowCount ?? 0,
-          committed: rows[0]
-        });
-      }
-      await client.query("COMMIT");
-      return result;
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      throw error;
-    } finally {
-      client.release();
-    }
-  }
-};
-export {
-  PostgresStore
-};
-//# sourceMappingURL=index.js.map