docs: serialization

yaythomas · yaythomas · commit facfab84e2f3 · 2026-04-10T10:42:49.000-07:00
- Rewrite serialization.md as language-neutral SDK reference - Add TypeScript, Python, and Java examples for all sections - Remove ToC, back-links, Terminology, Key Features, Best Practices, and FAQ listicles - Add Lambda handler serialization section with Python DynamoDB footgun callout - Collapse built-in SerDes helpers into single tabbed section - Fix broken links to error-handling, callback, and map pages Closes #43, Closes #67, Closes #49
diff --git a/docs/sdk-reference/state/serialization.md b/docs/sdk-reference/state/serialization.md
diff --git a/examples/java/sdk-reference/serialization/CallbackConfigExample.java b/examples/java/sdk-reference/serialization/CallbackConfigExample.java
@@ -0,0 +1,21 @@
+import java.util.Map;
+import software.amazon.lambda.durable.DurableCallbackFuture;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.CallbackConfig;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+
+public class CallbackConfigExample extends DurableHandler<Object, Map<String, Object>> {
+    @Override
+    public Map<String, Object> handleRequest(Object input, DurableContext context) {
+        CallbackConfig config = CallbackConfig.builder()
+            .serDes(new JacksonSerDes())
+            .build();
+
+        DurableCallbackFuture<Map<String, Object>> callback =
+            context.createCallback("await-approval", Map.class, config);
+
+        // Send callback.getCallbackId() to the external system here.
+        return callback.get();
+    }
+}
diff --git a/examples/java/sdk-reference/serialization/MapConfigExample.java b/examples/java/sdk-reference/serialization/MapConfigExample.java
@@ -0,0 +1,26 @@
+import java.util.List;
+import java.util.Map;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.MapConfig;
+import software.amazon.lambda.durable.model.MapResult;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+
+public class MapConfigExample extends DurableHandler<Object, List<Map<String, String>>> {
+    @Override
+    public List<Map<String, String>> handleRequest(Object input, DurableContext context) {
+        MapConfig config = MapConfig.builder()
+            .serDes(new JacksonSerDes())
+            .build();
+
+        List<String> items = List.of("a", "b", "c");
+        MapResult<Map<String, String>> result = context.map(
+            "process-items",
+            items,
+            Map.class,
+            (item, index, ctx) -> Map.of("id", item, "status", "done"),
+            config
+        );
+        return result.succeeded();
+    }
+}
diff --git a/examples/java/sdk-reference/serialization/OrderSerDes.java b/examples/java/sdk-reference/serialization/OrderSerDes.java
@@ -0,0 +1,26 @@
+import com.fasterxml.jackson.databind.ObjectMapper;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.exception.SerDesException;
+import software.amazon.lambda.durable.serde.SerDes;
+
+public class OrderSerDes implements SerDes {
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    @Override
+    public String serialize(Object value) {
+        try {
+            return mapper.writeValueAsString(value);
+        } catch (Exception e) {
+            throw new SerDesException("Serialization failed", e);
+        }
+    }
+
+    @Override
+    public <T> T deserialize(String data, TypeToken<T> typeToken) {
+        try {
+            return mapper.readValue(data, mapper.getTypeFactory().constructType(typeToken.getType()));
+        } catch (Exception e) {
+            throw new SerDesException("Deserialization failed", e);
+        }
+    }
+}
diff --git a/examples/java/sdk-reference/serialization/PassThroughSerdesExample.java b/examples/java/sdk-reference/serialization/PassThroughSerdesExample.java
@@ -0,0 +1,38 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.StepContext;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.config.StepConfig;
+import software.amazon.lambda.durable.exception.SerDesException;
+import software.amazon.lambda.durable.serde.SerDes;
+
+// A pass-through SerDes stores the value as-is (already a JSON string).
+class PassThroughSerDes implements SerDes {
+    @Override
+    public String serialize(Object value) {
+        return (String) value;
+    }
+
+    @Override
+    public <T> T deserialize(String data, TypeToken<T> typeToken) {
+        @SuppressWarnings("unchecked")
+        T result = (T) data;
+        return result;
+    }
+}
+
+public class PassThroughSerdesExample extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object input, DurableContext context) {
+        StepConfig config = StepConfig.builder()
+            .serDes(new PassThroughSerDes())
+            .build();
+
+        return context.step(
+            "fetch-raw",
+            String.class,
+            (StepContext ctx) -> "{\"id\":\"order-123\"}",
+            config
+        );
+    }
+}
diff --git a/examples/java/sdk-reference/serialization/SerdesInterface.java b/examples/java/sdk-reference/serialization/SerdesInterface.java
@@ -0,0 +1,9 @@
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.serde.SerDes;
+
+// SerDes interface
+interface SerDesInterface {
+    String serialize(Object value);
+
+    <T> T deserialize(String data, TypeToken<T> typeToken);
+}
diff --git a/examples/java/sdk-reference/serialization/StepConfigExample.java b/examples/java/sdk-reference/serialization/StepConfigExample.java
@@ -0,0 +1,23 @@
+import java.util.Map;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.StepContext;
+import software.amazon.lambda.durable.config.StepConfig;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+
+public class StepConfigExample extends DurableHandler<Object, Map<String, String>> {
+    @Override
+    public Map<String, String> handleRequest(Object input, DurableContext context) {
+        StepConfig config = StepConfig.builder()
+            .serDes(new JacksonSerDes())
+            .build();
+
+        Map<String, String> order = context.step(
+            "fetch-order",
+            Map.class,
+            (StepContext ctx) -> Map.of("id", "order-123", "total", "99.99"),
+            config
+        );
+        return order;
+    }
+}
diff --git a/examples/java/sdk-reference/serialization/Walkthrough.java b/examples/java/sdk-reference/serialization/Walkthrough.java
@@ -0,0 +1,17 @@
+import java.util.Map;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.StepContext;
+
+public class Walkthrough extends DurableHandler<Object, Map<String, String>> {
+    @Override
+    public Map<String, String> handleRequest(Object input, DurableContext context) {
+        // No SerDes config — the SDK serializes and deserializes the result automatically.
+        Map<String, String> order = context.step(
+            "fetch-order",
+            Map.class,
+            (StepContext ctx) -> Map.of("id", "order-123", "total", "99.99")
+        );
+        return order;
+    }
+}
diff --git a/examples/python/sdk-reference/serialization/builtin-helpers.py b/examples/python/sdk-reference/serialization/builtin-helpers.py
@@ -0,0 +1,25 @@
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import StepConfig
+from aws_durable_execution_sdk_python.serdes import JsonSerDes, PassThroughSerDes
+
+# PassThroughSerDes — stores the value as-is (must already be a string)
+# JsonSerDes — standard json.dumps / json.loads, no envelope format
+
+
+@durable_step
+def fetch_raw(ctx: StepContext) -> str:
+    return '{"id":"order-123"}'
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> str:
+    raw = context.step(
+        fetch_raw(),
+        config=StepConfig(serdes=PassThroughSerDes()),
+    )
+    return raw
diff --git a/examples/python/sdk-reference/serialization/callback-config.py b/examples/python/sdk-reference/serialization/callback-config.py
@@ -0,0 +1,28 @@
+import json
+
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    durable_execution,
+)
+from aws_durable_execution_sdk_python.config import CallbackConfig
+from aws_durable_execution_sdk_python.serdes import SerDes, SerDesContext
+
+
+class ApprovalSerDes(SerDes[dict]):
+    def serialize(self, value: dict, ctx: SerDesContext) -> str:
+        return json.dumps(value)
+
+    def deserialize(self, data: str, ctx: SerDesContext) -> dict:
+        return json.loads(data)
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    callback = context.create_callback(
+        "await-approval",
+        config=CallbackConfig(serdes=ApprovalSerDes()),
+    )
+
+    # Send callback.callback_id to the external system here.
+    result = callback.result()
+    return result
diff --git a/examples/python/sdk-reference/serialization/custom-serdes.py b/examples/python/sdk-reference/serialization/custom-serdes.py
@@ -0,0 +1,11 @@
+import json
+
+from aws_durable_execution_sdk_python.serdes import SerDes, SerDesContext
+
+
+class OrderSerDes(SerDes[dict]):
+    def serialize(self, value: dict, ctx: SerDesContext) -> str:
+        return json.dumps(value)
+
+    def deserialize(self, data: str, ctx: SerDesContext) -> dict:
+        return json.loads(data)
diff --git a/examples/python/sdk-reference/serialization/map-config.py b/examples/python/sdk-reference/serialization/map-config.py
@@ -0,0 +1,27 @@
+import json
+
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    durable_execution,
+)
+from aws_durable_execution_sdk_python.config import MapConfig
+from aws_durable_execution_sdk_python.serdes import SerDes, SerDesContext
+
+
+class ItemSerDes(SerDes[dict]):
+    def serialize(self, value: dict, ctx: SerDesContext) -> str:
+        return json.dumps(value)
+
+    def deserialize(self, data: str, ctx: SerDesContext) -> dict:
+        return json.loads(data)
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> list:
+    items = ["a", "b", "c"]
+    result = context.map(
+        items,
+        lambda ctx, item, idx, arr: {"id": item, "status": "done"},
+        config=MapConfig(item_serdes=ItemSerDes()),
+    )
+    return result.get_results()
diff --git a/examples/python/sdk-reference/serialization/pass-through-serdes.py b/examples/python/sdk-reference/serialization/pass-through-serdes.py
@@ -0,0 +1,22 @@
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import StepConfig
+from aws_durable_execution_sdk_python.serdes import PassThroughSerDes
+
+
+@durable_step
+def fetch_raw(ctx: StepContext) -> str:
+    return '{"id":"order-123"}'
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> str:
+    raw = context.step(
+        fetch_raw(),
+        config=StepConfig(serdes=PassThroughSerDes()),
+    )
+    return raw
diff --git a/examples/python/sdk-reference/serialization/serdes-interface.py b/examples/python/sdk-reference/serialization/serdes-interface.py
@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class SerDesContext:
+    operation_id: str = ""
+    durable_execution_arn: str = ""
+
+
+class SerDes(ABC, Generic[T]):
+    @abstractmethod
+    def serialize(self, value: T, serdes_context: SerDesContext) -> str: ...
+
+    @abstractmethod
+    def deserialize(self, data: str, serdes_context: SerDesContext) -> T: ...
diff --git a/examples/python/sdk-reference/serialization/step-config.py b/examples/python/sdk-reference/serialization/step-config.py
@@ -0,0 +1,32 @@
+import json
+
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import StepConfig
+from aws_durable_execution_sdk_python.serdes import SerDes, SerDesContext
+
+
+class OrderSerDes(SerDes[dict]):
+    def serialize(self, value: dict, ctx: SerDesContext) -> str:
+        return json.dumps(value)
+
+    def deserialize(self, data: str, ctx: SerDesContext) -> dict:
+        return json.loads(data)
+
+
+@durable_step
+def fetch_order(ctx: StepContext) -> dict:
+    return {"id": "order-123", "total": "99.99"}
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    order = context.step(
+        fetch_order(),
+        config=StepConfig(serdes=OrderSerDes()),
+    )
+    return order
diff --git a/examples/python/sdk-reference/serialization/walkthrough.py b/examples/python/sdk-reference/serialization/walkthrough.py
@@ -0,0 +1,18 @@
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+
+
+@durable_step
+def fetch_order(ctx: StepContext) -> dict:
+    return {"id": "order-123", "total": "99.99"}
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    # No SerDes config — the SDK serializes and deserializes the result automatically.
+    order = context.step(fetch_order())
+    return order
diff --git a/examples/typescript/sdk-reference/serialization/builtin-helpers.ts b/examples/typescript/sdk-reference/serialization/builtin-helpers.ts
@@ -0,0 +1,28 @@
+import {
+  DurableContext,
+  createClassSerdes,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+
+class Order {
+  id: string = "";
+  total: string = "";
+
+  label() {
+    return `Order ${this.id} — ${this.total}`;
+  }
+}
+
+const orderSerdes = createClassSerdes(Order);
+
+export const handler = withDurableExecution(
+  async (event: unknown, context: DurableContext) => {
+    const order = await context.step(
+      "fetch-order",
+      async () => Object.assign(new Order(), { id: "order-123", total: "99.99" }),
+      { serdes: orderSerdes },
+    );
+    // order.label() works — class methods are preserved after deserialization
+    return order.label();
+  },
+);
diff --git a/examples/typescript/sdk-reference/serialization/callback-config.ts b/examples/typescript/sdk-reference/serialization/callback-config.ts
diff --git a/examples/typescript/sdk-reference/serialization/custom-serdes.ts b/examples/typescript/sdk-reference/serialization/custom-serdes.ts
diff --git a/examples/typescript/sdk-reference/serialization/map-config.ts b/examples/typescript/sdk-reference/serialization/map-config.ts
diff --git a/examples/typescript/sdk-reference/serialization/pass-through-serdes.ts b/examples/typescript/sdk-reference/serialization/pass-through-serdes.ts
diff --git a/examples/typescript/sdk-reference/serialization/serdes-interface.ts b/examples/typescript/sdk-reference/serialization/serdes-interface.ts
diff --git a/examples/typescript/sdk-reference/serialization/step-config.ts b/examples/typescript/sdk-reference/serialization/step-config.ts
diff --git a/examples/typescript/sdk-reference/serialization/walkthrough.ts b/examples/typescript/sdk-reference/serialization/walkthrough.ts
