workflais 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# workflais
+
+Declarative workflow primitives for [Cloudflare Workflows](https://developers.cloudflare.com/workflows/).
+
+```
+npm install workflais
+```
+
+## Native CF Workflows vs workflais
+
+| | Native CF Workflows | workflais |
+|---|---|---|
+| **Step definition** | `step.do("name", { retries: { limit: 3, delay: "10s", backoff: "exponential" }, timeout: "30s" }, async () => {...})` | `step("name", fn).retry(3).timeout("30s")` |
+| **Result chaining** | Manual variables between steps | Automatic `ctx.prev` pipeline |
+| **Saga compensation** | Manual implementation | `.compensate(fn)` with automatic LIFO rollback via `step.do("⟲ name")` |
+| **Parallel execution** | Manual self-spawn + waitForEvent orchestration | `parallel(step1, step2, step3)` |
+| **waitForEvent** | Imperative `step.waitForEvent()` call | `waitForEvent("name", opts)` in pipeline with `ctx.prev` |
+| **Compile-time validation** | Runtime errors only | Duplicate step names, step count limits, timeout limits, event type validation |
+| **Error types** | Generic errors | `NonRetryableError`, `TimeoutTooLongError`, `DuplicateStepNameError`, etc. |
+
+## Quick Start
+
+```typescript
+import { step, compile, execute } from "workflais";
+import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from "cloudflare:workers";
+import type { WorkflowStep as WfStep, WorkflowEvent as WfEvent } from "workflais";
+
+export class MyWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, cfStep: WorkflowStep) {
+    const plan = compile([
+      step("fetch-data", async (ctx) => {
+        return { userId: ctx.event.payload.userId, name: "Alice" };
+      }),
+
+      step("process", async (ctx) => {
+        const data = ctx.prev; // automatic chaining
+        return { ...data, processed: true };
+      })
+        .retry(3, "1 minute")
+        .timeout("30 seconds"),
+
+      step("save", async (ctx) => {
+        return { ...ctx.prev, saved: true };
+      }).compensate(async () => {
+        // runs automatically on failure, wrapped in step.do for CF durability
+      }),
+    ]);
+
+    return execute(plan, cfStep as unknown as WfStep, event as unknown as WfEvent, this.env);
+  }
+}
+```
+
+## API
+
+### DSL
+
+```typescript
+step(name, fn)                    // durable step
+  .retry(limit, delay?)           // retry config (default: exponential backoff)
+  .timeout(duration)              // step timeout (max 30 min)
+  .compensate(fn)                 // saga rollback handler
+
+parallel(step1, step2, ...)       // fan-out/fan-in execution
+waitForEvent(name, { type, timeout })  // pause for external event
+
+compile(nodes)                    // validate + build execution plan
+execute(plan, step, event, env)   // run against CF Workflows runtime
+```
+
+### Context
+
+Every step callback receives `ctx`:
+- `ctx.prev` — previous step's return value (or `undefined` for the first step)
+- `ctx.event` — workflow event (frozen, immutable)
+- `ctx.env` — CF bindings
+
+After `parallel()`, `ctx.prev` is a tuple of results in declaration order.
+
+## Examples
+
+Each example is a deployable CF Workers project with `wrangler.toml`:
+
+| Example | Pattern | Features |
+|---|---|---|
+| [`ecommerce-checkout`](examples/ecommerce-checkout/) | Cart → Payment → Invoice | Linear pipeline, retry, timeout |
+| [`user-onboarding`](examples/user-onboarding/) | Account → Billing → Welcome | Saga compensation, LIFO rollback |
+| [`image-tagging`](examples/image-tagging/) | Store → Approve → Tag → Save | Human-in-the-loop, waitForEvent |
+| [`parallel-fan-out`](examples/parallel-fan-out/) | Validate → [Email, SMS, CRM] → Log | Parallel fan-out/fan-in |
+
+```bash
+cd examples/ecommerce-checkout
+npm install workflais
+npx wrangler deploy
+```
+
+## Why Child Workflows? The Resource Isolation Problem
+
+CF Workflows runs each instance inside a single Durable Object. A DO has hard limits:
+
+| Resource | Limit |
+|---|---|
+| Memory | 128 MB per DO |
+| CPU | 5 min per invocation |
+| Retry budget | Shared across the entire instance |
+
+If you run three heavy steps with `Promise.all` inside one DO, you get:
+
+```
+┌─ Single Durable Object (128 MB shared) ──────────────┐
+│  Promise.all([                                        │
+│    mlInference(),    ← 80 MB   ← 3 min CPU           │
+│    imageProcess(),   ← 60 MB   ← 2 min CPU           │
+│    videoTranscode(), ← 50 MB   ← 4 min CPU           │
+│  ])                                                   │
+│  Total: 190 MB → OOM CRASH                            │
+│  Total CPU: 9 min → TIMEOUT                           │
+│  If imageProcess fails → all three die                │
+└───────────────────────────────────────────────────────┘
+```
+
+**The problem is threefold:**
+
+1. **Memory** — All branches share 128 MB. Two 80 MB allocations = OOM crash, killing the entire workflow.
+2. **CPU** — All branches share 5 min. Three 2-minute tasks = timeout, even though each one is well under the limit.
+3. **Blast radius** — One branch throwing an unhandled error kills `Promise.all`, terminating siblings mid-execution. No partial results, no independent retry.
+
+### The Solution: Child Workflow Spawning
+
+`parallel()` compiles to the self-spawn pattern — each branch becomes a **separate workflow instance** running in its **own DO**:
+
+```
+Parent DO                          Child DO #1           Child DO #2           Child DO #3
+──────────                        ───────────           ───────────           ───────────
+step.do("⊕ spawn") ─────────►   128 MB own memory     128 MB own memory     128 MB own memory
+  binding.create(child1)          5 min own CPU         5 min own CPU         5 min own CPU
+  binding.create(child2)          own retry budget      own retry budget      own retry budget
+  binding.create(child3)
+                                  step.do("ml", fn)     step.do("img", fn)    step.do("vid", fn)
+waitForEvent("ml:cb")  ◄─ $0 ─  sendEvent(result)
+waitForEvent("img:cb") ◄─ $0 ─                        sendEvent(result)
+waitForEvent("vid:cb") ◄─ $0 ─                                              sendEvent(result)
+
+ctx.prev = [mlResult, imgResult, vidResult]  // tuple in declaration order
+```
+
+| | `Promise.all` (single DO) | `parallel()` (child DOs) |
+|---|---|---|
+| Memory | 128 MB shared | 128 MB **each** |
+| CPU | 5 min shared | 5 min **each** |
+| Retry | All-or-nothing | Per-branch |
+| Failure | One kills all | Isolated |
+| Parent cost while waiting | N/A | **$0** (hibernated) |
+
+```typescript
+// workflais — each branch gets its own DO
+parallel(
+  step("ml-inference", mlFn).retry(5, "exponential").timeout("25m"),
+  step("image-process", imgFn).retry(3).timeout("10m"),
+  step("video-transcode", vidFn).retry(2).timeout("20m"),
+)
+```
+
+The parent spawns all children in a single `step.do`, then **hibernates** via `waitForEvent`. Zero CPU, zero memory, zero cost. When all children report back, the parent wakes up with `ctx.prev = [result1, result2, result3]`.
+
+If any branch fails after the parallel group completes, workflais runs `.compensate()` for **every** child in the group — each compensation wrapped in its own `step.do` for CF-durable retry.
+
+## How It Works
+
+```
+step("a", fn).retry(3)  →  compile([...])  →  execute(plan, cfStep, event, env)
+     DSL                     Validation          CF step.do() / waitForEvent()
+```
+
+1. **DSL** — Declarative step definitions with chainable config
+2. **Compiler** — Validates names, limits, timeouts; builds execution plan
+3. **Runtime** — Translates plan into CF Workflows API calls with saga compensation

package/dist/compiler.d.ts

@@ -0,0 +1,12 @@
+import type { FlowNode, ExecutionPlan } from "./types.js";
+/**
+ * Compiles a flat array of FlowNodes into an ExecutionPlan.
+ *
+ * Responsibilities:
+ * 1. Level assignment — sequential vs parallel grouping
+ * 2. Duplicate step name detection (CF cache-key collision prevention)
+ * 3. Step name validation (length, emptiness)
+ * 4. Step count limit check (CF max 1024)
+ */
+export declare function compile(nodes: FlowNode[]): ExecutionPlan;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAER,aAAa,EAKd,MAAM,YAAY,CAAC;AAmBpB;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,aAAa,CAoExD"}

package/dist/compiler.js

@@ -0,0 +1,177 @@
+import { DuplicateStepNameError, StepNameTooLongError, EmptyStepNameError, StepLimitExceededError, TimeoutTooLongError, InvalidEventTypeError, } from "./types.js";
+import { toStepNode } from "./dsl.js";
+const MAX_STEP_NAME_LENGTH = 256;
+const MAX_STEPS_PER_WORKFLOW = 1024;
+const MAX_TIMEOUT_MINUTES = 30;
+// Parallel overhead: 1 spawn step + N waitForEvent steps
+const PARALLEL_OVERHEAD_STEPS = 1; // spawn step; waitForEvent per child added separately
+/**
+ * Compiles a flat array of FlowNodes into an ExecutionPlan.
+ *
+ * Responsibilities:
+ * 1. Level assignment — sequential vs parallel grouping
+ * 2. Duplicate step name detection (CF cache-key collision prevention)
+ * 3. Step name validation (length, emptiness)
+ * 4. Step count limit check (CF max 1024)
+ */
+export function compile(nodes) {
+    // Collect all step names for duplicate detection
+    const namePositions = new Map();
+    const allSteps = [];
+    let flatIndex = 0;
+    for (const node of nodes) {
+        if (node.type === "step") {
+            const stepNode = isChainable(node) ? toStepNode(node) : node;
+            validateStepName(stepNode.name);
+            checkDuplicate(stepNode.name, flatIndex, namePositions);
+            if (stepNode.timeoutConfig) {
+                validateTimeout(stepNode.timeoutConfig);
+            }
+            allSteps.push(stepNode);
+            flatIndex++;
+        }
+        else if (node.type === "parallel") {
+            for (const child of node.children) {
+                validateStepName(child.name);
+                checkDuplicate(child.name, flatIndex, namePositions);
+                if (child.timeoutConfig) {
+                    validateTimeout(child.timeoutConfig);
+                }
+                allSteps.push(child);
+                flatIndex++;
+            }
+        }
+        else if (node.type === "waitForEvent") {
+            validateStepName(node.name);
+            checkDuplicate(node.name, flatIndex, namePositions);
+            validateEventType(node.eventType);
+            flatIndex++;
+        }
+    }
+    // Build levels
+    const levels = [];
+    for (const node of nodes) {
+        if (node.type === "step") {
+            const stepNode = isChainable(node) ? toStepNode(node) : node;
+            const level = {
+                type: "sequential",
+                node: stepNode,
+            };
+            levels.push(level);
+        }
+        else if (node.type === "parallel") {
+            const level = {
+                type: "parallel",
+                nodes: node.children,
+            };
+            levels.push(level);
+        }
+        else if (node.type === "waitForEvent") {
+            const level = {
+                type: "waitForEvent",
+                node,
+            };
+            levels.push(level);
+        }
+    }
+    // Calculate total CF step count
+    const stepCount = calculateStepCount(levels);
+    if (stepCount > MAX_STEPS_PER_WORKFLOW) {
+        throw new StepLimitExceededError(stepCount);
+    }
+    return { levels, stepCount };
+}
+function validateStepName(name) {
+    if (name === "") {
+        throw new EmptyStepNameError();
+    }
+    if (name.length > MAX_STEP_NAME_LENGTH) {
+        throw new StepNameTooLongError(name, name.length);
+    }
+}
+function checkDuplicate(name, index, namePositions) {
+    const existing = namePositions.get(name);
+    if (existing !== undefined) {
+        throw new DuplicateStepNameError(name, [existing, index]);
+    }
+    namePositions.set(name, index);
+}
+/**
+ * Calculates total CF step count including parallel overhead.
+ *
+ * Sequential level: 1 CF step
+ * Parallel level with N children: N children + 1 spawn + N waitForEvent = 2N + 1
+ *
+ * But since children run in separate workflows, they don't count
+ * against the PARENT's 1024 limit. The parent uses:
+ * - 1 spawn step.do
+ * - N waitForEvent calls
+ *
+ * We count conservatively: parent steps + child steps
+ * (each child is 1 step in its own workflow)
+ */
+function calculateStepCount(levels) {
+    let count = 0;
+    for (const level of levels) {
+        if (level.type === "sequential") {
+            count += 1;
+        }
+        else if (level.type === "parallel") {
+            // Parallel: 1 spawn + N waitForEvents + N children (counted for total)
+            const n = level.nodes.length;
+            count += PARALLEL_OVERHEAD_STEPS + n + n; // spawn + waits + children
+        }
+        else if (level.type === "waitForEvent") {
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * Parses a CF duration string (e.g., "5m", "30 minutes", "1 hour") to minutes.
+ * Returns undefined if format is unrecognized.
+ */
+function parseDurationToMinutes(duration) {
+    const trimmed = duration.trim().toLowerCase();
+    // Pattern: "30m", "5m", "1h"
+    const shortMatch = trimmed.match(/^(\d+(?:\.\d+)?)\s*(s|m|h)$/);
+    if (shortMatch) {
+        const value = parseFloat(shortMatch[1]);
+        const unit = shortMatch[2];
+        if (unit === "s")
+            return value / 60;
+        if (unit === "m")
+            return value;
+        if (unit === "h")
+            return value * 60;
+    }
+    // Pattern: "30 minutes", "1 hour", "5 seconds"
+    const longMatch = trimmed.match(/^(\d+(?:\.\d+)?)\s*(seconds?|minutes?|hours?)$/);
+    if (longMatch) {
+        const value = parseFloat(longMatch[1]);
+        const unit = longMatch[2];
+        if (unit.startsWith("second"))
+            return value / 60;
+        if (unit.startsWith("minute"))
+            return value;
+        if (unit.startsWith("hour"))
+            return value * 60;
+    }
+    return undefined;
+}
+const EVENT_TYPE_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function validateEventType(type) {
+    if (!EVENT_TYPE_PATTERN.test(type)) {
+        throw new InvalidEventTypeError(type);
+    }
+}
+function validateTimeout(duration) {
+    const minutes = parseDurationToMinutes(duration);
+    if (minutes !== undefined && minutes > MAX_TIMEOUT_MINUTES) {
+        throw new TimeoutTooLongError(duration);
+    }
+}
+function isChainable(node) {
+    return node.type === "step" && typeof node.retry === "function";
+}
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,16 @@
+import type { StepContext, WorkflowEvent } from "./types.js";
+/**
+ * Creates a StepContext for step execution.
+ *
+ * CF Workflows rules enforced:
+ * - event is frozen/immutable (changes NOT persisted across steps)
+ * - prev carries the return value of the previous step
+ * - env provides access to CF bindings
+ */
+export declare function createStepContext<TPrev = unknown>(prev: TPrev, event: WorkflowEvent, env: Record<string, unknown>): StepContext<TPrev>;
+/**
+ * Assembles parallel results into a tuple (array in declaration order).
+ * Used after all parallel children complete to form ctx.prev for the next step.
+ */
+export declare function propagateResult(results: unknown[]): unknown[];
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAC/C,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,WAAW,CAAC,KAAK,CAAC,CAMpB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAE7D"}

package/dist/context.js

@@ -0,0 +1,23 @@
+/**
+ * Creates a StepContext for step execution.
+ *
+ * CF Workflows rules enforced:
+ * - event is frozen/immutable (changes NOT persisted across steps)
+ * - prev carries the return value of the previous step
+ * - env provides access to CF bindings
+ */
+export function createStepContext(prev, event, env) {
+    return {
+        prev,
+        event,
+        env,
+    };
+}
+/**
+ * Assembles parallel results into a tuple (array in declaration order).
+ * Used after all parallel children complete to form ctx.prev for the next step.
+ */
+export function propagateResult(results) {
+    return [...results];
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAW,EACX,KAAoB,EACpB,GAA4B;IAE5B,OAAO;QACL,IAAI;QACJ,KAAK;QACL,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAkB;IAChD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC"}

package/dist/dsl.d.ts

@@ -0,0 +1,21 @@
+import { type StepNode, type ParallelNode, type WaitEventNode, type FlowNode, type StepFn, type CompensateFn, type WorkflowBackoff, type ErrorHandler, type WorkflowDefinition, type WorkflowEvent, type WorkflowStep } from "./types.js";
+export interface ChainableStep extends StepNode {
+    retry(limit: number, backoff?: WorkflowBackoff | string): ChainableStep;
+    compensate(fn: CompensateFn): ChainableStep;
+    timeout(duration: string): ChainableStep;
+    schema(input?: unknown, output?: unknown): ChainableStep;
+}
+/** Extract plain StepNode data from a ChainableStep (strip methods) */
+export declare function toStepNode(s: ChainableStep): StepNode;
+export declare function step(name: string, fn: StepFn): ChainableStep;
+export declare function parallel(...steps: ChainableStep[]): ParallelNode;
+export declare function waitForEvent(name: string, options: {
+    type: string;
+    timeout: string;
+}): WaitEventNode;
+export interface ChainableWorkflow extends WorkflowDefinition {
+    run(event: WorkflowEvent, step: WorkflowStep): Promise<unknown>;
+    onError(handler: ErrorHandler): ChainableWorkflow;
+}
+export declare function workflow(...nodes: FlowNode[]): ChainableWorkflow;
+//# sourceMappingURL=dsl.d.ts.map

package/dist/dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,YAAY,EAGjB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,aAAc,SAAQ,QAAQ;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,aAAa,CAAC;IACxE,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC;IAC5C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC;IACzC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;CAC1D;AA6DD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,QAAQ,CAUrD;AAID,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAU5D;AAED,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,YAAY,CAKhE;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,aAAa,CAOf;AAID,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,iBAAiB,CAAC;CACnD;AAED,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CAMhE"}

package/dist/dsl.js

@@ -0,0 +1,107 @@
+import { EmptyWorkflowError, } from "./types.js";
+function createChainableStep(data) {
+    const chainable = {
+        // Data properties
+        type: data.type,
+        name: data.name,
+        fn: data.fn,
+        retryConfig: data.retryConfig,
+        compensateFn: data.compensateFn,
+        timeoutConfig: data.timeoutConfig,
+        schemaConfig: data.schemaConfig,
+        // Chainable methods — each returns a NEW ChainableStep
+        retry(limit, backoff) {
+            let retry;
+            if (backoff === undefined ||
+                backoff === "exponential" ||
+                backoff === "linear" ||
+                backoff === "constant") {
+                // CF requires delay when retries is provided — default to 10 seconds
+                retry = {
+                    limit,
+                    delay: "10 seconds",
+                    backoff: (backoff ?? "exponential"),
+                };
+            }
+            else {
+                // String duration like "2s" → constant backoff with fixed delay
+                retry = {
+                    limit,
+                    delay: backoff,
+                    backoff: "constant",
+                };
+            }
+            return createChainableStep({ ...toStepNode(chainable), retryConfig: retry });
+        },
+        compensate(fn) {
+            return createChainableStep({ ...toStepNode(chainable), compensateFn: fn });
+        },
+        timeout(duration) {
+            return createChainableStep({ ...toStepNode(chainable), timeoutConfig: duration });
+        },
+        schema(input, output) {
+            const schema = { input, output };
+            return createChainableStep({ ...toStepNode(chainable), schemaConfig: schema });
+        },
+    };
+    return chainable;
+}
+/** Extract plain StepNode data from a ChainableStep (strip methods) */
+export function toStepNode(s) {
+    return {
+        type: s.type,
+        name: s.name,
+        fn: s.fn,
+        retryConfig: s.retryConfig,
+        compensateFn: s.compensateFn,
+        timeoutConfig: s.timeoutConfig,
+        schemaConfig: s.schemaConfig,
+    };
+}
+// ─── Public DSL API ──────────────────────────────────────────────────────────
+export function step(name, fn) {
+    return createChainableStep({
+        type: "step",
+        name,
+        fn,
+        retryConfig: null,
+        compensateFn: null,
+        timeoutConfig: null,
+        schemaConfig: null,
+    });
+}
+export function parallel(...steps) {
+    return {
+        type: "parallel",
+        children: steps.map((s) => toStepNode(s)),
+    };
+}
+export function waitForEvent(name, options) {
+    return {
+        type: "waitForEvent",
+        name,
+        eventType: options.type,
+        timeout: options.timeout,
+    };
+}
+export function workflow(...nodes) {
+    if (nodes.length === 0) {
+        throw new EmptyWorkflowError();
+    }
+    return createChainableWorkflow(nodes, null);
+}
+function createChainableWorkflow(nodes, errorHandler) {
+    const definition = {
+        nodes,
+        errorHandler,
+        async run(_event, _step) {
+            // Runtime engine will handle this — placeholder for now
+            return undefined;
+        },
+        onError(handler) {
+            return createChainableWorkflow([...nodes], handler);
+        },
+    };
+    return definition;
+}
+//# sourceMappingURL=dsl.js.map

package/dist/dsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { step, parallel, workflow, toStepNode, waitForEvent } from "./dsl.js";
+export { compile } from "./compiler.js";
+export { execute } from "./runtime.js";
+export { createStepContext, propagateResult } from "./context.js";
+export { createCompensationStack } from "./saga.js";
+export type { StepNode, ParallelNode, WaitEventNode, FlowNode, StepFn, CompensateFn, RetryConfig, SchemaConfig, WorkflowBackoff, WorkflowStepConfig, WorkflowEvent, WorkflowStep, WorkflowInstance, InstanceStatus, WorkflowBinding, WorkflowInstanceCreateOptions, ExecutionPlan, Level, SequentialLevel, ParallelLevel, WaitEventLevel, StepContext, CompletedStep, ErrorHandler, WorkflowDefinition, ChildPayload, } from "./types.js";
+export { isChildPayload } from "./types.js";
+export { DuplicateStepNameError, StepNameTooLongError, InvalidEventTypeError, EmptyWorkflowError, StepLimitExceededError, CircularDependencyError, EmptyStepNameError, NonRetryableError, TimeoutTooLongError, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,6BAA6B,EAC7B,aAAa,EACb,KAAK,EACL,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { step, parallel, workflow, toStepNode, waitForEvent } from "./dsl.js";
+export { compile } from "./compiler.js";
+export { execute } from "./runtime.js";
+export { createStepContext, propagateResult } from "./context.js";
+export { createCompensationStack } from "./saga.js";
+export { isChildPayload } from "./types.js";
+export { DuplicateStepNameError, StepNameTooLongError, InvalidEventTypeError, EmptyWorkflowError, StepLimitExceededError, CircularDependencyError, EmptyStepNameError, NonRetryableError, TimeoutTooLongError, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AA+BpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,24 @@
+import type { ExecutionPlan, WorkflowEvent, WorkflowStep, ErrorHandler } from "./types.js";
+export interface ExecuteOptions {
+    onError?: ErrorHandler;
+    /** Workflow binding name in env (default: "WORKFLOW") */
+    bindingName?: string;
+}
+/**
+ * Executes an ExecutionPlan by translating it into CF Workflows API calls.
+ *
+ * Two modes:
+ * 1. **Parent mode** (default): Iterates levels sequentially.
+ *    - Sequential: calls step.do
+ *    - Parallel: spawns child workflows (separate DOs), hibernates with waitForEvent
+ *    - WaitForEvent: calls step.waitForEvent
+ *
+ * 2. **Child mode** (detected via `__workflais` in event.payload):
+ *    Runs a single step from the plan, then sends result back to parent via sendEvent.
+ *    Each child runs in its own DO — isolated 128MB memory, separate CPU budget,
+ *    per-branch retry, isolated failure. Parent pays $0 while hibernated.
+ *
+ * Maintains a compensation stack for saga rollback on failure.
+ */
+export declare function execute(plan: ExecutionPlan, cfStep: WorkflowStep, event: WorkflowEvent, env: Record<string, unknown>, options?: ExecuteOptions): Promise<unknown>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAGb,aAAa,EACb,YAAY,EAGZ,YAAY,EACb,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC,CAQlB"}

package/dist/runtime.js

@@ -0,0 +1,222 @@
+import { isChildPayload } from "./types.js";
+import { createStepContext } from "./context.js";
+import { createCompensationStack } from "./saga.js";
+/**
+ * Executes an ExecutionPlan by translating it into CF Workflows API calls.
+ *
+ * Two modes:
+ * 1. **Parent mode** (default): Iterates levels sequentially.
+ *    - Sequential: calls step.do
+ *    - Parallel: spawns child workflows (separate DOs), hibernates with waitForEvent
+ *    - WaitForEvent: calls step.waitForEvent
+ *
+ * 2. **Child mode** (detected via `__workflais` in event.payload):
+ *    Runs a single step from the plan, then sends result back to parent via sendEvent.
+ *    Each child runs in its own DO — isolated 128MB memory, separate CPU budget,
+ *    per-branch retry, isolated failure. Parent pays $0 while hibernated.
+ *
+ * Maintains a compensation stack for saga rollback on failure.
+ */
+export async function execute(plan, cfStep, event, env, options) {
+    // ─── Child mode: __workflais payload detected ────────────────────────
+    if (isChildPayload(event.payload)) {
+        return executeChildMode(plan, cfStep, event, env, options);
+    }
+    // ─── Parent mode: normal execution ───────────────────────────────────
+    return executeParentMode(plan, cfStep, event, env, options);
+}
+/**
+ * Child mode: runs a single step and sends result back to parent.
+ *
+ * Each child workflow instance runs in its own Durable Object:
+ * - 128 MB memory (not shared with parent)
+ * - Separate CPU budget
+ * - Per-branch retry (isolated from siblings)
+ * - Isolated failure blast radius
+ */
+async function executeChildMode(plan, cfStep, event, env, options) {
+    const childPayload = event.payload;
+    if (!isChildPayload(childPayload)) {
+        throw new Error("executeChildMode called without __workflais payload");
+    }
+    const { stepName, input, callbackId, parentInstanceId } = childPayload;
+    const bindingName = options?.bindingName ?? "WORKFLOW";
+    // Find the step in the plan
+    const stepNode = findStepInPlan(plan, stepName);
+    if (!stepNode) {
+        throw new Error(`Child workflow: step "${stepName}" not found in execution plan`);
+    }
+    // Create context with the input from parent as prev
+    const ctx = createStepContext(input, event, env);
+    const config = buildStepConfig(stepNode);
+    // Execute the single step
+    let result;
+    if (config) {
+        result = await cfStep.do(stepName, config, async () => {
+            return await stepNode.fn(ctx);
+        });
+    }
+    else {
+        result = await cfStep.do(stepName, async () => {
+            return await stepNode.fn(ctx);
+        });
+    }
+    // Send result back to parent via sendEvent
+    const binding = env[bindingName];
+    if (binding) {
+        const parentInstance = await binding.get(parentInstanceId);
+        await parentInstance.sendEvent({
+            type: callbackId,
+            payload: result,
+        });
+    }
+    return result;
+}
+async function executeParentMode(plan, cfStep, event, env, options) {
+    const compensationStack = createCompensationStack();
+    let prev = undefined;
+    try {
+        for (const level of plan.levels) {
+            if (level.type === "sequential") {
+                prev = await executeSequentialLevel(level.node, cfStep, event, env, prev, compensationStack);
+            }
+            else if (level.type === "parallel") {
+                prev = await executeParallelLevel(level.nodes, cfStep, event, env, prev, options);
+                // Push all parallel children onto compensation stack
+                for (const node of level.nodes) {
+                    compensationStack.push(node.name, node.compensateFn);
+                }
+            }
+            else if (level.type === "waitForEvent") {
+                prev = await cfStep.waitForEvent(level.node.name, {
+                    type: level.node.eventType,
+                    timeout: level.node.timeout,
+                });
+            }
+        }
+        return prev;
+    }
+    catch (error) {
+        // Call onError handler BEFORE compensation (per PRD spec)
+        if (options?.onError) {
+            const ctx = createStepContext(prev, event, env);
+            await options.onError(error, ctx);
+        }
+        // Run saga compensation
+        await compensationStack.compensate(cfStep, event, env);
+        // Re-throw original error
+        throw error;
+    }
+}
+async function executeSequentialLevel(node, cfStep, event, env, prev, compensationStack) {
+    const ctx = createStepContext(prev, event, env);
+    const config = buildStepConfig(node);
+    let result;
+    if (config) {
+        result = await cfStep.do(node.name, config, async () => {
+            return await node.fn(ctx);
+        });
+    }
+    else {
+        result = await cfStep.do(node.name, async () => {
+            return await node.fn(ctx);
+        });
+    }
+    // Push onto compensation stack after successful execution
+    compensationStack.push(node.name, node.compensateFn);
+    return result;
+}
+/**
+ * Parallel level execution via self-spawn pattern.
+ *
+ * 1. Parent spawns N child workflows via env.BINDING.create()
+ *    - Each child gets __workflais payload with stepName, input, callbackId
+ *    - Each child runs in its own DO (128MB, separate CPU, isolated retry)
+ *
+ * 2. Parent HIBERNATES via step.waitForEvent() for each child
+ *    - 0 CPU, 0 memory, $0 cost while waiting
+ *
+ * 3. Children send results back via env.BINDING.sendEvent()
+ *
+ * 4. Parent assembles results as tuple in declaration order
+ */
+async function executeParallelLevel(nodes, cfStep, event, env, prev, options) {
+    const childNames = nodes.map((n) => n.name);
+    const spawnStepName = `⊕ spawn:${childNames.join(",")}`;
+    const bindingName = options?.bindingName ?? "WORKFLOW";
+    const parentInstanceId = event.instanceId;
+    // Step 1: Spawn child workflows — each in its own DO
+    await cfStep.do(spawnStepName, async () => {
+        const binding = env[bindingName];
+        if (!binding) {
+            throw new Error(`Workflow binding "${bindingName}" not found in env. ` +
+                `Parallel execution requires the workflow's own binding. ` +
+                `Add it to wrangler.toml and pass bindingName in ExecuteOptions if not "WORKFLOW".`);
+        }
+        for (const node of nodes) {
+            await binding.create({
+                params: {
+                    __workflais: true,
+                    stepName: node.name,
+                    input: prev,
+                    callbackId: `${node.name}:callback`,
+                    parentInstanceId,
+                },
+            });
+        }
+    });
+    // Step 2: Parent HIBERNATES — $0 cost, 0 cpu, 0 mem
+    // waitForEvent releases the DO. Parent only wakes when child sends event.
+    const results = [];
+    for (const node of nodes) {
+        const callbackType = `${node.name}:callback`;
+        const result = await cfStep.waitForEvent(`wait:${node.name}`, { type: callbackType, timeout: "30 minutes" });
+        // Extract payload from the event envelope
+        const payload = result?.payload ?? result;
+        results.push(payload);
+    }
+    return results;
+}
+/**
+ * Finds a step node by name in the execution plan.
+ * Used by child mode to locate the step it should execute.
+ */
+function findStepInPlan(plan, stepName) {
+    for (const level of plan.levels) {
+        if (level.type === "sequential" && level.node.name === stepName) {
+            return level.node;
+        }
+        if (level.type === "parallel") {
+            const found = level.nodes.find((n) => n.name === stepName);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * Translates workflais retry/timeout config into CF WorkflowStepConfig.
+ * Returns undefined if no config is needed (cleaner CF API call).
+ */
+function buildStepConfig(node) {
+    const hasRetry = node.retryConfig !== null;
+    const hasTimeout = node.timeoutConfig !== null;
+    if (!hasRetry && !hasTimeout) {
+        return undefined;
+    }
+    const config = {};
+    if (hasRetry) {
+        config.retries = {
+            limit: node.retryConfig.limit,
+            delay: node.retryConfig.delay,
+            ...(node.retryConfig.backoff !== undefined && {
+                backoff: node.retryConfig.backoff,
+            }),
+        };
+    }
+    if (hasTimeout) {
+        config.timeout = node.timeoutConfig;
+    }
+    return config;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/saga.d.ts

@@ -0,0 +1,14 @@
+import type { CompensateFn, WorkflowEvent, WorkflowStep } from "./types.js";
+export interface CompensationStack {
+    push(name: string, compensateFn: CompensateFn | null): void;
+    size(): number;
+    isEmpty(): boolean;
+    /**
+     * Executes compensations in LIFO order.
+     * Each compensation is wrapped in step.do for CF durability.
+     * Steps without compensateFn are skipped.
+     */
+    compensate(cfStep: WorkflowStep, event: WorkflowEvent, env: Record<string, unknown>): Promise<void>;
+}
+export declare function createCompensationStack(): CompensationStack;
+//# sourceMappingURL=saga.d.ts.map

package/dist/saga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.d.ts","sourceRoot":"","sources":["../src/saga.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;IAC5D,IAAI,IAAI,MAAM,CAAC;IACf,OAAO,IAAI,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CACR,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAuC3D"}

package/dist/saga.js

@@ -0,0 +1,31 @@
+import { createStepContext } from "./context.js";
+export function createCompensationStack() {
+    const stack = [];
+    return {
+        push(name, compensateFn) {
+            stack.push({ name, compensateFn });
+        },
+        size() {
+            return stack.length;
+        },
+        isEmpty() {
+            return stack.length === 0;
+        },
+        async compensate(cfStep, event, env) {
+            // LIFO order — pop from the end
+            for (let i = stack.length - 1; i >= 0; i--) {
+                const { name, compensateFn } = stack[i];
+                if (compensateFn === null) {
+                    continue;
+                }
+                // Wrap in step.do for durable execution.
+                // CF Workflows will automatically retry failed compensations.
+                const ctx = createStepContext(undefined, event, env);
+                await cfStep.do(`⟲ ${name}`, async () => {
+                    await compensateFn(ctx);
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=saga.js.map

package/dist/saga.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.js","sourceRoot":"","sources":["../src/saga.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAkBjD,MAAM,UAAU,uBAAuB;IACrC,MAAM,KAAK,GAAoB,EAAE,CAAC;IAElC,OAAO;QACL,IAAI,CAAC,IAAY,EAAE,YAAiC;YAClD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QACrC,CAAC;QAED,IAAI;YACF,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAED,OAAO;YACL,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;QAC5B,CAAC;QAED,KAAK,CAAC,UAAU,CACd,MAAoB,EACpB,KAAoB,EACpB,GAA4B;YAE5B,gCAAgC;YAChC,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAExC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;oBAC1B,SAAS;gBACX,CAAC;gBAED,yCAAyC;gBACzC,8DAA8D;gBAC9D,MAAM,GAAG,GAAG,iBAAiB,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;gBAErD,MAAM,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE;oBACtC,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;gBAC1B,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+export type WorkflowBackoff = "constant" | "linear" | "exponential";
+export interface WorkflowStepConfig {
+    retries?: {
+        limit: number;
+        delay: string | number;
+        backoff?: WorkflowBackoff;
+    };
+    timeout?: string | number;
+}
+export interface WorkflowEvent<T = unknown> {
+    payload: Readonly<T>;
+    timestamp: Date;
+    instanceId: string;
+}
+export interface WorkflowStep {
+    do<T>(name: string, callback: () => Promise<T> | T): Promise<T>;
+    do<T>(name: string, config: WorkflowStepConfig, callback: () => Promise<T> | T): Promise<T>;
+    sleep(name: string, duration: string | number): Promise<void>;
+    sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+    waitForEvent<T = unknown>(name: string, options: {
+        type: string;
+        timeout: string;
+    }): Promise<T>;
+}
+export interface WorkflowInstance {
+    id: string;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    terminate(): Promise<void>;
+    restart(): Promise<void>;
+    status(): Promise<InstanceStatus>;
+    sendEvent(event: {
+        type: string;
+        payload?: unknown;
+    }): Promise<void>;
+}
+export interface InstanceStatus {
+    status: "queued" | "running" | "paused" | "errored" | "terminated" | "complete" | "waiting" | "waitingForPause" | "unknown";
+    error?: {
+        name: string;
+        message: string;
+    };
+    output?: unknown;
+}
+export interface WorkflowInstanceCreateOptions {
+    id?: string;
+    params?: unknown;
+}
+export interface WorkflowBinding {
+    create(options?: WorkflowInstanceCreateOptions): Promise<WorkflowInstance>;
+    createBatch(batch: WorkflowInstanceCreateOptions[]): Promise<WorkflowInstance[]>;
+    get(id: string): Promise<WorkflowInstance>;
+}
+export type StepFn<TIn = unknown, TOut = unknown> = (ctx: StepContext<TIn>) => Promise<TOut> | TOut;
+export type CompensateFn = (ctx: StepContext) => Promise<void> | void;
+export interface RetryConfig {
+    limit: number;
+    delay: string | number;
+    backoff?: WorkflowBackoff;
+}
+export interface SchemaConfig {
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Plain data structure representing a workflow step.
+ *
+ * Data property names (retryConfig, compensateFn, timeoutConfig, schemaConfig)
+ * are intentionally different from the chainable method names (retry, compensate,
+ * timeout, schema) to avoid JavaScript property conflicts.
+ */
+export interface StepNode {
+    readonly type: "step";
+    readonly name: string;
+    readonly fn: StepFn;
+    readonly retryConfig: RetryConfig | null;
+    readonly compensateFn: CompensateFn | null;
+    readonly timeoutConfig: string | null;
+    readonly schemaConfig: SchemaConfig | null;
+}
+export interface ParallelNode {
+    readonly type: "parallel";
+    readonly children: ReadonlyArray<StepNode>;
+}
+export interface WaitEventNode {
+    readonly type: "waitForEvent";
+    readonly name: string;
+    readonly eventType: string;
+    readonly timeout: string;
+}
+export type FlowNode = StepNode | ParallelNode | WaitEventNode;
+export interface SequentialLevel {
+    readonly type: "sequential";
+    readonly node: StepNode;
+}
+export interface ParallelLevel {
+    readonly type: "parallel";
+    readonly nodes: ReadonlyArray<StepNode>;
+}
+export interface WaitEventLevel {
+    readonly type: "waitForEvent";
+    readonly node: WaitEventNode;
+}
+export type Level = SequentialLevel | ParallelLevel | WaitEventLevel;
+export interface ExecutionPlan {
+    readonly levels: ReadonlyArray<Level>;
+    readonly stepCount: number;
+}
+export interface StepContext<TPrev = unknown> {
+    readonly prev: TPrev;
+    readonly event: WorkflowEvent;
+    readonly env: Record<string, unknown>;
+}
+export interface CompletedStep {
+    readonly name: string;
+    readonly compensateFn: CompensateFn | null;
+}
+export declare class DuplicateStepNameError extends Error {
+    readonly stepName: string;
+    readonly positions: [number, number];
+    constructor(stepName: string, positions: [number, number]);
+}
+export declare class StepNameTooLongError extends Error {
+    readonly stepName: string;
+    readonly length: number;
+    constructor(stepName: string, length: number);
+}
+export declare class InvalidEventTypeError extends Error {
+    readonly eventType: string;
+    constructor(eventType: string);
+}
+export declare class EmptyWorkflowError extends Error {
+    constructor();
+}
+export declare class StepLimitExceededError extends Error {
+    readonly count: number;
+    constructor(count: number);
+}
+export declare class CircularDependencyError extends Error {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+export declare class EmptyStepNameError extends Error {
+    constructor();
+}
+export declare class NonRetryableError extends Error {
+    constructor(message: string, name?: string);
+}
+export declare class TimeoutTooLongError extends Error {
+    readonly duration: string;
+    constructor(duration: string);
+}
+export interface ChildPayload {
+    readonly __workflais: true;
+    readonly stepName: string;
+    readonly input: unknown;
+    readonly callbackId: string;
+    readonly parentInstanceId: string;
+}
+export declare function isChildPayload(payload: unknown): payload is ChildPayload;
+export type ErrorHandler = (error: Error, ctx: StepContext) => Promise<void> | void;
+export interface WorkflowDefinition {
+    readonly nodes: ReadonlyArray<FlowNode>;
+    readonly errorHandler: ErrorHandler | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,eAAe,CAAC;KAC3B,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChE,EAAE,CAAC,CAAC,EACF,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,YAAY,CAAC,CAAC,GAAG,OAAO,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IAClC,SAAS,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EACF,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,SAAS,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,6BAA6B;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,OAAO,CAAC,EAAE,6BAA6B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3E,WAAW,CACT,KAAK,EAAE,6BAA6B,EAAE,GACrC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC5C;AAID,MAAM,MAAM,MAAM,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,IAAI,CAClD,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,KAClB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE1B,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEtE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;AAI/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,MAAM,KAAK,GAAG,eAAe,GAAG,aAAa,GAAG,cAAc,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAID,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5C;AAID,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAD3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;CAQ9C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAQjC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;aAClB,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAO9C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;;CAK5C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAO1C;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,KAAK,EAAE,MAAM,EAAE;gBAAf,KAAK,EAAE,MAAM,EAAE;CAO5C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;;CAO5C;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAI3C;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAO7C;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAMxE;AAID,MAAM,MAAM,YAAY,GAAG,CACzB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5C"}

package/dist/types.js

@@ -0,0 +1,86 @@
+// ─── CF Workflows Type Mirrors ───────────────────────────────────────────────
+// These mirror the actual CF types from 'cloudflare:workers' / 'cloudflare:workflows'
+// so we can work without installing the CF types package in dev.
+// ─── Error Types ─────────────────────────────────────────────────────────────
+export class DuplicateStepNameError extends Error {
+    stepName;
+    positions;
+    constructor(stepName, positions) {
+        super(`Duplicate step name "${stepName}" at positions ${positions[0]} and ${positions[1]}. ` +
+            `CF Workflows uses step names as cache keys — duplicates will return stale cached results.`);
+        this.stepName = stepName;
+        this.positions = positions;
+        this.name = "DuplicateStepNameError";
+    }
+}
+export class StepNameTooLongError extends Error {
+    stepName;
+    length;
+    constructor(stepName, length) {
+        super(`Step name "${stepName.slice(0, 50)}..." is ${length} characters. ` +
+            `CF Workflows allows max 256 characters per step name.`);
+        this.stepName = stepName;
+        this.length = length;
+        this.name = "StepNameTooLongError";
+    }
+}
+export class InvalidEventTypeError extends Error {
+    eventType;
+    constructor(eventType) {
+        super(`Event type "${eventType}" contains invalid characters. ` +
+            `CF Workflows waitForEvent type only supports [a-zA-Z0-9_-]. Dots (.) are NOT allowed.`);
+        this.eventType = eventType;
+        this.name = "InvalidEventTypeError";
+    }
+}
+export class EmptyWorkflowError extends Error {
+    constructor() {
+        super("Workflow must contain at least one step.");
+        this.name = "EmptyWorkflowError";
+    }
+}
+export class StepLimitExceededError extends Error {
+    count;
+    constructor(count) {
+        super(`Workflow has ${count} steps, exceeding CF Workflows limit of 1024 steps per workflow. ` +
+            `Note: step.sleep and step.sleepUntil do NOT count towards this limit.`);
+        this.count = count;
+        this.name = "StepLimitExceededError";
+    }
+}
+export class CircularDependencyError extends Error {
+    cycle;
+    constructor(cycle) {
+        super(`Circular dependency detected: ${cycle.join(" → ")}. ` +
+            `Workflow steps cannot form cycles.`);
+        this.cycle = cycle;
+        this.name = "CircularDependencyError";
+    }
+}
+export class EmptyStepNameError extends Error {
+    constructor() {
+        super("Step name cannot be empty. CF Workflows uses step names as cache keys.");
+        this.name = "EmptyStepNameError";
+    }
+}
+export class NonRetryableError extends Error {
+    constructor(message, name) {
+        super(message);
+        this.name = name ?? "NonRetryableError";
+    }
+}
+export class TimeoutTooLongError extends Error {
+    duration;
+    constructor(duration) {
+        super(`Timeout "${duration}" exceeds CF Workflows maximum of 30 minutes. ` +
+            `Ensure that the step timeout duration is 30 minutes or less.`);
+        this.duration = duration;
+        this.name = "TimeoutTooLongError";
+    }
+}
+export function isChildPayload(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        payload.__workflais === true);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,sFAAsF;AACtF,iEAAiE;AAiKjE,gFAAgF;AAEhF,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE7B;IACA;IAFlB,YACkB,QAAgB,EAChB,SAA2B;QAE3C,KAAK,CACH,wBAAwB,QAAQ,kBAAkB,SAAS,CAAC,CAAC,CAAC,QAAQ,SAAS,CAAC,CAAC,CAAC,IAAI;YACpF,2FAA2F,CAC9F,CAAC;QANc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAkB;QAM3C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAE3B;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CACH,cAAc,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,MAAM,eAAe;YACjE,uDAAuD,CAC1D,CAAC;QANc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAM9B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAClB;IAA5B,YAA4B,SAAiB;QAC3C,KAAK,CACH,eAAe,SAAS,iCAAiC;YACvD,uFAAuF,CAC1F,CAAC;QAJwB,cAAS,GAAT,SAAS,CAAQ;QAK3C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;QACE,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACnB;IAA5B,YAA4B,KAAa;QACvC,KAAK,CACH,gBAAgB,KAAK,mEAAmE;YACtF,uEAAuE,CAC1E,CAAC;QAJwB,UAAK,GAAL,KAAK,CAAQ;QAKvC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACpB;IAA5B,YAA4B,KAAe;QACzC,KAAK,CACH,iCAAiC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;YACpD,oCAAoC,CACvC,CAAC;QAJwB,UAAK,GAAL,KAAK,CAAU;QAKzC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;QACE,KAAK,CACH,wEAAwE,CACzE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,mBAAmB,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAChB;IAA5B,YAA4B,QAAgB;QAC1C,KAAK,CACH,YAAY,QAAQ,gDAAgD;YAClE,8DAA8D,CACjE,CAAC;QAJwB,aAAQ,GAAR,QAAQ,CAAQ;QAK1C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAYD,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QACf,OAAmC,CAAC,WAAW,KAAK,IAAI,CAC1D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "workflais",
+  "version": "0.1.0",
+  "description": "Effect-style composable workflow primitives for Cloudflare Workflows",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cf": "vitest run --config vitest.config.cf.ts",
+    "test:all": "vitest run && vitest run --config vitest.config.cf.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.12.18",
+    "@cloudflare/workers-types": "^4.20250214.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "wrangler": "^3.99.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}