@pgflow/dsl 0.0.0-test-snapshot-releases2-8d5d9bc1-20250922101158 → 0.0.0-testsnap-9294d743-20251207205914

package/dist/README.md

@@ -0,0 +1,346 @@
+# @pgflow/dsl
+
+The TypeScript Domain Specific Language (DSL) for defining type-safe workflow definitions in pgflow.
+
+> [!NOTE]
+> This project and all its components are licensed under [Apache 2.0](./LICENSE) license.
+
+## Overview
+
+`@pgflow/dsl` provides a type-safe, fluent interface for defining data-driven workflows with explicit dependencies. The DSL ensures that data flows correctly between steps and maintains type safety throughout the entire workflow definition.
+
+Key features:
+
+- **Type Safety** - Complete TypeScript type checking from flow inputs to outputs
+- **Fluent Interface** - Chainable method calls for defining steps and dependencies
+- **Functional Approach** - Clean separation between task implementation and flow orchestration
+- **JSON-Compatible** - All inputs and outputs are JSON-serializable for database storage
+- **Immutable Flow Definitions** - Each step operation returns a new Flow instance
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { Flow } from '@pgflow/dsl';
+
+// Define input type for the flow
+type Input = {
+  url: string;
+};
+
+// Define a flow with steps and dependencies
+export const AnalyzeWebsite = new Flow<Input>({
+  slug: 'analyzeWebsite',
+  maxAttempts: 3,
+  baseDelay: 5,
+  timeout: 10,
+})
+  .step(
+    { slug: 'website' },
+    async (input) => await scrapeWebsite(input.run.url)
+  )
+  .step(
+    { slug: 'sentiment', dependsOn: ['website'] },
+    async (input) => await analyzeSentiment(input.website.content)
+  )
+  .step(
+    { slug: 'summary', dependsOn: ['website'] },
+    async (input) => await summarizeWithAI(input.website.content)
+  )
+  .step(
+    { slug: 'saveToDb', dependsOn: ['sentiment', 'summary'] },
+    async (input) => {
+      return await saveToDb({
+        websiteUrl: input.run.url,
+        sentiment: input.sentiment.score,
+        summary: input.summary.aiSummary,
+      });
+    }
+  );
+```
+
+### Understanding Data Flow
+
+In pgflow, each step receives an `input` object that contains:
+
+1. **`input.run`** - The original flow input (available to all steps)
+2. **`input.{stepName}`** - Outputs from dependency steps
+
+This design ensures:
+
+- Original flow parameters are accessible throughout the entire flow
+- 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: 'fetchItems' },
+  async () => [1, 2, 3, 4, 5]
+)
+
+// With dependencies - combining data from multiple sources
+.array(
+  { slug: 'combineResults', 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: 'processStrings' })
+  .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: 'dataPipeline' })
+  .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: 'userFlow' })
+  .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: 'batchProcessor' })
+  .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: 'etlPipeline' })
+  .step({ slug: 'fetchUrls' }, () => ['url1', 'url2', 'url3'])
+  .map({ slug: 'scrape', array: 'fetchUrls' }, 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.
+
+```typescript
+.step(
+  { slug: 'saveToDb' },
+  async (input, context) => {
+    // Access platform resources through context
+    const result = await context.sql`SELECT * FROM users WHERE id = ${input.userId}`;
+    return result[0];
+  }
+)
+```
+
+#### Core Context Resources
+
+All platforms provide these core resources:
+
+- **`context.env`** - Environment variables (`Record<string, string | undefined>`)
+- **`context.shutdownSignal`** - AbortSignal for graceful shutdown handling
+- **`context.rawMessage`** - Original pgmq message with metadata
+  ```typescript
+  interface PgmqMessageRecord<T> {
+    msg_id: number;
+    read_ct: number;
+    enqueued_at: Date;
+    vt: Date;
+    message: T; // <-- this is your 'input'
+  }
+  ```
+- **`context.stepTask`** - Current step task details (flow handlers only)
+  ```typescript
+  interface StepTaskRecord<TFlow> {
+    flow_slug: string;
+    run_id: string;
+    step_slug: string;
+    input: StepInput<TFlow, StepSlug>; // <-- this is handler 'input'
+    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
+
+When using the Supabase platform with EdgeWorker, additional resources are available:
+
+- **`context.sql`** - PostgreSQL client (postgres.js)
+- **`context.supabase`** - Supabase client with service role key for full database access
+
+To use Supabase resources, import the `Flow` class from the Supabase preset:
+
+```typescript
+import { Flow } from '@pgflow/dsl/supabase';
+
+const MyFlow = new Flow<{ userId: string }>({
+  slug: 'myFlow',
+}).step({ slug: 'process' }, async (input, context) => {
+  // TypeScript knows context includes Supabase resources
+  const { data } = await context.supabase
+    .from('users')
+    .select('*')
+    .eq('id', input.userId);
+
+  // Use SQL directly
+  const stats = await context.sql`
+      SELECT COUNT(*) as total FROM events 
+      WHERE user_id = ${input.userId}
+    `;
+
+  return { user: data[0], eventCount: stats[0].total };
+});
+```
+
+> [!NOTE]
+> Context is optional - handlers that don't need platform resources can omit the second parameter for backward compatibility.
+
+For more details on available resources and platform configuration, see the [@pgflow/edge-worker documentation](https://github.com/pgflow-org/pgflow/tree/main/pkgs/edge-worker#context-resources).
+
+### Flow Configuration
+
+Configure flows and steps with runtime options:
+
+```typescript
+new Flow<Input>({
+  slug: 'myFlow', // Required: Unique flow identifier
+  maxAttempts: 3, // Optional: Maximum retry attempts (default: 1)
+  baseDelay: 5, // Optional: Base delay in seconds for retries (default: 1)
+  timeout: 10, // Optional: Task timeout in seconds (default: 30)
+});
+```
+
+## Compiling Flows
+
+Use the `compileFlow` utility to convert a flow definition into SQL statements:
+
+```typescript
+import { compileFlow } from '@pgflow/dsl';
+
+const sqlStatements = compileFlow(MyFlow);
+console.log(sqlStatements.join('\n'));
+```
+
+Alternatively, use the pgflow CLI to compile flows directly to migration files:
+
+```bash
+npx pgflow compile path/to/flow.ts
+```
+
+## Requirements
+
+- All step inputs and outputs MUST be JSON-serializable
+- Use only: primitive types, plain objects, and arrays
+- Convert dates to ISO strings (`new Date().toISOString()`)
+- Avoid: class instances, functions, symbols, undefined values, and circular references
+
+## Building
+
+Run `nx build dsl` to build the library.
+
+## Running unit tests
+
+Run `nx test dsl` to execute the unit tests via [Vitest](https://vitest.dev/).
+
+## Documentation
+
+For detailed documentation on the Flow DSL, visit:
+
+- [Understanding the Flow DSL](https://pgflow.dev/explanations/flow-dsl/)

package/dist/compile-flow.d.ts

@@ -0,0 +1,10 @@
+import { AnyFlow } from './dsl.js';
+/**
+ * Compiles a Flow object into an array of SQL statements
+ * that can be executed to create the flow and its steps in PostgreSQL
+ *
+ * @param flow The Flow object to compile
+ * @returns Array of SQL statements
+ */
+export declare function compileFlow(flow: AnyFlow): string[];
+//# sourceMappingURL=compile-flow.d.ts.map

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

@@ -0,0 +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,CA+BnD"}

package/dist/compile-flow.js

@@ -0,0 +1,50 @@
+/**
+ * Compiles a Flow object into an array of SQL statements
+ * that can be executed to create the flow and its steps in PostgreSQL
+ *
+ * @param flow The Flow object to compile
+ * @returns Array of SQL statements
+ */
+export function compileFlow(flow) {
+    const statements = [];
+    // Create the flow
+    const flowOptions = formatRuntimeOptions(flow.options);
+    statements.push(`SELECT pgflow.create_flow('${flow.slug}'${flowOptions});`);
+    // Add steps in the order they were defined
+    for (const stepSlug of flow.stepOrder) {
+        const step = flow.getStepDefinition(stepSlug);
+        const stepOptions = formatRuntimeOptions(step.options);
+        // Format dependencies array if it exists
+        let depsClause = '';
+        if (step.dependencies.length > 0) {
+            const depsArray = step.dependencies.map((dep) => `'${dep}'`).join(', ');
+            depsClause = `, ARRAY[${depsArray}]`;
+        }
+        // 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;
+}
+/**
+ * Formats runtime options into SQL parameter string
+ */
+function formatRuntimeOptions(options) {
+    const parts = [];
+    if (options.maxAttempts !== undefined) {
+        parts.push(`max_attempts => ${options.maxAttempts}`);
+    }
+    if (options.baseDelay !== undefined) {
+        parts.push(`base_delay => ${options.baseDelay}`);
+    }
+    if (options.timeout !== undefined) {
+        parts.push(`timeout => ${options.timeout}`);
+    }
+    if ('startDelay' in options && options.startDelay !== undefined) {
+        parts.push(`start_delay => ${options.startDelay}`);
+    }
+    return parts.length > 0 ? `, ${parts.join(', ')}` : '';
+}

package/dist/dsl.d.ts

@@ -0,0 +1,256 @@
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+type AwaitedReturn<T> = T extends (...args: any[]) => Promise<infer R> ? R : T extends (...args: any[]) => infer R ? R : never;
+export interface Env {
+    [key: string]: string | undefined;
+}
+export type ValidEnv<T> = T extends Env ? T : never;
+export interface UserEnv extends Env {
+}
+export type AnyInput = Json;
+export type AnyOutput = Json;
+export type EmptySteps = Record<never, never>;
+export type AnySteps = Record<string, AnyOutput>;
+export type EmptyDeps = Record<never, never[]>;
+export type DefaultDeps = Record<string, string[]>;
+export type AnyDeps = Record<string, string[]>;
+/**
+ * Represents a Flow that has not steps nor deps defined yet
+ */
+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, 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, infer _TEnv> ? TI : never;
+/**
+ * Utility type to extract all possible step inputs from a flow
+ * This creates a union of all step input types
+ */
+export type AllStepInputs<TFlow extends AnyFlow> = {
+    [K in keyof ExtractFlowSteps<TFlow> & string]: StepInput<TFlow, K>;
+}[keyof ExtractFlowSteps<TFlow> & string];
+/**
+ * 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, 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, 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, infer _TEnv> ? TD : never;
+/**
+ * Extracts the environment type from a Flow
+ * @template TFlow - The Flow type to extract from
+ * Returns the TEnv type parameter
+ */
+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
+ */
+type StepDepsOf<TFlow extends AnyFlow, TStepSlug extends string> = TStepSlug extends keyof ExtractFlowDeps<TFlow> ? ExtractFlowDeps<TFlow>[TStepSlug][number] : never;
+/**
+ * Extracts only the leaf steps from a Flow (steps that are not dependencies of any other steps)
+ * @template TFlow - The Flow type to extract from
+ */
+export type ExtractFlowLeafSteps<TFlow extends AnyFlow> = {
+    [K in keyof ExtractFlowSteps<TFlow> as K extends string ? K extends ExtractFlowDeps<TFlow>[keyof ExtractFlowDeps<TFlow>][number] ? never : K : never]: ExtractFlowSteps<TFlow>[K];
+};
+export type StepOutput<TFlow extends AnyFlow, TStepSlug extends string> = TStepSlug extends keyof ExtractFlowSteps<TFlow> ? ExtractFlowSteps<TFlow>[TStepSlug] : never;
+/**
+ * This ensures that:
+ * 1. The run input is always included
+ * 2. Only declared dependencies are included
+ * 3. No extra properties are allowed
+ * Utility type to extract the input type for a specific step in a flow
+ */
+export type StepInput<TFlow extends AnyFlow, TStepSlug extends string> = {
+    run: ExtractFlowInput<TFlow>;
+} & {
+    [K in Extract<keyof ExtractFlowSteps<TFlow>, StepDepsOf<TFlow, TStepSlug>>]: ExtractFlowSteps<TFlow>[K];
+};
+export interface RuntimeOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    timeout?: number;
+}
+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>, TEnv extends Env = Env> = FlowContext<TEnv> & T;
+export interface StepRuntimeOptions extends RuntimeOptions {
+    startDelay?: number;
+}
+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 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
+     *
+     * This is typed as a generic record because TypeScript cannot track the exact relationship
+     * between step slugs and their corresponding input/output types at the container level.
+     * Type safety is enforced at the method level when adding or retrieving steps.
+     */
+    private stepDefinitions;
+    readonly stepOrder: string[];
+    readonly slug: string;
+    readonly options: RuntimeOptions;
+    constructor(config: Simplify<{
+        slug: string;
+    } & RuntimeOptions>, stepDefinitions?: Record<string, StepDefinition<AnyInput, AnyOutput>>, stepOrder?: string[]);
+    /**
+     * Get a specific step definition by slug with proper typing
+     * @throws Error if the step with the given slug doesn't exist
+     */
+    getStepDefinition<SlugType extends keyof Steps & keyof StepDependencies>(slug: SlugType): StepDefinition<Simplify<{
+        run: TFlowInput;
+    } & {
+        [K in StepDependencies[SlugType][number]]: K extends keyof Steps ? Steps[K] : never;
+    }>, Steps[SlugType]>;
+    step<Slug extends string, THandler extends (input: Simplify<{
+        run: TFlowInput;
+    } & {
+        [K in Deps]: K extends keyof Steps ? Steps[K] : never;
+    }>, 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, 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 {};
+//# sourceMappingURL=dsl.d.ts.map

package/dist/dsl.d.ts.map

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