From 930de1cddb2e7f344a1061a17863438794eb4a10 Mon Sep 17 00:00:00 2001
From: Abhishek Chauhan <60182103+abhu85@users.noreply.github.com>
Date: Fri, 20 Feb 2026 18:53:54 +0000
Subject: [PATCH] docs: fix map operation examples to return JSON-serializable
 dict

Fix issue #301: Map operation examples were returning BatchResult
directly, which is not JSON serializable and causes Lambda to fail.

Changes:
- Update all handler return types from BatchResult[T] to dict
- Add .to_dict() calls to convert BatchResult before returning
- Add explanatory comments about JSON serialization requirement
- Update "Getting started" description to reflect dict return type
- Keep one example showing how to extract and filter results

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/core/map.md | 42 ++++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/docs/core/map.md b/docs/core/map.md
index 37ee489..2e67119 100644
--- a/docs/core/map.md
+++ b/docs/core/map.md
@@ -74,19 +74,20 @@ def square(context: DurableContext, item: int, index: int, items: list[int]) ->
     return item * item
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[int]:
+def handler(event: dict, context: DurableContext) -> dict:
     """Process a list of items using map operations."""
     items = [1, 2, 3, 4, 5]
-    
+
     result = context.map(items, square)
-    return result
+    # Convert to dict for JSON serialization (BatchResult is not JSON serializable)
+    return result.to_dict()
 ```
 
 When this function runs:
 1. Each item is processed in parallel
 2. The `square` function is called for each item
 3. Each result is checkpointed independently
-4. The function returns a `BatchResult` with results `[1, 4, 9, 16, 25]`
+4. The function returns a dict with results `[1, 4, 9, 16, 25]`
 
 If the function is interrupted after processing items 0-2, it resumes at item 3 without reprocessing the first three items.
 
@@ -162,10 +163,10 @@ def validate_email(
     }
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
+def handler(event: dict, context: DurableContext) -> dict:
     emails = ["jane_doe@example.com", "john_doe@example.org", "invalid"]
     result = context.map(emails, validate_email)
-    return result
+    return result.to_dict()
 ```
 
 [↑ Back to top](#table-of-contents)
@@ -190,7 +191,7 @@ def process_item(context: DurableContext, item: int, index: int, items: list[int
     return {"item": item, "squared": item * item}
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
+def handler(event: dict, context: DurableContext) -> dict:
     items = list(range(100))
 
     # Configure map operation
@@ -200,7 +201,7 @@ def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
     )
 
     result = context.map(items, process_item, name="process_numbers", config=config)
-    return result
+    return result.to_dict()
 ```
 
 ### MapConfig parameters
@@ -237,15 +238,14 @@ def fetch_data(context: DurableContext, url: str, index: int, urls: list[str]) -
     return {"url": url, "data": "..."}
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
+def handler(event: dict, context: DurableContext) -> dict:
     urls = [f"https://example.com/api/{i}" for i in range(100)]
-    
+
     # Process only 5 URLs at a time
     config = MapConfig(max_concurrency=5)
-    
+
     result = context.map(urls, fetch_data, config=config)
-    return result
-```
+    return result.to_dict()```
 
 ### Custom completion criteria
 
@@ -262,9 +262,9 @@ def process_item(context: DurableContext, item: int, index: int, items: list[int
     return {"item": item, "processed": True}
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
+def handler(event: dict, context: DurableContext) -> dict:
     items = list(range(20))
-    
+
     # Succeed if at least 15 items succeed, fail after 5 failures
     config = MapConfig(
         completion_config=CompletionConfig(
@@ -272,9 +272,9 @@ def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
             tolerated_failure_count=5,
         )
     )
-    
+
     result = context.map(items, process_item, config=config)
-    return result
+    return result.to_dict()
 ```
 
 ### Using context operations in map functions
@@ -307,11 +307,13 @@ def process_user(
     return {"user_id": user_id, "notification_sent": notification["sent"]}
 
 @durable_execution
-def handler(event: dict, context: DurableContext) -> BatchResult[dict]:
+def handler(event: dict, context: DurableContext) -> dict:
+    """Process multiple users using context operations within map functions."""
     user_ids = ["user_1", "user_2", "user_3"]
-    
+
     result = context.map(user_ids, process_user)
-    return result
+    # Convert to dict for JSON serialization (BatchResult is not JSON serializable)
+    return result.to_dict()
 ```
 
 ### Filtering and transforming results