awaitly 1.31.1 → 1.32.0

package/dist/durable.d.cts

@@ -1,361 +1,8 @@
-import { ah as WorkflowEvent, q as UnexpectedError, ai as RunStep, R as Result } from './run-entry-C1uFytM6.cjs';
-import { S as SnapshotStore, c as WorkflowSnapshot, b as AnyResultFn, E as ErrorsOfDeps, d as WorkflowContext, e as WorkflowCancelledError } from './persistence-entry-CgVzswbg.cjs';
-export { b as isWorkflowCancelled } from './guards-PU64_GKv.cjs';
-import './types-DUWrNIJu.cjs';
-
-/**
- * awaitly/durable
- *
- * Durable execution with automatic state persistence.
- * Workflows automatically checkpoint after each keyed step and can resume from any point.
- */
-
-/**
- * Error returned when workflow cannot resume due to version mismatch.
- * Indicates the stored state was created with a different workflow version.
- * Fail-fast contract: bump version when you change step keys, order, or outputs.
- */
-type VersionMismatchError = {
-    type: "VERSION_MISMATCH";
-    /** Workflow execution ID */
-    workflowId: string;
-    /** Version stored in persisted state */
-    storedVersion: number;
-    /** Version requested by this run */
-    requestedVersion: number;
-    /** Guidance message with suggested actions */
-    message: string;
-    /** Use requestedVersion. */
-    currentVersion?: number;
-};
-/**
- * Error returned when workflow execution is rejected due to concurrent run.
- */
-type ConcurrentExecutionError = {
-    type: "CONCURRENT_EXECUTION";
-    /** The workflow ID that is already running */
-    workflowId: string;
-    /** Guidance message */
-    message: string;
-    /**
-     * Distinguishes in-process (activeWorkflows) from cross-process (lock held).
-     * Enables debuggability and branching without parsing the message.
-     */
-    reason?: "in-process" | "cross-process";
-};
-/**
- * Error returned when a persistence store operation fails.
- */
-type PersistenceError = {
-    type: "PERSISTENCE_ERROR";
-    /** The operation that failed */
-    operation: "load" | "save" | "delete";
-    /** The workflow ID */
-    workflowId: string;
-    /** The underlying error */
-    cause: unknown;
-    /** Guidance message */
-    message: string;
-};
-/**
- * Type guard to check if an error is a VersionMismatchError.
- */
-declare function isVersionMismatch(error: unknown): error is VersionMismatchError;
-/**
- * Type guard to check if an error is a ConcurrentExecutionError.
- */
-declare function isConcurrentExecution(error: unknown): error is ConcurrentExecutionError;
-/**
- * Type guard to check if an error is a PersistenceError.
- */
-declare function isPersistenceError(error: unknown): error is PersistenceError;
-/**
- * Optional cross-process lock interface.
- * When a store implements this, durable.run uses it to ensure only one process
- * runs a given workflow ID at a time (when allowConcurrent is false).
- *
- * Uses a lease (TTL) + owner token so a crashed worker does not wedge a workflow
- * indefinitely. Release must verify the owner token so one process never
- * unlocks another's lease.
- *
- * Mid-run lock loss (e.g. lease expires during a long workflow) is handled
- * adapter-side; core assumes the lock is held until release in finally.
- * Adapters may implement heartbeats/renewal.
- */
-interface WorkflowLock {
-    /**
-     * Try to acquire a lease for the workflow ID.
-     * @param id - Workflow execution ID
-     * @param options - Optional TTL for the lease (adapter default if omitted)
-     * @returns Owner token if acquired, null if already held by another
-     */
-    tryAcquire(id: string, options?: {
-        ttlMs?: number;
-    }): Promise<{
-        ownerToken: string;
-    } | null>;
-    /**
-     * Release the lease. Must verify owner token; no-op or ignore if token
-     * does not match (e.g. lease already expired or taken by another).
-     */
-    release(id: string, ownerToken: string): Promise<void>;
-}
-/**
- * Options for durable workflow execution.
- */
-interface DurableOptions<C = void> {
-    /**
-     * Unique workflow execution ID.
-     * Used as the key for state persistence.
-     *
-     * @example 'order-checkout-123', 'user-onboarding-abc'
-     */
-    id: string;
-    /**
-     * Snapshot store for persistence. Optional. When omitted, an in-memory store is used (per process).
-     * Same-process resume/retry works; state is lost on restart. Override with postgres/mongo/libsql for persistence.
-     *
-     * @example
-     * ```typescript
-     * // Zero-config: uses in-memory store (per process)
-     * await durable.run(deps, fn, { id: 'my-id' });
-     *
-     * // Override: pass a store for persistence across restarts
-     * import { postgres } from 'awaitly-postgres';
-     * const store = postgres('postgresql://localhost/mydb');
-     * await durable.run(deps, fn, { id: 'my-id', store });
-     * ```
-     */
-    store?: SnapshotStore;
-    /**
-     * Workflow logic version.
-     * If stored state has a different version, workflow will reject resume with VersionMismatchError
-     * unless onVersionMismatch is used to clear or migrate.
-     *
-     * Bump when you change step keys, reorder steps, or change step outputs in a way old checkpoints can't satisfy.
-     *
-     * @default 1
-     */
-    version?: number;
-    /**
-     * When stored state version differs from requested version, either throw (default), clear state and run from scratch, or supply migrated snapshot.
-     * Use for migration or one-off clear without wrapping durable.run.
-     *
-     * @default 'throw'
-     */
-    onVersionMismatch?: (ctx: {
-        id: string;
-        storedVersion: number;
-        requestedVersion: number;
-    }) => "throw" | "clear" | {
-        migratedSnapshot: WorkflowSnapshot;
-    } | Promise<"throw" | "clear" | {
-        migratedSnapshot: WorkflowSnapshot;
-    }>;
-    /**
-     * Allow concurrent executions with the same workflow ID.
-     * When `false` (default), a second run with the same ID will be rejected while one is active.
-     *
-     * @default false
-     */
-    allowConcurrent?: boolean;
-    /**
-     * Lease TTL in milliseconds for cross-process locking.
-     * Only used when the store implements WorkflowLock and allowConcurrent is false.
-     * A crashed worker's lease expires after this duration so the workflow can be picked up again.
-     *
-     * @default 60000 (1 minute)
-     */
-    lockTtlMs?: number;
-    /**
-     * Metadata to store alongside workflow state.
-     * Useful for debugging, auditing, or filtering workflows.
-     *
-     * @example { userId: 'user-123', source: 'api' }
-     */
-    metadata?: Record<string, unknown>;
-    /**
-     * External AbortSignal for workflow-level cancellation.
-     * Cancellation persists state up to the last completed step.
-     */
-    signal?: AbortSignal;
-    /**
-     * Create per-run context for event correlation.
-     */
-    createContext?: () => C;
-    /**
-     * Unified event stream for workflow and step lifecycle.
-     * Includes durable-specific events: `persist_success` and `persist_error`.
-     */
-    onEvent?: (event: DurableWorkflowEvent<unknown, C>, ctx: C) => void;
-    /**
-     * Handler for expected and unexpected errors.
-     */
-    onError?: (error: unknown, stepName?: string, ctx?: C) => void;
-}
-/**
- * Extended workflow event type that includes durable-specific events.
- * E is the deps error type - the full error type includes E | UnexpectedError.
- */
-type DurableWorkflowEvent<E, C = void> = WorkflowEvent<E | UnexpectedError, C> | {
-    type: "persist_success";
-    workflowId: string;
-    stepKey: string;
-    ts: number;
-    context?: C;
-} | {
-    type: "persist_error";
-    workflowId: string;
-    stepKey: string;
-    error: unknown;
-    ts: number;
-    context?: C;
-};
-/**
- * Options for bulk delete of workflow state.
- */
-interface DeleteStatesOptions {
-    /**
-     * Max number of concurrent delete calls when store has no deleteMany.
-     * @default 10
-     */
-    concurrency?: number;
-    /**
-     * When true, collect errors and return them; when false, throw on first error.
-     * @default true
-     */
-    continueOnError?: boolean;
-}
-/**
- * Result of bulk delete of workflow state.
- */
-interface DeleteStatesResult {
-    /** Number of entries successfully deleted. */
-    deleted: number;
-    /** Per-id errors when continueOnError was true and some deletes failed. */
-    errors?: Array<{
-        id: string;
-        error: unknown;
-    }>;
-}
-/**
- * Durable workflow execution namespace.
- */
-declare const durable: {
-    /**
-     * Execute a workflow with automatic state persistence.
-     *
-     * Features:
-     * - **Automatic checkpointing**: State is saved after each keyed step
-     * - **Crash recovery**: Resume from the last completed step on restart
-     * - **Version checking**: Reject resume if workflow logic version changed
-     * - **Concurrency control**: Prevent duplicate executions of the same workflow ID
-     * - **Cancellation support**: Integrates with AbortSignal for graceful shutdown
-     *
-     * ## How It Works
-     *
-     * 1. On start: Load existing state from store (if any)
-     * 2. Check version compatibility (reject if mismatch)
-     * 3. Pre-populate cache from loaded state (skip completed steps)
-     * 4. Execute workflow, persisting state after each keyed step
-     * 5. On completion: Delete stored state (clean up)
-     * 6. On error/cancellation: State remains for future resume
-     *
-     * ## Important Notes
-     *
-     * - **Only keyed steps are durable**: Use `{ key: 'step-name' }` option
-     * - **Steps should be idempotent**: They may be retried on resume
-     * - **Serialization**: State is JSON-serialized; complex objects may lose fidelity
-     *
-     * @param deps - Workflow dependencies (Result-returning functions)
-     * @param fn - Workflow function receiving ({ step, deps, ctx })
-     * @param options - Durable execution options
-     * @returns AsyncResult with workflow result or error
-     *
-     * @example
-     * ```typescript
-     * import { durable } from 'awaitly/durable';
-     *
-     * // Zero-config: uses in-memory store (per process)
-     * const result = await durable.run(
-     *   { fetchUser, createOrder, sendEmail },
-     *   async ({ step, deps: { fetchUser, createOrder, sendEmail } }) => {
-     *     const user = await step(() => fetchUser('123'), { key: 'fetch-user' });
-     *     const order = await step(() => createOrder(user), { key: 'create-order' });
-     *     await step(() => sendEmail(order), { key: 'send-email' });
-     *     return order;
-     *   },
-     *   { id: 'checkout-123' }
-     * );
-     *
-     * // Override: pass a store for persistence across restarts
-     * import { createMemoryStatePersistence } from 'awaitly/persistence';
-     * const store = createMemoryStatePersistence();
-     * await durable.run(deps, fn, { id: 'checkout-123', store });
-     *
-     * if (result.ok) {
-     *   console.log('Order completed:', result.value);
-     * } else if (isWorkflowCancelled(result.error)) {
-     *   console.log('Workflow cancelled at:', result.error.lastStepKey);
-     * }
-     * ```
-     */
-    run<const Deps extends Readonly<Record<string, AnyResultFn>>, T, C = void>(deps: Deps, fn: (context: {
-        step: RunStep<ErrorsOfDeps<Deps>>;
-        deps: Deps;
-        ctx: WorkflowContext<C>;
-    }) => T | Promise<T>, options: DurableOptions<C>): Promise<Result<T, ErrorsOfDeps<Deps> | UnexpectedError | WorkflowCancelledError | VersionMismatchError | ConcurrentExecutionError | PersistenceError, unknown>>;
-    /**
-     * Clear all persisted workflow state from the store.
-     * Use for admin/testing. If the store implements `clear()`, that is used;
-     * otherwise clears by listing and deleting in pages.
-     *
-     * @param store - Snapshot store
-     */
-    clearState(store: SnapshotStore): Promise<void>;
-    /**
-     * Check if a workflow ID has persisted state (can be resumed).
-     *
-     * @param store - Snapshot store
-     * @param id - Workflow execution ID
-     * @returns `true` if state exists, `false` otherwise (including on store errors)
-     */
-    hasState(store: SnapshotStore, id: string): Promise<boolean>;
-    /**
-     * Delete persisted state for a workflow (cancel resume capability).
-     * Deleting is effectively an ack/reset: the workflow can no longer resume from that state.
-     * If you delete while a run is in flight, the run continues; on success it may delete again (no-op) or save (recreating state).
-     * For multi-worker safety, prefer deleting only when the workflow is not running or when you hold the lock.
-     *
-     * @param store - Snapshot store
-     * @param id - Workflow execution ID
-     * @returns `true` on success, `false` on store errors
-     */
-    deleteState(store: SnapshotStore, id: string): Promise<boolean>;
-    /**
-     * Bulk delete persisted state for multiple workflow IDs (best-effort).
-     * Use for admin/cleanup. Deletes in a loop with optional concurrency.
-     *
-     * @param store - Snapshot store
-     * @param ids - Workflow execution IDs to delete
-     * @param options - Optional concurrency and error handling
-     * @returns Count of deleted entries and any errors when continueOnError is true
-     */
-    deleteStates(store: SnapshotStore, ids: string[], options?: DeleteStatesOptions): Promise<DeleteStatesResult>;
-    /**
-     * List workflow IDs with persisted state.
-     *
-     * @param store - Snapshot store
-     * @param options - Optional prefix and limit
-     * @returns Array of { id, updatedAt } entries
-     */
-    listPending(store: SnapshotStore, options?: {
-        prefix?: string;
-        limit?: number;
-    }): Promise<Array<{
-        id: string;
-        updatedAt: string;
-    }>>;
-};
-
-export { type ConcurrentExecutionError, type DeleteStatesOptions, type DeleteStatesResult, type DurableOptions, type DurableWorkflowEvent, type PersistenceError, SnapshotStore, type VersionMismatchError, WorkflowCancelledError, type WorkflowLock, durable, isConcurrentExecution, isPersistenceError, isVersionMismatch };
+export { C as ConcurrentExecutionError, D as DeleteStatesOptions, a as DeleteStatesResult, b as DurableOptions, c as DurableWorkflowEvent, I as IdempotencyConflictError, L as LeaseExpiredError, P as PersistenceError, V as VersionMismatchError, W as WorkflowLock, d as durable, i as isConcurrentExecution, e as isIdempotencyConflict, f as isLeaseExpired, g as isPersistenceError, h as isVersionMismatch } from './index-CQnpmUcC.cjs';
+export { S as SnapshotStore, W as WorkflowCancelledError } from './persistence-entry-jflY61az.cjs';
+export { i as isWorkflowCancelled } from './guards-B79mP5Q8.cjs';
+import './run-entry-yQu63Yj9.cjs';
+import './errors-entry-CMH73Eym.cjs';
+import './tagged-error.cjs';
+import './types-uR3JpwvF.cjs';
+import '@standard-schema/spec';