@nest-native/jobs 0.1.0 → 0.2.0

package/dist/dialects/sqlite/schedule-store.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteScheduleStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const drizzle_orm_1 = require("drizzle-orm");
+const schema_1 = require("./schema");
+/**
+ * SQLite (better-sqlite3) schedule store. Like {@link SqliteJobStore}, every
+ * method runs **synchronously** — `upsert` returns the row directly so it
+ * composes inside a synchronous `@Transactional` body; the rest wrap their
+ * synchronous result in a resolved Promise.
+ *
+ * `claimAndEnqueue` runs the compare-and-swap on `next_run_at` and the
+ * occurrence insert in ONE synchronous transaction. The insert uses
+ * `ON CONFLICT DO NOTHING` on `(name, unique_key)` so an active occurrence
+ * with the schedule's `uniqueKey` suppresses the new one (the overlap guard)
+ * without poisoning the transaction — the schedule row still advances.
+ */
+class SqliteScheduleStore {
+    upsert(db, input) {
+        const nowIso = new Date().toISOString();
+        return db
+            .insert(schema_1.jobSchedules)
+            .values({
+            id: (0, node_crypto_1.randomUUID)(),
+            ...input,
+            enabled: input.enabled ?? true,
+            lastEnqueuedAt: null,
+            lastError: null,
+            createdAt: nowIso,
+            updatedAt: nowIso,
+        })
+            .onConflictDoUpdate({
+            target: schema_1.jobSchedules.name,
+            // Updates keep id / createdAt / lastEnqueuedAt; a successful upsert
+            // clears any stale claim-time error. Two deliberate preservations
+            // make boot-time upserts safe: an omitted `enabled` (null) keeps the
+            // stored flag (ops kill switches survive redeploys), and the stored
+            // `next_run_at` survives while cron/timezone are unchanged (a pending
+            // catch-up is not skipped; the rhythm is not perturbed). `IS` is
+            // SQLite's null-safe equality.
+            set: {
+                nextRunAt: (0, drizzle_orm_1.sql) `CASE WHEN ${schema_1.jobSchedules.cron} = excluded.cron AND ${schema_1.jobSchedules.timezone} IS excluded.timezone AND ${schema_1.jobSchedules.nextRunAt} IS NOT NULL THEN ${schema_1.jobSchedules.nextRunAt} ELSE excluded.next_run_at END`,
+                jobName: input.jobName,
+                payload: input.payload,
+                cron: input.cron,
+                timezone: input.timezone,
+                maxAttempts: input.maxAttempts,
+                priority: input.priority,
+                uniqueKey: input.uniqueKey,
+                lastError: null,
+                updatedAt: nowIso,
+                ...(input.enabled !== null && { enabled: input.enabled }),
+            },
+        })
+            .returning()
+            .get();
+    }
+    get(db, name) {
+        const row = db
+            .select()
+            .from(schema_1.jobSchedules)
+            .where((0, drizzle_orm_1.eq)(schema_1.jobSchedules.name, name))
+            .get();
+        return Promise.resolve(row);
+    }
+    list(db) {
+        return Promise.resolve(db
+            .select()
+            .from(schema_1.jobSchedules)
+            .orderBy((0, drizzle_orm_1.asc)(schema_1.jobSchedules.name))
+            .all());
+    }
+    remove(db, name) {
+        const result = db
+            .delete(schema_1.jobSchedules)
+            .where((0, drizzle_orm_1.eq)(schema_1.jobSchedules.name, name))
+            .run();
+        return Promise.resolve(result.changes > 0);
+    }
+    setEnabled(db, name, enabled, nextRunAt, expectedUpdatedAt) {
+        const rows = db
+            .update(schema_1.jobSchedules)
+            .set({ enabled, nextRunAt, updatedAt: new Date().toISOString() })
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobSchedules.name, name), 
+        // Optimistic guard: only write over the row version the caller read.
+        ...(expectedUpdatedAt === undefined
+            ? []
+            : [(0, drizzle_orm_1.eq)(schema_1.jobSchedules.updatedAt, expectedUpdatedAt)])))
+            .returning()
+            .all();
+        return Promise.resolve(rows[0]);
+    }
+    listDue(db, nowIso, limit) {
+        return Promise.resolve(db
+            .select()
+            .from(schema_1.jobSchedules)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobSchedules.enabled, true), (0, drizzle_orm_1.isNotNull)(schema_1.jobSchedules.nextRunAt), (0, drizzle_orm_1.lte)(schema_1.jobSchedules.nextRunAt, nowIso)))
+            .orderBy((0, drizzle_orm_1.asc)(schema_1.jobSchedules.nextRunAt))
+            .limit(limit)
+            .all());
+    }
+    claimAndEnqueue(db, claim) {
+        const result = db.transaction((tx) => {
+            const cas = tx
+                .update(schema_1.jobSchedules)
+                .set({
+                nextRunAt: claim.nextRunAt,
+                // A schedule with no future occurrence disables itself.
+                enabled: claim.nextRunAt !== null,
+                lastEnqueuedAt: claim.nowIso,
+                lastError: null,
+                updatedAt: claim.nowIso,
+            })
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobSchedules.id, claim.id), (0, drizzle_orm_1.eq)(schema_1.jobSchedules.nextRunAt, claim.expectedNextRunAt), (0, drizzle_orm_1.eq)(schema_1.jobSchedules.enabled, true)))
+                .run();
+            if (cas.changes === 0) {
+                return { claimed: false, job: null };
+            }
+            const inserted = tx
+                .insert(schema_1.jobs)
+                .values({
+                id: (0, node_crypto_1.randomUUID)(),
+                name: claim.input.name,
+                payload: claim.input.payload,
+                status: 'pending',
+                maxAttempts: claim.input.maxAttempts ?? 10,
+                uniqueKey: claim.input.uniqueKey ?? null,
+                priority: claim.input.priority ?? 0,
+                availableAt: claim.nowIso,
+                createdAt: claim.nowIso,
+            })
+                .onConflictDoNothing({ target: [schema_1.jobs.name, schema_1.jobs.uniqueKey] })
+                .returning()
+                .all();
+            // An empty RETURNING means the overlap guard suppressed the insert (an
+            // occurrence with this (name, unique_key) is still active) — the
+            // schedule still advanced; there is just no new job.
+            return { claimed: true, job: inserted.length > 0 ? inserted[0] : null };
+        });
+        return Promise.resolve(result);
+    }
+    disable(db, id, lastError) {
+        db
+            .update(schema_1.jobSchedules)
+            .set({ enabled: false, lastError, updatedAt: new Date().toISOString() })
+            .where((0, drizzle_orm_1.eq)(schema_1.jobSchedules.id, id))
+            .run();
+        return Promise.resolve();
+    }
+}
+exports.SqliteScheduleStore = SqliteScheduleStore;
+//# sourceMappingURL=schedule-store.js.map

package/dist/dialects/sqlite/schedule-store.js.map

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

package/dist/dialects/sqlite/schema.d.ts

@@ -277,3 +277,298 @@ export declare const jobs: import("drizzle-orm/sqlite-core").SQLiteTableWithColu
     };
     dialect: "sqlite";
 }>;
+/**
+ * SQLite `job_schedules` table. Add it to your Drizzle schema (alongside
+ * `jobs`) and generate a migration with drizzle-kit — only needed when you
+ * opt in to schedules.
+ *
+ * `name` is the unique schedule identity (upserts key on it); the
+ * `(enabled, next_run_at)` index serves the claimer's due query. Timestamps
+ * are ISO-8601 strings, like every timestamp in this package.
+ */
+export declare const jobSchedules: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "job_schedules";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "name";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        jobName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "job_name";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        payload: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload";
+            tableName: "job_schedules";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: Record<string, unknown>;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        cron: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "cron";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        timezone: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timezone";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        enabled: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "enabled";
+            tableName: "job_schedules";
+            dataType: "boolean";
+            columnType: "SQLiteBoolean";
+            data: boolean;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        nextRunAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "next_run_at";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        maxAttempts: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "max_attempts";
+            tableName: "job_schedules";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "priority";
+            tableName: "job_schedules";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        uniqueKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "unique_key";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        lastEnqueuedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "last_enqueued_at";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        lastError: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "last_error";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "job_schedules";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;

package/dist/dialects/sqlite/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.jobs = void 0;
+exports.jobSchedules = exports.jobs = void 0;
 const sqlite_core_1 = require("drizzle-orm/sqlite-core");
 /**
  * SQLite `jobs` table. Add it to your Drizzle schema and generate a migration
@@ -34,4 +34,35 @@ exports.jobs = (0, sqlite_core_1.sqliteTable)('jobs', {
     (0, sqlite_core_1.uniqueIndex)('jobs_name_unique_key_unique').on(table.name, table.uniqueKey),
     (0, sqlite_core_1.index)('jobs_status_available_idx').on(table.status, table.availableAt),
 ]);
+/**
+ * SQLite `job_schedules` table. Add it to your Drizzle schema (alongside
+ * `jobs`) and generate a migration with drizzle-kit — only needed when you
+ * opt in to schedules.
+ *
+ * `name` is the unique schedule identity (upserts key on it); the
+ * `(enabled, next_run_at)` index serves the claimer's due query. Timestamps
+ * are ISO-8601 strings, like every timestamp in this package.
+ */
+exports.jobSchedules = (0, sqlite_core_1.sqliteTable)('job_schedules', {
+    id: (0, sqlite_core_1.text)('id').primaryKey(),
+    name: (0, sqlite_core_1.text)('name').notNull(),
+    jobName: (0, sqlite_core_1.text)('job_name').notNull(),
+    payload: (0, sqlite_core_1.text)('payload', { mode: 'json' })
+        .$type()
+        .notNull(),
+    cron: (0, sqlite_core_1.text)('cron').notNull(),
+    timezone: (0, sqlite_core_1.text)('timezone'),
+    enabled: (0, sqlite_core_1.integer)('enabled', { mode: 'boolean' }).notNull().default(true),
+    nextRunAt: (0, sqlite_core_1.text)('next_run_at'),
+    maxAttempts: (0, sqlite_core_1.integer)('max_attempts'),
+    priority: (0, sqlite_core_1.integer)('priority'),
+    uniqueKey: (0, sqlite_core_1.text)('unique_key'),
+    lastEnqueuedAt: (0, sqlite_core_1.text)('last_enqueued_at'),
+    lastError: (0, sqlite_core_1.text)('last_error'),
+    createdAt: (0, sqlite_core_1.text)('created_at').notNull(),
+    updatedAt: (0, sqlite_core_1.text)('updated_at').notNull(),
+}, (table) => [
+    (0, sqlite_core_1.uniqueIndex)('job_schedules_name_unique').on(table.name),
+    (0, sqlite_core_1.index)('job_schedules_enabled_next_run_idx').on(table.enabled, table.nextRunAt),
+]);
 //# sourceMappingURL=schema.js.map

package/dist/dialects/sqlite/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../dialects/sqlite/schema.ts"],"names":[],"mappings":";;;AAAA,yDAMiC;AAGjC;;;;;;;;;;GAUG;AACU,QAAA,IAAI,GAAG,IAAA,yBAAW,EAC7B,MAAM,EACN;IACE,EAAE,EAAE,IAAA,kBAAI,EAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,IAAI,EAAE,IAAA,kBAAI,EAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,OAAO,EAAE,IAAA,kBAAI,EAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACvC,KAAK,EAA2B;SAChC,OAAO,EAAE;IACZ,MAAM,EAAE,IAAA,kBAAI,EAAC,QAAQ,CAAC,CAAC,KAAK,EAAa,CAAC,OAAO,EAAE;IACnD,QAAQ,EAAE,IAAA,qBAAO,EAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,WAAW,EAAE,IAAA,qBAAO,EAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,SAAS,EAAE,IAAA,kBAAI,EAAC,YAAY,CAAC;IAC7B,QAAQ,EAAE,IAAA,qBAAO,EAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,WAAW,EAAE,IAAA,kBAAI,EAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC3C,SAAS,EAAE,IAAA,kBAAI,EAAC,YAAY,CAAC;IAC7B,SAAS,EAAE,IAAA,kBAAI,EAAC,YAAY,CAAC;IAC7B,WAAW,EAAE,IAAA,kBAAI,EAAC,cAAc,CAAC;IACjC,SAAS,EAAE,IAAA,kBAAI,EAAC,YAAY,CAAC;IAC7B,SAAS,EAAE,IAAA,kBAAI,EAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CACxC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,IAAA,yBAAW,EAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1E,IAAA,mBAAK,EAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC;CACvE,CACF,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../dialects/sqlite/schema.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -16,3 +16,13 @@ export declare class RetryableError extends Error {
 export declare class PermanentError extends Error {
     constructor(message: string);
 }
+/**
+ * A cron expression (or its timezone) that croner cannot parse. Thrown by
+ * `JobSchedulesService.upsert`/`setEnabled` at call time — invalid schedules
+ * never reach the table. If a row is corrupted behind the service's back
+ * (hand-edited SQL), the claimer catches this during its tick and disables
+ * the row instead of crashing the loop.
+ */
+export declare class InvalidScheduleError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -3,7 +3,7 @@
 // dependency-free (no Nest, no Drizzle) so handlers, stores, and tests can all
 // throw these without importing anything heavier than this module.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PermanentError = exports.RetryableError = void 0;
+exports.InvalidScheduleError = exports.PermanentError = exports.RetryableError = void 0;
 /**
  * Signals a transient failure: the job could not complete now but a later
  * attempt may succeed. `delayMs`, when set, overrides the claimer's jittered
@@ -30,4 +30,18 @@ class PermanentError extends Error {
     }
 }
 exports.PermanentError = PermanentError;
+/**
+ * A cron expression (or its timezone) that croner cannot parse. Thrown by
+ * `JobSchedulesService.upsert`/`setEnabled` at call time — invalid schedules
+ * never reach the table. If a row is corrupted behind the service's back
+ * (hand-edited SQL), the claimer catches this during its tick and disables
+ * the row instead of crashing the loop.
+ */
+class InvalidScheduleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidScheduleError';
+    }
+}
+exports.InvalidScheduleError = InvalidScheduleError;
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../errors.ts"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,mEAAmE;;;AAEnE;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,KAAK;IACvC,YACE,OAAe,EACN,OAAgB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,YAAO,GAAP,OAAO,CAAS;QAGzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AARD,wCAQC;AAED;;;;GAIG;AACH,MAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../errors.ts"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,mEAAmE;;;AAEnE;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,KAAK;IACvC,YACE,OAAe,EACN,OAAgB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,YAAO,GAAP,OAAO,CAAS;QAGzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AARD,wCAQC;AAED;;;;GAIG;AACH,MAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED;;;;;;GAMG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AALD,oDAKC"}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from './interfaces';
 export * from './tokens';
 export * from './enqueue-input';
 export * from './job-handler.decorator';
+export * from './job-schedules.service';
+export * from './schedule-planner';
 export * from './jobs-handler.explorer';
 export * from './jobs.service';
 export * from './jobs-claimer.service';

package/dist/index.js

@@ -22,6 +22,8 @@ __exportStar(require("./interfaces"), exports);
 __exportStar(require("./tokens"), exports);
 __exportStar(require("./enqueue-input"), exports);
 __exportStar(require("./job-handler.decorator"), exports);
+__exportStar(require("./job-schedules.service"), exports);
+__exportStar(require("./schedule-planner"), exports);
 __exportStar(require("./jobs-handler.explorer"), exports);
 __exportStar(require("./jobs.service"), exports);
 __exportStar(require("./jobs-claimer.service"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAyD;AACzD,0EAA0E;AAC1E,+EAA+E;AAC/E,2CAAyB;AACzB,+CAA6B;AAC7B,2CAAyB;AACzB,kDAAgC;AAChC,0DAAwC;AACxC,0DAAwC;AACxC,iDAA+B;AAC/B,yDAAuC;AACvC,gDAA8B;AAC9B,gDAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAyD;AACzD,0EAA0E;AAC1E,+EAA+E;AAC/E,2CAAyB;AACzB,+CAA6B;AAC7B,2CAAyB;AACzB,kDAAgC;AAChC,0DAAwC;AACxC,0DAAwC;AACxC,qDAAmC;AACnC,0DAAwC;AACxC,iDAA+B;AAC/B,yDAAuC;AACvC,gDAA8B;AAC9B,gDAA8B"}