@aws/durable-execution-sdk-js 0.0.1 → 1.0.1

package/dist-types/types/durable-execution.d.ts

@@ -0,0 +1,192 @@
+import { CheckpointDurableExecutionRequest, CheckpointDurableExecutionResponse, GetDurableExecutionStateRequest, GetDurableExecutionStateResponse, LambdaClient } from "@aws-sdk/client-lambda";
+import { DurableContext } from "./durable-context";
+import { DurableLogger } from "./durable-logger";
+import { Context } from "aws-lambda";
+import { DurableExecutionInvocationInput, DurableExecutionInvocationOutput } from "./core";
+/**
+ * A handler function type for a durable execution that provides automatic state persistence,
+ * retry logic, and workflow orchestration capabilities.
+ *
+ * This handler type is the core interface for building stateful, long-running AWS Durable Executions
+ * using the Durable Execution SDK. The handler receives a durable context that enables:
+ * - Step-based execution with automatic checkpointing and replay
+ * - Built-in retry strategies with exponential backoff and jitter
+ * - Workflow orchestration with parallel execution and child contexts
+ * - External system integration via callbacks and conditional waiting
+ * - Batch operations with concurrency control
+ *
+ * This handler function must be wrapped by `withDurableExecution()` to enable
+ * durable execution capabilities. During replay scenarios, the handler function is re-executed,
+ * however the durable context operations that already completed(steps, waits, callbacks, etc.) are
+ * not re-executed.
+ *
+ * @typeParam TEvent - The type of the input event payload (defaults to any)
+ * @typeParam TResult - The type of the return value (defaults to any)
+ * @typeParam TLogger - The type of a custom logger implementation (defaults to DurableLogger)
+ *
+ * @param event - The parsed JSON input event data for the invocation
+ * @param context - The durable context providing methods for durable operations like steps,
+ *                  waits, parallel execution, external callbacks, and workflow orchestration
+ *
+ * @returns A promise that resolves with the handler's result value or rejects with an
+ *          execution error. The result will be automatically serialized and may be
+ *          checkpointed if it exceeds response size limits.
+ *
+ * @example
+ * ```typescript
+ * const durableHandler: DurableExecutionHandler<{ userId: string }, { status: string }> = async (event, context) => {
+ *   // Execute durable step with automatic retry and checkpointing
+ *   const user = await context.step("fetch-user", async () =>
+ *     fetchUserFromDB(event.userId)
+ *   );
+ *
+ *   // Wait for external callback (e.g., manual approval)
+ *   const approval = await context.waitForCallback("approval", async (callbackId) => {
+ *     await sendApprovalRequest(callbackId, user);
+ *   });
+ *
+ *   // Process in parallel with concurrency control
+ *   const results = await context.parallel("parallel-tasks", [
+ *     async (ctx) => ctx.step("task1", () => processTask1(user)),
+ *     async (ctx) => ctx.step("task2", () => processTask2(user))
+ *   ]);
+ *
+ *   return { status: "completed" };
+ * };
+ *
+ * export const handler = withDurableExecution(durableHandler);
+ * ```
+ *
+ * @public
+ */
+export type DurableExecutionHandler<TEvent = any, TResult = any, TLogger extends DurableLogger = DurableLogger> = (event: TEvent, context: DurableContext<TLogger>) => Promise<TResult>;
+/**
+ * Configuration options for durable execution setup.
+ *
+ * This interface allows customization of the durable execution runtime behavior,
+ * primarily for dependency injection and testing scenarios. In most production
+ * use cases, the default configuration is sufficient.
+ *
+ * @public
+ */
+export interface DurableExecutionConfig {
+    /**
+     * Optional custom AWS Lambda client instance for durable execution operations.
+     *
+     * When provided, this client will be used for all AWS Lambda service calls including
+     * checkpoint operations and execution state management. This is useful for:
+     * - Custom AWS configurations (regions, credentials, endpoints)
+     * - Testing with mocked Lambda clients
+     * - Advanced networking configurations (VPC endpoints, proxies)
+     * - Custom retry and timeout configurations
+     *
+     * If not provided, a default Lambda client will be created automatically using
+     * the standard AWS SDK configuration chain (environment variables, IAM roles, etc.).
+     *
+     * @example
+     * ```typescript
+     * import { LambdaClient } from '@aws-sdk/client-lambda';
+     *
+     * const customClient = new LambdaClient({
+     *   region: 'us-west-2',
+     *   maxAttempts: 5,
+     *   retryMode: 'adaptive'
+     * });
+     *
+     * export const handler = withDurableExecution(myHandler, {
+     *   client: customClient
+     * });
+     * ```
+     */
+    client?: LambdaClient;
+}
+/**
+ * Client interface for durable execution backend operations.
+ *
+ * This interface defines the core operations needed to manage durable execution state
+ * and checkpoints. It abstracts the underlying service calls and provides
+ * a clean contract for:
+ * - Retrieving execution state during replay scenarios
+ * - Creating checkpoints for state persistence
+ * - Managing long-running workflow state
+ *
+ * Implementations of this interface handle the communication with AWS services to
+ * ensure durable execution capabilities including automatic retry, state recovery,
+ * and workflow orchestration.
+ *
+ * @public
+ */
+export interface DurableExecutionClient {
+    /**
+     * Retrieves the current execution state for a durable execution.
+     *
+     * This method fetches the persisted state data from the durable execution backend,
+     * including step history, checkpoint data, and execution metadata. It's primarily
+     * used during replay scenarios to restore the execution context and determine
+     * which operations have already been completed.
+     *
+     * The execution state contains all information needed to resume a durable function
+     * from where it left off, enabling fault tolerance and long-running workflows.
+     *
+     * @param params - Request parameters including execution ARN and state identifiers
+     * @param logger - Optional logger instance for operation logging and debugging
+     *
+     * @returns Promise resolving to the execution state response containing step history,
+     *          checkpoint data, and execution metadata
+     *
+     * @throws Will throw an error if the execution state cannot be retrieved due to
+     *         network issues, authentication problems, or invalid execution ARN
+     */
+    getExecutionState(params: GetDurableExecutionStateRequest, logger?: DurableLogger): Promise<GetDurableExecutionStateResponse>;
+    /**
+     * Creates a checkpoint to persist the current execution state.
+     *
+     * This method saves the current execution progress, step results, and context data
+     * to enable recovery and replay capabilities. Checkpoints are created automatically
+     * at key points during execution (after steps complete, before waits, etc.) and
+     * can also be triggered manually for custom persistence needs.
+     *
+     * Checkpointing enables:
+     * - Automatic recovery from timeouts or failures
+     * - Resumption of long-running workflows
+     * - Replay semantics for consistent execution
+     * - State persistence across execution boundaries
+     *
+     * @param params - Checkpoint request parameters including execution data and metadata
+     * @param logger - Optional logger instance for operation logging and debugging
+     *
+     * @returns Promise resolving to the checkpoint response with confirmation and metadata
+     *
+     * @throws Will throw an error if the checkpoint cannot be created due to network issues,
+     *         authentication problems, or storage limitations
+     */
+    checkpoint(params: CheckpointDurableExecutionRequest, logger?: DurableLogger): Promise<CheckpointDurableExecutionResponse>;
+}
+/**
+ * The handler type returned by `withDurableExecution()` that handles durable execution behaviour.
+ *
+ * This handler type represents the final lambda function that gets deployed and invoked by the Durable
+ * Execution service.
+ *
+ * The handler receives `DurableExecutionInvocationInput` containing execution metadata, checkpoint tokens,
+ * and operation history, then returns `DurableExecutionInvocationOutput` with execution status and results.
+ *
+ * @example
+ * ```typescript
+ * // Define your durable handler
+ * const myHandler: DurableExecutionHandler<MyEvent, MyResult> = async (event, context) => {
+ *   const result = await context.step("process", async () => processEvent(event));
+ *   return result;
+ * };
+ *
+ * // Wrap it to create a DurableLambdaHandler
+ * export const handler: DurableLambdaHandler = withDurableExecution(myHandler);
+ *
+ * // Deploy this handler - it will receive DurableExecutionInvocationInput
+ * // and handle all the durability management automatically
+ * ```
+ *
+ * @public
+ */
+export type DurableLambdaHandler = (event: DurableExecutionInvocationInput, context: Context) => Promise<DurableExecutionInvocationOutput>;
+//# sourceMappingURL=durable-execution.d.ts.map

package/dist-types/types/durable-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-execution.d.ts","sourceRoot":"","sources":["../../src/types/durable-execution.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iCAAiC,EACjC,kCAAkC,EAClC,+BAA+B,EAC/B,gCAAgC,EAChC,YAAY,EACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EACjC,MAAM,QAAQ,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,MAAM,uBAAuB,CAEjC,MAAM,GAAG,GAAG,EAEZ,OAAO,GAAG,GAAG,EACb,OAAO,SAAS,aAAa,GAAG,aAAa,IAC3C,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CACf,MAAM,EAAE,+BAA+B,EACvC,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CACR,MAAM,EAAE,iCAAiC,EACzC,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,kCAAkC,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,KAAK,EAAE,+BAA+B,EACtC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,gCAAgC,CAAC,CAAC"}

package/dist-types/types/durable-logger.d.ts

@@ -0,0 +1,69 @@
+import { DurableLogData, DurableLogLevel } from "./logger";
+/**
+ * The durable logging context that can be used to provide durable execution metadata
+ * such as executionArn, operationId, and attempt.
+ * @public
+ */
+export interface DurableLoggingContext {
+    getDurableLogData: () => DurableLogData;
+}
+/**
+ * This interface provides structured logging capabilities for durable execution contexts.
+ * A custom logger must implement this interface to be used by the Durable Execution
+ * Language SDK. The SDK will automatically parse the logger and use the appropriate
+ * logging method based on the log level.
+ *
+ * @public
+ */
+export interface DurableLogger {
+    /**
+     * Generic log method with configurable level
+     * @param level - Log level (e.g., "INFO", "ERROR", "WARN", "DEBUG")
+     * @param message - Log message
+     * @param optionalParams - Additional data to include in log entry
+     * @example context.logger.log("INFO", "User logged in", \{ userId: "XXX" \})
+     */
+    log?(level: `${DurableLogLevel}`, ...params: any): void;
+    /**
+     * Log error messages with optional message and additional parameters
+     * @param message - Optional message
+     * @param optionalParams - Additional data to include in log entry
+     * @example context.logger.error("Database query failed", dbError, \{ query: "SELECT * FROM users" \})
+     */
+    error(...params: any): void;
+    /**
+     * Log warning messages with optional additional parameters
+     * @param message - Optional message
+     * @param optionalParams - Additional data to include in log entry
+     * @example context.logger.warn("Rate limit approaching", \{ currentRate: 95, limit: 100 \})
+     */
+    warn(...params: any): void;
+    /**
+     * Log informational messages with optional additional parameters
+     * @param message - Optional message
+     * @param optionalParams - Additional data to include in log entry
+     * @example context.logger.info("User action completed", \{ userId: "123", action: "login" \})
+     */
+    info(...params: any): void;
+    /**
+     * Log debug messages with optional additional parameters
+     * @param message - Optional message
+     * @param optionalParams - Additional data to include in log entry
+     * @example context.logger.debug("Processing step", \{ stepName: "validation", duration: 150 \})
+     */
+    debug(...params: any): void;
+    /**
+     * This function will be called by the language SDK before logging any records. The durableLoggingContext
+     * should be stored and used by custom loggers to enable logging of custom durable metadata
+     * such as operationId, attempt, executionArn, etc.
+     * @param durableLoggingContext - The logging context provided by the Durable Execution Language SDK
+     */
+    configureDurableLoggingContext?(durableLoggingContext: DurableLoggingContext): void;
+}
+/**
+ * The durable logger available inside a context.
+ *
+ * @public
+ */
+export type DurableContextLogger<Logger extends DurableLogger> = Pick<Logger, "log" | "warn" | "info" | "error" | "debug">;
+//# sourceMappingURL=durable-logger.d.ts.map

package/dist-types/types/durable-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-logger.d.ts","sourceRoot":"","sources":["../../src/types/durable-logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,EAAE,MAAM,cAAc,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,eAAe,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAExD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAE5B;;;;;OAKG;IACH,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAE3B;;;;;OAKG;IACH,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAE3B;;;;;OAKG;IACH,KAAK,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAE5B;;;;;OAKG;IACH,8BAA8B,CAAC,CAC7B,qBAAqB,EAAE,qBAAqB,GAC3C,IAAI,CAAC;CACT;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,aAAa,IAAI,IAAI,CACnE,MAAM,EACN,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAC5C,CAAC"}

package/dist-types/types/durable-promise.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A promise that defers execution until it's awaited or .then/.catch/.finally is called
+ *
+ * @public
+ */
+export declare class DurablePromise<T> implements Promise<T> {
+    /**
+     * The actual promise instance, created only when execution begins.
+     * Starts as null and remains null until the DurablePromise is first awaited
+     * or chained (.then/.catch/.finally). Once created, it holds the running
+     * promise returned by the _executor function.
+     *
+     * Example lifecycle:
+     * ```typescript
+     * const dp = new DurablePromise(() => fetch('/api')); // _promise = null
+     * console.log(dp.isExecuted); // false
+     *
+     * const result = await dp; // NOW _promise = fetch('/api') promise
+     * console.log(dp.isExecuted); // true
+     * ```
+     *
+     * This lazy initialization prevents the executor from running until needed.
+     */
+    private _promise;
+    /**
+     * Function that contains the deferred execution logic.
+     * This function is NOT called when the DurablePromise is created - it's only
+     * executed when the promise is first awaited or chained (.then/.catch/.finally).
+     *
+     * Example:
+     * ```typescript
+     * const durablePromise = new DurablePromise(async () => {
+     *   console.log("This runs ONLY when awaited, not when created");
+     *   return await someAsyncOperation();
+     * });
+     *
+     * // At this point, nothing has executed yet
+     * console.log("Promise created but not executed");
+     *
+     * // NOW the executor function runs
+     * const result = await durablePromise;
+     * ```
+     */
+    private _executor;
+    /** Flag indicating whether the promise has been executed (awaited or chained) */
+    private _isExecuted;
+    /**
+     * Creates a new DurablePromise
+     * @param executor - Function containing the deferred execution logic
+     */
+    constructor(executor: () => Promise<T>);
+    /**
+     * Ensures the promise is executed, creating the actual promise if needed
+     * @returns The underlying promise instance
+     */
+    private ensureExecution;
+    /**
+     * Attaches callbacks for the resolution and/or rejection of the Promise
+     * Triggers execution if not already started
+     */
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
+    /**
+     * Attaches a callback for only the rejection of the Promise
+     * Triggers execution if not already started
+     */
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
+    /**
+     * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected)
+     * Triggers execution if not already started
+     */
+    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
+    /** Returns the string tag for the promise type */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Check if the promise has been executed (awaited or had .then/.catch/.finally called)
+     * @returns true if execution has started, false otherwise
+     */
+    get isExecuted(): boolean;
+}
+//# sourceMappingURL=durable-promise.d.ts.map

package/dist-types/types/durable-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-promise.d.ts","sourceRoot":"","sources":["../../src/types/durable-promise.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IAClD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,QAAQ,CAA2B;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,SAAS,CAAmB;IAEpC,iFAAiF;IACjF,OAAO,CAAC,WAAW,CAAS;IAE5B;;;OAGG;gBACS,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAItC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAUvB;;;OAGG;IACH,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,EACjC,WAAW,CAAC,EACR,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAChD,SAAS,GACT,IAAI,EACR,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACvD,SAAS,GACT,IAAI,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAI/B;;;OAGG;IACH,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GACrD,SAAS,GACT,IAAI,GACP,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;IAIvB;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhE,kDAAkD;IAClD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED;;;OAGG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}

package/dist-types/types/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./core";
+export * from "./logger";
+export * from "./durable-logger";
+export * from "./step";
+export * from "./child-context";
+export * from "./callback";
+export * from "./invoke";
+export * from "./wait-condition";
+export * from "./batch";
+export * from "./durable-context";
+export * from "./durable-promise";
+export * from "./durable-execution";
+export * from "./operation-lifecycle-state";
+export * from "./operation-lifecycle";
+//# sourceMappingURL=index.d.ts.map

package/dist-types/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,QAAQ,CAAC;AACvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}

package/dist-types/types/invoke.d.ts

@@ -0,0 +1,12 @@
+import { Serdes } from "../utils/serdes/serdes";
+/**
+ * Configuration options for invoke operations
+ * @public
+ */
+export interface InvokeConfig<I, O> {
+    /** Serialization/deserialization configuration for input payload */
+    payloadSerdes?: Serdes<I>;
+    /** Serialization/deserialization configuration for result data */
+    resultSerdes?: Serdes<O>;
+}
+//# sourceMappingURL=invoke.d.ts.map

package/dist-types/types/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/types/invoke.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC;IAChC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC1B"}

package/dist-types/types/logger.d.ts

@@ -0,0 +1,63 @@
+import { DurableContextLogger, DurableLogger } from "./durable-logger";
+/**
+ * Log data passed to the durable logger when `getDurableLogData` is called.
+ * @public
+ */
+export interface DurableLogData {
+    requestId: string;
+    executionArn: string;
+    tenantId?: string;
+    operationId?: string;
+    attempt?: number;
+    [key: string]: unknown;
+}
+/**
+ * Log level supported by the durable logger
+ * @public
+ */
+export declare enum DurableLogLevel {
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    DEBUG = "DEBUG"
+}
+/**
+ * Configuration options for logger behavior
+ * @public
+ */
+export interface LoggerConfig<Logger extends DurableLogger> {
+    /**
+     * Custom logger implementation to use instead of the default console logger
+     * @defaultValue Default console logger
+     */
+    customLogger?: Logger;
+    /**
+     * Whether to enable mode-aware logging (suppress logs during replay)
+     * @defaultValue true
+     */
+    modeAware?: boolean;
+}
+/**
+ * Base interface for operation contexts.
+ * Do not use directly - use specific context types like StepContext, WaitForConditionContext, etc.
+ * @public
+ */
+export interface OperationContext<Logger extends DurableLogger> {
+    logger: Logger;
+}
+/**
+ * Context for step operations.
+ * @public
+ */
+export type StepContext<Logger extends DurableLogger> = OperationContext<DurableContextLogger<Logger>>;
+/**
+ * Context for waitForCondition operations.
+ * @public
+ */
+export type WaitForConditionContext<Logger extends DurableLogger> = OperationContext<DurableContextLogger<Logger>>;
+/**
+ * Context for step operations.
+ * @public
+ */
+export type WaitForCallbackContext<Logger extends DurableLogger> = OperationContext<DurableContextLogger<Logger>>;
+//# sourceMappingURL=logger.d.ts.map

package/dist-types/types/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;IACf,KAAK,UAAU;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,aAAa;IACxD;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,SAAS,aAAa;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,aAAa,IAAI,gBAAgB,CACtE,oBAAoB,CAAC,MAAM,CAAC,CAC7B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,CAAC,MAAM,SAAS,aAAa,IAC9D,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,MAAM,SAAS,aAAa,IAC7D,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC"}

package/dist-types/types/operation-lifecycle-state.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents the lifecycle state of an operation in the durable execution system.
+ * This is distinct from AWS SDK's OperationStatus (PENDING, SUCCEEDED, FAILED).
+ */
+export declare enum OperationLifecycleState {
+    /**
+     * Operation is currently executing user code (step function, waitForCondition check)
+     */
+    EXECUTING = "EXECUTING",
+    /**
+     * Operation is waiting for retry timer to expire before re-executing user code
+     */
+    RETRY_WAITING = "RETRY_WAITING",
+    /**
+     * Operation is waiting for external event (timer, callback, invoke) but not awaited yet (phase 1)
+     */
+    IDLE_NOT_AWAITED = "IDLE_NOT_AWAITED",
+    /**
+     * Operation is waiting for external event and has been awaited (phase 2)
+     */
+    IDLE_AWAITED = "IDLE_AWAITED",
+    /**
+     * Operation has completed (success or permanent failure)
+     */
+    COMPLETED = "COMPLETED"
+}
+//# sourceMappingURL=operation-lifecycle-state.d.ts.map

package/dist-types/types/operation-lifecycle-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lifecycle-state.d.ts","sourceRoot":"","sources":["../../src/types/operation-lifecycle-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,uBAAuB;IACjC;;OAEG;IACH,SAAS,cAAc;IAEvB;;OAEG;IACH,aAAa,kBAAkB;IAE/B;;OAEG;IACH,gBAAgB,qBAAqB;IAErC;;OAEG;IACH,YAAY,iBAAiB;IAE7B;;OAEG;IACH,SAAS,cAAc;CACxB"}

package/dist-types/types/operation-lifecycle.d.ts

@@ -0,0 +1,27 @@
+import { OperationType } from "@aws-sdk/client-lambda";
+import { OperationSubType } from "./core";
+import { OperationLifecycleState } from "./operation-lifecycle-state";
+/**
+ * Metadata about an operation for lifecycle tracking
+ */
+export interface OperationMetadata {
+    stepId: string;
+    name?: string;
+    type: OperationType;
+    subType: OperationSubType;
+    parentId?: string;
+}
+/**
+ * Complete information about an operation's lifecycle state
+ */
+export interface OperationInfo {
+    stepId: string;
+    state: OperationLifecycleState;
+    metadata: OperationMetadata;
+    endTimestamp?: Date;
+    timer?: NodeJS.Timeout;
+    resolver?: () => void;
+    pollCount?: number;
+    pollStartTime?: number;
+}
+//# sourceMappingURL=operation-lifecycle.d.ts.map

package/dist-types/types/operation-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lifecycle.d.ts","sourceRoot":"","sources":["../../src/types/operation-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,uBAAuB,CAAC;IAC/B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist-types/types/step.d.ts

@@ -0,0 +1,76 @@
+import { Serdes } from "../utils/serdes/serdes";
+import { StepContext } from "./logger";
+import { DurableLogger, Duration } from "../types";
+/**
+ * Decision returned by a retry strategy function
+ *
+ * @remarks
+ * Returned by retry strategy functions to indicate whether an operation should be retried
+ * and how long to wait before the next attempt.
+ *
+ * @example
+ * ```typescript
+ * // Don't retry
+ * { shouldRetry: false }
+ *
+ * // Retry after 5 seconds
+ * { shouldRetry: true, delay: { seconds: 5 } }
+ *
+ * // Retry after 2 minutes
+ * { shouldRetry: true, delay: { minutes: 2 } }
+ * ```
+ *
+ * @see {@link createRetryStrategy} for creating retry strategies
+ *
+ * @public
+ */
+export interface RetryDecision {
+    /** Whether the operation should be retried */
+    shouldRetry: boolean;
+    /**
+     * Delay before the next retry attempt
+     * @remarks Only used when `shouldRetry` is true. If not specified, defaults to 1 second.
+     */
+    delay?: Duration;
+}
+/**
+ * @public
+ */
+export declare enum StepSemantics {
+    AtMostOncePerRetry = "AT_MOST_ONCE_PER_RETRY",
+    AtLeastOncePerRetry = "AT_LEAST_ONCE_PER_RETRY"
+}
+/**
+ * Jitter strategy for retry delays to prevent thundering herd. Jitter reduces simultaneous retry attempts
+ * by spreading retries out over a randomized delay interval.
+ *
+ * @public
+ */
+export declare enum JitterStrategy {
+    /** No jitter - use exact calculated delay */
+    NONE = "NONE",
+    /** Full jitter - random delay between 0 and calculated delay */
+    FULL = "FULL",
+    /** Half jitter - random delay between 50% and 100% of calculated delay */
+    HALF = "HALF"
+}
+/**
+ * Configuration options for step operations
+ * @public
+ */
+export interface StepConfig<T> {
+    /** Strategy for retrying failed step executions */
+    retryStrategy?: (error: Error, attemptCount: number) => RetryDecision;
+    /** Execution semantics for the step (at-most-once or at-least-once per retry) */
+    semantics?: StepSemantics;
+    /** Serialization/deserialization configuration for step data */
+    serdes?: Serdes<T>;
+}
+/**
+ * Function to be executed as a durable step
+ * @param context - Context for logging and other operations during step execution
+ * @returns Promise resolving to the step result
+ * @public
+ */
+export type StepFunc<T, Logger extends DurableLogger = DurableLogger> = (context: StepContext<Logger>) => Promise<T>;
+//# sourceMappingURL=step.d.ts.map

package/dist-types/types/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/types/step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,kBAAkB,2BAA2B;IAC7C,mBAAmB,4BAA4B;CAChD;AAED;;;;;GAKG;AACH,oBAAY,cAAc;IACxB,6CAA6C;IAC7C,IAAI,SAAS;IACb,gEAAgE;IAChE,IAAI,SAAS;IACb,0EAA0E;IAC1E,IAAI,SAAS;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,mDAAmD;IACnD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,aAAa,CAAC;IACtE,iFAAiF;IACjF,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,IAAI,CACtE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,KACzB,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist-types/types/wait-condition.d.ts

@@ -0,0 +1,46 @@
+import { Serdes } from "../utils/serdes/serdes";
+import { WaitForConditionContext } from "./logger";
+import { DurableLogger, Duration } from "../types";
+/**
+ * Function that checks and updates state for waitForCondition operations
+ * @param state - Current state value
+ * @param context - Context for logging and other operations during state checking
+ * @returns Promise resolving to the updated state
+ *
+ * @public
+ */
+export type WaitForConditionCheckFunc<T, Logger extends DurableLogger = DurableLogger> = (state: T, context: WaitForConditionContext<Logger>) => Promise<T>;
+/**
+ * Function that determines whether to continue waiting and how long to delay
+ * @param state - Current state value
+ * @param attempt - Current attempt number (starts at 1)
+ * @returns Decision object indicating whether to continue and delay duration
+ *
+ * @public
+ */
+export type WaitForConditionWaitStrategyFunc<T> = (state: T, attempt: number) => WaitForConditionDecision;
+/**
+ * Decision object for waitForCondition wait strategy
+ *
+ * @public
+ */
+export type WaitForConditionDecision = {
+    shouldContinue: true;
+    delay: Duration;
+} | {
+    shouldContinue: false;
+};
+/**
+ * Configuration options for waitForCondition operations
+ *
+ * @public
+ */
+export interface WaitForConditionConfig<T> {
+    /** Strategy function that determines when to continue waiting and how long to delay */
+    waitStrategy: WaitForConditionWaitStrategyFunc<T>;
+    /** Initial state value to start the condition checking with */
+    initialState: T;
+    /** Serialization/deserialization configuration for state data */
+    serdes?: Serdes<T>;
+}
+//# sourceMappingURL=wait-condition.d.ts.map

package/dist-types/types/wait-condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-condition.d.ts","sourceRoot":"","sources":["../../src/types/wait-condition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,CACnC,CAAC,EACD,MAAM,SAAS,aAAa,GAAG,aAAa,IAC1C,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,gCAAgC,CAAC,CAAC,IAAI,CAChD,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,KACZ,wBAAwB,CAAC;AAE9B;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,cAAc,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GACzC;IAAE,cAAc,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,uFAAuF;IACvF,YAAY,EAAE,gCAAgC,CAAC,CAAC,CAAC,CAAC;IAClD,+DAA+D;IAC/D,YAAY,EAAE,CAAC,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACpB"}

package/dist-types/utils/checkpoint/checkpoint-ancestor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=checkpoint-ancestor.test.d.ts.map