@dudousxd/nestjs-durable-core 0.1.0

package/dist/duration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
+ * `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
+ */
+export declare function parseDuration(duration: string | number): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAS/D"}

package/dist/duration.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuration = parseDuration;
+const UNIT_MS = {
+    ms: 1,
+    s: 1_000,
+    sec: 1_000,
+    second: 1_000,
+    seconds: 1_000,
+    m: 60_000,
+    min: 60_000,
+    minute: 60_000,
+    minutes: 60_000,
+    h: 3_600_000,
+    hr: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+    days: 86_400_000,
+    w: 604_800_000,
+    week: 604_800_000,
+    weeks: 604_800_000,
+};
+/**
+ * Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
+ * `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
+ */
+function parseDuration(duration) {
+    if (typeof duration === 'number')
+        return duration;
+    const match = duration.trim().match(/^(\d+(?:\.\d+)?)\s*([a-z]+)$/i);
+    if (!match)
+        throw new Error(`invalid duration: ${duration}`);
+    const value = Number(match[1]);
+    const unit = (match[2] ?? '').toLowerCase();
+    const factor = UNIT_MS[unit];
+    if (factor === undefined)
+        throw new Error(`unknown duration unit: ${unit}`);
+    return value * factor;
+}
+//# sourceMappingURL=duration.js.map

package/dist/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":";;AA0BA,sCASC;AAnCD,MAAM,OAAO,GAA2B;IACtC,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,KAAK;IACR,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,CAAC,EAAE,MAAM;IACT,GAAG,EAAE,MAAM;IACX,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,MAAM;IACf,CAAC,EAAE,SAAS;IACZ,EAAE,EAAE,SAAS;IACb,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,CAAC,EAAE,UAAU;IACb,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,UAAU;IAChB,CAAC,EAAE,WAAW;IACd,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,WAAW;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,aAAa,CAAC,QAAyB;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IAC5E,OAAO,KAAK,GAAG,MAAM,CAAC;AACxB,CAAC"}

package/dist/engine.d.ts

@@ -0,0 +1,115 @@
+import type { EngineListener, RunResult, StateStore, StepError, Transport, WorkflowCtx } from './interfaces';
+type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
+export interface WorkflowEngineDeps {
+    store: StateStore;
+    transport?: Transport;
+    /** Epoch-ms clock; injectable for tests. Defaults to `Date.now`. */
+    clock?: () => number;
+    /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
+    instanceId?: string;
+    /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
+    leaseMs?: number;
+}
+/**
+ * The orchestrator. Owns workflow state and replays runs deterministically: each step's
+ * result is checkpointed, so on resume a completed step returns its saved output instead of
+ * re-executing. Remote steps are dispatched over the Transport; their results checkpoint the
+ * same way local steps do.
+ */
+export declare class WorkflowEngine {
+    private readonly store;
+    private readonly transport?;
+    private readonly clock;
+    private readonly instanceId;
+    private readonly leaseMs;
+    /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
+    private readonly workflows;
+    /** The newest registered version per workflow name — used to `start` new runs. */
+    private readonly latest;
+    /** In-flight remote steps awaiting a worker result, keyed by stepId. */
+    private readonly pending;
+    /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+    private readonly heartbeatResets;
+    private readonly listeners;
+    /** Executions currently in flight, so a graceful shutdown can wait for them to settle. */
+    private readonly inflight;
+    private draining;
+    constructor(deps: WorkflowEngineDeps);
+    /**
+     * Register a workflow version. Register multiple versions of the same name to keep in-flight
+     * runs working across a breaking change: old runs resume on the version they started on, new
+     * runs start on the newest registered version.
+     */
+    register(name: string, version: string, fn: WorkflowFn): void;
+    /** Subscribe to lifecycle events. Returns an unsubscribe function. */
+    subscribe(listener: EngineListener): () => void;
+    private emit;
+    start(workflow: string, input: unknown, runId: string): Promise<RunResult>;
+    resume(runId: string): Promise<RunResult>;
+    /** Track an in-flight execution so {@link drain} can wait for it. */
+    private track;
+    /**
+     * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
+     * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
+     * deploy hands off cleanly instead of leaving runs to the lease timeout.
+     */
+    drain(timeoutMs?: number): Promise<void>;
+    /**
+     * Resume every run left incomplete by a crash or deploy. Called on boot. Completed steps
+     * replay from their checkpoints, so only the work that had not finished runs again.
+     */
+    recoverIncomplete(): Promise<RunResult[]>;
+    /**
+     * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
+     * boot. A run still not due re-suspends cheaply without running new work.
+     */
+    resumeDueTimers(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Resume each run only if this instance can acquire its recovery lease — so when several
+     * replicas recover or poll at once, each run is picked up by exactly one of them.
+     */
+    private resumeLeased;
+    /**
+     * Deliver an external signal to the run waiting on `token` and resume it with `payload`.
+     * Returns the run result, or null if no run is waiting for that token.
+     */
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
+    /**
+     * Report the result of a `ctx.task(name, …)` back to its run (async completion). The external
+     * worker that the task dispatched to calls this when done; the run resumes with `result`. Returns
+     * null if no run is waiting on the task (e.g. a duplicate/late delivery) — a safe no-op.
+     */
+    completeTask(runId: string, name: string, result: unknown): Promise<RunResult | null>;
+    /** Report that a `ctx.task` failed — the run resumes and throws a FatalError at the task. */
+    failTask(runId: string, name: string, error: string): Promise<RunResult | null>;
+    /**
+     * Notify a parent that's waiting on `runId` as a child of its terminal outcome (the `ctx.child`
+     * rendezvous). A no-op when no parent is waiting, so `execute()` can call it on every run without
+     * knowing about the child feature.
+     */
+    private notifyParent;
+    /** Cancel a run (e.g. from the dashboard). Returns null if the run does not exist. */
+    cancel(runId: string): Promise<RunResult | null>;
+    /** Checkpoint a finished step and announce it — the two things that must always happen together. */
+    private completeStep;
+    /** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
+    private failStep;
+    private execute;
+    private makeCtx;
+    /** Persist a completed timer checkpoint (a durable sleep / signal deadline) at a logical position. */
+    private recordTimer;
+    private callRemote;
+    /**
+     * Await a remote result, but reject with `RemoteStepTimeout` if neither the result nor a heartbeat
+     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`) rearms the
+     * window, so a worker that keeps beating stays alive past `timeoutMs`.
+     */
+    private awaitWithHeartbeat;
+}
+/** Raised inside the workflow when a remote worker reports a step failure. */
+export declare class RemoteStepError extends Error {
+    readonly stepError?: StepError;
+    constructor(stepError?: StepError);
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

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