sayiir 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,291 @@
+# Sayiir
+
+**Durable workflows for Node.js and TypeScript, powered by a Rust runtime.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sayiir/sayiir/blob/main/LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/node-18+-339933.svg)](https://nodejs.org)
+[![Discord](https://img.shields.io/badge/Discord-Join-7289da)](https://discord.gg/MWSzsHeg)
+
+Write plain TypeScript functions. Sayiir makes them durable — automatic checkpointing, crash recovery, and parallel execution with zero infrastructure.
+
+```typescript
+import { task, flow, runWorkflow } from "sayiir";
+
+const fetchUser = task("fetch-user", async (id: number) => {
+  return { id, name: "Alice" };
+});
+
+const sendEmail = task("send-email", (user: { id: number; name: string }) => {
+  return `Sent welcome to ${user.name}`;
+});
+
+const workflow = flow<number>("welcome")
+  .then(fetchUser)
+  .then(sendEmail)
+  .build();
+
+const result = runWorkflow(workflow, 42);
+// "Sent welcome to Alice"
+```
+
+No DSL. No YAML. No determinism constraints. No infrastructure to deploy.
+
+## Why Sayiir?
+
+- **No replay, no determinism rules** — Unlike Temporal, Restate, and other replay-based engines, Sayiir checkpoints after each task and resumes from the last checkpoint. Your tasks can call any API, use any library, read the clock, generate random values. No restrictions.
+- **A library, not a platform** — `pnpm add sayiir` and write workflows. No server cluster, no separate services. Optional PostgreSQL for production persistence.
+- **Rust core** — All orchestration, checkpointing, and execution runs in Rust via NAPI-RS. You write TypeScript; Rust handles the hard parts.
+- **Type-safe** — Generic `Flow<TInput, TLast>` builder tracks types through the chain. Full inference, no manual annotations.
+- **Zod integration** — Optional input/output validation with Zod schemas as a peer dependency.
+
+## Installation
+
+```bash
+pnpm add sayiir
+```
+
+Requires Node.js 18 or higher.
+
+## Quickstart
+
+### Inline lambdas — zero boilerplate
+
+```typescript
+import { flow, runWorkflow } from "sayiir";
+
+const workflow = flow<number>("pipeline")
+  .then("double", (x) => x * 2)
+  .then("add-one", (x) => x + 1)
+  .then("stringify", (x) => String(x))
+  .build();
+
+const result = runWorkflow(workflow, 5);
+// "11"  (5 * 2 = 10, 10 + 1 = 11, String(11))
+```
+
+No decorators, no registration — just pass any function. Use `task()` when you need metadata (retries, timeouts, tags) or reusable task definitions.
+
+### Sequential workflow
+
+```typescript
+import { task, flow, runWorkflow } from "sayiir";
+
+const double = task("double", (x: number) => x * 2);
+const addTen = task("add-ten", (x: number) => x + 10);
+
+const workflow = flow<number>("math")
+  .then(double)
+  .then(addTen)
+  .build();
+
+const result = runWorkflow(workflow, 5);
+// 20  (5 * 2 = 10, 10 + 10 = 20)
+```
+
+### Durable workflow (survives crashes)
+
+```typescript
+import { task, flow, runDurableWorkflow, InMemoryBackend } from "sayiir";
+
+const processOrder = task("process-order", (orderId: number) => {
+  return { orderId, status: "processed" };
+}, { timeout: "30s" });
+
+const sendConfirmation = task("send-confirmation", (order: { orderId: number }) => {
+  return `Confirmed order ${order.orderId}`;
+});
+
+const workflow = flow<number>("order")
+  .then(processOrder)
+  .then(sendConfirmation)
+  .build();
+
+const backend = new InMemoryBackend();
+
+// Checkpoints after each task — resumes from last checkpoint on crash
+const status = runDurableWorkflow(workflow, "order-123", 42, backend);
+
+if (status.status === "completed") {
+  console.log(status.output); // "Confirmed order 42"
+}
+```
+
+### PostgreSQL persistence
+
+```typescript
+import { PostgresBackend, runDurableWorkflow } from "sayiir";
+
+// Auto-runs migrations on first connect
+const backend = PostgresBackend.connect("postgresql://localhost/sayiir");
+const status = runDurableWorkflow(workflow, "run-001", 21, backend);
+```
+
+### Retry policy
+
+```typescript
+import { task } from "sayiir";
+
+const flakyCall = task("flaky-call", async (url: string) => {
+  const res = await fetch(url);
+  return res.json();
+}, {
+  retry: { maxAttempts: 3, initialDelay: "500ms", backoffMultiplier: 2.0 },
+});
+```
+
+### Parallel execution (fork/join)
+
+```typescript
+import { task, flow, branch, runWorkflow } from "sayiir";
+
+const validatePayment = task("validate-payment", (order: { id: number }) => {
+  return { payment: "valid" };
+});
+
+const checkInventory = task("check-inventory", (order: { id: number }) => {
+  return { stock: "available" };
+});
+
+const workflow = flow<{ id: number }>("checkout")
+  .fork([
+    branch("payment", validatePayment),
+    branch("inventory", checkInventory),
+  ])
+  .join("finalize", ([payment, inventory]) => {
+    return { ...payment, ...inventory };
+  })
+  .build();
+
+const result = runWorkflow(workflow, { id: 1 });
+```
+
+### Delays and signals
+
+```typescript
+import { flow, runDurableWorkflow, sendSignal, resumeWorkflow } from "sayiir";
+
+const workflow = flow<number>("approval")
+  .then("submit", (id) => ({ requestId: id }))
+  .waitForSignal("approval", "manager_approval", { timeout: "48h" })
+  .then("process", (signal) => `Approved: ${signal}`)
+  .build();
+
+// First run — parks at the signal
+const status = runDurableWorkflow(workflow, "req-1", 42, backend);
+// status.status === "awaiting_signal"
+
+// Later, when the approval arrives:
+sendSignal("req-1", "manager_approval", { approved: true }, backend);
+const final = resumeWorkflow(workflow, "req-1", backend);
+```
+
+### Zod validation
+
+```typescript
+import { z } from "zod";
+import { task, flow, runWorkflow } from "sayiir";
+
+const OrderSchema = z.object({
+  id: z.string(),
+  amount: z.number().positive(),
+});
+
+const processOrder = task("process-order", (order) => {
+  return { status: "charged", amount: order.amount };
+}, {
+  input: OrderSchema,
+});
+
+const workflow = flow("checkout").then(processOrder).build();
+const result = runWorkflow(workflow, { id: "abc", amount: 99.99 });
+// Zod validates input before the task runs
+```
+
+### Task metadata
+
+```typescript
+const processPayment = task("process-payment", async (order) => {
+  // ...
+}, {
+  timeout: "60s",
+  retries: 3,
+  tags: ["payments", "critical"],
+  description: "Charges the customer's payment method",
+});
+```
+
+## API Reference
+
+### Task Definition
+
+- **`task(id, fn, opts?)`** — Create a named task. Optional: `timeout`, `retries`, `retry`, `tags`, `description`, `input`/`output` (Zod schemas).
+
+### Flow Builder
+
+- **`flow<TInput>(name)`** — Create a new type-safe flow builder.
+- **`.then(fn)`** / **`.then(id, fn, opts?)`** — Append a task step. Accepts `task()` functions, plain functions, or lambdas.
+- **`.fork(branches)`** — Start parallel branches. Takes an array of `branch()` definitions.
+- **`.join(id, fn)`** — Merge branches with a combining function.
+- **`.delay(id, duration)`** — Durable delay (`"30s"`, `"5m"`, `"1h"`, or milliseconds).
+- **`.waitForSignal(id, signalName, opts?)`** — Wait for an external signal.
+- **`.build()`** — Compile and return a `Workflow<TIn, TOut>`.
+
+### Execution
+
+- **`runWorkflow(workflow, input)`** — Execute in-memory. Returns the final output.
+- **`runDurableWorkflow(workflow, instanceId, input, backend)`** — Execute with checkpointing. Returns `WorkflowStatus<TOut>`.
+- **`resumeWorkflow(workflow, instanceId, backend)`** — Resume from last checkpoint.
+- **`cancelWorkflow(instanceId, backend, opts?)`** — Cancel a running workflow.
+- **`pauseWorkflow(instanceId, backend, opts?)`** — Pause a running workflow.
+- **`unpauseWorkflow(instanceId, backend)`** — Unpause a paused workflow.
+- **`sendSignal(instanceId, signalName, payload, backend)`** — Send an external signal.
+
+### WorkflowStatus\<TOut\>
+
+Discriminated union — use `status.status` with TypeScript narrowing:
+
+```typescript
+if (status.status === "completed") {
+  console.log(status.output); // TOut
+} else if (status.status === "failed") {
+  console.log(status.error);  // string
+}
+```
+
+Variants: `completed`, `in_progress`, `failed`, `cancelled`, `paused`, `waiting`, `awaiting_signal`.
+
+### Backends
+
+- **`new InMemoryBackend()`** — In-memory storage for development and testing.
+- **`PostgresBackend.connect(url)`** — PostgreSQL persistence. Auto-runs migrations.
+
+## Architecture
+
+```
+Your TypeScript code       Sayiir (Rust)              Storage
+┌──────────────┐    ┌─────────────────────┐    ┌──────────────┐
+│  task()       │───>│  Orchestration      │───>│  Checkpoint  │
+│  functions   │    │  Checkpointing      │    │  after each  │
+│              │<───│  Crash recovery     │<───│  task        │
+└──────────────┘    │  Fork/join          │    └──────────────┘
+                    │  Serialization      │
+                    └─────────────────────┘
+```
+
+TypeScript provides task implementations. Rust handles everything else: building the execution graph, running tasks in order, checkpointing results, recovering from crashes, and managing parallel branches.
+
+## Requirements
+
+- Node.js 18+
+- Optional: `zod` for input/output validation
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://docs.sayiir.dev/getting-started/nodejs/)
+- [GitHub](https://github.com/sayiir/sayiir)
+- [Discord](https://discord.gg/MWSzsHeg)
+- [Roadmap](https://github.com/sayiir/sayiir/blob/main/ROADMAP.md)

package/dist/duration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Duration parsing utility.
+ *
+ * Converts human-readable duration strings (via `ms` library) or numeric
+ * milliseconds to milliseconds.
+ */
+import type { Duration } from "./types.js";
+/**
+ * Parse a Duration value to milliseconds.
+ *
+ * - Numbers are returned as-is (assumed to be ms).
+ * - Strings are parsed via the `ms` library (e.g. "30s", "5m", "1h").
+ */
+export declare function parseDuration(d: Duration): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAY3C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAOjD"}

package/dist/duration.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Duration parsing utility.
+ *
+ * Converts human-readable duration strings (via `ms` library) or numeric
+ * milliseconds to milliseconds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuration = parseDuration;
+let _ms;
+function getMs() {
+    if (!_ms) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _ms = require("ms");
+    }
+    return _ms;
+}
+/**
+ * Parse a Duration value to milliseconds.
+ *
+ * - Numbers are returned as-is (assumed to be ms).
+ * - Strings are parsed via the `ms` library (e.g. "30s", "5m", "1h").
+ */
+function parseDuration(d) {
+    if (typeof d === "number")
+        return d;
+    const result = getMs()(d);
+    if (result == null) {
+        throw new Error(`Invalid duration: "${d}"`);
+    }
+    return result;
+}
+//# sourceMappingURL=duration.js.map

package/dist/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAoBH,sCAOC;AAvBD,IAAI,GAAsD,CAAC;AAE3D,SAAS,KAAK;IACZ,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,iEAAiE;QACjE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAwC,CAAC;IAC7D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,CAAW;IACvC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/executor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Workflow execution utilities.
+ *
+ * Thin wrappers around the native addon, mirroring the Python executor.
+ */
+import type { Workflow } from "./flow.js";
+import type { WorkflowStatus } from "./types.js";
+import type { NapiInMemoryBackend, NapiPostgresBackend } from "./native.js";
+/** Backend type union. */
+export type Backend = InMemoryBackend | PostgresBackend;
+/** In-memory persistence backend for testing and development. */
+export declare class InMemoryBackend {
+    /** @internal */
+    readonly _inner: NapiInMemoryBackend;
+    constructor();
+}
+/** PostgreSQL persistence backend for durable production workflows. */
+export declare class PostgresBackend {
+    /** @internal */
+    readonly _inner: NapiPostgresBackend;
+    private constructor();
+    static connect(url: string): PostgresBackend;
+}
+/**
+ * Run a workflow to completion (no persistence).
+ *
+ * Returns the workflow output directly.
+ */
+export declare function runWorkflow<TIn, TOut>(workflow: Workflow<TIn, TOut>, input: TIn): TOut;
+/**
+ * Run a workflow with checkpointing and durability.
+ *
+ * Returns a WorkflowStatus indicating the outcome.
+ */
+export declare function runDurableWorkflow<TIn, TOut>(workflow: Workflow<TIn, TOut>, instanceId: string, input: TIn, backend: Backend): WorkflowStatus<TOut>;
+/** Resume a workflow from a saved checkpoint. */
+export declare function resumeWorkflow<TIn, TOut>(workflow: Workflow<TIn, TOut>, instanceId: string, backend: Backend): WorkflowStatus<TOut>;
+/** Request cancellation of a running workflow. */
+export declare function cancelWorkflow(instanceId: string, backend: Backend, opts?: {
+    reason?: string;
+    cancelledBy?: string;
+}): void;
+/** Request pausing of a running workflow. */
+export declare function pauseWorkflow(instanceId: string, backend: Backend, opts?: {
+    reason?: string;
+    pausedBy?: string;
+}): void;
+/** Unpause a paused workflow so it can be resumed. */
+export declare function unpauseWorkflow(instanceId: string, backend: Backend): void;
+/** Send an external signal to a workflow instance. */
+export declare function sendSignal(instanceId: string, signalName: string, payload: unknown, backend: Backend): void;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,YAAY,CAAC;AAEvE,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAGrB,0BAA0B;AAC1B,MAAM,MAAM,OAAO,GAAG,eAAe,GAAG,eAAe,CAAC;AAExD,iEAAiE;AACjE,qBAAa,eAAe;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;;CAKtC;AAED,uEAAuE;AACvE,qBAAa,eAAe;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAErC,OAAO;IAIP,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;CAI7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,EACnC,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EAC7B,KAAK,EAAE,GAAG,GACT,IAAI,CAON;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,EAC1C,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,OAAO,GACf,cAAc,CAAC,IAAI,CAAC,CAStB;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,EACtC,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,cAAc,CAAC,IAAI,CAAC,CAQtB;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAGN;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,IAAI,CAGN;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,IAAI,CAGN;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GACf,IAAI,CAGN"}

package/dist/executor.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Workflow execution utilities.
+ *
+ * Thin wrappers around the native addon, mirroring the Python executor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresBackend = exports.InMemoryBackend = void 0;
+exports.runWorkflow = runWorkflow;
+exports.runDurableWorkflow = runDurableWorkflow;
+exports.resumeWorkflow = resumeWorkflow;
+exports.cancelWorkflow = cancelWorkflow;
+exports.pauseWorkflow = pauseWorkflow;
+exports.unpauseWorkflow = unpauseWorkflow;
+exports.sendSignal = sendSignal;
+const types_js_1 = require("./types.js");
+const native_js_1 = require("./native.js");
+/** In-memory persistence backend for testing and development. */
+class InMemoryBackend {
+    /** @internal */
+    _inner;
+    constructor() {
+        this._inner = new ((0, native_js_1.getNative)().NapiInMemoryBackend)();
+    }
+}
+exports.InMemoryBackend = InMemoryBackend;
+/** PostgreSQL persistence backend for durable production workflows. */
+class PostgresBackend {
+    /** @internal */
+    _inner;
+    constructor(inner) {
+        this._inner = inner;
+    }
+    static connect(url) {
+        const inner = (0, native_js_1.getNative)().NapiPostgresBackend.connect(url);
+        return new PostgresBackend(inner);
+    }
+}
+exports.PostgresBackend = PostgresBackend;
+/**
+ * Run a workflow to completion (no persistence).
+ *
+ * Returns the workflow output directly.
+ */
+function runWorkflow(workflow, input) {
+    const engine = new ((0, native_js_1.getNative)().NapiWorkflowEngine)();
+    return engine.run(workflow._inner, input, workflow._taskRegistry);
+}
+/**
+ * Run a workflow with checkpointing and durability.
+ *
+ * Returns a WorkflowStatus indicating the outcome.
+ */
+function runDurableWorkflow(workflow, instanceId, input, backend) {
+    const engine = createDurableEngine(backend);
+    const raw = engine.run(workflow._inner, instanceId, input, workflow._taskRegistry);
+    return parseWorkflowStatus(raw);
+}
+/** Resume a workflow from a saved checkpoint. */
+function resumeWorkflow(workflow, instanceId, backend) {
+    const engine = createDurableEngine(backend);
+    const raw = engine.resume(workflow._inner, instanceId, workflow._taskRegistry);
+    return parseWorkflowStatus(raw);
+}
+/** Request cancellation of a running workflow. */
+function cancelWorkflow(instanceId, backend, opts) {
+    const engine = createDurableEngine(backend);
+    engine.cancel(instanceId, opts?.reason, opts?.cancelledBy);
+}
+/** Request pausing of a running workflow. */
+function pauseWorkflow(instanceId, backend, opts) {
+    const engine = createDurableEngine(backend);
+    engine.pause(instanceId, opts?.reason, opts?.pausedBy);
+}
+/** Unpause a paused workflow so it can be resumed. */
+function unpauseWorkflow(instanceId, backend) {
+    const engine = createDurableEngine(backend);
+    engine.unpause(instanceId);
+}
+/** Send an external signal to a workflow instance. */
+function sendSignal(instanceId, signalName, payload, backend) {
+    const engine = createDurableEngine(backend);
+    engine.sendSignal(instanceId, signalName, payload);
+}
+// ---- Internal helpers ----
+function createDurableEngine(backend) {
+    const native = (0, native_js_1.getNative)();
+    if (backend instanceof InMemoryBackend) {
+        return native.NapiDurableEngine.withInMemory(backend._inner);
+    }
+    if (backend instanceof PostgresBackend) {
+        return native.NapiDurableEngine.withPostgres(backend._inner);
+    }
+    throw new types_js_1.WorkflowError("backend must be InMemoryBackend or PostgresBackend");
+}
+function parseWorkflowStatus(raw) {
+    switch (raw.status) {
+        case "completed":
+            return {
+                status: "completed",
+                output: (raw.outputJson != null
+                    ? JSON.parse(raw.outputJson)
+                    : undefined),
+            };
+        case "in_progress":
+            return { status: "in_progress" };
+        case "failed":
+            return { status: "failed", error: raw.error ?? "unknown error" };
+        case "cancelled":
+            return {
+                status: "cancelled",
+                reason: raw.reason,
+                cancelledBy: raw.cancelledBy,
+            };
+        case "paused":
+            return {
+                status: "paused",
+                reason: raw.reason,
+                pausedBy: raw.cancelledBy,
+            };
+        default:
+            return { status: raw.status };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

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

package/dist/flow.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Type-safe flow builder for constructing workflows.
+ *
+ * The builder tracks input/output types through the chain using generics,
+ * providing full type inference without manual annotations.
+ *
+ * ```ts
+ * const wf = flow<number>("welcome")
+ *   .then("fetch", (id) => getUser(id))       // id: number -> User
+ *   .then("greet", (user) => `Hi ${user.name}`) // user: User -> string
+ *   .build();                                    // Workflow<number, string>
+ * ```
+ */
+import type { Duration, StepOptions, ZodLike } from "./types.js";
+import type { TaskFn } from "./task.js";
+import type { NapiFlowBuilder, NapiTaskMetadata, NapiWorkflow } from "./native.js";
+/** A compiled workflow ready for execution. */
+export declare class Workflow<TIn, TOut> {
+    /** @internal */
+    readonly _inner: NapiWorkflow;
+    /** @internal */
+    readonly _taskRegistry: Record<string, Function>;
+    constructor(inner: NapiWorkflow, taskRegistry: Record<string, Function>);
+    get workflowId(): string;
+    get definitionHash(): string;
+}
+/** A branch definition for fork/join. */
+export interface BranchDef<TIn, TOut> {
+    readonly name: string;
+    readonly steps: readonly BranchStep[];
+    /** @internal — phantom type marker */
+    readonly _in?: TIn;
+    readonly _out?: TOut;
+}
+interface BranchStep {
+    taskId: string;
+    fn: Function;
+    metadata?: NapiTaskMetadata;
+}
+/** Infer the output types from a tuple of branch definitions. */
+export type InferBranchOutputs<T extends readonly BranchDef<any, any>[]> = {
+    [K in keyof T]: T[K] extends BranchDef<any, infer O> ? O : never;
+};
+/**
+ * Create a branch for use with `.fork()`.
+ *
+ * ```ts
+ * flow<Order>("process")
+ *   .then(chargePayment)
+ *   .fork([
+ *     branch("email", sendConfirmation),
+ *     branch("ship", shipOrder),
+ *   ])
+ *   .join("finalize", ([email, ship]) => ({ email, ship }))
+ *   .build();
+ * ```
+ */
+export declare function branch<TIn, TOut>(name: string, fn: TaskFn<TIn, TOut> | ((input: TIn) => TOut | Promise<TOut>)): BranchDef<TIn, Awaited<TOut>>;
+/** Type-safe workflow builder. */
+export declare class Flow<TInput, TLast = TInput> {
+    /** @internal */
+    readonly _builder: NapiFlowBuilder;
+    /** @internal */
+    readonly _taskRegistry: Record<string, Function>;
+    /** @internal */
+    _lambdaCounter: number;
+    constructor(name: string);
+    /**
+     * Add a sequential task step.
+     *
+     * Accepts either a `TaskFn` (created by `task()`) or an inline function with an id.
+     */
+    then<TOut>(fn: TaskFn<TLast, TOut>): Flow<TInput, Awaited<TOut>>;
+    then<TOut>(id: string, fn: ((input: TLast) => TOut | Promise<TOut>) | TaskFn<TLast, TOut>, opts?: StepOptions): Flow<TInput, Awaited<TOut>>;
+    /**
+     * Start a fork for parallel execution.
+     *
+     * ```ts
+     * .fork([
+     *   branch("email", sendEmail),
+     *   branch("sms", sendSms),
+     * ])
+     * .join("merge", ([email, sms]) => ({ email, sms }))
+     * ```
+     */
+    fork<TBranches extends readonly BranchDef<TLast, any>[]>(branches: [...TBranches]): ForkBuilder<TInput, TLast, TBranches>;
+    /**
+     * Add a durable delay. No workers are held during the delay.
+     *
+     * Duration can be a number (ms) or a string like "30s", "5m", "1h".
+     */
+    delay(id: string, duration: Duration): Flow<TInput, TLast>;
+    /**
+     * Wait for an external signal before continuing.
+     *
+     * The workflow parks and releases the worker until the signal arrives.
+     */
+    waitForSignal<TSignal = unknown>(id: string, signalName: string, opts?: {
+        timeout?: Duration;
+        schema?: ZodLike<TSignal>;
+    }): Flow<TInput, TSignal>;
+    /** Build the workflow definition. */
+    build(): Workflow<TInput, TLast>;
+}
+/** Builder for fork/join parallel branches. */
+export declare class ForkBuilder<TInput, TLast, TBranches extends readonly BranchDef<TLast, any>[]> {
+    private readonly flow;
+    private readonly branches;
+    constructor(flow: Flow<TInput, TLast>, branches: TBranches);
+    /**
+     * Join branches with a combining function.
+     *
+     * The join function receives a tuple of branch outputs.
+     */
+    join<TOut>(id: string, fn: (branches: InferBranchOutputs<TBranches>) => TOut | Promise<TOut>): Flow<TInput, Awaited<TOut>>;
+}
+/** Factory function to create a new flow. */
+export declare function flow<TInput>(name: string): Flow<TInput>;
+export {};
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

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