@nest-native/jobs 0.1.0 → 0.2.0

package/dist/interfaces.d.ts

@@ -104,6 +104,137 @@ export interface JobStore {
     /** Terminal: sets `failed`, attempts+1, and clears `uniqueKey`. */
     markFailed(db: unknown, id: string, reason: string): Promise<void>;
 }
+/**
+ * The dialect-agnostic shape of a `job_schedules` row. Like {@link JobRow},
+ * timestamps are ISO-8601 strings on every dialect (lexicographic comparison
+ * is what `listDue` relies on). `nextRunAt` is `null` only when the schedule
+ * has no future occurrence (the claimer also disables it then).
+ */
+export interface ScheduleRow {
+    id: string;
+    /** Unique schedule identity — upserts key on it. */
+    name: string;
+    /** The `@JobHandler` name each occurrence enqueues. */
+    jobName: string;
+    payload: Record<string, unknown>;
+    /** Cron expression (croner syntax). */
+    cron: string;
+    /** IANA timezone; `null` means UTC. */
+    timezone: string | null;
+    enabled: boolean;
+    nextRunAt: string | null;
+    /** Occurrence enqueue overrides; `null` falls back to the store default. */
+    maxAttempts: number | null;
+    priority: number | null;
+    /**
+     * When set, every occurrence enqueues with this `uniqueKey` — so while one
+     * occurrence is still ACTIVE the next is a dedup no-op (the overlap guard),
+     * reusing the jobs uniqueKey contract verbatim.
+     */
+    uniqueKey: string | null;
+    lastEnqueuedAt: string | null;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a caller supplies to {@link JobSchedulesService.upsert}. */
+export interface UpsertScheduleInput<TPayload extends object = Record<string, unknown>> {
+    /** Unique schedule identity — upserting an existing name updates it. */
+    name: string;
+    /** The `@JobHandler` name each occurrence enqueues. */
+    jobName: string;
+    payload?: TPayload;
+    /** Cron expression (croner syntax); validated at call time — expressions with no future occurrence are rejected. */
+    cron: string;
+    /** IANA timezone (default UTC). */
+    timezone?: string;
+    /**
+     * OMITTING this is not the same as `true`: an omitted `enabled` defaults to
+     * true on INSERT but PRESERVES the stored value on update — so a boot-time
+     * upsert never resurrects a schedule that ops disabled at runtime with
+     * `setEnabled(name, false)`.
+     */
+    enabled?: boolean;
+    maxAttempts?: number;
+    priority?: number;
+    /** Occurrence dedup key — the overlap guard (see {@link ScheduleRow.uniqueKey}). */
+    uniqueKey?: string;
+}
+/** The fully-resolved row content the service hands `ScheduleStore.upsert`. */
+export interface ResolvedScheduleUpsert {
+    name: string;
+    jobName: string;
+    payload: Record<string, unknown>;
+    cron: string;
+    timezone: string | null;
+    /** `null` = the caller omitted it: default true on insert, PRESERVE the stored value on update. */
+    enabled: boolean | null;
+    /**
+     * The freshly-armed due time. On a conflict-update the store only applies
+     * it when `cron`/`timezone` changed or the stored `nextRunAt` is null —
+     * otherwise the stored due time is preserved, so a redeploy's boot upsert
+     * neither skips a pending catch-up nor perturbs the rhythm.
+     */
+    nextRunAt: string;
+    maxAttempts: number | null;
+    priority: number | null;
+    uniqueKey: string | null;
+}
+/** One due-schedule claim attempt (see {@link ScheduleStore.claimAndEnqueue}). */
+export interface ScheduleClaim {
+    id: string;
+    /** CAS guard: the `nextRunAt` this claimer read — the claim wins only if it is unchanged. */
+    expectedNextRunAt: string;
+    /** The new `nextRunAt`; `null` disables the schedule (no future occurrence). */
+    nextRunAt: string | null;
+    nowIso: string;
+    /** The occurrence to enqueue when the claim wins. */
+    input: EnqueueJobInput<object>;
+}
+export interface ScheduleClaimResult {
+    /** True when THIS claimer won the compare-and-swap (the row advanced). */
+    claimed: boolean;
+    /**
+     * The occurrence job inserted by THIS claim. `null` when the claim lost,
+     * or when the overlap guard suppressed the insert (an occurrence with the
+     * schedule's `(name, uniqueKey)` is still active) — in the latter case the
+     * schedule still advanced.
+     */
+    job: JobRow | null;
+}
+/**
+ * The transactional persistence seam for schedules — same design as
+ * {@link JobStore}: dialect-specific, owns its Drizzle table and transactions,
+ * `db` is opaque to the engine. `upsert` returns the store's native shape
+ * (synchronous on sqlite, a `Promise` on pg/mysql) so it composes inside the
+ * caller's `@Transactional` body.
+ *
+ * `claimAndEnqueue` is the exactly-once occurrence handoff: in ONE store
+ * transaction it (1) compare-and-swaps the row's `nextRunAt` from
+ * `expectedNextRunAt` to the new value (losing the race returns
+ * `{ claimed: false }` with nothing written) and (2) inserts the occurrence
+ * job conflict-tolerantly (a `(name, unique_key)` duplicate is the overlap
+ * guard, not an error — the schedule still advances).
+ */
+export interface ScheduleStore {
+    upsert(db: unknown, input: ResolvedScheduleUpsert): ScheduleRow | Promise<ScheduleRow>;
+    get(db: unknown, name: string): Promise<ScheduleRow | undefined>;
+    list(db: unknown): Promise<ScheduleRow[]>;
+    /** Resolves true when a row was deleted. */
+    remove(db: unknown, name: string): Promise<boolean>;
+    /**
+     * Flips `enabled` and overwrites `nextRunAt`; resolves the updated row, or
+     * undefined when the name is unknown OR `expectedUpdatedAt` was supplied
+     * and no longer matches (optimistic-concurrency guard — the caller re-reads
+     * and retries).
+     */
+    setEnabled(db: unknown, name: string, enabled: boolean, nextRunAt: string | null, expectedUpdatedAt?: string): Promise<ScheduleRow | undefined>;
+    /** Enabled rows with a non-null `nextRunAt <= nowIso`, oldest due first. */
+    listDue(db: unknown, nowIso: string, limit: number): Promise<ScheduleRow[]>;
+    claimAndEnqueue(db: unknown, claim: ScheduleClaim): Promise<ScheduleClaimResult>;
+    /** Disables a corrupted schedule (invalid cron found at claim time) recording `lastError`. */
+    disable(db: unknown, id: string, lastError: string): Promise<void>;
+}
 /** Options for {@link JobsModule.forRoot}. */
 export interface JobsModuleOptions {
     /**
@@ -114,6 +245,12 @@ export interface JobsModuleOptions {
     drizzleInstanceToken: symbol | string;
     /** The dialect-specific job store. */
     store: JobStore;
+    /**
+     * The dialect-specific schedule store. OPT-IN: without it the claimer never
+     * touches schedules and `JobSchedulesService` throws on use — 0.1 behavior
+     * is unchanged.
+     */
+    scheduleStore?: ScheduleStore;
     /**
      * Modules that provide (and export) the `drizzleInstanceToken`. Required when
      * that token is not registered by a global module — `JobsModule` imports

package/dist/job-schedules.service.d.ts

@@ -0,0 +1,44 @@
+import type { ScheduleRow, ScheduleStore, UpsertScheduleInput } from './interfaces';
+/**
+ * Injectable CRUD for DB-stored cron schedules — deliberately **no REST
+ * controller and no admin UI**: expose it from your own endpoints if you want
+ * runtime editing over HTTP.
+ *
+ * `upsert` returns the store's native shape (synchronous `ScheduleRow` on
+ * sqlite, a `Promise` on pg/mysql) and — like `JobsService.enqueue` — runs on
+ * the transaction-scoped Drizzle instance, so creating a schedule can ride the
+ * caller's business transaction.
+ *
+ * Upserts are safe to run on every boot (the documented pattern): on an
+ * existing schedule, an OMITTED `enabled` preserves the stored value (an ops
+ * `setEnabled(name, false)` survives redeploys), and the stored `nextRunAt`
+ * is preserved while `cron`/`timezone` are unchanged (a pending catch-up
+ * survives restarts).
+ *
+ * Cron expressions are validated (croner) at call time; invalid ones — and
+ * expressions with no future occurrence at all — throw `InvalidScheduleError`
+ * and never reach the table. The misfire policy is fixed: arming always
+ * computes from *now*, so `setEnabled(name, true)` on a long-disabled
+ * schedule resumes at the next FUTURE occurrence instead of bursting.
+ */
+export declare class JobSchedulesService<TStore extends ScheduleStore = ScheduleStore> {
+    private readonly db;
+    private readonly store;
+    constructor(db: unknown, store?: TStore | null);
+    upsert<TPayload extends object>(input: UpsertScheduleInput<TPayload>): ReturnType<TStore['upsert']>;
+    get(name: string): Promise<ScheduleRow | undefined>;
+    list(): Promise<ScheduleRow[]>;
+    /** Resolves true when the schedule existed and was deleted. */
+    remove(name: string): Promise<boolean>;
+    /**
+     * Enables or disables a schedule. Enabling re-arms `nextRunAt` from now
+     * (skip-missed policy — no catch-up burst); disabling clears it. Resolves
+     * the updated row, or undefined when the name is unknown.
+     *
+     * The enable path is a read-compute-write guarded by the row's `updatedAt`
+     * (so a concurrent upsert changing the cron cannot be overwritten with a
+     * stale computation) and retried a few times; persistent contention throws.
+     */
+    setEnabled(name: string, enabled: boolean): Promise<ScheduleRow | undefined>;
+    private requireStore;
+}

package/dist/job-schedules.service.js

@@ -0,0 +1,125 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobSchedulesService = void 0;
+const common_1 = require("@nestjs/common");
+const transactional_1 = require("@nestjs-cls/transactional");
+const schedule_planner_1 = require("./schedule-planner");
+const tokens_1 = require("./tokens");
+/**
+ * Injectable CRUD for DB-stored cron schedules — deliberately **no REST
+ * controller and no admin UI**: expose it from your own endpoints if you want
+ * runtime editing over HTTP.
+ *
+ * `upsert` returns the store's native shape (synchronous `ScheduleRow` on
+ * sqlite, a `Promise` on pg/mysql) and — like `JobsService.enqueue` — runs on
+ * the transaction-scoped Drizzle instance, so creating a schedule can ride the
+ * caller's business transaction.
+ *
+ * Upserts are safe to run on every boot (the documented pattern): on an
+ * existing schedule, an OMITTED `enabled` preserves the stored value (an ops
+ * `setEnabled(name, false)` survives redeploys), and the stored `nextRunAt`
+ * is preserved while `cron`/`timezone` are unchanged (a pending catch-up
+ * survives restarts).
+ *
+ * Cron expressions are validated (croner) at call time; invalid ones — and
+ * expressions with no future occurrence at all — throw `InvalidScheduleError`
+ * and never reach the table. The misfire policy is fixed: arming always
+ * computes from *now*, so `setEnabled(name, true)` on a long-disabled
+ * schedule resumes at the next FUTURE occurrence instead of bursting.
+ */
+let JobSchedulesService = class JobSchedulesService {
+    constructor(db, store = null) {
+        this.db = db;
+        this.store = store;
+    }
+    upsert(input) {
+        const store = this.requireStore();
+        const timezone = input.timezone ?? null;
+        const resolved = {
+            name: input.name,
+            jobName: input.jobName,
+            // The one place the structural payload widens to the stored shape.
+            payload: (input.payload ?? {}),
+            cron: input.cron,
+            timezone,
+            // null = omitted: the store defaults it to true on insert and
+            // preserves the stored value on update.
+            enabled: input.enabled ?? null,
+            // Validates the expression AND rejects never-firing ones.
+            nextRunAt: (0, schedule_planner_1.armSchedule)(input.cron, timezone, new Date()),
+            maxAttempts: input.maxAttempts ?? null,
+            priority: input.priority ?? null,
+            uniqueKey: input.uniqueKey ?? null,
+        };
+        return store.upsert(this.db, resolved);
+    }
+    async get(name) {
+        return this.requireStore().get(this.db, name);
+    }
+    async list() {
+        return this.requireStore().list(this.db);
+    }
+    /** Resolves true when the schedule existed and was deleted. */
+    async remove(name) {
+        return this.requireStore().remove(this.db, name);
+    }
+    /**
+     * Enables or disables a schedule. Enabling re-arms `nextRunAt` from now
+     * (skip-missed policy — no catch-up burst); disabling clears it. Resolves
+     * the updated row, or undefined when the name is unknown.
+     *
+     * The enable path is a read-compute-write guarded by the row's `updatedAt`
+     * (so a concurrent upsert changing the cron cannot be overwritten with a
+     * stale computation) and retried a few times; persistent contention throws.
+     */
+    async setEnabled(name, enabled) {
+        const store = this.requireStore();
+        if (!enabled) {
+            return store.setEnabled(this.db, name, false, null);
+        }
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const row = await store.get(this.db, name);
+            if (!row) {
+                return undefined;
+            }
+            // The row may have been hand-edited behind the service's back — arming
+            // validates (and rejects never-firing expressions) before enabling.
+            const next = (0, schedule_planner_1.armSchedule)(row.cron, row.timezone, new Date());
+            const updated = await store.setEnabled(this.db, name, true, next, row.updatedAt);
+            if (updated) {
+                return updated;
+            }
+            // Guard miss: someone modified the row between our read and write —
+            // re-read and recompute from the fresh cron/timezone.
+        }
+        throw new Error(`Schedule "${name}" is being modified concurrently — retry setEnabled.`);
+    }
+    requireStore() {
+        if (!this.store) {
+            throw new Error('JobsModule was configured without a scheduleStore — pass one ' +
+                '(e.g. new SqliteScheduleStore()) to JobsModule.forRoot to use schedules.');
+        }
+        return this.store;
+    }
+};
+exports.JobSchedulesService = JobSchedulesService;
+exports.JobSchedulesService = JobSchedulesService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, transactional_1.InjectTransaction)()),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_1.JOBS_SCHEDULE_STORE)),
+    __metadata("design:paramtypes", [Object, Object])
+], JobSchedulesService);
+//# sourceMappingURL=job-schedules.service.js.map

package/dist/job-schedules.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-schedules.service.js","sourceRoot":"","sources":["../job-schedules.service.ts"],"names":[],"mappings":"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"}

package/dist/jobs-claimer.service.d.ts

@@ -1,7 +1,9 @@
-import type { JobStore, ResolvedRunnerConfig, RunnerConfig } from './interfaces';
+import type { JobStore, ResolvedRunnerConfig, RunnerConfig, ScheduleStore } from './interfaces';
 import { JobsHandlerExplorer } from './jobs-handler.explorer';
 export declare const DEFAULT_RUNNER_CONFIG: ResolvedRunnerConfig;
 export interface TickReport {
+    /** Schedule occurrences THIS tick enqueued (won claims; dedup-suppressed occurrences still count as claimed). */
+    scheduled: number;
     claimed: number;
     completed: number;
     retried: number;
@@ -27,9 +29,21 @@ export declare class JobsClaimer {
     private readonly db;
     private readonly store;
     private readonly explorer;
+    private readonly scheduleStore;
     private readonly logger;
-    constructor(db: unknown, store: JobStore, explorer: JobsHandlerExplorer);
+    constructor(db: unknown, store: JobStore, explorer: JobsHandlerExplorer, scheduleStore?: ScheduleStore | null);
     tick(overrides?: RunnerConfig): Promise<TickReport>;
+    /**
+     * Fires every due schedule at most once. Per schedule: compute the next
+     * occurrence strictly after *now* (skip-missed policy — a schedule that was
+     * down for a week gets at most this one catch-up), then let the store
+     * compare-and-swap `nextRunAt` and insert the occurrence in ONE transaction.
+     * A lost CAS means another instance fired it — not an error, not counted.
+     * A schedule whose cron cannot be evaluated (hand-corrupted row) is disabled
+     * with the error recorded, and the loop continues.
+     */
+    private drainSchedules;
+    private fireSchedule;
     private processOne;
     private onHandlerError;
     private fail;

package/dist/jobs-claimer.service.js

@@ -18,6 +18,7 @@ const node_os_1 = require("node:os");
 const common_1 = require("@nestjs/common");
 const errors_1 = require("./errors");
 const jobs_handler_explorer_1 = require("./jobs-handler.explorer");
+const schedule_planner_1 = require("./schedule-planner");
 const tokens_1 = require("./tokens");
 exports.DEFAULT_RUNNER_CONFIG = {
     workerInstanceId: `${(0, node_os_1.hostname)()}-${process.pid}`,
@@ -43,16 +44,21 @@ exports.DEFAULT_RUNNER_CONFIG = {
  * transaction — so it freely awaits the store and the handlers.
  */
 let JobsClaimer = JobsClaimer_1 = class JobsClaimer {
-    constructor(db, store, explorer) {
+    constructor(db, store, explorer, scheduleStore = null) {
         this.db = db;
         this.store = store;
         this.explorer = explorer;
+        this.scheduleStore = scheduleStore;
         this.logger = new common_1.Logger(JobsClaimer_1.name);
     }
     async tick(overrides = {}) {
         const cfg = { ...exports.DEFAULT_RUNNER_CONFIG, ...overrides };
+        // Due schedules fire first, so their occurrences (due immediately) are
+        // claimable by this very tick's batch claim.
+        const scheduled = this.scheduleStore ? await this.drainSchedules(cfg) : 0;
         const claimed = await this.store.claimBatch(this.db, cfg);
         const report = {
+            scheduled,
             claimed: claimed.length,
             completed: 0,
             retried: 0,
@@ -64,6 +70,57 @@ let JobsClaimer = JobsClaimer_1 = class JobsClaimer {
         }
         return report;
     }
+    /**
+     * Fires every due schedule at most once. Per schedule: compute the next
+     * occurrence strictly after *now* (skip-missed policy — a schedule that was
+     * down for a week gets at most this one catch-up), then let the store
+     * compare-and-swap `nextRunAt` and insert the occurrence in ONE transaction.
+     * A lost CAS means another instance fired it — not an error, not counted.
+     * A schedule whose cron cannot be evaluated (hand-corrupted row) is disabled
+     * with the error recorded, and the loop continues.
+     */
+    async drainSchedules(cfg) {
+        const now = new Date();
+        const due = await this.scheduleStore.listDue(this.db, now.toISOString(), cfg.batchSize);
+        let scheduled = 0;
+        for (const schedule of due) {
+            scheduled += await this.fireSchedule(schedule, now);
+        }
+        return scheduled;
+    }
+    async fireSchedule(schedule, now) {
+        let nextRunAt;
+        try {
+            nextRunAt = (0, schedule_planner_1.nextOccurrence)(schedule.cron, schedule.timezone, now);
+        }
+        catch (error) {
+            // Only InvalidScheduleError (an Error subclass) escapes nextOccurrence —
+            // the hand-corrupted row case. THAT alone disables a schedule.
+            const message = error.message;
+            this.logger.warn(`schedule ${schedule.id} ("${schedule.name}") disabled: ${message}`);
+            await this.scheduleStore.disable(this.db, schedule.id, message);
+            return 0;
+        }
+        try {
+            const result = await this.scheduleStore.claimAndEnqueue(this.db, {
+                id: schedule.id,
+                // listDue only returns rows with a non-null nextRunAt.
+                expectedNextRunAt: schedule.nextRunAt,
+                nextRunAt,
+                nowIso: now.toISOString(),
+                input: occurrenceInput(schedule),
+            });
+            return result.claimed ? 1 : 0;
+        }
+        catch (error) {
+            // A transient store error (connection drop, lock timeout, serialization
+            // failure) must NOT kill the schedule: nothing was written, the row is
+            // still due, and the next tick retries it naturally.
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`schedule ${schedule.id} ("${schedule.name}") claim failed, will retry next tick: ${message}`);
+            return 0;
+        }
+    }
     async processOne(job, cfg) {
         try {
             const handler = this.explorer.get(job.name);
@@ -116,6 +173,18 @@ exports.JobsClaimer = JobsClaimer = JobsClaimer_1 = __decorate([
     (0, common_1.Injectable)(),
     __param(0, (0, common_1.Inject)(tokens_1.JOBS_DRIZZLE)),
     __param(1, (0, common_1.Inject)(tokens_1.JOBS_STORE)),
-    __metadata("design:paramtypes", [Object, Object, jobs_handler_explorer_1.JobsHandlerExplorer])
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(tokens_1.JOBS_SCHEDULE_STORE)),
+    __metadata("design:paramtypes", [Object, Object, jobs_handler_explorer_1.JobsHandlerExplorer, Object])
 ], JobsClaimer);
+/** The occurrence a schedule enqueues: due immediately, overrides only when set. */
+function occurrenceInput(schedule) {
+    return {
+        name: schedule.jobName,
+        payload: schedule.payload,
+        ...(schedule.maxAttempts !== null && { maxAttempts: schedule.maxAttempts }),
+        ...(schedule.priority !== null && { priority: schedule.priority }),
+        ...(schedule.uniqueKey !== null && { uniqueKey: schedule.uniqueKey }),
+    };
+}
 //# sourceMappingURL=jobs-claimer.service.js.map

package/dist/jobs-claimer.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"jobs-claimer.service.js","sourceRoot":"","sources":["../jobs-claimer.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jobs-claimer.service.js","sourceRoot":"","sources":["../jobs-claimer.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qCAAmC;AACnC,2CAAsE;AACtE,qCAA0D;AAU1D,mEAA8D;AAC9D,yDAAoD;AACpD,qCAAyE;AAE5D,QAAA,qBAAqB,GAAyB;IACzD,gBAAgB,EAAE,GAAG,IAAA,kBAAQ,GAAE,IAAI,OAAO,CAAC,GAAG,EAAE;IAChD,cAAc,EAAE,MAAM;IACtB,SAAS,EAAE,EAAE;IACb,aAAa,EAAE,KAAK;IACpB,YAAY,EAAE,MAAM;CACrB,CAAC;AAaF;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,WAAW,mBAAjB,MAAM,WAAW;IAGtB,YACwB,EAA4B,EAC9B,KAAgC,EACnC,QAA6B,EAG9C,gBAAuD,IAAI;QALpB,OAAE,GAAF,EAAE,CAAS;QACb,UAAK,GAAL,KAAK,CAAU;QACnC,aAAQ,GAAR,QAAQ,CAAqB;QAG7B,kBAAa,GAAb,aAAa,CAA6B;QAR5C,WAAM,GAAG,IAAI,eAAM,CAAC,aAAW,CAAC,IAAI,CAAC,CAAC;IASpD,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,YAA0B,EAAE;QACrC,MAAM,GAAG,GAAG,EAAE,GAAG,6BAAqB,EAAE,GAAG,SAAS,EAAE,CAAC;QACvD,uEAAuE;QACvE,6CAA6C;QAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1D,MAAM,MAAM,GAAe;YACzB,SAAS;YACT,OAAO,EAAE,OAAO,CAAC,MAAM;YACvB,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,CAAC;SACV,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAChD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,cAAc,CAAC,GAAyB;QACpD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,aAAc,CAAC,OAAO,CAC3C,IAAI,CAAC,EAAE,EACP,GAAG,CAAC,WAAW,EAAE,EACjB,GAAG,CAAC,SAAS,CACd,CAAC;QACF,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC3B,SAAS,IAAI,MAAM,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,QAAqB,EAAE,GAAS;QACzD,IAAI,SAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,SAAS,GAAG,IAAA,iCAAc,EAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yEAAyE;YACzE,+DAA+D;YAC/D,MAAM,OAAO,GAAI,KAAe,CAAC,OAAO,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,YAAY,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,IAAI,gBAAgB,OAAO,EAAE,CACpE,CAAC;YACF,MAAM,IAAI,CAAC,aAAc,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YACjE,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAc,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,EAAE;gBAChE,EAAE,EAAE,QAAQ,CAAC,EAAE;gBACf,uDAAuD;gBACvD,iBAAiB,EAAE,QAAQ,CAAC,SAAmB;gBAC/C,SAAS;gBACT,MAAM,EAAE,GAAG,CAAC,WAAW,EAAE;gBACzB,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC;aACjC,CAAC,CAAC;YACH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,wEAAwE;YACxE,uEAAuE;YACvE,qDAAqD;YACrD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,YAAY,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,IAAI,0CAA0C,OAAO,EAAE,CAC9F,CAAC;YACF,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,UAAU,CACtB,GAAW,EACX,GAAyB;QAEzB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,uBAAc,CACtB,sCAAsC,GAAG,CAAC,IAAI,GAAG,CAClD,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE;gBAChC,KAAK,EAAE,GAAG,CAAC,EAAE;gBACb,OAAO,EAAE,GAAG,CAAC,QAAQ,GAAG,CAAC;aAC1B,CAAC,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAChD,OAAO,WAAW,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,cAAc,CAC1B,GAAW,EACX,GAAyB,EACzB,KAAc;QAEd,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,gFAAgF;QAChF,IAAI,KAAK,YAAY,uBAAc,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,2EAA2E;QAC3E,IAAI,KAAK,YAAY,uBAAc,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC/D,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACxD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,kEAAkE;QAClE,IAAI,GAAG,CAAC,QAAQ,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CACpB,IAAI,CAAC,EAAE,EACP,GAAG,CAAC,EAAE,EACN,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC/B,OAAO,CACR,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,MAAc;QAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,cAAc,MAAM,EAAE,CAAC,CAAC;QACpE,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,OAAO,CAAC,QAAgB,EAAE,GAAyB;QACzD,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,GAAG,CAAC,IAAI,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAChD,OAAO,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IAChE,CAAC;CACF,CAAA;AAzJY,kCAAW;sBAAX,WAAW;IADvB,IAAA,mBAAU,GAAE;IAKR,WAAA,IAAA,eAAM,EAAC,qBAAY,CAAC,CAAA;IACpB,WAAA,IAAA,eAAM,EAAC,mBAAU,CAAC,CAAA;IAElB,WAAA,IAAA,iBAAQ,GAAE,CAAA;IACV,WAAA,IAAA,eAAM,EAAC,4BAAmB,CAAC,CAAA;qDAFD,2CAAmB;GANrC,WAAW,CAyJvB;AAED,oFAAoF;AACpF,SAAS,eAAe,CAAC,QAAqB;IAC5C,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,OAAO;QACtB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,GAAG,CAAC,QAAQ,CAAC,WAAW,KAAK,IAAI,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC3E,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,IAAI,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,IAAI,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;KACtE,CAAC;AACJ,CAAC"}

package/dist/jobs.module.d.ts

@@ -1,5 +1,5 @@
 import { type DynamicModule, type InjectionToken, type ModuleMetadata, type OptionalFactoryDependency } from '@nestjs/common';
-import type { JobsModuleOptions, JobStore } from './interfaces';
+import type { JobsModuleOptions, JobStore, ScheduleStore } from './interfaces';
 /**
  * Async configuration. The Drizzle token is static (a DI token is known at
  * module-definition time); the store is built by a factory so it can inject
@@ -12,6 +12,8 @@ export interface JobsModuleAsyncOptions {
     imports?: ModuleMetadata['imports'];
     inject?: (InjectionToken | OptionalFactoryDependency)[];
     useStore: (...args: any[]) => JobStore | Promise<JobStore>;
+    /** Optional schedules opt-in; shares `inject` with `useStore`. */
+    useScheduleStore?: (...args: any[]) => ScheduleStore | Promise<ScheduleStore>;
 }
 export declare class JobsModule {
     static forRoot(options: JobsModuleOptions): DynamicModule;

package/dist/jobs.module.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.JobsModule = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
+const job_schedules_service_1 = require("./job-schedules.service");
 const jobs_claimer_service_1 = require("./jobs-claimer.service");
 const jobs_handler_explorer_1 = require("./jobs-handler.explorer");
 const jobs_service_1 = require("./jobs.service");
@@ -18,6 +19,7 @@ let JobsModule = class JobsModule {
         return assemble(options.isGlobal ?? true, options.imports ?? [], [
             { provide: tokens_1.JOBS_OPTIONS, useValue: options },
             { provide: tokens_1.JOBS_STORE, useValue: options.store },
+            { provide: tokens_1.JOBS_SCHEDULE_STORE, useValue: options.scheduleStore ?? null },
             { provide: tokens_1.JOBS_DRIZZLE, useExisting: options.drizzleInstanceToken },
         ]);
     }
@@ -28,6 +30,13 @@ let JobsModule = class JobsModule {
                 useFactory: options.useStore,
                 inject: options.inject ?? [],
             },
+            options.useScheduleStore
+                ? {
+                    provide: tokens_1.JOBS_SCHEDULE_STORE,
+                    useFactory: options.useScheduleStore,
+                    inject: options.inject ?? [],
+                }
+                : { provide: tokens_1.JOBS_SCHEDULE_STORE, useValue: null },
             { provide: tokens_1.JOBS_DRIZZLE, useExisting: options.drizzleInstanceToken },
         ]);
     }
@@ -42,8 +51,14 @@ function assemble(global, imports, base) {
         global,
         // DiscoveryModule powers the @JobHandler scan at bootstrap.
         imports: [core_1.DiscoveryModule, ...imports],
-        providers: [...base, jobs_service_1.JobsService, jobs_claimer_service_1.JobsClaimer, jobs_handler_explorer_1.JobsHandlerExplorer],
-        exports: [jobs_service_1.JobsService, jobs_claimer_service_1.JobsClaimer, jobs_handler_explorer_1.JobsHandlerExplorer],
+        providers: [
+            ...base,
+            jobs_service_1.JobsService,
+            job_schedules_service_1.JobSchedulesService,
+            jobs_claimer_service_1.JobsClaimer,
+            jobs_handler_explorer_1.JobsHandlerExplorer,
+        ],
+        exports: [jobs_service_1.JobsService, job_schedules_service_1.JobSchedulesService, jobs_claimer_service_1.JobsClaimer, jobs_handler_explorer_1.JobsHandlerExplorer],
     };
 }
 //# sourceMappingURL=jobs.module.js.map

package/dist/jobs.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"jobs.module.js","sourceRoot":"","sources":["../jobs.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAOwB;AACxB,uCAA+C;AAE/C,iEAAqD;AACrD,mEAA8D;AAC9D,iDAA6C;AAC7C,qCAAkE;AAoB3D,IAAM,UAAU,GAAhB,MAAM,UAAU;IACrB,MAAM,CAAC,OAAO,CAAC,OAA0B;QACvC,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE;YAC/D,EAAE,OAAO,EAAE,qBAAY,EAAE,QAAQ,EAAE,OAAO,EAAE;YAC5C,EAAE,OAAO,EAAE,mBAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE;YAChD,EAAE,OAAO,EAAE,qBAAY,EAAE,WAAW,EAAE,OAAO,CAAC,oBAAoB,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAA+B;QACjD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE;YAC/D;gBACE,OAAO,EAAE,mBAAU;gBACnB,UAAU,EAAE,OAAO,CAAC,QAAQ;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;aAC7B;YACD,EAAE,OAAO,EAAE,qBAAY,EAAE,WAAW,EAAE,OAAO,CAAC,oBAAoB,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAnBY,gCAAU;qBAAV,UAAU;IADtB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,UAAU,CAmBtB;AAED,SAAS,QAAQ,CACf,MAAe,EACf,OAA+C,EAC/C,IAAgB;IAEhB,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,MAAM;QACN,4DAA4D;QAC5D,OAAO,EAAE,CAAC,sBAAe,EAAE,GAAG,OAAO,CAAC;QACtC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,0BAAW,EAAE,kCAAW,EAAE,2CAAmB,CAAC;QACnE,OAAO,EAAE,CAAC,0BAAW,EAAE,kCAAW,EAAE,2CAAmB,CAAC;KACzD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"jobs.module.js","sourceRoot":"","sources":["../jobs.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAOwB;AACxB,uCAA+C;AAE/C,mEAA8D;AAC9D,iEAAqD;AACrD,mEAA8D;AAC9D,iDAA6C;AAC7C,qCAKkB;AAsBX,IAAM,UAAU,GAAhB,MAAM,UAAU;IACrB,MAAM,CAAC,OAAO,CAAC,OAA0B;QACvC,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE;YAC/D,EAAE,OAAO,EAAE,qBAAY,EAAE,QAAQ,EAAE,OAAO,EAAE;YAC5C,EAAE,OAAO,EAAE,mBAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE;YAChD,EAAE,OAAO,EAAE,4BAAmB,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI,EAAE;YACzE,EAAE,OAAO,EAAE,qBAAY,EAAE,WAAW,EAAE,OAAO,CAAC,oBAAoB,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAA+B;QACjD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE;YAC/D;gBACE,OAAO,EAAE,mBAAU;gBACnB,UAAU,EAAE,OAAO,CAAC,QAAQ;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;aAC7B;YACD,OAAO,CAAC,gBAAgB;gBACtB,CAAC,CAAC;oBACE,OAAO,EAAE,4BAAmB;oBAC5B,UAAU,EAAE,OAAO,CAAC,gBAAgB;oBACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;iBAC7B;gBACH,CAAC,CAAC,EAAE,OAAO,EAAE,4BAAmB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACpD,EAAE,OAAO,EAAE,qBAAY,EAAE,WAAW,EAAE,OAAO,CAAC,oBAAoB,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA3BY,gCAAU;qBAAV,UAAU;IADtB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,UAAU,CA2BtB;AAED,SAAS,QAAQ,CACf,MAAe,EACf,OAA+C,EAC/C,IAAgB;IAEhB,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,MAAM;QACN,4DAA4D;QAC5D,OAAO,EAAE,CAAC,sBAAe,EAAE,GAAG,OAAO,CAAC;QACtC,SAAS,EAAE;YACT,GAAG,IAAI;YACP,0BAAW;YACX,2CAAmB;YACnB,kCAAW;YACX,2CAAmB;SACpB;QACD,OAAO,EAAE,CAAC,0BAAW,EAAE,2CAAmB,EAAE,kCAAW,EAAE,2CAAmB,CAAC;KAC9E,CAAC;AACJ,CAAC"}

package/dist/schedule-planner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one place cron math happens. Parsing, next-occurrence computation,
+ * timezones, and DST semantics are all delegated to `croner` (the package's
+ * single runtime dependency) — hand-rolling cron is forbidden by the
+ * guidelines. The default timezone is **UTC**, not server-local, so a
+ * schedule means the same thing on every instance.
+ */
+/**
+ * The next occurrence STRICTLY AFTER `after`, as an ISO-8601 string, or
+ * `null` when the expression has no future occurrence. Used by the claimer,
+ * where `null` means the schedule just fired for the last time and disables
+ * itself.
+ *
+ * Always advancing from *now* — never from the previously stored due time —
+ * is the misfire policy: missed occurrences are skipped, and a schedule that
+ * was down for a week fires at most one catch-up.
+ *
+ * Throws {@link InvalidScheduleError} when the expression (or timezone)
+ * cannot be evaluated. Croner reports a bad pattern at construction but a bad
+ * timezone only when computing a run, so both surface here.
+ */
+export declare function nextOccurrence(cron: string, timezone: string | null, after: Date): string | null;
+/**
+ * Like {@link nextOccurrence}, but for ARMING a schedule (upsert /
+ * `setEnabled(true)`): an expression with no future occurrence at all (e.g.
+ * `0 0 30 2 *` — February 30th never comes) is rejected with
+ * {@link InvalidScheduleError} instead of creating a schedule that can never
+ * fire.
+ */
+export declare function armSchedule(cron: string, timezone: string | null, after: Date): string;

package/dist/schedule-planner.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextOccurrence = nextOccurrence;
+exports.armSchedule = armSchedule;
+const croner_1 = require("croner");
+const errors_1 = require("./errors");
+/**
+ * The one place cron math happens. Parsing, next-occurrence computation,
+ * timezones, and DST semantics are all delegated to `croner` (the package's
+ * single runtime dependency) — hand-rolling cron is forbidden by the
+ * guidelines. The default timezone is **UTC**, not server-local, so a
+ * schedule means the same thing on every instance.
+ */
+/**
+ * The next occurrence STRICTLY AFTER `after`, as an ISO-8601 string, or
+ * `null` when the expression has no future occurrence. Used by the claimer,
+ * where `null` means the schedule just fired for the last time and disables
+ * itself.
+ *
+ * Always advancing from *now* — never from the previously stored due time —
+ * is the misfire policy: missed occurrences are skipped, and a schedule that
+ * was down for a week fires at most one catch-up.
+ *
+ * Throws {@link InvalidScheduleError} when the expression (or timezone)
+ * cannot be evaluated. Croner reports a bad pattern at construction but a bad
+ * timezone only when computing a run, so both surface here.
+ */
+function nextOccurrence(cron, timezone, after) {
+    const parsed = wrap(cron, timezone, () => new croner_1.Cron(cron, { timezone: timezone ?? 'UTC' }));
+    return wrap(cron, timezone, () => parsed.nextRun(after)?.toISOString() ?? null);
+}
+/**
+ * Like {@link nextOccurrence}, but for ARMING a schedule (upsert /
+ * `setEnabled(true)`): an expression with no future occurrence at all (e.g.
+ * `0 0 30 2 *` — February 30th never comes) is rejected with
+ * {@link InvalidScheduleError} instead of creating a schedule that can never
+ * fire.
+ */
+function armSchedule(cron, timezone, after) {
+    const next = nextOccurrence(cron, timezone, after);
+    if (next === null) {
+        throw new errors_1.InvalidScheduleError(`Invalid cron schedule "${cron}"${tzSuffix(timezone)}: it has no future occurrence`);
+    }
+    return next;
+}
+function wrap(cron, timezone, run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        // Croner throws Error subclasses (TypeError for bad patterns/timezones).
+        throw new errors_1.InvalidScheduleError(`Invalid cron schedule "${cron}"${tzSuffix(timezone)}: ${error.message}`);
+    }
+}
+function tzSuffix(timezone) {
+    return timezone ? ` (timezone "${timezone}")` : '';
+}
+//# sourceMappingURL=schedule-planner.js.map