@bitclaw/jobs 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @bitclaw/jobs
+
+SQLite-backed background job queue for Bun. Features priority ordering, retries with backoff, cron scheduling, job dependencies, batch processing, rate limiting, and a dead-letter table.
+
+## Features
+
+- **Typed** Generic `JobQueue<TMap>` with per-type payload validation
+- **Priority** Jobs ordered by priority DESC then created_at ASC
+- **Retries** Configurable `maxRetries` with automatic dead-letter after exhaustion
+- **Dependencies** Blocked jobs auto-unblock when all dependencies complete
+- **Batches** Group jobs, track progress, fire `then`/`finally` callbacks on completion
+- **Cron** 5-field cron parser with `nextCronOccurrence` and overlap control
+- **Scheduler** Persistent `schedules` table with upsert semantics and cleanup
+- **Rate Limiter** In-memory sliding window per-worker throttling
+- **Worker** `setTimeout`-based poll loop with graceful shutdown and per-job timeout
+
+## Installation
+
+```bash
+bun add @bitclaw/jobs
+```
+
+## Quick Start
+
+```typescript
+import { JobQueue } from '@bitclaw/jobs'
+
+type AppJobs = {
+  'email:send': { to: string; subject: string }
+}
+
+const queue = new JobQueue<AppJobs>('./jobs.db')
+queue.add('email:send', { to: 'user@test.com', subject: 'Hello' })
+```
+
+## Worker
+
+```typescript
+const worker = queue.createWorker({
+  type: 'email:send',
+  handler: async (job, ctx) => {
+    ctx.reportProgress(50)
+    await sendEmail(job.data.to, job.data.subject)
+  },
+  pollIntervalMs: 1000,
+  maxRate: { count: 10, windowMs: 1000 }
+})
+
+worker.start()
+// ... later
+await worker.stop()
+```
+
+## Cron Scheduler
+
+```typescript
+import { Scheduler } from '@bitclaw/jobs'
+
+const scheduler = new Scheduler(queue)
+scheduler.register('daily-report', 'report:generate', '0 2 * * *', {
+  data: { type: 'daily' }
+})
+scheduler.start() // ticks every 60s by default
+```
+
+## Subpath Exports
+
+```typescript
+import { JobQueue }       from '@bitclaw/jobs'
+import { JobWorker }      from '@bitclaw/jobs/worker'
+import { JobQueue }       from '@bitclaw/jobs/queue'
+import { Scheduler }      from '@bitclaw/jobs/scheduler'
+import { parseCron }      from '@bitclaw/jobs/cron'
+import { initializeSchema } from '@bitclaw/jobs/schema'
+import { SlidingWindowRateLimiter } from '@bitclaw/jobs/rate-limiter'
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+118 tests across 7 files.

package/dist/cron.d.ts

@@ -0,0 +1,11 @@
+export type ParsedCron = {
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    daysOfWeek: Set<number>;
+};
+export declare function parseCron(expression: string): ParsedCron;
+export declare function cronMatches(parsed: ParsedCron, date: Date): boolean;
+export declare function nextCronOccurrence(parsed: ParsedCron, after: Date): Date;
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC;AAqDF,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAmBxD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAQnE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI,CAiBxE"}

package/dist/cron.js

@@ -0,0 +1,86 @@
+// packages/jobs/src/cron.ts
+// Minimal 5-field cron parser (minute, hour, day-of-month, month, day-of-week)
+const FIELD_RANGES = [
+    [0, 59], // minute
+    [0, 23], // hour
+    [1, 31], // day of month
+    [1, 12], // month
+    [0, 6] // day of week (0=Sun)
+];
+function parseField(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(',')) {
+        if (part === '*') {
+            for (let i = min; i <= max; i++)
+                values.add(i);
+            continue;
+        }
+        // */N step from min
+        const fullStepMatch = part.match(/^\*\/(\d+)$/);
+        if (fullStepMatch) {
+            const step = Number(fullStepMatch[1]);
+            if (step === 0)
+                throw new Error(`Invalid step value: ${part}`);
+            for (let i = min; i <= max; i += step)
+                values.add(i);
+            continue;
+        }
+        // N-M or N-M/S range with optional step
+        const rangeMatch = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+        if (rangeMatch) {
+            const start = Number(rangeMatch[1]);
+            const end = Number(rangeMatch[2]);
+            const step = rangeMatch[3] ? Number(rangeMatch[3]) : 1;
+            if (start < min || end > max || start > end) {
+                throw new Error(`Invalid range: ${part} (valid: ${min}-${max})`);
+            }
+            if (step === 0)
+                throw new Error(`Invalid step value: ${part}`);
+            for (let i = start; i <= end; i += step)
+                values.add(i);
+            continue;
+        }
+        // Plain number
+        const num = Number(part);
+        if (Number.isNaN(num) || num < min || num > max) {
+            throw new Error(`Invalid value: ${part} (valid: ${min}-${max})`);
+        }
+        values.add(num);
+    }
+    return values;
+}
+export function parseCron(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Invalid cron expression: expected 5 fields, got ${fields.length}`);
+    }
+    return {
+        minutes: parseField(fields[0], FIELD_RANGES[0][0], FIELD_RANGES[0][1]),
+        hours: parseField(fields[1], FIELD_RANGES[1][0], FIELD_RANGES[1][1]),
+        daysOfMonth: parseField(fields[2], FIELD_RANGES[2][0], FIELD_RANGES[2][1]),
+        months: parseField(fields[3], FIELD_RANGES[3][0], FIELD_RANGES[3][1]),
+        daysOfWeek: parseField(fields[4], FIELD_RANGES[4][0], FIELD_RANGES[4][1])
+    };
+}
+export function cronMatches(parsed, date) {
+    return (parsed.minutes.has(date.getUTCMinutes()) &&
+        parsed.hours.has(date.getUTCHours()) &&
+        parsed.daysOfMonth.has(date.getUTCDate()) &&
+        parsed.months.has(date.getUTCMonth() + 1) &&
+        parsed.daysOfWeek.has(date.getUTCDay()));
+}
+export function nextCronOccurrence(parsed, after) {
+    // Start from the next minute
+    const candidate = new Date(after.getTime());
+    candidate.setUTCSeconds(0, 0);
+    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    // Cap at 2 years to avoid infinite loops
+    const limit = after.getTime() + 2 * 365 * 24 * 60 * 60 * 1000;
+    while (candidate.getTime() <= limit) {
+        if (cronMatches(parsed, candidate)) {
+            return candidate;
+        }
+        candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    }
+    throw new Error('No matching cron occurrence found within 2 years');
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { ParsedCron } from './cron';
+export { cronMatches, nextCronOccurrence, parseCron } from './cron';
+export { JobQueue } from './queue';
+export { SlidingWindowRateLimiter } from './rate-limiter';
+export { Scheduler } from './scheduler';
+export { applyPragmas, initializeSchema } from './schema';
+export type { AddJobOptions, AddScheduleOptions, BatchOptions, FailedJob, Job, JobBatch, JobContext, JobMap, JobStats, JobStatus, ListJobsOptions, PaginatedResult, PurgeOptions, RateLimit, Schedule, WorkerOptions } from './types';
+export { NonRetryableError } from './types';
+export { JobWorker } from './worker';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,UAAU,EACV,MAAM,EACN,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// packages/jobs/src/index.ts
+// Barrel export for @bitclaw/jobs
+export { cronMatches, nextCronOccurrence, parseCron } from './cron';
+export { JobQueue } from './queue';
+export { SlidingWindowRateLimiter } from './rate-limiter';
+export { Scheduler } from './scheduler';
+export { applyPragmas, initializeSchema } from './schema';
+export { NonRetryableError } from './types';
+export { JobWorker } from './worker';

package/dist/queue.d.ts

@@ -0,0 +1,63 @@
+import { Database } from 'bun:sqlite';
+import type { AddJobOptions, BatchOptions, FailedJob, Job, JobBatch, JobMap, JobStats, ListJobsOptions, PaginatedResult, PurgeOptions, WorkerOptions } from './types';
+import { JobWorker } from './worker';
+export declare class JobQueue<TMap extends JobMap = Record<string, unknown>> {
+    readonly db: Database;
+    private readonly insertJobStmt;
+    private readonly insertDepStmt;
+    private readonly selectJobStmt;
+    private readonly selectPendingStmt;
+    private readonly markProcessingStmt;
+    private readonly markDoneStmt;
+    private readonly markFailedStmt;
+    private readonly updateProgressStmt;
+    private readonly selectStatsStmt;
+    private readonly countFailedStmt;
+    private readonly insertFailedJobStmt;
+    private readonly deleteJobStmt;
+    private readonly selectDependentsStmt;
+    private readonly countUnmetDepsStmt;
+    private readonly unblockJobStmt;
+    private readonly lastInsertRowIdStmt;
+    private readonly insertBatchStmt;
+    private readonly selectBatchStmt;
+    private readonly decrementBatchPendingStmt;
+    private readonly incrementBatchFailedStmt;
+    private readonly finishBatchStmt;
+    private readonly cancelBatchStmt;
+    private readonly cancelBatchJobsStmt;
+    constructor(dbPath: string);
+    add<K extends string & keyof TMap>(type: K, data: TMap[K], options?: AddJobOptions): number;
+    getJob(id: number): Job | null;
+    getStats(): JobStats;
+    getFailedJobs(options?: {
+        type?: string;
+        limit?: number;
+        offset?: number;
+    }): PaginatedResult<FailedJob>;
+    listJobs(options?: ListJobsOptions): PaginatedResult<Job>;
+    cancelJob(id: number): boolean;
+    forceRetryJob(id: number): boolean;
+    setJobHttpLog(id: number, requestLog: string, responseLog: string): void;
+    getJobTypes(): string[];
+    retryFailedJob(failedJobId: number): number;
+    purgeFailedJobs(olderThanMs: number): number;
+    purge(options: PurgeOptions): number;
+    pollAndClaim(type: string): Job | null;
+    markJobDone(id: number): void;
+    markJobDead(id: number, error: string): void;
+    markJobFailed(id: number, error: string): void;
+    updateProgress(id: number, progress: number): void;
+    createBatch(name: string, options?: BatchOptions): string;
+    addToBatch<K extends string & keyof TMap>(batchId: string, type: K, data: TMap[K], options?: AddJobOptions): number;
+    getBatch(batchId: string): JobBatch | null;
+    cancelBatch(batchId: string): void;
+    createWorker<K extends string & keyof TMap>(options: WorkerOptions<TMap[K]> & {
+        type: K;
+    }): JobWorker<TMap, K>;
+    private insertJob;
+    close(): void;
+    private unblockDependents;
+    private handleBatchJobComplete;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EAET,GAAG,EACH,QAAQ,EAER,MAAM,EAEN,QAAQ,EACR,eAAe,EACf,eAAe,EACf,YAAY,EAEZ,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAuDrC,qBAAa,QAAQ,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAGrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC3C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC;gBAEzB,MAAM,EAAE,MAAM;IAgG1B,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,EAC/B,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM;IAIT,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAK9B,QAAQ,IAAI,QAAQ;IAwBpB,aAAa,CAAC,OAAO,CAAC,EAAE;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,eAAe,CAAC,SAAS,CAAC;IAkC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC,GAAG,CAAC;IAkCzD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAS9B,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IASlC,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAQxE,WAAW,IAAI,MAAM,EAAE;IAOvB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IA6B3C,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAQ5C,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAQpC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAgBtC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAa7B,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IA4B5C,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAkC9C,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAUlD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM;IAWzD,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,EACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM;IAYT,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAO1C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMlC,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,EACxC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,GAC5C,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAIrB,OAAO,CAAC,SAAS;IAuCjB,KAAK,IAAI,IAAI;IAWb,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,sBAAsB;CA4C/B"}