@cnstra/pg-boss 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,37 +1,269 @@
 #!/usr/bin/env node
 var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/cli.ts
 var import_pg = require("pg");
 
-// src/migrate.ts
-var DEFAULT_TABLE = "cns_pgboss_progress";
-function assertSafeTable(table) {
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
-    throw new Error(`[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`);
+// ../postgres-schema/dist/index.mjs
+var __defProp2 = Object.defineProperty;
+var __defNormalProp2 = /* @__PURE__ */ __name((obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value, "__defNormalProp");
+var __name2 = /* @__PURE__ */ __name((target, value) => __defProp2(target, "name", { value, configurable: true }), "__name");
+var __publicField2 = /* @__PURE__ */ __name((obj, key, value) => __defNormalProp2(obj, typeof key !== "symbol" ? key + "" : key, value), "__publicField");
+var _a;
+var _CNSPostgresSchemaMigrator = (_a = class {
+  constructor(options) {
+    __publicField2(this, "options");
+    __publicField2(this, "steps");
+    var _a4;
+    this.options = options;
+    this.steps = [
+      ...options.steps
+    ].sort((left, right) => left.step - right.step);
+    this.steps.forEach((step, index) => {
+      if (step.step !== index + 1) throw new Error(`[${options.name}] schema steps must be numbered 1, 2, 3\u2026; found ${step.step} at position ${index + 1}`);
+    });
+    if (((_a4 = this.steps[0]) == null ? void 0 : _a4.kind) !== "expand") throw new Error(`[${options.name}] schema step 1 must be an expand step`);
   }
-  return table;
-}
-__name(assertSafeTable, "assertSafeTable");
-function pgBossProgressSchemaSql(table = DEFAULT_TABLE) {
-  assertSafeTable(table);
-  return `CREATE TABLE IF NOT EXISTS ${table} (
-    key text PRIMARY KEY,
+  migrationTable(tablePrefix) {
+    return `${tablePrefix}${this.options.name}_migration`;
+  }
+  async migrate(database, tablePrefix, options = {}) {
+    await database.transaction(async (connection) => {
+      await connection.query("SELECT pg_advisory_xact_lock($1, hashtext($2))", [
+        _a.LOCK_NAMESPACE,
+        tablePrefix + this.options.name
+      ]);
+      await connection.query(`SET LOCAL lock_timeout = '${_a.LOCK_TIMEOUT}'`);
+      const applied = await this.readAppliedSteps(connection, tablePrefix);
+      if (applied === void 0) await this.assertNoUntrackedTables(connection, tablePrefix);
+      const pending = this.pendingSteps(applied != null ? applied : /* @__PURE__ */ new Map(), applied === void 0 || options.contract === true);
+      if (pending.length > 0) await connection.query(this.sqlFor(tablePrefix, pending, applied === void 0));
+    });
+  }
+  async verify(connection, tablePrefix) {
+    const applied = await this.readAppliedSteps(connection, tablePrefix);
+    if (applied === void 0) {
+      throw new Error(`[${this.options.name}] the schema is not installed under prefix "${tablePrefix}": run migrate()`);
+    }
+    const missing = this.steps.filter((step) => step.kind === "expand" && !applied.has(step.step)).map((step) => step.step);
+    if (missing.length > 0) {
+      throw new Error(`[${this.options.name}] schema steps ${missing.join(", ")} are not applied under prefix "${tablePrefix}": run migrate()`);
+    }
+    const unknown = [
+      ...applied
+    ].filter(([step, kind]) => kind === "contract" && step > this.steps.length).map(([step]) => step);
+    if (unknown.length > 0) {
+      throw new Error(`[${this.options.name}] the database has contract steps ${unknown.join(", ")} that this version does not know: upgrade the package`);
+    }
+  }
+  migrationSql(tablePrefix, appliedSteps = [], options = {}) {
+    const fresh = appliedSteps.length === 0;
+    const applied = new Map(appliedSteps.map((step) => [
+      step,
+      "expand"
+    ]));
+    return this.sqlFor(tablePrefix, this.pendingSteps(applied, fresh || options.contract === true), fresh);
+  }
+  assertTablePrefix(tablePrefix, longestSuffix) {
+    const longest = Math.max(longestSuffix.length, `${this.options.name}_migration`.length);
+    const limit = _a.MAX_IDENTIFIER_LENGTH - longest;
+    if (!new RegExp(`^[A-Za-z_][A-Za-z0-9_]{0,${limit - 1}}$`).test(tablePrefix)) {
+      throw new Error(`[${this.options.name}] unsafe table prefix ${JSON.stringify(tablePrefix)}: letters, digits and _ only, at most ${limit} characters`);
+    }
+    return tablePrefix;
+  }
+  pendingSteps(applied, withContract) {
+    return this.steps.filter((step) => !applied.has(step.step) && (step.kind === "expand" || withContract));
+  }
+  sqlFor(tablePrefix, steps, createMigrationTable) {
+    const table = this.migrationTable(tablePrefix);
+    const parts = createMigrationTable ? [
+      `CREATE TABLE ${table} (step integer PRIMARY KEY, kind text NOT NULL CHECK (kind IN ('expand', 'contract')));`
+    ] : [];
+    for (const step of steps) {
+      parts.push(step.sql(tablePrefix), `INSERT INTO ${table} (step, kind) VALUES (${step.step}, '${step.kind}');`);
+    }
+    return parts.join("\n");
+  }
+  async readAppliedSteps(connection, tablePrefix) {
+    var _a4;
+    const table = this.migrationTable(tablePrefix);
+    const exists = await connection.query("SELECT to_regclass($1)::text AS found", [
+      table
+    ]);
+    if (((_a4 = exists.rows[0]) == null ? void 0 : _a4.found) == null) return void 0;
+    const rows = await connection.query(`SELECT step, kind FROM ${table}`);
+    return new Map(rows.rows.map((row) => [
+      Number(row.step),
+      row.kind
+    ]));
+  }
+  async assertNoUntrackedTables(connection, tablePrefix) {
+    const tables = this.options.tables(tablePrefix);
+    const found = await connection.query("SELECT name FROM unnest($1::text[]) AS name WHERE to_regclass(name) IS NOT NULL", [
+      tables
+    ]);
+    if (found.rows.length > 0) {
+      throw new Error(`[${this.options.name}] tables ${found.rows.map((row) => row.name).join(", ")} exist without ${this.migrationTable(tablePrefix)}: they were created by an earlier unversioned release; drop them or move the data before migrate()`);
+    }
+  }
+}, __name(_a, "_CNSPostgresSchemaMigrator"), _a);
+__name2(_CNSPostgresSchemaMigrator, "CNSPostgresSchemaMigrator");
+__publicField2(_CNSPostgresSchemaMigrator, "LOCK_NAMESPACE", 6);
+__publicField2(_CNSPostgresSchemaMigrator, "LOCK_TIMEOUT", "5s");
+__publicField2(_CNSPostgresSchemaMigrator, "MAX_IDENTIFIER_LENGTH", 63);
+var CNSPostgresSchemaMigrator = _CNSPostgresSchemaMigrator;
+var _a2;
+var _CNSPostgresSchemaPgDatabase = (_a2 = class {
+  constructor(open) {
+    __publicField2(this, "open");
+    this.open = open;
+  }
+  static fromPool(pool) {
+    return new _a2(async () => {
+      const client = await pool.connect();
+      return {
+        connection: client,
+        release: /* @__PURE__ */ __name2((error) => client.release(error), "release")
+      };
+    });
+  }
+  async transaction(work) {
+    const { connection, release } = await this.open();
+    try {
+      await connection.query("BEGIN");
+      const result = await work(connection);
+      await connection.query("COMMIT");
+      release();
+      return result;
+    } catch (error) {
+      const rollback = await connection.query("ROLLBACK").then(() => void 0, (rollbackError) => rollbackError);
+      release(rollback instanceof Error ? rollback : void 0);
+      throw error;
+    }
+  }
+}, __name(_a2, "_CNSPostgresSchemaPgDatabase"), _a2);
+__name2(_CNSPostgresSchemaPgDatabase, "CNSPostgresSchemaPgDatabase");
+var CNSPostgresSchemaPgDatabase = _CNSPostgresSchemaPgDatabase;
+var _a3;
+var _CNSPostgresSchemaPartitionRotation = (_a3 = class {
+  constructor(options) {
+    __publicField2(this, "options");
+    __publicField2(this, "rotatedFor", /* @__PURE__ */ new Map());
+    this.options = options;
+    if (!(options.premakeDays >= 1) || !Number.isInteger(options.premakeDays)) {
+      throw new Error(`[partition rotation] premakeDays must be a positive integer, got ${options.premakeDays}`);
+    }
+  }
+  async rotate(database, table, now, dropBefore, beforeDrop) {
+    const today = Math.floor(now / _a3.DAY_MS);
+    const days = `${today}:${Math.floor(dropBefore / _a3.DAY_MS)}`;
+    if (this.rotatedFor.get(table) === days) return [];
+    const dropped = await this.underLock(database, table, async (connection) => {
+      const expired = (await this.readRangePartitions(connection, table)).filter((partition) => partition.to <= dropBefore);
+      if (beforeDrop) for (const partition of expired) await beforeDrop(connection, partition.name);
+      for (const partition of expired) await connection.query(`DROP TABLE ${partition.name}`);
+      return expired.map((partition) => partition.name);
+    });
+    await this.underLock(database, table, async (connection) => {
+      const partitions = await this.readRangePartitions(connection, table);
+      for (let ahead = 1; ahead <= this.options.premakeDays; ahead++) {
+        const from = (today + ahead) * _a3.DAY_MS;
+        const to = from + _a3.DAY_MS;
+        if (partitions.some((partition) => partition.from < to && from < partition.to)) continue;
+        const name = `${table}_p${new Date(from).toISOString().slice(0, 10).replace(/-/g, "")}`;
+        await connection.query(`CREATE TABLE ${name} (LIKE ${table} INCLUDING DEFAULTS INCLUDING CONSTRAINTS)`);
+        await connection.query(`ALTER TABLE ${table} ATTACH PARTITION ${name} FOR VALUES FROM (${from}) TO (${to})`);
+      }
+    });
+    this.rotatedFor.set(table, days);
+    return dropped;
+  }
+  underLock(database, table, work) {
+    return database.transaction(async (connection) => {
+      await connection.query("SELECT pg_advisory_xact_lock($1, hashtext($2))", [
+        _a3.LOCK_NAMESPACE,
+        table
+      ]);
+      await connection.query(`SET LOCAL lock_timeout = '${_a3.LOCK_TIMEOUT}'`);
+      return work(connection);
+    });
+  }
+  async readRangePartitions(connection, table) {
+    const rows = await connection.query(`SELECT child.oid::regclass::text AS name, pg_get_expr(child.relpartbound, child.oid) AS bound
+             FROM pg_inherits
+             JOIN pg_class child ON child.oid = pg_inherits.inhrelid
+             WHERE pg_inherits.inhparent = $1::regclass`, [
+      table
+    ]);
+    const partitions = [];
+    for (const row of rows.rows) {
+      const range = /^FOR VALUES FROM \('?(-?[\d.e+]+)'?\) TO \('?(-?[\d.e+]+)'?\)$/.exec(row.bound);
+      if (range) partitions.push({
+        name: row.name,
+        from: Number(range[1]),
+        to: Number(range[2])
+      });
+    }
+    return partitions;
+  }
+}, __name(_a3, "_CNSPostgresSchemaPartitionRotation"), _a3);
+__name2(_CNSPostgresSchemaPartitionRotation, "CNSPostgresSchemaPartitionRotation");
+__publicField2(_CNSPostgresSchemaPartitionRotation, "LOCK_NAMESPACE", 8);
+__publicField2(_CNSPostgresSchemaPartitionRotation, "LOCK_TIMEOUT", "5s");
+__publicField2(_CNSPostgresSchemaPartitionRotation, "DAY_MS", 24 * 60 * 60 * 1e3);
+
+// src/schema/CNSPgBossProgressSchema.ts
+var _CNSPgBossProgressSchema = class _CNSPgBossProgressSchema {
+  static assertTablePrefix(tablePrefix) {
+    return _CNSPgBossProgressSchema.migrator.assertTablePrefix(tablePrefix, _CNSPgBossProgressSchema.LONGEST_SUFFIX);
+  }
+  static table(tablePrefix = _CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX) {
+    return `${_CNSPgBossProgressSchema.assertTablePrefix(tablePrefix)}pgboss_progress`;
+  }
+  static migrationTable(tablePrefix = _CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX) {
+    return _CNSPgBossProgressSchema.migrator.migrationTable(_CNSPgBossProgressSchema.assertTablePrefix(tablePrefix));
+  }
+  static migrationSql(tablePrefix = _CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX, appliedSteps = [], options) {
+    return _CNSPgBossProgressSchema.migrator.migrationSql(_CNSPgBossProgressSchema.assertTablePrefix(tablePrefix), appliedSteps, options);
+  }
+  static async migrate(pool, tablePrefix = _CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX, options) {
+    await _CNSPgBossProgressSchema.migrator.migrate(CNSPostgresSchemaPgDatabase.fromPool(pool), _CNSPgBossProgressSchema.assertTablePrefix(tablePrefix), options);
+  }
+  static async verify(pool, tablePrefix = _CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX) {
+    await _CNSPgBossProgressSchema.migrator.verify(pool, _CNSPgBossProgressSchema.assertTablePrefix(tablePrefix));
+  }
+};
+__name(_CNSPgBossProgressSchema, "CNSPgBossProgressSchema");
+__publicField(_CNSPgBossProgressSchema, "DEFAULT_TABLE_PREFIX", "cns_");
+__publicField(_CNSPgBossProgressSchema, "LONGEST_SUFFIX", "pgboss_progress_pkey");
+__publicField(_CNSPgBossProgressSchema, "migrator", new CNSPostgresSchemaMigrator({
+  name: "pgboss_progress",
+  tables: /* @__PURE__ */ __name((tablePrefix) => [
+    _CNSPgBossProgressSchema.table(tablePrefix)
+  ], "tables"),
+  steps: [
+    {
+      step: 1,
+      kind: "expand",
+      sql: /* @__PURE__ */ __name((p) => `
+CREATE TABLE ${p}pgboss_progress (
+    job_id text PRIMARY KEY,
     progress jsonb NOT NULL,
-    updated_at timestamptz NOT NULL DEFAULT now()
+    updated_at bigint NOT NULL
 );
-CREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;
-}
-__name(pgBossProgressSchemaSql, "pgBossProgressSchemaSql");
-async function ensureSchema(db, table = DEFAULT_TABLE) {
-  await db.query(pgBossProgressSchemaSql(table));
-}
-__name(ensureSchema, "ensureSchema");
+`, "sql")
+    }
+  ]
+}));
+var CNSPgBossProgressSchema = _CNSPgBossProgressSchema;
 
 // src/cli.ts
 async function main() {
-  var _a;
+  var _a4;
   const cmd = process.argv[2];
   if (cmd !== "migrate") {
     console.error("usage: cnstra-pgboss-progress migrate");
@@ -42,13 +274,13 @@ async function main() {
     console.error("DATABASE_URL is required");
     process.exit(1);
   }
-  const table = (_a = process.env.CNS_PGBOSS_PROGRESS_TABLE) != null ? _a : DEFAULT_TABLE;
+  const tablePrefix = (_a4 = process.env.CNS_TABLE_PREFIX) != null ? _a4 : CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX;
   const pool = new import_pg.Pool({
     connectionString: url
   });
   try {
-    await ensureSchema(pool, table);
-    console.log(`\u2713 ensured progress table "${table}"`);
+    await CNSPgBossProgressSchema.migrate(pool, tablePrefix);
+    console.log(`\u2713 progress table is up to date "${CNSPgBossProgressSchema.table(tablePrefix)}"`);
   } finally {
     await pool.end();
   }

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli.ts","../src/migrate.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_PGBOSS_PROGRESS_TABLE=my_table  (optional; default cns_pgboss_progress)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_TABLE } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const table = process.env.CNS_PGBOSS_PROGRESS_TABLE ?? DEFAULT_TABLE;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, table);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured progress table \"${table}\"`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n","/**\n * Schema / migrations for the pg-boss progress table (`cns_pgboss_progress`).\n *\n * The package OWNS this schema so you can manage it explicitly (a migration step in\n * your own tooling) instead of relying on the repository's lazy auto-create. Run it\n * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself\n * with any pg client/pool.\n */\n\n/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */\nexport interface IPgQueryable {\n    query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\nexport const DEFAULT_TABLE = 'cns_pgboss_progress';\n\n/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafeTable(table: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {\n        throw new Error(\n            `[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`\n        );\n    }\n    return table;\n}\n\n/** The CREATE TABLE for the progress store. One upserted row per key (job id). */\nexport function pgBossProgressSchemaSql(table: string = DEFAULT_TABLE): string {\n    assertSafeTable(table);\n    // `updated_at` + its index back `deleteStale()`: a row is deleted when its job\n    // succeeds, but a job that fails PERMANENTLY (retries exhausted) leaves its row —\n    // pg-boss has no terminal-failure hook to key off. Pruning by staleness collects\n    // those, and the index keeps the sweep cheap.\n    return `CREATE TABLE IF NOT EXISTS ${table} (\n    key text PRIMARY KEY,\n    progress jsonb NOT NULL,\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;\n}\n\n/** Idempotently create the progress table. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    table: string = DEFAULT_TABLE\n): Promise<void> {\n    await db.query(pgBossProgressSchemaSql(table));\n}\n"],"mappings":";;;;;AAOA,gBAAqB;;;ACOd,IAAMA,gBAAgB;AAGtB,SAASC,gBAAgBC,OAAa;AACzC,MAAI,CAAC,2BAA2BC,KAAKD,KAAAA,GAAQ;AACzC,UAAM,IAAIE,MACN,iDAAiDC,KAAKC,UAAUJ,KAAAA,CAAAA,EAAQ;EAEhF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,wBAAwBL,QAAgBF,eAAa;AACjEC,kBAAgBC,KAAAA;AAKhB,SAAO,8BAA8BA,KAAAA;;;;;6BAKZA,KAAAA,mBAAwBA,KAAAA;AACrD;AAZgBK;AAehB,eAAsBC,aAClBC,IACAP,QAAgBF,eAAa;AAE7B,QAAMS,GAAGC,MAAMH,wBAAwBL,KAAAA,CAAAA;AAC3C;AALsBM;;;ADhCtB,eAAeG,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,uCAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMC,MAAML,QAAQM,IAAIC;AACxB,MAAI,CAACF,KAAK;AACNH,YAAQC,MAAM,0BAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMI,SAAQR,aAAQM,IAAIG,8BAAZT,YAAyCU;AACvD,QAAMC,OAAO,IAAIC,eAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,KAAAA;AAEzBN,YAAQa,IAAI,kCAA6BP,KAAAA,GAAQ;EACrD,UAAA;AACI,UAAMG,KAAKK,IAAG;EAClB;AACJ;AApBelB;AAsBf,KAAKA,KAAAA,EAAOmB,MAAMC,CAAAA,MAAAA;AACdhB,UAAQC,MAAMe,CAAAA;AACdlB,UAAQI,KAAK,CAAA;AACjB,CAAA;","names":["DEFAULT_TABLE","assertSafeTable","table","test","Error","JSON","stringify","pgBossProgressSchemaSql","ensureSchema","db","query","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","table","CNS_PGBOSS_PROGRESS_TABLE","DEFAULT_TABLE","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}
+{"version":3,"sources":["../src/cli.ts","../../postgres-schema/src/CNSPostgresSchemaMigrator.ts","../../postgres-schema/src/CNSPostgresSchemaPgDatabase.ts","../../postgres-schema/src/CNSPostgresSchemaPartitionRotation.ts","../src/schema/CNSPgBossProgressSchema.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_TABLE_PREFIX=my_  (optional; default cns_)\n */\nimport { Pool } from 'pg';\nimport { CNSPgBossProgressSchema } from './schema/CNSPgBossProgressSchema';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const tablePrefix = process.env.CNS_TABLE_PREFIX ?? CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await CNSPgBossProgressSchema.migrate(pool, tablePrefix);\n        // eslint-disable-next-line no-console\n        console.log(`✓ progress table is up to date \"${CNSPgBossProgressSchema.table(tablePrefix)}\"`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n","import type { ICNSPostgresSchemaConnection } from './interfaces/ICNSPostgresSchemaConnection';\nimport type { ICNSPostgresSchemaDatabase } from './interfaces/ICNSPostgresSchemaDatabase';\nimport type { ECNSPostgresSchemaStepKind } from './types/ECNSPostgresSchemaStepKind';\nimport type { TCNSPostgresSchemaMigrateOptions } from './types/TCNSPostgresSchemaMigrateOptions';\nimport type { TCNSPostgresSchemaMigratorOptions } from './types/TCNSPostgresSchemaMigratorOptions';\nimport type { TCNSPostgresSchemaStep } from './types/TCNSPostgresSchemaStep';\n\nexport class CNSPostgresSchemaMigrator {\n    static readonly LOCK_NAMESPACE = 6;\n    static readonly LOCK_TIMEOUT = '5s';\n    static readonly MAX_IDENTIFIER_LENGTH = 63;\n\n    private readonly steps: readonly TCNSPostgresSchemaStep[];\n\n    constructor(private readonly options: TCNSPostgresSchemaMigratorOptions) {\n        this.steps = [...options.steps].sort((left, right) => left.step - right.step);\n        this.steps.forEach((step, index) => {\n            if (step.step !== index + 1) throw new Error(`[${options.name}] schema steps must be numbered 1, 2, 3…; found ${step.step} at position ${index + 1}`);\n        });\n        if (this.steps[0]?.kind !== 'expand') throw new Error(`[${options.name}] schema step 1 must be an expand step`);\n    }\n\n    migrationTable(tablePrefix: string): string {\n        return `${tablePrefix}${this.options.name}_migration`;\n    }\n\n    async migrate(database: ICNSPostgresSchemaDatabase, tablePrefix: string, options: TCNSPostgresSchemaMigrateOptions = {}): Promise<void> {\n        await database.transaction(async connection => {\n            await connection.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [CNSPostgresSchemaMigrator.LOCK_NAMESPACE, tablePrefix + this.options.name]);\n            await connection.query(`SET LOCAL lock_timeout = '${CNSPostgresSchemaMigrator.LOCK_TIMEOUT}'`);\n            const applied = await this.readAppliedSteps(connection, tablePrefix);\n            if (applied === undefined) await this.assertNoUntrackedTables(connection, tablePrefix);\n            const pending = this.pendingSteps(applied ?? new Map(), applied === undefined || options.contract === true);\n            if (pending.length > 0) await connection.query(this.sqlFor(tablePrefix, pending, applied === undefined));\n        });\n    }\n\n    async verify(connection: ICNSPostgresSchemaConnection, tablePrefix: string): Promise<void> {\n        const applied = await this.readAppliedSteps(connection, tablePrefix);\n        if (applied === undefined) {\n            throw new Error(`[${this.options.name}] the schema is not installed under prefix \"${tablePrefix}\": run migrate()`);\n        }\n        const missing = this.steps.filter(step => step.kind === 'expand' && !applied.has(step.step)).map(step => step.step);\n        if (missing.length > 0) {\n            throw new Error(`[${this.options.name}] schema steps ${missing.join(', ')} are not applied under prefix \"${tablePrefix}\": run migrate()`);\n        }\n        const unknown = [...applied].filter(([step, kind]) => kind === 'contract' && step > this.steps.length).map(([step]) => step);\n        if (unknown.length > 0) {\n            throw new Error(`[${this.options.name}] the database has contract steps ${unknown.join(', ')} that this version does not know: upgrade the package`);\n        }\n    }\n\n    migrationSql(tablePrefix: string, appliedSteps: readonly number[] = [], options: TCNSPostgresSchemaMigrateOptions = {}): string {\n        const fresh = appliedSteps.length === 0;\n        const applied = new Map<number, ECNSPostgresSchemaStepKind>(appliedSteps.map(step => [step, 'expand']));\n        return this.sqlFor(tablePrefix, this.pendingSteps(applied, fresh || options.contract === true), fresh);\n    }\n\n    assertTablePrefix(tablePrefix: string, longestSuffix: string): string {\n        const longest = Math.max(longestSuffix.length, `${this.options.name}_migration`.length);\n        const limit = CNSPostgresSchemaMigrator.MAX_IDENTIFIER_LENGTH - longest;\n        if (!new RegExp(`^[A-Za-z_][A-Za-z0-9_]{0,${limit - 1}}$`).test(tablePrefix)) {\n            throw new Error(`[${this.options.name}] unsafe table prefix ${JSON.stringify(tablePrefix)}: letters, digits and _ only, at most ${limit} characters`);\n        }\n        return tablePrefix;\n    }\n\n    private pendingSteps(applied: ReadonlyMap<number, ECNSPostgresSchemaStepKind>, withContract: boolean): TCNSPostgresSchemaStep[] {\n        return this.steps.filter(step => !applied.has(step.step) && (step.kind === 'expand' || withContract));\n    }\n\n    private sqlFor(tablePrefix: string, steps: readonly TCNSPostgresSchemaStep[], createMigrationTable: boolean): string {\n        const table = this.migrationTable(tablePrefix);\n        const parts = createMigrationTable\n            ? [`CREATE TABLE ${table} (step integer PRIMARY KEY, kind text NOT NULL CHECK (kind IN ('expand', 'contract')));`]\n            : [];\n        for (const step of steps) {\n            parts.push(step.sql(tablePrefix), `INSERT INTO ${table} (step, kind) VALUES (${step.step}, '${step.kind}');`);\n        }\n        return parts.join('\\n');\n    }\n\n    private async readAppliedSteps(connection: ICNSPostgresSchemaConnection, tablePrefix: string): Promise<Map<number, ECNSPostgresSchemaStepKind> | undefined> {\n        const table = this.migrationTable(tablePrefix);\n        const exists = await connection.query<{ found: string | null }>('SELECT to_regclass($1)::text AS found', [table]);\n        if (exists.rows[0]?.found == null) return undefined;\n        const rows = await connection.query<{ step: number; kind: ECNSPostgresSchemaStepKind }>(`SELECT step, kind FROM ${table}`);\n        return new Map(rows.rows.map(row => [Number(row.step), row.kind]));\n    }\n\n    private async assertNoUntrackedTables(connection: ICNSPostgresSchemaConnection, tablePrefix: string): Promise<void> {\n        const tables = this.options.tables(tablePrefix);\n        const found = await connection.query<{ name: string }>(\n            'SELECT name FROM unnest($1::text[]) AS name WHERE to_regclass(name) IS NOT NULL',\n            [tables]\n        );\n        if (found.rows.length > 0) {\n            throw new Error(\n                `[${this.options.name}] tables ${found.rows.map(row => row.name).join(', ')} exist without ${this.migrationTable(tablePrefix)}: they were created by an earlier unversioned release; drop them or move the data before migrate()`\n            );\n        }\n    }\n}\n","import type { ICNSPostgresSchemaConnection } from './interfaces/ICNSPostgresSchemaConnection';\nimport type { ICNSPostgresSchemaDatabase } from './interfaces/ICNSPostgresSchemaDatabase';\nimport type { ICNSPostgresSchemaPgPool } from './interfaces/ICNSPostgresSchemaPgPool';\n\nexport class CNSPostgresSchemaPgDatabase implements ICNSPostgresSchemaDatabase {\n    private constructor(\n        private readonly open: () => Promise<{ connection: ICNSPostgresSchemaConnection; release: (error?: Error) => void }>\n    ) {}\n\n    static fromPool(pool: ICNSPostgresSchemaPgPool): CNSPostgresSchemaPgDatabase {\n        return new CNSPostgresSchemaPgDatabase(async () => {\n            const client = await pool.connect();\n            return { connection: client, release: error => client.release(error) };\n        });\n    }\n\n    async transaction<TResult>(work: (connection: ICNSPostgresSchemaConnection) => Promise<TResult>): Promise<TResult> {\n        const { connection, release } = await this.open();\n        try {\n            await connection.query('BEGIN');\n            const result = await work(connection);\n            await connection.query('COMMIT');\n            release();\n            return result;\n        } catch (error) {\n            const rollback = await connection.query('ROLLBACK').then(\n                () => undefined,\n                (rollbackError: unknown) => rollbackError\n            );\n            release(rollback instanceof Error ? rollback : undefined);\n            throw error;\n        }\n    }\n}\n","import type { ICNSPostgresSchemaConnection } from './interfaces/ICNSPostgresSchemaConnection';\nimport type { ICNSPostgresSchemaDatabase } from './interfaces/ICNSPostgresSchemaDatabase';\nimport type { TCNSPostgresSchemaPartitionRotationOptions } from './types/TCNSPostgresSchemaPartitionRotationOptions';\n\ntype TRangePartition = { readonly name: string; readonly from: number; readonly to: number };\n\nexport class CNSPostgresSchemaPartitionRotation {\n    static readonly LOCK_NAMESPACE = 8;\n    static readonly LOCK_TIMEOUT = '5s';\n    static readonly DAY_MS = 24 * 60 * 60 * 1000;\n\n    private readonly rotatedFor = new Map<string, string>();\n\n    constructor(private readonly options: TCNSPostgresSchemaPartitionRotationOptions) {\n        if (!(options.premakeDays >= 1) || !Number.isInteger(options.premakeDays)) {\n            throw new Error(`[partition rotation] premakeDays must be a positive integer, got ${options.premakeDays}`);\n        }\n    }\n\n    async rotate(\n        database: ICNSPostgresSchemaDatabase,\n        table: string,\n        now: number,\n        dropBefore: number,\n        beforeDrop?: (connection: ICNSPostgresSchemaConnection, partition: string) => Promise<void>\n    ): Promise<string[]> {\n        const today = Math.floor(now / CNSPostgresSchemaPartitionRotation.DAY_MS);\n        const days = `${today}:${Math.floor(dropBefore / CNSPostgresSchemaPartitionRotation.DAY_MS)}`;\n        if (this.rotatedFor.get(table) === days) return [];\n        const dropped = await this.underLock(database, table, async connection => {\n            const expired = (await this.readRangePartitions(connection, table)).filter(partition => partition.to <= dropBefore);\n            if (beforeDrop) for (const partition of expired) await beforeDrop(connection, partition.name);\n            for (const partition of expired) await connection.query(`DROP TABLE ${partition.name}`);\n            return expired.map(partition => partition.name);\n        });\n        await this.underLock(database, table, async connection => {\n            const partitions = await this.readRangePartitions(connection, table);\n            for (let ahead = 1; ahead <= this.options.premakeDays; ahead++) {\n                const from = (today + ahead) * CNSPostgresSchemaPartitionRotation.DAY_MS;\n                const to = from + CNSPostgresSchemaPartitionRotation.DAY_MS;\n                if (partitions.some(partition => partition.from < to && from < partition.to)) continue;\n                const name = `${table}_p${new Date(from).toISOString().slice(0, 10).replace(/-/g, '')}`;\n                await connection.query(`CREATE TABLE ${name} (LIKE ${table} INCLUDING DEFAULTS INCLUDING CONSTRAINTS)`);\n                await connection.query(`ALTER TABLE ${table} ATTACH PARTITION ${name} FOR VALUES FROM (${from}) TO (${to})`);\n            }\n        });\n        this.rotatedFor.set(table, days);\n        return dropped;\n    }\n\n    private underLock<TResult>(database: ICNSPostgresSchemaDatabase, table: string, work: (connection: ICNSPostgresSchemaConnection) => Promise<TResult>): Promise<TResult> {\n        return database.transaction(async connection => {\n            await connection.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [CNSPostgresSchemaPartitionRotation.LOCK_NAMESPACE, table]);\n            await connection.query(`SET LOCAL lock_timeout = '${CNSPostgresSchemaPartitionRotation.LOCK_TIMEOUT}'`);\n            return work(connection);\n        });\n    }\n\n    private async readRangePartitions(connection: ICNSPostgresSchemaConnection, table: string): Promise<TRangePartition[]> {\n        const rows = await connection.query<{ name: string; bound: string }>(\n            `SELECT child.oid::regclass::text AS name, pg_get_expr(child.relpartbound, child.oid) AS bound\n             FROM pg_inherits\n             JOIN pg_class child ON child.oid = pg_inherits.inhrelid\n             WHERE pg_inherits.inhparent = $1::regclass`,\n            [table]\n        );\n        const partitions: TRangePartition[] = [];\n        for (const row of rows.rows) {\n            const range = /^FOR VALUES FROM \\('?(-?[\\d.e+]+)'?\\) TO \\('?(-?[\\d.e+]+)'?\\)$/.exec(row.bound);\n            if (range) partitions.push({ name: row.name, from: Number(range[1]), to: Number(range[2]) });\n        }\n        return partitions;\n    }\n}\n","import { CNSPostgresSchemaMigrator, CNSPostgresSchemaPgDatabase } from '@cnstra/postgres-schema';\nimport type { ICNSPostgresSchemaConnection, ICNSPostgresSchemaPgPool } from '@cnstra/postgres-schema';\nimport type { Pool } from 'pg';\nimport type { TCNSPgBossProgressMigrateOptions } from '../types/TCNSPgBossProgressMigrateOptions';\n\nexport class CNSPgBossProgressSchema {\n    static readonly DEFAULT_TABLE_PREFIX = 'cns_';\n    private static readonly LONGEST_SUFFIX = 'pgboss_progress_pkey';\n\n    private static readonly migrator = new CNSPostgresSchemaMigrator({\n        name: 'pgboss_progress',\n        tables: tablePrefix => [CNSPgBossProgressSchema.table(tablePrefix)],\n        steps: [\n            {\n                step: 1,\n                kind: 'expand',\n                sql: p => `\nCREATE TABLE ${p}pgboss_progress (\n    job_id text PRIMARY KEY,\n    progress jsonb NOT NULL,\n    updated_at bigint NOT NULL\n);\n`,\n            },\n        ],\n    });\n\n    static assertTablePrefix(tablePrefix: string): string {\n        return CNSPgBossProgressSchema.migrator.assertTablePrefix(tablePrefix, CNSPgBossProgressSchema.LONGEST_SUFFIX);\n    }\n\n    static table(tablePrefix: string = CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX): string {\n        return `${CNSPgBossProgressSchema.assertTablePrefix(tablePrefix)}pgboss_progress`;\n    }\n\n    static migrationTable(tablePrefix: string = CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX): string {\n        return CNSPgBossProgressSchema.migrator.migrationTable(CNSPgBossProgressSchema.assertTablePrefix(tablePrefix));\n    }\n\n    static migrationSql(\n        tablePrefix: string = CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX,\n        appliedSteps: readonly number[] = [],\n        options?: TCNSPgBossProgressMigrateOptions\n    ): string {\n        return CNSPgBossProgressSchema.migrator.migrationSql(CNSPgBossProgressSchema.assertTablePrefix(tablePrefix), appliedSteps, options);\n    }\n\n    static async migrate(\n        pool: Pool,\n        tablePrefix: string = CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX,\n        options?: TCNSPgBossProgressMigrateOptions\n    ): Promise<void> {\n        await CNSPgBossProgressSchema.migrator.migrate(\n            CNSPostgresSchemaPgDatabase.fromPool(pool as unknown as ICNSPostgresSchemaPgPool),\n            CNSPgBossProgressSchema.assertTablePrefix(tablePrefix),\n            options\n        );\n    }\n\n    static async verify(pool: Pool, tablePrefix: string = CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX): Promise<void> {\n        await CNSPgBossProgressSchema.migrator.verify(\n            pool as unknown as ICNSPostgresSchemaConnection,\n            CNSPgBossProgressSchema.assertTablePrefix(tablePrefix)\n        );\n    }\n}\n"],"mappings":"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","names":["CNSPostgresSchemaMigrator","options","steps","_a","sort","left","right","step","forEach","index","Error","name","kind","migrationTable","tablePrefix","migrate","database","transaction","connection","query","LOCK_NAMESPACE","LOCK_TIMEOUT","applied","readAppliedSteps","undefined","assertNoUntrackedTables","pending","pendingSteps","Map","contract","length","sqlFor","verify","missing","filter","has","map","join","unknown","migrationSql","appliedSteps","fresh","assertTablePrefix","longestSuffix","longest","Math","max","limit","MAX_IDENTIFIER_LENGTH","RegExp","test","JSON","stringify","withContract","createMigrationTable","table","parts","push","sql","exists","rows","found","row","Number","tables","__publicField","CNSPostgresSchemaPgDatabase","open","fromPool","pool","client","connect","release","error","work","result","rollback","then","rollbackError","CNSPostgresSchemaPartitionRotation","rotatedFor","premakeDays","isInteger","rotate","now","dropBefore","beforeDrop","today","floor","DAY_MS","days","get","dropped","underLock","expired","readRangePartitions","partition","to","partitions","ahead","from","some","Date","toISOString","slice","replace","set","range","exec","bound","CNSPgBossProgressSchema","assertTablePrefix","tablePrefix","migrator","LONGEST_SUFFIX","table","DEFAULT_TABLE_PREFIX","migrationTable","migrationSql","appliedSteps","options","migrate","pool","CNSPostgresSchemaPgDatabase","fromPool","verify","CNSPostgresSchemaMigrator","name","tables","steps","step","kind","sql","p","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","tablePrefix","CNS_TABLE_PREFIX","CNSPgBossProgressSchema","DEFAULT_TABLE_PREFIX","pool","Pool","connectionString","migrate","log","table","end","catch","e"]}

package/dist/cli.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 import {
-  DEFAULT_TABLE,
-  ensureSchema
-} from "./chunk-XJFC72LU.mjs";
+  CNSPgBossProgressSchema
+} from "./chunk-OJUUT4VL.mjs";
 import {
   __name
 } from "./chunk-2JTKI4GS.mjs";
@@ -21,13 +20,13 @@ async function main() {
     console.error("DATABASE_URL is required");
     process.exit(1);
   }
-  const table = (_a = process.env.CNS_PGBOSS_PROGRESS_TABLE) != null ? _a : DEFAULT_TABLE;
+  const tablePrefix = (_a = process.env.CNS_TABLE_PREFIX) != null ? _a : CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX;
   const pool = new Pool({
     connectionString: url
   });
   try {
-    await ensureSchema(pool, table);
-    console.log(`\u2713 ensured progress table "${table}"`);
+    await CNSPgBossProgressSchema.migrate(pool, tablePrefix);
+    console.log(`\u2713 progress table is up to date "${CNSPgBossProgressSchema.table(tablePrefix)}"`);
   } finally {
     await pool.end();
   }

package/dist/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_PGBOSS_PROGRESS_TABLE=my_table  (optional; default cns_pgboss_progress)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_TABLE } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const table = process.env.CNS_PGBOSS_PROGRESS_TABLE ?? DEFAULT_TABLE;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, table);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured progress table \"${table}\"`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n"],"mappings":";;;;;;;;;;AAOA,SAASA,YAAY;AAGrB,eAAeC,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,uCAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMC,MAAML,QAAQM,IAAIC;AACxB,MAAI,CAACF,KAAK;AACNH,YAAQC,MAAM,0BAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMI,SAAQR,aAAQM,IAAIG,8BAAZT,YAAyCU;AACvD,QAAMC,OAAO,IAAIC,KAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,KAAAA;AAEzBN,YAAQa,IAAI,kCAA6BP,KAAAA,GAAQ;EACrD,UAAA;AACI,UAAMG,KAAKK,IAAG;EAClB;AACJ;AApBelB;AAsBf,KAAKA,KAAAA,EAAOmB,MAAMC,CAAAA,MAAAA;AACdhB,UAAQC,MAAMe,CAAAA;AACdlB,UAAQI,KAAK,CAAA;AACjB,CAAA;","names":["Pool","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","table","CNS_PGBOSS_PROGRESS_TABLE","DEFAULT_TABLE","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_TABLE_PREFIX=my_  (optional; default cns_)\n */\nimport { Pool } from 'pg';\nimport { CNSPgBossProgressSchema } from './schema/CNSPgBossProgressSchema';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const tablePrefix = process.env.CNS_TABLE_PREFIX ?? CNSPgBossProgressSchema.DEFAULT_TABLE_PREFIX;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await CNSPgBossProgressSchema.migrate(pool, tablePrefix);\n        // eslint-disable-next-line no-console\n        console.log(`✓ progress table is up to date \"${CNSPgBossProgressSchema.table(tablePrefix)}\"`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n"],"mappings":";;;;;;;;;AAOA,SAASA,YAAY;AAGrB,eAAeC,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,uCAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMC,MAAML,QAAQM,IAAIC;AACxB,MAAI,CAACF,KAAK;AACNH,YAAQC,MAAM,0BAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMI,eAAcR,aAAQM,IAAIG,qBAAZT,YAAgCU,wBAAwBC;AAC5E,QAAMC,OAAO,IAAIC,KAAK;IAAEC,kBAAkBT;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMK,wBAAwBK,QAAQH,MAAMJ,WAAAA;AAE5CN,YAAQc,IAAI,wCAAmCN,wBAAwBO,MAAMT,WAAAA,CAAAA,GAAe;EAChG,UAAA;AACI,UAAMI,KAAKM,IAAG;EAClB;AACJ;AApBepB;AAsBf,KAAKA,KAAAA,EAAOqB,MAAMC,CAAAA,MAAAA;AACdlB,UAAQC,MAAMiB,CAAAA;AACdpB,UAAQI,KAAK,CAAA;AACjB,CAAA;","names":["Pool","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","tablePrefix","CNS_TABLE_PREFIX","CNSPgBossProgressSchema","DEFAULT_TABLE_PREFIX","pool","Pool","connectionString","migrate","log","table","end","catch","e"]}

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
+import { CNSPersistOptionsRegistry, ICNSStimulationWriter, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
 import { ICNS } from '@cnstra/types';
 import { CNSCollateral } from '@cnstra/core';
-import { TCNSStimulationJobData } from '@cnstra/broker';
+import { TCNSStimulationJobOptions, TCNSStimulationJobData } from '@cnstra/broker';
 export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
+import { TCNSDevToolsActionMiddleware } from '@cnstra/persist-dto';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,22 +13,29 @@ export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
  * `work` handlers receive an array of jobs (batch). Pass your real `PgBoss`
  * instance — it satisfies this shape structurally.
  */
-interface IPgBossJob<TData = unknown> {
+interface ICNSPgBossJob<TData = unknown> {
     id: string;
     name: string;
     data: TData;
     /** 0-based retry count (pg-boss `Job.retryCount`); drives the attempt number. */
     retryCount?: number;
 }
-interface IPgBossLike {
+interface ICNSPgBossLike {
     send(name: string, data: object, options?: Record<string, unknown>): Promise<string | null>;
-    work<TData extends object>(name: string, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
-    work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
+    work<TData extends object>(name: string, handler: (jobs: ICNSPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
+    work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: ICNSPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
+    /**
+     * Mark jobs finished by id (pg-boss `complete(name, ids)`). The batch handler
+     * calls it for the jobs that succeeded alongside one that did not, so a single
+     * failure does not re-run its neighbours. Optional: a stand-in that never
+     * batches has nothing to settle.
+     */
+    complete?(name: string, ids: string[]): Promise<unknown>;
 }
 
-interface TCNSWorkerOptions {
+type TCNSWorkerOptions = {
     /** Your pg-boss instance (already started). */
-    boss: IPgBossLike;
+    boss: ICNSPgBossLike;
     /** The CNS the jobs run against. */
     cns: ICNS<any, any>;
     /** Name ↔ object registry used to reconstruct signals from job data. */
@@ -43,7 +51,7 @@ interface TCNSWorkerOptions {
      * that is `resume` below. One job = one stimulation (`stimulationId` = job id),
      * each pg-boss retry = a new attempt.
      */
-    observe?: ICNSStimulationRepository;
+    observe?: ICNSStimulationWriter;
     /**
      * Optional resumable **resume**. When set, the worker records the run's
      * outstanding frontier (by name) into `repository` as it advances, and a
@@ -63,7 +71,7 @@ interface TCNSWorkerOptions {
     };
     /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */
     workOptions?: Record<string, unknown>;
-}
+};
 /**
  * Register a pg-boss worker that turns each job into a CNStra stimulation.
  *
@@ -74,7 +82,7 @@ interface TCNSWorkerOptions {
  * own retry/backoff policy.
  */
 /** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
-interface TCNSPgBossWorkerHandle {
+type TCNSPgBossWorkerHandle = {
     /** The pg-boss `work()` registration id. */
     workId: string;
     /**
@@ -88,11 +96,11 @@ interface TCNSPgBossWorkerHandle {
     shutdown(opts?: {
         drainMs?: number;
     }): Promise<void>;
-}
+};
 declare function createCNSWorker(options: TCNSWorkerOptions): Promise<TCNSPgBossWorkerHandle>;
 
 /** Commonly used pg-boss send options (a superset is passed through). */
-interface TCNSSendOptions {
+type TCNSSendOptions = {
     retryLimit?: number;
     retryBackoff?: boolean;
     retryDelay?: number;
@@ -102,13 +110,34 @@ interface TCNSSendOptions {
     expireInSeconds?: number;
     priority?: number;
     [key: string]: unknown;
-}
+};
 /**
  * Build a queue job from a **registered** collateral. Throws if the collateral
  * is not in the registry, so a typo can't reach the queue.
  */
-declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral: CNSCollateral<unknown>, payload: unknown, extra?: Pick<TCNSStimulationJobData, 'maxNeuronHops'>): TCNSStimulationJobData;
+declare function cnsStimulationJob(registry: CNSPersistOptionsRegistry, collateral: CNSCollateral<unknown>, payload: unknown, stimulationJobOptions?: TCNSStimulationJobOptions): TCNSStimulationJobData;
 /** Send a stimulation job to a pg-boss queue. Returns the job id. */
-declare function enqueueStimulation(boss: IPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
+declare function enqueueCNSStimulation(boss: ICNSPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
+
+/** The two calls this needs beyond `send` — kept structural, like the rest. */
+interface ICNSPgBossActionsLike extends ICNSPgBossLike {
+    getJobById(name: string, id: string): Promise<{
+        id: string;
+        state?: string;
+    } | null | undefined>;
+    retry(name: string, id: string): Promise<unknown>;
+}
+/**
+ * Carries out DevTools actions against a pg-boss queue.
+ *
+ * Same shape as the BullMQ adapter and for the same reason: **retry is the
+ * broker's own retry**, keyed by the job id — which is our `stimulationId` — so
+ * the run keeps its identity, its history and its resume checkpoint. A clone or
+ * a replay is a new job under a new id.
+ *
+ * Ownership is decided by asking pg-boss whether it holds the job; anything else
+ * falls through to the next link in the chain.
+ */
+declare const createCNSPgBossActions: (boss: ICNSPgBossActionsLike, queue: string) => TCNSDevToolsActionMiddleware;
 
-export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type ICNSPgBossActionsLike, type ICNSPgBossJob, type ICNSPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, cnsStimulationJob, createCNSPgBossActions, createCNSWorker, enqueueCNSStimulation };