pg-boss 12.33.7 → 12.35.0

package/README.md

@@ -36,13 +36,12 @@ readme()
 
 pg-boss is a job queue built in Node.js on top of PostgreSQL in order to provide background processing and reliable asynchronous execution to Node.js applications.
 
-pg-boss relies on Postgres's SKIP LOCKED, a feature built specifically for message queues to resolve record locking challenges inherent with relational databases. This provides exactly-once delivery and the safety of guaranteed atomic commits to asynchronous job processing.
+pg-boss relies on Postgres's SKIP LOCKED, a feature built specifically for message queues to resolve record locking challenges inherent with relational databases. Concurrent workers claim jobs without blocking each other, and job processing gets the safety of guaranteed atomic commits.
 
 This will likely cater the most to teams already familiar with the simplicity of relational database semantics and operations (SQL, querying, and backups). It will be especially useful to those already relying on PostgreSQL that want to limit how many systems are required to monitor and support in their architecture.
 
 
 ## Summary
-* Exactly-once job delivery
 * Create jobs in an existing db transaction, including adapters for popular ORMs such as Drizzle, Knex, Kysely, Prisma
 * Backpressure-compatible polling workers, including support for LISTEN/NOTIFY low latency delivery
 * Job dependency workflow orchestration

package/dist/activity.d.ts

@@ -0,0 +1,15 @@
+import type { IDatabase } from './types.ts';
+/**
+ * The db a tracked one wraps, or the db itself if it is not tracked. What a transactional handler
+ * is given, since a handler's statements are not pg-boss's to wait for.
+ */
+export declare function untracked<D extends IDatabase>(db: D): D;
+/**
+ * Counts the statements pg-boss has in flight, so a TestClock can let them finish before it moves
+ * time on. PgBoss wraps its db with this only when its clock is attachable.
+ */
+export declare function trackActivity<T extends IDatabase>(db: T): {
+    db: T;
+    idle: () => Promise<boolean>;
+};
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAA;AAI9D;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAAG,EAAE,EAAE,CAAC,GAAG,CAAC,CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,EAAG,EAAE,EAAE,CAAC,GAAG;IAAE,EAAE,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAmFlG"}

package/dist/activity.js

@@ -0,0 +1,95 @@
+import { setImmediate } from 'node:timers/promises';
+const originals = new WeakMap();
+/**
+ * The db a tracked one wraps, or the db itself if it is not tracked. What a transactional handler
+ * is given, since a handler's statements are not pg-boss's to wait for.
+ */
+export function untracked(db) {
+    return originals.get(db) ?? db;
+}
+/**
+ * Counts the statements pg-boss has in flight, so a TestClock can let them finish before it moves
+ * time on. PgBoss wraps its db with this only when its clock is attachable.
+ */
+export function trackActivity(db) {
+    let inFlight = 0;
+    let started = 0;
+    let waiters = [];
+    const track = (fn) => async (...args) => {
+        inFlight++;
+        started++;
+        try {
+            return await fn(...args);
+        }
+        finally {
+            inFlight--;
+            if (inFlight === 0) {
+                const settled = waiters;
+                waiters = [];
+                for (const resolve of settled)
+                    resolve();
+            }
+        }
+    };
+    // Bound to the original, so an adapter's private fields still work through the proxy.
+    const wrap = (target, overrides) => new Proxy(target, {
+        get(t, key) {
+            if (Object.hasOwn(overrides, key))
+                return overrides[key];
+            const value = Reflect.get(t, key);
+            return typeof value === 'function' ? value.bind(t) : value;
+        },
+        // A caller that patches a counted method has usually captured the tracked one to call through.
+        // Writing the patch onto the original instead would make the tracked one call the patch forever.
+        set(t, key, value) {
+            if (Object.hasOwn(overrides, key)) {
+                overrides[key] = value;
+                return true;
+            }
+            return Reflect.set(t, key, value);
+        }
+    });
+    const wrapDb = (inner) => {
+        const overrides = {
+            executeSql: track((text, values) => inner.executeSql(text, values))
+        };
+        // Only when present: callers detect the capability with typeof.
+        if (typeof inner.beginTransaction === 'function') {
+            overrides.beginTransaction = track(async () => wrapTransaction(await inner.beginTransaction()));
+        }
+        // pg-boss's own pool runs multi-statement work through this, and it begins the transaction on
+        // the original, past the override above, so the whole call is counted as one.
+        const withTransaction = inner.withTransaction;
+        if (typeof withTransaction === 'function') {
+            overrides.withTransaction = track((fn) => withTransaction.call(inner, fn));
+        }
+        const tracked = wrap(inner, overrides);
+        originals.set(tracked, inner);
+        return tracked;
+    };
+    // The open transaction is not counted, only each call on it, or a transactional handler's whole
+    // run would read as busy.
+    const wrapTransaction = (tx) => wrap(tx, {
+        db: wrapDb(tx.db),
+        commit: track(() => tx.commit()),
+        rollback: track(() => tx.rollback())
+    });
+    async function idle() {
+        let waited = false;
+        for (;;) {
+            if (inFlight > 0) {
+                waited = true;
+                await new Promise(resolve => waiters.push(resolve));
+                continue;
+            }
+            // A caller whose statement just settled runs on in microtasks: it either arms a timer or
+            // starts another statement before this turn ends.
+            const seen = started;
+            await setImmediate();
+            if (inFlight === 0 && started === seen)
+                return waited;
+            waited = true;
+        }
+    }
+    return { db: wrapDb(db), idle };
+}

package/dist/attorney.d.ts

@@ -4,7 +4,7 @@ declare const POLICY: {
     MIN_POLLING_INTERVAL_MS: number;
     MAX_RETENTION_DAYS: number;
 };
-declare const COMPATIBILITY_FLAGS: readonly ["noSkipLocked", "noMultiMutationCte", "noTablePartitioning", "noDeferrableConstraints", "noAdvisoryLocks", "noCoveringIndexes", "noAddColumnBackfill", "noListenNotify", "noIndexProgressView", "noReindex", "noMonitorVacuum", "noTransactionalHeartbeat"];
+declare const COMPATIBILITY_FLAGS: readonly ["noSkipLocked", "noMultiMutationCte", "noTablePartitioning", "noDeferrableConstraints", "noAdvisoryLocks", "noCoveringIndexes", "noAddColumnBackfill", "noListenNotify", "noIndexProgressView", "noReindex", "noMonitorVacuum", "noTransactionalHeartbeat", "inlineTableIndexes"];
 declare function validateQueueArgs(config?: any): void;
 declare function pinZonelessDateTime(value: string): string;
 declare function checkSendArgs(args: any): types.Request;

package/dist/attorney.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,uQAaf,CAAA;AA2EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAiBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CA0B9F;AA8GD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}
+{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,6RAcf,CAAA;AA+EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAiBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CA0B9F;AAgHD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -21,7 +21,8 @@ const COMPATIBILITY_FLAGS = [
     'noIndexProgressView',
     'noReindex',
     'noMonitorVacuum',
-    'noTransactionalHeartbeat'
+    'noTransactionalHeartbeat',
+    'inlineTableIndexes'
 ];
 // The single source of truth for backend presets, mirrored by test/testHelper.ts.
 const BACKEND_PROFILES = {
@@ -53,7 +54,11 @@ const BACKEND_PROFILES = {
             // serializable lands at a timestamp above the handler transaction's. The completion pg-boss
             // runs inside that transaction then cannot write the same row and the batch dies with a
             // WriteTooOldError. YugabyteDB's snapshot isolation waits instead, so it does NOT set this.
-            noTransactionalHeartbeat: true
+            noTransactionalHeartbeat: true,
+            // Each CREATE INDEX or ADD PRIMARY KEY after a CREATE TABLE is its own schema-change job,
+            // run after commit even inside the create transaction: ~0.4-2s apiece, ~15s for a fresh
+            // schema. Declared inside CREATE TABLE they cost nothing extra.
+            inlineTableIndexes: true
         }
     },
     yugabytedb: {
@@ -441,6 +446,7 @@ function validateWarningConfig(config) {
     assert(!('warningSlowQuerySeconds' in config) || config.warningSlowQuerySeconds >= 1, 'configuration assert: warningSlowQuerySeconds must be at least 1');
     assert(!('warningRetentionDays' in config) || (Number.isInteger(config.warningRetentionDays) && config.warningRetentionDays >= 1), 'configuration assert: warningRetentionDays must be an integer >= 1');
     assert(!('warningRetentionDays' in config) || config.warningRetentionDays <= POLICY.MAX_RETENTION_DAYS, `configuration assert: warningRetentionDays cannot exceed ${POLICY.MAX_RETENTION_DAYS} days`);
+    config.warningRetentionDays = config.warningRetentionDays || POLICY.MAX_RETENTION_DAYS;
 }
 // Expands config.backend into the internal compatibility flags. The flags are derived
 // solely from the backend profile. They are not part of the public input, so a

package/dist/boss.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAaL,IAAI;IAmGJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAurBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}
+{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAIK,KAAK;IAiBL,IAAI;IAwGJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IA0tBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -123,11 +123,15 @@ class Boss extends EventEmitter {
     get maintaining() {
         return !!this.#maintaining;
     }
+    // Started with supervise disabled too, which only leaves the timer unarmed, so stop() still
+    // reaches a supervise() call on an instance that drives maintenance itself.
     async start() {
         if (this.#stopped) {
             this.#stopping = false;
-            this.#superviseTimer = new ClaimTimer(this.#config.clock, this.#config.superviseIntervalSeconds, () => this.#onSupervise());
-            this.#superviseTimer.start();
+            if (this.#config.supervise) {
+                this.#superviseTimer = new ClaimTimer(this.#config.clock, this.#config.superviseIntervalSeconds, () => this.#onSupervise());
+                this.#superviseTimer.start();
+            }
             this.#stopped = false;
         }
     }
@@ -167,15 +171,15 @@ class Boss extends EventEmitter {
         return result;
     }
     async #onSupervise() {
+        // Outside the try, so an attempt that skips does not clear the flag the running pass is
+        // holding and stop() waits on. See Timekeeper.onCron().
+        if (this.#stopped || this.#maintaining)
+            return;
+        this.#maintaining = true;
         try {
-            if (this.#stopped)
-                return;
-            if (this.#maintaining)
-                return;
             if (this.#config.__test__throw_maint) {
                 throw new Error(this.#config.__test__throw_maint);
             }
-            this.#maintaining = true;
             if (this.#config.__test__delay_maint_ms) {
                 await delay(this.#config.__test__delay_maint_ms);
             }
@@ -213,8 +217,22 @@ class Boss extends EventEmitter {
             : plans.dropOldQueueStatsPartitions(this.#config.schema, this.#config.queueStatRetentionDays);
         await this.#executeQuery(sql);
     }
+    // Waits for a pass in flight rather than skipping like #onSupervise, since the caller asked for
+    // this one. Holding #maintaining keeps it from overlapping the background pass and makes stop()
+    // wait for it, as Navigator.resolveNow() does.
     async supervise(value, options) {
-        await this.#supervisePass(value, options);
+        while (this.#maintaining) {
+            await delay(10);
+        }
+        if (this.#stopping)
+            return;
+        this.#maintaining = true;
+        try {
+            await this.#supervisePass(value, options);
+        }
+        finally {
+            this.#maintaining = false;
+        }
     }
     // onClaimsSettled fires once every monitor and maintain claim in the pass has been stamped, which
     // is where the background timer measures its next attempt from. Only #onSupervise passes one.
@@ -275,7 +293,7 @@ class Boss extends EventEmitter {
     async #monitor(table, names) {
         if (this.#stopping)
             return;
-        const command = plans.trySetQueueMonitorTime(this.#config.schema, names, this.#config.monitorIntervalSeconds);
+        const command = plans.trySetQueueMonitorTime(this.#config.schema, names, this.#config.monitorIntervalSeconds, plans.queueClaimSkipLocked(this.#config.backend, this.#config.noSkipLocked));
         const { rows } = await this.#executeQuery(command);
         if (this.#stopping)
             return;
@@ -288,7 +306,9 @@ class Boss extends EventEmitter {
             // statement, not of a queue, so every row carries the same value.
             const refreshStats = rows[0].refreshStats !== false;
             if (refreshStats) {
-                const cacheStatsSql = plans.cacheQueueStats(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
+                // A pass needs both timers, so passes are as far apart as the longer of the two.
+                const passSeconds = Math.max(this.#config.monitorIntervalSeconds, this.#config.superviseIntervalSeconds);
+                const cacheStatsSql = plans.cacheQueueStats(this.#config.schema, table, queues, this.#config.noAdvisoryLocks, this.#config.persistQueueStats, { resetMax: plans.deltaResetMax(passSeconds) });
                 // The pin this pass cost, taken from the server's own clock (see the pinSeconds column in
                 // cacheQueueStats) and not from a stopwatch around the call - that would count pool wait,
                 // network and event-loop lag, none of which hold the horizon. The client measurement stays as
@@ -303,9 +323,26 @@ class Boss extends EventEmitter {
                 if (rowsCacheStats.length) {
                     this.#statsElapsedSeconds += pinned || (Date.now() - statsStarted) / 1000;
                 }
-                if (this.#config.persistQueueStats) {
-                    const insertSql = plans.insertQueueStats(this.#config.schema, queues, this.#config.noAdvisoryLocks);
+                // Only the queues this pass wrote counts for. Another instance holding the stats lock means
+                // nothing was updated, and inserting anyway copied the previous pass's counters into a
+                // second snapshot, which the history then counted twice.
+                if (this.#config.persistQueueStats && rowsCacheStats.length) {
+                    const written = rowsCacheStats.map(row => row.name);
+                    const insertSql = plans.insertQueueStats(this.#config.schema, written, this.#config.noAdvisoryLocks);
                     await this.#executeQuery(insertSql);
+                    // Jobs committed after the pass that counted their window: the aggregate saw more of them
+                    // across the recorded windows than the snapshots hold. Recount those queues' recent windows
+                    // and raise the snapshots that fell short. A second scan, so it is paid only when the
+                    // check fires, and it counts toward the pin like the aggregate does.
+                    const late = rowsCacheStats.filter(row => row.trueUp).map(row => row.name);
+                    if (late.length && !this.#stopping) {
+                        const trueUpStarted = Date.now();
+                        const trueUpSql = plans.trueUpQueueStats(this.#config.schema, table, late, this.#config.noAdvisoryLocks);
+                        const { rows: [trued] } = await this.#executeQuery(trueUpSql);
+                        if (trued) {
+                            this.#statsElapsedSeconds += Number(trued.pinSeconds) || (Date.now() - trueUpStarted) / 1000;
+                        }
+                    }
                 }
                 if (this.#stopping)
                     return;
@@ -345,7 +382,7 @@ class Boss extends EventEmitter {
     async #maintain(table, names) {
         if (this.#stopping)
             return;
-        const command = plans.trySetQueueDeletionTime(this.#config.schema, names, this.#config.maintenanceIntervalSeconds);
+        const command = plans.trySetQueueDeletionTime(this.#config.schema, names, this.#config.maintenanceIntervalSeconds, plans.queueClaimSkipLocked(this.#config.backend, this.#config.noSkipLocked));
         const { rows } = await this.#executeQuery(command);
         if (this.#stopping)
             return;

package/dist/claimTimer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claimTimer.d.ts","sourceRoot":"","sources":["../src/claimTimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;;gBASR,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMnE,KAAK,IAAK,IAAI;IAOd,IAAI,IAAK,IAAI;IAKb;;;;;;;;;;OAUG;IACH,MAAM,CAAE,EAAE,GAAE,MAAiB,GAAG,IAAI;CAwCrC"}
+{"version":3,"file":"claimTimer.d.ts","sourceRoot":"","sources":["../src/claimTimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;;gBAUR,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMnE,KAAK,IAAK,IAAI;IAOd,IAAI,IAAK,IAAI;IAKb;;;;;;;;;;OAUG;IACH,MAAM,CAAE,EAAE,GAAE,MAAiB,GAAG,IAAI;CA0DrC"}

package/dist/claimTimer.js

@@ -34,6 +34,7 @@ export class ClaimTimer {
     #ms;
     #fn;
     #handle;
+    #due = 0;
     #stopped = true;
     #anchored = false;
     constructor(clock, seconds, fn) {
@@ -72,7 +73,24 @@ export class ClaimTimer {
         this.#disarm();
         if (this.#stopped)
             return;
-        this.#handle = this.#clock.setTimeout(() => { this.#run(); }, ms);
+        this.#due = this.#clock.now() + ms;
+        this.#wait(ms);
+    }
+    // Node's timers run on the monotonic clock and can fire a millisecond short of the wall clock the
+    // claim is measured on. Against a server whose now() has millisecond resolution and sits in the
+    // same process (PGlite), a reply inside the millisecond it was stamped leaves no round trip to
+    // absorb that, and the claim is refused. Waiting out the remainder keeps the attempt from landing
+    // before the wall clock says the wait is over.
+    #wait(ms) {
+        this.#handle = this.#clock.setTimeout(() => {
+            const remaining = this.#due - this.#clock.now();
+            if (remaining > 0) {
+                this.#wait(remaining);
+            }
+            else {
+                this.#run();
+            }
+        }, ms);
     }
     #disarm() {
         if (this.#handle !== undefined) {

package/dist/cli.js

@@ -4,7 +4,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import Db from "./db.js";
 import * as plans from "./plans.js";
-import Contractor from "./contractor.js";
+import Contractor, { installConfig } from "./contractor.js";
 import * as migrationStore from "./migrationStore.js";
 import * as attorney from "./attorney.js";
 import packageJson from '../package.json' with { type: 'json' };
@@ -267,7 +267,7 @@ async function cmdCreate(args) {
             return;
         }
         console.log(`Creating pg-boss schema "${schema}"...`);
-        const sql = plans.create(schema, schemaVersion, { ...config, createSchema: true });
+        const sql = plans.create(schema, schemaVersion, { ...await installConfig(db, config), createSchema: true });
         await db.executeSql(sql);
         console.log(`Successfully created pg-boss schema "${schema}" at version ${schemaVersion}`);
     }
@@ -315,7 +315,7 @@ async function cmdMigrate(args) {
         const version = await getSchemaVersion(db, schema);
         if (version === null) {
             console.log(`pg-boss is not installed. Creating schema "${schema}"...`);
-            const sql = plans.create(schema, schemaVersion, { ...config, createSchema: true });
+            const sql = plans.create(schema, schemaVersion, { ...await installConfig(db, config), createSchema: true });
             await db.executeSql(sql);
             console.log(`Successfully created pg-boss schema "${schema}" at version ${schemaVersion}`);
             return;

package/dist/clock.d.ts

@@ -4,6 +4,7 @@ export declare function isAttachable(clock: Clock): clock is AttachableClock;
 interface Target {
     db: IDatabase;
     schema: string;
+    idle?: () => Promise<boolean>;
 }
 /**
  * A clock a test drives by hand. Time only moves through setTime() and tick(); timers only fire
@@ -18,11 +19,19 @@ export declare class TestClock implements AttachableClock {
     setInterval(fn: () => void, ms: number): ClockTimer;
     clearTimeout(handle: ClockTimer): void;
     clearInterval(handle: ClockTimer): void;
-    /** Jumps to a time, forwards or backwards, firing nothing. */
+    /**
+     * Jumps to a time, forwards or backwards, firing nothing. Settles first, so work already in
+     * flight finishes on the time it started under. Postgres sees a forward jump as elapsed time, so
+     * JS timers do too: each one the jump passed fires once on the next tick, as if the process had
+     * slept, and an interval then keeps its period from there instead of replaying every period it
+     * skipped. A backward jump leaves timers alone, so JS deadlines still agree with the database's.
+     */
     setTime(t: Date | number | string): Promise<void>;
     /**
-     * Advances by ms, firing each due timer in order at its own due time. Does not wait for I/O the
-     * callbacks start; observe effects with spies or by querying.
+     * Advances by ms, firing each due timer in order at its own due time. After each timer, and
+     * before and after the whole advance, waits until pg-boss has no statement in flight, so a poll
+     * the tick fired finishes, and anything it re-arms before the target fires in this same tick.
+     * Does not wait for job handlers; observe their effects with spies or by querying.
      */
     tick(ms: number): Promise<void>;
     attach(target: Target): Promise<AsyncDisposable>;

package/dist/clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/E,eAAO,MAAM,WAAW,EAAE,KAMzB,CAAA;AAED,wBAAgB,YAAY,CAAE,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAEpE;AASD,UAAU,MAAM;IACd,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAUD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;;gBAWlC,KAAK,GAAE,IAAI,GAAG,MAAM,GAAG,MAAmB;IAIvD,GAAG,IAAK,MAAM;IAId,UAAU,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAInD,WAAW,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAIpD,YAAY,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKvC,aAAa,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC,8DAA8D;IACxD,OAAO,CAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD;;;OAGG;IACG,IAAI,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsChC,MAAM,CAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CA4ExD"}
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/E,eAAO,MAAM,WAAW,EAAE,KAMzB,CAAA;AAED,wBAAgB,YAAY,CAAE,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAEpE;AASD,UAAU,MAAM;IACd,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9B;AAUD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;;gBAalC,KAAK,GAAE,IAAI,GAAG,MAAM,GAAG,MAAmB;IAIvD,GAAG,IAAK,MAAM;IAId,UAAU,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAInD,WAAW,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAIpD,YAAY,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKvC,aAAa,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC;;;;;;OAMG;IACG,OAAO,CAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxD;;;;;OAKG;IACG,IAAI,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDhC,MAAM,CAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAsFxD"}

package/dist/clock.js

@@ -26,7 +26,9 @@ export class TestClock {
     #now;
     #timers = [];
     #seq = 0;
-    #ticking = false;
+    // tick() and setTime() both await I/O before they finish, so either one started meanwhile would
+    // interleave with the one running.
+    #busy = null;
     // Every (db, schema) this clock currently pushes time to. More than one because a multi-instance
     // test shares one clock across several PgBoss instances, each of which attaches on start(). The
     // schema is shared, so the last handle to be disposed is the one that restores job_now() and
@@ -52,44 +54,77 @@ export class TestClock {
     clearInterval(handle) {
         this.clearTimeout(handle);
     }
-    /** Jumps to a time, forwards or backwards, firing nothing. */
+    /**
+     * Jumps to a time, forwards or backwards, firing nothing. Settles first, so work already in
+     * flight finishes on the time it started under. Postgres sees a forward jump as elapsed time, so
+     * JS timers do too: each one the jump passed fires once on the next tick, as if the process had
+     * slept, and an interval then keeps its period from there instead of replaying every period it
+     * skipped. A backward jump leaves timers alone, so JS deadlines still agree with the database's.
+     */
     async setTime(t) {
-        this.#now = toMillis(t);
-        await this.#push();
+        this.#enter('setTime');
+        try {
+            const next = toMillis(t);
+            await this.#settle();
+            // #timers is sorted by due time, so the overdue timers are a prefix and stay sorted once moved.
+            for (const timer of this.#timers) {
+                if (timer.due >= next)
+                    break;
+                timer.due = next;
+            }
+            this.#now = next;
+            await this.#push();
+        }
+        finally {
+            this.#busy = null;
+        }
     }
     /**
-     * Advances by ms, firing each due timer in order at its own due time. Does not wait for I/O the
-     * callbacks start; observe effects with spies or by querying.
+     * Advances by ms, firing each due timer in order at its own due time. After each timer, and
+     * before and after the whole advance, waits until pg-boss has no statement in flight, so a poll
+     * the tick fired finishes, and anything it re-arms before the target fires in this same tick.
+     * Does not wait for job handlers; observe their effects with spies or by querying.
      */
     async tick(ms) {
-        if (this.#ticking) {
-            throw new Error('TestClock: tick() called while a tick is in progress');
-        }
-        this.#ticking = true;
+        this.#enter('tick');
         try {
+            await this.#settle();
             const target = this.#now + ms;
-            while (this.#timers.length && this.#timers[0].due <= target) {
-                const timer = this.#timers.shift();
-                if (timer.due > this.#now) {
-                    this.#now = timer.due;
+            for (;;) {
+                const timer = this.#timers[0];
+                if (timer && timer.due <= target) {
+                    this.#timers.shift();
+                    if (timer.due > this.#now) {
+                        this.#now = timer.due;
+                        await this.#push();
+                    }
+                    // Reinsert the same object so the handle handed out by setInterval still clears it.
+                    if (timer.interval !== null) {
+                        timer.due += timer.interval;
+                        timer.seq = this.#seq++;
+                        this.#insert(timer);
+                    }
+                    timer.fn();
+                }
+                else if (this.#now < target) {
+                    this.#now = target;
                     await this.#push();
                 }
-                // Reinsert the same object so the handle handed out by setInterval still clears it.
-                if (timer.interval !== null) {
-                    timer.due += timer.interval;
-                    timer.seq = this.#seq++;
-                    this.#insert(timer);
+                else {
+                    break;
                 }
-                timer.fn();
-                await setImmediate();
+                await this.#settle();
             }
-            this.#now = target;
-            await this.#push();
-            await setImmediate();
         }
         finally {
-            this.#ticking = false;
+            this.#busy = null;
+        }
+    }
+    #enter(method) {
+        if (this.#busy) {
+            throw new Error(`TestClock: ${method}() called while a ${this.#busy} is in progress`);
         }
+        this.#busy = method;
     }
     async attach(target) {
         const { db, schema } = target;
@@ -111,7 +146,7 @@ export class TestClock {
         // The session opt-in is not issued here. attach() runs after the contractor has already opened
         // connections and migrated, so a SET on this one session would miss every other one. PgBoss
         // declares it through db.setSessionStatements() before anything opens; see #doStart.
-        const entry = { db, schema };
+        const entry = { db, schema, idle: target.idle };
         this.#targets.push(entry);
         let disposed = false;
         return {
@@ -153,4 +188,14 @@ export class TestClock {
         const seconds = this.#now / 1000;
         await Promise.all(this.#targets.map(({ db, schema }) => db.executeSql(`UPDATE ${plans.clockTable(schema)} SET now = to_timestamp($1)`, [seconds])));
     }
+    // Repeats until every target is quiet in the same pass: one instance going quiet can wake
+    // another, for example through a NOTIFY, after that one's idle() has already returned.
+    async #settle() {
+        for (;;) {
+            await setImmediate();
+            const waited = await Promise.all(this.#targets.map(t => t.idle ? t.idle() : false));
+            if (!waited.includes(true))
+                return;
+        }
+    }
 }

package/dist/contractor.d.ts

@@ -1,4 +1,7 @@
 import type * as types from './types.ts';
+export declare function installConfig<T extends {
+    inlineTableIndexes?: boolean;
+}>(db: types.IDatabase, config: T): Promise<T>;
 declare class Contractor {
     static constructionPlans(schema?: string, options?: types.ConstructionPlanOptions): string;
     static migrationPlans(schema?: string, version?: number, options?: types.MigrationPlanOptions): string;

package/dist/contractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO,GAAE,KAAK,CAAC,uBAA4B;IAapG,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE,KAAK,CAAC,oBAAyB;IAS3H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB,EAAE,OAAO,GAAE,KAAK,CAAC,WAAgB;IAM7G,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAgBpE,aAAa;IAKb,WAAW;IAKX,KAAK;YAsBG,yBAAyB;IAkCjC,WAAW,CAAE,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAsHzF,mBAAmB,IAAK,OAAO,CAAC,OAAO,CAAC;IASxC,oBAAoB,IAAK,OAAO,CAAC,IAAI,CAAC;IAItC,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAsBxC,wBAAsB,aAAa,CAAC,CAAC,SAAS;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,EAAG,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO3H;AAED,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO,GAAE,KAAK,CAAC,uBAA4B;IAcpG,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE,KAAK,CAAC,oBAAyB;IAS3H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB,EAAE,OAAO,GAAE,KAAK,CAAC,WAAgB;IAM7G,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAgBpE,aAAa;IAKb,WAAW;IAKX,KAAK;YAsBG,yBAAyB;IAkCjC,WAAW,CAAE,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAwHzF,mBAAmB,IAAK,OAAO,CAAC,OAAO,CAAC;IASxC,oBAAoB,IAAK,OAAO,CAAC,IAAI,CAAC;IAItC,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}

package/dist/contractor.js

@@ -17,6 +17,17 @@ function planConfig(schema, backend) {
     // value, so `{ backend: undefined }` is a named backend that is not one of the profiles.
     return getConfig(backend ? { schema, backend } : { schema });
 }
+// Whether a live install may use inlineTableIndexes. The flag comes from the backend profile, but
+// the syntax it emits is CockroachDB's own, and the cockroachdb profile is otherwise safe to run on
+// plain Postgres (its other flags only remove features). So a live install asks the server what it
+// is before inlining. Printed plans have no server to ask and follow the named backend instead.
+export async function installConfig(db, config) {
+    if (!config.inlineTableIndexes)
+        return config;
+    const { rows } = await db.executeSql(plans.SERVER_VERSION);
+    const cockroach = /cockroachdb/i.test(String(rows[0]?.version ?? ''));
+    return cockroach ? config : { ...config, inlineTableIndexes: false };
+}
 class Contractor {
     static constructionPlans(schema = plans.DEFAULT_SCHEMA, options = {}) {
         const { createSchema = true, backend } = options;
@@ -26,7 +37,8 @@ class Contractor {
             noTablePartitioning: config.noTablePartitioning,
             noDeferrableConstraints: config.noDeferrableConstraints,
             noAdvisoryLocks: config.noAdvisoryLocks,
-            noCoveringIndexes: config.noCoveringIndexes
+            noCoveringIndexes: config.noCoveringIndexes,
+            inlineTableIndexes: config.inlineTableIndexes
         });
     }
     static migrationPlans(schema = plans.DEFAULT_SCHEMA, version = schemaVersion - 1, options = {}) {
@@ -190,10 +202,12 @@ class Contractor {
             liveConstraints = [];
         }
         const building = new Set(bamCommands.map(plans.bamCommandIndexName).filter((n) => n !== null));
-        // CockroachDB renders column types (INT8 vs integer), default expressions, and constraint
-        // definitions differently from standard Postgres, so the canonical-form checks would false-positive
-        // there. Restrict type/default/constraint drift to Postgres-typed backends; the presence checks
-        // (tables, indexes, column names, functions, enum) still run everywhere.
+        // CockroachDB renders column types (INT8 vs integer), default expressions, constraint definitions,
+        // index definitions (`name ASC`, `''::STRING`, `!=`, `IN (...)`) and function bodies (database-
+        // qualified names, `::INT8`, `now():::TIMESTAMPTZ`) differently from standard Postgres, so the
+        // canonical-form checks would flag every one of them there. Restrict definition drift to
+        // Postgres-typed backends; the presence checks (tables, indexes and their validity, column
+        // names, functions, enum) still run everywhere.
         const canonicalPg = this.config.backend !== 'cockroachdb';
         const expectedColumns = plans.expectedManagedColumns(schema, partitioned, partitions)
             .map(c => canonicalPg ? c : { table: c.table, columns: c.columns });
@@ -204,9 +218,9 @@ class Contractor {
         const expectedIndexes = plans.expectedManagedIndexes(schema, partitioned, partitions)
             .map(i => this.config.noCoveringIndexes ? { ...i, include: '' } : i);
         return drifter.computeSchemaDrift({
-            indexes: { expected: expectedIndexes, live, building },
+            indexes: { expected: expectedIndexes, live, building, presenceOnly: !canonicalPg },
             tables: { expected: plans.expectedManagedTables(schema, partitioned, partitions), live: liveTables ?? [...new Set(liveColumns.map(c => c.table))] },
-            functions: functionsSupported ? { expected: plans.expectedManagedFunctions(schema, partitioned, options), live: liveFunctions } : undefined,
+            functions: functionsSupported ? { expected: plans.expectedManagedFunctions(schema, partitioned, options), live: liveFunctions, presenceOnly: !canonicalPg } : undefined,
             columns: { expected: expectedColumns, live: liveColumns },
             constraints: canonicalPg ? { expected: plans.expectedManagedConstraints(schema, partitioned), live: liveConstraints } : undefined,
             enum: { name: 'job_state', expected: plans.EXPECTED_JOB_STATES, actual: enumLabels }
@@ -246,7 +260,7 @@ class Contractor {
     }
     async create() {
         try {
-            const commands = plans.create(this.config.schema, schemaVersion, this.config);
+            const commands = plans.create(this.config.schema, schemaVersion, await installConfig(this.db, this.config));
             await this.db.executeSql(commands);
         }
         catch (err) {