@zmdb/jobs 1.0.0-beta.1

package/README.md

@@ -0,0 +1,87 @@
+# @zmdb/jobs
+
+Typed queues, workers, dead letters, scheduling, leases, and explicit provider ports for zmdb applications.
+
+## Install
+
+```bash
+yarn add @zmdb/jobs@1.0.0-beta.1
+```
+
+The package is ESM-only and requires Node.js 26 or later. It has no third-party runtime peer. `yarn add zmdb@1.0.0-beta.1` does not install it, and there is no `zmdb/jobs` facade.
+
+## Choose the capability and its storage
+
+The default [SQLite HTTP application](https://ambasta.github.io/zmdb/docs/web-overview.html) starts with `yarn add zmdb@1.0.0-beta.1`. Add jobs when the application needs background work:
+
+| Choice                                  | Install                                                                        | Public imports                            |
+| --------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| Portable queues and scheduling          | `yarn add @zmdb/jobs@1.0.0-beta.1`                                             | `@zmdb/jobs`, `@zmdb/jobs/schedule`       |
+| SQLite jobs, including the memory store | `yarn add @zmdb/jobs@1.0.0-beta.1 @zmdb/jobs-sqlite@1.0.0-beta.1`              | `@zmdb/jobs`, `@zmdb/jobs-sqlite`         |
+| PostgreSQL jobs                         | `yarn add @zmdb/jobs@1.0.0-beta.1 @zmdb/jobs-postgres@1.0.0-beta.1 pg@^8.23.0` | `@zmdb/jobs`, `@zmdb/jobs-postgres`, `pg` |
+
+The portable install supplies behavior and provider ports. Queue and worker constructors require an explicit `store` and throw `TypeError` when it is missing; they never choose SQLite automatically.
+Per-replica schedules can run without a database. A cluster schedule requires a supplied `LeaseStore` and is refused before startup when it is missing. These package boundaries let applications select
+storage and upgrade providers independently while using the same jobs APIs and application lifecycle.
+
+## Migrations and ownership
+
+| Constructor                                                 | Before starting work                                                            | Resource ownership                                                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `createMemoryJobStore()` from `@zmdb/jobs-sqlite`           | Creates and migrates a fresh memory database automatically                      | The store owns and closes that database                                                                |
+| `createSqliteJobStore(database)` from `@zmdb/jobs-sqlite`   | Apply the exported `jobsSqliteMigrations` to the caller's database              | Closing the store leaves the supplied database open                                                    |
+| `createPgJobStore(poolOrClient)` from `@zmdb/jobs-postgres` | Apply the exported `jobsPostgresMigrations` to the selected PostgreSQL database | The caller owns the supplied pool/client; the adapter releases only connections it acquires internally |
+
+Durable providers do not apply migrations automatically. Their stores also implement the scheduler's lease port, so a cluster scheduler can use the selected store as `leases`. Distinct replicas need
+shared storage; a fresh process-local memory store cannot coordinate them.
+
+Include a store in `jobsExtension({ workers, schedulers, stores })` to close its adapter after schedulers and workers stop. Await `app[Symbol.asyncDispose]()` before closing a caller-owned database or
+pool. If a store is managed outside the extension, the caller closes it after background work stops, as in the complete server example below.
+
+## Entry points
+
+- `@zmdb/jobs` — queues, workers, the common clock, lifecycle integration, and the complete convenience surface
+- `@zmdb/jobs/schedule` — cron and interval decorators, schedulers, and the lease-store port
+
+Workers and schedulers are explicit instances. Pass them to `jobsExtension({ workers, schedulers, stores })` to start after application bootstrap and stop under the application's bounded grace period.
+
+```ts
+import { createApplication, Module } from '@zmdb/app';
+import { jobsExtension } from '@zmdb/jobs';
+
+@Module({ controllers: [] })
+class Application {}
+
+const app = createApplication(Application, {
+  extensions: [jobsExtension({ workers: [], schedulers: [] })],
+});
+await app.init();
+await app[Symbol.asyncDispose]();
+```
+
+The [complete server example](https://ambasta.github.io/zmdb/docs/web-overview.html) creates a real SQLite worker and supplies this extension to `createApp`, so HTTP and jobs share one application
+lifecycle.
+
+Replace the empty arrays with the workers and schedulers owned by that application. The extension uses the same startup, rollback, reverse shutdown, and grace deadline as every other `@zmdb/app`
+extension.
+
+The default package has no `pg` peer. SQLite workers add `@zmdb/jobs-sqlite@1.0.0-beta.1`, which owns both durable and memory storage. PostgreSQL workers add `@zmdb/jobs-postgres@1.0.0-beta.1` and
+`pg@^8.23.0`; that adapter borrows a caller-owned pool or client and never closes the supplied resource; it releases only connections it acquires internally.
+
+## Alpha migration
+
+Update the selected dependency and import together:
+
+| Removed or branch-only import | Current import                                  | Required selection                             |
+| ----------------------------- | ----------------------------------------------- | ---------------------------------------------- |
+| `@zmdb/jobs/memory`           | `createMemoryJobStore` from `@zmdb/jobs-sqlite` | Add `@zmdb/jobs-sqlite` alongside `@zmdb/jobs` |
+| `zmdb/jobs`                   | `@zmdb/jobs`                                    | Add `@zmdb/jobs` explicitly                    |
+| `zmdb/jobs/schedule`          | `@zmdb/jobs/schedule`                           | Add `@zmdb/jobs` explicitly                    |
+| `zmdb/jobs/memory`            | `createMemoryJobStore` from `@zmdb/jobs-sqlite` | Add both jobs and the SQLite provider          |
+
+The memory constructor now belongs to the SQLite provider. Keep portable queues, workers and schedules imported from `@zmdb/jobs`; supply the chosen provider through its public ports. The retired
+entries have no runtime forwarders. The [queues guide](https://ambasta.github.io/zmdb/docs/web-queues.html) covers provider migrations, transactions and bounded shutdown.
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later).

package/dist/extension.d.ts

@@ -0,0 +1,15 @@
+import type { ApplicationExtension } from '@zmdb/app';
+import type { JobStoreResource, Worker } from './queues/index.js';
+import type { Scheduler } from './schedule/index.js';
+/**
+ * Start and stop one application's explicit background-work components.
+ *
+ * Workers start first so a scheduled enqueue always has a consumer. Shutdown
+ * reverses that order so no scheduler can add work after worker drain begins.
+ */
+export declare function jobsExtension(options: {
+    readonly workers?: readonly Worker[];
+    readonly schedulers?: readonly Scheduler[];
+    readonly stores?: readonly JobStoreResource[];
+}): ApplicationExtension;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAOrD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C,GAAG,oBAAoB,CAsBvB"}

package/dist/extension.js

@@ -0,0 +1,74 @@
+/**
+ * Start and stop one application's explicit background-work components.
+ *
+ * Workers start first so a scheduled enqueue always has a consumer. Shutdown
+ * reverses that order so no scheduler can add work after worker drain begins.
+ */
+export function jobsExtension(options) {
+    const workers = Object.freeze([...(options.workers ?? [])]);
+    const schedulers = Object.freeze([...(options.schedulers ?? [])]);
+    const stores = [...new Set(options.stores ?? [])];
+    const enteredWorkers = [];
+    const enteredSchedulers = [];
+    let started = false;
+    let stopped;
+    return {
+        name: '@zmdb/jobs',
+        start() {
+            if (started)
+                return;
+            started = true;
+            startAll(workers, enteredWorkers);
+            startAll(schedulers, enteredSchedulers);
+        },
+        stop({ graceMs }) {
+            stopped ??= stopAll(enteredSchedulers, enteredWorkers, stores, graceMs);
+            return stopped;
+        },
+    };
+}
+function startAll(participants, entered) {
+    for (const participant of participants) {
+        entered.push(participant);
+        participant.start();
+    }
+}
+async function stopAll(schedulers, workers, stores, graceMs) {
+    if (!Number.isSafeInteger(graceMs) || graceMs < 0 || graceMs > 2_147_483_647) {
+        throw new RangeError('@zmdb/jobs: graceMs must be a non-negative safe integer');
+    }
+    const deadline = Date.now() + graceMs;
+    const errors = [];
+    const stops = [
+        ...schedulers
+            .toReversed()
+            .map(participant => (remaining) => participant.onShutdown({ graceMs: remaining })),
+        ...workers.toReversed().map(participant => (remaining) => participant.onShutdown({ graceMs: remaining })),
+        ...stores.toReversed().map(store => (remaining) => store.close({ graceMs: remaining })),
+    ];
+    for (const stop of stops) {
+        let timer;
+        try {
+            const remaining = Math.max(0, deadline - Date.now());
+            const work = Promise.resolve(stop(remaining));
+            await Promise.race([
+                work,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new DOMException('@zmdb/jobs: shutdown deadline exceeded', 'TimeoutError')), remaining);
+                }),
+            ]);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    if (errors.length === 0)
+        return;
+    if (errors.length === 1)
+        throw errors[0];
+    throw new AggregateError(errors, '@zmdb/jobs: background work shutdown failed');
+}
+//# sourceMappingURL=extension.js.map

package/dist/extension.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { jobsExtension } from './extension.js';
+export { createQueue, createWorker } from './queues/index.js';
+export { Cron, Interval, createScheduler, schedulesOf } from './schedule/index.js';
+export type { AnyJobHandler, Backoff, Clock, DeadJob, DeadReason, EnqueueOptions, JobContext, ClaimedJob, JobCandidate, JobEnqueue, JobEnqueuer, JobEnqueueResult, JobSettlement, JobStoreResource, JobStoreMigration, JobHandler, JobOutcome, JobStore, Queue, QueueOptions, RetryPolicy, RunReport, Worker, WorkerOptions, } from './queues/index.js';
+export type { IntervalOptions, LeaseStore, ScheduleDef, Scheduler, SchedulerOptions, SkippedRun, TaskDecorator, TaskOptions, TaskRuns, } from './schedule/index.js';
+//# 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":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnF,YAAY,EACV,aAAa,EACb,OAAO,EACP,KAAK,EACL,OAAO,EACP,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,MAAM,EACN,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,UAAU,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,WAAW,EACX,QAAQ,GACT,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// @zmdb/jobs — queues, workers, scheduling and app lifecycle integration.
+export { jobsExtension } from './extension.js';
+export { createQueue, createWorker } from './queues/index.js';
+export { Cron, Interval, createScheduler, schedulesOf } from './schedule/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/queues/index.d.ts

@@ -0,0 +1,191 @@
+export interface Clock {
+    now(): number;
+    sleep(ms: number, signal: AbortSignal): Promise<void>;
+}
+export interface JobEnqueue {
+    readonly id: string;
+    readonly name: string;
+    readonly payload: string;
+    readonly enqueuedAt: Date;
+    readonly availableAt: Date;
+    readonly dedupeKey?: string;
+}
+export type JobEnqueueResult = {
+    readonly kind: 'inserted';
+    readonly jobId: string;
+} | {
+    readonly kind: 'duplicate';
+    readonly jobId: string;
+};
+export interface JobEnqueuer {
+    enqueue(job: JobEnqueue): Promise<JobEnqueueResult>;
+}
+export interface JobCandidate {
+    readonly id: string;
+    readonly name: string;
+    readonly enqueuedAt: Date;
+}
+export interface ClaimedJob extends JobCandidate {
+    readonly payload: string;
+    readonly attempts: number;
+    readonly dedupeKey?: string;
+    readonly holder: string;
+}
+export type JobSettlement = {
+    readonly kind: 'done';
+    readonly jobId: string;
+    readonly holder: string;
+    readonly idempotencyKey: string;
+    readonly completedAt: Date;
+} | {
+    readonly kind: 'retry';
+    readonly jobId: string;
+    readonly holder: string;
+    readonly attempts: number;
+    readonly availableAt: Date;
+    readonly detail: string;
+} | {
+    readonly kind: 'dead';
+    readonly jobId: string;
+    readonly holder: string;
+    readonly attempts: number;
+    readonly reason: DeadReason;
+    readonly detail: string;
+    readonly deadAt: Date;
+} | {
+    readonly kind: 'release';
+    readonly jobId: string;
+    readonly holder: string;
+    readonly availableAt: Date;
+};
+export interface JobStore extends JobEnqueuer {
+    candidates(options: {
+        readonly now: Date;
+        readonly limit: number;
+    }): Promise<readonly JobCandidate[]>;
+    claim(options: {
+        readonly ids: readonly string[];
+        readonly holder: string;
+        readonly now: Date;
+        readonly leaseUntil: Date;
+    }): Promise<readonly ClaimedJob[]>;
+    completed(key: string): Promise<boolean>;
+    settle(settlement: JobSettlement): Promise<boolean>;
+    listDead(options: {
+        readonly limit: number;
+        readonly reason?: DeadReason;
+    }): Promise<readonly DeadJob[]>;
+    replay(jobId: string, availableAt: Date): Promise<boolean>;
+}
+export interface JobStoreResource {
+    close(options?: {
+        readonly graceMs: number;
+    }): void | Promise<void>;
+}
+export interface JobStoreMigration {
+    readonly version: number;
+    readonly name: string;
+    readonly up: string;
+    readonly down: string;
+}
+export type Backoff = {
+    readonly kind: 'fixed';
+    readonly delayMs: number;
+} | {
+    readonly kind: 'exponential';
+    readonly baseMs: number;
+    readonly ceilingMs: number;
+};
+export interface RetryPolicy {
+    readonly attempts: number;
+    readonly backoff: Backoff;
+}
+export type DeadReason = 'invalid-payload' | 'unknown-name' | 'attempts-exhausted';
+export type JobOutcome = {
+    readonly kind: 'done';
+} | {
+    readonly kind: 'retry';
+    readonly afterMs: number;
+} | {
+    readonly kind: 'dead';
+    readonly reason: DeadReason;
+    readonly detail: string;
+};
+export interface JobContext {
+    readonly jobId: string;
+    readonly name: string;
+    readonly attempt: number;
+    readonly enqueuedAt: Date;
+    readonly idempotencyKey: string;
+    readonly signal: AbortSignal;
+}
+export interface JobHandler<M, K extends keyof M & string> {
+    readonly name: K;
+    readonly validate: (raw: unknown) => M[K];
+    handle(payload: M[K], ctx: JobContext): Promise<void>;
+    readonly concurrency?: number;
+    readonly timeoutMs?: number;
+    readonly retries?: RetryPolicy;
+}
+export type AnyJobHandler<M> = {
+    readonly [K in keyof M & string]: JobHandler<M, K>;
+}[keyof M & string];
+export interface EnqueueOptions {
+    readonly delayMs?: number;
+    readonly dedupeKey?: string;
+}
+export interface Queue<M> {
+    enqueue<K extends keyof M & string>(name: K, payload: M[K], opts?: EnqueueOptions): Promise<string>;
+    enqueueInTransaction<K extends keyof M & string>(tx: JobEnqueuer, name: K, payload: M[K], opts?: EnqueueOptions): Promise<string>;
+}
+export interface QueueOptions {
+    readonly store: JobStore;
+    readonly clock: Clock;
+}
+export interface DeadJob {
+    readonly jobId: string;
+    readonly name: string;
+    readonly payload: string;
+    readonly attempts: number;
+    readonly reason: DeadReason;
+    readonly detail: string;
+    readonly enqueuedAt: Date;
+    readonly deadAt: Date;
+}
+export interface WorkerOptions<M> {
+    readonly handlers: readonly AnyJobHandler<M>[];
+    readonly store: JobStore;
+    readonly clock: Clock;
+    readonly concurrency: number;
+    readonly graceMs: number;
+    readonly leaseMs: number;
+    readonly onDead: (job: DeadJob) => void | Promise<void>;
+    readonly onHandlerError: (ctx: JobContext, error: unknown) => void;
+    readonly timeoutMs?: number;
+    readonly retries?: RetryPolicy;
+    readonly batch?: number;
+    readonly idleMs?: number;
+    readonly maxIdleMs?: number;
+}
+export interface Worker {
+    runOnce(): Promise<RunReport>;
+    start(): void;
+    onShutdown(options?: {
+        readonly graceMs: number;
+    }): Promise<void>;
+    listDead(opts: {
+        readonly limit: number;
+        readonly reason?: DeadReason;
+    }): Promise<readonly DeadJob[]>;
+    replay(jobId: string): Promise<boolean>;
+}
+export interface RunReport {
+    readonly claimed: number;
+    readonly done: number;
+    readonly retried: number;
+    readonly dead: number;
+    readonly skipped: number;
+}
+export declare function createQueue<M>(opts: QueueOptions): Queue<M>;
+export declare function createWorker<M>(opts: WorkerOptions<M>): Worker;
+//# sourceMappingURL=index.d.ts.map

package/dist/queues/index.d.ts.map

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