openworkflow 0.3.0 → 0.4.1

package/README.md

@@ -1,8 +1,8 @@
 # OpenWorkflow
 
-[![npm version](https://badge.fury.io/js/openworkflow.svg)](https://www.npmjs.com/package/openworkflow)
-[![CI](https://img.shields.io/github/actions/workflow/status/openworkflowdev/openworkflow/ci.yaml)](https://github.com/openworkflowdev/openworkflow/actions/workflows/ci.yaml)
-[![codecov](https://codecov.io/github/openworkflowdev/openworkflow/graph/badge.svg?token=T618G8O4XS)](https://codecov.io/github/openworkflowdev/openworkflow)
+[![npm](https://img.shields.io/npm/v/openworkflow)](https://www.npmjs.com/package/openworkflow)
+[![build](https://img.shields.io/github/actions/workflow/status/openworkflowdev/openworkflow/ci.yaml)](https://github.com/openworkflowdev/openworkflow/actions/workflows/ci.yaml)
+[![coverage](https://img.shields.io/codecov/c/github/openworkflowdev/openworkflow)](https://codecov.io/github/openworkflowdev/openworkflow)
 
 OpenWorkflow is a TypeScript framework for building durable, resumable workflows
 that can pause for seconds or months, survive crashes and deploys, and resume
@@ -16,23 +16,29 @@ exactly where they left off - all without extra servers to manage.
 Prerequisites:
 
 - Node.js
-- PostgreSQL (support for additional backends like Redis and SQLite coming soon.
-  See [Roadmap](#roadmap) for details.)
+- PostgreSQL (and/or SQLite)
 
 ### 1. Install
 
 ```bash
-npm install openworkflow @openworkflow/backend-postgres
+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
 
 ```ts
 import { BackendPostgres } from "@openworkflow/backend-postgres";
+import { BackendSqlite } from "@openworkflow/backend-sqlite";
 import { OpenWorkflow } from "openworkflow";
 
-const postgresUrl = process.env.DATABASE_URL; // connection url to your db
-const backend = await BackendPostgres.connect(postgresUrl);
+// 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 ow = new OpenWorkflow({ backend });
 
 const sendWelcomeEmail = ow.defineWorkflow(
@@ -149,7 +155,7 @@ Your database is the source of truth.
 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
-   `succeeded` or `failed`.
+   `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.
@@ -220,7 +226,7 @@ Durations accept a number followed by a unit:
 | 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/duration.test.ts).
+[tests](https://github.com/openworkflowdev/openworkflow/blob/main/packages/openworkflow/core/duration.test.ts).
 
 ### Type Safety
 
@@ -297,6 +303,35 @@ const workflow = ow.defineWorkflow(
 );
 ```
 
+### 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" });
+```
+
+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.
+
 ## Production Checklist
 
 - **Database**: Use a production-ready Postgres instance
@@ -331,7 +366,7 @@ const workflow = ow.defineWorkflow(
 
 **Live in current `npm` release:**
 
-- ✅ PostgreSQL backend
+- ✅ PostgreSQL and SQLite backends
 - ✅ Worker with concurrency control
 - ✅ Step memoization & retries
 - ✅ Graceful shutdown
@@ -342,19 +377,20 @@ const workflow = ow.defineWorkflow(
 
 **Coming Soon:**
 
-> These releeases don't yet include a dashboard UI or CLI. For now, you can
-> inspect workflow and step state directly in PostgreSQL (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 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.
 
-- Improved local dev experience
-- CLI
+- Improved local dev experience (coming in v0.5)
+- CLI (coming in v0.5)
 - Dashboard UI
 - Idempotency keys
 - Rollback / compensation functions
 - Configurable retry policies
 - Signals for external events
-- Additional backends (Redis, SQLite)
+- Native OpenTelemetry integration
+- Additional backends (Redis)
 - Additional languages (Go, Python)
 
 ## Bugs & feature requests

package/dist/backend-sqlite/backend.d.ts

@@ -0,0 +1,38 @@
+import { Backend, CancelWorkflowRunParams, ClaimWorkflowRunParams, CreateStepAttemptParams, CreateWorkflowRunParams, GetStepAttemptParams, GetWorkflowRunParams, ExtendWorkflowRunLeaseParams, ListStepAttemptsParams, ListWorkflowRunsParams, PaginatedResponse, FailStepAttemptParams, CompleteStepAttemptParams, FailWorkflowRunParams, CompleteWorkflowRunParams, SleepWorkflowRunParams, StepAttempt, WorkflowRun } from "../index.js";
+export declare const DEFAULT_PAGINATION_PAGE_SIZE = 100;
+interface BackendSqliteOptions {
+    namespaceId?: string;
+    runMigrations?: boolean;
+}
+/**
+ * Manages a connection to a SQLite database for workflow operations.
+ */
+export declare class BackendSqlite implements Backend {
+    private db;
+    private namespaceId;
+    private constructor();
+    /**
+     * Create and initialize a new BackendSqlite instance. This will
+     * automatically run migrations on startup unless `runMigrations` is set to
+     * false.
+     */
+    static connect(path?: string, options?: BackendSqliteOptions): BackendSqlite;
+    stop(): void;
+    createWorkflowRun(params: CreateWorkflowRunParams): Promise<WorkflowRun>;
+    getWorkflowRun(params: GetWorkflowRunParams): Promise<WorkflowRun | null>;
+    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>;
+    listWorkflowRuns(params: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun>>;
+    listStepAttempts(params: ListStepAttemptsParams): Promise<PaginatedResponse<StepAttempt>>;
+    private processPaginationResults;
+    createStepAttempt(params: CreateStepAttemptParams): Promise<StepAttempt>;
+    getStepAttempt(params: GetStepAttemptParams): Promise<StepAttempt | null>;
+    completeStepAttempt(params: CompleteStepAttemptParams): Promise<StepAttempt>;
+    failStepAttempt(params: FailStepAttemptParams): Promise<StepAttempt>;
+}
+export {};
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend-sqlite/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../backend-sqlite/backend.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,OAAO,EACP,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,WAAW,EACX,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,UAAU,oBAAoB;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAKP;;;;OAIG;IACH,MAAM,CAAC,OAAO,CACZ,IAAI,GAAE,MAA8B,EACpC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa;IAgBhB,IAAI,IAAI,IAAI;IAIN,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IAgDvB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAenE,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA0FxB,sBAAsB,CAC1B,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,WAAW,CAAC;IAmCjB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoCtE,mBAAmB,CACvB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,WAAW,CAAC;IAyCjB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IA+DpE,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IAuDvB,gBAAgB,CACd,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAgE1C,gBAAgB,CACd,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAmE1C,OAAO,CAAC,wBAAwB;IAyC1B,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IAwCvB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAenE,mBAAmB,CACvB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,WAAW,CAAC;IA0DjB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAyD3E"}