test: add comprehensive tests for map step compilation, type constraints, and edge cases

- Introduced new integration tests for flow compilation involving map steps
- Added runtime validation tests for step dependencies and slug validation
- Included type inference validation tests for map method constraints
- Covered edge cases such as empty arrays and various runtime options
- Added tests for flow with only map steps and multiple independent chains
- Ensured correct parameter ordering and handling of dependencies in compiled SQL
- Expanded coverage for root and dependent map compilation scenarios
- Included tests for flow with only map steps and chaining behaviors
- Improved test suite robustness for map step handling in flow compilation

Author: jumski

.changeset/easy-bats-nail.md

@@ -0,0 +1,26 @@
+---
+'@pgflow/example-flows': patch
+'@pgflow/dsl': patch
+---
+
+Add `.map()` method to Flow DSL for defining map-type steps
+
+The new `.map()` method enables defining steps that process arrays element-by-element, complementing the existing SQL Core map infrastructure. Key features:
+
+- **Root maps**: Process flow input arrays directly by omitting the `array` property
+- **Dependent maps**: Process another step's array output using `array: 'stepSlug'`
+- **Type-safe**: Enforces Json-compatible types with full TypeScript inference
+- **Different handler signature**: Receives individual items `(item, context)` instead of full input object
+- **Always returns arrays**: Return type is `HandlerReturnType[]`
+- **SQL generation**: Correctly adds `step_type => 'map'` parameter to `pgflow.add_step()`
+
+Example usage:
+```typescript
+// Root map - processes array input
+new Flow<string[]>({ slug: 'process' })
+  .map({ slug: 'uppercase' }, (item) => item.toUpperCase())
+
+// Dependent map - processes another step's output
+new Flow<{}>({ slug: 'workflow' })
+  .array({ slug: 'items' }, () => [1, 2, 3])
+  .map({ slug: 'double', array: 'items' }, (n) => n * 2)

.claude/settings.json

@@ -23,6 +23,8 @@
       "Bash(grep:*)",
       "Bash(ls:*)",
       "Bash(mkdir:*)",
+      "Bash(npx tsc:*)",
+      "Bash(pnpm tsc:*)",
       "Bash(pnpm eslint:*)",
       "Bash(pnpm nx build:*)",
       "Bash(pnpm nx lint:*)",

PLAN.md

@@ -9,14 +9,17 @@
 - ✅ **DONE**: Dependency count propagation for map steps
 - ✅ **DONE**: Array element extraction - tasks receive individual array elements
 - ✅ **DONE**: Output aggregation - inline implementation aggregates map task outputs for dependents
-- ⏳ **NEXT**: DSL support for `.map()` for defining map steps
+- ✅ **DONE**: DSL support for `.map()` for defining map steps
+- ⏳ **TODO**: Fix orphaned messages on run failure
+- ⏳ **TODO**: Performance optimization with step_states.output column
 
 ### Chores
 
-- ⏳ **WAITING**: Integration tests for map steps
-- ⏳ **WAITING**: Consolidated migration for map steps
-- ⏳ **WAITING**: Documentation for map steps
-- ⏳ **WAITING**: Graphite stack merge for map steps
+- ⏳ **TODO**: Integration tests for map steps
+- ⏳ **TODO**: Update core README
+- ⏳ **TODO**: Add docs page for array and map steps
+- ⏳ **TODO**: Migration consolidation
+- ⏳ **TODO**: Graphite stack merge
 
 ## Implementation Status
 
@@ -83,22 +86,24 @@
   - Validates non-array outputs to map steps fail correctly
   - Fixed broadcast aggregation to send full array not individual task output
 
-#### ❌ Remaining Work
-
-- [ ] **DSL Support for .map() Step Type**
+- [x] **PR #218: DSL Support for .map() Step Type** - `09-18-add-map-support-to-dsl` (THIS PR)
 
-  - Add `.map()` method to Flow DSL for defining map steps
+  - Added `.map()` method to Flow DSL for defining map steps
   - Constraints:
     - Locked to exactly one dependency (enforced at compile time)
     - Dependency must return an array (type-checked)
   - Syntax design:
     - Dependent maps: `flow.map({ slug: 'stepName', array: 'arrayReturningStep' }, handler)`
-    - Root maps: Decide between `{ array: 'run' }` or omitting array property
+    - Root maps: Omit array property
   - Return type always inferred as array
   - Comprehensive tests:
     - Runtime validation of array dependencies
     - Type safety for input/output types
     - Compile-time enforcement of single dependency rule
+  - Fixed complex TypeScript type inference issue with overloads
+  - Updated DSL README with .map() documentation
+
+#### ❌ Remaining Work
 
 - [ ] **Fix Orphaned Messages on Run Failure**
 
@@ -130,14 +135,7 @@
   - Basic happy path coverage
   - This should be minimal and added to the Edge Worker integration test suite for now
 
-- [ ] **Migration Consolidation**
-
-  - Remove all temporary/incremental migrations from feature branches
-  - Generate a single consolidated migration for the entire map infrastructure
-  - Ensure clean migration path from current production schema
-  - If NULL improvement is done, include it in the consolidated migration
-
-- [ ] **Update README's** and **Docs**
+- [ ] **Update core README**
 
   - `pkgs/core/README.md`
 
@@ -149,12 +147,7 @@
     - Explain root map vs dependent map and how it gets handled and what restrictions those apply on the Flow input
     - Explain cascade completion of taskless steps and its limitations
 
-  - `pkgs/dsl/README.md`
-
-    - Briefly describe the new `.array()` and `.map()` methods
-    - Mention `.array` is mostly sugar, and `.map` is the new step type
-    - Link to `pkgs/core/README.md` sections for more explanation about map steps
-    - Make sure to mention that maps are constrained to have exactly one dependency
+- [ ] **Add docs page**
 
   - **Add basic docs page**
 
@@ -165,6 +158,13 @@
     - focus mostly on how to use it, instead of how it works under the hood
     - link to the README's for more details
 
+- [ ] **Migration Consolidation**
+
+  - Remove all temporary/incremental migrations from feature branches
+  - Generate a single consolidated migration for the entire map infrastructure
+  - Ensure clean migration path from current production schema
+  - If NULL improvement is done, include it in the consolidated migration
+
 - [ ] **Graphite Stack Merge**
 
   - Configure Graphite merge queue for the complete PR stack

pkgs/dsl/README.md

@@ -73,6 +73,78 @@ This design ensures:
 - Data doesn't need to be manually forwarded through intermediate steps
 - Steps can combine original input with processed data from previous steps
 
+### Step Methods
+
+The Flow DSL provides three methods for defining steps in your workflow:
+
+#### `.step()` - Regular Steps
+
+The standard method for adding steps to a flow. Each step processes input and returns output.
+
+```typescript
+.step(
+  { slug: 'process', dependsOn: ['previous'] },
+  async (input) => {
+    // Access input.run and input.previous
+    return { result: 'processed' };
+  }
+)
+```
+
+#### `.array()` - Array-Returning Steps
+
+A semantic wrapper around `.step()` that provides type enforcement for steps that return arrays. Useful for data fetching or collection steps.
+
+```typescript
+.array(
+  { slug: 'fetch_items' },
+  async () => [1, 2, 3, 4, 5]
+)
+```
+
+#### `.map()` - Array Processing Steps
+
+Processes arrays element-by-element, similar to JavaScript's `Array.map()`. The handler receives individual items instead of the full input object.
+
+```typescript
+// Root map - processes flow input array
+new Flow<string[]>({ slug: 'process_strings' })
+  .map({ slug: 'uppercase' }, (item) => item.toUpperCase());
+
+// Dependent map - processes another step's output
+new Flow<{}>({ slug: 'data_pipeline' })
+  .array({ slug: 'numbers' }, () => [1, 2, 3])
+  .map({ slug: 'double', array: 'numbers' }, (n) => n * 2)
+  .map({ slug: 'square', array: 'double' }, (n) => n * n);
+```
+
+**Key differences from regular steps:**
+- Uses `array:` instead of `dependsOn:` for specifying the single array dependency
+- Handler signature is `(item, context) => result` instead of `(input, context) => result`
+- Return type is always an array
+- Generates SQL with `step_type => 'map'` parameter for pgflow's map processing
+
+**Type Safety:**
+The `.map()` method provides full TypeScript type inference for array elements:
+
+```typescript
+type User = { id: number; name: string };
+
+new Flow<{}>({ slug: 'user_flow' })
+  .array({ slug: 'users' }, (): User[] => [
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+  ])
+  .map({ slug: 'greet', array: 'users' }, (user) => {
+    // TypeScript knows user is of type User
+    return `Hello, ${user.name} (ID: ${user.id})`;
+  });
+```
+
+**Limitations:**
+- Can only depend on a single array-returning step
+- TypeScript may not track type transformations between chained maps (use type assertions if needed)
+
 ### Context Object
 
 Step handlers can optionally receive a second parameter - the **context object** - which provides access to platform resources and runtime information.
@@ -114,6 +186,11 @@ All platforms provide these core resources:
     msg_id: number;
   }
   ```
+- **`context.workerConfig`** - Resolved worker configuration with all defaults applied
+  ```typescript
+  // Provides access to worker settings like retry limits
+  const isLastAttempt = context.rawMessage.read_ct >= context.workerConfig.retry.limit;
+  ```
 
 #### Supabase Platform Resources