@daloyjs/core 1.2.0 → 1.3.0

package/dist/jobs.d.ts

@@ -0,0 +1,665 @@
+/**
+ * Queue-agnostic background jobs for DaloyJS.
+ *
+ * Where {@link Scheduler} answers *“run this work in this process, on this
+ * clock”*, this module answers *“run this work somewhere,
+ * eventually”* — the three things a production job interface needs:
+ *
+ * - **A durable record.** {@link JobStore.put} persists a named JSON payload
+ *   so the work survives the HTTP request and the process that accepted it.
+ *   {@link MemoryJobStore} is correct for tests and single-process apps;
+ *   production supplies a shared adapter (Redis, Postgres, SQS) that
+ *   implements the same SPI. Core stays zero-dependency.
+ * - **At-least-once execution.** {@link createJobWorker} claims a lease,
+ *   runs an allowlisted handler, and completes or fails with bounded
+ *   retries (exponential backoff, full jitter) and a dead-letter status.
+ *   If the process dies after the side effect but before complete, the
+ *   lease expires and another worker may run it again — handlers must be
+ *   idempotent. {@link EnqueueOptions.idempotencyKey} collapses duplicate
+ *   producers (same key + same payload) the way HTTP `idempotency()`
+ *   collapses duplicate POSTs.
+ * - **A clean split from workflows.** This is not Temporal, Inngest, or
+ *   Vercel Workflow: there is no replay of TypeScript, no “world”,
+ *   and no `await sleep("7 days")` inside a function body. Delayed jobs and
+ *   retries are *new attempts of the same record*, not continuations.
+ *
+ * Pair `App.useJobs` to attach a queue (and optionally a worker that
+ * drains on graceful shutdown) and `App.cronEnqueue` when a cron tick
+ * should create a job instead of running the side effect in-process.
+ *
+ * @example
+ * ```ts
+ * import { createJobQueue, createJobWorker, MemoryJobStore } from "@daloyjs/core/jobs";
+ *
+ * const store = new MemoryJobStore();
+ * const queue = createJobQueue({ store });
+ * const worker = createJobWorker({
+ *   queue,
+ *   handlers: {
+ *     "email.welcome": async ({ job, signal }) => {
+ *       await sendEmail(job.payload, { signal });
+ *     },
+ *   },
+ * });
+ * await queue.enqueue({ name: "email.welcome", payload: { to: "a@b.c" } });
+ * await worker.runOnce();
+ * ```
+ *
+ * @module
+ * @since 1.3.0
+ */
+import type { SchedulerLogger, TimerFns } from "./scheduler.js";
+/**
+ * Machine-readable reason carried by a {@link JobConfigError}.
+ *
+ * - `invalid_name` — job or queue name failed the charset allowlist.
+ * - `invalid_payload` — payload (or result) is not plain JSON, or carries a
+ *   prototype-pollution key.
+ * - `payload_too_large` — serialized payload (or result) exceeds
+ *   {@link JobQueueOptions.payloadMaxBytes}.
+ * - `invalid_option` — a numeric/enum option failed validation, or a
+ *   lifecycle call was duplicated (`useJobs` twice, worker `start()` twice).
+ * - `unknown_handler` — no handler was registered for a claimed job's name.
+ * - `store_required` — an operation needs a queue that was never configured
+ *   (for example `app.cronEnqueue()` before `app.useJobs()`).
+ * - `store_full` — a bounded store rejected a new job because it is at
+ *   capacity.
+ *
+ * @since 1.3.0
+ */
+export type JobConfigErrorCode = "invalid_name" | "invalid_payload" | "payload_too_large" | "invalid_option" | "unknown_handler" | "store_required" | "store_full";
+/**
+ * Enqueue validation, unknown names at define-time, and bad options. An
+ * ordinary `Error` subclass (like `CronParseError`), not an `HttpError` —
+ * the jobs engine is a library, not a mounted route; map it to `400`/`422`
+ * in your own contract route if you expose enqueue over HTTP.
+ *
+ * @since 1.3.0
+ */
+export declare class JobConfigError extends Error {
+    /** Machine-readable failure reason; see {@link JobConfigErrorCode}. */
+    readonly code: JobConfigErrorCode;
+    constructor(code: JobConfigErrorCode, message: string);
+}
+/**
+ * Same idempotency key, different payload fingerprint. A key is permanently
+ * bound to the first payload it was enqueued with — mirroring the `422`
+ * key-reuse rule of the HTTP `idempotency()` middleware.
+ *
+ * @since 1.3.0
+ */
+export declare class JobIdempotencyConflictError extends Error {
+    /** Machine-readable failure reason. */
+    readonly code: "idempotency_conflict";
+    /** The idempotency key that was reused. */
+    readonly key: string;
+    /** The id of the job that already holds the key. */
+    readonly existingJobId: string;
+    constructor(key: string, existingJobId: string);
+}
+/**
+ * Thrown by a handler (or the worker, for an unknown job name) to signal
+ * “do not retry” — the job is dead-lettered on the spot, however
+ * many attempts remain. Analogous to a webhook SSRF / permanent-4xx failure.
+ *
+ * @since 1.3.0
+ */
+export declare class JobFatalError extends Error {
+    /** Machine-readable failure reason. */
+    readonly code: "fatal";
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * A claimed job exceeded its `timeoutMs`; the worker aborted the handler's
+ * signal and failed the job as retryable (unless the attempt budget is
+ * already exhausted).
+ *
+ * @since 1.3.0
+ */
+export declare class JobTimeoutError extends Error {
+    /** Machine-readable failure reason. */
+    readonly code: "timeout";
+    /** The per-attempt timeout that elapsed, in ms. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Lifecycle states of a {@link Job}. Terminal states (`completed`, `dead`,
+ * `cancelled`) have no outgoing transitions.
+ *
+ * ```text
+ * delayed  --(runAt <= now)--> queued
+ * queued   --claim--> running
+ * running  --complete--> completed   (terminal)
+ * running  --fail, attempts < max--> delayed (runAt = now + backoff)
+ * running  --fail, attempts >= max--> dead     (terminal)
+ * running  --JobFatalError--> dead             (terminal)
+ * running  --lease expired--> queued           (attempts already counted)
+ * queued/delayed/running --cancel--> cancelled (terminal)
+ * ```
+ *
+ * @since 1.3.0
+ */
+export type JobStatus = "queued" | "delayed" | "running" | "completed" | "dead" | "cancelled";
+/**
+ * A serializable snapshot of one unit of background work: an opaque named
+ * handler plus a plain-JSON payload. All fields are readonly snapshots —
+ * mutate nothing; stores return deep copies.
+ *
+ * @since 1.3.0
+ */
+export interface Job<P = unknown> {
+    /** Unique job id (`crypto.randomUUID()`). */
+    readonly id: string;
+    /** Named partition inside the store (`default`, `mail`, …). */
+    readonly queue: string;
+    /** Handler registry key. */
+    readonly name: string;
+    /** Plain-JSON handler input, validated at enqueue. */
+    readonly payload: P;
+    /** Current lifecycle state. */
+    readonly status: JobStatus;
+    /** How many times execution has started, including the current run. */
+    readonly attempts: number;
+    /** Maximum starts before the job dead-letters. */
+    readonly maxAttempts: number;
+    /** Earliest epoch ms the job may be claimed. */
+    readonly runAt: number;
+    /** Epoch ms the record was created. */
+    readonly createdAt: number;
+    /** Epoch ms the record last changed. */
+    readonly updatedAt: number;
+    /** Epoch ms the current lease ends, or `null` when not claimed. */
+    readonly leaseUntil: number | null;
+    /** Worker holding the lease, or `null` when not claimed. */
+    readonly lockedBy: string | null;
+    /** Lease duration granted per claim, in ms. */
+    readonly leaseMs: number;
+    /** Producer-supplied dedupe key, unique per queue, or `null`. */
+    readonly idempotencyKey: string | null;
+    /** Claim ordering: higher first. */
+    readonly priority: number;
+    /** Per-attempt timeout in ms; `0` disables. */
+    readonly timeoutMs: number;
+    /** Message of the most recent failure, or `null`. */
+    readonly lastError: string | null;
+    /** Epoch ms the job completed, or `null`. */
+    readonly completedAt: number | null;
+    /** Optional value stored at completion (the handler's return value). */
+    readonly result: unknown | null;
+    /** Optional tenant discriminator copied from enqueue (data, not authz). */
+    readonly tenant: string | null;
+}
+/**
+ * Input to {@link JobQueue.enqueue}. Only `name` and `payload` are required.
+ *
+ * @since 1.3.0
+ */
+export interface EnqueueOptions<P = unknown> {
+    /** Handler registry key: `^[a-zA-Z][a-zA-Z0-9._:-]{0,127}$`. */
+    name: string;
+    /** Plain-JSON handler input. Not a blob store — see `payloadMaxBytes`. */
+    payload: P;
+    /** Named partition. Default `"default"`. Charset `[a-zA-Z0-9_:-]{1,64}`. */
+    queue?: string;
+    /**
+     * Unique-per-queue dedupe key. A second enqueue with the same key and a
+     * deep-equal payload returns the existing job with `duplicate: true`; the
+     * same key with a different payload throws {@link JobIdempotencyConflictError}.
+     * Printable ASCII, 1–255 chars — build tenant-safe keys with
+     * {@link jobIdempotencyKey}.
+     */
+    idempotencyKey?: string;
+    /** Absolute earliest claim time. If in the future, status starts `delayed`. */
+    runAt?: number | Date;
+    /** Relative delay in ms. Ignored when {@link runAt} is set. */
+    delayMs?: number;
+    /** Claim ordering: higher first. Default `0`. */
+    priority?: number;
+    /** Maximum starts before dead-letter. Default `5`. */
+    maxAttempts?: number;
+    /** Per-attempt timeout in ms; `0` disables (dangerous). Default `30_000`. */
+    timeoutMs?: number;
+    /** Lease duration granted per claim in ms. Default `30_000`. */
+    leaseMs?: number;
+    /**
+     * Optional tenant discriminator copied onto the record for store key
+     * partitioning and logs. Validated against the same `[a-z0-9_-]` grammar
+     * as `tenancy()` ids. Jobs are not HTTP — pass `ctx.state.tenant`
+     * explicitly; nothing reads it for you.
+     */
+    tenant?: string;
+}
+/**
+ * Outcome of {@link JobQueue.enqueue} / {@link JobStore.put}.
+ *
+ * @since 1.3.0
+ */
+export interface EnqueueResult<P = unknown> {
+    /** The created job, or the existing one on an idempotency hit. */
+    job: Job<P>;
+    /** `true` when an existing job was returned due to an idempotency-key hit. */
+    duplicate: boolean;
+}
+/**
+ * Persistence SPI — the whole point of &ldquo;queue-agnostic&rdquo;. All
+ * durability lives behind this interface; durable backends (Redis, Postgres,
+ * SQS) are user-supplied adapters, never core dependencies. Every method may
+ * be synchronous or asynchronous, mirroring `IdempotencyStore`.
+ *
+ * Implementations must treat {@link JobStore.claim} and {@link JobStore.put}
+ * as atomic: two concurrent claims must never hand the same job to two
+ * workers, and two concurrent puts with the same idempotency key must never
+ * create two records.
+ *
+ * @since 1.3.0
+ */
+export interface JobStore {
+    /**
+     * Insert a new job. If `idempotencyKey` is set and a job already exists in
+     * this queue with that key, return the existing job with `duplicate: true`
+     * WITHOUT modifying it — even if it is terminal (first-writer-wins). If the
+     * existing payload fingerprint differs, throw
+     * {@link JobIdempotencyConflictError}.
+     *
+     * @param job - The fully-formed record to persist.
+     * @param fingerprint - SHA-256 hex of the serialized payload, or `null`
+     *   when no idempotency key is set. Provided so adapters can compare
+     *   payloads without re-hashing.
+     */
+    put(job: Job, fingerprint: string | null): Promise<EnqueueResult> | EnqueueResult;
+    /**
+     * Atomically select the next runnable job in `queue` (`queued`, or
+     * `delayed` with `runAt <= now`, or `running` with an expired lease),
+     * highest `priority` first, then oldest `runAt` / `createdAt`. Set
+     * `status = "running"`, `leaseUntil = now + job.leaseMs`,
+     * `lockedBy = workerId`, increment `attempts`, and return the claimed
+     * record. Return `null` when nothing is runnable.
+     *
+     * @param queue - The partition to claim from (never cross-queue).
+     * @param workerId - Identity written to `lockedBy` for fencing.
+     * @param now - Epoch ms, injected for deterministic leases.
+     */
+    claim(queue: string, workerId: string, now: number): Promise<Job | null> | Job | null;
+    /**
+     * Extend the lease of a running job still owned by `workerId`.
+     *
+     * @returns `false` when the lease was lost (not running, wrong owner, or
+     *   already expired) — the caller must stop touching the job.
+     */
+    heartbeat(id: string, workerId: string, leaseUntil: number, now: number): Promise<boolean> | boolean;
+    /**
+     * Mark a running job owned by `workerId` as `completed` (terminal),
+     * storing an optional result value.
+     *
+     * @returns `false` when the lease was lost — the worker must treat the
+     *   completion as not persisted.
+     */
+    complete(id: string, workerId: string, now: number, result: unknown | null): Promise<boolean> | boolean;
+    /**
+     * Record a failure for a running job owned by `workerId`. Attempts were
+     * already incremented at claim time: when `attempts >= maxAttempts` the
+     * store marks the job `dead`; otherwise it applies `next` (requeue
+     * `delayed` until `runAt`, or straight back to `queued`).
+     *
+     * @returns `false` when the lease was lost — another worker owns the job.
+     */
+    fail(id: string, workerId: string, error: string, next: {
+        status: "delayed" | "queued" | "dead";
+        runAt: number;
+    }, now: number): Promise<boolean> | boolean;
+    /**
+     * Cancel a non-terminal job. Terminal jobs return `false`.
+     */
+    cancel(id: string, now: number): Promise<boolean> | boolean;
+    /**
+     * Read one job by id, or `null` when unknown. Expired leases are reaped
+     * lazily before the snapshot is taken.
+     */
+    get(id: string, now: number): Promise<Job | null> | Job | null;
+    /**
+     * Optional filtered listing — required on {@link MemoryJobStore} for
+     * tests and inspection; production adapters may omit it.
+     */
+    list?(filter?: {
+        queue?: string;
+        status?: JobStatus | JobStatus[];
+        name?: string;
+        tenant?: string;
+    }): Promise<readonly Job[]> | readonly Job[];
+}
+/**
+ * Exponential backoff with full jitter, in ms — the same math as webhook
+ * delivery: `min(max, base * 2^(attempt-1))` scaled by a uniform random
+ * factor in `[0, 1)`. Exported for deterministic tests (inject
+ * `random: () => 1` for the unfuzzed ceiling).
+ *
+ * @param attempt - The attempt number that just failed (1-based; attempts
+ *   were already incremented at claim time).
+ * @param base - Base delay for the first retry, in ms.
+ * @param max - Upper bound on the un-jittered delay, in ms.
+ * @param random - Uniform source in `[0, 1)`.
+ * @returns The delay before the next attempt, in ms.
+ * @since 1.3.0
+ */
+export declare function computeBackoffMs(attempt: number, base: number, max: number, random: () => number): number;
+/**
+ * Options for {@link MemoryJobStore}.
+ *
+ * @since 1.3.0
+ */
+export interface MemoryJobStoreOptions {
+    /**
+     * Maximum jobs held (all statuses). Default `10_000`. On overflow of new
+     * puts the store first sweeps terminal records past their retention, then
+     * throws {@link JobConfigError} (`store_full`) — evicting queued work
+     * would be silent data loss.
+     */
+    capacity?: number;
+    /** Injectable clock (ms since epoch). Default {@link Date.now}. */
+    now?: () => number;
+    /**
+     * How long `completed` / `cancelled` records are retained after their last
+     * update, in ms. Default 24h. Terminal records are swept lazily on
+     * mutating operations.
+     */
+    retentionMs?: number;
+    /** How long `dead` records are retained for inspection, in ms. Default 7d. */
+    deadRetentionMs?: number;
+}
+/**
+ * In-memory {@link JobStore}. Correct for tests and single-process apps —
+ * a full implementation of the SPI, not a fake. **Not durable across
+ * processes** and invisible to other replicas: production deployments must
+ * supply a shared store (Redis, Postgres, SQS) through the same interface.
+ * `app.useJobs()` warns when it sees this store with production config.
+ *
+ * Payloads are held serialized and re-parsed with the prototype-pollution-safe
+ * `safeJsonParse` on every read, and every read returns a deep copy, so
+ * callers can never mutate store state.
+ *
+ * @since 1.3.0
+ */
+export declare class MemoryJobStore implements JobStore {
+    #private;
+    /**
+     * @param opts - Capacity, clock, and retention knobs.
+     * @throws {RangeError} when a numeric option is out of bounds.
+     */
+    constructor(opts?: MemoryJobStoreOptions);
+    /** The number of jobs currently held (all statuses). */
+    get size(): number;
+    /**
+     * @inheritDoc
+     * `_fingerprint` is part of the {@link JobStore} contract but unused here:
+     * the in-memory store compares serialized payloads directly.
+     */
+    put(job: Job, _fingerprint: string | null): EnqueueResult;
+    /** @inheritDoc */
+    claim(queue: string, workerId: string, now: number): Job | null;
+    /** @inheritDoc */
+    heartbeat(id: string, workerId: string, leaseUntil: number, now: number): boolean;
+    /** @inheritDoc */
+    complete(id: string, workerId: string, now: number, result: unknown | null): boolean;
+    /** @inheritDoc */
+    fail(id: string, workerId: string, error: string, next: {
+        status: "delayed" | "queued" | "dead";
+        runAt: number;
+    }, now: number): boolean;
+    /** @inheritDoc */
+    cancel(id: string, now: number): boolean;
+    /** @inheritDoc */
+    get(id: string, now: number): Job | null;
+    /** @inheritDoc */
+    list(filter?: {
+        queue?: string;
+        status?: JobStatus | JobStatus[];
+        name?: string;
+        tenant?: string;
+    }): Job[];
+    /** Test helper: every job, including terminal records. */
+    dump(): Job[];
+}
+/**
+ * Context handed to a {@link JobHandler} on each attempt.
+ *
+ * @since 1.3.0
+ */
+export interface JobContext<P = unknown> {
+    /** The claimed job snapshot (status `running`, `attempts` already incremented). */
+    readonly job: Job<P>;
+    /**
+     * Aborted when the per-attempt `timeoutMs` elapses, when the worker stops
+     * out of grace, or when the lease is lost to another worker. Forward it to
+     * every I/O call the handler makes.
+     */
+    readonly signal: AbortSignal;
+    /** 1-based attempt number (=== `job.attempts`). */
+    readonly attempt: number;
+    /**
+     * Extend the lease by another `leaseMs`. Long-running handlers should call
+     * this (or rely on the worker's automatic heartbeat every `leaseMs / 3`).
+     * If the lease is already lost, the handler's signal is aborted instead.
+     */
+    heartbeat(): Promise<void>;
+    /** Structured logger pre-bound with job id / name / queue / attempt. */
+    readonly log: SchedulerLogger;
+}
+/**
+ * A registered unit of work. Throw {@link JobFatalError} for permanent
+ * failures (no retry); any other throw — or a timeout — is retried with
+ * backoff until the attempt budget is spent, then the job is dead-lettered.
+ * The return value, when not `undefined`, is stored as {@link Job.result}
+ * under the same plain-JSON rules and size cap as payloads.
+ *
+ * Handlers must be idempotent: delivery is at-least-once. Pass an
+ * idempotency key through to downstream APIs (e.g. Stripe's
+ * `Idempotency-Key`) when a duplicate run would move money or send email.
+ *
+ * @since 1.3.0
+ */
+export type JobHandler<P = unknown> = (ctx: JobContext<P>) => unknown | Promise<unknown>;
+/**
+ * A handler registry: job name to handler. Closed at
+ * {@link createJobWorker} time — there is deliberately no dynamic
+ * registration and no `import(job.name)`, so a store record can never pick
+ * the code that runs it. Typed as `unknown` payload per entry; a
+ * heterogeneous map cannot unify payload types, so annotate each handler's
+ * `ctx` as {@link JobContext}`<YourPayload>` for narrowing.
+ *
+ * @since 1.3.0
+ */
+export type JobHandlerMap = {
+    [name: string]: JobHandler<unknown>;
+};
+/**
+ * Backoff policy shared by queue and worker.
+ *
+ * @since 1.3.0
+ */
+export interface JobBackoffOptions {
+    /** Base delay for the first retry, in ms. Default `200`. */
+    baseDelayMs: number;
+    /** Upper bound on the un-jittered delay, in ms. Default `60_000`. */
+    maxDelayMs: number;
+    /** Uniform jitter source in `[0, 1)`. Default {@link Math.random}. */
+    random: () => number;
+}
+/**
+ * Options for {@link createJobQueue}. Only `store` is required.
+ *
+ * @since 1.3.0
+ */
+export interface JobQueueOptions {
+    /** Persistence backend. {@link MemoryJobStore} for tests / single process. */
+    store: JobStore;
+    /** Structured logger for queue events. */
+    logger?: SchedulerLogger;
+    /** Injectable clock (ms since epoch). Default {@link Date.now}. */
+    now?: () => number;
+    /**
+     * Maximum UTF-8 bytes of the serialized payload (and of a completion
+     * result). Default `65536` (64 KiB) — jobs are not a blob store.
+     */
+    payloadMaxBytes?: number;
+    /** Partition used when {@link EnqueueOptions.queue} is omitted. Default `"default"`. */
+    defaultQueue?: string;
+    /** Default for {@link EnqueueOptions.maxAttempts}. Default `5`. */
+    defaultMaxAttempts?: number;
+    /** Default for {@link EnqueueOptions.timeoutMs}. Default `30_000`. */
+    defaultTimeoutMs?: number;
+    /** Default for {@link EnqueueOptions.leaseMs}. Default `30_000`. */
+    defaultLeaseMs?: number;
+    /** Retry backoff policy; see {@link JobBackoffOptions}. */
+    backoff?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        random?: () => number;
+    };
+}
+/**
+ * The producer façade: validate, serialize, fingerprint, enqueue, inspect,
+ * cancel. Split from {@link JobWorker} so HTTP replicas never poll. Safe to
+ * share across an entire process.
+ *
+ * @since 1.3.0
+ */
+export interface JobQueue {
+    /**
+     * Persist a job. Resolves with `duplicate: true` and the existing job when
+     * the idempotency key matches a prior enqueue of the same payload.
+     *
+     * @param opts - The job to create; see {@link EnqueueOptions}.
+     * @returns The created (or deduplicated) record.
+     * @throws {@link JobConfigError} on invalid names, options, non-JSON
+     *   payloads, oversized payloads, or a full bounded store.
+     * @throws {@link JobIdempotencyConflictError} when the key was already used
+     *   with a different payload.
+     */
+    enqueue<P>(opts: EnqueueOptions<P>): Promise<EnqueueResult<P>>;
+    /** Read one job by id, or `null`. */
+    get(id: string): Promise<Job | null>;
+    /** Cancel a non-terminal job. Resolves `false` for terminal/unknown ids. */
+    cancel(id: string): Promise<boolean>;
+    /** The underlying store, exposed for adapters and test inspection. */
+    readonly store: JobStore;
+    /** Partition used when enqueue omits `queue`. */
+    readonly defaultQueue: string;
+    /** Serialized-payload (and result) byte cap. */
+    readonly payloadMaxBytes: number;
+    /** Resolved retry backoff policy (used by workers on failure). */
+    readonly backoff: JobBackoffOptions;
+}
+/**
+ * Create a {@link JobQueue} over a {@link JobStore}. Validates all options
+ * eagerly (fail-fast config): numeric bounds throw `RangeError`, bad names
+ * throw {@link JobConfigError}, a missing store throws
+ * {@link JobConfigError} (`store_required`).
+ *
+ * @param opts - Queue configuration; see {@link JobQueueOptions}.
+ * @returns The producer façade.
+ * @since 1.3.0
+ */
+export declare function createJobQueue(opts: JobQueueOptions): JobQueue;
+/**
+ * Options for {@link createJobWorker}.
+ *
+ * @since 1.3.0
+ */
+export interface JobWorkerOptions {
+    /** The queue to claim from (provides the store and backoff policy). */
+    queue: JobQueue;
+    /**
+     * Handler registry, closed at construction. Keys must satisfy the job-name
+     * grammar; values are `JobHandler<any>` because a heterogeneous map cannot
+     * unify payload types — annotate each handler's ctx for narrowing.
+     */
+    handlers: Record<string, JobHandler<any>>;
+    /** Partitions to claim from, in order. Default `[queue.defaultQueue]`. */
+    queues?: string[];
+    /** Maximum jobs run concurrently. Default `1`. */
+    concurrency?: number;
+    /** Idle poll cadence in ms. Default `200`. */
+    pollIntervalMs?: number;
+    /** Fencing identity written to `lockedBy`. Default `crypto.randomUUID()`. */
+    workerId?: string;
+    /** Structured logger for worker lifecycle and failure events. */
+    logger?: SchedulerLogger;
+    /** Injectable timer primitives (shared shape with the Scheduler). */
+    timers?: TimerFns;
+    /** Injectable clock (ms since epoch). Default {@link Date.now}. */
+    now?: () => number;
+    /** Called when a job dead-letters (fatal, or budget exhausted). */
+    onDead?: (job: Job, error: string) => void | Promise<void>;
+    /** Called when a job completes. */
+    onComplete?: (job: Job) => void | Promise<void>;
+    /** Called on every non-fatal failure, before the next state is applied. */
+    onFail?: (job: Job, error: string, willRetry: boolean, delayMs?: number) => void | Promise<void>;
+}
+/**
+ * A claimed-job consumer: poll/claim/run/complete with leases, heartbeats,
+ * bounded retries, and graceful drain. Create it where a long-lived process
+ * exists (Node/Bun/Deno); on serverless isolates, enqueue only.
+ *
+ * @since 1.3.0
+ */
+export interface JobWorker {
+    /**
+     * Start the poll loop.
+     *
+     * @throws {@link JobConfigError} when the worker was already started (or
+     *   was started and then stopped — a stopped worker is spent).
+     */
+    start(): void;
+    /**
+     * Stop polling, wait up to `graceMs` for in-flight jobs to settle, then
+     * abort their signals and wait for them to unwind. Jobs aborted this way
+     * are failed back to the queue so another worker can pick them up.
+     * Idempotent.
+     */
+    stop(graceMs?: number): Promise<void>;
+    /** Point-in-time worker state. */
+    getState(): {
+        running: boolean;
+        inFlight: number;
+        workerId: string;
+    };
+    /**
+     * Test helper: claim and run one available job to settlement, whether or
+     * not the loop is started. Resolves `false` when nothing was claimable.
+     */
+    runOnce(): Promise<boolean>;
+}
+/**
+ * Create a {@link JobWorker}. The handler registry is frozen into a
+ * null-prototype map at construction: unknown job names dead-letter as
+ * poison pills instead of spinning, and no code path resolves a handler by
+ * dynamic lookup or import.
+ *
+ * @param opts - Worker configuration; see {@link JobWorkerOptions}.
+ * @returns The worker.
+ * @throws {RangeError} on out-of-bounds numeric options.
+ * @throws {@link JobConfigError} on a missing/empty registry or invalid
+ *   handler names.
+ * @since 1.3.0
+ */
+export declare function createJobWorker(opts: JobWorkerOptions): JobWorker;
+/**
+ * Build a tenant-safe idempotency key of the form `t/{tenant}/{name}/{key}`
+ * (or `g/{name}/{key}` when no tenant applies). Segments are validated so a
+ * key can never smuggle whitespace/control characters, newlines, or `..`
+ * into store keys or log lines, and tenant ids follow the `tenancy()`
+ * grammar — one tenant's keys can never collide with another's.
+ *
+ * @param parts - `name` is the job name; `key` is the caller's dedupe id
+ *   (user id, provider event id, order id, …); `tenant` scopes the key.
+ * @returns The composed key, at most 255 chars.
+ * @throws {@link JobConfigError} when a segment fails validation.
+ * @since 1.3.0
+ */
+export declare function jobIdempotencyKey(parts: {
+    tenant?: string;
+    name: string;
+    key: string;
+}): string;