feat(sdk): add comprehensive JSDoc documentation for DurableContext API (#84)

- Add detailed JSDoc comments for all DurableContext methods
- Include comprehensive parameter descriptions and examples
- Document return types and error conditions
- Revert RetryDecision from discriminated union to interface for
compatibility
- Fix TypeScript compilation errors in examples package

*Description of changes:*

This commit significantly improves the developer experience in IDEs by
providing comprehensive JSDoc documentation for the DurableContext API.
Here's how it helps developers:

## IDE IntelliSense & Autocomplete Benefits

1. Rich Method Documentation
• Hover over any context.step(), context.parallel(), etc. to see
detailed descriptions
• Clear explanations of what each method does and when to use it
• Parameter descriptions with expected types and constraints

2. Interactive Code Examples
• Real TypeScript code examples appear in IDE tooltips
• Copy-paste ready snippets for common patterns
• Shows proper usage patterns and best practices

3. Parameter Guidance
• Detailed descriptions for each parameter (name, functions, configs)
• Type information with constraints (e.g., "must be unique within
execution")
• Optional vs required parameter clarity

4. Return Type Documentation
• Clear descriptions of what each method returns
• Promise resolution types and error conditions
• Helps with proper error handling and result processing

## Example IDE Experience

When typing context.step(, developers now see:
```
step(fn: StepFunc<T>, config?: StepConfig<T>): Promise<T>

Executes a step function with automatic retry and checkpointing capabilities.
Steps are the fundamental unit of work in durable functions...

Parameters:
• fn - The function to execute as a step
• config - Optional configuration for retry strategy and semantics

Example:
const result = await context.step(async () => {
  return await apiCall();
}, { retryStrategy: ... });
```

This transforms the development experience from "figure it out yourself"
to "guided development with rich context."

Co-authored-by: Pooya Paridel <parpooya@amazon.com>

Author: ParidelPooya

package-lock.json

@@ -12,7 +12,11 @@ const STEP_CONFIG_WITH_RETRY_FAILURES_AFTER_1_SECOND_5_TIMES = {
       error,
       `. Retry? ${shouldRetry}. `,
     );
-    return { shouldRetry, delaySeconds: 1 };
+    if (shouldRetry) {
+      return { shouldRetry: true, delaySeconds: 1 };
+    } else {
+      return { shouldRetry: false };
+    }
   },
 };
 

packages/aws-durable-execution-sdk-js-examples/src/examples/steps-with-retry.ts

@@ -243,5 +243,10 @@
     "timestamp": "2025-09-25T21:18:04.199Z",
     "size": 361361,
     "gitCommit": "2ea3ba34da20407b32cbeeb99cf71e61c758016e"
+  },
+  {
+    "timestamp": "2025-09-27T19:52:39.277Z",
+    "size": 361660,
+    "gitCommit": "fed4cf7151607892268067a15ca3430c2f6abbbc"
   }
 ]

packages/aws-durable-execution-sdk-js/bundle-size-history.json

@@ -1,6 +1,7 @@
 const tsParser = require("@typescript-eslint/parser");
 const typescriptEslint = require("@typescript-eslint/eslint-plugin");
 const filenameConvention = require("eslint-plugin-filename-convention");
+const tsdoc = require("eslint-plugin-tsdoc");
 
 module.exports = [
   {
@@ -16,6 +17,7 @@ module.exports = [
     plugins: {
       "@typescript-eslint": typescriptEslint,
       "filename-convention": filenameConvention,
+      "tsdoc": tsdoc,
     },
     rules: {
       ...typescriptEslint.configs.recommended.rules,
@@ -26,6 +28,7 @@ module.exports = [
       "no-debugger": "warn",
       "no-duplicate-imports": "error",
       "filename-convention/kebab-case": "error",
+      "tsdoc/syntax": "warn",
     },
   },
   {

packages/aws-durable-execution-sdk-js/eslint.config.js

@@ -61,6 +61,7 @@
     "aws-lambda": "^1.0.7",
     "eslint": "^9.21.0",
     "eslint-plugin-filename-convention": "file:scripts/eslint-plugin-filename-convention",
+    "eslint-plugin-tsdoc": "^0.4.0",
     "globals": "^14.0.0",
     "husky": "^9.1.7",
     "jest": "^29.7.0",

packages/aws-durable-execution-sdk-js/package.json

@@ -159,7 +159,7 @@ export const createDurableContext = (
 
   const map: DurableContext["map"] = <T>(
     nameOrItems: string | undefined | any[],
-    itemsOrMapFunc?: any[] | MapFunc<T>,
+    itemsOrMapFunc: any[] | MapFunc<T>,
     mapFuncOrConfig?: MapFunc<T> | MapConfig,
     maybeConfig?: MapConfig,
   ) => {

packages/aws-durable-execution-sdk-js/src/context/durable-context/durable-context.ts

@@ -271,14 +271,21 @@ describe("Concurrent Execution Handler", () => {
 
       // Mock the executeOperation function to capture the actual execution
       let capturedExecuteOperation: any;
-      mockRunInChildContext.mockImplementation((name, executeOp, options) => {
-        capturedExecuteOperation = executeOp;
-        return Promise.resolve(
-          new MockBatchResult([
-            { index: 0, result: "result", status: BatchItemStatus.SUCCEEDED },
-          ]) as any,
-        );
-      });
+      mockRunInChildContext.mockImplementation(
+        (nameOrFn: any, fnOrConfig?: any, maybeConfig?: any) => {
+          // Handle the overloaded signature
+          if (typeof nameOrFn === "string" || nameOrFn === undefined) {
+            capturedExecuteOperation = fnOrConfig;
+          } else {
+            capturedExecuteOperation = nameOrFn;
+          }
+          return Promise.resolve(
+            new MockBatchResult([
+              { index: 0, result: "result", status: BatchItemStatus.SUCCEEDED },
+            ]) as any,
+          );
+        },
+      );
 
       await concurrentExecutionHandler(items, executor, config);
 
@@ -295,15 +302,22 @@ describe("Concurrent Execution Handler", () => {
       // Create a real execution context that will execute the actual path
       let actualExecuteOperation: any;
       mockRunInChildContext.mockImplementation(
-        async (name, executeOp, options) => {
-          actualExecuteOperation = executeOp;
+        async (nameOrFn: any, fnOrConfig?: any, maybeConfig?: any) => {
+          // Handle the overloaded signature
+          let actualFn;
+          if (typeof nameOrFn === "string" || nameOrFn === undefined) {
+            actualFn = fnOrConfig;
+          } else {
+            actualFn = nameOrFn;
+          }
+          actualExecuteOperation = actualFn;
           // Execute the actual operation to cover the executeOperation function
-          if (typeof executeOp === "function") {
+          if (typeof actualFn === "function") {
             const mockDurableContext = {
               runInChildContext: jest.fn().mockResolvedValue("test-result"),
             } as any;
 
-            return await executeOp(mockDurableContext);
+            return await actualFn(mockDurableContext);
           }
           return new MockBatchResult([]) as any;
         },
@@ -322,14 +336,21 @@ describe("Concurrent Execution Handler", () => {
       // Test with undefined config to cover the config || {} branch
       let actualExecuteOperation: any;
       mockRunInChildContext.mockImplementation(
-        async (name, executeOp, options) => {
-          actualExecuteOperation = executeOp;
-          if (typeof executeOp === "function") {
+        async (nameOrFn: any, fnOrConfig?: any, maybeConfig?: any) => {
+          // Handle the overloaded signature
+          let actualFn;
+          if (typeof nameOrFn === "string" || nameOrFn === undefined) {
+            actualFn = fnOrConfig;
+          } else {
+            actualFn = nameOrFn;
+          }
+          actualExecuteOperation = actualFn;
+          if (typeof actualFn === "function") {
             const mockDurableContext = {
               runInChildContext: jest.fn().mockResolvedValue("test-result"),
             } as any;
 
-            return await executeOp(mockDurableContext);
+            return await actualFn(mockDurableContext);
           }
           return new MockBatchResult([]) as any;
         },

packages/aws-durable-execution-sdk-js/src/handlers/concurrent-execution-handler/concurrent-execution-handler.test.ts

@@ -180,8 +180,18 @@ describe("Parallel Handler", () => {
     // Mock the executor being called
     let capturedExecutor: any;
     mockExecuteConcurrently.mockImplementation(
-      async (name, items, executor, config) => {
-        capturedExecutor = executor;
+      async (
+        nameOrItems: any,
+        itemsOrExecutor?: any,
+        executorOrConfig?: any,
+        maybeConfig?: any,
+      ) => {
+        // Handle the overloaded signature
+        if (typeof nameOrItems === "string" || nameOrItems === undefined) {
+          capturedExecutor = executorOrConfig;
+        } else {
+          capturedExecutor = itemsOrExecutor;
+        }
         return new MockBatchResult([
           { index: 0, result: "result1", status: BatchItemStatus.SUCCEEDED },
         ]) as any;