@pgflow/core 0.0.5-prealpha.2 → 0.0.5

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

@@ -0,0 +1,46 @@
+<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

@@ -0,0 +1,152 @@
+// ../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

@@ -0,0 +1,11 @@
+# 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/).