docs: map

- Replace Python-centric page with language-neutral rewrite
- Add TypeScript, Python, and Java examples for all sections
- Add Map Function subsection under Method signature with
  per-language type signatures and parameter docs
- Document MapResult (Java) vs BatchResult (TS/Python) difference
- Document SKIPPED status in Java vs STARTED in TS/Python
- Fix completion strategy tables in map.md and parallel.md
  (were collapsed by mdformat; fixed with mdformat-gfm tables extension)
- Remove item_batcher from MapConfig docs (not implemented)
- Remove ToC, Terminology, Key Features, Best Practices,
  Performance Tips, FAQ, Testing sections

closes #19, closes #22, closes #74, closes #56, closes #93, closes #94, ref #96

Author: yaythomas

docs/sdk-reference/operations/map.md

@@ -0,0 +1,25 @@
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.CompletionConfig;
+import software.amazon.lambda.durable.config.MapConfig;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class MapCompletionConfig extends DurableHandler<List<String>, List<String>> {
+    @Override
+    public List<String> handleRequest(List<String> items, DurableContext context) {
+        var config = MapConfig.builder()
+                .completionConfig(CompletionConfig.minSuccessful(3))
+                .build();
+
+        MapResult<String> result = context.map(
+                "process-items",
+                items,
+                String.class,
+                (item, index, ctx) -> ctx.step(
+                        "process-" + index, String.class, s -> item.toUpperCase()),
+                config);
+
+        return result.succeeded();
+    }
+}

examples/java/operations/map/completion-config.java

@@ -0,0 +1,28 @@
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class MapErrorHandling extends DurableHandler<List<String>, Void> {
+    @Override
+    public Void handleRequest(List<String> items, DurableContext context) {
+        MapResult<String> result = context.map(
+                "process-items",
+                items,
+                String.class,
+                (item, index, ctx) -> ctx.step("process-" + index, String.class, s -> {
+                    if ("bad".equals(item)) throw new IllegalArgumentException("bad item");
+                    return item.toUpperCase();
+                }));
+
+        var failures = result.failed();
+        if (!failures.isEmpty()) {
+            System.out.println(failures.size() + " items failed");
+            failures.forEach(e -> System.out.println(e.errorType() + ": " + e.errorMessage()));
+        }
+
+        var successes = result.succeeded();
+        System.out.println(successes.size() + " items succeeded: " + successes);
+        return null;
+    }
+}

examples/java/operations/map/error-handling.java

@@ -0,0 +1,34 @@
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.CompletionConfig;
+import software.amazon.lambda.durable.config.MapConfig;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class MapConfigExample extends DurableHandler<List<String>, List<String>> {
+    private static final HttpClient HTTP = HttpClient.newHttpClient();
+
+    @Override
+    public List<String> handleRequest(List<String> urls, DurableContext context) {
+        var config = MapConfig.builder()
+                .maxConcurrency(5)
+                .completionConfig(CompletionConfig.toleratedFailureCount(2))
+                .build();
+
+        MapResult<String> result = context.map(
+                "fetch-urls",
+                urls,
+                String.class,
+                (url, index, ctx) -> ctx.step("fetch-" + index, String.class, s -> {
+                    var request = HttpRequest.newBuilder(URI.create(url)).build();
+                    return HTTP.send(request, HttpResponse.BodyHandlers.ofString()).body();
+                }),
+                config);
+
+        return result.succeeded();
+    }
+}

examples/java/operations/map/map-config.java

@@ -0,0 +1,14 @@
+import software.amazon.lambda.durable.DurableContext;
+
+record Order(String id, double amount) {}
+record Receipt(String orderId, double charged) {}
+
+// MapFunction<Order, Receipt> implementation
+Receipt processOrder(Order order, int index, DurableContext ctx) {
+    var validated = ctx.step("validate", Order.class, s -> {
+        if (order.amount() <= 0) throw new IllegalArgumentException("Invalid amount");
+        return order;
+    });
+    var charged = ctx.step("charge", Double.class, s -> validated.amount());
+    return new Receipt(validated.id(), charged);
+}

examples/java/operations/map/map-function.java

@@ -0,0 +1,21 @@
+// sync — blocks until all items complete
+<I, O> MapResult<O> map(String name, Collection<I> items, Class<O> resultType,
+                        MapFunction<I, O> function)
+<I, O> MapResult<O> map(String name, Collection<I> items, Class<O> resultType,
+                        MapFunction<I, O> function, MapConfig config)
+<I, O> MapResult<O> map(String name, Collection<I> items, TypeToken<O> resultType,
+                        MapFunction<I, O> function)
+<I, O> MapResult<O> map(String name, Collection<I> items, TypeToken<O> resultType,
+                        MapFunction<I, O> function, MapConfig config)
+
+// async — returns immediately
+<I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items,
+                                            Class<O> resultType, MapFunction<I, O> function)
+<I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items,
+                                            Class<O> resultType, MapFunction<I, O> function,
+                                            MapConfig config)
+<I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items,
+                                            TypeToken<O> resultType, MapFunction<I, O> function)
+<I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items,
+                                            TypeToken<O> resultType, MapFunction<I, O> function,
+                                            MapConfig config)

examples/java/operations/map/map-signature.java

@@ -0,0 +1,19 @@
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class NamedMap extends DurableHandler<List<String>, List<String>> {
+    @Override
+    public List<String> handleRequest(List<String> userIds, DurableContext context) {
+        // The name is always required in Java
+        MapResult<String> result = context.map(
+                "process-users",
+                userIds,
+                String.class,
+                (userId, index, ctx) -> ctx.step(
+                        "process-" + index, String.class, s -> "processed-" + userId));
+
+        return result.succeeded();
+    }
+}

examples/java/operations/map/named-map.java

@@ -0,0 +1,28 @@
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class NestedMap extends DurableHandler<List<Region>, List<List<String>>> {
+    record Region(String name, List<String> items) {}
+
+    @Override
+    public List<List<String>> handleRequest(List<Region> regions, DurableContext context) {
+        MapResult<List<String>> result = context.map(
+                "process-regions",
+                regions,
+                new TypeToken<List<String>>() {},
+                (region, index, ctx) -> {
+                    MapResult<String> inner = ctx.map(
+                            "process-" + region.name(),
+                            region.items(),
+                            String.class,
+                            (item, i, innerCtx) -> innerCtx.step(
+                                    "item-" + i, String.class, s -> item.toUpperCase()));
+                    return inner.succeeded();
+                });
+
+        return result.succeeded();
+    }
+}

examples/java/operations/map/nested-map.java

@@ -0,0 +1,18 @@
+import java.util.List;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.model.MapResult;
+
+public class SimpleMap extends DurableHandler<Void, List<Integer>> {
+    @Override
+    public List<Integer> handleRequest(Void input, DurableContext context) {
+        MapResult<Integer> result = context.map(
+                "square-numbers",
+                List.of(1, 2, 3, 4, 5),
+                Integer.class,
+                (item, index, ctx) -> ctx.step(
+                        "square-" + index, Integer.class, s -> item * item));
+
+        return result.results();
+    }
+}

examples/java/operations/map/simple-map.java

@@ -0,0 +1,26 @@
+from aws_durable_execution_sdk_python import (
+    BatchResult,
+    DurableContext,
+    durable_execution,
+)
+from aws_durable_execution_sdk_python.config import CompletionConfig, MapConfig
+
+
+def process_item(
+    ctx: DurableContext, item: str, index: int, items: list[str]
+) -> str:
+    return ctx.step(lambda _: item.upper(), name=f"process-{index}")
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> list[str]:
+    config = MapConfig(
+        completion_config=CompletionConfig(min_successful=3),
+    )
+    result: BatchResult[str] = context.map(
+        event["items"],
+        process_item,
+        name="process-items",
+        config=config,
+    )
+    return result.to_dict()