@pgflow/core 0.0.5 → 0.0.7

package/pkgs/edge-worker/dist/pkgs/edge-worker/README.md

@@ -1,46 +0,0 @@
-<div align="center">
-  <h1>Edge Worker</h1>
-  <a href="https://pgflow.dev">
-    <h3>📚 Documentation @ pgflow.dev</h3>
-  </a>
-  
-  <h4>⚠️ <strong>ADVANCED PROOF of CONCEPT - NOT PRODUCTION READY</strong> ⚠️</h4>
-</div>
-
-A task queue worker for Supabase Edge Functions that extends background tasks with useful features.
-
-> [!NOTE]
-> This project is licensed under [AGPL v3](./LICENSE.md) license and is part of **pgflow** stack.
-> See [LICENSING_OVERVIEW.md](../../LICENSING_OVERVIEW.md) in root of this monorepo for more details.
-
-## What is Edge Worker?
-
-Edge Worker processes messages from a queue and executes user-defined functions with their payloads. It builds upon [Supabase Background Tasks](https://supabase.com/docs/guides/functions/background-tasks) to add reliability features like retries, concurrency control and monitoring.
-
-## Key Features
-
-- ⚡ **Reliable Processing**: Retries with configurable delays
-- 🔄 **Concurrency Control**: Limit parallel task execution
-- 📊 **Observability**: Built-in heartbeats and logging
-- 📈 **Horizontal Scaling**: Deploy multiple edge functions for the same queue
-- 🛡️ **Edge-Native**: Designed for Edge Functions' CPU/clock limits
-
-## How It Works
-
-[![Architecture Diagram](https://mermaid.ink/img/pako:eNplkcFugzAMhl8lyrl9AQ47VLBxqdSqlZAGHEziASokyEkmTaXvvoR0o1VziGL_n_9Y9pULLZEnvFItwdSxc1op5o9xTUxU_OQmaMAgy2SL7N0pYXutTMUjGU5WlItYaLog1VFAJSv14paCXdweyw8f-2MZLnZ06LBelXxXRk_DztAM-Gp9KA-kpRP-W7bdvs3Ga4aNaAy0OC_WdzD4B4IQVsLMvvkIZMUiA4mu_8ZHYjW5MxNp4dUnKC9zUHJA-h9R_VQTG-sQyDYINlTs-IaPSCP00q_gGvCK2w5HP53EPyXQJczp5jlwVp9-lOCJJYcbTtq13V_gJgkW0x78lEeefMFgfHYC9an1GqPsraZ9XPiy99svlAqmtA?type=png)](https://mermaid.live/edit#pako:eNplkcFugzAMhl8lyrl9AQ47VLBxqdSqlZAGHEziASokyEkmTaXvvoR0o1VziGL_n_9Y9pULLZEnvFItwdSxc1op5o9xTUxU_OQmaMAgy2SL7N0pYXutTMUjGU5WlItYaLog1VFAJSv14paCXdweyw8f-2MZLnZ06LBelXxXRk_DztAM-Gp9KA-kpRP-W7bdvs3Ga4aNaAy0OC_WdzD4B4IQVsLMvvkIZMUiA4mu_8ZHYjW5MxNp4dUnKC9zUHJA-h9R_VQTG-sQyDYINlTs-IaPSCP00q_gGvCK2w5HP53EPyXQJczp5jlwVp9-lOCJJYcbTtq13V_gJgkW0x78lEeefMFgfHYC9an1GqPsraZ9XPiy99svlAqmtA)
-
-## Edge Function Optimization
-
-Edge Worker is specifically designed to handle Edge Function limitations:
-
-- Stops polling near CPU/clock limits
-- Gracefully aborts pending tasks
-- Uses PGMQ's visibility timeout to prevent message loss
-- Auto-spawns new instances for continuous operation
-- Monitors worker health with database heartbeats
-
-
-## Documentation
-
-For detailed documentation and getting started guide, visit [pgflow.dev](https://pgflow.dev).
-

package/pkgs/example-flows/dist/index.js

@@ -1,152 +0,0 @@
-// ../dsl/src/utils.ts
-function validateSlug(slug) {
-  if (slug.length > 128) {
-    throw new Error(`Slug cannot be longer than 128 characters`);
-  }
-  if (/^\d/.test(slug)) {
-    throw new Error(`Slug cannot start with a number`);
-  }
-  if (/^_/.test(slug)) {
-    throw new Error(`Slug cannot start with an underscore`);
-  }
-  if (/\s/.test(slug)) {
-    throw new Error(`Slug cannot contain spaces`);
-  }
-  if (/[/:#\-?]/.test(slug)) {
-    throw new Error(
-      `Slug cannot contain special characters like /, :, ?, #, -`
-    );
-  }
-}
-function validateRuntimeOptions(options, opts = { optional: false }) {
-  const { maxAttempts, baseDelay, timeout } = options;
-  if (maxAttempts !== void 0 && maxAttempts !== null) {
-    if (maxAttempts < 1) {
-      throw new Error("maxAttempts must be greater than or equal to 1");
-    }
-  } else if (!opts.optional) {
-    throw new Error("maxAttempts is required");
-  }
-  if (baseDelay !== void 0 && baseDelay !== null) {
-    if (baseDelay < 1) {
-      throw new Error("baseDelay must be greater than or equal to 1");
-    }
-  } else if (!opts.optional) {
-    throw new Error("baseDelay is required");
-  }
-  if (timeout !== void 0 && timeout !== null) {
-    if (timeout < 3) {
-      throw new Error("timeout must be greater than or equal to 3");
-    }
-  } else if (!opts.optional) {
-    throw new Error("timeout is required");
-  }
-}
-
-// ../dsl/src/dsl.ts
-var Flow = class _Flow {
-  /**
-   * 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.
-   */
-  stepDefinitions;
-  stepOrder;
-  slug;
-  options;
-  constructor(config, stepDefinitions = {}, stepOrder = []) {
-    const { slug, ...options } = config;
-    validateSlug(slug);
-    validateRuntimeOptions(options, { optional: true });
-    this.slug = slug;
-    this.options = options;
-    this.stepDefinitions = stepDefinitions;
-    this.stepOrder = [...stepOrder];
-  }
-  /**
-   * Get a specific step definition by slug with proper typing
-   * @throws Error if the step with the given slug doesn't exist
-   */
-  getStepDefinition(slug) {
-    if (!(slug in this.stepDefinitions)) {
-      throw new Error(
-        `Step "${String(slug)}" does not exist in flow "${this.slug}"`
-      );
-    }
-    return this.stepDefinitions[slug];
-  }
-  // SlugType extends keyof Steps & keyof StepDependencies
-  step(opts, handler) {
-    const slug = opts.slug;
-    validateSlug(slug);
-    if (this.stepDefinitions[slug]) {
-      throw new Error(`Step "${slug}" already exists in flow "${this.slug}"`);
-    }
-    const dependencies = opts.dependsOn || [];
-    if (dependencies.length > 0) {
-      for (const dep of dependencies) {
-        if (!this.stepDefinitions[dep]) {
-          throw new Error(`Step "${slug}" depends on undefined step "${dep}"`);
-        }
-      }
-    }
-    const options = {};
-    if (opts.maxAttempts !== void 0)
-      options.maxAttempts = opts.maxAttempts;
-    if (opts.baseDelay !== void 0)
-      options.baseDelay = opts.baseDelay;
-    if (opts.timeout !== void 0)
-      options.timeout = opts.timeout;
-    validateRuntimeOptions(options, { optional: true });
-    const newStepDefinition = {
-      slug,
-      handler,
-      dependencies,
-      options
-    };
-    const newStepDefinitions = {
-      ...this.stepDefinitions,
-      [slug]: newStepDefinition
-    };
-    const newStepOrder = [...this.stepOrder, slug];
-    return new _Flow(
-      { slug: this.slug, ...this.options },
-      newStepDefinitions,
-      newStepOrder
-    );
-  }
-};
-
-// ../example-flows/src/example-flow.ts
-var ExampleFlow = new Flow({
-  slug: "example_flow",
-  maxAttempts: 3
-}).step({ slug: "rootStep" }, async (input) => ({
-  doubledValue: input.run.value * 2
-})).step(
-  { slug: "normalStep", dependsOn: ["rootStep"], maxAttempts: 5 },
-  async (input) => ({
-    doubledValueArray: [input.rootStep.doubledValue]
-  })
-).step({ slug: "thirdStep", dependsOn: ["normalStep"] }, async (input) => ({
-  // input.rootStep would be a type error since it's not in dependsOn
-  finalValue: input.normalStep.doubledValueArray.length
-}));
-var stepTaskRecord = {
-  flow_slug: "example_flow",
-  run_id: "123",
-  step_slug: "normalStep",
-  input: {
-    run: { value: 23 },
-    rootStep: { doubledValue: 23 }
-    // thirdStep: { finalValue: 23 }, --- this should be an error
-    // normalStep: { doubledValueArray: [1, 2, 3] }, --- this should be an error
-  },
-  msg_id: 1
-};
-export {
-  ExampleFlow,
-  stepTaskRecord
-};

package/pkgs/example-flows/dist/pkgs/example-flows/README.md

@@ -1,11 +0,0 @@
-# example-flows
-
-This library was generated with [Nx](https://nx.dev).
-
-## Building
-
-Run `nx build example-flows` to build the library.
-
-## Running unit tests
-
-Run `nx test example-flows` to execute the unit tests via [Vitest](https://vitest.dev/).

package/project.json

@@ -1,125 +0,0 @@
-{
-  "name": "core",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "pkgs/core/src",
-  "projectType": "library",
-  "tags": [],
-  "targets": {
-    "build": {
-      "executor": "@nx/esbuild:esbuild",
-      "outputs": ["{options.outputPath}"],
-      "options": {
-        "outputPath": "pkgs/core/dist",
-        "main": "pkgs/core/src/index.ts",
-        "tsConfig": "pkgs/core/tsconfig.lib.json",
-        "assets": ["pkgs/core/*.md"]
-      }
-    },
-    "lint": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["sqruff --config=../../.sqruff lint --parsing-errors"],
-        "inputs": ["{projectRoot}/**/*.sql", "{workspaceRoot}/.sqruff"],
-        "parallel": false
-      }
-    },
-    "fix-sql": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": [
-          "sqruff --config=../../.sqruff fix --force --parsing-errors"
-        ],
-        "inputs": ["{projectRoot}/**/*.sql", "{workspaceRoot}/.sqruff"],
-        "parallel": false
-      }
-    },
-    "supabase:ensure-started": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": [
-          "supabase status || (echo \"Starting Supabase...\" && supabase start)"
-        ],
-        "parallel": false
-      }
-    },
-    "supabase:start": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["supabase start"],
-        "parallel": false
-      }
-    },
-    "supabase:stop": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["supabase stop --no-backup"],
-        "parallel": false
-      }
-    },
-    "supabase:status": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["supabase status"],
-        "parallel": false
-      }
-    },
-    "supabase:restart": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["supabase stop --no-backup", "supabase start"],
-        "parallel": false
-      }
-    },
-    "supabase:reset": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["supabase db reset"],
-        "parallel": false
-      }
-    },
-    "test": {
-      "executor": "nx:noop",
-      "dependsOn": ["test:pgtap", "test:vitest"]
-    },
-    "test:pgtap": {
-      "executor": "nx:run-commands",
-      "dependsOn": ["supabase:ensure-started"],
-      "options": {
-        "cwd": "{projectRoot}",
-        "commands": ["scripts/run-test-with-colors"],
-        "parallel": false
-      }
-    },
-    "test:vitest": {
-      "executor": "@nx/vite:test",
-      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-      "options": {
-        "passWithNoTests": true,
-        "reportsDirectory": "{workspaceRoot}/coverage/{projectRoot}"
-      }
-    },
-    "test:pgtap:watch": {
-      "executor": "nx:run-commands",
-      "options": {
-        "cwd": "{projectRoot}",
-        "command": "scripts/watch-test"
-      },
-      "cache": false
-    },
-    "gen-types": {
-      "executor": "nx:run-commands",
-      "options": {
-        "command": "supabase gen types --local --schema pgflow --schema pgmq > src/database-types.ts",
-        "cwd": "{projectRoot}"
-      }
-    }
-  }
-}

package/prompts/architect.md

@@ -1,87 +0,0 @@
-# Architect Mode
-
-## Your Role
-You are a senior software architect with extensive experience designing scalable, maintainable systems. Your purpose is to thoroughly analyze requirements and design optimal solutions before any implementation begins. You must resist the urge to immediately write code and instead focus on comprehensive planning and architecture design.
-
-## Your Behavior Rules
-- You must thoroughly understand requirements before proposing solutions
-- You must reach 90% confidence in your understanding before suggesting implementation
-- You must identify and resolve ambiguities through targeted questions
-- You must document all assumptions clearly
-
-## Process You Must Follow
-
-### Phase 1: Requirements Analysis
-1. Carefully read all provided information about the project or feature
-2. Extract and list all functional requirements explicitly stated
-3. Identify implied requirements not directly stated
-4. Determine non-functional requirements including:
-   - Performance expectations
-   - Security requirements
-   - Scalability needs
-   - Maintenance considerations
-5. Ask clarifying questions about any ambiguous requirements
-6. Report your current understanding confidence (0-100%)
-
-### Phase 2: System Context Examination
-1. If an existing codebase is available:
-   - Request to examine directory structure
-   - Ask to review key files and components
-   - Identify integration points with the new feature
-2. Identify all external systems that will interact with this feature
-3. Define clear system boundaries and responsibilities
-4. If beneficial, create a high-level system context diagram
-5. Update your understanding confidence percentage
-
-### Phase 3: Architecture Design
-1. Propose 2-3 potential architecture patterns that could satisfy requirements
-2. For each pattern, explain:
-   - Why it's appropriate for these requirements
-   - Key advantages in this specific context
-   - Potential drawbacks or challenges
-3. Recommend the optimal architecture pattern with justification
-4. Define core components needed in the solution, with clear responsibilities for each
-5. Design all necessary interfaces between components
-6. If applicable, design database schema showing:
-   - Entities and their relationships
-   - Key fields and data types
-   - Indexing strategy
-7. Address cross-cutting concerns including:
-   - Authentication/authorization approach
-   - Error handling strategy
-   - Logging and monitoring
-   - Security considerations
-8. Update your understanding confidence percentage
-
-### Phase 4: Technical Specification
-1. Recommend specific technologies for implementation, with justification
-2. Break down implementation into distinct phases with dependencies
-3. Identify technical risks and propose mitigation strategies
-4. Create detailed component specifications including:
-   - API contracts
-   - Data formats
-   - State management
-   - Validation rules
-5. Define technical success criteria for the implementation
-6. Update your understanding confidence percentage
-
-### Phase 5: Transition Decision
-1. Summarize your architectural recommendation concisely
-2. Present implementation roadmap with phases
-3. State your final confidence level in the solution
-4. If confidence ≥ 90%:
-   - State: "I'm ready to build! Switch to Agent mode and tell me to continue."
-5. If confidence < 90%:
-   - List specific areas requiring clarification
-   - Ask targeted questions to resolve remaining uncertainties
-   - State: "I need additional information before we start coding."
-
-## Response Format
-Always structure your responses in this order:
-1. Current phase you're working on
-2. Findings or deliverables for that phase
-3. Current confidence percentage
-4. Questions to resolve ambiguities (if any)
-5. Next steps
-
-Remember: Your primary value is in thorough design that prevents costly implementation mistakes. Take the time to design correctly before suggesting to use Agent mode.

package/prompts/condition.md

@@ -1,33 +0,0 @@
-# Conditional Steps in the Flow DSL
-
-Conditional steps allow steps to run only when certain criteria are met based on the incoming payload. Instead of always executing as soon as their dependencies complete, these steps check the provided condition against the input data.
-
-## How It Works
-
-- **Definition**: A condition is supplied as a JSON fragment via the step options (for example, using `runIf` or `runUnless`).
-- **Evaluation**: At runtime, the system evaluates the condition by comparing the step's combined inputs against the JSON fragment.
-- **Mechanism**: Under the hood, the payload is matched against the condition using a JSON containment operator (`@>`), commonly available in PostgreSQL. This operator checks if the input JSON "contains" the condition JSON structure.
-- **Outcome**:
-  - If the condition is met (for `runIf`) or not met (for `runUnless`), the step is executed.
-  - If the condition fails, the step is marked as skipped, and its downstream dependent steps are not executed (or are similarly marked as skipped).
-
-This design helps ensure that unnecessary processing is avoided when prerequisites are not satisfied.
-
-## Type safety
-
-Options object can be strictly type-safe and only allow values that are available in the payload,
-so it is impossible to define invalid condition object.
-
-## Marking as skipped
-
-Skipped steps are not considered a failure but will propagate skipped status to all dependent steps and
-they will not run.
-
-This way we can achieve a kinda robust low level branching logic - users can define branches
-by creating steps with mutually-exclusive conditions, so only one branch will be executed:
-
-```ts
-const ScrapeWebsiteFlow = new Flow<{ input: true }>()
-  .step({ slug: 'run_if_true', runIf: { run: { input: true } } }, handler)
-  .step({ slug: 'run_if_false', runUnless: { run: { input: true } } }, handler);
-```

package/prompts/declarative_sql.md

@@ -1,15 +0,0 @@
-### Declarative vs procedural
-
-**YOU MUST ALWAYS PRIORITIZE DECLARATIVE STYLE** and prioritize Batching operations.
-
-Avoid plpgsql as much as you can.
-It is important to have your DB procedures run in batched ways and use declarative rather than procedural constructs where possible:
-
-- do not ever use `language plplsql` in functions, always use `language sql`
-- don't do loops, do SQL statements that address multiple rows at once.
-- don't write trigger functions that fire for a single row, use `FOR EACH STATEMENT` instead.
-- don't call functions for each row in a result set, a condition, a join, or whatever; instead use functions that return `SETOF` and join against these.
-
-If you're constructing dynamic SQL, you should only ever use `%I` and `%L` when using `FORMAT` or similar; you should never see `%s` (with the very rare exception of where you're merging in another SQL fragment that you've previously formatted using %I and %L).
-
-Remember, that functions have significant overhead in Postgres - instead of factoring into lots of tiny functions, think about how to make your code more expressive so there's no need.

package/prompts/deps_in_payloads.md

@@ -1,20 +0,0 @@
-currently the 'input' jsonb that we are building contains only the 'run' input
-
-we really want to have this jsonb to contain all the deps outputs
-by dep output i mean a step_tasks.output value that corresponds to step_states row that is a dependency of the given updated_step_tasks (via step_states->steps)
-the step_slug of a given dependency should be used as key and its output as value in the input jsonb
-
-so, if a given updated_step_task belongs to step_state, that have 2 dependencies:
-
-step_slug=dep_a output=123
-step_slug=dep_b output=456
-
-we would like the final 'input' jsonb to look like this:
-
-{
-  "run": r.input,
-  "dep_a": dep_a_step_task.output,
-  "dep_b": dep_b_step_task.output
-}
-
-write appropriate joins and augment this code with this requirements

package/prompts/dsl-multi-arg.ts

@@ -1,48 +0,0 @@
-const ScrapeWebsiteFlow = new Flow<Input>()
-  .step('verify_status', async (payload) => {
-    // Placeholder function
-    return { status: 'success' };
-  })
-  .step(
-    'when_success',
-    ['verify_status'],
-    async (payload) => {
-      // Placeholder function
-      return await scrapeSubpages(
-        payload.run.url,
-        payload.table_of_contents.urls_of_subpages
-      );
-    },
-    { runIf: { verify_status: { status: 'success' } } }
-  )
-  .step(
-    'when_server_error',
-    ['verify_status'],
-    async (payload) => {
-      // Placeholder function
-      return await generateSummaries(payload.subpages.contentsOfSubpages);
-    },
-    { runUnless: { verify_status: { status: 'success' } } }
-  )
-
-  .step(
-    'sentiments',
-    ['subpages'],
-    async (payload) => {
-      // Placeholder function
-      return await analyzeSentiments(payload.subpages.contentsOfSubpages);
-    },
-    { maxAttempts: 5, baseDelay: 10 }
-  )
-  .step(
-    'save_to_db',
-    ['subpages', 'summaries', 'sentiments'],
-    async (payload) => {
-      // Placeholder function
-      return await saveToDb(
-        payload.subpages,
-        payload.summaries,
-        payload.sentiments
-      );
-    }
-  );

package/prompts/dsl-options.md

@@ -1,39 +0,0 @@
-# Flow DSL with options
-
-The idea is to add 4th argument to the `.step` method which will be an object
-for the step options:
-
-```ts
-{
-  runIf: Json;
-  runUnless: Json;
-  maxAttempts: number;
-  baseDelay: number;
-}
-```
-
-## Full flow example
-
-```ts
-const ScrapeWebsiteFlow = new Flow<Input>()
-  .step('verify_status', async (payload) => {
-    // Placeholder function
-    return { status: 'success' }
-  })
-  .step('when_success', ['verify_status'], async (payload) => {
-    // Placeholder function
-    return await scrapeSubpages(payload.run.url, payload.table_of_contents.urls_of_subpages);
-  }, { runIf: { status: 'success' } })
-  .step('when_server_error', ['verify_status'], async (payload) => {
-    // Placeholder function
-    return await generateSummaries(payload.subpages.contentsOfSubpages);
-  }, { runUnless: { status: 'success' } })
-  .step('sentiments', ['subpages'], async (payload) => {
-    // Placeholder function
-    return await analyzeSentiments(payload.subpages.contentsOfSubpages);
-  }, { maxAttempts: 5, baseDelay: 10 })
-  .step('save_to_db', ['subpages', 'summaries', 'sentiments'], async (payload) => {
-    // Placeholder function
-    return await saveToDb(payload.subpages, payload.summaries, payload.sentiments);
-  });
-```

package/prompts/dsl-single-arg.ts

@@ -1,51 +0,0 @@
-const ScrapeWebsiteFlow = new Flow<Input>()
-  .step({
-    id: 'verify_status',
-    handler: async (payload) => {
-      // Placeholder function
-      return { status: 'success' };
-    },
-  })
-  .step({
-    id: 'when_success',
-    deps: ['verify_status'],
-    runIf: { verify_status: { status: 'success' } },
-    async handler(payload) {
-      // Placeholder function
-      return await scrapeSubpages(
-        payload.run.url,
-        payload.table_of_contents.urls_of_subpages
-      );
-    }
-  })
-  .step({
-    id: 'when_server_error',
-    deps: ['verify_status'],
-    runUnless: { verify_status: { status: 'success' } },
-    async handler(payload) {
-      // Placeholder function
-      return await generateSummaries(payload.subpages.contentsOfSubpages);
-    }
-  })
-  .step({
-    id: 'sentiments',
-    deps: ['subpages'],
-    async handler(payload) {
-      // Placeholder function
-      return await analyzeSentiments(payload.subpages.contentsOfSubpages);
-    },
-    maxAttempts: 5,
-    baseDelay: 10
-  })
-  .step({
-    id: 'save_to_db',
-    deps: ['subpages', 'summaries', 'sentiments'],
-    async handler(payload) {
-      // Placeholder function
-      return await saveToDb(
-        payload.subpages,
-        payload.summaries,
-        payload.sentiments
-      );
-    },
-  });