Update async order docs to show concurrent execution pattern

- Update CLAUDE.md and README.md with improved async order handling
  examples showing how to return unresolved Promises for parallel
  execution instead of awaiting sequentially
- Add tests for the documented patterns: mixed order types with
  type-based dispatch and error handling for unknown order types

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: DmitryBochkarev

CLAUDE.md

@@ -583,23 +583,32 @@ function fetch(url: string): Promise<any> {
 const data = await fetch("/api/users");
 ```
 
-JavaScript handles these orders and fulfills them:
+JavaScript handles orders by returning unresolved Promises immediately, enabling parallel async operations:
 
 ```javascript
-async function handleOrders(orders) {
-    const responses = [];
-    for (const order of orders) {
-        const { id, payload } = order;
-        // payload contains { type: "fetch", url: "..." }
-
-        // Simulate async operation with setTimeout
-        await new Promise(r => setTimeout(r, 100));
-
-        // Mock response based on payload
-        const result = { data: "mock" };
-        responses.push({ id, result });
+// Handle orders by returning unresolved Promises immediately.
+// This enables parallel async operations - each order gets a Promise that
+// resolves after async work, but execution continues immediately.
+function handleOrders(orderIds) {
+    for (const orderId of orderIds) {
+        const payload = runner.get_order_payload(orderId);
+
+        // Create unresolved Promise and fulfill order immediately
+        const promiseHandle = runner.create_promise();
+        runner.set_order_result(orderId, promiseHandle);
+
+        // Schedule resolution based on order type (runs concurrently!)
+        if (payload.type === "fetch") {
+            fetch(payload.url)
+                .then(r => r.json())
+                .then(data => runner.resolve_promise(promiseHandle, toHandle(data)));
+        } else if (payload.type === "timeout") {
+            setTimeout(() => runner.resolve_promise(promiseHandle, undefined), payload.ms);
+        } else {
+            runner.reject_promise(promiseHandle, `Unknown type: ${payload.type}`);
+        }
     }
-    return responses;
+    // Return immediately - don't wait for async operations
 }
 ```
 

README.md

@@ -219,17 +219,17 @@ assert_eq!(joined.as_str(), Some("admin, developer"));
 
 ### Async/Await with Orders
 
-For async operations, the interpreter pauses with pending "orders" that the host fulfills:
+For async operations, the interpreter pauses with pending "orders" that the host fulfills. The host examines the order payload to determine what operation to perform:
 
 ```rust
-use tsrun::{Interpreter, StepResult, OrderResponse, RuntimeValue, api};
+use tsrun::{Interpreter, StepResult, OrderResponse, RuntimeValue, JsError, api};
 
 let mut interp = Interpreter::new();
 
 // Code that uses the order system for async I/O
 interp.prepare(r#"
     import { order } from "tsrun:host";
-    const response = await order({ url: "/api/users" });
+    const response = await order({ type: "fetch", url: "/api/users" });
     response.data
 "#, Some("/main.ts".into()))?;
 
@@ -239,14 +239,33 @@ loop {
         StepResult::Suspended { pending, cancelled } => {
             let mut responses = Vec::new();
             for order in pending {
-                // Examine order.payload to determine what to do
-                // Create response value
-                let response = api::create_response_object(&mut interp, &serde_json::json!({
-                    "data": [{"id": 1, "name": "Alice"}]
-                }))?;
+                // Extract order type from payload to dispatch
+                let order_type = api::get_property(order.payload.value(), "type")
+                    .ok()
+                    .and_then(|v| v.as_str().map(String::from));
+
+                let result = match order_type.as_deref() {
+                    Some("fetch") => {
+                        let url = api::get_property(order.payload.value(), "url")
+                            .ok()
+                            .and_then(|v| v.as_str().map(String::from))
+                            .unwrap_or_default();
+                        // In real code: perform actual HTTP fetch here
+                        api::create_response_object(&mut interp, &serde_json::json!({
+                            "data": [{"id": 1, "name": "Alice"}],
+                            "url": url
+                        }))
+                    }
+                    Some("timeout") => {
+                        // In real code: sleep for the requested duration
+                        Ok(RuntimeValue::unguarded(tsrun::JsValue::Undefined))
+                    }
+                    _ => Err(JsError::type_error("Unknown order type")),
+                };
+
                 responses.push(OrderResponse {
                     id: order.id,
-                    result: Ok(response),
+                    result,
                 });
             }
             interp.fulfill_orders(responses);
@@ -381,15 +400,32 @@ const [user, posts] = await Promise.all([
 ```javascript
 // In the step loop, handle STEP_SUSPENDED status:
 if (result.status === STEP_SUSPENDED()) {
-    const orders = runner.get_pending_orders();
-    // orders = [{ id: 1, payload: { type: "fetch", url: "/api/users/1" } }, ...]
-
-    const responses = await Promise.all(orders.map(async order => {
-        const data = await realFetch(order.payload.url);
-        return { id: order.id, result: data };
-    }));
-
-    runner.fulfill_orders(responses);
+    const orderIds = runner.get_pending_order_ids();
+
+    for (const orderId of orderIds) {
+        // Read payload now (before fulfilling)
+        const payload = runner.get_order_payload(orderId);
+
+        // Create an unresolved Promise - enables concurrent execution
+        const promiseHandle = runner.create_promise();
+
+        // Fulfill the order immediately with this Promise
+        runner.set_order_result(orderId, promiseHandle);
+
+        // Schedule async work based on order type - all run concurrently!
+        if (payload.type === "fetch") {
+            fetch(payload.url)
+                .then(r => r.json())
+                .then(data => runner.resolve_promise(promiseHandle, toHandle(data)));
+        } else if (payload.type === "timeout") {
+            setTimeout(() => {
+                runner.resolve_promise(promiseHandle, runner.create_undefined());
+            }, payload.ms);
+        } else {
+            runner.reject_promise(promiseHandle, `Unknown order type: ${payload.type}`);
+        }
+    }
+    runner.commit_fulfillments();
 }
 ```
 

tests/interpreter/orders.rs

@@ -2193,3 +2193,148 @@ fn test_three_way_race_cancels_two_losers() {
         cancelled
     );
 }
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Documentation Example Pattern Tests
+// These tests demonstrate the patterns shown in README.md and CLAUDE.md:
+// - Multiple order types with type-based dispatch
+// - Returning unresolved Promises for concurrent execution
+// - Error handling for unknown order types
+// ═══════════════════════════════════════════════════════════════════════════════
+
+#[test]
+fn test_concurrent_mixed_order_types() {
+    // Demonstrates the pattern from documentation examples:
+    // 1. Multiple order types (fetch, timeout)
+    // 2. Host checks payload.type to dispatch
+    // 3. Returns unresolved Promises for concurrent execution
+    let mut interp = create_test_interp();
+
+    // Create Promises upfront for concurrent resolution
+    let fetch_promise = api::create_promise(&mut interp);
+    let timeout_promise = api::create_promise(&mut interp);
+
+    let result = run_with_globals(
+        &mut interp,
+        r#"
+        import { order } from "tsrun:host";
+
+        // Issue two orders with different types
+        const fetchPromise = order({ type: "fetch", url: "/api/users" });
+        const timeoutPromise = order({ type: "timeout", ms: 100 });
+
+        // Wait for both concurrently
+        const [data, _] = await Promise.all([fetchPromise, timeoutPromise]);
+        data.name;
+    "#,
+    );
+
+    // First order: fetch
+    let StepResult::Suspended { pending, .. } = result else {
+        panic!("Expected Suspended for fetch order");
+    };
+    assert_eq!(pending.len(), 1);
+
+    // Host checks type to dispatch
+    let payload = pending[0].payload.value();
+    let order_type = get_string_prop(payload, "type");
+    assert_eq!(order_type, Some("fetch".into()));
+
+    // Return unresolved Promise immediately
+    interp.fulfill_orders(vec![OrderResponse {
+        id: pending[0].id,
+        result: Ok(RuntimeValue::unguarded(fetch_promise.value().clone())),
+    }]);
+    let result = run_to_completion(&mut interp).unwrap();
+
+    // Second order: timeout
+    let StepResult::Suspended { pending, .. } = result else {
+        panic!("Expected Suspended for timeout order");
+    };
+    assert_eq!(pending.len(), 1);
+
+    // Host checks type to dispatch
+    let payload = pending[0].payload.value();
+    let order_type = get_string_prop(payload, "type");
+    assert_eq!(order_type, Some("timeout".into()));
+    let ms = get_number_prop(payload, "ms");
+    assert_eq!(ms, Some(100.0));
+
+    // Return unresolved Promise immediately
+    interp.fulfill_orders(vec![OrderResponse {
+        id: pending[0].id,
+        result: Ok(RuntimeValue::unguarded(timeout_promise.value().clone())),
+    }]);
+    let result = run_to_completion(&mut interp).unwrap();
+
+    // Now awaiting Promise.all - host can resolve concurrently
+    let StepResult::Suspended { pending, .. } = result else {
+        panic!("Expected Suspended for Promise.all");
+    };
+    assert!(pending.is_empty());
+
+    // Simulate concurrent resolution (timeout resolves first, then fetch)
+    api::resolve_promise(
+        &mut interp,
+        &timeout_promise,
+        RuntimeValue::unguarded(JsValue::Undefined),
+    )
+    .unwrap();
+
+    let fetch_data = api::create_response_object(&mut interp, &json!({ "name": "Alice" })).unwrap();
+    api::resolve_promise(&mut interp, &fetch_promise, fetch_data).unwrap();
+
+    let result = run_to_completion(&mut interp).unwrap();
+
+    let StepResult::Complete(value) = result else {
+        panic!("Expected Complete");
+    };
+    assert_eq!(*value, JsValue::String("Alice".into()));
+}
+
+#[test]
+fn test_unknown_order_type_rejection() {
+    // Test that unknown order types can be rejected by the host
+    let mut interp = create_test_interp();
+
+    let result = run_with_globals(
+        &mut interp,
+        r#"
+        import { order } from "tsrun:host";
+
+        try {
+            const result = await order({ type: "unknown_type" });
+            "success: " + result;
+        } catch (e) {
+            "error: " + e;
+        }
+    "#,
+    );
+
+    let StepResult::Suspended { pending, .. } = result else {
+        panic!("Expected Suspended");
+    };
+
+    // Host checks type - unknown type, return error
+    let order_type = get_string_prop(pending[0].payload.value(), "type");
+    assert_eq!(order_type, Some("unknown_type".into()));
+
+    // Reject with error for unknown type
+    interp.fulfill_orders(vec![OrderResponse {
+        id: pending[0].id,
+        result: Err(tsrun::JsError::type_error(
+            "Unknown order type: unknown_type",
+        )),
+    }]);
+    let result = run_to_completion(&mut interp).unwrap();
+
+    let StepResult::Complete(value) = result else {
+        panic!("Expected Complete with error");
+    };
+    let result_str = value.as_str().expect("Expected string result");
+    assert!(
+        result_str.contains("Unknown order type"),
+        "Expected error message, got: {}",
+        result_str
+    );
+}