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

package/README.md

@@ -49,8 +49,9 @@ export const lambdaHandler = withDurableExecution(handler);
 
 This README provides a quick reference for the SDK's main features. For more detailed information:
 
+- **[API Reference](../../docs/api-reference/durable-execution-sdk-js.md)** - Complete technical reference with detailed type definitions and operation specifications
 - **[Concepts and Use Cases](src/documents/CONCEPTS.md)** - Learn about the replay model, best practices, and real-world examples including GenAI agents, human-in-the-loop workflows, and saga patterns
-- **[API Specification](src/documents/API_SPECIFICATION.md)** - Complete technical reference with detailed type definitions and operation specifications
+- **[Contributing](../../CONTRIBUTING.md)** - Learn about contributing to the AWS Durable Execution SDK for JavaScript
 
 ## Core Concepts
 
@@ -106,7 +107,7 @@ const orderResult = await context.runInChildContext(
 
 ### Invoking Other Functions
 
-Call other durable functions:
+Call another AWS Lambda function and wait for it complete:
 
 ```typescript
 const result = await context.invoke(
@@ -266,16 +267,6 @@ const results = await context.promise.allSettled([operation1(), operation2()]);
 
 ### Retry Strategies
 
-Built-in retry presets:
-
-```typescript
-import { retryPresets } from "@aws/durable-execution-sdk-js";
-
-await context.step("api-call", async () => callExternalAPI(), {
-  retryStrategy: retryPresets.exponentialBackoff(),
-});
-```
-
 Custom retry strategy:
 
 ```typescript
@@ -287,32 +278,6 @@ await context.step("custom-retry", async () => riskyOperation(), {
 });
 ```
 
-### Serialization
-
-Custom serialization for complex types:
-
-```typescript
-import {
-  createClassSerdes,
-  createClassSerdesWithDates,
-} from "@aws/durable-execution-sdk-js";
-
-class User {
-  constructor(
-    public name: string,
-    public createdAt: Date,
-  ) {}
-}
-
-const result = await context.step(
-  "create-user",
-  async () => new User("Alice", new Date()),
-  {
-    serdes: createClassSerdesWithDates(User, ["createdAt"]),
-  },
-);
-```
-
 ### Step Semantics
 
 Control execution guarantees:
@@ -320,17 +285,37 @@ Control execution guarantees:
 ```typescript
 import { StepSemantics } from "@aws/durable-execution-sdk-js";
 
-// At-most-once per retry (default)
+// At-least-once per retry (default)
+await context.step("retriable-operation", async () => sendNotification(), {
+  semantics: StepSemantics.AtLeastOncePerRetry,
+});
+
+// At-most-once per retry
 await context.step("idempotent-operation", async () => updateDatabase(), {
   semantics: StepSemantics.AtMostOncePerRetry,
 });
+```
 
-// At-least-once per retry
-await context.step("retriable-operation", async () => sendNotification(), {
-  semantics: StepSemantics.AtLeastOncePerRetry,
-});
+**Important**: These semantics apply _per retry_, not per overall execution:
+
+- **AtLeastOncePerRetry**: The step will execute at least once on each retry attempt. If the step succeeds but the checkpoint fails (e.g., sandbox crash), the step will re-execute on replay.
+- **AtMostOncePerRetry**: The step will execute at most once per retry attempt. A checkpoint is created before execution, so if a failure occurs after the checkpoint but before step completion, the previous step retry attempt is skipped on replay.
+
+**To achieve at-most-once semantics on a step-level**, use a custom retry strategy:
+
+```typescript
+await context.step(
+  "truly-once-only",
+  async () => callThatCannotTolerateDuplicates(),
+  {
+    semantics: StepSemantics.AtMostOncePerRetry,
+    retryStrategy: () => ({ shouldRetry: false }), // No retries
+  },
+);
 ```
 
+Without this, a step using `AtMostOncePerRetry` with retries enabled could still execute multiple times across different retry attempts.
+
 ### Jitter Strategies
 
 Prevent thundering herd:
@@ -395,18 +380,6 @@ context.configureLogger({
 context.configureLogger({ modeAware: false });
 ```
 
-## Testing Locally
-
-Run durable functions locally for development:
-
-```bash
-# Basic example
-npm run run-locally src/demo/usage-example.ts
-
-# With invocation ID
-npm run run-locally src/demo/retry-config.ts invocation001
-```
-
 ## License
 
 This project is licensed under the Apache-2.0 License.