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

package/README.md

@@ -31,7 +31,7 @@ type Input = {
 
 // Define a flow with steps and dependencies
 export const AnalyzeWebsite = new Flow<Input>({
-  slug: 'analyze_website',
+  slug: 'analyzeWebsite',
   maxAttempts: 3,
   baseDelay: 5,
   timeout: 10,
@@ -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: '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.
@@ -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
 
@@ -128,7 +271,7 @@ To use Supabase resources, import the `Flow` class from the Supabase preset:
 import { Flow } from '@pgflow/dsl/supabase';
 
 const MyFlow = new Flow<{ userId: string }>({
-  slug: 'my_flow',
+  slug: 'myFlow',
 }).step({ slug: 'process' }, async (input, context) => {
   // TypeScript knows context includes Supabase resources
   const { data } = await context.supabase
@@ -157,7 +300,7 @@ Configure flows and steps with runtime options:
 
 ```typescript
 new Flow<Input>({
-  slug: 'my_flow', // Required: Unique flow identifier
+  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)

package/dist/CHANGELOG.md

@@ -0,0 +1,481 @@
+# @pgflow/dsl
+
+## 0.0.0-testsnap-9294d743-20251207205914
+
+### Patch Changes
+
+- 0b84bb0: Add automatic flow compilation at worker startup. Workers now call ensure_flow_compiled to verify flows are up-to-date. In development, mismatched flows are recompiled automatically. In production, mismatches cause errors. Use ensureCompiledOnStartup: false to opt-out.
+
+## 0.9.1
+
+### Patch Changes
+
+- 992a86b: Unify connection configuration with improved local detection. The `connectionString` config option now works correctly, and you can pass a raw postgres.js `sql` instance via `config.sql` for full control over connection options (SSL, pooling, etc.).
+
+  Fixes [#469](https://github.com/pgflow-dev/pgflow/issues/469), [#424](https://github.com/pgflow-dev/pgflow/issues/424). Thanks to [@Nciso](https://github.com/Nciso), [@mikz](https://github.com/mikz), [@ddlaws0n](https://github.com/ddlaws0n), and **PixelEcho** for feedback and bug reports.
+
+## 0.9.0
+
+## 0.8.1
+
+## 0.8.0
+
+## 0.7.3
+
+## 0.7.2
+
+## 0.7.1
+
+## 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
+
+### Minor Changes
+
+- a67bf27: 🚨 **BREAKING**: Remove `anonSupabase` and `serviceSupabase` from context, replaced with single `supabase` client (initialized with service role key)
+
+  The dual-client approach was unnecessary complexity. Edge Functions run in a trusted environment with service role access, so a single client is sufficient.
+
+  **Migration guide**:
+
+  ```typescript
+  // Before
+  const { data } = await context.serviceSupabase.from('users').select();
+  const { data: publicData } = await context.anonSupabase
+    .from('posts')
+    .select();
+
+  // After
+  const { data } = await context.supabase.from('users').select();
+  // For RLS-respecting queries, implement proper policies in your database
+  ```
+
+  ⚠️ **Breaking changes**:
+
+  - Removed `anonSupabase` from context interface
+  - Removed `serviceSupabase` from context interface
+  - Added `supabase` field (initialized with service role key)
+  - Removed `createAnonSupabaseClient` function
+
+## 0.5.4
+
+### Patch Changes
+
+- 9f219a4: Add context object as second parameter to handlers
+
+  Queue and flow handlers now receive an optional context parameter that provides platform resources like database connections, environment variables, and Supabase clients - eliminating boilerplate and connection management.
+
+  ```typescript
+  // Queue handler
+  EdgeWorker.start(async (payload, context) => {
+    await context.sql`INSERT INTO tasks (data) VALUES (${payload})`;
+  });
+
+  // Flow step handler
+  .step({ slug: 'process' }, async (input, context) => {
+    const result = await context.serviceSupabase.from('users').select();
+  })
+  ```
+
+  **Core resources** (always available):
+
+  - `context.env` - Environment variables
+  - `context.shutdownSignal` - AbortSignal for graceful shutdown
+  - `context.rawMessage` - Original pgmq message with metadata
+  - `context.stepTask` - Current step task details (flow handlers only)
+
+  **Supabase platform resources**:
+
+  - `context.sql` - PostgreSQL client (postgres.js)
+  - `context.anonSupabase` - Supabase client with anonymous key
+  - `context.serviceSupabase` - Supabase client with service role key
+
+  To use Supabase resources in flows, import from the Supabase preset:
+
+  ```typescript
+  import { Flow } from '@pgflow/dsl/supabase';
+  ```
+
+  The context parameter is optional for backward compatibility - existing single-parameter handlers continue to work unchanged.
+
+## 0.5.3
+
+### Patch Changes
+
+- af787ff: Add `startDelay` option for workflow steps
+
+  Introduces the ability to delay a step's **initial execution** by a specified number of seconds, enabling multi-day workflows and scheduled tasks within pgflow.
+
+  **Important**: `startDelay` only applies to the first execution attempt. Retries use the standard exponential backoff mechanism based on `baseDelay`, not `startDelay`.
+
+  ### Core Changes (@pgflow/core)
+
+  - Added `opt_start_delay` column (integer, nullable, CHECK >= 0) to `pgflow.steps` table
+  - Updated `add_step` function to accept and validate the new `start_delay` parameter
+  - Modified `start_ready_steps` to schedule initial task execution with delay via `pgmq.send(queue, message, delay)`
+  - Requires pgmq >= 0.40 for delay support
+  - Migration: `20250707210212_pgflow_add_opt_start_delay.sql`
+  - Added comprehensive PgTAP tests for validation and scheduling behavior
+
+  ### DSL Changes (@pgflow/dsl)
+
+  - Extended `StepOptions` and `StepRuntimeOptions` interfaces with optional `startDelay` (in seconds)
+  - Updated `compileFlow()` to emit `start_delay => value` in generated SQL
+  - Added validation: `startDelay` is only allowed at step level, not flow level (prevents cascading delays)
+  - Valid range: 0 to 2,147,483,647 seconds (~68 years)
+  - Added unit tests for compilation and validation
+
+  ### Documentation Updates (@pgflow/website)
+
+  - Added `startDelay` section in configuration guide with detailed explanation
+  - Created multi-day workflow example (onboarding email sequence)
+  - Updated "Update Flow Options" to include `opt_start_delay`
+  - Enhanced VS comparison pages to mention "Native step delays" capability
+  - Documented why `startDelay` is step-level only
+
+  ### Example Usage
+
+  ```typescript
+  new Flow({
+    slug: 'user_onboarding',
+    maxAttempts: 3,
+    baseDelay: 5, // Retry delay (not initial delay)
+    timeout: 60,
+  })
+    .step(
+      {
+        slug: 'send_welcome_email',
+        // Executes immediately when step becomes ready
+      },
+      sendWelcomeHandler
+    )
+    .step(
+      {
+        slug: 'send_day_3_tips',
+        startDelay: 259200, // Wait 3 days before first execution
+        timeout: 120,
+      },
+      sendTipsHandler
+    )
+    .step(
+      {
+        slug: 'send_week_review',
+        startDelay: 604800, // Wait 7 days after dependencies complete
+        timeout: 120,
+      },
+      sendReviewHandler
+    );
+  ```
+
+  ### Use Cases
+
+  - **Multi-day workflows**: Onboarding sequences, follow-up reminders
+  - **Scheduled notifications**: Send reports or alerts at specific intervals
+  - **Rate limiting**: Enforce minimum time between API calls
+  - **Compliance delays**: Cooling-off periods before actions
+
+  ### Technical Notes
+
+  - Non-breaking, additive change (hence minor version bump)
+  - No changes required in `@pgflow/edge-worker` - delays handled by pgmq
+  - `startDelay` does not affect retry timing - only the initial execution
+  - Delays are reliable even across worker restarts (persisted in queue)
+
+## 0.5.2
+
+## 0.5.1
+
+## 0.5.0
+
+## 0.4.3
+
+## 0.4.2
+
+## 0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 98556d3: Add TypeScript client library for pgflow workflow management
+
+  ## @pgflow/client
+
+  Introduces a new TypeScript client library that provides both event-based and promise-based APIs for interacting with pgflow workflows:
+
+  ### Features
+
+  - **Type-safe workflow management** with full TypeScript support and automatic type inference from flow definitions
+  - **Dual API approach**: Choose between event-based subscriptions or promise-based async/await patterns
+  - **Real-time monitoring** via Supabase broadcasts with granular event subscriptions
+  - **Resource management** with automatic cleanup and disposal
+  - **Comprehensive error handling** and recovery mechanisms
+
+  ### Core Components
+
+  - `PgflowClient` - Main client for starting and managing workflow runs
+  - `FlowRun` - Monitor and interact with workflow executions
+  - `FlowStep` - Track individual step progress and outputs
+
+  ### Example Usage
+
+  ```typescript
+  // Start a workflow
+  const pgflow = new PgflowClient(supabase);
+  const run = await pgflow.startFlow('analyze_website', {
+    url: 'https://example.com',
+  });
+
+  // Event-based monitoring
+  run.on('completed', (event) => {
+    console.log('Workflow completed:', event.output);
+  });
+
+  // Promise-based monitoring
+  const completed = await run.waitForStatus(FlowRunStatus.Completed, {
+    timeoutMs: 30000,
+  });
+  ```
+
+  ## @pgflow/core
+
+  ### Database Enhancements
+
+  - Add `start_flow_with_states()` function to start flows and return complete initial state
+  - Add `get_run_with_states()` function to retrieve runs with all step states efficiently
+  - Implement `SECURITY DEFINER` functions for secure API access
+  - Add real-time broadcast support for workflow state changes
+
+  ## @pgflow/edge-worker
+
+  ### Test Infrastructure Updates
+
+  - Update test database configuration to use standard PostgreSQL credentials
+  - Improve test helper functions for database transactions
+  - Update Docker Compose configuration for test environment
+
+  ## @pgflow/dsl
+
+  ### Build Configuration
+
+  - Add TypeScript references to tsconfig.spec.json for improved type checking in tests
+
+## 0.3.1
+
+## 0.3.0
+
+## 0.2.6
+
+## 0.2.5
+
+## 0.2.4
+
+## 0.2.3
+
+## 0.2.2
+
+## 0.2.1
+
+### Patch Changes
+
+- 3f3174e: Update the README's
+
+## 0.2.0
+
+## 0.1.23
+
+## 0.1.22
+
+### Patch Changes
+
+- 8f6eb3d: Added ExtractFlowLeafSteps and ExtractFlowOutput utility types
+
+## 0.1.21
+
+## 0.1.20
+
+## 0.1.19
+
+## 0.1.18
+
+### Patch Changes
+
+- 3a7e132: Do not build edge-worker for npm
+
+## 0.1.17
+
+### Patch Changes
+
+- d215ed2: Trigger version change
+
+## 0.1.16
+
+### Patch Changes
+
+- cc7c431: Test release to verify combined publishing of both npm and jsr packages
+
+## 0.1.15
+
+### Patch Changes
+
+- ce34a2c: Update release pipeline to publish to jsr
+
+## 0.1.14
+
+## 0.1.13
+
+## 0.1.12
+
+### Patch Changes
+
+- 7b1328e: Include invalid slug in validateSlug error message
+
+## 0.1.11
+
+## 0.1.10
+
+### Patch Changes
+
+- bafe767: Fix deno/ folder for cli being missing
+
+## 0.1.9
+
+### Patch Changes
+
+- 1a30c6c: Make sure to tag and push tags
+
+## 0.1.8
+
+### Patch Changes
+
+- 05f5bd8: Update release script
+
+## 0.1.7
+
+## 0.1.6
+
+### Patch Changes
+
+- Test release to verify problem with bumping edge-worker
+
+## 0.1.5
+
+### Patch Changes
+
+- 5820e7a: Bump version for tests
+
+## 0.1.4
+
+## 0.1.3
+
+## 0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- b362364: Add compileFlow function
+
+## 0.1.0
+
+## 0.0.23
+
+## 0.0.22
+
+## 0.0.21
+
+## 0.0.20
+
+## 0.0.19
+
+## 0.0.18
+
+### Patch Changes
+
+- 53abf4a: Fix pnpm issues with linking to dist/
+
+## 0.0.17
+
+## 0.0.16
+
+## 0.0.15
+
+## 0.0.14
+
+## 0.0.13
+
+## 0.0.12
+
+## 0.0.11
+
+### Patch Changes
+
+- 17937e3: Update changesets action and comment out custom publish
+
+## 0.0.10
+
+## 0.0.9
+
+### Patch Changes
+
+- 70d3f2d: Tweak extension setting in tsconfig.base.json
+
+## 0.0.8
+
+## 0.0.7
+
+### Patch Changes
+
+- 7c83db9: Add release-related options to package.json files
+
+## 0.0.6
+
+## 0.0.5
+
+### Patch Changes
+
+- b4b0809: test changesets