pg-boss 12.36.0 → 12.37.1

package/dist/plans.js

@@ -3,7 +3,11 @@ import { indexKeysRaw, indexIncludeRaw, indexPredicateRaw, displayIndexDefinitio
 import schemaManifest from './schema.json' with { type: 'json' };
 import { normalizeSchemaName, resolveSchemaName } from "./tools.js";
 export const PG_ERROR = {
-    divisionByZero: '22012'
+    divisionByZero: '22012',
+    lockNotAvailable: '55P03',
+    foreignKeyViolation: '23503',
+    undefinedTable: '42P01',
+    checkViolation: '23514'
 };
 export const DEFAULT_SCHEMA = 'pgboss';
 export const MIGRATE_RACE_MESSAGE = 'division by zero';
@@ -854,7 +858,8 @@ function createTableJob(schema, noPartitioning = false) {
       source_retry_count int,
       source_output jsonb,
       source_root_id uuid,
-      trace_context jsonb
+      trace_context jsonb,
+      upsert_by_key bool
     ) ${partitionClause}
   `;
 }
@@ -909,6 +914,7 @@ function createTableJobCommon(schema) {
     SELECT ${schema}.job_table_run($cmd$${createIndexJobGroupConcurrency(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobBlocking(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobSourceRoot(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobUpsert(schema)}$cmd$, '${COMMON_JOB_TABLE}');
 
     ALTER TABLE ${schema}.job ATTACH PARTITION ${schema}.${COMMON_JOB_TABLE} DEFAULT;
   `;
@@ -930,6 +936,7 @@ function createTableJobIndexes(schema, noDeferrableConstraints = false, noCoveri
     ${createIndexJobGroupConcurrency(schema)};
     ${createIndexJobBlocking(schema)};
     ${createIndexJobSourceRoot(schema)};
+    ${createIndexJobUpsert(schema)};
   `;
 }
 function createQueueFunction(schema, noPartitioning = false) {
@@ -1053,6 +1060,7 @@ function createQueueFunction(schema, noPartitioning = false) {
       EXECUTE ${schema}.job_table_format($cmd$${createIndexJobGroupConcurrency(schema)}$cmd$, tablename);
       EXECUTE ${schema}.job_table_format($cmd$${createIndexJobBlocking(schema)}$cmd$, tablename);
       EXECUTE ${schema}.job_table_format($cmd$${createIndexJobSourceRoot(schema)}$cmd$, tablename);
+      EXECUTE ${schema}.job_table_format($cmd$${createIndexJobUpsert(schema)}$cmd$, tablename);
 
       IF options->>'policy' = 'short' THEN
         EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyShort(schema)}$cmd$, tablename);
@@ -1135,8 +1143,32 @@ export function notifyChannelSql(schema) {
 export function notifyQueue(schema, name) {
     return `SELECT pg_notify(${notifyChannelSql(schema)}, '${name}')`;
 }
-export function deleteQueue(schema, name, noAdvisoryLocks) {
-    const sql = `SELECT ${schema}.delete_queue('${name}')`;
+// Dropping a queue's own table (partition: true) needs ACCESS EXCLUSIVE on it, on job and on job_common,
+// and an insert into job_common or a query through job takes those in other orders. So the locks are
+// taken first, all with NOWAIT: the transaction never waits holding one, so it can never be part of a
+// deadlock, and the caller tries again when one is busy. The table is read in the same transaction, so
+// a stale cache cannot name the wrong one, and a queue already gone is left alone.
+export function deleteQueue(schema, name, noAdvisoryLocks, partitioned = false) {
+    const sql = partitioned
+        ? `
+      DO $$
+      DECLARE
+        v_table text;
+        v_partition bool;
+      BEGIN
+        SELECT table_name, partition FROM ${schema}.queue WHERE name = '${name}' INTO v_table, v_partition;
+        IF NOT FOUND THEN
+          RETURN;
+        END IF;
+
+        IF v_partition AND to_regclass(format('${schema}.%I', v_table)) IS NOT NULL THEN
+          EXECUTE format('LOCK TABLE ${schema}.${COMMON_JOB_TABLE}, ${schema}.%I, ${schema}.${BASE_JOB_TABLE} IN ACCESS EXCLUSIVE MODE NOWAIT', v_table);
+        END IF;
+
+        PERFORM ${schema}.delete_queue('${name}');
+      END $$
+    `
+        : `SELECT ${schema}.delete_queue('${name}')`;
     return locked(schema, sql, 'delete-queue', noAdvisoryLocks);
 }
 function createPrimaryKeyJob(schema) {
@@ -1230,6 +1262,14 @@ function createIndexJobBlocking(schema) {
 function createIndexJobSourceRoot(schema) {
     return `CREATE INDEX job_i12 ON ${schema}.job (source_root_id) WHERE source_root_id IS NOT NULL`;
 }
+// At most one waiting job per key among the jobs upsert() inserted by singletonKey, which is what makes
+// concurrent upserts of one key agree: the second insert waits on the first's index entry, conflicts,
+// and edits that job instead. upsert_by_key is set only on those inserts, so send() keeps its own policy's
+// rules and a queue that never upserts carries the index empty. Only created, not retry, so a failing
+// job never collides with a newer upsert on its way back to retry.
+function createIndexJobUpsert(schema) {
+    return `CREATE UNIQUE INDEX job_i13 ON ${schema}.job (name, singleton_key) WHERE state = '${JOB_STATES.created}' AND upsert_by_key`;
+}
 // The interval claim for a monitor pass. It stamps monitor_claim_on, never monitor_on, which only
 // the stats aggregate writes, so a pass that skips the aggregate leaves capturedOn aging.
 //
@@ -2093,8 +2133,7 @@ export function insertVersion(schema, version) {
     return `INSERT INTO ${schema}.version(version) VALUES ('${version}')`;
 }
 function buildFetchParams(options) {
-    const { ignoreSingletons, ignoreGroups, groupConcurrency, minPriority, maxPriority } = options;
-    const hasIgnoreSingletons = ignoreSingletons != null && ignoreSingletons.length > 0;
+    const { ignoreGroups, groupConcurrency, minPriority, maxPriority } = options;
     const hasIgnoreGroups = ignoreGroups != null && ignoreGroups.length > 0;
     const hasGroupConcurrency = groupConcurrency != null;
     const hasMinPriority = minPriority != null;
@@ -2105,22 +2144,11 @@ function buildFetchParams(options) {
     const hasTiers = groupConcurrencyConfig?.tiers && Object.keys(groupConcurrencyConfig.tiers).length > 0;
     const values = [];
     let paramIndex = 0;
-    let ignoreSingletonsParam = '';
     let ignoreGroupsParam = '';
     let defaultGroupLimitParam = '';
     let tiersParam = '';
     let minPriorityParam = '';
     let maxPriorityParam = '';
-    if (hasIgnoreSingletons) {
-        paramIndex++;
-        ignoreSingletonsParam = `$${paramIndex}::text[]`;
-        // job_i2/job_i3 key singleton/stately jobs on the empty key (COALESCE(singleton_key, ''))
-        // as one slot, so a keyless active job must block keyless pending jobs the same way a keyed
-        // one blocks its key. Map null -> '' here so the WHERE clause's COALESCE comparison (below)
-        // never has to compare against a literal NULL array element, which would make `<> ALL(...)`
-        // evaluate to NULL (excluding every row) instead of the intended per-key filter.
-        values.push(ignoreSingletons.map(key => key ?? ''));
-    }
     if (hasIgnoreGroups) {
         paramIndex++;
         ignoreGroupsParam = `$${paramIndex}::text[]`;
@@ -2146,7 +2174,7 @@ function buildFetchParams(options) {
         maxPriorityParam = `$${paramIndex}::int`;
         values.push(maxPriority);
     }
-    return { values, ignoreSingletonsParam, ignoreGroupsParam, defaultGroupLimitParam, tiersParam, minPriorityParam, maxPriorityParam };
+    return { values, ignoreGroupsParam, defaultGroupLimitParam, tiersParam, minPriorityParam, maxPriorityParam };
 }
 /**
  * Builds the fetch query for claiming jobs from the queue.
@@ -2167,8 +2195,8 @@ function buildFetchParams(options) {
 export function fetchNextJob(options, noSkipLocked = false) {
     const { schema, table, name, policy, limit, includeMetadata, includeTraceContext = false, ignoreStartAfter = false, groupConcurrency, minPriority, maxPriority } = options;
     const keyStrictFifo = policy === QUEUE_POLICIES.key_strict_fifo;
-    const singletonFetch = limit > 1 && (policy === QUEUE_POLICIES.singleton || policy === QUEUE_POLICIES.stately);
-    const hasIgnoreSingletons = options.ignoreSingletons != null && options.ignoreSingletons.length > 0;
+    const singletonPolicy = policy === QUEUE_POLICIES.singleton || policy === QUEUE_POLICIES.stately;
+    const singletonFetch = limit > 1 && singletonPolicy;
     const hasIgnoreGroups = options.ignoreGroups != null && options.ignoreGroups.length > 0;
     const hasGroupConcurrency = groupConcurrency != null;
     const hasMinPriority = minPriority != null;
@@ -2266,7 +2294,19 @@ export function fetchNextJob(options, noSkipLocked = false) {
               AND b.id <> j.id
           )`
             : '',
-        hasIgnoreSingletons ? `COALESCE(j.singleton_key, '') <> ALL(${params.ignoreSingletonsParam})` : '',
+        // Skips a key whose active slot is taken, so its pending job does not lose the fetch to a
+        // job_i2/job_i3 conflict and block the keys behind it. Read live: queue stats can be one
+        // monitor interval old or more, and a stale active key would block the key with nothing active.
+        singletonPolicy
+            ? `NOT EXISTS (
+            SELECT 1
+            FROM ${schema}.${table} singleton_probe
+            WHERE singleton_probe.name = j.name
+              AND singleton_probe.state = '${JOB_STATES.active}'
+              AND singleton_probe.policy = '${policy}'
+              AND COALESCE(singleton_probe.singleton_key, '') = COALESCE(j.singleton_key, '')
+          )`
+            : '',
         hasIgnoreGroups ? `(j.group_id IS NULL OR j.group_id <> ALL(${params.ignoreGroupsParam}))` : '',
         hasMinPriority ? `j.priority >= ${params.minPriorityParam}` : '',
         hasMaxPriority ? `j.priority <= ${params.maxPriorityParam}` : '',
@@ -2520,13 +2560,16 @@ export function cancelJobs(schema, table, fenced) {
 }
 // A resumed job's start_after moves up to now, as a released flow child's does, so its wait (in the
 // monitor's histograms and ready_oldest_seconds) counts from when it could run again rather than
-// from when it was first sent. A start_after still in the future is kept.
+// from when it was first sent. A start_after still in the future is kept. It also loses upsert_by_key,
+// here and in restoreJobs, so it never collides in job_i13 with a newer job upserted by the same key,
+// and queues beside it.
 export function resumeJobs(schema, table) {
     return `
     WITH results as (
       UPDATE ${schema}.${table}
       SET completed_on = NULL,
         state = '${JOB_STATES.created}',
+        upsert_by_key = NULL,
         start_after = GREATEST(start_after, ${schema}.job_now())
       WHERE name = $1
         AND id = ANY($2::uuid[])
@@ -2541,7 +2584,8 @@ export function restoreJobs(schema, table) {
     UPDATE ${schema}.${table}
     SET state = '${JOB_STATES.created}',
         started_on = NULL,
-        heartbeat_on = NULL
+        heartbeat_on = NULL,
+        upsert_by_key = NULL
     WHERE name = $1
       AND id = ANY($2::uuid[])
   `;
@@ -2566,7 +2610,11 @@ export function restoreJobs(schema, table) {
 function isDateTimeString(expression) {
     return `(right(${expression}, 1) = 'Z' OR ${expression} ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}')`;
 }
-export function insertJobs(schema, { table, name, returnId = true, notify = false, slots = false }) {
+// The queue is LEFT JOINed and every NOT NULL column it supplies falls back to the schema default, so
+// a job for a queue deleted after the caller cached it still reaches q_fkey and fails there (23503),
+// rather than producing no row, which would read the same as a singleton or throttle refusal. The
+// fallbacks never apply to a queue that exists, since its own columns are NOT NULL.
+export function insertJobs(schema, { table, name, returnId = true, notify = false, slots = false, upsertByKey = false }) {
     // When notify is enabled we always RETURN start_after so the wrapper below can gate
     // the NOTIFY on immediate availability, regardless of whether the caller wants ids.
     const returning = notify ? 'RETURNING id, start_after' : returnId ? 'RETURNING id' : '';
@@ -2603,7 +2651,7 @@ export function insertJobs(schema, { table, name, returnId = true, notify = fals
       blocked,
       blocking,
       pending_dependencies,
-      trace_context
+      trace_context${upsertByKey ? ', upsert_by_key' : ''}
     )
     SELECT
       COALESCE(id, gen_random_uuid()) as id,
@@ -2620,12 +2668,12 @@ export function insertJobs(schema, { table, name, returnId = true, notify = fals
         END as singleton_on,
       "groupId" as group_id,
       "groupTier" as group_tier,
-      COALESCE("expireInSeconds", q.expire_seconds) as expire_seconds,
-      COALESCE("deleteAfterSeconds", q.deletion_seconds) as deletion_seconds,
-      j.start_after + (COALESCE("retentionSeconds", q.retention_seconds) * interval '1s') as keep_until,
-      COALESCE("retryLimit", q.retry_limit) as retry_limit,
-      COALESCE("retryDelay", q.retry_delay) as retry_delay,
-      COALESCE("retryBackoff", q.retry_backoff, false) as retry_backoff,
+      COALESCE("expireInSeconds", q.expire_seconds, ${QUEUE_DEFAULTS.expire_seconds}) as expire_seconds,
+      COALESCE("deleteAfterSeconds", q.deletion_seconds, ${QUEUE_DEFAULTS.deletion_seconds}) as deletion_seconds,
+      j.start_after + (COALESCE("retentionSeconds", q.retention_seconds, ${QUEUE_DEFAULTS.retention_seconds}) * interval '1s') as keep_until,
+      COALESCE("retryLimit", q.retry_limit, ${QUEUE_DEFAULTS.retry_limit}) as retry_limit,
+      COALESCE("retryDelay", q.retry_delay, ${QUEUE_DEFAULTS.retry_delay}) as retry_delay,
+      COALESCE("retryBackoff", q.retry_backoff, ${QUEUE_DEFAULTS.retry_backoff}) as retry_backoff,
       COALESCE("retryDelayMax", q.retry_delay_max) as retry_delay_max,
       q.policy,
       COALESCE("deadLetter", q.dead_letter) as dead_letter,
@@ -2633,7 +2681,7 @@ export function insertJobs(schema, { table, name, returnId = true, notify = fals
       COALESCE(blocked, false) as blocked,
       COALESCE(blocking, false) as blocking,
       COALESCE("pendingDependencies", 0) as pending_dependencies,
-      "__traceContext" as trace_context
+      "__traceContext" as trace_context${upsertByKey ? ', true as upsert_by_key' : ''}
     FROM (
       SELECT *,
         CASE
@@ -2666,7 +2714,7 @@ export function insertJobs(schema, { table, name, returnId = true, notify = fals
         "__traceContext" jsonb
       )
     ) j
-    JOIN ${schema}.queue q ON q.name = '${name}'
+    LEFT JOIN ${schema}.queue q ON q.name = '${name}'
     ON CONFLICT DO NOTHING
     ${returning}
   `;
@@ -3910,6 +3958,24 @@ export function cacheQueueStats(schema, table, queues, noAdvisoryLocks, throughp
     // Serialize the $1 parameter for use in the multi-statement transaction below
     const statsText = statsQuery.text.replaceAll('$1::text[]', serializeArrayParam(queues));
     const lock = tryAdvisoryLock(schema, 'queue-stats', noAdvisoryLocks);
+    // Only when the try-lock was lost. Clearing the claim makes the queue due from monitor_on, which is
+    // already a full interval old, so the next pass claims it again. No other instance can have
+    // claimed it since this pass did, because the claim is not due again yet. The rows are locked in
+    // name order like everywhere else.
+    const release = lock.cte
+        ? `released AS (
+      UPDATE ${schema}.queue SET monitor_claim_on = NULL
+      FROM (
+        SELECT name
+        FROM ${schema}.queue
+        WHERE name = ANY(${serializeArrayParam(queues)}) AND NOT (SELECT got FROM lock)
+        ORDER BY name
+        FOR NO KEY UPDATE
+      ) r
+      WHERE queue.name = r.name
+    ),
+    `
+        : '';
     // Two columns in here are not counts and are easy to mistake for incidental:
     //
     // monitor_on is stamped by this statement and by refreshQueueStats - the two that write counts -
@@ -3936,7 +4002,7 @@ export function cacheQueueStats(schema, table, queues, noAdvisoryLocks, throughp
     // Its count over stats is there only to finish the aggregate before the first row is locked, so no
     // queue row stays locked through the job table scan.
     const sql = `
-    WITH ${lock.cte}stats AS (SELECT * FROM (${statsText}) agg WHERE true${lock.guard})
+    WITH ${lock.cte}${release}stats AS (SELECT * FROM (${statsText}) agg WHERE true${lock.guard})
     UPDATE ${schema}.queue SET
       deferred_count = COALESCE(stats."deferredCount", 0),
       blocked_count = COALESCE(stats."blockedCount", 0),
@@ -4088,12 +4154,14 @@ function advisoryLock(schema, key) {
 // overlapping-analytics regime this whole subsystem exists to prevent, manufactured by the lock
 // meant to prevent duplicate work.
 //
-// So the loser does nothing. trySetQueueMonitorTime stamped monitor_claim_on a statement earlier,
-// when it claimed the interval and before this lock was attempted, so those queues sit out one
-// interval rather than retrying at once - their counts end up at most one monitorIntervalSeconds
-// behind, and monitor_on keeps aging so capturedOn says so.
-// Against a staleness budget measured in hours, losing one sample costs a gap in the sparkline;
-// winning the race to duplicate a scan nobody asked for costs the job table.
+// So the loser does not count. cacheQueueStats also hands back the interval claim that
+// trySetQueueMonitorTime stamped a statement earlier, so those queues are due again on the next
+// pass of any instance instead of a whole monitorIntervalSeconds later. Keeping the claim looked
+// like losing one sample, but it does not stay one. A pass claims and counts one chunk (or one
+// partitioned table) at a time, so a second instance whose pass overlaps claims every queue the
+// first has not reached yet, and loses the lock to the first one's aggregate. Both sets are then
+// stamped together, come due together, and race again the next interval. With 3 instances and
+// 250 queues that was 41% of claims never counted and runs of 10 in a row.
 //
 // The guard is a one-time filter, so a lost race skips the scan rather than running and discarding
 // it, verified on the plan: `Parallel Seq Scan on job (never executed)`. It also has to gate the
@@ -4461,6 +4529,32 @@ function manifestSection(partitioned) {
 function applyManifestSchema(text, schema) {
     return text.split(schemaManifest.schemaToken).join(schema);
 }
+// The argument types in a manifest function's definition, without names or defaults, as DROP FUNCTION
+// takes them: "create_queue(queue_name text, options jsonb)" gives "text, jsonb".
+function functionArgTypes(def) {
+    const args = def.slice(def.indexOf('(') + 1, def.indexOf(')'));
+    return args.split(',')
+        .map(arg => arg.trim().replace(/\s+DEFAULT\s+.*$/i, ''))
+        .filter(Boolean)
+        .map(arg => arg.split(/\s+/).slice(1).join(' '))
+        .join(', ');
+}
+// Removes everything create() installs, for a schema pg-boss shares with other objects; a schema of
+// its own is simply dropped. Read from the manifest, so it covers whatever this version installs.
+// Dropping job takes every queue's own table with it: a partitioned queue's table is a partition of
+// job, and without partitioning every queue's jobs are in job itself. queue_stats' daily partitions
+// go with queue_stats the same way.
+export function uninstall(schema, partitioned = true) {
+    const section = manifestSection(partitioned);
+    const tables = section.tables.map(table => `${schema}.${table}`).join(', ');
+    const functions = section.functions.map(fn => `${schema}.${fn.name}(${functionArgTypes(fn.def)})`).join(', ');
+    // Functions first: CockroachDB records a function as depending on the tables its body names.
+    return [
+        `DROP FUNCTION IF EXISTS ${functions};`,
+        `DROP TABLE IF EXISTS ${tables};`,
+        `DROP TYPE IF EXISTS ${schema}.job_state;`
+    ].join('\n');
+}
 // The job_state enum values in declaration order, from the manifest (both sections carry the same enum).
 // Order is significant. The numeric base type makes created < retry < … < failed load-bearing.
 export const EXPECTED_JOB_STATES = schemaManifest.partitioned.enum;

package/dist/registrar.d.ts

@@ -8,7 +8,7 @@ declare class Registrar extends EventEmitter implements types.EventsMixin {
         error: string;
     };
     constructor(id: string, db: types.IDatabase, manager: Manager, config: types.ResolvedConstructorOptions);
-    start(): Promise<void>;
+    start(startAttempt?: number): Promise<void>;
     stop(): Promise<void>;
     getInstances(): Promise<types.Instance[]>;
 }

package/dist/registrar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../src/registrar.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAiCnC,cAAM,SAAU,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAWnB,MAAM;;MAAS;gBAEF,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IASlG,KAAK;IAuBL,IAAI;IAuBJ,YAAY,IAAK,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;CA4IjD;AAED,eAAe,SAAS,CAAA"}
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../src/registrar.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAiCnC,cAAM,SAAU,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAYnB,MAAM;;MAAS;gBAEF,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAUlG,KAAK,CAAE,YAAY,SAAI;IAyBvB,IAAI;IAuBJ,YAAY,IAAK,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;CA8IjD;AAED,eAAe,SAAS,CAAA"}

package/dist/registrar.js

@@ -43,6 +43,7 @@ class Registrar extends EventEmitter {
     #nurse = new Nurse();
     #recount;
     #active = false;
+    #startAttempt = 1;
     events = events;
     constructor(id, db, manager, config) {
         super();
@@ -51,9 +52,11 @@ class Registrar extends EventEmitter {
         this.#manager = manager;
         this.#config = config;
     }
-    async start() {
+    // startAttempt is the start() try this registration comes from, recorded in config when past the first.
+    async start(startAttempt = 1) {
         if (!this.#config.registerInstance || this.#timer)
             return;
+        this.#startAttempt = startAttempt;
         this.#active = true;
         this.#nurse.start();
         try {
@@ -173,6 +176,8 @@ class Registrar extends EventEmitter {
             if (value !== undefined)
                 config[key] = value;
         }
+        if (this.#startAttempt > 1)
+            config.startAttempt = this.#startAttempt;
         return config;
     }
     // One entry per work() call. Each call spawns localConcurrency workers sharing a workId, so they are

package/dist/schema.json

@@ -1,6 +1,6 @@
 {
     "_generated": "Generated by scripts/gen-manifest.ts — do not edit by hand. Run `npm run gen:manifest`.",
-    "version": 44,
+    "version": 45,
     "schemaToken": "{{schema}}",
     "partitioned": {
         "tables": [
@@ -521,6 +521,13 @@
                 "notNull": false,
                 "default": null
             },
+            {
+                "table": "job_common",
+                "column": "upsert_by_key",
+                "type": "boolean",
+                "notNull": false,
+                "default": null
+            },
             {
                 "table": "job_dependency",
                 "column": "child_id",
@@ -801,6 +808,13 @@
                 "notNull": false,
                 "default": null
             },
+            {
+                "table": "job",
+                "column": "upsert_by_key",
+                "type": "boolean",
+                "notNull": false,
+                "default": null
+            },
             {
                 "table": "queue_stats",
                 "column": "active_count",
@@ -1458,6 +1472,12 @@
                 "valid": true,
                 "def": "CREATE INDEX job_common_i12 ON {{schema}}.job_common USING btree (source_root_id) WHERE (source_root_id IS NOT NULL)"
             },
+            {
+                "name": "job_common_i13",
+                "table": "job_common",
+                "valid": true,
+                "def": "CREATE UNIQUE INDEX job_common_i13 ON {{schema}}.job_common USING btree (name, singleton_key) WHERE ((state = 'created'::{{schema}}.job_state) AND upsert_by_key)"
+            },
             {
                 "name": "job_common_i2",
                 "table": "job_common",
@@ -1522,7 +1542,7 @@
         "functions": [
             {
                 "name": "create_queue",
-                "def": "CREATE OR REPLACE FUNCTION {{schema}}.create_queue(queue_name text, options jsonb)\n RETURNS void\n LANGUAGE plpgsql\nAS $function$\n    DECLARE\n      tablename varchar := CASE WHEN options->>'partition' = 'true'\n                            THEN 'j' || encode(sha224(queue_name::bytea), 'hex')\n                            ELSE 'job_common'\n                            END;\n      queue_created_on timestamptz;\n    BEGIN\n\n      WITH q as (\n        INSERT INTO {{schema}}.queue (\n          name,\n          policy,\n          retry_limit,\n          retry_delay,\n          retry_backoff,\n          retry_delay_max,\n          expire_seconds,\n          retention_seconds,\n          deletion_seconds,\n          warning_queued,\n          dead_letter,\n          partition,\n          table_name,\n          heartbeat_seconds,\n          notify,\n          created_on,\n          updated_on\n        )\n        VALUES (\n          queue_name,\n          options->>'policy',\n          COALESCE((options->>'retryLimit')::int, 2),\n          COALESCE((options->>'retryDelay')::int, 0),\n          COALESCE((options->>'retryBackoff')::bool, false),\n          (options->>'retryDelayMax')::int,\n          COALESCE((options->>'expireInSeconds')::int, 900),\n          COALESCE((options->>'retentionSeconds')::int, 1209600),\n          COALESCE((options->>'deleteAfterSeconds')::int, 604800),\n          COALESCE((options->>'warningQueueSize')::int, 0),\n          options->>'deadLetter',\n          COALESCE((options->>'partition')::bool, false),\n          tablename,\n          (options->>'heartbeatSeconds')::int,\n          COALESCE((options->>'notify')::bool, false),\n          {{schema}}.job_now(),\n          {{schema}}.job_now()\n        )\n        ON CONFLICT DO NOTHING\n        RETURNING created_on\n      )\n      SELECT created_on into queue_created_on from q;\n\n      IF queue_created_on IS NULL OR options->>'partition' IS DISTINCT FROM 'true' THEN\n        RETURN;\n      END IF;\n\n      EXECUTE format('CREATE TABLE {{schema}}.%I (LIKE {{schema}}.job INCLUDING DEFAULTS)', tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD PRIMARY KEY (name, id)$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT q_fkey FOREIGN KEY (name) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT dlq_fkey FOREIGN KEY (dead_letter) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i11 ON {{schema}}.job (name, priority DESC, created_on, start_after) WHERE state < 'active' AND NOT blocked$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i4 ON {{schema}}.job (name, singleton_on, COALESCE(singleton_key, '')) WHERE state <> 'cancelled' AND singleton_on IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i7 ON {{schema}}.job (name, group_id) WHERE state = 'active' AND group_id IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i9 ON {{schema}}.job (name, id) WHERE blocking AND state = 'completed'$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i12 ON {{schema}}.job (source_root_id) WHERE source_root_id IS NOT NULL$cmd$, tablename);\n\n      IF options->>'policy' = 'short' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i1 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'created' AND policy = 'short'$cmd$, tablename);\n      ELSIF options->>'policy' = 'singleton' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i2 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'active' AND policy = 'singleton'$cmd$, tablename);\n      ELSIF options->>'policy' = 'stately' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i3 ON {{schema}}.job (name, state, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'stately'$cmd$, tablename);\n      ELSIF options->>'policy' = 'exclusive' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i6 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'exclusive'$cmd$, tablename);\n      ELSIF options->>'policy' = 'key_strict_fifo' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i8 ON {{schema}}.job (name, singleton_key) WHERE state IN ('active', 'retry', 'failed') AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i10 ON {{schema}}.job (name, singleton_key, state DESC, created_on, id) INCLUDE (start_after) WHERE state < 'active' AND NOT blocked AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT job_key_strict_fifo_singleton_key_check CHECK (NOT (policy = 'key_strict_fifo' AND singleton_key IS NULL))$cmd$, tablename);\n      END IF;\n\n      EXECUTE format('ALTER TABLE {{schema}}.%I ADD CONSTRAINT cjc CHECK (name=%L)', tablename, queue_name);\n      EXECUTE format('ALTER TABLE {{schema}}.job ATTACH PARTITION {{schema}}.%I FOR VALUES IN (%L)', tablename, queue_name);\n    END;\n    $function$\n"
+                "def": "CREATE OR REPLACE FUNCTION {{schema}}.create_queue(queue_name text, options jsonb)\n RETURNS void\n LANGUAGE plpgsql\nAS $function$\n    DECLARE\n      tablename varchar := CASE WHEN options->>'partition' = 'true'\n                            THEN 'j' || encode(sha224(queue_name::bytea), 'hex')\n                            ELSE 'job_common'\n                            END;\n      queue_created_on timestamptz;\n    BEGIN\n\n      WITH q as (\n        INSERT INTO {{schema}}.queue (\n          name,\n          policy,\n          retry_limit,\n          retry_delay,\n          retry_backoff,\n          retry_delay_max,\n          expire_seconds,\n          retention_seconds,\n          deletion_seconds,\n          warning_queued,\n          dead_letter,\n          partition,\n          table_name,\n          heartbeat_seconds,\n          notify,\n          created_on,\n          updated_on\n        )\n        VALUES (\n          queue_name,\n          options->>'policy',\n          COALESCE((options->>'retryLimit')::int, 2),\n          COALESCE((options->>'retryDelay')::int, 0),\n          COALESCE((options->>'retryBackoff')::bool, false),\n          (options->>'retryDelayMax')::int,\n          COALESCE((options->>'expireInSeconds')::int, 900),\n          COALESCE((options->>'retentionSeconds')::int, 1209600),\n          COALESCE((options->>'deleteAfterSeconds')::int, 604800),\n          COALESCE((options->>'warningQueueSize')::int, 0),\n          options->>'deadLetter',\n          COALESCE((options->>'partition')::bool, false),\n          tablename,\n          (options->>'heartbeatSeconds')::int,\n          COALESCE((options->>'notify')::bool, false),\n          {{schema}}.job_now(),\n          {{schema}}.job_now()\n        )\n        ON CONFLICT DO NOTHING\n        RETURNING created_on\n      )\n      SELECT created_on into queue_created_on from q;\n\n      IF queue_created_on IS NULL OR options->>'partition' IS DISTINCT FROM 'true' THEN\n        RETURN;\n      END IF;\n\n      EXECUTE format('CREATE TABLE {{schema}}.%I (LIKE {{schema}}.job INCLUDING DEFAULTS)', tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD PRIMARY KEY (name, id)$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT q_fkey FOREIGN KEY (name) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT dlq_fkey FOREIGN KEY (dead_letter) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i11 ON {{schema}}.job (name, priority DESC, created_on, start_after) WHERE state < 'active' AND NOT blocked$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i4 ON {{schema}}.job (name, singleton_on, COALESCE(singleton_key, '')) WHERE state <> 'cancelled' AND singleton_on IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i7 ON {{schema}}.job (name, group_id) WHERE state = 'active' AND group_id IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i9 ON {{schema}}.job (name, id) WHERE blocking AND state = 'completed'$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i12 ON {{schema}}.job (source_root_id) WHERE source_root_id IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i13 ON {{schema}}.job (name, singleton_key) WHERE state = 'created' AND upsert_by_key$cmd$, tablename);\n\n      IF options->>'policy' = 'short' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i1 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'created' AND policy = 'short'$cmd$, tablename);\n      ELSIF options->>'policy' = 'singleton' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i2 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'active' AND policy = 'singleton'$cmd$, tablename);\n      ELSIF options->>'policy' = 'stately' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i3 ON {{schema}}.job (name, state, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'stately'$cmd$, tablename);\n      ELSIF options->>'policy' = 'exclusive' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i6 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'exclusive'$cmd$, tablename);\n      ELSIF options->>'policy' = 'key_strict_fifo' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i8 ON {{schema}}.job (name, singleton_key) WHERE state IN ('active', 'retry', 'failed') AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i10 ON {{schema}}.job (name, singleton_key, state DESC, created_on, id) INCLUDE (start_after) WHERE state < 'active' AND NOT blocked AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT job_key_strict_fifo_singleton_key_check CHECK (NOT (policy = 'key_strict_fifo' AND singleton_key IS NULL))$cmd$, tablename);\n      END IF;\n\n      EXECUTE format('ALTER TABLE {{schema}}.%I ADD CONSTRAINT cjc CHECK (name=%L)', tablename, queue_name);\n      EXECUTE format('ALTER TABLE {{schema}}.job ATTACH PARTITION {{schema}}.%I FOR VALUES IN (%L)', tablename, queue_name);\n    END;\n    $function$\n"
             },
             {
                 "name": "delete_queue",
@@ -2100,6 +2120,13 @@
                 "notNull": false,
                 "default": null
             },
+            {
+                "table": "job",
+                "column": "upsert_by_key",
+                "type": "boolean",
+                "notNull": false,
+                "default": null
+            },
             {
                 "table": "queue_stats",
                 "column": "active_count",
@@ -2759,6 +2786,12 @@
                 "valid": true,
                 "def": "CREATE INDEX job_i12 ON {{schema}}.job USING btree (source_root_id) WHERE (source_root_id IS NOT NULL)"
             },
+            {
+                "name": "job_i13",
+                "table": "job",
+                "valid": true,
+                "def": "CREATE UNIQUE INDEX job_i13 ON {{schema}}.job USING btree (name, singleton_key) WHERE ((state = 'created'::{{schema}}.job_state) AND upsert_by_key)"
+            },
             {
                 "name": "job_i2",
                 "table": "job",

package/dist/timekeeper.d.ts

@@ -76,6 +76,9 @@ declare class Timekeeper extends EventEmitter implements types.EventsMixin {
      * labels every row from its default. Either way the row reads fine and never fires again. So when
      * an expression cannot be read the way the column says, and is written the other way, it is read
      * the way it is written: one regex, on a path that was already about to give up.
+     *
+     * An empty expression is refused first, as schedule() refuses it. cron-parser would read one as
+     * every minute, and a row stored before schedule() checked for it would keep firing that often.
      */
     private dueOccurrences;
     /**
@@ -170,7 +173,7 @@ declare class Timekeeper extends EventEmitter implements types.EventsMixin {
      */
     previewSchedule(cron: string, options?: types.PreviewScheduleOptions): Date[];
     schedule(name: string, cron: string, data?: unknown, options?: types.ScheduleOptions): Promise<void>;
-    unschedule(name: string, key?: string): Promise<void>;
+    unschedule(name: string, key?: string, options?: types.ConnectionOptions): Promise<void>;
 }
 export default Timekeeper;
 //# sourceMappingURL=timekeeper.d.ts.map

package/dist/timekeeper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timekeeper.d.ts","sourceRoot":"","sources":["../src/timekeeper.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAKvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAGnC,eAAO,MAAM,MAAM;;CAElB,CAAA;AAwBD,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,OAAO,CAAA;AA8MrC,cAAM,UAAW,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;IAChE,EAAE,EAAE,KAAK,CAAC,SAAS,CAAA;IACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B,CAAA;IACxC,OAAO,EAAE,OAAO,CAAA;IAEhB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,aAAa,CAAQ;IAS7B,OAAO,CAAC,eAAe,CAAoB;IAE3C,SAAS,SAAI;IACb,MAAM;;;;MAAS;gBAEF,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAQ5F,IAAI,YAAY,IAAK,OAAO,CAE3B;IAED,IAAI,WAAW,IAAK,OAAO,CAE1B;IAMD,OAAO,KAAK,YAAY,GAEvB;IAED,OAAO,KAAK,cAAc,GASzB;IAEK,KAAK;IA4BL,IAAI;IAmCV,OAAO,CAAC,mBAAmB;IAUrB,cAAc;IA8Cd,MAAM;IAuDZ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;OAKG;IACG,IAAI,CAAE,WAAW,GAAE,OAAc;IAoIvC,YAAY,CAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,KAAK,CAAC,YAAwC;IAIlG;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,iBAAiB;YAQX,QAAQ;YAsDR,aAAa;IAerB,YAAY,CAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAiBrE,WAAW,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IAe1E;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,KAAK,CAAC,sBAA2B,GAAG,IAAI,EAAE;IA0C5E,QAAQ,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,KAAK,CAAC,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CzG,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"timekeeper.d.ts","sourceRoot":"","sources":["../src/timekeeper.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAKvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAGnC,eAAO,MAAM,MAAM;;CAElB,CAAA;AAwBD,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAuNrC,cAAM,UAAW,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;IAChE,EAAE,EAAE,KAAK,CAAC,SAAS,CAAA;IACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B,CAAA;IACxC,OAAO,EAAE,OAAO,CAAA;IAEhB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,aAAa,CAAQ;IAS7B,OAAO,CAAC,eAAe,CAAoB;IAE3C,SAAS,SAAI;IACb,MAAM;;;;MAAS;gBAEF,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAQ5F,IAAI,YAAY,IAAK,OAAO,CAE3B;IAED,IAAI,WAAW,IAAK,OAAO,CAE1B;IAMD,OAAO,KAAK,YAAY,GAEvB;IAED,OAAO,KAAK,cAAc,GASzB;IAEK,KAAK;IA4BL,IAAI;IAmCV,OAAO,CAAC,mBAAmB;IAUrB,cAAc;IA8Cd,MAAM;IAuDZ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;OAKG;IACG,IAAI,CAAE,WAAW,GAAE,OAAc;IAoIvC,YAAY,CAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,KAAK,CAAC,YAAwC;IAIlG;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,iBAAiB;YAQX,QAAQ;YAwDR,aAAa;IAerB,YAAY,CAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAiBrE,WAAW,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IAe1E;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,KAAK,CAAC,sBAA2B,GAAG,IAAI,EAAE;IA0C5E,QAAQ,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,KAAK,CAAC,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDzG,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,EAAE,OAAO,GAAE,KAAK,CAAC,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAIhG;AAED,eAAe,UAAU,CAAA"}

package/dist/timekeeper.js

@@ -178,11 +178,18 @@ function parseRecurrence(cron, tz, currentDate) {
     assertTimezone(tz);
     return CronExpressionParser.parse(cron, { tz, strict: false, currentDate });
 }
+// cron-parser reads an empty expression, and undefined or null, as `* * * * *`, and those are nearly
+// always a missing value, not a request to run every minute. Checked before isRrule(), which reads a
+// non-string as its string form and would send something like ['FREQ=DAILY'] down the rule path.
+function assertExpression(expression) {
+    assert(typeof expression === 'string' && expression.trim() !== '', 'cron expression must be a non-empty string');
+}
 /**
  * Validates a recurrence in whichever of the two formats it is written, so previewSchedule() and
  * schedule() reject exactly the same expressions.
  */
 function assertRecurrence(expression, tz, now) {
+    assertExpression(expression);
     if (isRrule(expression)) {
         assertRrule(expression, tz);
     }
@@ -542,8 +549,12 @@ class Timekeeper extends EventEmitter {
      * labels every row from its default. Either way the row reads fine and never fires again. So when
      * an expression cannot be read the way the column says, and is written the other way, it is read
      * the way it is written: one regex, on a path that was already about to give up.
+     *
+     * An empty expression is refused first, as schedule() refuses it. cron-parser would read one as
+     * every minute, and a row stored before schedule() checked for it would keep firing that often.
      */
     dueOccurrences(expression, kind, tz, databaseTime = this.databaseTime) {
+        assertExpression(expression);
         try {
             return { kind, occurrences: this.readOccurrences(expression, kind, tz, databaseTime) };
         }
@@ -670,7 +681,9 @@ class Timekeeper extends EventEmitter {
             // key and slot are the pass's own bookkeeping, read below rather than sent: send() takes the
             // request the schedule row described and nothing else.
             const { key, slot, ...request } = data;
-            return await this.manager.send(request);
+            // A row written before 12.37.0 may still carry `db` from schedule(); it is never a send option here.
+            const { db, ...options } = request.options ?? {};
+            return await this.manager.send({ ...request, options });
         }));
         // Keyed on (name, key) so a batch holding more than one occurrence of the same schedule
         // resolves to its latest. Feeding several to the UPDATE would let postgres pick any of the
@@ -756,6 +769,7 @@ class Timekeeper extends EventEmitter {
      * occurrence after the last one handed back.
      */
     occurrenceWalker(expression, tz, from) {
+        assertExpression(expression);
         if (isRrule(expression)) {
             assertRrule(expression, tz);
             return rruleWalker(expression, tz, from);
@@ -810,9 +824,12 @@ class Timekeeper extends EventEmitter {
         return occurrences;
     }
     async schedule(name, cron, data, options = {}) {
+        // `db` is how this call runs, not part of the schedule: it comes out first so the options blob
+        // stored on the row, and later handed to send() by the cron pass, never carries a connection.
+        const { db, ...persisted } = options;
         // `missed` comes out with tz and key: it tells the pass what to do about a gap and is no more a
         // send option than they are, so the send-option check below is not handed it.
-        const { tz: requestedTz, key = '', missed, ...rest } = options;
+        const { tz: requestedTz, key = '', missed, ...rest } = persisted;
         // Any falsy zone is "none specified", not a zone to be judged: a destructuring default only
         // covers `undefined`, and a value threaded out of a config object or read back off the nullable
         // timezone column arrives as null. Coalescing it here is what keeps the two engines from
@@ -838,7 +855,7 @@ class Timekeeper extends EventEmitter {
         assertMissedPolicy(missed);
         try {
             const sql = plans.schedule(this.config.schema);
-            await this.db.executeSql(sql, [name, key, kind, cron, tz, data, options]);
+            await (db || this.db).executeSql(sql, [name, key, kind, cron, tz, data, persisted]);
         }
         catch (err) {
             if (err.message.includes('foreign key')) {
@@ -847,9 +864,9 @@ class Timekeeper extends EventEmitter {
             throw err;
         }
     }
-    async unschedule(name, key = '') {
+    async unschedule(name, key = '', options = {}) {
         const sql = plans.unschedule(this.config.schema);
-        await this.db.executeSql(sql, [name, key]);
+        await (options.db || this.db).executeSql(sql, [name, key]);
     }
 }
 export default Timekeeper;