- Fix bug where Promise.all would wipe out previous variables

- Add retry for map - Steps.map
- Add shared task options
- Doc fixes

Author: DevNamedZed

README.md

@@ -11,7 +11,7 @@ TypeScript-to-ASL compiler for AWS Step Functions. Define workflows as typed asy
 
 At my previous company we had dozens of Step Functions deployed with CDK. They were incredibly hard to read and maintain. The CDK approach defines a program by stringing together a tree of construct objects — `.next().next().next()` chains with raw JSONPath and `sfn.CustomState` workarounds. That's exactly the kind of work a compiler should handle.
 
-SimpleSteps compiles typed async functions to ASL state machines. The compiler performs whole-program data flow analysis and derives all JSONPath expressions (`Parameters`, `ResultPath`, `InputPath`, `ResultSelector`, `OutputPath`) from variable usage. Service bindings are resolved at compile time, with CDK token substitution at synth time.
+SimpleSteps compiles typed async functions to ASL state machines. The compiler performs whole-program data flow analysis and derives all JSONPath expressions (`Parameters`, `ResultPath`, `InputPath`, `ResultSelector`) from variable usage. Service bindings are resolved at compile time, with CDK token substitution at synth time.
 
 **Input:**
 
@@ -135,8 +135,9 @@ npx simplesteps compile workflow.ts -o output/
 | `const x = { ... }` | Pass state |
 | `if/else`, `switch/case` | Choice state |
 | `while`, `do...while` | Choice + back-edge loop |
-| `for (const item of array)` | Map state (parallel) |
+| `for (const item of array)` | Map state (parallel, with closures) |
 | `await Steps.map(items, cb, opts?)` | Map state (results, closures, MaxConcurrency) |
+| `for (const item of Steps.items(arr, opts?))` | Map state (for...of + MaxConcurrency) |
 | `await Promise.all([...])` | Parallel state |
 | Deferred-await (`const p = call(); await p`) | Parallel state (auto-batched) |
 | `await Steps.delay({ seconds: 30 })` | Wait state |

docs/language-reference.md

@@ -10,8 +10,9 @@ Every TypeScript construct supported by SimpleSteps and its ASL mapping.
 | `const x = { ... }` | Pass |
 | `if/else`, `switch/case` | Choice |
 | `while`, `do...while` | Choice + back-edge loop |
-| `for (const item of array)` | Map (parallel) |
+| `for (const item of array)` | Map (parallel, with closures) |
 | `await Steps.map(items, callback, opts?)` | Map (with result capture, closures, MaxConcurrency) |
+| `for (const item of Steps.items(array, opts?))` | Map (for...of with MaxConcurrency + closures) |
 | `for (const item of Steps.sequential(array))` | Map (sequential, `MaxConcurrency: 1`) |
 | `await Promise.all([...])` | Parallel |
 | Deferred-await (`const p = call(); await p`) | Parallel (auto-batched) |
@@ -110,10 +111,21 @@ for (const item of input.items) {
   await processor.call(item);
 }
 
+// Closures work in all iteration styles
+const config = await getConfig.call({ env: input.env });
+for (const item of input.items) {
+  await processor.call({ item, prefix: config.prefix }); // config captured via ItemSelector
+}
+
 // Sequential iteration
 for (const step of Steps.sequential(input.steps)) {
   await executor.call(step);
 }
+
+// For-of with concurrency control
+for (const item of Steps.items(input.items, { maxConcurrency: 5 })) {
+  await processor.call({ item });
+}
 ```
 
 ### Steps.map()
@@ -145,7 +157,21 @@ await Steps.map(input.items, async (item) => {
 });
 ```
 
-Unlike `for...of`, `Steps.map()` supports closures over prior `await` results and can capture iteration results into a variable.
+All iteration styles (`for...of`, `Steps.map()`, `Steps.items()`, `Steps.sequential()`) support closures over prior `await` results. `Steps.map()` additionally captures iteration results into a variable.
+
+### Steps.items()
+
+`Steps.items()` wraps an array for use with `for...of`, adding MaxConcurrency control:
+
+```typescript
+// for...of with concurrency limit + closures
+const config = await getConfig.call({ env: input.env });
+for (const item of Steps.items(input.items, { maxConcurrency: 5 })) {
+  await processItem.call({ item, prefix: config.prefix });
+}
+```
+
+Use `Steps.items()` when you prefer imperative `for...of` syntax but need concurrency control. Use `Steps.map()` when you need to collect iteration results.
 
 ### Parallel Execution
 
@@ -241,7 +267,7 @@ One of SimpleSteps' key design goals: **you never write JSONPath or data flow fi
 | `ResultPath` | Variable assignment — `const x = await svc.call(...)` stores the result at `$.x` |
 | `InputPath` | Variable references in service call arguments — the compiler determines what data the state needs |
 | `ResultSelector` | Automatic `.Payload` extraction for Lambda results (so you access `result.field`, not `result.Payload.field`) |
-| `OutputPath` | Variable liveness analysis — the compiler prunes fields that are no longer needed downstream |
+| `OutputPath` | *Not yet implemented* — planned optimization for payload size reduction via variable liveness analysis |
 
 In CDK, you'd write `sfn.JsonPath.stringAt('$.order.total')` and manually set `outputPath: '$.Payload'`. In SimpleSteps, you write `order.total` and the compiler handles the rest.
 

docs/limitations.md

@@ -115,33 +115,28 @@ Workaround for rest parameters: pass an explicit array parameter instead.
 
 ## Closures and Variable Capture
 
-Map state iterations have isolated state — each iteration receives only its array element as input.
+Map state iterations have isolated state — each iteration receives only its array element as input. The compiler automatically detects outer-scope variables referenced inside a loop body and projects them into each iteration via ASL's `ItemSelector`.
 
-**`Steps.map()` supports closures** — prior `await` results are automatically projected into each iteration via ASL's `ItemSelector`:
+**All iteration styles support closures** — `for...of`, `Steps.map()`, `Steps.items()`, and `Steps.sequential()` all capture outer `await` results automatically:
 
 ```typescript
 const config = await getConfig.call({ env: input.env });
 
-// OK — Steps.map() captures `config` via ItemSelector
+// All of these capture `config` via ItemSelector:
+for (const item of input.items) {
+  await processor.call({ key: config.prefix, item });
+}
+
 await Steps.map(input.items, async (item) => {
   await processor.call({ key: config.prefix, item });
 });
-```
-
-**`for...of` loops do NOT support closures** — each iteration cannot reference runtime variables from the outer scope:
 
-```typescript
-const config = await getConfig.call({ env: input.env });
-
-// NOT OK — for...of Map state can't access `config`
-for (const item of input.items) {
-  await processor.call({ key: config.prefix, item }); // SS502
+for (const item of Steps.items(input.items, { maxConcurrency: 5 })) {
+  await processor.call({ key: config.prefix, item });
 }
 ```
 
-Compile-time constants and service bindings are accessible in all Map iterations. Only runtime variables (service call results) are restricted in `for...of`.
-
-Workaround for `for...of`: Use `Steps.map()` instead (which supports closures), use `Steps.sequential()` for sequential iteration, or restructure the data so each item carries what it needs.
+Compile-time constants and service bindings are also accessible in all Map iterations.
 
 ## Array Methods
 

packages/core/src/compiler/cfg/cfgBuilder.ts

@@ -747,16 +747,43 @@ function processForOfStatement(
     }
   }
 
+  // Detect Steps.sequential() / Steps.items() wrappers and unwrap to the real items expression
+  let itemsExpression: ts.Expression = stmt.expression;
+  let maxConcurrency: number | undefined;
+  let retryExpression: ts.Expression | undefined;
+
+  if (ts.isCallExpression(stmt.expression)) {
+    if (isStepsCall(stmt.expression, 'sequential')) {
+      itemsExpression = stmt.expression.arguments[0];
+      maxConcurrency = 1;
+    } else if (isStepsCall(stmt.expression, 'items')) {
+      itemsExpression = stmt.expression.arguments[0];
+      const optionsArg = stmt.expression.arguments[1];
+      if (optionsArg && ts.isObjectLiteralExpression(optionsArg)) {
+        for (const prop of optionsArg.properties) {
+          if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
+          if (prop.name.text === 'maxConcurrency' && ts.isNumericLiteral(prop.initializer)) {
+            maxConcurrency = Number(prop.initializer.text);
+          } else if (prop.name.text === 'retry') {
+            retryExpression = prop.initializer;
+          }
+        }
+      }
+    }
+  }
+
   // Finalize current block with mapState terminator
   state.addBlock(currentBlockId, accumulated, {
     kind: 'mapState',
     expression: stmt,
-    itemsExpression: stmt.expression,
+    itemsExpression,
     iterVarName,
     iterVarSymbol,
     bodyBlock: bodyBlockId,
     exitBlock: exitBlockId,
     collectResults,
+    ...(maxConcurrency != null && { maxConcurrency }),
+    ...(retryExpression && { retryExpression }),
   });
 
   // Process body — break/continue targets loop exit/body start
@@ -1404,13 +1431,16 @@ function tryExtractStepsMap(
     return undefined;
   }
 
-  // Extract maxConcurrency from options
+  // Extract maxConcurrency and retry from options
   let maxConcurrency: number | undefined;
+  let retryExpression: ts.Expression | undefined;
   if (optionsArg && ts.isObjectLiteralExpression(optionsArg)) {
     for (const prop of optionsArg.properties) {
-      if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) &&
-          prop.name.text === 'maxConcurrency' && ts.isNumericLiteral(prop.initializer)) {
+      if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
+      if (prop.name.text === 'maxConcurrency' && ts.isNumericLiteral(prop.initializer)) {
         maxConcurrency = Number(prop.initializer.text);
+      } else if (prop.name.text === 'retry') {
+        retryExpression = prop.initializer;
       }
     }
   }
@@ -1438,6 +1468,7 @@ function tryExtractStepsMap(
     maxConcurrency,
     ...(resultBindingName && { resultBindingName }),
     ...(resultSymbol && { resultSymbol }),
+    ...(retryExpression && { retryExpression }),
   });
 
   // Process the callback body
@@ -1466,6 +1497,15 @@ function isStepsMapCall(call: ts.CallExpression): boolean {
          prop.name.text === 'map';
 }
 
+/** Check if an expression is a call to Steps.<method>() */
+function isStepsCall(expr: ts.Expression, method: string): boolean {
+  if (!ts.isCallExpression(expr)) return false;
+  if (!ts.isPropertyAccessExpression(expr.expression)) return false;
+  const prop = expr.expression;
+  return ts.isIdentifier(prop.expression) && prop.expression.text === 'Steps' &&
+         prop.name.text === method;
+}
+
 // ---------------------------------------------------------------------------
 // Parallel branch classification
 // ---------------------------------------------------------------------------

packages/core/src/compiler/cfg/types.ts

@@ -61,6 +61,8 @@ export interface MapStateTerminator {
   readonly resultBindingName?: string;
   /** Symbol of the result variable for registration in the variable resolver. */
   readonly resultSymbol?: ts.Symbol;
+  /** Retry policy extracted from options (for Steps.map/items). */
+  readonly retryExpression?: ts.Expression;
 }
 
 export interface ReturnTerminator {