pg-boss 12.35.1 → 12.37.0

package/dist/telemetry.d.ts

@@ -0,0 +1,65 @@
+import type * as types from './types.ts';
+export declare const ATTR: {
+    readonly messagingSystem: "messaging.system";
+    readonly operationName: "messaging.operation.name";
+    readonly operationType: "messaging.operation.type";
+    readonly destinationName: "messaging.destination.name";
+    readonly messageId: "messaging.message.id";
+    readonly batchMessageCount: "messaging.batch.message_count";
+    readonly errorType: "error.type";
+    readonly dbNamespace: "db.namespace";
+    readonly schema: "pgboss.schema";
+    readonly retryCount: "pgboss.job.retry_count";
+    readonly jobState: "pgboss.job.state";
+};
+export declare const METRIC: {
+    readonly operationDuration: "messaging.client.operation.duration";
+    readonly sentMessages: "messaging.client.sent.messages";
+    readonly consumedMessages: "messaging.client.consumed.messages";
+    readonly processDuration: "messaging.process.duration";
+    readonly queueJobs: "pgboss.queue.jobs";
+};
+export declare const MESSAGING_SYSTEM = "pg-boss";
+export declare const INSTRUMENTATION_SCOPE = "pg-boss";
+export type TraceCarrier = Record<string, string>;
+interface CarrierJob {
+    id: string;
+    retryCount?: number;
+}
+type QueueSnapshot = () => Record<string, types.QueueResult> | null;
+declare class Telemetry {
+    #private;
+    readonly enabled: boolean;
+    constructor(options: types.OpenTelemetryOptions | undefined, schema: string, queues: QueueSnapshot);
+    setDatabase(database: string): void;
+    observeQueues(): void;
+    unobserveQueues(): void;
+    refreshInstruments(): void;
+    /**
+     * Runs a job-creating operation in a PRODUCER span and hands `fn` the trace context to store on
+     * each job it inserts, or null when there is nothing to propagate. `attempted` is the number of
+     * jobs it creates itself, counted whether or not they land. A function instead counts from the
+     * result, and counts nothing when `fn` throws.
+     */
+    send<T>(operation: string, destination: string | null, attempted: number | ((result: T) => number), fn: (carrier: TraceCarrier | null) => Promise<T>, idsOf?: (result: T) => string[] | null): Promise<T>;
+    /**
+     * Wraps a fetch() the application made itself in a CLIENT `receive` span, linked to the send of
+     * every job it returned.
+     */
+    receive<J extends CarrierJob>(destination: string, fn: () => Promise<J[]>, carrierOf: (job: J) => TraceCarrier | null | undefined): Promise<J[]>;
+    consumed(destination: string, count: number): void;
+    /**
+     * Runs a worker's handler over a batch in a CONSUMER `process` span. A batch of one continues the
+     * trace its send() started; a larger batch starts a trace of its own and links to every send.
+     *
+     * `fn` resolves with the error the batch failed with, or undefined when it completed, because the
+     * worker settles a failed batch itself rather than letting the error escape.
+     */
+    process<J extends CarrierJob>(destination: string, jobs: J[], carrierOf: (job: J) => TraceCarrier | null | undefined, fn: () => Promise<unknown>): Promise<void>;
+    /**
+     * Wraps a call that settles or removes jobs (complete, fail, cancel, deleteJob) in a CLIENT span.
+     */
+    settle<T>(operation: string, destination: string, ids: string[], fn: () => Promise<T>): Promise<T>;
+}
+export default Telemetry;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAMxC,eAAO,MAAM,IAAI;;;;;;;;;;;;CAYP,CAAA;AAEV,eAAO,MAAM,MAAM;;;;;;CAMT,CAAA;AAEV,eAAO,MAAM,gBAAgB,YAAY,CAAA;AACzC,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAQ9C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAUjD,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,KAAK,aAAa,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAA;AA8BnE,cAAM,SAAS;;IACb,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAYZ,OAAO,EAAE,KAAK,CAAC,oBAAoB,YAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa;IAa5F,WAAW,CAAE,QAAQ,EAAE,MAAM;IA+E7B,aAAa;IAMb,eAAe;IAQf,kBAAkB;IAIlB;;;;;OAKG;IACG,IAAI,CAAC,CAAC,EACV,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC,EAC3C,EAAE,EAAE,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,KAAK,GAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,EAAE,GAAG,IAAiB,GACjD,OAAO,CAAC,CAAC,CAAC;IA4Cb;;;OAGG;IACG,OAAO,CAAC,CAAC,SAAS,UAAU,EAAG,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAkCvJ,QAAQ,CAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAK5C;;;;;;OAMG;IACG,OAAO,CAAC,CAAC,SAAS,UAAU,EAAG,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,YAAY,GAAG,IAAI,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CvK;;OAEG;IACG,MAAM,CAAC,CAAC,EAAG,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA8C1G;AAED,eAAe,SAAS,CAAA"}

package/dist/telemetry.js

@@ -0,0 +1,349 @@
+import { context, defaultTextMapGetter, defaultTextMapSetter, metrics, propagation, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import packageJson from '../package.json' with { type: 'json' };
+// The OpenTelemetry messaging semantic conventions, copied rather than imported: the messaging
+// attributes still live in the unstable "incubating" entry point of @opentelemetry/semantic-conventions,
+// which is not meant to be depended on by libraries.
+// https://opentelemetry.io/docs/specs/semconv/messaging/
+export const ATTR = {
+    messagingSystem: 'messaging.system',
+    operationName: 'messaging.operation.name',
+    operationType: 'messaging.operation.type',
+    destinationName: 'messaging.destination.name',
+    messageId: 'messaging.message.id',
+    batchMessageCount: 'messaging.batch.message_count',
+    errorType: 'error.type',
+    dbNamespace: 'db.namespace',
+    schema: 'pgboss.schema',
+    retryCount: 'pgboss.job.retry_count',
+    jobState: 'pgboss.job.state'
+};
+export const METRIC = {
+    operationDuration: 'messaging.client.operation.duration',
+    sentMessages: 'messaging.client.sent.messages',
+    consumedMessages: 'messaging.client.consumed.messages',
+    processDuration: 'messaging.process.duration',
+    queueJobs: 'pgboss.queue.jobs'
+};
+export const MESSAGING_SYSTEM = 'pg-boss';
+export const INSTRUMENTATION_SCOPE = 'pg-boss';
+// The bucket boundaries the messaging conventions recommend for their duration histograms.
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
+function errorType(err) {
+    if (err instanceof Error)
+        return err.constructor.name;
+    return '_OTHER';
+}
+function spanName(operation, destination) {
+    return destination ? `${operation} ${destination}` : operation;
+}
+function metricAttributes(attributes, err) {
+    const { [ATTR.messageId]: _id, [ATTR.batchMessageCount]: _count, [ATTR.retryCount]: _retry, ...rest } = attributes;
+    return err === undefined ? rest : { ...rest, [ATTR.errorType]: errorType(err) };
+}
+function recordError(span, err) {
+    span.setAttribute(ATTR.errorType, errorType(err));
+    if (err instanceof Error) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+    }
+}
+function seconds(startedAt) {
+    return (performance.now() - startedAt) / 1000;
+}
+class Telemetry {
+    enabled;
+    #propagate;
+    #propagator;
+    #schema;
+    #namespace;
+    #tracer;
+    #meterProvider;
+    #queues;
+    #instrumentsFor = null;
+    #instruments = null;
+    #observing = false;
+    constructor(options = {}, schema, queues) {
+        this.enabled = options.enabled !== false;
+        this.#propagate = this.enabled && options.propagateContext === true;
+        this.#propagator = options.propagator ?? propagation;
+        this.#schema = schema;
+        this.#namespace = { [ATTR.schema]: schema };
+        this.#tracer = (options.tracerProvider ?? trace.getTracerProvider()).getTracer(INSTRUMENTATION_SCOPE, packageJson.version);
+        this.#meterProvider = options.meterProvider;
+        this.#queues = queues;
+    }
+    // db.namespace follows the PostgreSQL convention, {database}|{schema}, so the same schema in two
+    // databases stays apart. The database is only known once start() has asked for it.
+    setDatabase(database) {
+        this.#namespace = { [ATTR.dbNamespace]: `${database}|${this.#schema}`, [ATTR.schema]: this.#schema };
+    }
+    #baseAttributes(operation, type, destination) {
+        const attributes = {
+            [ATTR.messagingSystem]: MESSAGING_SYSTEM,
+            [ATTR.operationName]: operation,
+            [ATTR.operationType]: type,
+            ...this.#namespace
+        };
+        if (destination)
+            attributes[ATTR.destinationName] = destination;
+        return attributes;
+    }
+    // The global meter provider has no proxy the way the tracer provider does: a meter taken before
+    // an SDK registers stays a no-op forever. Resolving the provider on every use and rebuilding the
+    // instruments when it changes is what lets an SDK started after pg-boss still receive metrics.
+    #getInstruments() {
+        if (!this.enabled)
+            return null;
+        const provider = this.#meterProvider ?? metrics.getMeterProvider();
+        if (provider === this.#instrumentsFor && this.#instruments)
+            return this.#instruments;
+        this.#instruments?.queueJobs.removeCallback(this.#observeQueues);
+        const meter = provider.getMeter(INSTRUMENTATION_SCOPE, packageJson.version);
+        this.#instrumentsFor = provider;
+        this.#instruments = {
+            operationDuration: meter.createHistogram(METRIC.operationDuration, {
+                description: 'Duration of messaging operation initiated by a producer or consumer client.',
+                unit: 's',
+                advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+            }),
+            sentMessages: meter.createCounter(METRIC.sentMessages, {
+                description: 'Number of messages producer attempted to send to the broker.',
+                unit: '{message}'
+            }),
+            consumedMessages: meter.createCounter(METRIC.consumedMessages, {
+                description: 'Number of messages that were delivered to the application.',
+                unit: '{message}'
+            }),
+            processDuration: meter.createHistogram(METRIC.processDuration, {
+                description: 'Duration of processing operation.',
+                unit: 's',
+                advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+            }),
+            queueJobs: meter.createObservableGauge(METRIC.queueJobs, {
+                description: 'Jobs in a queue by state, as of the last queue cache refresh.',
+                unit: '{job}'
+            })
+        };
+        if (this.#observing) {
+            this.#instruments.queueJobs.addCallback(this.#observeQueues);
+        }
+        return this.#instruments;
+    }
+    #observeQueues = (result) => {
+        const queues = this.#queues();
+        if (!queues)
+            return;
+        for (const queue of Object.values(queues)) {
+            const attributes = { [ATTR.messagingSystem]: MESSAGING_SYSTEM, [ATTR.destinationName]: queue.name, ...this.#namespace };
+            result.observe(queue.deferredCount ?? 0, { ...attributes, [ATTR.jobState]: 'deferred' });
+            result.observe(queue.readyCount ?? 0, { ...attributes, [ATTR.jobState]: 'ready' });
+            result.observe(queue.blockedCount ?? 0, { ...attributes, [ATTR.jobState]: 'blocked' });
+            result.observe(queue.activeCount ?? 0, { ...attributes, [ATTR.jobState]: 'active' });
+            result.observe(queue.failedCount ?? 0, { ...attributes, [ATTR.jobState]: 'failed' });
+        }
+    };
+    // Starts reporting pgboss.queue.jobs from the queue cache. Called by start(), undone by stop().
+    observeQueues() {
+        if (!this.enabled || this.#observing)
+            return;
+        this.#observing = true;
+        this.#getInstruments()?.queueJobs.addCallback(this.#observeQueues);
+    }
+    unobserveQueues() {
+        if (!this.#observing)
+            return;
+        this.#observing = false;
+        this.#instruments?.queueJobs.removeCallback(this.#observeQueues);
+    }
+    // Moves the queue gauge to a meter provider registered after start(), which otherwise waits for
+    // the next send, fetch or settle. Called on each queue cache refresh.
+    refreshInstruments() {
+        if (this.#observing)
+            this.#getInstruments();
+    }
+    /**
+     * Runs a job-creating operation in a PRODUCER span and hands `fn` the trace context to store on
+     * each job it inserts, or null when there is nothing to propagate. `attempted` is the number of
+     * jobs it creates itself, counted whether or not they land. A function instead counts from the
+     * result, and counts nothing when `fn` throws.
+     */
+    async send(operation, destination, attempted, fn, idsOf = () => null) {
+        if (!this.enabled)
+            return fn(null);
+        const attributes = this.#baseAttributes(operation, 'send', destination);
+        if (typeof attempted === 'number' && attempted > 1)
+            attributes[ATTR.batchMessageCount] = attempted;
+        const span = this.#tracer.startSpan(spanName(operation, destination), { kind: SpanKind.PRODUCER, attributes });
+        const spanContext = trace.setSpan(context.active(), span);
+        const startedAt = performance.now();
+        let carrier = null;
+        if (this.#propagate) {
+            const injected = {};
+            this.#propagator.inject(spanContext, injected, defaultTextMapSetter);
+            carrier = Object.keys(injected).length > 0 ? injected : null;
+        }
+        try {
+            const result = await context.with(spanContext, () => fn(carrier));
+            const ids = idsOf(result);
+            const sent = typeof attempted === 'number' ? attempted : attempted(result);
+            if (sent === 1 && ids?.length === 1) {
+                span.setAttribute(ATTR.messageId, ids[0]);
+            }
+            this.#recordSend(startedAt, sent, metricAttributes(attributes));
+            return result;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#recordSend(startedAt, typeof attempted === 'number' ? attempted : 0, metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    #recordSend(startedAt, attempted, attributes) {
+        const instruments = this.#getInstruments();
+        instruments?.operationDuration.record(seconds(startedAt), attributes);
+        if (attempted > 0)
+            instruments?.sentMessages.add(attempted, attributes);
+    }
+    /**
+     * Wraps a fetch() the application made itself in a CLIENT `receive` span, linked to the send of
+     * every job it returned.
+     */
+    async receive(destination, fn, carrierOf) {
+        if (!this.enabled)
+            return fn();
+        const attributes = this.#baseAttributes('receive', 'receive', destination);
+        const span = this.#tracer.startSpan(spanName('receive', destination), { kind: SpanKind.CLIENT, attributes });
+        const startedAt = performance.now();
+        try {
+            const jobs = await context.with(trace.setSpan(context.active(), span), fn);
+            if (jobs.length === 1) {
+                span.setAttribute(ATTR.messageId, jobs[0].id);
+            }
+            else {
+                span.setAttribute(ATTR.batchMessageCount, jobs.length);
+            }
+            span.addLinks(this.#links(jobs, carrierOf));
+            const instruments = this.#getInstruments();
+            instruments?.operationDuration.record(seconds(startedAt), metricAttributes(attributes));
+            if (jobs.length > 0)
+                instruments?.consumedMessages.add(jobs.length, metricAttributes(attributes));
+            return jobs;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // Jobs a worker claimed. The worker's own fetch has no span: it polls on a timer, and a span per
+    // empty poll would bury the traces that matter. The process span covers what it delivers.
+    consumed(destination, count) {
+        if (count === 0)
+            return;
+        this.#getInstruments()?.consumedMessages.add(count, metricAttributes(this.#baseAttributes('process', 'process', destination)));
+    }
+    /**
+     * Runs a worker's handler over a batch in a CONSUMER `process` span. A batch of one continues the
+     * trace its send() started; a larger batch starts a trace of its own and links to every send.
+     *
+     * `fn` resolves with the error the batch failed with, or undefined when it completed, because the
+     * worker settles a failed batch itself rather than letting the error escape.
+     */
+    async process(destination, jobs, carrierOf, fn) {
+        if (!this.enabled) {
+            await fn();
+            return;
+        }
+        const attributes = this.#baseAttributes('process', 'process', destination);
+        let parent = ROOT_CONTEXT;
+        let links = [];
+        if (jobs.length === 1) {
+            attributes[ATTR.messageId] = jobs[0].id;
+            if (jobs[0].retryCount !== undefined)
+                attributes[ATTR.retryCount] = jobs[0].retryCount;
+            // The whole extracted context, so baggage sent with the job reaches the handler too.
+            const carrier = carrierOf(jobs[0]);
+            if (carrier)
+                parent = this.#extract(carrier);
+        }
+        else {
+            attributes[ATTR.batchMessageCount] = jobs.length;
+            links = this.#links(jobs, carrierOf);
+        }
+        // The parent is chosen explicitly, never taken from context.active(): the worker loop inherits
+        // whatever context work() was called in, and a job has nothing to do with that caller's trace.
+        const span = this.#tracer.startSpan(spanName('process', destination), { kind: SpanKind.CONSUMER, attributes, links }, parent);
+        const startedAt = performance.now();
+        let failure;
+        try {
+            failure = await context.with(trace.setSpan(parent, span), fn);
+        }
+        catch (err) {
+            failure = err ?? new Error('undefined error');
+            throw err;
+        }
+        finally {
+            if (failure !== undefined)
+                recordError(span, failure);
+            this.#getInstruments()?.processDuration.record(seconds(startedAt), metricAttributes(attributes, failure));
+            span.end();
+        }
+    }
+    /**
+     * Wraps a call that settles or removes jobs (complete, fail, cancel, deleteJob) in a CLIENT span.
+     */
+    async settle(operation, destination, ids, fn) {
+        if (!this.enabled)
+            return fn();
+        const attributes = this.#baseAttributes(operation, 'settle', destination);
+        if (ids.length === 1) {
+            attributes[ATTR.messageId] = ids[0];
+        }
+        else {
+            attributes[ATTR.batchMessageCount] = ids.length;
+        }
+        const span = this.#tracer.startSpan(spanName(operation, destination), { kind: SpanKind.CLIENT, attributes });
+        const startedAt = performance.now();
+        try {
+            const result = await context.with(trace.setSpan(context.active(), span), fn);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes));
+            return result;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    #links(jobs, carrierOf) {
+        const links = [];
+        for (const job of jobs) {
+            const spanContext = this.#extractSpanContext(carrierOf(job));
+            if (spanContext)
+                links.push({ context: spanContext });
+        }
+        return links;
+    }
+    #extract(carrier) {
+        return this.#propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+    }
+    #extractSpanContext(carrier) {
+        if (!carrier)
+            return null;
+        const spanContext = trace.getSpanContext(this.#extract(carrier));
+        return spanContext && trace.isSpanContextValid(spanContext) ? spanContext : null;
+    }
+}
+export default Telemetry;

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;