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

package/dist-types/types/child-context.d.ts

@@ -0,0 +1,24 @@
+import { Serdes } from "../utils/serdes/serdes";
+import { DurableLogger } from "./durable-logger";
+import { DurableContext } from "./durable-context";
+/**
+ * Configuration options for child context operations
+ * @public
+ */
+export interface ChildConfig<T> {
+    /** Serialization/deserialization configuration for child context data */
+    serdes?: Serdes<T>;
+    /** Sub-type identifier for categorizing child contexts */
+    subType?: string;
+    /** Function to generate summaries for large results (used internally by map/parallel) */
+    summaryGenerator?: (result: T) => string;
+}
+/**
+ * Function to be executed in a child context with isolated state
+ * @param context - DurableContext with isolated step counter and state tracking
+ * @returns Promise resolving to the child function result
+ *
+ * @public
+ */
+export type ChildFunc<T, Logger extends DurableLogger = DurableLogger> = (context: DurableContext<Logger>) => Promise<T>;
+//# sourceMappingURL=child-context.d.ts.map

package/dist-types/types/child-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-context.d.ts","sourceRoot":"","sources":["../../src/types/child-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,IAAI,CACvE,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,KAC5B,OAAO,CAAC,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,315 @@
+import { TerminationManager } from "../termination-manager/termination-manager";
+import { DurableExecutionClient } from "./durable-execution";
+import { ErrorObject, Operation } from "@aws-sdk/client-lambda";
+import { ActiveOperationsTracker } from "../utils/termination-helper/active-operations-tracker";
+/**
+ * @internal
+ */
+export declare enum DurableExecutionMode {
+    ExecutionMode = "ExecutionMode",
+    ReplayMode = "ReplayMode",
+    ReplaySucceededContext = "ReplaySucceededContext"
+}
+/**
+ * Input structure for durable execution invocations.
+ *
+ * This interface defines the payload structure that the durable execution service provides
+ * to durable functions. It contains all the necessary information for the Durable
+ * Execution Language SDK to:
+ * - Manage checkpointing and state persistence
+ * - Replay completed operations from previous state
+ *
+ * The input is automatically provided by the durable execution service and
+ * contains both execution metadata and the operation history for replay.
+ *
+ * @public
+ */
+export interface DurableExecutionInvocationInput {
+    /**
+     * Amazon Resource Name (ARN) that uniquely identifies this durable execution instance.
+     */
+    DurableExecutionArn: string;
+    /**
+     * Unique token for the next checkpoint in this execution.
+     *
+     * This token:
+     * - Ensures checkpoint operations are idempotent
+     * - Prevents duplicate checkpoints
+     * - Validates that checkpoint requests belong to the current execution cycle
+     */
+    CheckpointToken: string;
+    /**
+     * Execution state including operation history and pagination information.
+     *
+     * Contains the full context needed to resume execution including:
+     * - All previously completed operations with their results
+     * - Execution metadata and step identifiers
+     * - Pagination markers for long operation histories
+     */
+    InitialExecutionState: {
+        /**
+         * Array of completed operations with their execution details and results.
+         *
+         * Each operation contains:
+         * - Operation type and subtype (STEP, WAIT, CALLBACK, etc.)
+         * - Unique operation identifier
+         * - Output results
+         * - Execution timestamps and status
+         */
+        Operations: Operation[];
+        /**
+         * Pagination marker for retrieving additional operation history if needed.
+         *
+         * Used when the operation history is too large to fit in a single response.
+         * The Durable Execution Language SDK handles pagination automatically.
+         */
+        NextMarker: string;
+    };
+}
+/**
+ * Status enumeration for durable execution invocation results.
+ *
+ * This enum defines the possible outcomes of a durable execution invocation,
+ * indicating whether the execution completed successfully, failed, or is
+ * continuing asynchronously.
+ *
+ * The status determines how the AWS durable execution service will handle
+ * the execution:
+ * - SUCCEEDED: Execution completed successfully with a final result
+ * - FAILED: Execution failed with an error that cannot be retried
+ * - PENDING: Execution is continuing and will be resumed later (checkpointed)
+ *
+ * @public
+ */
+export declare enum InvocationStatus {
+    /**
+     * The durable execution completed successfully.
+     *
+     * This status indicates:
+     * - A final result is available (if any)
+     * - No further invocations are needed
+     * - The execution has reached its natural completion
+     */
+    SUCCEEDED = "SUCCEEDED",
+    /**
+     * The durable execution failed with an unrecoverable error.
+     *
+     * This status indicates:
+     * - An error occurred that cannot be automatically retried
+     * - Error details are provided in the response
+     * - No further invocations will occur
+     */
+    FAILED = "FAILED",
+    /**
+     * The durable execution is continuing asynchronously.
+     *
+     * This status indicates:
+     * - Execution was checkpointed and will resume later
+     * - Common scenarios: waiting for callbacks, retries, wait operations
+     * - The function may terminate while execution continues
+     * - Future invocations will resume from the checkpoint
+     */
+    PENDING = "PENDING"
+}
+/**
+ * Operation subtype enumeration for categorizing different types of durable operations.
+ *
+ * This enum provides fine-grained classification of durable operations beyond the
+ * basic operation types. Subtypes enable improved observability for specific
+ * operation patterns.
+ *
+ * Each subtype corresponds to a specific durable context method or execution pattern.
+ *
+ * @public
+ */
+export declare enum OperationSubType {
+    /**
+     * A durable step operation (`context.step`).
+     *
+     * Represents atomic operations with automatic retry and checkpointing.
+     * Steps are the fundamental building blocks of durable executions.
+     */
+    STEP = "Step",
+    /**
+     * A wait operation (`context.wait`).
+     *
+     * Represents time-based delays that pause execution for a specified duration.
+     * Waits allow long-running workflows without keeping invocations active.
+     */
+    WAIT = "Wait",
+    /**
+     * A callback creation operation (`context.createCallback`).
+     *
+     * Represents the creation of a callback that external systems can complete.
+     * Used for human-in-the-loop workflows and external system integration.
+     */
+    CALLBACK = "Callback",
+    /**
+     * A child context operation (`context.runInChildContext`).
+     *
+     * Represents execution within an isolated child context with its own
+     * step counter and state tracking. Used for grouping related operations.
+     */
+    RUN_IN_CHILD_CONTEXT = "RunInChildContext",
+    /**
+     * A map operation (`context.map`).
+     *
+     * Represents parallel processing of an array of items with concurrency control
+     * and completion policies. Each map operation coordinates multiple iterations.
+     */
+    MAP = "Map",
+    /**
+     * An individual iteration within a map operation.
+     *
+     * Represents the processing of a single item within a `context.map` call.
+     * Each iteration runs in its own child context with isolated state.
+     */
+    MAP_ITERATION = "MapIteration",
+    /**
+     * A parallel execution operation (`context.parallel`).
+     *
+     * Represents concurrent execution of multiple branches with optional
+     * concurrency control and completion policies.
+     */
+    PARALLEL = "Parallel",
+    /**
+     * An individual branch within a parallel operation.
+     *
+     * Represents a single branch of execution within a `context.parallel` call.
+     * Each branch runs in its own child context with isolated state.
+     */
+    PARALLEL_BRANCH = "ParallelBranch",
+    /**
+     * A wait for callback operation (`context.waitForCallback`).
+     *
+     * Represents waiting for an external system to complete a callback,
+     * combining callback creation with submission logic.
+     */
+    WAIT_FOR_CALLBACK = "WaitForCallback",
+    /**
+     * A wait for condition operation (`context.waitForCondition`).
+     *
+     * Represents periodic checking of a condition until it's met,
+     * with configurable polling intervals and wait strategies.
+     */
+    WAIT_FOR_CONDITION = "WaitForCondition",
+    /**
+     * A chained invocation operation (`context.invoke`).
+     *
+     * Represents calling another durable function with input parameters
+     * and waiting for its completion. Used for function composition and workflows.
+     */
+    CHAINED_INVOKE = "ChainedInvoke"
+}
+/**
+ * Response structure for failed durable execution invocations.
+ * @public
+ */
+interface DurableExecutionInvocationOutputFailed {
+    /** Status indicating the execution failed */
+    Status: InvocationStatus.FAILED;
+    /** Error object containing failure details and stack trace */
+    Error: ErrorObject;
+}
+/**
+ * Response structure for successfully completed durable execution invocations.
+ * @public
+ */
+interface DurableExecutionInvocationOutputSucceeded {
+    /** Status indicating successful completion */
+    Status: InvocationStatus.SUCCEEDED;
+    /** Optional serialized result from the execution (undefined for void results) */
+    Result?: string;
+}
+/**
+ * Response structure for durable execution invocations that are continuing asynchronously.
+ * @public
+ */
+interface DurableExecutionInvocationOutputPending {
+    /** Status indicating the execution is pending and will be resumed later */
+    Status: InvocationStatus.PENDING;
+}
+/**
+ * Union type representing all possible output formats for durable execution invocations.
+ *
+ * This type defines the complete response structure that durable functions return
+ * to the AWS Durable Execution service. The response format varies based on the
+ * execution outcome:
+ *
+ * **Successful Completion (`SUCCEEDED`):**
+ * - Contains the final execution result (if any) as a serialized string
+ * - Indicates the execution has completed and no further invocations are needed
+ * - The Result field may be undefined for void functions or large results that were checkpointed
+ *
+ * **Execution Failure (`FAILED`):**
+ * - Contains structured error information including message and stack trace
+ * - Indicates an unrecoverable error that terminates the execution
+ * - No further automatic retries will occur
+ *
+ * **Continued Execution (`PENDING`):**
+ * - Indicates the execution is continuing asynchronously
+ * - Common for operations involving waits, callbacks, or retries
+ * - The execution will be resumed in a future invocation
+ *
+ * The durable execution service uses this response to determine next steps:
+ * - Schedule continuation for PENDING status
+ * - Complete the execution for SUCCEEDED status
+ * - Complete the execution for FAILED status
+ *
+ * @public
+ */
+export type DurableExecutionInvocationOutput = DurableExecutionInvocationOutputSucceeded | DurableExecutionInvocationOutputFailed | DurableExecutionInvocationOutputPending;
+/**
+ * Type representing time durations for durable execution operations, such as
+ * `wait`, `retry`, and `timeout` options.
+ *
+ * **Supported Units:**
+ * - `days`: Number of days
+ * - `hours`: Number of hours
+ * - `minutes`: Number of minutes
+ * - `seconds`: Number of seconds
+ *
+ * **Usage Rules:**
+ * - At least one time unit must be specified
+ * - All numeric values must be positive integers
+ * - Fractional values are not supported
+ *
+ * @example
+ * ```typescript
+ * // Wait for 30 seconds
+ * await context.wait({ seconds: 30 });
+ * ```
+ *
+ * @public
+ */
+export type Duration = {
+    days: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+} | {
+    hours: number;
+    minutes?: number;
+    seconds?: number;
+} | {
+    minutes: number;
+    seconds?: number;
+} | {
+    seconds: number;
+};
+/**
+ * @internal
+ */
+export interface ExecutionContext {
+    durableExecutionClient: DurableExecutionClient;
+    _stepData: Record<string, Operation>;
+    terminationManager: TerminationManager;
+    durableExecutionArn: string;
+    activeOperationsTracker?: ActiveOperationsTracker;
+    requestId: string;
+    tenantId: string | undefined;
+    pendingCompletions: Set<string>;
+    getStepData(stepId: string): Operation | undefined;
+}
+export {};
+//# sourceMappingURL=core.d.ts.map

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

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