experimental-ash 0.22.2 → 0.23.0

package/dist/src/compiled/@workflow/core/serialization.d.ts

@@ -0,0 +1,329 @@
+import { type CryptoKey } from './encryption.js';
+import { decrypt, type EncryptionKeyParam, encrypt } from './serialization/encryption.js';
+import { decodeFormatPrefix, encodeWithFormatPrefix, isEncrypted, peekFormatPrefix } from './serialization/format.js';
+import { type FormatPrefix, isFormatPrefix, SerializationFormat } from './serialization/types.js';
+export { SerializationFormat, type FormatPrefix, isFormatPrefix, encodeWithFormatPrefix, decodeFormatPrefix, peekFormatPrefix, isEncrypted, encrypt, decrypt, type EncryptionKeyParam, };
+export type SerializationFormatType = (typeof SerializationFormat)[keyof typeof SerializationFormat];
+/**
+ * Detect if a readable stream is a byte stream.
+ *
+ * @param stream
+ * @returns `"bytes"` if the stream is a byte stream, `undefined` otherwise
+ */
+export declare function getStreamType(stream: ReadableStream): 'bytes' | undefined;
+export declare function getSerializeStream(reducers: Partial<Reducers>, cryptoKey: EncryptionKeyParam): TransformStream<any, Uint8Array>;
+export declare function getDeserializeStream(revivers: Partial<Revivers>, cryptoKey: EncryptionKeyParam): TransformStream<Uint8Array, any>;
+export declare class WorkflowServerReadableStream extends ReadableStream<Uint8Array> {
+    #private;
+    constructor(runId: string, name: string, startIndex?: number);
+}
+export declare class WorkflowServerWritableStream extends WritableStream<Uint8Array> {
+    constructor(runId: string, name: string);
+}
+export type { Reducers, Revivers, SerializableSpecial, } from './serialization/types.js';
+import type { Reducers, Revivers } from './serialization/types.js';
+/**
+ * Reducers for serialization boundary from the client side, passing arguments
+ * to the workflow handler.
+ *
+ * @param global
+ * @param ops
+ * @returns
+ */
+export declare function getExternalReducers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam): Partial<Reducers>;
+/**
+ * Reducers for serialization boundary from within the workflow execution
+ * environment, passing return value to the client side and into step arguments.
+ *
+ * @param global
+ * @returns
+ */
+export declare function getWorkflowReducers(global?: Record<string, any>): Partial<Reducers>;
+/**
+ * Cancel dangling abort-stream readers on any AbortController instances found
+ * in the hydrated step arguments. Called after the step function returns
+ * (success or failure) to prevent reader promises from keeping the serverless
+ * function alive indefinitely.
+ */
+export declare function cancelAbortReaders(...values: unknown[]): void;
+/**
+ * Base revivers shared across all serialization boundaries.
+ * Composes: class + common revivers from the modular modules.
+ *
+ * This is exported because serialization-format.ts and other files reference it.
+ */
+export declare function getCommonRevivers(global?: Record<string, any>): {
+    ArrayBuffer?: ((value: string) => any) | undefined;
+    BigInt?: ((value: string) => any) | undefined;
+    BigInt64Array?: ((value: string) => any) | undefined;
+    BigUint64Array?: ((value: string) => any) | undefined;
+    Date?: ((value: string) => any) | undefined;
+    DOMException?: ((value: {
+        message: string;
+        name: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    FatalError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    Float32Array?: ((value: string) => any) | undefined;
+    Float64Array?: ((value: string) => any) | undefined;
+    Error?: ((value: {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    EvalError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    Headers?: ((value: [string, string][]) => any) | undefined;
+    Int8Array?: ((value: string) => any) | undefined;
+    Int16Array?: ((value: string) => any) | undefined;
+    Int32Array?: ((value: string) => any) | undefined;
+    Map?: ((value: [any, any][]) => any) | undefined;
+    RangeError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    ReadableStream?: ((value: {
+        name: string;
+        type?: "bytes";
+        startIndex?: number;
+    } | {
+        bodyInit: any;
+    }) => any) | undefined;
+    ReferenceError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    RegExp?: ((value: {
+        source: string;
+        flags: string;
+    }) => any) | undefined;
+    RetryableError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        retryAfter: number;
+    }) => any) | undefined;
+    Request?: ((value: {
+        method: string;
+        url: string;
+        headers: Headers;
+        body: Request["body"];
+        duplex: Request["duplex"];
+        responseWritable?: WritableStream<Response>;
+        signal?: AbortSignal;
+    }) => any) | undefined;
+    Response?: ((value: {
+        type: Response["type"];
+        url: string;
+        status: number;
+        statusText: string;
+        headers: Headers;
+        body: Response["body"];
+        redirected: boolean;
+    }) => any) | undefined;
+    Class?: ((value: {
+        classId: string;
+    }) => any) | undefined;
+    Instance?: ((value: {
+        classId: string;
+        data: unknown;
+    }) => any) | undefined;
+    Set?: ((value: any[]) => any) | undefined;
+    SyntaxError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    StepFunction?: ((value: {
+        stepId: string;
+        closureVars?: Record<string, any>;
+        boundThis?: unknown;
+        boundArgs?: unknown[];
+    }) => any) | undefined;
+    TypeError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    URIError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    URL?: ((value: string) => any) | undefined;
+    WorkflowFunction?: ((value: {
+        workflowId: string;
+    }) => any) | undefined;
+    URLSearchParams?: ((value: string) => any) | undefined;
+    Uint8Array?: ((value: string) => any) | undefined;
+    Uint8ClampedArray?: ((value: string) => any) | undefined;
+    Uint16Array?: ((value: string) => any) | undefined;
+    Uint32Array?: ((value: string) => any) | undefined;
+    AggregateError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        errors: unknown[];
+    }) => any) | undefined;
+    WritableStream?: ((value: {
+        name: string;
+    }) => any) | undefined;
+    AbortController?: ((value: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    }) => any) | undefined;
+    AbortSignal?: ((value: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    }) => any) | undefined;
+};
+/**
+ * Revivers for deserialization boundary from the client side,
+ * receiving the return value from the workflow handler.
+ *
+ * @param global
+ * @param ops
+ * @param runId
+ */
+export declare function getExternalRevivers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam): Partial<Revivers>;
+/**
+ * Revivers for deserialization boundary from within the workflow execution
+ * environment, receiving arguments from the client side, and return values
+ * from the steps.
+ *
+ * @param global
+ * @returns
+ */
+export declare function getWorkflowRevivers(global?: Record<string, any>): Partial<Revivers>;
+/**
+ * Encrypt data if the world supports encryption.
+ * Returns original data if encryption is not available.
+ *
+ * @deprecated Use `encrypt` from `./serialization/encryption.js` instead.
+ */
+export declare function maybeEncrypt(data: Uint8Array, key: CryptoKey | undefined): Promise<Uint8Array>;
+/**
+ * Decrypt data if it has the 'encr' prefix.
+ *
+ * @deprecated Use `decrypt` from `./serialization/encryption.js` instead.
+ */
+export declare function maybeDecrypt(data: Uint8Array | unknown, key: CryptoKey | undefined): Promise<Uint8Array | unknown>;
+/**
+ * Called from the `start()` function to serialize the workflow arguments
+ * into a format that can be saved to the database and then hydrated from
+ * within the workflow execution environment.
+ */
+export declare function dehydrateWorkflowArguments(value: unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+/**
+ * Called from workflow execution environment to hydrate the workflow
+ * arguments from the database at the start of workflow execution.
+ */
+export declare function hydrateWorkflowArguments(value: Uint8Array | unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+/**
+ * Dehydrate workflow return value for storage.
+ */
+export declare function dehydrateWorkflowReturnValue(value: unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+/**
+ * Called from the client side to hydrate the workflow return value
+ * of a completed workflow run.
+ */
+export declare function hydrateWorkflowReturnValue(value: Uint8Array | unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+/**
+ * Called from the workflow handler when a step is being created.
+ * Dehydrates values from within the workflow execution environment.
+ */
+export declare function dehydrateStepArguments(value: unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+/**
+ * Called from the step handler to hydrate the arguments of a step
+ * from the database at the start of the step execution.
+ */
+export declare function hydrateStepArguments(value: Uint8Array | unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+/**
+ * Called from the step handler when a step has completed.
+ * Dehydrates values from within the step execution environment.
+ */
+export declare function dehydrateStepReturnValue(value: unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+/**
+ * Called from the step handler when a step throws. Dehydrates the thrown
+ * value from within the step execution environment into a format that can
+ * be saved to the database in a `step_failed` or `step_retrying` event.
+ *
+ * Any JavaScript value can be thrown (strings, numbers, objects, Errors,
+ * Error subclasses), so the same serialization pipeline used for step
+ * arguments and return values is applied here.
+ *
+ * @param value - The thrown value to serialize (can be any type)
+ * @param runId - Run ID for encryption context
+ * @param key - Encryption key (undefined to skip encryption)
+ * @param ops - Promise array for stream operations
+ * @param global - Global object for serialization context
+ * @returns The dehydrated value as binary data (Uint8Array) with format prefix
+ */
+export declare function dehydrateStepError(value: unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<any>[], global?: Record<string, any>): Promise<Uint8Array>;
+/**
+ * Called from the workflow handler when replaying the event log of a
+ * `step_failed` or `step_retrying` event. Hydrates the thrown value from
+ * the database so the workflow can see the original thrown value.
+ *
+ * @param value - Binary serialized data (Uint8Array) with format prefix
+ * @param runId - Run ID for decryption context
+ * @param key - Encryption key (undefined to skip decryption)
+ * @param global - Global object for deserialization context
+ * @param extraRevivers - Additional revivers for custom types
+ * @returns The hydrated thrown value, ready to reject the step promise
+ */
+export declare function hydrateStepError(value: Uint8Array | unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<unknown>;
+/**
+ * Called from the workflow handler when the workflow itself throws.
+ * Dehydrates the thrown value from within the workflow execution environment
+ * into a format that can be saved to the database in a `run_failed` event.
+ *
+ * @param value - The thrown value to serialize (can be any type)
+ * @param runId - Run ID for encryption context
+ * @param key - Encryption key (undefined to skip encryption)
+ * @param global - Global object for serialization context
+ * @returns The dehydrated value as binary data (Uint8Array) with format prefix
+ */
+export declare function dehydrateRunError(value: unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>): Promise<Uint8Array>;
+/**
+ * Called from the client side (or observability tools) to hydrate the run
+ * error value of a failed workflow run.
+ *
+ * @param value - Binary serialized data (Uint8Array) with format prefix
+ * @param runId - Run ID for decryption context
+ * @param key - Encryption key (undefined to skip decryption)
+ * @param ops - Promise array for stream operations
+ * @param global - Global object for deserialization context
+ * @param extraRevivers - Additional revivers for custom types
+ * @returns The hydrated thrown value, ready to be consumed by the client
+ */
+export declare function hydrateRunError(value: Uint8Array | unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<unknown>;
+/**
+ * Called from the workflow handler when replaying the event log of a `step_completed` event.
+ * Hydrates the return value of a step from the database.
+ *
+ * @param value - Binary serialized data (Uint8Array) with format prefix
+ * @param runId - Run ID for decryption context
+ * @param key - Encryption key (undefined to skip decryption)
+ * @param global - Global object for deserialization context
+ * @param extraRevivers - Additional revivers for custom types
+ * Called from the workflow handler when replaying the event log
+ * of a `step_completed` event.
+ */
+export declare function hydrateStepReturnValue(value: Uint8Array | unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/src/compiled/@workflow/core/sleep.d.ts

@@ -0,0 +1,33 @@
+import type { StringValue } from './_ms.js';
+/**
+ * Sleep within a workflow for a given duration.
+ *
+ * This is a built-in runtime function that uses timer events in the event log.
+ *
+ * @param duration - The duration to sleep for, this is a string in the format
+ * of `"1000ms"`, `"1s"`, `"1m"`, `"1h"`, or `"1d"`.
+ * @overload
+ * @returns A promise that resolves when the sleep is complete.
+ */
+export declare function sleep(duration: StringValue): Promise<void>;
+/**
+ * Sleep within a workflow until a specific date.
+ *
+ * This is a built-in runtime function that uses timer events in the event log.
+ *
+ * @param date - The date to sleep until, this must be a future date.
+ * @overload
+ * @returns A promise that resolves when the sleep is complete.
+ */
+export declare function sleep(date: Date): Promise<void>;
+/**
+ * Sleep within a workflow for a given duration in milliseconds.
+ *
+ * This is a built-in runtime function that uses timer events in the event log.
+ *
+ * @param durationMs - The duration to sleep for in milliseconds.
+ * @overload
+ * @returns A promise that resolves when the sleep is complete.
+ */
+export declare function sleep(durationMs: number): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/src/compiled/@workflow/core/source-map.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Remaps an error stack trace using inline source maps to show original source locations.
+ *
+ * @param stack - The error stack trace to remap
+ * @param filename - The workflow filename to match in stack frames
+ * @param workflowCode - The workflow bundle code containing inline source maps
+ * @returns The remapped stack trace with original source locations
+ */
+export declare function remapErrorStack(stack: string, filename: string, workflowCode: string): string;
+//# sourceMappingURL=source-map.d.ts.map

package/dist/src/compiled/@workflow/core/step/context-storage.d.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { CryptoKey } from '../encryption.js';
+import type { WorkflowMetadata } from '../workflow/get-workflow-metadata.js';
+import type { StepMetadata } from './get-step-metadata.js';
+export type StepContext = {
+    stepMetadata: StepMetadata;
+    workflowMetadata: WorkflowMetadata;
+    ops: Promise<void>[];
+    closureVars?: Record<string, any>;
+    encryptionKey?: CryptoKey;
+};
+export declare const contextStorage: AsyncLocalStorage<StepContext>;
+//# sourceMappingURL=context-storage.d.ts.map

package/dist/src/compiled/@workflow/core/step/get-closure-vars.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the closure variables for the current step function.
+ * This is an internal function used by the SWC transform to access
+ * variables from the parent workflow scope.
+ *
+ * @internal
+ */
+export declare function __private_getClosureVars(): Record<string, any>;
+//# sourceMappingURL=get-closure-vars.d.ts.map

package/dist/src/compiled/@workflow/core/step/get-step-metadata.d.ts

@@ -0,0 +1,42 @@
+export interface StepMetadata {
+    /**
+     * The name of the step.
+     */
+    stepName: string;
+    /**
+     * Unique identifier for the currently executing step.
+     * Useful to use as part of an idempotency key for critical
+     * operations that must only be executed once (such as charging a customer).
+     *
+     * @remarks
+     *
+     * Only available inside a step function.
+     * Accessing this property in a workflow function will throw an error.
+     */
+    stepId: string;
+    /**
+     * Timestamp when the current step started.
+     *
+     * @remarks
+     *
+     * Only available inside a step function.
+     * Accessing this property in a workflow function will throw an error.
+     */
+    stepStartedAt: Date;
+    /**
+     * The number of times the current step has been executed. This will increase with each retry.
+     *
+     * @remarks
+     *
+     * Only available inside a step function.
+     * Accessing this property in a workflow function will throw an error.
+     */
+    attempt: number;
+}
+/**
+ * Returns metadata available in the current step function.
+ * It uses `AsyncLocalStorage` to store the context and
+ * retrieve it in the step function.
+ */
+export declare function getStepMetadata(): StepMetadata;
+//# sourceMappingURL=get-step-metadata.d.ts.map

package/dist/src/compiled/@workflow/core/step/get-workflow-metadata.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowMetadata } from '../workflow/get-workflow-metadata.js';
+export type { WorkflowMetadata };
+/**
+ * Returns metadata available in the current workflow run inside a step function.
+ */
+export declare function getWorkflowMetadata(): WorkflowMetadata;
+//# sourceMappingURL=get-workflow-metadata.d.ts.map

package/dist/src/compiled/@workflow/core/step/writable-stream.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The options for {@link getWritable}.
+ */
+export interface WorkflowWritableStreamOptions {
+    /**
+     * An optional namespace to distinguish between multiple streams associated
+     * with the same workflow run.
+     */
+    namespace?: string;
+}
+/**
+ * Retrieves a writable stream that is associated with the current workflow.
+ *
+ * The writable stream is intended to be used within step functions to write
+ * data that can be read outside the workflow by using the readable method of getRun.
+ *
+ * @param options - Optional configuration for the writable stream
+ * @returns The writable stream associated with the current workflow run
+ * @throws Error if called outside a workflow or step function
+ */
+export declare function getWritable<W = any>(options?: WorkflowWritableStreamOptions): WritableStream<W>;
+//# sourceMappingURL=writable-stream.d.ts.map

package/dist/src/compiled/@workflow/core/step.d.ts

@@ -0,0 +1,4 @@
+import { type WorkflowOrchestratorContext } from './private.js';
+import type { Serializable } from './schemas.js';
+export declare function createUseStep(ctx: WorkflowOrchestratorContext): <Args extends Serializable[], Result>(stepName: string, closureVarsFn?: () => Record<string, Serializable>) => (this: unknown, ...args: Args) => Promise<Result>;
+//# sourceMappingURL=step.d.ts.map

package/dist/src/compiled/@workflow/core/symbols.d.ts

@@ -0,0 +1,20 @@
+export declare const WORKFLOW_USE_STEP: unique symbol;
+export declare const WORKFLOW_CREATE_HOOK: unique symbol;
+export declare const WORKFLOW_SLEEP: unique symbol;
+export declare const WORKFLOW_CONTEXT: unique symbol;
+export declare const WORKFLOW_GET_STREAM_ID: unique symbol;
+export declare const STABLE_ULID: unique symbol;
+export declare const STREAM_NAME_SYMBOL: unique symbol;
+export declare const STREAM_TYPE_SYMBOL: unique symbol;
+export declare const BODY_INIT_SYMBOL: unique symbol;
+export declare const WEBHOOK_RESPONSE_WRITABLE: unique symbol;
+/**
+ * Symbol used to store the class registry on globalThis in workflow mode.
+ * This allows the deserializer to find classes by classId in the VM context.
+ */
+export declare const WORKFLOW_CLASS_REGISTRY: unique symbol;
+export declare const ABORT_STREAM_NAME: unique symbol;
+export declare const ABORT_HOOK_TOKEN: unique symbol;
+export declare const ABORT_LISTENER_ATTACHED: unique symbol;
+export declare const ABORT_READER_CANCEL: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map