openworkflow 0.4.1 → 0.5.0

package/README.md

@@ -8,37 +8,13 @@ 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.
 
-> 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)
-
-### 1. Install
-
-```bash
-npm install openworkflow @openworkflow/backend-postgres @openworkflow/backend-sqlite
-```
-
-You only need to install the backend package(s) for the database you plan to
-use.
-
-### 2. Define a workflow
+Define a workflow in a few lines:
 
 ```ts
-import { BackendPostgres } from "@openworkflow/backend-postgres";
 import { BackendSqlite } from "@openworkflow/backend-sqlite";
 import { OpenWorkflow } from "openworkflow";
 
-// use Postgres if DATABASE_URL is set, otherwise use SQLite
-const backend = process.env["DATABASE_URL"]
-  ? await BackendPostgres.connect(process.env["DATABASE_URL"])
-  : BackendSqlite.connect(); // optionally provide SQLite file path
-
+const backend = BackendSqlite.connect("openworkflow/backend.db");
 const ow = new OpenWorkflow({ backend });
 
 const sendWelcomeEmail = ow.defineWorkflow(
@@ -67,29 +43,44 @@ const sendWelcomeEmail = ow.defineWorkflow(
 );
 ```
 
-### 3. Start a worker
+> OpenWorkflow is in active development and moving quickly. Check out the
+> [Roadmap](#roadmap) for what’s coming next.
 
-Workers are background processes that execute your workflows. Start one in a
-separate process or the same one as your app:
+## Quick Start
 
-```ts
-const worker = ow.newWorker();
-await worker.start();
+Prerequisites:
+
+- Node.js
+- PostgreSQL (and/or SQLite)
+
+### 1. Install
+
+Install and set up OpenWorkflow with:
+
+```bash
+npx @openworkflow/cli init
 ```
 
-### 4. Run workflows from your app
+The CLI will prompt for your backend, installs dependencies, and generates:
+`openworkflow.config.ts`, `openworkflow/hello-world.ts`, `.env`, `.gitignore`,
+and a `worker` script.
 
-Trigger workflows from your web server, API, or any application code:
+### 2. Start a worker
 
-```ts
-// In your API route handler
-app.post("/users/:id/welcome", async (req, res) => {
-  // Run the workflow async and do not wait for the result
-  const runHandle = await sendWelcomeEmail.run({ userId: req.params.id });
-  res.json({ runId: runHandle.workflowRun.id });
-});
+```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
@@ -133,9 +124,24 @@ the email.
 ### Workers
 
 Workers are long-running processes that poll your database for pending workflows
-and execute them. You can run multiple workers for high availability and scale.
+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();
 
@@ -367,6 +373,7 @@ and Yup.
 **Live in current `npm` release:**
 
 - ✅ PostgreSQL and SQLite backends
+- ✅ CLI (`npx @openworkflow/cli`)
 - ✅ Worker with concurrency control
 - ✅ Step memoization & retries
 - ✅ Graceful shutdown
@@ -377,13 +384,11 @@ and Yup.
 
 **Coming Soon:**
 
-> These releases don't yet include a dashboard UI or CLI. For now, you can
-> inspect workflow and step state directly in PostgreSQL or SQLite
-> (workflow_runs and step_runs tables). A CLI and dashboard are planned for an
-> upcoming release to make debugging and monitoring much easier.
+> 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.
 
-- Improved local dev experience (coming in v0.5)
-- CLI (coming in v0.5)
 - Dashboard UI
 - Idempotency keys
 - Rollback / compensation functions

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

@@ -0,0 +1,44 @@
+import type { Backend, CancelWorkflowRunParams, ClaimWorkflowRunParams, CompleteStepAttemptParams, CompleteWorkflowRunParams, CreateStepAttemptParams, CreateWorkflowRunParams, ExtendWorkflowRunLeaseParams, FailStepAttemptParams, FailWorkflowRunParams, GetStepAttemptParams, GetWorkflowRunParams, ListStepAttemptsParams, ListWorkflowRunsParams, PaginatedResponse, SleepWorkflowRunParams } from "../backend.js";
+import type { StepAttempt } from "../core/step.js";
+import type { WorkflowRun } from "../core/workflow.js";
+interface BackendPostgresOptions {
+    namespaceId?: string;
+    runMigrations?: boolean;
+}
+/**
+ * Manages a connection to a Postgres database for workflow operations.
+ */
+export declare class BackendPostgres implements Backend {
+    private pg;
+    private namespaceId;
+    private constructor();
+    /**
+     * Create and initialize a new BackendPostgres instance. This will
+     * automatically run migrations on startup unless `runMigrations` is set to
+     * false.
+     * @param url - Postgres connection URL
+     * @param options - Backend options
+     * @returns A connected backend instance
+     */
+    static connect(url: string, options?: BackendPostgresOptions): Promise<BackendPostgres>;
+    stop(): Promise<void>;
+    createWorkflowRun(params: CreateWorkflowRunParams): Promise<WorkflowRun>;
+    getWorkflowRun(params: GetWorkflowRunParams): Promise<WorkflowRun | null>;
+    listWorkflowRuns(params: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun>>;
+    private buildListWorkflowRunsWhere;
+    claimWorkflowRun(params: ClaimWorkflowRunParams): Promise<WorkflowRun | null>;
+    extendWorkflowRunLease(params: ExtendWorkflowRunLeaseParams): Promise<WorkflowRun>;
+    sleepWorkflowRun(params: SleepWorkflowRunParams): Promise<WorkflowRun>;
+    completeWorkflowRun(params: CompleteWorkflowRunParams): Promise<WorkflowRun>;
+    failWorkflowRun(params: FailWorkflowRunParams): Promise<WorkflowRun>;
+    cancelWorkflowRun(params: CancelWorkflowRunParams): Promise<WorkflowRun>;
+    createStepAttempt(params: CreateStepAttemptParams): Promise<StepAttempt>;
+    getStepAttempt(params: GetStepAttemptParams): Promise<StepAttempt | null>;
+    listStepAttempts(params: ListStepAttemptsParams): Promise<PaginatedResponse<StepAttempt>>;
+    private buildListStepAttemptsWhere;
+    private processPaginationResults;
+    completeStepAttempt(params: CompleteStepAttemptParams): Promise<StepAttempt>;
+    failStepAttempt(params: FailStepAttemptParams): Promise<StepAttempt>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend-postgres/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAWvD,UAAU,sBAAsB;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAKP;;;;;;;OAOG;WACU,OAAO,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,eAAe,CAAC;IAiBrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IA0CjB,cAAc,CAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAYxB,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IA2B1C,OAAO,CAAC,0BAA0B;IA0B5B,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAmDxB,sBAAsB,CAC1B,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,WAAW,CAAC;IAkBjB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC;IAwBtE,mBAAmB,CACvB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,WAAW,CAAC;IAuBjB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAgEpE,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IA2CjB,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IAoCjB,cAAc,CAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAWxB,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IA2B1C,OAAO,CAAC,0BAA0B;IA6BlC,OAAO,CAAC,wBAAwB;IAyC1B,mBAAmB,CACvB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,WAAW,CAAC;IA0BjB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAyB3E"}