@rangka/core 0.0.1

package/dist/jobs/scheduler.d.ts

@@ -0,0 +1,51 @@
+import type { Kysely } from 'kysely';
+import type { JobRegistry } from './registry.js';
+/**
+ * ScheduleManager polls the database for cron-scheduled jobs that are due,
+ * enqueues them, and advances their next_run_at timestamps.
+ */
+export declare class ScheduleManager {
+    private running;
+    private pollTimer;
+    private readonly pollInterval;
+    private readonly db;
+    private readonly registry;
+    constructor(db: Kysely<unknown>, registry: JobRegistry, pollInterval?: number);
+    /** Upserts all registered scheduled jobs into the database. */
+    syncSchedules(): Promise<void>;
+    /** Starts the polling loop. */
+    start(): void;
+    /** Stops the polling loop. */
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    /**
+     * Parses a 5-field cron expression and returns the next matching minute
+     * after `from`. Scans up to ~1 year of minutes before giving up.
+     */
+    computeNextRun(cronExpr: string, from?: Date): Date;
+    /** Arms the next poll timer. */
+    private schedulePoll;
+    /** Runs one poll cycle, then re-arms the timer if still running. */
+    private poll;
+    /**
+     * Finds all schedules that are due and processes each one:
+     * - Skips enqueuing if the job already has a pending/active instance.
+     * - Otherwise enqueues a new job instance.
+     * In both cases, advances the schedule's next_run_at.
+     */
+    private checkSchedules;
+    /** Inserts a new job instance into the jobs table. */
+    private enqueueJob;
+    /** Updates a schedule's next_run_at and records last_run_at. */
+    private advanceSchedule;
+    /** Returns true if a job with the given name is already created or active. */
+    private hasPendingJob;
+    /**
+     * Checks whether a single cron field expression matches the given value.
+     * Supports: wildcard (*), lists (1,5,10), ranges (1-5), and steps (star/5, 1-10/2).
+     */
+    private matchesCronField;
+    /** Evaluates a single segment of a cron field (step, range, or literal). */
+    private segmentMatches;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/jobs/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,SAAQ;IAQ5E,+DAA+D;IACzD,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAepC,+BAA+B;IAC/B,KAAK,IAAI,IAAI;IAMb,8BAA8B;IACxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,IAAI;IAmC/D,gCAAgC;IAChC,OAAO,CAAC,YAAY;IAIpB,oEAAoE;IACpE,OAAO,CAAC,IAAI;IAUZ;;;;;OAKG;YACW,cAAc;IAkB5B,sDAAsD;YACxC,UAAU;IAOxB,gEAAgE;YAClD,eAAe;IAS7B,8EAA8E;YAChE,aAAa;IAQ3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAaxB,4EAA4E;IAC5E,OAAO,CAAC,cAAc;CAoBvB"}

package/dist/jobs/scheduler.js

@@ -0,0 +1,172 @@
+import { sql } from 'kysely';
+import { toCount } from '../helpers/coerce.js';
+/**
+ * ScheduleManager polls the database for cron-scheduled jobs that are due,
+ * enqueues them, and advances their next_run_at timestamps.
+ */
+export class ScheduleManager {
+    running = false;
+    pollTimer = null;
+    pollInterval;
+    db;
+    registry;
+    constructor(db, registry, pollInterval = 60000) {
+        this.db = db;
+        this.registry = registry;
+        this.pollInterval = pollInterval;
+    }
+    // ─── Public API ────────────────────────────────────────────────────────────
+    /** Upserts all registered scheduled jobs into the database. */
+    async syncSchedules() {
+        const scheduledJobs = this.registry.getScheduled();
+        for (const job of scheduledJobs) {
+            const cronExpr = job.config.schedule;
+            const nextRun = this.computeNextRun(cronExpr);
+            await sql `
+        INSERT INTO rangka_scheduled_jobs (name, cron, data, next_run_at)
+        VALUES (${job.name}, ${cronExpr}, NULL, ${nextRun})
+        ON CONFLICT (name) DO UPDATE SET cron = ${cronExpr}, next_run_at = COALESCE(rangka_scheduled_jobs.next_run_at, ${nextRun})
+      `.execute(this.db);
+        }
+    }
+    /** Starts the polling loop. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedulePoll();
+    }
+    /** Stops the polling loop. */
+    async stop() {
+        this.running = false;
+        if (this.pollTimer) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Parses a 5-field cron expression and returns the next matching minute
+     * after `from`. Scans up to ~1 year of minutes before giving up.
+     */
+    computeNextRun(cronExpr, from = new Date()) {
+        const fields = cronExpr.trim().split(/\s+/);
+        if (fields.length !== 5) {
+            throw new Error(`Invalid cron expression: "${cronExpr}"`);
+        }
+        const [minuteExpr, hourExpr, dayOfMonthExpr, monthExpr, dayOfWeekExpr] = fields;
+        // Start scanning from the next whole minute after `from`
+        const candidate = new Date(from.getTime());
+        candidate.setSeconds(0, 0);
+        candidate.setMinutes(candidate.getMinutes() + 1);
+        const ONE_YEAR_IN_MINUTES = 525_960;
+        for (let i = 0; i < ONE_YEAR_IN_MINUTES; i++) {
+            const matchesAllFields = this.matchesCronField(minuteExpr, candidate.getMinutes(), 0, 59) &&
+                this.matchesCronField(hourExpr, candidate.getHours(), 0, 23) &&
+                this.matchesCronField(dayOfMonthExpr, candidate.getDate(), 1, 31) &&
+                this.matchesCronField(monthExpr, candidate.getMonth() + 1, 1, 12) &&
+                this.matchesCronField(dayOfWeekExpr, candidate.getDay(), 0, 6);
+            if (matchesAllFields) {
+                return candidate;
+            }
+            candidate.setMinutes(candidate.getMinutes() + 1);
+        }
+        throw new Error(`Could not compute next run for cron: "${cronExpr}"`);
+    }
+    // ─── Private helpers ───────────────────────────────────────────────────────
+    /** Arms the next poll timer. */
+    schedulePoll() {
+        this.pollTimer = setTimeout(() => this.poll(), this.pollInterval);
+    }
+    /** Runs one poll cycle, then re-arms the timer if still running. */
+    poll() {
+        if (!this.running)
+            return;
+        this.checkSchedules().finally(() => {
+            if (this.running) {
+                this.schedulePoll();
+            }
+        });
+    }
+    /**
+     * Finds all schedules that are due and processes each one:
+     * - Skips enqueuing if the job already has a pending/active instance.
+     * - Otherwise enqueues a new job instance.
+     * In both cases, advances the schedule's next_run_at.
+     */
+    async checkSchedules() {
+        const dueSchedules = await sql `
+      SELECT id, name, cron, data FROM rangka_scheduled_jobs
+      WHERE next_run_at <= NOW()
+      FOR UPDATE SKIP LOCKED
+    `.execute(this.db);
+        for (const schedule of dueSchedules.rows) {
+            const alreadyPending = await this.hasPendingJob(schedule.name);
+            if (!alreadyPending) {
+                await this.enqueueJob(schedule.name, schedule.data);
+            }
+            await this.advanceSchedule(schedule.id, schedule.cron);
+        }
+    }
+    /** Inserts a new job instance into the jobs table. */
+    async enqueueJob(name, data) {
+        await sql `
+      INSERT INTO rangka_jobs (name, data, state, max_retries, backoff)
+      VALUES (${name}, ${JSON.stringify(data)}::jsonb, 'created', 0, 'exponential')
+    `.execute(this.db);
+    }
+    /** Updates a schedule's next_run_at and records last_run_at. */
+    async advanceSchedule(scheduleId, cronExpr) {
+        const nextRun = this.computeNextRun(cronExpr);
+        await sql `
+      UPDATE rangka_scheduled_jobs
+      SET next_run_at = ${nextRun}, last_run_at = NOW()
+      WHERE id = ${scheduleId}
+    `.execute(this.db);
+    }
+    /** Returns true if a job with the given name is already created or active. */
+    async hasPendingJob(name) {
+        const result = await sql `
+      SELECT COUNT(*) as count FROM rangka_jobs
+      WHERE name = ${name} AND state IN ('created', 'active')
+    `.execute(this.db);
+        return toCount(result.rows[0]) > 0;
+    }
+    /**
+     * Checks whether a single cron field expression matches the given value.
+     * Supports: wildcard (*), lists (1,5,10), ranges (1-5), and steps (star/5, 1-10/2).
+     */
+    matchesCronField(expr, value, min, _max) {
+        if (expr === '*')
+            return true;
+        // A field can be a comma-separated list of segments
+        for (const segment of expr.split(',')) {
+            if (this.segmentMatches(segment, value, min)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Evaluates a single segment of a cron field (step, range, or literal). */
+    segmentMatches(segment, value, fieldMin) {
+        if (segment.includes('/')) {
+            // Step expression, e.g. "*/5" or "10-30/5"
+            const [rangeExpr, stepStr] = segment.split('/');
+            const step = parseInt(stepStr, 10);
+            const start = rangeExpr === '*' ? fieldMin : parseInt(rangeExpr, 10);
+            return value >= start && (value - start) % step === 0;
+        }
+        if (segment.includes('-')) {
+            // Range expression, e.g. "1-5"
+            const [startStr, endStr] = segment.split('-');
+            const rangeStart = parseInt(startStr, 10);
+            const rangeEnd = parseInt(endStr, 10);
+            return value >= rangeStart && value <= rangeEnd;
+        }
+        // Exact value, e.g. "30"
+        return parseInt(segment, 10) === value;
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/jobs/scheduler.js.map

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

package/dist/jobs/tables.d.ts

@@ -0,0 +1,3 @@
+import type { TableDefinition } from '../db/types.js';
+export declare function getJobTables(): TableDefinition[];
+//# sourceMappingURL=tables.d.ts.map

package/dist/jobs/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/jobs/tables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,wBAAgB,YAAY,IAAI,eAAe,EAAE,CAEhD"}

package/dist/jobs/tables.js

@@ -0,0 +1,128 @@
+export function getJobTables() {
+    return [buildJobsTable(), buildDeadLettersTable(), buildScheduledJobsTable()];
+}
+function buildJobsTable() {
+    return {
+        name: 'rangka_jobs',
+        columns: [
+            {
+                name: 'id',
+                type: 'UUID',
+                nullable: false,
+                primaryKey: true,
+                defaultValue: 'gen_random_uuid()',
+            },
+            { name: 'name', type: 'TEXT', nullable: false },
+            { name: 'data', type: 'JSONB', nullable: true },
+            { name: 'state', type: 'TEXT', nullable: false, defaultValue: "'created'" },
+            { name: 'retry_count', type: 'INTEGER', nullable: false, defaultValue: '0' },
+            { name: 'max_retries', type: 'INTEGER', nullable: false, defaultValue: '0' },
+            { name: 'backoff', type: 'TEXT', nullable: false, defaultValue: "'exponential'" },
+            { name: 'start_after', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'started_at', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'completed_at', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'failed_at', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'error', type: 'TEXT', nullable: true },
+            { name: 'unique_key', type: 'TEXT', nullable: true },
+            { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+            { name: 'expire_in', type: 'INTERVAL', nullable: false, defaultValue: "'15 minutes'" },
+        ],
+        foreignKeys: [],
+        checkConstraints: [
+            {
+                name: 'chk_rangka_jobs_state',
+                column: 'state',
+                expression: "state IN ('created', 'active', 'completed', 'failed')",
+            },
+        ],
+        indexes: [
+            {
+                name: 'idx_rangka_jobs_state_start_after',
+                table: 'rangka_jobs',
+                columns: ['state', 'start_after'],
+                unique: false,
+            },
+            {
+                name: 'idx_rangka_jobs_name_state',
+                table: 'rangka_jobs',
+                columns: ['name', 'state'],
+                unique: false,
+            },
+            {
+                name: 'idx_rangka_jobs_unique_key_active',
+                table: 'rangka_jobs',
+                columns: ['unique_key'],
+                unique: true,
+                where: "state IN ('created', 'active')",
+            },
+        ],
+    };
+}
+function buildDeadLettersTable() {
+    return {
+        name: 'rangka_dead_letters',
+        columns: [
+            {
+                name: 'id',
+                type: 'UUID',
+                nullable: false,
+                primaryKey: true,
+                defaultValue: 'gen_random_uuid()',
+            },
+            { name: 'job_id', type: 'UUID', nullable: false },
+            { name: 'name', type: 'TEXT', nullable: false },
+            { name: 'data', type: 'JSONB', nullable: true },
+            { name: 'error', type: 'TEXT', nullable: true },
+            { name: 'retry_count', type: 'INTEGER', nullable: false, defaultValue: '0' },
+            { name: 'failed_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+            { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+        ],
+        foreignKeys: [],
+        checkConstraints: [],
+        indexes: [
+            {
+                name: 'idx_rangka_dead_letters_name',
+                table: 'rangka_dead_letters',
+                columns: ['name'],
+                unique: false,
+            },
+        ],
+    };
+}
+function buildScheduledJobsTable() {
+    return {
+        name: 'rangka_scheduled_jobs',
+        columns: [
+            {
+                name: 'id',
+                type: 'UUID',
+                nullable: false,
+                primaryKey: true,
+                defaultValue: 'gen_random_uuid()',
+            },
+            { name: 'name', type: 'TEXT', nullable: false },
+            { name: 'cron', type: 'TEXT', nullable: false },
+            { name: 'data', type: 'JSONB', nullable: true },
+            { name: 'last_run_at', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'next_run_at', type: 'TIMESTAMPTZ', nullable: true },
+            { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+        ],
+        foreignKeys: [],
+        checkConstraints: [],
+        indexes: [
+            {
+                name: 'uidx_rangka_scheduled_jobs_name',
+                table: 'rangka_scheduled_jobs',
+                columns: ['name'],
+                unique: true,
+            },
+            {
+                name: 'idx_rangka_scheduled_jobs_next_run',
+                table: 'rangka_scheduled_jobs',
+                columns: ['next_run_at'],
+                unique: false,
+            },
+        ],
+    };
+}
+//# sourceMappingURL=tables.js.map

package/dist/jobs/tables.js.map

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

package/dist/jobs/types.d.ts

@@ -0,0 +1,55 @@
+import type { JobConfig } from '@rangka/shared';
+export type JobState = 'created' | 'active' | 'completed' | 'failed';
+export type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+export interface JobRecord {
+    id: string;
+    name: string;
+    data: unknown;
+    state: JobState;
+    retry_count: number;
+    max_retries: number;
+    backoff: BackoffStrategy;
+    start_after: Date | null;
+    started_at: Date | null;
+    completed_at: Date | null;
+    failed_at: Date | null;
+    error: string | null;
+    unique_key: string | null;
+    created_at: Date;
+    expire_in: string;
+}
+export interface DeadLetterRecord {
+    id: string;
+    job_id: string;
+    name: string;
+    data: unknown;
+    error: string | null;
+    retry_count: number;
+    failed_at: Date;
+    created_at: Date;
+}
+export interface ScheduledJobRecord {
+    id: string;
+    name: string;
+    cron: string;
+    data: unknown;
+    last_run_at: Date | null;
+    next_run_at: Date | null;
+    created_at: Date;
+}
+export interface JobWorkerConfig {
+    pollInterval?: number;
+    enabled?: boolean;
+}
+export interface RegisteredJob {
+    name: string;
+    config: JobConfig;
+}
+export interface EnqueueOptions {
+    delay?: number;
+    unique?: boolean;
+    uniqueKey?: string;
+    retries?: number;
+    backoff?: BackoffStrategy;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErE,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B"}

package/dist/jobs/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":""}

package/dist/jobs/worker.d.ts

@@ -0,0 +1,55 @@
+import type { Kysely } from 'kysely';
+import type { FrameworkContext } from '@rangka/shared';
+import type { JobRegistry } from './registry.js';
+import type { JobWorkerConfig } from './types.js';
+/**
+ * Polls the database for pending jobs, claims them, and executes their handlers.
+ * Supports concurrency limits, retry with backoff, and graceful shutdown.
+ */
+export declare class JobWorker {
+    private running;
+    private pollTimer;
+    private activeJobIds;
+    private readonly pollInterval;
+    private readonly db;
+    private readonly registry;
+    private readonly ctx;
+    private shutdownResolve;
+    constructor(db: Kysely<unknown>, registry: JobRegistry, ctx: FrameworkContext, config?: JobWorkerConfig);
+    /** Begin polling for jobs. */
+    start(): void;
+    /** Stop polling and wait for in-flight jobs to finish. */
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getInFlightCount(): number;
+    /** Single poll iteration: claim a batch of jobs, execute them, then schedule the next poll. */
+    private poll;
+    /** Claim available jobs from the database and run them concurrently. */
+    private claimAndExecute;
+    /**
+     * Fetch pending jobs that this worker can handle, respecting concurrency limits.
+     * Uses SELECT FOR UPDATE SKIP LOCKED to allow multiple workers without conflicts.
+     */
+    private claimJobs;
+    /** Query the database for jobs that are ready to run. */
+    private fetchPendingJobs;
+    /** Filter jobs by concurrency limits and mark them as active. */
+    private claimWithConcurrencyCheck;
+    /** Returns true if the job type already has too many active instances. */
+    private exceedsConcurrencyLimit;
+    private getActiveCount;
+    /** Run a single job's handler, then mark it completed or handle failure. */
+    private executeJob;
+    /** If the worker is stopping and no jobs remain in flight, signal completion. */
+    private resolveShutdownIfDrained;
+    private markCompleted;
+    /** Either schedule a retry (with backoff) or move the job to the dead-letter table. */
+    private handleFailure;
+    /** Reset the job to 'created' with a delayed start_after timestamp. */
+    private scheduleRetry;
+    /** Permanently fail the job: archive it to dead letters and mark it failed. */
+    private moveToDeadLetter;
+    /** Calculate how long to wait before the next retry attempt. */
+    private computeBackoffDelay;
+}
+//# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAA8B,eAAe,EAAE,MAAM,YAAY,CAAC;AAM9E;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;IACvC,OAAO,CAAC,eAAe,CAA6B;gBAGlD,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EACnB,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,gBAAgB,EACrB,MAAM,GAAE,eAAoB;IAQ9B,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAMb,0DAA0D;IACpD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,SAAS,IAAI,OAAO;IAIpB,gBAAgB,IAAI,MAAM;IAQ1B,+FAA+F;IAC/F,OAAO,CAAC,IAAI;IAUZ,wEAAwE;YAC1D,eAAe;IAS7B;;;OAGG;YACW,SAAS;IAQvB,yDAAyD;YAC3C,gBAAgB;IAgB9B,iEAAiE;YACnD,yBAAyB;IAsBvC,0EAA0E;YAC5D,uBAAuB;YAWvB,cAAc;IAa5B,4EAA4E;YAC9D,UAAU;IAkBxB,iFAAiF;IACjF,OAAO,CAAC,wBAAwB;YAOlB,aAAa;IAW3B,uFAAuF;YACzE,aAAa;IAU3B,uEAAuE;YACzD,aAAa;IAe3B,+EAA+E;YACjE,gBAAgB;IAmB9B,gEAAgE;IAChE,OAAO,CAAC,mBAAmB;CAc5B"}