context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "pgflow",
  "description": "Database-centric workflow orchestration for Postgres and Supabase",
  "branch": "main",
  "folders": ["pkgs/website/src/content/docs"],
  "excludeFolders": [
    "pkgs/website/src/content/docs/news",
    "pkgs/website/src/content/docs/edge-worker/_drafts",
    "pkgs/website/src/content/docs/index.mdx",
    "pkgs/website/src/content/docs/demo-colors.mdx",
    "pkgs/website/src/content/docs/author.mdx",
    "pkgs/website/src/content/docs/project-status.mdx"
  ],
  "excludeFiles": [],
  "rules": [
    "Flow definitions are immutable and declarative - Each `.step()`, `.array()` or `.map()` call returns a new Flow instance; describe what steps exist and how they connect, pgflow handles execution.",
    "Step slugs identify steps and type their outputs - Each step has a unique `slug` used in `dependsOn` arrays and to access outputs via `deps.stepName` in dependent steps, which is automatically typed as the step's handler return type.",
    "Asymmetric handler signatures - Root steps receive `(flowInput, ctx)` where flowInput is the flow input directly; dependent steps receive `(deps, ctx)` where deps contains outputs from dependencies and `ctx.flowInput` provides the original flow input if needed.",
    "Root steps omit `dependsOn`, dependent steps require it - Steps with no dependencies omit `dependsOn` entirely; steps that depend on others specify them in the `dependsOn` array (e.g., `{ slug: 'summary', dependsOn: ['website'] }`).",
    "All inputs and outputs must be JSON-serializable - Step handlers must return plain objects, primitives, and arrays only; convert dates to ISO strings and avoid functions, class instances, or circular references.",
    "Use `.array()` for array-returning steps - The `.array()` method is a semantic wrapper around `.step()` that enforces array return types, useful for data collection that will be processed by map steps.",
    "Use `.map()` for parallel array processing - The `.map()` method creates a step that spawns N parallel tasks (one per array element), each with its own retry counter, returning an aggregated array of results.",
    "Handler functions for `.map()` steps receive individual array elements - Unlike `.step()` and `.array()` handlers that receive flowInput or deps, map handlers receive only the array element (e.g., `(item, ctx) => processItem(item)`) with flowInput available via `ctx.flowInput`.",
    "Use `.array()` to prepare data for `.map()` handlers - When map handlers need access to flowInput or outputs from other steps, create an intermediate `.array()` step that enriches each element with the required data.",
    "Map steps can only have a single dependency - Specify the array source via the `array` property (e.g., `{ slug: 'process', array: 'items' }`) and cannot use `dependsOn`.",
    "Root map steps omit `array:`, dependent maps require it - Root maps process flow input directly without `array:` property (e.g., `new Flow<string[]>().map({ slug: 'process' }, ...)`); dependent maps must specify `array:` to indicate which step's output to process.",
    "Steps with the same dependencies run in parallel - pgflow automatically maximizes parallelism by running independent steps concurrently once their dependencies are satisfied.",
    "Handler functions receive context as second parameter - Root steps: `(flowInput, ctx)`, dependent steps: `(deps, ctx)`. Context provides platform resources like `ctx.sql`, `ctx.supabase`, `ctx.env`, `ctx.flowInput`, `ctx.stepTask`, and `ctx.rawMessage` without requiring global imports or connection setup.",
    "Flows must be compiled before execution - Run `npx pgflow@latest compile` to convert TypeScript flow definitions into SQL migrations that register the flow structure in the database.",
    "Registered flows are immutable - Once a flow is registered in the database, its structure cannot be modified; use versioning or deletion (development only) to make changes.",
    "Use camelCase for step slugs - Step slugs follow JavaScript naming conventions (e.g., `fetchData`, not `fetch_data`) since they become property names in TypeScript for accessing outputs.",
    "Name steps based on their primary purpose - Use nouns when downstream steps process the returned data (e.g., `website`, `userProfiles`); use verb-noun when the side effect is primary (e.g., `sendEmails`, `saveToDb`).",
    "Step options inherit from flow defaults - `maxAttempts`, `baseDelay`, and `timeout` can be set at flow level as defaults, then overridden per-step; `startDelay` is step-level only.",
    "Task functions should accept specific parameters, not entire input objects - Let step handlers act as adapters that extract needed data from flow context and pass it to task functions for better reusability and testability.",
    "Use validation steps with `maxAttempts: 1` for input validation - Create explicit validation steps that fail fast without retries to catch invalid input before expensive operations run.",
    "Keep validation steps synchronous - Validation should only check format and structure (email format, positive numbers, array length); existence checks and external validations belong in separate steps with retry configuration."
  ]
}