diff --git a/context7.json b/context7.json new file mode 100644 index 000000000..023186653 --- /dev/null +++ b/context7.json @@ -0,0 +1,39 @@ +{ + "$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 `input.stepName`, which is automatically typed as the step's handler return type.", + "Flow input type determines `input.run` in all steps - Define `Flow` to type the original flow input accessible in ALL steps via `input.run` (e.g., `new Flow<{ url: string }>()` makes `input.run.url` available everywhere with full type safety).", + "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 the full `input` object, map handlers receive only the array element (e.g., `(item) => processItem(item)`).", + "Use `.array()` to prepare data for `.map()` handlers - When map handlers need access to `input.run` 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().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 `(input, context)` parameters - The second parameter provides platform resources like `context.sql`, `context.supabase`, `context.env`, `context.stepTask`, and `context.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." + ] +} diff --git a/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx b/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx index dd62c3a12..4ab156783 100644 --- a/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx +++ b/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx @@ -13,7 +13,7 @@ Now that we've defined our flow, we need to register it in the database. pgflow Before continuing, make sure you have: - Completed the [flow definition](/get-started/flows/create-flow/) from the previous step - The Supabase CLI installed and configured -- [Deno version **1.45.2 or higher**](https://github.com/denoland/deno/releases/tag/v1.45.2) (2.x also supported) - required for flow compilation +- [Deno version **2.1.x or higher**](https://github.com/denoland/deno/releases) - required for flow compilation ## What is compilation? diff --git a/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx b/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx index 13900e922..bbfc76629 100644 --- a/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx +++ b/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx @@ -73,7 +73,7 @@ Before starting, make sure you have completed: ``` Setting up Edge Functions runtime... Serving functions on http://127.0.0.1:54321/functions/v1/ - Using supabase-edge-runtime-1.67.4 (compatible with Deno v1.45.2) + Using supabase-edge-runtime-1.67.4 (compatible with Deno v2.1.4) serving the request with supabase/functions/greet_user_worker ``` diff --git a/pkgs/website/src/content/docs/get-started/installation.mdx b/pkgs/website/src/content/docs/get-started/installation.mdx index 724d9dad6..9d38feaee 100644 --- a/pkgs/website/src/content/docs/get-started/installation.mdx +++ b/pkgs/website/src/content/docs/get-started/installation.mdx @@ -15,7 +15,7 @@ Let's set up pgflow in your Supabase project. This setup needs to be done only o