@nest-native/jobs 0.1.0

package/dist/interfaces.d.ts

@@ -0,0 +1,125 @@
+import type { ModuleMetadata } from '@nestjs/common';
+export declare const JOB_STATUSES: readonly ["pending", "processing", "completed", "failed"];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+/**
+ * The dialect-agnostic shape of a job row as the engine reasons about it. All
+ * three dialect stores map their Drizzle rows to this shape, so the claimer
+ * never sees a dialect-specific type. Timestamps are ISO-8601 strings on every
+ * dialect (they compare lexicographically, which the claimer's due-time query
+ * relies on).
+ */
+export interface JobRow {
+    id: string;
+    name: string;
+    payload: Record<string, unknown>;
+    status: JobStatus;
+    attempts: number;
+    maxAttempts: number;
+    /**
+     * The active-dedup key. Uniqueness is enforced by a FULL unique index on
+     * `(name, unique_key)` on every dialect, and terminal transitions
+     * (`completed`/`failed`) clear it to `NULL` — so "unique among ACTIVE jobs"
+     * holds everywhere without partial indexes. `NULL` keys never collide.
+     */
+    uniqueKey: string | null;
+    /** Claim priority — higher runs first among due jobs. Default 0. */
+    priority: number;
+    availableAt: string;
+    claimedAt: string | null;
+    claimedBy: string | null;
+    processedAt: string | null;
+    lastError: string | null;
+    createdAt: string;
+}
+/**
+ * What a caller supplies to enqueue a job.
+ *
+ * `runAt` and `delayMs` are **mutually exclusive** — supplying both throws.
+ * Omitting both makes the job due immediately.
+ *
+ * `TPayload` keeps the payload **structural**: a value typed as a plain
+ * interface (which has no index signature, so it is not assignable to
+ * `Record<string, unknown>`) is accepted as-is — no `as unknown as
+ * Record<string, unknown>` at every call site. The stored row shape stays
+ * `Record<string, unknown>` (see {@link JobRow}); the dialect stores perform
+ * that widening internally, exactly once.
+ */
+export interface EnqueueJobInput<TPayload extends object = Record<string, unknown>> {
+    name: string;
+    payload: TPayload;
+    /** Absolute due time. Mutually exclusive with `delayMs`. */
+    runAt?: Date;
+    /** Relative due time in milliseconds from now. Mutually exclusive with `runAt`. */
+    delayMs?: number;
+    maxAttempts?: number;
+    /**
+     * Dedup among ACTIVE jobs with the same `name`: while a `(name, uniqueKey)`
+     * job is pending/processing, enqueueing the same pair is a no-op that
+     * returns the EXISTING row. Terminal jobs release the key.
+     */
+    uniqueKey?: string;
+    /** Higher runs first among due jobs (default 0). */
+    priority?: number;
+}
+/** Fully-resolved runner configuration (defaults applied). */
+export interface ResolvedRunnerConfig {
+    workerInstanceId: string;
+    stuckTimeoutMs: number;
+    batchSize: number;
+    baseBackoffMs: number;
+    maxBackoffMs: number;
+}
+export type RunnerConfig = Partial<ResolvedRunnerConfig>;
+/** Execution context the claimer passes to a handler alongside the payload. */
+export interface JobContext {
+    /** The job row id — the natural idempotency key for handler side effects. */
+    jobId: string;
+    /** The 1-based attempt number of THIS execution (first run → 1). */
+    attempt: number;
+}
+/**
+ * The transactional persistence seam for the queue. Each implementation is
+ * dialect-specific and owns its Drizzle table + the sync/async query execution;
+ * `db` is passed per call (the tx-scoped instance for {@link enqueue}, the base
+ * instance for the rest) and is intentionally opaque (`unknown`) to the engine.
+ *
+ * `enqueue` returns the store's native shape — the **sqlite** store returns a
+ * synchronous `JobRow` (so it composes inside a synchronous `@Transactional`
+ * body); the **postgres** and **mysql** stores return a `Promise`. On a
+ * `(name, uniqueKey)` unique violation it returns the EXISTING active row
+ * (dedup no-op). It accepts `EnqueueJobInput<object>` so any structurally-typed
+ * payload flows through; the store widens the payload internally.
+ *
+ * `claimBatch` opens its own transaction, claims due `pending` jobs plus
+ * `processing` jobs stuck past `stuckTimeoutMs`, ordered by `priority DESC,
+ * available_at ASC`, and marks them `processing`.
+ */
+export interface JobStore {
+    enqueue(db: unknown, input: EnqueueJobInput<object>): JobRow | Promise<JobRow>;
+    claimBatch(db: unknown, cfg: ResolvedRunnerConfig): Promise<JobRow[]>;
+    /** Terminal: sets `completed` and clears `uniqueKey` (releases the key). */
+    markCompleted(db: unknown, id: string): Promise<void>;
+    /** Re-arms the job: `pending`, attempts+1, due in `delayMs`. Keeps `uniqueKey`. */
+    retry(db: unknown, id: string, delayMs: number, lastError?: string): Promise<void>;
+    /** Terminal: sets `failed`, attempts+1, and clears `uniqueKey`. */
+    markFailed(db: unknown, id: string, reason: string): Promise<void>;
+}
+/** Options for {@link JobsModule.forRoot}. */
+export interface JobsModuleOptions {
+    /**
+     * Token of the base (non-transactional) Drizzle instance — the same instance
+     * the `@nestjs-cls/transactional` Drizzle adapter is configured with. The
+     * claimer uses it to open its own claim transaction.
+     */
+    drizzleInstanceToken: symbol | string;
+    /** The dialect-specific job store. */
+    store: JobStore;
+    /**
+     * Modules that provide (and export) the `drizzleInstanceToken`. Required when
+     * that token is not registered by a global module — `JobsModule` imports
+     * these so it can resolve the Drizzle instance.
+     */
+    imports?: ModuleMetadata['imports'];
+    /** Register the module globally (default: true). */
+    isGlobal?: boolean;
+}

package/dist/interfaces.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_STATUSES = void 0;
+exports.JOB_STATUSES = [
+    'pending',
+    'processing',
+    'completed',
+    'failed',
+];
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../interfaces.ts"],"names":[],"mappings":";;;AAEa,QAAA,YAAY,GAAG;IAC1B,SAAS;IACT,YAAY;IACZ,WAAW;IACX,QAAQ;CACA,CAAC"}

package/dist/job-handler.decorator.d.ts

@@ -0,0 +1,31 @@
+import { type CustomDecorator } from '@nestjs/common';
+import type { JobContext } from './interfaces';
+/** Metadata key carrying the job name a `@JobHandler` class handles. */
+export declare const JOB_HANDLER_NAME: unique symbol;
+/**
+ * The contract a `@JobHandler(name)` class fulfils. Handlers run in the
+ * claimer's poll loop, OUTSIDE any business transaction, and delivery is
+ * at-least-once — make them idempotent or key side effects on `ctx.jobId`.
+ * Throw {@link RetryableError} / {@link PermanentError} to steer retries; any
+ * other throw retries with backoff until `maxAttempts`, then fails.
+ *
+ * The interface and the decorator below share the name deliberately (one lives
+ * in the type space, the other in the value space), so a handler reads:
+ *
+ * ```ts
+ * @JobHandler('email.welcome')
+ * @Injectable()
+ * export class WelcomeEmailHandler implements JobHandler { ... }
+ * ```
+ */
+export interface JobHandler {
+    handle(payload: Record<string, unknown>, ctx: JobContext): void | Promise<void>;
+}
+/**
+ * Marks a provider class as the handler for jobs enqueued under `name`.
+ *
+ * Register the class as a provider in any module; {@link JobsHandlerExplorer}
+ * discovers it at application bootstrap. Exactly one handler per name —
+ * duplicates throw at startup.
+ */
+export declare function JobHandler(name: string): CustomDecorator<symbol>;

package/dist/job-handler.decorator.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_HANDLER_NAME = void 0;
+exports.JobHandler = JobHandler;
+const common_1 = require("@nestjs/common");
+/** Metadata key carrying the job name a `@JobHandler` class handles. */
+exports.JOB_HANDLER_NAME = Symbol.for('@nest-native/jobs:job-handler-name');
+/**
+ * Marks a provider class as the handler for jobs enqueued under `name`.
+ *
+ * Register the class as a provider in any module; {@link JobsHandlerExplorer}
+ * discovers it at application bootstrap. Exactly one handler per name —
+ * duplicates throw at startup.
+ */
+function JobHandler(name) {
+    return (0, common_1.SetMetadata)(exports.JOB_HANDLER_NAME, name);
+}
+//# sourceMappingURL=job-handler.decorator.js.map

package/dist/job-handler.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.decorator.js","sourceRoot":"","sources":["../job-handler.decorator.ts"],"names":[],"mappings":";;;AAiCA,gCAEC;AAnCD,2CAAmE;AAGnE,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAsBjF;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,OAAO,IAAA,oBAAW,EAAC,wBAAgB,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC"}

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

@@ -0,0 +1,37 @@
+import type { JobStore, ResolvedRunnerConfig, RunnerConfig } from './interfaces';
+import { JobsHandlerExplorer } from './jobs-handler.explorer';
+export declare const DEFAULT_RUNNER_CONFIG: ResolvedRunnerConfig;
+export interface TickReport {
+    claimed: number;
+    completed: number;
+    retried: number;
+    failed: number;
+}
+/**
+ * Executes committed jobs. `tick()` claims a batch of due jobs (the store opens
+ * its own transaction; priority first, oldest due first, reclaiming jobs stuck
+ * in `processing`), dispatches each to the `@JobHandler` registered for its
+ * name, and records the outcome:
+ *
+ *   - handler returns          → `markCompleted` (key released)
+ *   - {@link PermanentError}   → `markFailed` immediately (no point retrying)
+ *   - {@link RetryableError}   → `retry`, honouring its `delayMs` if given
+ *   - any other throw          → `retry` with jittered exponential backoff
+ *                                until `maxAttempts`, then `markFailed`
+ *   - no handler registered    → `PermanentError` → `markFailed`
+ *
+ * Runs in a background worker (see `runWorkerLoop`) — never inside a business
+ * transaction — so it freely awaits the store and the handlers.
+ */
+export declare class JobsClaimer {
+    private readonly db;
+    private readonly store;
+    private readonly explorer;
+    private readonly logger;
+    constructor(db: unknown, store: JobStore, explorer: JobsHandlerExplorer);
+    tick(overrides?: RunnerConfig): Promise<TickReport>;
+    private processOne;
+    private onHandlerError;
+    private fail;
+    private backoff;
+}

package/dist/jobs-claimer.service.js

@@ -0,0 +1,121 @@
+"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); }
+};
+var JobsClaimer_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobsClaimer = exports.DEFAULT_RUNNER_CONFIG = void 0;
+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 tokens_1 = require("./tokens");
+exports.DEFAULT_RUNNER_CONFIG = {
+    workerInstanceId: `${(0, node_os_1.hostname)()}-${process.pid}`,
+    stuckTimeoutMs: 60_000,
+    batchSize: 32,
+    baseBackoffMs: 1_000,
+    maxBackoffMs: 60_000,
+};
+/**
+ * Executes committed jobs. `tick()` claims a batch of due jobs (the store opens
+ * its own transaction; priority first, oldest due first, reclaiming jobs stuck
+ * in `processing`), dispatches each to the `@JobHandler` registered for its
+ * name, and records the outcome:
+ *
+ *   - handler returns          → `markCompleted` (key released)
+ *   - {@link PermanentError}   → `markFailed` immediately (no point retrying)
+ *   - {@link RetryableError}   → `retry`, honouring its `delayMs` if given
+ *   - any other throw          → `retry` with jittered exponential backoff
+ *                                until `maxAttempts`, then `markFailed`
+ *   - no handler registered    → `PermanentError` → `markFailed`
+ *
+ * Runs in a background worker (see `runWorkerLoop`) — never inside a business
+ * transaction — so it freely awaits the store and the handlers.
+ */
+let JobsClaimer = JobsClaimer_1 = class JobsClaimer {
+    constructor(db, store, explorer) {
+        this.db = db;
+        this.store = store;
+        this.explorer = explorer;
+        this.logger = new common_1.Logger(JobsClaimer_1.name);
+    }
+    async tick(overrides = {}) {
+        const cfg = { ...exports.DEFAULT_RUNNER_CONFIG, ...overrides };
+        const claimed = await this.store.claimBatch(this.db, cfg);
+        const report = {
+            claimed: claimed.length,
+            completed: 0,
+            retried: 0,
+            failed: 0,
+        };
+        for (const job of claimed) {
+            const outcome = await this.processOne(job, cfg);
+            report[outcome] += 1;
+        }
+        return report;
+    }
+    async processOne(job, cfg) {
+        try {
+            const handler = this.explorer.get(job.name);
+            if (!handler) {
+                throw new errors_1.PermanentError(`No @JobHandler registered for job "${job.name}"`);
+            }
+            await handler.handle(job.payload, {
+                jobId: job.id,
+                attempt: job.attempts + 1,
+            });
+            await this.store.markCompleted(this.db, job.id);
+            return 'completed';
+        }
+        catch (error) {
+            return this.onHandlerError(job, cfg, error);
+        }
+    }
+    async onHandlerError(job, cfg, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Permanent: retrying can never succeed — fail now instead of burning attempts.
+        if (error instanceof errors_1.PermanentError) {
+            return this.fail(job, message);
+        }
+        // Retryable: schedule another attempt, honouring a handler-supplied delay.
+        if (error instanceof errors_1.RetryableError) {
+            const delay = error.delayMs ?? this.backoff(job.attempts, cfg);
+            await this.store.retry(this.db, job.id, delay, message);
+            return 'retried';
+        }
+        // Anything else: retry with backoff until maxAttempts, then fail.
+        if (job.attempts + 1 >= job.maxAttempts) {
+            return this.fail(job, message);
+        }
+        await this.store.retry(this.db, job.id, this.backoff(job.attempts, cfg), message);
+        return 'retried';
+    }
+    async fail(job, reason) {
+        this.logger.warn(`job ${job.id} ("${job.name}") failed: ${reason}`);
+        await this.store.markFailed(this.db, job.id, reason);
+        return 'failed';
+    }
+    backoff(attempts, cfg) {
+        const base = cfg.baseBackoffMs * 2 ** attempts;
+        const capped = Math.min(base, cfg.maxBackoffMs);
+        return capped + Math.floor(Math.random() * cfg.baseBackoffMs);
+    }
+};
+exports.JobsClaimer = JobsClaimer;
+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])
+], JobsClaimer);
+//# sourceMappingURL=jobs-claimer.service.js.map

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

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

package/dist/jobs-handler.explorer.d.ts

@@ -0,0 +1,24 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { type JobHandler } from './job-handler.decorator';
+/**
+ * Discovers `@JobHandler(name)` provider classes in the Nest container and
+ * builds the name → handler-instance registry the claimer dispatches through.
+ *
+ * Discovery happens once, at application bootstrap (so every module has
+ * finished instantiating its providers). Exactly one handler per job name:
+ * a second class claiming an already-registered name throws, failing the
+ * application at startup instead of silently shadowing a handler at runtime.
+ */
+export declare class JobsHandlerExplorer implements OnApplicationBootstrap {
+    private readonly discovery;
+    private readonly reflector;
+    private readonly registry;
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+    onApplicationBootstrap(): void;
+    /** The handler registered for `name`, if any. */
+    get(name: string): JobHandler | undefined;
+    /** Every registered job name (useful for diagnostics and tests). */
+    names(): readonly string[];
+    private register;
+}

package/dist/jobs-handler.explorer.js

@@ -0,0 +1,67 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobsHandlerExplorer = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const job_handler_decorator_1 = require("./job-handler.decorator");
+/**
+ * Discovers `@JobHandler(name)` provider classes in the Nest container and
+ * builds the name → handler-instance registry the claimer dispatches through.
+ *
+ * Discovery happens once, at application bootstrap (so every module has
+ * finished instantiating its providers). Exactly one handler per job name:
+ * a second class claiming an already-registered name throws, failing the
+ * application at startup instead of silently shadowing a handler at runtime.
+ */
+let JobsHandlerExplorer = class JobsHandlerExplorer {
+    constructor(discovery, reflector) {
+        this.discovery = discovery;
+        this.reflector = reflector;
+        this.registry = new Map();
+    }
+    onApplicationBootstrap() {
+        for (const wrapper of this.discovery.getProviders()) {
+            this.register(wrapper);
+        }
+    }
+    /** The handler registered for `name`, if any. */
+    get(name) {
+        return this.registry.get(name);
+    }
+    /** Every registered job name (useful for diagnostics and tests). */
+    names() {
+        return [...this.registry.keys()];
+    }
+    register(wrapper) {
+        const { instance, metatype } = wrapper;
+        if (!instance || !metatype) {
+            return;
+        }
+        const name = this.reflector.get(job_handler_decorator_1.JOB_HANDLER_NAME, metatype);
+        if (name === undefined) {
+            return;
+        }
+        const existing = this.registry.get(name);
+        if (existing && existing !== instance) {
+            throw new Error(`Duplicate @JobHandler("${name}"): ${metatype.name} conflicts ` +
+                'with an already-registered handler. Job names must map to exactly one handler.');
+        }
+        this.registry.set(name, instance);
+    }
+};
+exports.JobsHandlerExplorer = JobsHandlerExplorer;
+exports.JobsHandlerExplorer = JobsHandlerExplorer = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.Reflector])
+], JobsHandlerExplorer);
+//# sourceMappingURL=jobs-handler.explorer.js.map

package/dist/jobs-handler.explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs-handler.explorer.js","sourceRoot":"","sources":["../jobs-handler.explorer.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAoF;AACpF,uCAA2D;AAC3D,mEAA4E;AAW5E;;;;;;;;GAQG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAG9B,YACmB,SAA2B,EAC3B,SAAoB;QADpB,cAAS,GAAT,SAAS,CAAkB;QAC3B,cAAS,GAAT,SAAS,CAAW;QAJtB,aAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAKvD,CAAC;IAEJ,sBAAsB;QACpB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,YAAY,EAA2B,EAAE,CAAC;YAC7E,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,iDAAiD;IACjD,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,oEAAoE;IACpE,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;IAEO,QAAQ,CAAC,OAA4B;QAC3C,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QACvC,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAC7B,wCAAgB,EAChB,QAAgB,CACjB,CAAC;QACF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,OAAQ,QAAiB,CAAC,IAAI,aAAa;gBACvE,gFAAgF,CACnF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAsB,CAAC,CAAC;IAClD,CAAC;CACF,CAAA;AA7CY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAKmB,uBAAgB;QAChB,gBAAS;GAL5B,mBAAmB,CA6C/B"}

package/dist/jobs-worker.d.ts

@@ -0,0 +1,21 @@
+import type { RunnerConfig } from './interfaces';
+import type { JobsClaimer, TickReport } from './jobs-claimer.service';
+export interface WorkerLoopOptions {
+    /** Delay between ticks when the last tick claimed nothing (default 2000ms). */
+    pollIntervalMs?: number;
+    /** Runner overrides applied to every tick. */
+    runner?: RunnerConfig;
+    /** Abort to stop the loop. */
+    signal?: AbortSignal;
+    /** Called after each successful tick. */
+    onTick?: (report: TickReport) => void;
+    /** Called when a tick throws — the loop reports and continues. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Runs `claimer.tick()` in a loop until `signal` aborts. When a tick claims a
+ * batch it loops immediately to drain the backlog; when it claims nothing it
+ * waits `pollIntervalMs`. A throwing tick is reported via `onError` and the loop
+ * continues after the same wait.
+ */
+export declare function runWorkerLoop(claimer: JobsClaimer, options?: WorkerLoopOptions): Promise<void>;

package/dist/jobs-worker.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorkerLoop = runWorkerLoop;
+/**
+ * Runs `claimer.tick()` in a loop until `signal` aborts. When a tick claims a
+ * batch it loops immediately to drain the backlog; when it claims nothing it
+ * waits `pollIntervalMs`. A throwing tick is reported via `onError` and the loop
+ * continues after the same wait.
+ */
+async function runWorkerLoop(claimer, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    const { signal } = options;
+    while (!signal?.aborted) {
+        try {
+            const report = await claimer.tick(options.runner);
+            options.onTick?.(report);
+            if (report.claimed === 0) {
+                await sleep(pollIntervalMs, signal);
+            }
+        }
+        catch (error) {
+            options.onError?.(error);
+            await sleep(pollIntervalMs, signal);
+        }
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=jobs-worker.js.map

package/dist/jobs-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs-worker.js","sourceRoot":"","sources":["../jobs-worker.ts"],"names":[],"mappings":";;AAsBA,sCAkBC;AAxBD;;;;;GAKG;AACI,KAAK,UAAU,aAAa,CACjC,OAAoB,EACpB,UAA6B,EAAE;IAE/B,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IACvD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;YACzB,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;YACzB,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/jobs.module.d.ts

@@ -0,0 +1,19 @@
+import { type DynamicModule, type InjectionToken, type ModuleMetadata, type OptionalFactoryDependency } from '@nestjs/common';
+import type { JobsModuleOptions, JobStore } 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
+ * runtime providers (e.g. configuration).
+ */
+export interface JobsModuleAsyncOptions {
+    isGlobal?: boolean;
+    /** Token of the base (non-transactional) Drizzle instance. */
+    drizzleInstanceToken: symbol | string;
+    imports?: ModuleMetadata['imports'];
+    inject?: (InjectionToken | OptionalFactoryDependency)[];
+    useStore: (...args: any[]) => JobStore | Promise<JobStore>;
+}
+export declare class JobsModule {
+    static forRoot(options: JobsModuleOptions): DynamicModule;
+    static forRootAsync(options: JobsModuleAsyncOptions): DynamicModule;
+}

package/dist/jobs.module.js

@@ -0,0 +1,49 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobsModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+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");
+const tokens_1 = require("./tokens");
+let JobsModule = class JobsModule {
+    static forRoot(options) {
+        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_DRIZZLE, useExisting: options.drizzleInstanceToken },
+        ]);
+    }
+    static forRootAsync(options) {
+        return assemble(options.isGlobal ?? true, options.imports ?? [], [
+            {
+                provide: tokens_1.JOBS_STORE,
+                useFactory: options.useStore,
+                inject: options.inject ?? [],
+            },
+            { provide: tokens_1.JOBS_DRIZZLE, useExisting: options.drizzleInstanceToken },
+        ]);
+    }
+};
+exports.JobsModule = JobsModule;
+exports.JobsModule = JobsModule = __decorate([
+    (0, common_1.Module)({})
+], JobsModule);
+function assemble(global, imports, base) {
+    return {
+        module: JobsModule,
+        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],
+    };
+}
+//# sourceMappingURL=jobs.module.js.map

package/dist/jobs.module.js.map

@@ -0,0 +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"}

package/dist/jobs.service.d.ts

@@ -0,0 +1,25 @@
+import type { EnqueueJobInput, JobStore } from './interfaces';
+/**
+ * Enqueues jobs **inside the caller's business transaction** — the job row
+ * commits atomically with your writes. Inject it into a `@Transactional()`
+ * service and call `enqueue` alongside your business writes; if the
+ * transaction rolls back, the job was never enqueued.
+ *
+ * `enqueue` returns the store's native shape: the **sqlite** store returns a
+ * synchronous `JobRow` (call it without `await` inside a synchronous
+ * `@Transactional` body); the **postgres** and **mysql** stores return a
+ * `Promise` (await it). Type the service as `JobsService<typeof yourStore>` to get the
+ * exact shape. On a `(name, uniqueKey)` collision with an ACTIVE job it
+ * returns that existing row — a dedup no-op.
+ *
+ * Requires the host app to configure `@nestjs-cls/transactional` with the
+ * Drizzle adapter (`enableTransactionProxy: true`) — `@InjectTransaction()`
+ * resolves the transaction-scoped Drizzle instance from it (and falls back to
+ * the base instance outside any transaction).
+ */
+export declare class JobsService<TStore extends JobStore = JobStore> {
+    private readonly db;
+    private readonly store;
+    constructor(db: unknown, store: TStore);
+    enqueue<TPayload extends object>(input: EnqueueJobInput<TPayload>): ReturnType<TStore['enqueue']>;
+}