@pgflow/dsl 0.6.1 → 0.7.0

package/README.md

@@ -73,6 +73,144 @@ 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 that will be processed by map steps.
+
+```typescript
+// Fetch an array of items to be processed
+.array(
+  { slug: 'fetch_items' },
+  async () => [1, 2, 3, 4, 5]
+)
+
+// With dependencies - combining data from multiple sources
+.array(
+  { slug: 'combine_results', dependsOn: ['source1', 'source2'] },
+  async (input) => [...input.source1, ...input.source2]
+)
+```
+
+**Key Points:**
+- Return type is enforced to be an array at compile time
+- Commonly used as input for subsequent map steps
+- Can depend on other steps just like regular steps
+
+#### `.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.
+
+**Two Modes of Operation:**
+
+1. **Root Map** (no `array:` property): Processes the flow's input array directly
+   - The flow input MUST be an array when using root maps
+   - Omitting the `array:` property tells pgflow to use the flow input
+
+2. **Dependent Map** (with `array:` property): Processes another step's array output
+   - The `array:` property specifies which step's output to process
+   - That step must return an array
+
+```typescript
+// ROOT MAP - No array: property means use flow input
+// Flow input MUST be an array (e.g., ["hello", "world"])
+new Flow<string[]>({ slug: 'process_strings' })
+  .map(
+    { slug: 'uppercase' }, // No array: property!
+    (item) => item.toUpperCase()
+  );
+// Each string in the input array gets uppercased in parallel
+
+// DEPENDENT MAP - array: property specifies the source step
+new Flow<{}>({ slug: 'data_pipeline' })
+  .array({ slug: 'numbers' }, () => [1, 2, 3])
+  .map(
+    { slug: 'double', array: 'numbers' }, // Processes 'numbers' output
+    (n) => n * 2
+  )
+  .map(
+    { slug: 'square', array: 'double' }, // Chains from 'double'
+    (n) => n * n
+  );
+// Results: numbers: [1,2,3] → double: [2,4,6] → square: [4,16,36]
+```
+
+**Key differences from regular steps:**
+- Uses `array:` to specify dependency (not `dependsOn:`)
+- When `array:` is omitted, uses flow input array (root map)
+- Handler signature is `(item, context) => result` instead of `(input, context) => result`
+- Return type is always an array
+- Map steps can have at most one dependency (the array source)
+- 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})`;
+  });
+```
+
+**Common Patterns:**
+
+```typescript
+// Batch processing - process multiple items in parallel
+new Flow<number[]>({ slug: 'batch_processor' })
+  .map({ slug: 'validate' }, (item) => {
+    if (item < 0) throw new Error('Invalid item');
+    return item;
+  })
+  .map({ slug: 'process', array: 'validate' }, async (item) => {
+    // Each item processed in its own task
+    return await expensiveOperation(item);
+  });
+
+// Data transformation pipeline
+new Flow<{}>({ slug: 'etl_pipeline' })
+  .step({ slug: 'fetch_urls' }, () => ['url1', 'url2', 'url3'])
+  .map({ slug: 'scrape', array: 'fetch_urls' }, async (url) => {
+    return await fetchContent(url);
+  })
+  .map({ slug: 'extract', array: 'scrape' }, (html) => {
+    return extractData(html);
+  })
+  .step({ slug: 'aggregate', dependsOn: ['extract'] }, (input) => {
+    // input.extract is the aggregated array from all map tasks
+    return consolidateResults(input.extract);
+  });
+```
+
+**Limitations:**
+- Can only depend on a single array-returning step
+- TypeScript may not track type transformations between chained maps (use type assertions if needed)
+- Root maps require the entire flow input to be an array
+
 ### Context Object
 
 Step handlers can optionally receive a second parameter - the **context object** - which provides access to platform resources and runtime information.
@@ -114,6 +252,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
 

package/dist/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @pgflow/dsl
 
+## 0.7.0
+
+### Minor Changes
+
+- 524db03: Add `.array()` method for type-safe array step creation
+
+  Introduces a new `.array()` method that provides compile-time type safety for array-returning handlers with zero runtime overhead.
+
+  - Enforces array return types at compile time
+  - Pure delegation to existing `.step()` method
+  - Full support for dependencies and runtime options
+  - Backward compatible
+
+  ```typescript
+  flow.array({ slug: 'items' }, () => [1, 2, 3]); // ✅ Valid
+  flow.array({ slug: 'invalid' }, () => 42); // ❌ Compile error
+  ```
+
+- 524db03: 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
+  - **Compile-time duplicate slug detection**: TypeScript now prevents duplicate step slugs at compile-time
+  - **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);
+  ```
+
 ## 0.6.1
 
 ## 0.6.0

package/dist/README.md

@@ -73,6 +73,144 @@ 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 that will be processed by map steps.
+
+```typescript
+// Fetch an array of items to be processed
+.array(
+  { slug: 'fetch_items' },
+  async () => [1, 2, 3, 4, 5]
+)
+
+// With dependencies - combining data from multiple sources
+.array(
+  { slug: 'combine_results', dependsOn: ['source1', 'source2'] },
+  async (input) => [...input.source1, ...input.source2]
+)
+```
+
+**Key Points:**
+- Return type is enforced to be an array at compile time
+- Commonly used as input for subsequent map steps
+- Can depend on other steps just like regular steps
+
+#### `.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.
+
+**Two Modes of Operation:**
+
+1. **Root Map** (no `array:` property): Processes the flow's input array directly
+   - The flow input MUST be an array when using root maps
+   - Omitting the `array:` property tells pgflow to use the flow input
+
+2. **Dependent Map** (with `array:` property): Processes another step's array output
+   - The `array:` property specifies which step's output to process
+   - That step must return an array
+
+```typescript
+// ROOT MAP - No array: property means use flow input
+// Flow input MUST be an array (e.g., ["hello", "world"])
+new Flow<string[]>({ slug: 'process_strings' })
+  .map(
+    { slug: 'uppercase' }, // No array: property!
+    (item) => item.toUpperCase()
+  );
+// Each string in the input array gets uppercased in parallel
+
+// DEPENDENT MAP - array: property specifies the source step
+new Flow<{}>({ slug: 'data_pipeline' })
+  .array({ slug: 'numbers' }, () => [1, 2, 3])
+  .map(
+    { slug: 'double', array: 'numbers' }, // Processes 'numbers' output
+    (n) => n * 2
+  )
+  .map(
+    { slug: 'square', array: 'double' }, // Chains from 'double'
+    (n) => n * n
+  );
+// Results: numbers: [1,2,3] → double: [2,4,6] → square: [4,16,36]
+```
+
+**Key differences from regular steps:**
+- Uses `array:` to specify dependency (not `dependsOn:`)
+- When `array:` is omitted, uses flow input array (root map)
+- Handler signature is `(item, context) => result` instead of `(input, context) => result`
+- Return type is always an array
+- Map steps can have at most one dependency (the array source)
+- 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})`;
+  });
+```
+
+**Common Patterns:**
+
+```typescript
+// Batch processing - process multiple items in parallel
+new Flow<number[]>({ slug: 'batch_processor' })
+  .map({ slug: 'validate' }, (item) => {
+    if (item < 0) throw new Error('Invalid item');
+    return item;
+  })
+  .map({ slug: 'process', array: 'validate' }, async (item) => {
+    // Each item processed in its own task
+    return await expensiveOperation(item);
+  });
+
+// Data transformation pipeline
+new Flow<{}>({ slug: 'etl_pipeline' })
+  .step({ slug: 'fetch_urls' }, () => ['url1', 'url2', 'url3'])
+  .map({ slug: 'scrape', array: 'fetch_urls' }, async (url) => {
+    return await fetchContent(url);
+  })
+  .map({ slug: 'extract', array: 'scrape' }, (html) => {
+    return extractData(html);
+  })
+  .step({ slug: 'aggregate', dependsOn: ['extract'] }, (input) => {
+    // input.extract is the aggregated array from all map tasks
+    return consolidateResults(input.extract);
+  });
+```
+
+**Limitations:**
+- Can only depend on a single array-returning step
+- TypeScript may not track type transformations between chained maps (use type assertions if needed)
+- Root maps require the entire flow input to be an array
+
 ### Context Object
 
 Step handlers can optionally receive a second parameter - the **context object** - which provides access to platform resources and runtime information.
@@ -114,6 +252,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
 

package/dist/compile-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-flow.d.ts","sourceRoot":"","sources":["../src/compile-flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAsC,MAAM,UAAU,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAyBnD"}
+{"version":3,"file":"compile-flow.d.ts","sourceRoot":"","sources":["../src/compile-flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAsC,MAAM,UAAU,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CA+BnD"}

package/dist/compile-flow.js

@@ -20,7 +20,12 @@ export function compileFlow(flow) {
             const depsArray = step.dependencies.map((dep) => `'${dep}'`).join(', ');
             depsClause = `, ARRAY[${depsArray}]`;
         }
-        statements.push(`SELECT pgflow.add_step('${flow.slug}', '${step.slug}'${depsClause}${stepOptions});`);
+        // Add step_type parameter for map steps
+        let stepTypeClause = '';
+        if (step.stepType === 'map') {
+            stepTypeClause = `, step_type => 'map'`;
+        }
+        statements.push(`SELECT pgflow.add_step('${flow.slug}', '${step.slug}'${depsClause}${stepOptions}${stepTypeClause});`);
     }
     return statements;
 }

package/dist/dsl.d.ts

@@ -1,5 +1,5 @@
 export type Json = string | number | boolean | null | Json[] | {
-    [key: string]: Json | undefined;
+    [key: string]: Json;
 };
 export type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
@@ -21,18 +21,18 @@ export type AnyDeps = Record<string, string[]>;
 /**
  * Represents a Flow that has not steps nor deps defined yet
  */
-export type EmptyFlow = Flow<AnyInput, BaseContext, EmptySteps, EmptyDeps>;
+export type EmptyFlow = Flow<AnyInput, {}, EmptySteps, EmptyDeps>;
 /**
  * Represents any Flow with flexible input, context, steps, and dependencies.
  * This type is intentionally more permissive to allow for better type inference
  * in utility types like StepOutput.
  */
-export type AnyFlow = Flow<any, any, any, any>;
+export type AnyFlow = Flow<any, any, any, any, any>;
 /**
  * Extracts the input type from a Flow
  * @template TFlow - The Flow type to extract from
  */
-export type ExtractFlowInput<TFlow extends AnyFlow> = TFlow extends Flow<infer TI, infer _TC, infer _TS, infer _TD> ? TI : never;
+export type ExtractFlowInput<TFlow extends AnyFlow> = TFlow extends Flow<infer TI, infer _TC, infer _TS, infer _TD, infer _TEnv> ? TI : never;
 /**
  * Utility type to extract all possible step inputs from a flow
  * This creates a union of all step input types
@@ -44,24 +44,54 @@ export type AllStepInputs<TFlow extends AnyFlow> = {
  * Extracts the output type from a Flow
  * @template TFlow - The Flow type to extract from
  */
-export type ExtractFlowOutput<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer _TS, infer _TD> ? {
+export type ExtractFlowOutput<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer _TS, infer _TD, infer _TEnv> ? {
     [K in keyof ExtractFlowLeafSteps<TFlow> as K extends string ? K : never]: StepOutput<TFlow, K & string>;
 } : never;
 /**
  * Extracts the steps type from a Flow
  * @template TFlow - The Flow type to extract from
  */
-export type ExtractFlowSteps<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer TS, infer _TD> ? TS : never;
+export type ExtractFlowSteps<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer TS, infer _TD, infer _TEnv> ? TS : never;
 /**
  * Extracts the dependencies type from a Flow
  * @template TFlow - The Flow type to extract from
  */
-export type ExtractFlowDeps<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer _TS, infer TD> ? TD : never;
+export type ExtractFlowDeps<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer _TS, infer TD, infer _TEnv> ? TD : never;
 /**
- * Extracts the context type from a Flow
+ * Extracts the environment type from a Flow
  * @template TFlow - The Flow type to extract from
+ * Returns the TEnv type parameter
  */
-export type ExtractFlowContext<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer TC, infer _TS, infer _TD> ? TC : never;
+export type ExtractFlowEnv<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer _TC, infer _TS, infer _TD, infer TEnv> ? TEnv : never;
+/**
+ * Extracts the full handler context type from a Flow
+ * @template TFlow - The Flow type to extract from
+ * Returns FlowContext<TEnv> & TContext (the complete context handlers receive)
+ */
+export type ExtractFlowContext<TFlow extends AnyFlow> = TFlow extends Flow<infer _TI, infer TC, infer _TS, infer _TD, infer TEnv> ? FlowContext<TEnv> & TC : never;
+/**
+ * Type guard that ensures a flow's context requirements can be satisfied
+ * by the resources provided by the platform and optional user resources.
+ *
+ * A flow is compatible if the provided platform and user resources can satisfy
+ * all the context requirements declared by the flow.
+ *
+ * @template F - The Flow type to check for compatibility
+ * @template PlatformResources - Resources provided by the execution platform (e.g., Supabase resources)
+ * @template UserResources - Additional user-provided resources (default: empty)
+ *
+ * @example
+ * ```typescript
+ * // In a platform worker:
+ * type SupabaseCompatibleFlow<F extends AnyFlow> = CompatibleFlow<F, SupabaseResources>;
+ *
+ * // Usage:
+ * function startWorker<F extends AnyFlow>(flow: SupabaseCompatibleFlow<F>) {
+ *   // flow is guaranteed to be compatible with Supabase platform
+ * }
+ * ```
+ */
+export type CompatibleFlow<F extends AnyFlow, PlatformResources extends Record<string, unknown>, UserResources extends Record<string, unknown> = Record<string, never>> = (FlowContext<ExtractFlowEnv<F>> & PlatformResources & UserResources) extends ExtractFlowContext<F> ? F : never;
 /**
  * Extracts the dependencies type from a Flow
  * @template TFlow - The Flow type to extract from
@@ -92,23 +122,49 @@ export interface RuntimeOptions {
     baseDelay?: number;
     timeout?: number;
 }
-export interface BaseContext {
-    env: Env & ValidEnv<UserEnv>;
+export interface WorkerConfig {
+    maxConcurrent: number;
+    maxPollSeconds: number;
+    pollIntervalMs: number;
+    batchSize: number;
+    visibilityTimeout: number;
+}
+export interface MessageRecord {
+    msg_id: number;
+    read_ct: number;
+    enqueued_at: string;
+    vt: string;
+    message: Json;
+}
+export interface StepTaskRecord<TFlow extends AnyFlow> {
+    flow_slug: string;
+    run_id: string;
+    step_slug: string;
+    input: Json;
+    msg_id: number;
+}
+export interface BaseContext<TEnv extends Env = Env> {
+    env: TEnv & ValidEnv<UserEnv>;
     shutdownSignal: AbortSignal;
+    rawMessage: MessageRecord;
+    workerConfig: Readonly<WorkerConfig>;
+}
+export interface FlowContext<TEnv extends Env = Env> extends BaseContext<TEnv> {
+    stepTask: StepTaskRecord<AnyFlow>;
 }
-export type Context<T extends Record<string, unknown> = Record<string, never>> = BaseContext & T;
-type ExtractHandlerContext<T> = T extends (input: any, context: infer C) => any ? C : never;
+export type Context<T extends Record<string, unknown> = Record<string, never>, TEnv extends Env = Env> = FlowContext<TEnv> & T;
 export interface StepRuntimeOptions extends RuntimeOptions {
     startDelay?: number;
 }
-export interface StepDefinition<TInput extends AnyInput, TOutput extends AnyOutput, TContext = BaseContext> {
+export interface StepDefinition<TInput extends AnyInput, TOutput extends AnyOutput, TContext = FlowContext> {
     slug: string;
     handler: (input: TInput, context: TContext) => TOutput | Promise<TOutput>;
     dependencies: string[];
     options: StepRuntimeOptions;
+    stepType?: 'single' | 'map';
 }
-export declare class Flow<TFlowInput extends AnyInput = AnyInput, TContext = BaseContext, // Accumulated context requirements (starts with BaseContext)
-Steps extends AnySteps = EmptySteps, StepDependencies extends AnyDeps = EmptyDeps> {
+export declare class Flow<TFlowInput extends AnyInput = AnyInput, TContext extends Record<string, unknown> = {}, // Accumulated custom context (FlowContext is always provided)
+Steps extends AnySteps = EmptySteps, StepDependencies extends AnyDeps = EmptyDeps, TEnv extends Env = Env> {
     /**
      * Store step definitions with their proper types
      *
@@ -136,13 +192,64 @@ Steps extends AnySteps = EmptySteps, StepDependencies extends AnyDeps = EmptyDep
         run: TFlowInput;
     } & {
         [K in Deps]: K extends keyof Steps ? Steps[K] : never;
-    }>, context: BaseContext & TContext) => any, Deps extends Extract<keyof Steps, string> = never>(opts: Simplify<{
-        slug: Slug;
+    }>, context: FlowContext<TEnv> & TContext) => any, Deps extends Extract<keyof Steps, string> = never>(opts: Simplify<{
+        slug: Slug extends keyof Steps ? never : Slug;
         dependsOn?: Deps[];
-    } & StepRuntimeOptions>, handler: THandler): Flow<TFlowInput, TContext & BaseContext & ExtractHandlerContext<THandler>, Steps & {
+    } & StepRuntimeOptions>, handler: THandler): Flow<TFlowInput, TContext, Steps & {
         [K in Slug]: AwaitedReturn<THandler>;
     }, StepDependencies & {
         [K in Slug]: Deps[];
+    }, TEnv>;
+    /**
+     * Add an array-returning step to the flow with compile-time type safety
+     *
+     * This method provides semantic clarity and type enforcement for steps that return arrays,
+     * while maintaining full compatibility with the existing step system by delegating to `.step()`.
+     *
+     * @template Slug - The unique identifier for this step
+     * @template THandler - The handler function that must return an array or Promise<array>
+     * @template Deps - The step dependencies (must be existing step slugs)
+     * @param opts - Step configuration including slug, dependencies, and runtime options
+     * @param handler - Function that processes input and returns an array (null/undefined rejected)
+     * @returns A new Flow instance with the array step added
+     */
+    array<Slug extends string, THandler extends (input: Simplify<{
+        run: TFlowInput;
+    } & {
+        [K in Deps]: K extends keyof Steps ? Steps[K] : never;
+    }>, context: BaseContext & TContext) => readonly any[] | Promise<readonly any[]>, Deps extends Extract<keyof Steps, string> = never>(opts: Simplify<{
+        slug: Slug extends keyof Steps ? never : Slug;
+        dependsOn?: Deps[];
+    } & StepRuntimeOptions>, handler: THandler): Flow<TFlowInput, TContext, Steps & {
+        [K in Slug]: AwaitedReturn<THandler>;
+    }, StepDependencies & {
+        [K in Slug]: Deps[];
+    }, TEnv>;
+    /**
+     * Add a map step to the flow that processes arrays element by element
+     *
+     * Map steps apply a handler function to each element of an array, producing
+     * a new array with the transformed elements. The handler receives individual
+     * array elements, not the full input object.
+     *
+     * @param opts - Step configuration including slug and optional array dependency
+     * @param handler - Function that processes individual array elements
+     * @returns A new Flow instance with the map step added
+     */
+    map<Slug extends string, THandler extends TFlowInput extends readonly (infer Item)[] ? (item: Item, context: BaseContext & TContext) => Json | Promise<Json> : never>(opts: Simplify<{
+        slug: Slug extends keyof Steps ? never : Slug;
+    } & StepRuntimeOptions>, handler: THandler): Flow<TFlowInput, TContext & BaseContext, Steps & {
+        [K in Slug]: AwaitedReturn<THandler>[];
+    }, StepDependencies & {
+        [K in Slug]: [];
+    }>;
+    map<Slug extends string, TArrayDep extends Extract<keyof Steps, string>, THandler extends Steps[TArrayDep] extends readonly (infer Item)[] ? (item: Item, context: BaseContext & TContext) => Json | Promise<Json> : never>(opts: Simplify<{
+        slug: Slug extends keyof Steps ? never : Slug;
+        array: TArrayDep;
+    } & StepRuntimeOptions>, handler: THandler): Flow<TFlowInput, TContext & BaseContext, Steps & {
+        [K in Slug]: AwaitedReturn<THandler>[];
+    }, StepDependencies & {
+        [K in Slug]: [TArrayDep];
     }>;
 }
 export {};

package/dist/dsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}

package/dist/dsl.js

@@ -87,4 +87,73 @@ export class Flow {
         // This is safe because we're constructing the newStepDefinitions in a type-safe way above
         return new Flow({ slug: this.slug, ...this.options }, newStepDefinitions, newStepOrder);
     }
+    /**
+     * Add an array-returning step to the flow with compile-time type safety
+     *
+     * This method provides semantic clarity and type enforcement for steps that return arrays,
+     * while maintaining full compatibility with the existing step system by delegating to `.step()`.
+     *
+     * @template Slug - The unique identifier for this step
+     * @template THandler - The handler function that must return an array or Promise<array>
+     * @template Deps - The step dependencies (must be existing step slugs)
+     * @param opts - Step configuration including slug, dependencies, and runtime options
+     * @param handler - Function that processes input and returns an array (null/undefined rejected)
+     * @returns A new Flow instance with the array step added
+     */
+    array(opts, handler) {
+        // Delegate to existing .step() method for maximum code reuse
+        return this.step(opts, handler);
+    }
+    // Implementation
+    map(opts, handler) {
+        const slug = opts.slug;
+        // Validate the step slug
+        validateSlug(slug);
+        if (this.stepDefinitions[slug]) {
+            throw new Error(`Step "${slug}" already exists in flow "${this.slug}"`);
+        }
+        // Determine dependencies based on whether array is specified
+        let dependencies = [];
+        const arrayDep = opts.array;
+        if (arrayDep) {
+            // Dependent map - validate single dependency exists and returns array
+            if (!this.stepDefinitions[arrayDep]) {
+                throw new Error(`Step "${slug}" depends on undefined step "${arrayDep}"`);
+            }
+            dependencies = [arrayDep];
+        }
+        else {
+            // Root map - flow input must be an array (type system enforces this)
+            dependencies = [];
+        }
+        // Extract runtime options
+        const options = {};
+        if (opts.maxAttempts !== undefined)
+            options.maxAttempts = opts.maxAttempts;
+        if (opts.baseDelay !== undefined)
+            options.baseDelay = opts.baseDelay;
+        if (opts.timeout !== undefined)
+            options.timeout = opts.timeout;
+        if (opts.startDelay !== undefined)
+            options.startDelay = opts.startDelay;
+        // Validate runtime options
+        validateRuntimeOptions(options, { optional: true });
+        // Create the map step definition with stepType
+        // Note: We use AnyInput/AnyOutput here because the actual types are handled at the type level via overloads
+        const newStepDefinition = {
+            slug,
+            handler: handler, // Type assertion needed due to complex generic constraints
+            dependencies,
+            options,
+            stepType: 'map', // Mark this as a map step
+        };
+        const newStepDefinitions = {
+            ...this.stepDefinitions,
+            [slug]: newStepDefinition,
+        };
+        // Create a new stepOrder array with the new slug appended
+        const newStepOrder = [...this.stepOrder, slug];
+        // Create and return new Flow instance with updated types
+        return new Flow({ slug: this.slug, ...this.options }, newStepDefinitions, newStepOrder); // Type assertion handled by overloads
+    }
 }

package/dist/example-flow.d.ts

@@ -2,7 +2,7 @@ import { Flow } from './dsl.js';
 type Input = {
     url: string;
 };
-export declare const AnalyzeWebsite: Flow<Input, import("./dsl.js").BaseContext, import("./dsl.js").EmptySteps & {
+export declare const AnalyzeWebsite: Flow<Input, {}, import("./dsl.js").EmptySteps & {
     website: {
         content: string;
     };
@@ -24,6 +24,6 @@ export declare const AnalyzeWebsite: Flow<Input, import("./dsl.js").BaseContext,
     summary: "website"[];
 } & {
     saveToDb: ("sentiment" | "summary")[];
-}>;
+}, import("./dsl.js").Env>;
 export {};
 //# sourceMappingURL=example-flow.d.ts.map

package/dist/example-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"example-flow.d.ts","sourceRoot":"","sources":["../src/example-flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAGhC,KAAK,KAAK,GAAG;IACX,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;EA4BxB,CAAC"}
+{"version":3,"file":"example-flow.d.ts","sourceRoot":"","sources":["../src/example-flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAGhC,KAAK,KAAK,GAAG;IACX,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;0BA4BxB,CAAC"}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgflow/dsl",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/dist/platforms/supabase.d.ts

@@ -1,6 +1,6 @@
 import type { Sql } from 'postgres';
 import type { SupabaseClient } from '@supabase/supabase-js';
-import { Flow as CoreFlow, type AnyInput, type AnySteps, type AnyDeps, EmptySteps, EmptyDeps, type Env, type UserEnv, type ValidEnv, type AnyFlow, type Json, type BaseContext } from '../index.js';
+import { Flow as CoreFlow, type AnyInput, type AnySteps, type AnyDeps, EmptySteps, EmptyDeps, type Env } from '../index.js';
 export interface SupabaseResources extends Record<string, unknown> {
     sql: Sql;
     /**
@@ -16,17 +16,7 @@ export interface SupabaseEnv extends Env {
     SB_EXECUTION_ID: string;
     EDGE_WORKER_LOG_LEVEL?: string;
 }
-export type SupabasePlatformContext = BaseContext & SupabaseResources & {
-    env: SupabaseEnv & ValidEnv<UserEnv>;
-};
-export type SupabaseMessageContext<T extends Json = Json> = SupabasePlatformContext & {
-    rawMessage: any;
-};
-export type SupabaseStepTaskContext<F extends AnyFlow = AnyFlow> = SupabasePlatformContext & {
-    rawMessage: any;
-    stepTask: any;
-};
-export declare class Flow<I extends AnyInput = AnyInput, ExtraCtx extends Record<string, unknown> = Record<string, never>, S extends AnySteps = EmptySteps, D extends AnyDeps = EmptyDeps> extends CoreFlow<I, SupabasePlatformContext & ExtraCtx, // <── full ctx in handlers
-S, D> {
+export type SupabasePlatformContext = SupabaseResources;
+export declare class Flow<I extends AnyInput = AnyInput, CustomCtx extends Record<string, unknown> = {}, S extends AnySteps = EmptySteps, D extends AnyDeps = EmptyDeps, TEnv extends Env = SupabaseEnv> extends CoreFlow<I, SupabasePlatformContext & CustomCtx, S, D, TEnv> {
 }
 //# sourceMappingURL=supabase.d.ts.map

package/dist/platforms/supabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/platforms/supabase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EACL,IAAI,IAAI,QAAQ,EAChB,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAC1C,UAAU,EAAE,SAAS,EAAE,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAC5D,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAC1C,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,GAAG,EAAc,GAAG,CAAC;IACrB;;OAEG;IACH,QAAQ,EAAS,cAAc,CAAC;CACjC;AAGD,MAAM,WAAW,WAAY,SAAQ,GAAG;IACtC,kBAAkB,EAAQ,MAAM,CAAC;IACjC,YAAY,EAAc,MAAM,CAAC;IACjC,iBAAiB,EAAQ,MAAM,CAAC;IAChC,yBAAyB,EAAE,MAAM,CAAC;IAClC,eAAe,EAAW,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAI,MAAM,CAAC;CAClC;AAGD,MAAM,MAAM,uBAAuB,GACjC,WAAW,GAAG,iBAAiB,GAAG;IAChC,GAAG,EAAE,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAGJ,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,IACtD,uBAAuB,GAAG;IACxB,UAAU,EAAE,GAAG,CAAC;CACjB,CAAC;AAEJ,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAC7D,uBAAuB,GAAG;IACxB,UAAU,EAAE,GAAG,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC;CACf,CAAC;AAGJ,qBAAa,IAAI,CACf,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAChE,CAAC,SAAS,QAAQ,GAAG,UAAU,EAC/B,CAAC,SAAS,OAAO,GAAK,SAAS,CAC/B,SAAQ,QAAQ,CAChB,CAAC,EACD,uBAAuB,GAAG,QAAQ,EAAI,2BAA2B;AACjE,CAAC,EAAE,CAAC,CACL;CAAG"}
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/platforms/supabase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EACL,IAAI,IAAI,QAAQ,EAChB,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAC1C,UAAU,EAAE,SAAS,EAAE,KAAK,GAAG,EAChC,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,GAAG,EAAc,GAAG,CAAC;IACrB;;OAEG;IACH,QAAQ,EAAS,cAAc,CAAC;CACjC;AAGD,MAAM,WAAW,WAAY,SAAQ,GAAG;IACtC,kBAAkB,EAAQ,MAAM,CAAC;IACjC,YAAY,EAAc,MAAM,CAAC;IACjC,iBAAiB,EAAQ,MAAM,CAAC;IAChC,yBAAyB,EAAE,MAAM,CAAC;IAClC,eAAe,EAAW,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAI,MAAM,CAAC;CAClC;AAMD,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAGxD,qBAAa,IAAI,CACf,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAE7B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAC9C,CAAC,SAAS,QAAQ,GAAG,UAAU,EAC/B,CAAC,SAAS,OAAO,GAAK,SAAS,EAC/B,IAAI,SAAS,GAAG,GAAG,WAAW,CAC9B,SAAQ,QAAQ,CAChB,CAAC,EACD,uBAAuB,GAAG,SAAS,EACnC,CAAC,EAAE,CAAC,EACJ,IAAI,CACL;CAAG"}

package/dist/platforms/supabase.js

@@ -1,4 +1,4 @@
 import { Flow as CoreFlow } from '../index.js';
-/* ---------- 5. pre-wired Flow helper -------------------------------- */
+/* ---------- 4. pre-wired Flow helper -------------------------------- */
 export class Flow extends CoreFlow {
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgflow/dsl",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",