openworkflow 0.5.0 → 0.6.0

package/README.md

@@ -8,16 +8,10 @@ OpenWorkflow is a TypeScript framework for building durable, resumable workflows
 that can pause for seconds or months, survive crashes and deploys, and resume
 exactly where they left off - all without extra servers to manage.
 
-Define a workflow in a few lines:
-
 ```ts
-import { BackendSqlite } from "@openworkflow/backend-sqlite";
-import { OpenWorkflow } from "openworkflow";
-
-const backend = BackendSqlite.connect("openworkflow/backend.db");
-const ow = new OpenWorkflow({ backend });
+import { defineWorkflow } from "openworkflow";
 
-const sendWelcomeEmail = ow.defineWorkflow(
+export const sendWelcomeEmail = defineWorkflow(
   { name: "send-welcome-email" },
   async ({ input, step }) => {
     const user = await step.run({ name: "fetch-user" }, async () => {
@@ -43,363 +37,62 @@ const sendWelcomeEmail = ow.defineWorkflow(
 );
 ```
 
-> OpenWorkflow is in active development and moving quickly. Check out the
-> [Roadmap](#roadmap) for what’s coming next.
-
 ## Quick Start
 
-Prerequisites:
-
-- Node.js
-- PostgreSQL (and/or SQLite)
+**Prerequisites:** Node.js & PostgreSQL (or SQLite)
 
-### 1. Install
-
-Install and set up OpenWorkflow with:
+### Install
 
 ```bash
 npx @openworkflow/cli init
 ```
 
-The CLI will prompt for your backend, installs dependencies, and generates:
-`openworkflow.config.ts`, `openworkflow/hello-world.ts`, `.env`, `.gitignore`,
-and a `worker` script.
-
-### 2. Start a worker
-
-```bash
-npm run worker
-# or
-npx @openworkflow/cli worker start
-```
-
-This runs the worker using `openworkflow.config.ts` and auto-loads workflows
-from the configured directories (default: `openworkflow/`).
-
-### 3. Run workflows from your app
-
-Edit the generated workflow file and run it from your application code using the
-OpenWorkflow client APIs (see examples below).
-
-That's it. Your workflow is now durable, resumable, and fault-tolerant.
-
-## Core Concepts
-
-### Workflows
-
-Workflows are durable functions. They can contain multiple steps, make external
-API calls, query databases, and perform complex logic. If a workflow is
-interrupted (crash, deploy, server restart), it resumes from its last completed
-step.
-
-```ts
-const workflow = ow.defineWorkflow(
-  { name: "my-workflow" },
-  async ({ input, step }) => {
-    // Your workflow logic here
-    return result;
-  },
-);
-```
-
-### Steps
-
-Steps are the building blocks of workflows. Each step is executed exactly once
-and its result is memoized. Steps let you break workflows into checkpoints.
-
-```ts
-const result = await step.run({ name: "step-name" }, async () => {
-  // This function runs once. If the workflow restarts,
-  // this returns the cached result instead of re-running.
-  return await someAsyncWork();
-});
-```
-
-**Why steps matter**: Imagine a workflow that charges a credit card, then sends
-an email. Without steps, if your server crashes after charging the card, the
-workflow would retry from the beginning and charge the customer twice. With
-steps, the charge is memoized. The retry skips it and goes straight to sending
-the email.
-
-### Workers
-
-Workers are long-running processes that poll your database for pending workflows
-and execute them. Run workers via the CLI so workflow discovery stays in sync
-with your `openworkflow.config.ts`:
-
-```bash
-npm run worker
-# or
-npx @openworkflow/cli worker start
-```
-
-Or, for more control, you can write your own workers:
-
-```ts
-import { BackendSqlite } from "@openworkflow/backend-sqlite";
-import { OpenWorkflow } from "openworkflow";
-
-const backend = BackendSqlite.connect("openworkflow/backend.db");
-const ow = new OpenWorkflow({ backend });
-
-const worker = ow.newWorker({ concurrency: 20 });
-await worker.start();
-
-// & to shut down...
-await worker.stop(); // waits for in-flight workflows to complete
-```
-
-Workers are stateless. They can be started, stopped, and deployed independently.
-Your database is the source of truth.
-
-### How it Works
-
-1. **Your app starts a workflow**: A row is inserted into the `workflow_runs`
-   table with status `pending`.
-2. **A worker picks it up**: The worker polls the database, claims the workflow,
-   and sets its status to `running`.
-3. **The worker executes steps**: Each step is recorded in the `step_attempts`
-   table. If a step succeeds, its result is cached.
-4. **The workflow completes**: The worker updates the `workflow_run` status to
-   `completed` or `failed`.
-5. **If the worker crashes**: The workflow becomes visible to other workers via
-   a heartbeat timeout. Another worker picks it up, loads the cached step
-   results, and resumes from the next step.
-
-## Advanced Patterns
-
-### Parallel Steps
-
-Run multiple steps concurrently using `Promise.all`:
-
-```ts
-const [user, subscription, settings] = await Promise.all([
-  step.run({ name: "fetch-user" }, async () => {
-    await db.users.findOne({ id: input.userId });
-  }),
-  step.run({ name: "fetch-subscription" }, async () => {
-    await stripe.subscriptions.retrieve(input.subId);
-  }),
-  step.run({ name: "fetch-settings" }, async () => {
-    await db.settings.findOne({ userId: input.userId });
-  }),
-]);
-```
-
-Each step is still memoized individually. If the workflow crashes mid-execution,
-completed steps return instantly on resume.
-
-### Automatic Retries
-
-Steps can retry automatically with exponential backoff:
-
-```ts
-const data = await step.run({ name: "fetch-external-api" }, async () => {
-  // If this throws, the step retries automatically
-  return await externalAPI.getData();
-});
-```
-
-Configure retry behavior at the workflow or step level (coming soon) or handle
-errors explicitly in your step functions.
-
-### Sleeping (Pausing) Workflows
-
-You can pause a workflow until a future time and, because sleeping releases the
-worker slot, you can pause thousands of workflows without tying up compute:
-
-```ts
-// Pause for 1 hour (durable, non-blocking)
-await step.sleep("wait-one-hour", "1h");
-```
-
-The sleep step is memoized after it completes. If the workflow is replayed again
-(e.g. due to a later retry) the completed sleep is not re-applied.
-
-#### Duration Formats
-
-Durations accept a number followed by a unit:
-
-| Unit         | Aliases               | Examples         |
-| ------------ | --------------------- | ---------------- |
-| milliseconds | `ms`, `msec`, `msecs` | `100ms`, `1.5ms` |
-| seconds      | `s`, `sec`, `secs`    | `5s`, `0.25s`    |
-| minutes      | `m`, `min`, `mins`    | `2m`, `1.5m`     |
-| hours        | `h`, `hr`, `hrs`      | `1h`, `0.25h`    |
-| days         | `d`, `day(s)`         | `1d`, `0.5d`     |
-| weeks        | `w`, `week(s)`        | `1w`, `2w`       |
-| months       | `mo`, `month(s)`      | `1mo`, `2mo`     |
-| years        | `y`, `yr`, `yrs`      | `1y`, `2yr`      |
-
-See more examples of accepted duration formats and aliases in the
-[tests](https://github.com/openworkflowdev/openworkflow/blob/main/packages/openworkflow/core/duration.test.ts).
-
-### Type Safety
-
-Workflows are fully typed. Define input and output types for compile-time
-safety:
-
-```ts
-interface ProcessOrderInput {
-  orderId: string;
-  userId: string;
-}
-
-interface ProcessOrderOutput {
-  paymentId: string;
-  shipmentId: string;
-}
-
-const processOrder = ow.defineWorkflow<ProcessOrderInput, ProcessOrderOutput>(
-  { name: "process-order" },
-  async ({ input, step }) => {
-    // input is typed as ProcessOrderInput
-    // return type must match ProcessOrderOutput
-    return { paymentId: "...", shipmentId: "..." };
-  },
-);
-```
-
-### Waiting for Results
-
-You can wait for a workflow to complete and get its result:
-
-```ts
-const run = await myWorkflow.run({ data: "..." });
-
-// Wait for the workflow to finish (polls the database)
-const result = await run.result();
-```
-
-### Canceling Workflows
-
-You can cancel a workflow that is pending, running, or sleeping to prevent a
-workflow from continuing on to the next step:
-
-```ts
-const handle = await myWorkflow.run({ data: "..." });
-
-// Cancel the workflow
-await handle.cancel();
-```
-
-### Workflow Versioning
-
-When you need to change workflow logic, use versioning for backwards
-compatibility.
-
-Define a workflow with an optional version:
-
-```ts
-const workflow = ow.defineWorkflow(
-  { name: "my-workflow", version: "v2" },
-  async ({ input, step, version }) => {
-    if (version === "v2") {
-      // v2 runs go here
-      await step.run({ name: "new-step" }, async () => {
-        // legacy logic
-      });
-    } else {
-      // v1 runs go here
-      await step.run({ name: "old-step" }, async () => {
-        // ...
-      });
-    }
-  },
-);
-```
-
-### Validating Workflow Inputs
-
-You can require `.run()` callers to provide specific inputs by supplying a
-`schema` when defining the workflow. The schema is evaluated before the run is
-enqueued, so invalid requests fail immediately.
-
-```ts
-import { z } from "zod";
-
-const summarizeDoc = ow.defineWorkflow(
-  {
-    name: "summarize",
-    schema: z.object({
-      docUrl: z.string().url(),
-    }),
-  },
-  async ({ input, step }) => {
-    // `input` has type { docUrl: string }
-  },
-);
-
-// Throws before enqueueing the workflow because the input isn't a URL
-await summarizeDoc.run({ docUrl: "not-a-url" });
-```
+The CLI will guide you through setup and generate everything you need to get
+started.
 
-Any validator function works as long as it throws on invalid data (great for
-custom logic or lightweight checks). Libraries such as Zod, ArkType, Valibot,
-and Yup.
+For more details, check out our [docs](https://openworkflow.dev/docs).
 
-## Production Checklist
+## Features
 
-- **Database**: Use a production-ready Postgres instance
-- **Workers**: Run at lease one worker process
-- **Concurrency**: Start with `concurrency: 10` per worker and tune based on
-  your workload
-- **Monitoring**: Log worker activity and set up alerts for failed workflows
-- **Graceful Shutdown**: Handle `SIGTERM` to ensure clean deploys:
-  ```ts
-  process.on("SIGTERM", async () => {
-    await worker.stop();
-    process.exit(0);
-  });
-  ```
-- **Namespaces** (optional): Use `namespaceId` in your backend configuration to
-  isolate workflows per environment:
-  ```ts
-  const backend = await BackendPostgres.connect(postgresUrl, {
-    namespaceId: "production",
-  });
-  ```
+- ✅ **Durable** - Workflows survive crashes and deploys
+- ✅ **Resumable** - Pick up exactly where you left off
+- ✅ **Type-safe** - Full TypeScript support
+- ✅ **Step memoization** - Never repeat completed work
+- ✅ **Automatic retries** - Built-in exponential backoff
+- ✅ **Long pauses** - Sleep for seconds or months
+- ✅ **Parallel execution** - Run steps concurrently
+- ✅ **No extra servers** - Uses your existing database
+- ✅ **Dashboard included** - Monitor and debug workflows
+- ✅ **Production ready** - PostgreSQL and SQLite support
 
-## What's Next
+## Documentation
 
-- Read [ARCHITECTURE.md](./ARCHITECTURE.md) for a deep dive into how
-  OpenWorkflow works
-- Check [examples/](./examples) for working examples
-- Star the repo and follow development on
-  [GitHub](https://github.com/openworkflowdev/openworkflow)
+- [Documentation](https://openworkflow.dev/docs)
+- [Quick Start Guide](https://openworkflow.dev/docs/quickstart)
+- [Core Concepts](https://openworkflow.dev/docs/core-concepts)
+- [Advanced Patterns](https://openworkflow.dev/docs/advanced-patterns)
+- [Production Checklist](https://openworkflow.dev/docs/production)
 
-## Roadmap
+## Architecture
 
-**Live in current `npm` release:**
+Read
+[ARCHITECTURE.md](https://github.com/openworkflowdev/openworkflow/blob/main/ARCHITECTURE.md)
+for a deep dive into how OpenWorkflow works under the hood.
 
-- ✅ PostgreSQL and SQLite backends
-- ✅ CLI (`npx @openworkflow/cli`)
-- ✅ Worker with concurrency control
-- ✅ Step memoization & retries
-- ✅ Graceful shutdown
-- ✅ Parallel step execution
-- ✅ Sleeping (pausing) workflows
-- ✅ Workflow versioning
-- ✅ Workflow cancelation
+## Examples
 
-**Coming Soon:**
+Check out
+[examples/](https://github.com/openworkflowdev/openworkflow/tree/main/examples)
+for working examples.
 
-> These releases don't yet include a dashboard UI. For now, you can inspect
-> workflow and step state directly in PostgreSQL or SQLite (workflow_runs and
-> step_attempts tables). A dashboard is planned for an upcoming release to make
-> debugging and monitoring much easier.
+## Contributing
 
-- Dashboard UI
-- Idempotency keys
-- Rollback / compensation functions
-- Configurable retry policies
-- Signals for external events
-- Native OpenTelemetry integration
-- Additional backends (Redis)
-- Additional languages (Go, Python)
+We welcome contributions! Please read
+[CONTRIBUTING.md](https://github.com/openworkflowdev/openworkflow/blob/main/CONTRIBUTING.md)
+before submitting a pull request.
 
-## Bugs & feature requests
+## Community
 
-Found a bug or have a feature request? Please open an issue on GitHub so we can
-track and prioritize it:
-https://github.com/openworkflowdev/openworkflow/issues/new
+- [GitHub Issues](https://github.com/openworkflowdev/openworkflow/issues) -
+  Report bugs and request features
+- [Roadmap](https://openworkflow.dev/docs/roadmap) - See what's coming next

package/dist/{testing → backend-test}/backend.testsuite.d.ts

@@ -1,4 +1,4 @@
-import type { Backend } from "openworkflow/internal";
+import type { Backend } from "../backend.js";
 /**
  * Options for the Backend test suite.
  */

package/dist/backend-test/backend.testsuite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.testsuite.d.ts","sourceRoot":"","sources":["../../backend-test/backend.testsuite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAM7C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B;;OAEG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA8sC7D"}

package/dist/{testing → backend-test}/backend.testsuite.js

@@ -88,7 +88,7 @@ export function testBackend(options) {
                 const second = await createPendingWorkflowRun(backend);
                 const listed = await backend.listWorkflowRuns({});
                 const listedIds = listed.data.map((run) => run.id);
-                expect(listedIds).toEqual([first.id, second.id]);
+                expect(listedIds).toEqual([second.id, first.id]);
                 await teardown(backend);
             });
             test("paginates workflow runs", async () => {
@@ -101,8 +101,8 @@ export function testBackend(options) {
                 // p1
                 const page1 = await backend.listWorkflowRuns({ limit: 2 });
                 expect(page1.data).toHaveLength(2);
-                expect(page1.data[0]?.id).toBe(runs[0]?.id);
-                expect(page1.data[1]?.id).toBe(runs[1]?.id);
+                expect(page1.data[0]?.id).toBe(runs[4]?.id);
+                expect(page1.data[1]?.id).toBe(runs[3]?.id);
                 expect(page1.pagination.next).not.toBeNull();
                 expect(page1.pagination.prev).toBeNull();
                 // p2
@@ -112,7 +112,7 @@ export function testBackend(options) {
                 });
                 expect(page2.data).toHaveLength(2);
                 expect(page2.data[0]?.id).toBe(runs[2]?.id);
-                expect(page2.data[1]?.id).toBe(runs[3]?.id);
+                expect(page2.data[1]?.id).toBe(runs[1]?.id);
                 expect(page2.pagination.next).not.toBeNull();
                 expect(page2.pagination.prev).not.toBeNull();
                 // p3
@@ -121,7 +121,7 @@ export function testBackend(options) {
                     after: page2.pagination.next, // eslint-disable-line @typescript-eslint/no-non-null-assertion
                 });
                 expect(page3.data).toHaveLength(1);
-                expect(page3.data[0]?.id).toBe(runs[4]?.id);
+                expect(page3.data[0]?.id).toBe(runs[0]?.id);
                 expect(page3.pagination.next).toBeNull();
                 expect(page3.pagination.prev).not.toBeNull();
                 // p2 again
@@ -131,7 +131,7 @@ export function testBackend(options) {
                 });
                 expect(page2Back.data).toHaveLength(2);
                 expect(page2Back.data[0]?.id).toBe(runs[2]?.id);
-                expect(page2Back.data[1]?.id).toBe(runs[3]?.id);
+                expect(page2Back.data[1]?.id).toBe(runs[1]?.id);
                 expect(page2Back.pagination.next).toEqual(page2.pagination.next);
                 expect(page2Back.pagination.prev).toEqual(page2.pagination.prev);
                 await teardown(backend);
@@ -151,10 +151,10 @@ export function testBackend(options) {
                     runs.push(await createPendingWorkflowRun(backend));
                 }
                 runs.sort((a, b) => {
-                    const timeDiff = a.createdAt.getTime() - b.createdAt.getTime();
+                    const timeDiff = b.createdAt.getTime() - a.createdAt.getTime();
                     if (timeDiff !== 0)
                         return timeDiff;
-                    return a.id.localeCompare(b.id);
+                    return b.id.localeCompare(a.id);
                 });
                 const page1 = await backend.listWorkflowRuns({ limit: 2 });
                 expect(page1.data).toHaveLength(2);
@@ -1088,4 +1088,3 @@ function newDateInOneYear() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-//# sourceMappingURL=backend.testsuite.js.map

package/dist/backend-test/index.d.ts

@@ -0,0 +1,2 @@
+export { testBackend } from "./backend.testsuite.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/backend-test/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../backend-test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/{testing → backend-test}/index.js

@@ -1,2 +1 @@
 export { testBackend } from "./backend.testsuite.js";
-//# sourceMappingURL=index.js.map

package/dist/backend.js

@@ -1,2 +1 @@
 export const DEFAULT_NAMESPACE_ID = "default";
-//# sourceMappingURL=backend.js.map

package/dist/backend.testsuite.d.ts

@@ -0,0 +1,20 @@
+import type { Backend } from "./backend.js";
+/**
+ * Options for the Backend test suite.
+ */
+export interface TestBackendOptions {
+    /**
+     * Creates a new isolated Backend instance.
+     */
+    setup: () => Promise<Backend>;
+    /**
+     * Cleans up a Backend instance.
+     */
+    teardown: (backend: Backend) => Promise<void>;
+}
+/**
+ * Runs the Backend test suite.
+ * @param options - Test suite options
+ */
+export declare function testBackend(options: TestBackendOptions): void;
+//# sourceMappingURL=backend.testsuite.d.ts.map

package/dist/backend.testsuite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.testsuite.d.ts","sourceRoot":"","sources":["../backend.testsuite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B;;OAEG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAgtC7D"}