@ultimat3/jobs 1.0.0 → 1.2.0

package/src/scheduler.js

@@ -1,183 +0,0 @@
-// The `task` primitive + the `scheduler` role. A task NEVER does work: it enqueues jobs, so
-// retries, idempotency and observability all come from the job machinery instead of being
-// re-invented per cron.
-//
-// `tz` is required by the type. A cron without a timezone is a bug waiting for March: `0 3 *
-// * *` in a DST-observing zone runs twice or zero times on the switch day, and "the nightly
-// digest went out at 2am and again at 3am" is not a mystery anyone should have to debug.
-//
-// Exactly one node dispatches per tick, enforced by a Postgres advisory lock. Two schedulers
-// double-enqueue every task; the idempotency key would absorb it, but leader election means
-// the queue never sees the duplicate at all.
-import { assert, logger } from '@ultimat3/core';
-import { instant, nextCronOccurrence } from '@ultimat3/time';
-import { nowMs } from './clock';
-const defaultCronResolver = (cron, options) => 
-// Instant is a branded Date, so it satisfies CronResolver's Date return directly.
-nextCronOccurrence(cron, options.tz, instant(options.from));
-const registry = new Map();
-let anonymous = 0;
-export function task(definition) {
-    anonymous += 1;
-    const name = definition.name ?? `anonymous-task-${anonymous}`;
-    // Runtime backstop; the type already makes an omitted tz a build error.
-    assert(typeof definition.tz === 'string' && definition.tz.length > 0, `task "${name}" needs an explicit IANA tz — a cron without a timezone is a bug`, `add tz to task("${name}"), e.g. tz: 'UTC' — an unzoned cron silently drifts by an hour at every DST transition`);
-    const handle = {
-        kind: 'task',
-        name,
-        cron: definition.cron,
-        tz: definition.tz,
-        catchUp: definition.catchUp ?? 'skip',
-        maxCatchUp: definition.maxCatchUp ?? 10,
-        entries: () => definition.enqueue(),
-    };
-    registry.set(name, handle);
-    return handle;
-}
-export function nameTasks(record) {
-    for (const [exportName, handle] of Object.entries(record)) {
-        if (handle.name === exportName)
-            continue;
-        registry.delete(handle.name);
-        Object.defineProperty(handle, 'name', { value: exportName, configurable: true });
-        registry.set(exportName, handle);
-    }
-}
-export function registeredTasks() {
-    return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
-export function getTask(name) {
-    return registry.get(name);
-}
-export function resetTasks() {
-    registry.clear();
-    anonymous = 0;
-}
-/** Single-node default: always the leader. Multi-node uses `createPgLeader()`. */
-export function soleLeader() {
-    return {
-        acquire: () => Promise.resolve(true),
-        release: () => Promise.resolve(),
-    };
-}
-export function createMemorySchedulerState() {
-    const fired = new Map();
-    return {
-        lastFiredAt: (taskName) => Promise.resolve(fired.get(taskName)),
-        markFired(taskName, occurrenceMs) {
-            fired.set(taskName, occurrenceMs);
-            return Promise.resolve();
-        },
-    };
-}
-export function createScheduler(options) {
-    const state = options.state ?? createMemorySchedulerState();
-    const resolveCron = options.cron ?? defaultCronResolver;
-    const tickIntervalMs = options.tickIntervalMs ?? 1_000;
-    const leader = options.leader ?? soleLeader();
-    let timer;
-    let isLeader = false;
-    const nextRunFor = (handle, from) => resolveCron(handle.cron, { tz: handle.tz, from: from ?? new Date(nowMs(options.clock)) });
-    /**
-     * Occurrences in `(after, until]`. Walking forward from the last fire is what makes
-     * catch-up possible at all — a scheduler that only knows "now" cannot know what it missed.
-     */
-    const occurrencesSince = (handle, after, until) => {
-        const out = [];
-        let cursor = after;
-        for (let i = 0; i < handle.maxCatchUp; i += 1) {
-            const next = nextRunFor(handle, new Date(cursor)).getTime();
-            if (!Number.isFinite(next) || next <= cursor || next > until)
-                break;
-            out.push(next);
-            cursor = next;
-        }
-        return out;
-    };
-    const dispatch = async (handle, occurrenceMs, catchUp) => {
-        const jobs = [];
-        for (const [handleForJob, input] of handle.entries()) {
-            const result = await options.driver.enqueue({
-                name: handleForJob.name,
-                queue: handleForJob.queue,
-                input,
-                // Occurrence-scoped key: two schedulers, or a retried tick, cannot double-fire.
-                idempotencyKey: `${handle.name}:${occurrenceMs}:${handleForJob.idempotencyKeyFor(input)}`,
-                maxAttempts: handleForJob.retry.attempts,
-                runAt: occurrenceMs,
-            });
-            jobs.push({ job: handleForJob.name, result });
-        }
-        await state.markFired(handle.name, occurrenceMs);
-        logger.info('jobs.scheduler.dispatched', {
-            task: handle.name,
-            occurrence: new Date(occurrenceMs).toISOString(),
-            tz: handle.tz,
-            catchUp,
-            jobs: jobs.length,
-        });
-        return { task: handle.name, occurrenceMs, jobs, catchUp };
-    };
-    const tick = async () => {
-        if (!isLeader) {
-            isLeader = await leader.acquire();
-            if (!isLeader)
-                return [];
-        }
-        const at = nowMs(options.clock);
-        const tasks = options.tasks ?? registeredTasks();
-        const dispatched = [];
-        for (const handle of tasks) {
-            const last = await state.lastFiredAt(handle.name);
-            if (last === undefined) {
-                // First sight of this task: arm it, never fire retroactively for all of history.
-                await state.markFired(handle.name, nextRunFor(handle, new Date(at)).getTime() - 1);
-                continue;
-            }
-            const due = occurrencesSince(handle, last, at);
-            if (due.length === 0)
-                continue;
-            if (handle.catchUp === 'skip') {
-                const latest = due[due.length - 1];
-                if (latest !== undefined)
-                    dispatched.push(await dispatch(handle, latest, due.length > 1));
-                continue;
-            }
-            if (handle.catchUp === 'run-once') {
-                const first = due[0];
-                if (first !== undefined)
-                    dispatched.push(await dispatch(handle, first, due.length > 1));
-                continue;
-            }
-            for (const occurrence of due) {
-                dispatched.push(await dispatch(handle, occurrence, occurrence !== due[due.length - 1]));
-            }
-        }
-        return dispatched;
-    };
-    return {
-        start() {
-            if (timer !== undefined)
-                return;
-            timer = setInterval(() => {
-                void tick().catch((error) => {
-                    logger.error('jobs.scheduler.tick-failed', {
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                });
-            }, tickIntervalMs);
-            logger.info('jobs.scheduler.started', { tasks: (options.tasks ?? registeredTasks()).length });
-        },
-        async stop() {
-            if (timer !== undefined)
-                clearInterval(timer);
-            timer = undefined;
-            if (isLeader)
-                await leader.release();
-            isLeader = false;
-        },
-        tick,
-        nextRunFor,
-    };
-}
-//# sourceMappingURL=scheduler.js.map

package/src/scheduler.js.map

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

package/src/steps.d.ts

@@ -1,86 +0,0 @@
-import type { Clock } from '@ultimat3/core';
-import type { DurationInput } from './clock';
-export type StepStatus = 'completed' | 'sleeping' | 'waiting' | 'failed';
-export interface StepRecord {
-    readonly runId: string;
-    readonly name: string;
-    readonly status: StepStatus;
-    /** The memoized return value. Present only when `status === 'completed'`. */
-    readonly output?: unknown;
-    readonly startedAt: number;
-    readonly completedAt?: number;
-    /** Epoch ms at which a sleeping/waiting step becomes runnable. */
-    readonly wakeAt?: number;
-    readonly event?: string;
-    readonly correlationKey?: string;
-    readonly attempts: number;
-    readonly error?: string;
-}
-export interface StepStore {
-    get(runId: string, name: string): Promise<StepRecord | undefined>;
-    put(record: StepRecord): Promise<void>;
-    list(runId: string): Promise<readonly StepRecord[]>;
-    del(runId: string, name: string): Promise<void>;
-    clear(runId: string): Promise<void>;
-}
-/** The slice of the event bus a waiting step needs. Implemented by `events.ts`. */
-export interface EventLookup {
-    find(event: string, correlationKey: string | undefined, afterMs: number): Promise<{
-        readonly payload: unknown;
-        readonly publishedAt: number;
-    } | undefined>;
-}
-export interface WaitForEventOptions {
-    /** How long to wait before giving up. Default 24h. */
-    readonly timeout?: DurationInput;
-    /** Correlation key the published event must carry — usually an entity id. */
-    readonly match?: string;
-    /** Default false: a timeout resolves `undefined`. `true` fails the job with X_JOB_TIMEOUT. */
-    readonly required?: boolean;
-}
-export interface StepApi {
-    /** Run once, ever. On replay the persisted output is returned and `fn` is not called. */
-    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
-    /** Suspend the run. `sleep(duration)` derives the step name from the duration. */
-    sleep(name: string, duration: DurationInput): Promise<void>;
-    sleep(duration: DurationInput): Promise<void>;
-    waitForEvent<T>(name: string, event: string, options?: WaitForEventOptions): Promise<T | undefined>;
-}
-/**
- * Control flow, not a failure: it must never be logged as an error or counted as an attempt.
- * Branded by string rather than `instanceof` so two copies of this module still agree.
- */
-export declare class StepSuspension extends Error {
-    static readonly brand = "ultimate.jobs.suspension";
-    readonly brand: string;
-    readonly step: string;
-    readonly resumeAt: number;
-    readonly reason: 'sleep' | 'event';
-    constructor(input: {
-        step: string;
-        resumeAt: number;
-        reason: 'sleep' | 'event';
-    });
-}
-export declare function isStepSuspension(error: unknown): error is StepSuspension;
-export declare function createMemoryStepStore(): StepStore;
-export interface StepRunnerOptions {
-    readonly runId: string;
-    readonly jobName: string;
-    readonly store: StepStore;
-    readonly clock?: Clock;
-    readonly events?: EventLookup;
-    /** How long a waiting step stays parked between event polls. Default 30s. */
-    readonly eventPollMs?: number;
-    /** Per-step ceiling; the job-level timeout is enforced by the worker. */
-    readonly stepTimeoutMs?: number;
-}
-export interface StepRunner {
-    readonly step: StepApi;
-    /** Names used in THIS attempt, in order — the trace shown by `x jobs show`. */
-    usedNames(): readonly string[];
-    /** Names that were served from storage instead of executed. */
-    replayedNames(): readonly string[];
-}
-export declare function createStepRunner(options: StepRunnerOptions): StepRunner;
-//# sourceMappingURL=steps.d.ts.map

package/src/steps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["steps.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClE,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACpD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,IAAI,CACF,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,OAAO;IACtB,yFAAyF;IACzF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,kFAAkF;IAClF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,YAAY,CAAC,CAAC,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,MAAM,CAAC,QAAQ,CAAC,KAAK,8BAA8B;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAwB;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IAEnC,YAAY,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,EAM/E;CACF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED,wBAAgB,qBAAqB,IAAI,SAAS,CA+BjD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,+EAA+E;IAC/E,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;IAC/B,+DAA+D;IAC/D,aAAa,IAAI,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAyKvE"}

package/src/steps.js

@@ -1,227 +0,0 @@
-// Durable steps — the heart of the package. Each step's result is PERSISTED before the next
-// one starts, so a retry replays completed steps from storage instead of re-executing them:
-// the welcome email is not sent twice because step 3 failed. That makes step names the replay
-// key, which is why they must be deterministic and unique within a run (X_STEP_DUPLICATE).
-//
-// Suspension (sleep / waitForEvent) unwinds the run by throwing a StepSuspension. The worker
-// catches it and re-queues the job for `resumeAt` instead of holding a process for three days.
-import { logger } from '@ultimat3/core';
-import { nowMs, toMs } from './clock';
-import { JobTimeoutError, StepDuplicateError } from './errors';
-/**
- * Control flow, not a failure: it must never be logged as an error or counted as an attempt.
- * Branded by string rather than `instanceof` so two copies of this module still agree.
- */
-export class StepSuspension extends Error {
-    static brand = 'ultimate.jobs.suspension';
-    brand = StepSuspension.brand;
-    step;
-    resumeAt;
-    reason;
-    constructor(input) {
-        super(`step "${input.step}" suspended until ${new Date(input.resumeAt).toISOString()}`);
-        this.name = 'StepSuspension';
-        this.step = input.step;
-        this.resumeAt = input.resumeAt;
-        this.reason = input.reason;
-    }
-}
-export function isStepSuspension(error) {
-    return error instanceof Error && error.brand === StepSuspension.brand;
-}
-export function createMemoryStepStore() {
-    const byRun = new Map();
-    const runOf = (runId) => {
-        let run = byRun.get(runId);
-        if (run === undefined) {
-            run = new Map();
-            byRun.set(runId, run);
-        }
-        return run;
-    };
-    return {
-        get(runId, name) {
-            return Promise.resolve(byRun.get(runId)?.get(name));
-        },
-        put(record) {
-            runOf(record.runId).set(record.name, record);
-            return Promise.resolve();
-        },
-        list(runId) {
-            const records = [...(byRun.get(runId)?.values() ?? [])];
-            return Promise.resolve(records.sort((a, b) => a.startedAt - b.startedAt));
-        },
-        del(runId, name) {
-            byRun.get(runId)?.delete(name);
-            return Promise.resolve();
-        },
-        clear(runId) {
-            byRun.delete(runId);
-            return Promise.resolve();
-        },
-    };
-}
-export function createStepRunner(options) {
-    const { runId, jobName, store } = options;
-    const used = [];
-    const replayed = [];
-    const clock = options.clock;
-    const pollMs = options.eventPollMs ?? 30_000;
-    const claimName = (name) => {
-        if (used.includes(name))
-            throw new StepDuplicateError({ job: jobName, step: name });
-        used.push(name);
-    };
-    const now = () => nowMs(clock);
-    async function run(name, fn) {
-        claimName(name);
-        const existing = await store.get(runId, name);
-        if (existing?.status === 'completed') {
-            replayed.push(name);
-            return existing.output;
-        }
-        const startedAt = existing?.startedAt ?? now();
-        const attempts = (existing?.attempts ?? 0) + 1;
-        try {
-            const output = await withStepTimeout(fn(), options.stepTimeoutMs, () => new JobTimeoutError({ job: jobName, step: name, timeoutMs: options.stepTimeoutMs ?? 0 }));
-            // Persist BEFORE returning: a crash one line later must not re-run this step.
-            await store.put({
-                runId,
-                name,
-                status: 'completed',
-                output,
-                startedAt,
-                completedAt: now(),
-                attempts,
-            });
-            return output;
-        }
-        catch (error) {
-            if (isStepSuspension(error))
-                throw error;
-            await store.put({
-                runId,
-                name,
-                status: 'failed',
-                startedAt,
-                attempts,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw error;
-        }
-    }
-    async function sleep(a, b) {
-        // `sleep('3d')` — the duration doubles as the step name, which stays deterministic.
-        const name = b === undefined ? `sleep:${String(a)}` : String(a);
-        const duration = b === undefined ? a : b;
-        claimName(name);
-        const existing = await store.get(runId, name);
-        if (existing?.status === 'completed') {
-            replayed.push(name);
-            return;
-        }
-        const at = now();
-        if (existing?.status === 'sleeping' && existing.wakeAt !== undefined) {
-            if (existing.wakeAt <= at) {
-                await store.put({ ...existing, status: 'completed', completedAt: at });
-                return;
-            }
-            throw new StepSuspension({ step: name, resumeAt: existing.wakeAt, reason: 'sleep' });
-        }
-        const wakeAt = at + toMs(duration);
-        await store.put({
-            runId,
-            name,
-            status: 'sleeping',
-            startedAt: at,
-            wakeAt,
-            attempts: 1,
-        });
-        throw new StepSuspension({ step: name, resumeAt: wakeAt, reason: 'sleep' });
-    }
-    async function waitForEvent(name, event, waitOptions = {}) {
-        claimName(name);
-        const existing = await store.get(runId, name);
-        if (existing?.status === 'completed') {
-            replayed.push(name);
-            return existing.output;
-        }
-        const at = now();
-        const startedAt = existing?.startedAt ?? at;
-        const deadline = startedAt + toMs(waitOptions.timeout ?? 86_400_000);
-        const correlationKey = waitOptions.match;
-        const hit = await options.events?.find(event, correlationKey, startedAt);
-        if (hit !== undefined) {
-            await store.put({
-                runId,
-                name,
-                status: 'completed',
-                output: hit.payload,
-                startedAt,
-                completedAt: at,
-                event,
-                attempts: (existing?.attempts ?? 0) + 1,
-                ...(correlationKey === undefined ? {} : { correlationKey }),
-            });
-            return hit.payload;
-        }
-        if (at >= deadline) {
-            if (waitOptions.required === true) {
-                throw new JobTimeoutError({
-                    job: jobName,
-                    step: name,
-                    timeoutMs: toMs(waitOptions.timeout ?? 86_400_000),
-                });
-            }
-            logger.warn('jobs.step.wait-timeout', { job: jobName, step: name, event });
-            await store.put({
-                runId,
-                name,
-                status: 'completed',
-                output: undefined,
-                startedAt,
-                completedAt: at,
-                event,
-                attempts: (existing?.attempts ?? 0) + 1,
-            });
-            return undefined;
-        }
-        const resumeAt = Math.min(deadline, at + pollMs);
-        await store.put({
-            runId,
-            name,
-            status: 'waiting',
-            startedAt,
-            wakeAt: resumeAt,
-            event,
-            attempts: (existing?.attempts ?? 0) + 1,
-            ...(correlationKey === undefined ? {} : { correlationKey }),
-        });
-        throw new StepSuspension({ step: name, resumeAt, reason: 'event' });
-    }
-    const step = {
-        run,
-        sleep: sleep,
-        waitForEvent,
-    };
-    return {
-        step,
-        usedNames: () => [...used],
-        replayedNames: () => [...replayed],
-    };
-}
-function withStepTimeout(work, timeoutMs, error) {
-    if (timeoutMs === undefined || timeoutMs <= 0)
-        return Promise.resolve(work);
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(error()), timeoutMs);
-        Promise.resolve(work).then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (cause) => {
-            clearTimeout(timer);
-            reject(cause);
-        });
-    });
-}
-//# sourceMappingURL=steps.js.map

package/src/steps.js.map

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

package/src/worker.d.ts

@@ -1,68 +0,0 @@
-import type { Clock, Ctx } from '@ultimat3/core';
-import type { ClaimedJob, JobDriver, QueueStats } from './driver';
-import type { AnyJobHandle } from './job';
-import type { Limiter } from './limits';
-import type { EventLookup, StepRecord } from './steps';
-export type JobOutcome = 'completed' | 'suspended' | 'retried' | 'dead-lettered';
-export interface JobExecution {
-    readonly outcome: JobOutcome;
-    readonly jobId: string;
-    readonly job: string;
-    readonly attempt: number;
-    readonly durationMs: number;
-    readonly resumeAt?: number;
-    readonly error?: string;
-    readonly steps: readonly StepRecord[];
-    readonly replayed: readonly string[];
-}
-export interface ExecuteJobOptions {
-    readonly driver: JobDriver;
-    readonly claimed: ClaimedJob;
-    readonly handle: AnyJobHandle;
-    readonly ctx: Ctx;
-    readonly clock?: Clock;
-    readonly events?: EventLookup;
-}
-/**
- * Run one claimed job to completion, suspension or failure, and settle it with the driver.
- * Shared by the worker loop and `x jobs run` so both take exactly the same code path.
- */
-export declare function executeJob(options: ExecuteJobOptions): Promise<JobExecution>;
-export interface WorkerOptions {
-    readonly driver: JobDriver;
-    /** Queues this process serves. Default `['default']`. */
-    readonly queues?: readonly string[];
-    /** Slots per queue. A number applies to every queue. */
-    readonly concurrency?: number | Readonly<Record<string, number>>;
-    readonly limiter?: Limiter;
-    readonly clock?: Clock;
-    readonly events?: EventLookup;
-    /** Supplies the ambient Ctx for a job run; the app wires ALS + tenant here. */
-    readonly context: () => Ctx;
-    readonly visibilityTimeoutMs?: number;
-    readonly pollIntervalMs?: number;
-    readonly heartbeatIntervalMs?: number;
-    readonly workerId?: string;
-    /** Default true. Registers a SIGTERM drain via `onShutdown`. */
-    readonly drainOnShutdown?: boolean;
-}
-export interface WorkerStats {
-    readonly workerId: string;
-    readonly queues: readonly string[];
-    readonly state: 'idle' | 'running' | 'draining' | 'stopped';
-    readonly inFlight: number;
-    readonly processed: number;
-    readonly failed: number;
-    readonly suspended: number;
-    readonly deadLettered: number;
-    readonly queueDepth: readonly QueueStats[];
-}
-export interface Worker {
-    start(): void;
-    /** One claim+run round. Returns jobs processed. Tests drive this instead of the timer. */
-    tick(): Promise<readonly JobExecution[]>;
-    stop(reason?: string): Promise<void>;
-    stats(): Promise<WorkerStats>;
-}
-export declare function createWorker(options: WorkerOptions): Worker;
-//# sourceMappingURL=worker.d.ts.map

package/src/worker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["worker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAIlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGvD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAoFlF;AAkBD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,IAAI,IAAI,CAAC;IACd,0FAA0F;IAC1F,IAAI,IAAI,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAuK3D"}