openworkflow 0.5.0 → 0.6.0

package/dist/core/workflow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow.test.d.ts.map

package/dist/core/workflow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.test.d.ts","sourceRoot":"","sources":["../../core/workflow.test.ts"],"names":[],"mappings":""}

package/dist/core/workflow.test.js

@@ -0,0 +1,113 @@
+import { validateInput } from "./workflow.js";
+import { describe, expect, test } from "vitest";
+describe("validateInput", () => {
+    test("returns success with input when no schema provided (null)", async () => {
+        const input = { name: "test", value: 42 };
+        const result = await validateInput(null, input);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toBe(input);
+        }
+    });
+    test("returns success with input when no schema provided (undefined)", async () => {
+        const input = "string input";
+        const result = await validateInput(undefined, input);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toBe(input);
+        }
+    });
+    test("validates input successfully against schema", async () => {
+        const schema = createMockSchema({
+            validate: (input) => ({ value: input }),
+        });
+        const input = { name: "test" };
+        const result = await validateInput(schema, input);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toEqual({ name: "test" });
+        }
+    });
+    test("transforms input using schema", async () => {
+        const schema = createMockSchema({
+            validate: (input) => ({ value: Number.parseInt(input, 10) }),
+        });
+        const result = await validateInput(schema, "42");
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toBe(42);
+        }
+    });
+    test("returns failure with error message when validation fails", async () => {
+        const schema = createMockSchema({
+            validate: () => ({
+                issues: [{ message: "Invalid input" }],
+            }),
+        });
+        const result = await validateInput(schema, "bad input");
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error).toBe("Invalid input");
+        }
+    });
+    test("combines multiple validation error messages", async () => {
+        const schema = createMockSchema({
+            validate: () => ({
+                issues: [
+                    { message: "Invalid email format" },
+                    { message: "Age must be positive" },
+                ],
+            }),
+        });
+        const result = await validateInput(schema, {
+            email: "invalid",
+            age: -5,
+        });
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error).toBe("Invalid email format; Age must be positive");
+        }
+    });
+    test("returns generic message when issues array is empty", async () => {
+        const schema = createMockSchema({
+            validate: () => ({
+                issues: [],
+            }),
+        });
+        const result = await validateInput(schema, "test");
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error).toBe("Validation failed");
+        }
+    });
+    test("handles async schema validation", async () => {
+        const schema = createMockSchema({
+            validate: async (input) => {
+                await new Promise((resolve) => setTimeout(resolve, 1));
+                return { value: input.toUpperCase() };
+            },
+        });
+        const result = await validateInput(schema, "hello");
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toBe("HELLO");
+        }
+    });
+    test("handles undefined input when no schema", async () => {
+        // eslint-disable-next-line unicorn/no-useless-undefined
+        const result = await validateInput(null, undefined);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.value).toBeUndefined();
+        }
+    });
+});
+function createMockSchema(options) {
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "test",
+            validate: options.validate,
+        },
+    };
+}

package/dist/driver.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Drizzle-style driver model for OpenWorkflow backends.
+ *
+ * This module provides a driver abstraction layer that separates the database
+ * client (driver) from the backend operations. It follows the Drizzle ORM
+ * pattern where:
+ *
+ * 1. A `Driver` wraps the low-level database client
+ * 2. A `DriverConfig` specifies connection and namespace options
+ * 3. The `openworkflow()` factory function creates an `OpenWorkflow` instance
+ *
+ * Example usage with PostgreSQL:
+ * ```ts
+ * import { openworkflow } from 'openworkflow';
+ * import { postgres } from 'openworkflow/postgres';
+ *
+ * // Simple usage with connection string
+ * const ow = openworkflow(postgres(process.env.DATABASE_URL));
+ *
+ * // With config options
+ * const ow = openworkflow(postgres({
+ *   connection: process.env.DATABASE_URL,
+ *   namespace: 'my-app',
+ * }));
+ * ```
+ *
+ * Example usage with SQLite:
+ * ```ts
+ * import { openworkflow } from 'openworkflow';
+ * import { sqlite } from 'openworkflow/sqlite';
+ *
+ * const ow = openworkflow(sqlite(':memory:'));
+ * ```
+ */
+import type { Backend } from "./backend.js";
+/**
+ * A driver creates Backend instances from database connections.
+ * This is the core abstraction that allows OpenWorkflow to work with
+ * different database backends using the same API.
+ *
+ * Drivers are typically created using helper functions like:
+ * - `postgres()` from 'openworkflow/postgres'
+ * - `sqlite()` from 'openworkflow/sqlite'
+ */
+export interface Driver {
+    /**
+     * Unique identifier for this driver type.
+     */
+    readonly dialect: DriverDialect;
+    /**
+     * Creates a new Backend instance from this driver.
+     * This method handles connection setup and migrations.
+     */
+    createBackend(): Promise<Backend> | Backend;
+    /**
+     * The underlying database client, if available.
+     * This can be used for advanced operations or debugging.
+     */
+    readonly $client?: unknown;
+}
+/**
+ * Supported driver dialects.
+ */
+export type DriverDialect = "postgres" | "sqlite";
+/**
+ * Common configuration options for all drivers.
+ */
+export interface DriverConfig {
+    /**
+     * The namespace for workflow runs. Defaults to 'default'.
+     * This allows multiple applications to share the same database.
+     */
+    namespace?: string;
+    /**
+     * Whether to automatically run migrations on connection.
+     * Defaults to true.
+     */
+    runMigrations?: boolean;
+    /**
+     * Optional logger for debugging.
+     */
+    logger?: DriverLogger;
+}
+/**
+ * Logger interface for driver operations.
+ */
+export interface DriverLogger {
+    /**
+     * Log a message at info level.
+     */
+    logQuery?(query: string, params?: unknown[]): void;
+    /**
+     * Log a message at error level.
+     */
+    error?(message: string, error?: unknown): void;
+}
+/**
+ * Configuration options for the openworkflow factory function.
+ */
+export interface OpenWorkflowConfig {
+    /**
+     * Optional logger for debugging.
+     */
+    logger?: DriverLogger;
+}
+/**
+ * A driver that is ready to create backends.
+ * This type is used to ensure the driver has been properly configured.
+ */
+export interface PreparedDriver<TClient = unknown> extends Driver {
+    /**
+     * The underlying database client.
+     */
+    readonly $client: TClient;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAE5C;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEnD;;OAEG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,GAAG,OAAO,CAAE,SAAQ,MAAM;IAC/D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B"}

package/dist/driver.js

@@ -0,0 +1 @@
+export {};

package/dist/execution.js

@@ -185,4 +185,3 @@ export async function executeWorkflow(params) {
         });
     }
 }
-//# sourceMappingURL=execution.js.map

package/dist/execution.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execution.test.d.ts.map

package/dist/execution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.test.d.ts","sourceRoot":"","sources":["../execution.test.ts"],"names":[],"mappings":""}

package/dist/execution.test.js

@@ -0,0 +1,381 @@
+import { OpenWorkflow } from "./client.js";
+import { BackendPostgres } from "./postgres.js";
+import { DEFAULT_POSTGRES_URL } from "./postgres/postgres.js";
+import { randomUUID } from "node:crypto";
+import { describe, test, expect } from "vitest";
+describe("StepExecutor", () => {
+    test("executes step and returns result", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "executor-basic" }, async ({ step }) => {
+            const result = await step.run({ name: "add" }, () => 5 + 3);
+            return result;
+        });
+        const worker = client.newWorker();
+        const handle = await workflow.run();
+        await worker.tick();
+        const result = await handle.result();
+        expect(result).toBe(8);
+    });
+    test("caches step results for same step name", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        let executionCount = 0;
+        const workflow = client.defineWorkflow({ name: "executor-cached" }, async ({ step }) => {
+            const first = await step.run({ name: "cached-step" }, () => {
+                executionCount++;
+                return "first-execution";
+            });
+            const second = await step.run({ name: "cached-step" }, () => {
+                executionCount++;
+                return "second-execution";
+            });
+            return { first, second };
+        });
+        const worker = client.newWorker();
+        const handle = await workflow.run();
+        await worker.tick();
+        const result = await handle.result();
+        expect(result).toEqual({
+            first: "first-execution",
+            second: "first-execution",
+        });
+        expect(executionCount).toBe(1);
+    });
+    test("different step names execute independently", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        let executionCount = 0;
+        const workflow = client.defineWorkflow({ name: "executor-different-steps" }, async ({ step }) => {
+            const first = await step.run({ name: "step-1" }, () => {
+                executionCount++;
+                return "a";
+            });
+            const second = await step.run({ name: "step-2" }, () => {
+                executionCount++;
+                return "b";
+            });
+            return { first, second };
+        });
+        const worker = client.newWorker();
+        const handle = await workflow.run();
+        await worker.tick();
+        const result = await handle.result();
+        expect(result).toEqual({ first: "a", second: "b" });
+        expect(executionCount).toBe(2);
+    });
+    test("propagates step errors with deadline exceeded", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "executor-error" }, async ({ step }) => {
+            await step.run({ name: "failing-step" }, () => {
+                throw new Error("Step failed intentionally");
+            });
+            return "should not reach";
+        });
+        const worker = client.newWorker();
+        // Use deadline to force immediate failure without retries
+        const handle = await workflow.run({}, { deadlineAt: new Date() });
+        await worker.tick();
+        await sleep(100);
+        await expect(handle.result()).rejects.toThrow(/deadline exceeded/);
+    });
+    test("sleep puts workflow in sleeping status", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "executor-sleep" }, async ({ step }) => {
+            await step.sleep("sleep-1", "5s");
+            return "after sleep";
+        });
+        const handle = await workflow.run();
+        const worker = client.newWorker();
+        await worker.tick();
+        const workflowRun = await backend.getWorkflowRun({
+            workflowRunId: handle.workflowRun.id,
+        });
+        expect(workflowRun?.status).toBe("sleeping");
+        expect(workflowRun?.availableAt).not.toBeNull();
+    });
+    test("workflow resumes after sleep duration", async () => {
+        const backend = await createBackend();
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "resume-after-sleep" }, async ({ step }) => {
+            const value = await step.run({ name: "before" }, () => 5);
+            await step.sleep("wait", "10ms");
+            return value + 10;
+        });
+        const handle = await workflow.run();
+        const worker = client.newWorker();
+        // First tick - hits sleep
+        await worker.tick();
+        await sleep(50); // Wait for tick to complete
+        const sleeping = await backend.getWorkflowRun({
+            workflowRunId: handle.workflowRun.id,
+        });
+        expect(sleeping?.status).toBe("sleeping");
+        // Wait for sleep to elapse
+        await sleep(50);
+        // Second tick - completes
+        await worker.tick();
+        const result = await handle.result();
+        expect(result).toBe(15);
+    });
+});
+describe("executeWorkflow", () => {
+    describe("successful execution", () => {
+        test("executes a simple workflow", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "simple-workflow" }, ({ input }) => {
+                return input.a + input.b;
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ a: 10, b: 5 });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(15);
+        });
+        test("executes a multi-step workflow", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "multi-step-workflow" }, async ({ input, step }) => {
+                const sum = await step.run({ name: "add" }, () => input.value + 5);
+                const product = await step.run({ name: "multiply" }, () => sum * 2);
+                return product;
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ value: 10 });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(30);
+        });
+        test("returns null for workflows without return", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "void-workflow" }, () => null);
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBeNull();
+        });
+        test("returns null from workflow", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "null-workflow" }, () => null);
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBeNull();
+        });
+    });
+    describe("error handling", () => {
+        test("handles workflow errors with deadline exceeded", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "failing-workflow" }, () => {
+                throw new Error("Workflow error");
+            });
+            const worker = client.newWorker();
+            // Use deadline to skip retries - fails with deadline exceeded
+            const handle = await workflow.run({}, { deadlineAt: new Date() });
+            await worker.tick();
+            await sleep(100);
+            await expect(handle.result()).rejects.toThrow(/deadline exceeded/);
+        });
+        test("handles step errors with deadline exceeded", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "step-error-workflow" }, async ({ step }) => {
+                await step.run({ name: "failing" }, () => {
+                    throw new Error("Step error");
+                });
+                return "unreachable";
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({}, { deadlineAt: new Date() });
+            await worker.tick();
+            await sleep(100);
+            await expect(handle.result()).rejects.toThrow(/deadline exceeded/);
+        });
+        test("serializes non-Error exceptions", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "non-error-workflow" }, async ({ step }) => {
+                await step.run({ name: "throw-object" }, () => {
+                    // eslint-disable-next-line @typescript-eslint/only-throw-error
+                    throw { custom: "error", code: 500 };
+                });
+                return "nope";
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({}, { deadlineAt: new Date() });
+            await worker.tick();
+            await sleep(100);
+            await expect(handle.result()).rejects.toThrow();
+        });
+    });
+    describe("sleep handling", () => {
+        test("workflow enters sleeping status", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "sleep-workflow" }, async ({ step }) => {
+                await step.sleep("wait", "5s");
+                return "after sleep";
+            });
+            const handle = await workflow.run();
+            const worker = client.newWorker();
+            await worker.tick();
+            const workflowRun = await backend.getWorkflowRun({
+                workflowRunId: handle.workflowRun.id,
+            });
+            expect(workflowRun?.status).toBe("sleeping");
+        });
+        test("resumes workflow after sleep duration", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "resume-after-sleep" }, async ({ input, step }) => {
+                const sum = await step.run({ name: "add" }, () => input.value + 1);
+                await step.sleep("wait", "10ms");
+                return sum + 10;
+            });
+            const handle = await workflow.run({ value: 5 });
+            const worker = client.newWorker();
+            // first tick - hits sleep
+            await worker.tick();
+            await sleep(50);
+            const sleeping = await backend.getWorkflowRun({
+                workflowRunId: handle.workflowRun.id,
+            });
+            expect(sleeping?.status).toBe("sleeping");
+            // wait for sleep
+            await sleep(50);
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(16);
+        });
+    });
+    describe("workflow with complex data", () => {
+        test("handles objects as input and output", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "user-workflow" }, ({ input }) => {
+                return {
+                    greeting: `Hello, ${input.name}! You are ${String(input.age)} years old.`,
+                    processed: true,
+                };
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ name: "Alice", age: 30 });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toEqual({
+                greeting: "Hello, Alice! You are 30 years old.",
+                processed: true,
+            });
+        });
+        test("handles arrays in workflow", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "array-workflow" }, ({ input }) => {
+                return input.numbers.reduce((a, b) => a + b, 0);
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ numbers: [1, 2, 3, 4, 5] });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(15);
+        });
+    });
+    describe("result type handling", () => {
+        test("returns success with numeric result", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "numeric-result" }, async ({ step }) => {
+                return await step.run({ name: "compute" }, () => 100 + 200);
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(300);
+        });
+        test("returns success with string result", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "string-result" }, ({ input }) => {
+                return input.text.toUpperCase();
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ text: "hello world" });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe("HELLO WORLD");
+        });
+        test("returns success with boolean result", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "bool-result" }, ({ input }) => {
+                return input.value > 0;
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run({ value: 42 });
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toBe(true);
+        });
+    });
+    describe("step execution order", () => {
+        test("executes steps in sequence", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const order = [];
+            const workflow = client.defineWorkflow({ name: "sequence-workflow" }, async ({ step }) => {
+                await step.run({ name: "first" }, () => order.push("first"));
+                await step.run({ name: "second" }, () => order.push("second"));
+                await step.run({ name: "third" }, () => order.push("third"));
+                return order;
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toEqual(["first", "second", "third"]);
+        });
+    });
+    describe("version handling", () => {
+        test("passes version to workflow function", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "version-workflow", version: "1.0.0" }, ({ version }) => {
+                return { receivedVersion: version };
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toEqual({ receivedVersion: "1.0.0" });
+        });
+        test("passes null version when not specified", async () => {
+            const backend = await createBackend();
+            const client = new OpenWorkflow({ backend });
+            const workflow = client.defineWorkflow({ name: "no-version-workflow" }, ({ version }) => {
+                return { receivedVersion: version };
+            });
+            const worker = client.newWorker();
+            const handle = await workflow.run();
+            await worker.tick();
+            const result = await handle.result();
+            expect(result).toEqual({ receivedVersion: null });
+        });
+    });
+});
+async function createBackend() {
+    return await BackendPostgres.connect(DEFAULT_POSTGRES_URL, {
+        namespaceId: randomUUID(),
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}