@aws/durable-execution-sdk-js 1.1.1 → 2.0.0-alpha.1

package/dist-types/utils/constants/version.d.ts

@@ -1,14 +1,3 @@
-/**
- * SDK metadata injected by Rollup at build time from package.json.
- *
- * At build time, Rollup replaces process.env.NPM_PACKAGE_NAME and
- * process.env.NPM_PACKAGE_VERSION with actual values from package.json.
- *
- * Defaults are provided for test environments where Rollup doesn't run
- * and process.env values are undefined.
- *
- * @internal
- */
-export declare const SDK_NAME: string;
+export declare const SDK_NAME = "aws-durable-execution-sdk-js";
 export declare const SDK_VERSION: string;
 //# sourceMappingURL=version.d.ts.map

package/dist-types/utils/constants/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../src/utils/constants/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,QAC4C,CAAC;AAClE,eAAO,MAAM,WAAW,QAA6C,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../src/utils/constants/version.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,QAAQ,iCAAiC,CAAC;AAEvD,eAAO,MAAM,WAAW,QAET,CAAC"}

package/dist-types/utils/retry/linear-retry-strategy/linear-retry-strategy.d.ts

@@ -0,0 +1,10 @@
+import { RetryDecision } from "../../../types";
+/**
+ * Creates a linear backoff retry strategy
+ * @param maxAttempts - Maximum number of attempts (default: 6)
+ * @param initialDelay - Initial delay in seconds (default: 1)
+ * @param increment - Linear increment per attempt in seconds (default: 1)
+ * @returns Retry strategy with linear backoff
+ */
+export declare const createLinearRetryStrategy: (maxAttempts?: number, initialDelay?: number, increment?: number) => (error: Error, attemptsMade: number) => RetryDecision;
+//# sourceMappingURL=linear-retry-strategy.d.ts.map

package/dist-types/utils/retry/linear-retry-strategy/linear-retry-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-retry-strategy.d.ts","sourceRoot":"","sources":["../../../../src/utils/retry/linear-retry-strategy/linear-retry-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,cAAa,MAAU,EACvB,eAAc,MAAU,EACxB,YAAW,MAAU,MAEb,OAAO,KAAK,EAAE,cAAc,MAAM,KAAG,aAU9C,CAAC"}

package/dist-types/utils/retry/linear-retry-strategy/linear-retry-strategy.test.d.ts

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

package/dist-types/utils/retry/linear-retry-strategy/linear-retry-strategy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-retry-strategy.test.d.ts","sourceRoot":"","sources":["../../../../src/utils/retry/linear-retry-strategy/linear-retry-strategy.test.ts"],"names":[],"mappings":""}

package/dist-types/utils/retry/retry-presets/retry-presets.d.ts

@@ -2,11 +2,16 @@
  * Pre-configured retry strategies for common use cases
  * @example
  * ```typescript
- * // Use default retry preset (3 attempts with exponential backoff)
+ * // Use default retry preset (6 attempts with exponential backoff)
  * await context.step('my-step', async () => {
  *   return await someOperation();
  * }, { retryStrategy: retryPresets.default });
  *
+ * // Use linear retry preset (1s, 2s, 3s, 4s, 5s delays)
+ * await context.step('linear-step', async () => {
+ *   return await someOperation();
+ * }, { retryStrategy: retryPresets.linear });
+ *
  * // Use no-retry preset (fail immediately on error)
  * await context.step('critical-step', async () => {
  *   return await criticalOperation();
@@ -26,6 +31,13 @@ export declare const retryPresets: {
      * - Total max wait time less than 150 seconds (2:30)
      */
     default: (error: Error, attemptsMade: number) => import("../../..").RetryDecision;
+    /**
+     * Linear retry strategy with fixed increment
+     * - 6 total attempts (1 initial + 5 retries)
+     * - Delays: 1s, 2s, 3s, 4s, 5s
+     * - Total max wait time: 15 seconds
+     */
+    linear: (error: Error, attemptsMade: number) => import("../../..").RetryDecision;
     /**
      * No retry strategy - fails immediately on first error
      * - 1 total attempt (no retries)

package/dist-types/utils/retry/retry-presets/retry-presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry-presets.d.ts","sourceRoot":"","sources":["../../../../src/utils/retry/retry-presets/retry-presets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;;;;OAQG;;IASH;;;OAGG;;CAIJ,CAAC"}
+{"version":3,"file":"retry-presets.d.ts","sourceRoot":"","sources":["../../../../src/utils/retry/retry-presets/retry-presets.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;;;;OAQG;;IASH;;;;;OAKG;;IAGH;;;OAGG;;CAIJ,CAAC"}

package/dist-types/utils/serdes/filesystem-serdes.d.ts

@@ -0,0 +1,119 @@
+import { AnySerdes } from "./serdes";
+export { FieldMatchMode, PreviewMode, PreviewField, PreviewConfig, buildPreview, } from "./preview";
+/**
+ * Controls when data is written to the filesystem.
+ *
+ * - `ALWAYS`: Every value is written to a file; the checkpoint stores only a file pointer.
+ *   Best for consistently large payloads or when you want predictable checkpoint sizes.
+ *
+ * - `OVERFLOW`: Data is written inline (as JSON) unless it exceeds the durable function
+ *   checkpoint size limit (~256KB), in which case it overflows to a file.
+ *   Best for mixed workloads where most payloads are small.
+ *
+ * @public
+ */
+export declare enum FileSystemSerdesMode {
+    ALWAYS = "ALWAYS",
+    OVERFLOW = "OVERFLOW"
+}
+/**
+ * Configuration options for {@link createFileSystemSerdes}.
+ *
+ * @public
+ */
+export interface FileSystemSerdesConfig {
+    /**
+     * Controls when data is written to the filesystem.
+     * @defaultValue `FileSystemSerdesMode.ALWAYS`
+     */
+    storageMode?: FileSystemSerdesMode;
+    /**
+     * Optional function that generates a preview object from the value.
+     * When provided, the preview is stored inline in the checkpoint envelope
+     * alongside the file pointer, making data visible in the console and API
+     * without reading the full file.
+     *
+     * Use {@link buildPreview} with a {@link PreviewConfig} for the built-in
+     * field selection logic, or provide your own implementation.
+     *
+     * @example
+     * ```typescript
+     * // Using the built-in buildPreview helper
+     * createFileSystemSerdes("/mnt/s3", {
+     *   generatePreview: (value) => buildPreview(value, {
+     *     mode: PreviewMode.EXCLUDE_ALL,
+     *     include: [{ name: "id" }, { name: "status" }],
+     *     mask: [{ name: "email" }],
+     *   }),
+     * });
+     *
+     * // Custom implementation
+     * createFileSystemSerdes("/mnt/s3", {
+     *   generatePreview: (value) => ({
+     *     id: (value as any).id,
+     *     summary: `Order ${(value as any).id}`,
+     *   }),
+     * });
+     * ```
+     */
+    generatePreview?: (value: unknown) => Record<string, unknown> | undefined;
+}
+/**
+ * Creates a Serdes that stores serialized values on a durable filesystem.
+ *
+ * **⚠️ WARNING: Do NOT use with Lambda's ephemeral `/tmp` storage.**
+ * Lambda's `/tmp` filesystem is local to a single execution environment and is
+ * not shared across invocations or function instances. On replay, a different
+ * execution environment may be used and the file will not be found, causing
+ * deserialization to fail.
+ *
+ * **Use only with a durable, shared filesystem such as:**
+ * - **Amazon S3 Files** — mount an S3 bucket as a filesystem via the Lambda console or IaC
+ * - **Amazon EFS** — mount an EFS file system to your Lambda function
+ *
+ * Both options provide persistence across invocations and are accessible from
+ * multiple concurrent function instances, which is required for correct replay behavior.
+ *
+ * The checkpoint stores a JSON envelope that is either:
+ * - `{"data":"<inline JSON>"}` — value stored inline (OVERFLOW mode, under threshold)
+ * - `{"file":"<path>"}` — value stored in a file
+ * - `{"file":"<path>","preview":{...}}` — file pointer with inline preview (when preview is configured)
+ *
+ * @param basePath - Directory path where data files will be stored (e.g. `/mnt/s3` for S3 Files, `/mnt/efs` for EFS)
+ * @param config - Optional configuration options
+ * @returns A Serdes that reads/writes JSON files under basePath
+ *
+ * @example
+ * ```typescript
+ * // Always write to S3 Files mount (default)
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3"),
+ * });
+ *
+ * // Only overflow to filesystem when payload exceeds ~256KB
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3", { storageMode: FileSystemSerdesMode.OVERFLOW }),
+ * });
+ *
+ * // With preview: show id and masked email in checkpoint
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3", {
+ *     generatePreview: (value) => buildPreview(value, {
+ *       mode: PreviewMode.EXCLUDE_ALL,
+ *       include: [{ name: "id" }, { name: "status" }],
+ *       mask: [{ name: "email" }],
+ *     }),
+ *   }),
+ * });
+ * ```
+ *
+ * Limitations:
+ * - Field names containing dots are not supported in preview field selectors.
+ *   A dot in a field name is indistinguishable from a path separator.
+ * - Array structure is not preserved in preview output — fields from array
+ *   elements are merged into a plain object at the array's path.
+ *
+ * @public
+ */
+export declare function createFileSystemSerdes(basePath: string, config?: FileSystemSerdesConfig): AnySerdes;
+//# sourceMappingURL=filesystem-serdes.d.ts.map

package/dist-types/utils/serdes/filesystem-serdes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-serdes.d.ts","sourceRoot":"","sources":["../../../src/utils/serdes/filesystem-serdes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,SAAS,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,WAAW,CAAC;AAKnB;;;;;;;;;;;GAWG;AACH,oBAAY,oBAAoB;IAC9B,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC3E;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,sBAA2B,GAClC,SAAS,CAiDX"}

package/dist-types/utils/serdes/filesystem-serdes.test.d.ts

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

package/dist-types/utils/serdes/filesystem-serdes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-serdes.test.d.ts","sourceRoot":"","sources":["../../../src/utils/serdes/filesystem-serdes.test.ts"],"names":[],"mappings":""}

package/dist-types/utils/serdes/preview.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Controls whether a preview field is matched by name anywhere in the object
+ * tree, or by exact dot-notation path from the root.
+ *
+ * @public
+ */
+export declare enum FieldMatchMode {
+    /** Match the field name at any depth in the object tree (default). */
+    ANYWHERE = "ANYWHERE",
+    /**
+     * Match by exact dot-notation path from root.
+     * A single segment (e.g. `"email"`) matches only the root-level field.
+     * A dotted path (e.g. `"user.email"`) matches that exact nested location.
+     */
+    PATH = "PATH"
+}
+/**
+ * Controls which fields are included in the preview by default.
+ *
+ * @public
+ */
+export declare enum PreviewMode {
+    /** Include all fields, then apply `exclude` and `mask` rules. */
+    INCLUDE_ALL = "INCLUDE_ALL",
+    /** Exclude all fields, then apply `include` and `mask` rules. */
+    EXCLUDE_ALL = "EXCLUDE_ALL"
+}
+/**
+ * A field selector used in preview include/exclude/mask lists.
+ *
+ * @public
+ */
+export interface PreviewField {
+    /** Field name or dot-notation path. */
+    name: string;
+    /** How to match the field. Defaults to `FieldMatchMode.ANYWHERE`. */
+    match?: FieldMatchMode;
+}
+/**
+ * Configuration for {@link buildPreview}.
+ *
+ * @public
+ */
+export interface PreviewConfig {
+    /** Whether to start with all fields included or all excluded. */
+    mode: PreviewMode;
+    /** Fields to include (used with `EXCLUDE_ALL` mode, or to override `INCLUDE_ALL`). */
+    include?: PreviewField[];
+    /** Fields to exclude (used with `INCLUDE_ALL` mode, or to override `EXCLUDE_ALL`). */
+    exclude?: PreviewField[];
+    /** Fields to mask — if visible, their value is replaced with `maskString`. */
+    mask?: PreviewField[];
+    /**
+     * String used to replace masked field values.
+     * @defaultValue `"***"`
+     */
+    maskString?: string;
+    /**
+     * Maximum size in bytes for the preview object (JSON-serialized).
+     * Fields are added until this limit is reached.
+     * @defaultValue `4096`
+     */
+    maxPreviewBytes?: number;
+}
+/**
+ * Builds a preview object from `value` according to `config`.
+ *
+ * Traverses the object tree and collects fields based on the include/exclude/mask
+ * rules in `config`. The result is a nested object mirroring the original structure,
+ * capped at `config.maxPreviewBytes` (default 4096 bytes).
+ *
+ * Priority rules:
+ * - `exclude` always wins — excluded fields are never shown, even if in `mask`
+ * - `mask` implies visibility — masked fields are shown (with `maskString`) unless excluded
+ *
+ * Limitations:
+ * - Field names containing dots are not supported (indistinguishable from path separators)
+ * - Array structure is not preserved — fields from array elements are merged into a plain object
+ * - When array elements have heterogeneous shapes at the same field path, later elements
+ *   overwrite earlier primitives in the preview (e.g. `[{ user: "arb" }, { user: { email: "x" } }]`
+ *   produces `{ user: { email: "x" } }` — `"arb"` is lost)
+ *
+ * @example
+ * ```typescript
+ * const preview = buildPreview(order, {
+ *   mode: PreviewMode.EXCLUDE_ALL,
+ *   include: [{ name: "id" }, { name: "status" }],
+ *   mask: [{ name: "email" }],
+ * });
+ * // { id: "order-123", status: "pending", user: { email: "***" } }
+ * ```
+ *
+ * @public
+ */
+export declare function buildPreview(value: any, config: PreviewConfig): Record<string, unknown> | undefined;
+//# sourceMappingURL=preview.d.ts.map

package/dist-types/utils/serdes/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/utils/serdes/preview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,cAAc;IACxB,sEAAsE;IACtE,QAAQ,aAAa;IACrB;;;;OAIG;IACH,IAAI,SAAS;CACd;AAED;;;;GAIG;AACH,oBAAY,WAAW;IACrB,iEAAiE;IACjE,WAAW,gBAAgB;IAC3B,iEAAiE;IACjE,WAAW,gBAAgB;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,IAAI,EAAE,WAAW,CAAC;IAClB,sFAAsF;IACtF,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,sFAAsF;IACtF,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,GAAG,EACV,MAAM,EAAE,aAAa,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAkFrC"}

package/dist-types/utils/serdes/serdes.d.ts

@@ -35,6 +35,35 @@ export interface Serdes<T> {
      */
     deserialize: (data: string | undefined, context: SerdesContext) => Promise<T | undefined>;
 }
+/**
+ * Serdes typed for arbitrary values. Used internally where the concrete type is unknown.
+ * @internal
+ */
+export type AnySerdes = Serdes<any>;
+/**
+ * Deserialize-only Serdes typed for arbitrary values. Used for callback deserializers.
+ * @internal
+ */
+export type AnySerdesDeserializer = Pick<AnySerdes, "deserialize">;
+/**
+ * Configuration for default serdes behavior on a DurableContext.
+ *
+ * @public
+ */
+export interface SerdesConfig {
+    /**
+     * Default serdes used for step, runInChildContext, invoke, and waitForCondition results.
+     * Falls back to the built-in JSON serdes if not provided.
+     */
+    defaultSerdes?: AnySerdes;
+    /**
+     * Default deserializer used for createCallback and waitForCallback results.
+     * If not provided, falls back to the built-in passthrough (raw string) deserializer,
+     * regardless of whether defaultSerdes is set.
+     * Must be set explicitly to use a custom deserializer for callbacks.
+     */
+    defaultCallbackDeserializer?: AnySerdesDeserializer;
+}
 /**
  * Default Serdes implementation using JSON.stringify and JSON.parse
  * Wrapped in Promise.resolve() to maintain async interface compatibility

package/dist-types/utils/serdes/serdes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serdes.d.ts","sourceRoot":"","sources":["../../../src/utils/serdes/serdes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,CACT,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,WAAW,EAAE,CACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,GAAG,CAYrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,GAAG,EAAE,UAAU,CAAC,GACf,MAAM,CAAC,CAAC,CAAC,CAeX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,MAAM,EACzD,GAAG,EAAE,UAAU,CAAC,EAChB,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,CAAC,CAAC,CAAC,CA2CX"}
+{"version":3,"file":"serdes.d.ts","sourceRoot":"","sources":["../../../src/utils/serdes/serdes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,CACT,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,WAAW,EAAE,CACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CAC7B;AAED;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;IAE1B;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,qBAAqB,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,GAAG,CAYrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,GAAG,EAAE,UAAU,CAAC,GACf,MAAM,CAAC,CAAC,CAAC,CAeX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,MAAM,EACzD,GAAG,EAAE,UAAU,CAAC,EAChB,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,CAAC,CAAC,CAAC,CA2CX"}

package/dist-types/utils/with-retry/index.d.ts

@@ -0,0 +1,188 @@
+import { DurableContext } from "../../types/durable-context";
+import { RetryDecision } from "../../types";
+import { ChildConfig } from "../../types/child-context";
+/**
+ * Configuration for {@link withRetry}.
+ *
+ * @typeParam T - The resolved value type of a successful attempt. Used to
+ * type {@link WithRetryConfig.childContextConfig}. Inferred automatically
+ * from the function passed to {@link withRetry}; callers rarely need to
+ * specify it explicitly.
+ *
+ * @public
+ */
+export interface WithRetryConfig<T> {
+    /**
+     * Strategy for retrying failed attempts. Uses the same signature as
+     * {@link StepConfig.retryStrategy}, so values produced by
+     * {@link createRetryStrategy} or entries of {@link retryPresets} can be
+     * passed directly.
+     *
+     * @param error - The error thrown by the most recent attempt.
+     * @param attemptCount - The 1-based attempt number that just failed.
+     * @returns A {@link RetryDecision} describing whether to retry and the
+     * backoff delay to use before the next attempt.
+     *
+     * @example
+     * ```typescript
+     * retryStrategy: (error, attempt) => ({
+     *   shouldRetry: attempt < 3,
+     *   delay: { seconds: 2 ** attempt },
+     * })
+     * ```
+     */
+    retryStrategy: (error: Error, attemptCount: number) => RetryDecision;
+    /**
+     * Wrap the retry loop (attempts + backoff waits) in `runInChildContext`
+     * so attempts are grouped under a single operation in the execution
+     * history. When a `name` is provided it's used as the child context's
+     * name; otherwise the child context is anonymous.
+     *
+     * @remarks
+     * Changing this flag changes the shape of thrown errors:
+     * - When `true` (default), a final failure is rethrown as a
+     *   {@link ChildContextError} that wraps the original error on its `cause`
+     *   property (standard `runInChildContext` behavior).
+     * - When `false`, the original error from the final failed attempt is
+     *   rethrown unchanged.
+     *
+     * Code that uses `instanceof` to branch on error type should account for
+     * this, or always inspect `error.cause`.
+     *
+     * @defaultValue true
+     */
+    wrapWithRunInChildContext?: boolean;
+    /**
+     * Optional {@link ChildConfig} forwarded to the wrapping
+     * `context.runInChildContext` call (e.g. `serdes`, `subType`,
+     * `errorMapper`, `virtualContext`).
+     *
+     * @remarks
+     * Ignored when {@link WithRetryConfig.wrapWithRunInChildContext} is
+     * `false`.
+     *
+     * If `errorMapper` is provided it runs on errors produced by the child
+     * context (i.e. after retries are exhausted), not on per-attempt errors
+     * handed to {@link WithRetryConfig.retryStrategy}.
+     */
+    childContextConfig?: ChildConfig<T>;
+}
+/**
+ * A function executed by {@link withRetry} on each attempt.
+ *
+ * @remarks
+ * The body can contain any chunk of durable-execution logic — multiple
+ * steps, waits, callbacks, invokes, etc. — not just a single durable
+ * operation.
+ *
+ * @typeParam T - The resolved value type of a successful attempt.
+ * @param context - The {@link DurableContext} to use for durable operations.
+ * When {@link WithRetryConfig.wrapWithRunInChildContext} is enabled this is
+ * the child context.
+ * @param attempt - The 1-based attempt number. Provided as metadata; useful
+ * for logging or for incorporating into operation names to improve execution
+ * history readability. Not required for correctness — the SDK disambiguates
+ * operations by call-site position.
+ * @returns A promise for the successful result. If it rejects, the error is
+ * passed to {@link WithRetryConfig.retryStrategy} to decide whether to
+ * retry.
+ *
+ * @public
+ */
+export type RetryableFunc<T> = (context: DurableContext, attempt: number) => Promise<T>;
+/**
+ * Runs a chunk of durable-execution logic with retries. Semantically a
+ * `runInChildContext` with a retry policy wrapped around it — on failure the
+ * whole function body is re-run from the beginning with configurable
+ * backoff, using the same `retryStrategy` shape as {@link StepConfig}.
+ *
+ * @remarks
+ * Unlike `context.step()`, durable operations such as `waitForCallback` and
+ * `invoke` cannot be nested inside a step. `withRetry` runs the function at
+ * the top level and uses `context.wait` between attempts for backoff. By
+ * default the whole loop is wrapped in `context.runInChildContext` for
+ * isolation (opt out with `wrapWithRunInChildContext: false`); the child
+ * context is named when `name` is provided and anonymous otherwise.
+ *
+ * The function body can contain multiple durable operations — this is
+ * effectively "retry this block of logic," not "retry one operation."
+ *
+ * Because the SDK identifies durable operations by call-site position,
+ * unique per-attempt names are not required for correctness. Callers may
+ * still incorporate `attempt` into operation names (e.g.
+ * "`my-callback-${attempt}`") to make execution history easier to read.
+ * Backoff waits are named automatically as `${name}-backoff-${attempt}`
+ * when `name` is provided; otherwise they are anonymous.
+ *
+ * @typeParam T - The resolved value type of a successful attempt.
+ * @param context - The parent {@link DurableContext}.
+ * @param name - Optional name used for the enclosing child context and
+ * backoff wait operations. Omit to run the retry loop directly in `context`.
+ * @param func - The function to execute on each attempt.
+ * @param config - Retry configuration.
+ * @returns The result of the first successful attempt.
+ * @throws \{ChildContextError\} When `wrapWithRunInChildContext` is `true`
+ * (default) and retries are exhausted or `retryStrategy` returns
+ * `shouldRetry: false`. The original error from the final failed attempt is
+ * available on the `cause` property.
+ * @throws When `wrapWithRunInChildContext` is `false`, the original error
+ * from the final failed attempt is rethrown unchanged.
+ *
+ * @example Named (wrapped in a child context by default)
+ * ```typescript
+ * import {
+ *   withRetry,
+ *   createRetryStrategy,
+ * } from "@aws/durable-execution-sdk-js";
+ *
+ * const decision = await withRetry(
+ *   context,
+ *   "approval",
+ *   (ctx, attempt) =>
+ *     ctx.waitForCallback(`approval-${attempt}`, submitter, {
+ *       timeout: { hours: 24 },
+ *     }),
+ *   {
+ *     retryStrategy: createRetryStrategy({
+ *       maxAttempts: 3,
+ *       initialDelay: { seconds: 2 },
+ *       backoffRate: 2,
+ *     }),
+ *   },
+ * );
+ * ```
+ *
+ * @example Anonymous (no child-context name)
+ * ```typescript
+ * const result = await withRetry(
+ *   context,
+ *   (ctx, attempt) =>
+ *     ctx.invoke(`charge-${attempt}`, paymentFnArn, { orderId }),
+ *   {
+ *     retryStrategy: (_err, attempt) => ({
+ *       shouldRetry: attempt < 3,
+ *       delay: { seconds: 1 },
+ *     }),
+ *   },
+ * );
+ * ```
+ *
+ * @see {@link createRetryStrategy}
+ * @see {@link retryPresets}
+ * @see {@link StepConfig}
+ *
+ * @public
+ */
+export declare function withRetry<T>(context: DurableContext, name: string, func: RetryableFunc<T>, config: WithRetryConfig<T>): Promise<T>;
+/**
+ * Anonymous overload of {@link withRetry}.
+ *
+ * @remarks
+ * Same behavior as the named overload, but the enclosing
+ * `runInChildContext` (when `wrapWithRunInChildContext` is enabled) and the
+ * backoff waits are anonymous.
+ *
+ * @public
+ */
+export declare function withRetry<T>(context: DurableContext, func: RetryableFunc<T>, config: WithRetryConfig<T>): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist-types/utils/with-retry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/with-retry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,aAAa,CAAC;IAErE;;;;;;;;;;;;;;;;;;OAkBG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAEpC;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAAC;AACd;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist-types/utils/with-retry/index.test.d.ts

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

package/dist-types/utils/with-retry/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../src/utils/with-retry/index.test.ts"],"names":[],"mappings":""}

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

@@ -1 +1 @@
-{"version":3,"file":"with-durable-execution.d.ts","sourceRoot":"","sources":["../src/with-durable-execution.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,aAAa,EAMd,MAAM,SAAS,CAAC;AAKjB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AA8PnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,eAAO,MAAM,oBAAoB,GAE/B,MAAM,GAAG,GAAG,EAEZ,OAAO,GAAG,GAAG,EACb,OAAO,SAAS,aAAa,GAAG,aAAa,EAE7C,SAAS,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAC1D,SAAS,sBAAsB,KAC9B,oBAiBF,CAAC"}
+{"version":3,"file":"with-durable-execution.d.ts","sourceRoot":"","sources":["../src/with-durable-execution.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,aAAa,EAMd,MAAM,SAAS,CAAC;AAKjB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AA8PnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,eAAO,MAAM,oBAAoB,GAE/B,MAAM,GAAG,GAAG,EAEZ,OAAO,GAAG,GAAG,EACb,OAAO,SAAS,aAAa,GAAG,aAAa,EAE7C,SAAS,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAC1D,SAAS,sBAAsB,KAC9B,oBA6BF,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@aws/durable-execution-sdk-js",
   "description": "AWS Durable Execution Language SDK for TypeScript",
   "license": "Apache-2.0",
-  "version": "1.1.1",
+  "version": "2.0.0-alpha.1",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/aws/aws-durable-execution-sdk-js.git",
@@ -57,7 +57,7 @@
     "@typescript-eslint/parser": "^8.25.0",
     "eslint": "^9.21.0",
     "eslint-plugin-filename-convention": "file:scripts/eslint-plugin-filename-convention",
-    "eslint-plugin-tsdoc": "^0.4.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "jest": "^29.7.0",
     "prettier": "^3.5.2",
     "rimraf": "^5.0.10",
@@ -66,7 +66,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@aws-sdk/client-lambda": "^3.943.0"
+    "@aws-sdk/client-lambda": "^3.1014.0"
   },
   "private": false
 }