Skip to content

Update docs to use ow.runWorkflow #286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamescmartinez merged 1 commit into from
Feb 12, 2026
Merged

Update docs to use ow.runWorkflow #286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions packages/docs/docs/advanced-patterns.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ TypeScript will catch type errors at compile time, preventing runtime issues.
Wait for a workflow to complete and get its result:

```ts
const run = await myWorkflow.run({ data: "..." });
const run = await ow.runWorkflow(myWorkflow.spec, { data: "..." });

// Wait for the workflow to finish (polls the database)
Comment on lines 113 to 116
Copy link

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page now uses ow.runWorkflow(...) in code blocks, but ow is not defined or imported anywhere in the document. Add a brief setup snippet (e.g., importing/constructing ow) or clarify that ow refers to your OpenWorkflow client instance before these examples.

Copilot uses AI. Check for mistakes.
const result = await run.result();
Expand All @@ -129,7 +129,7 @@ Cancel a workflow that is pending, running, or sleeping to prevent it from
continuing:

```ts
const handle = await myWorkflow.run({ data: "..." });
const handle = await ow.runWorkflow(myWorkflow.spec, { data: "..." });

// Cancel the workflow
await handle.cancel();
Expand Down Expand Up @@ -191,7 +191,7 @@ const summarizeDoc = defineWorkflow(
);

// Throws before enqueueing the workflow because the input isn't a URL
await summarizeDoc.run({ docUrl: "not-a-url" });
await ow.runWorkflow(summarizeDoc.spec, { docUrl: "not-a-url" });
```

Any validator function works as long as it throws on invalid data. This supports
Expand Down
5 changes: 3 additions & 2 deletions packages/docs/docs/canceling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ You can cancel workflow runs that are pending, running, or sleeping.
Use the `cancel()` method on a workflow run handle:

```ts
import { ow } from "./openworkflow/client";
Copy link

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new example imports ow from ./openworkflow/client without an extension. For Node ESM / compiled JS setups, ./openworkflow/client.js is typically required (and matches the CLI init template). Consider updating the import to avoid copy/paste runtime errors.

Suggested change
import { ow } from "./openworkflow/client";
import { ow } from "./openworkflow/client.js";

Copilot uses AI. Check for mistakes.
import { defineWorkflow } from "openworkflow";

const longRunning = defineWorkflow(
Expand All @@ -21,7 +22,7 @@ const longRunning = defineWorkflow(
);

// Start the workflow
const handle = await longRunning.run();
const handle = await ow.runWorkflow(longRunning.spec);

// Cancel it before it completes
await handle.cancel();
Expand Down Expand Up @@ -67,7 +68,7 @@ no new steps will run on the next poll.
After calling `cancel()`, you can verify the status:

```ts
const handle = await workflow.run();
const handle = await ow.runWorkflow(workflow.spec);
await handle.cancel();

// Waiting for result on a canceled workflow throws
Expand Down
3 changes: 2 additions & 1 deletion packages/docs/docs/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ Your application enqueues workflow runs. Workers pick them up. The backend

When a run starts:

1. Your app calls `workflow.run()`, creating a `pending` run in the database
1. Your app enqueues a run (for example, with `ow.runWorkflow(workflow.spec,
input)`), creating a `pending` run in the database
2. A worker claims the run and marks it `running`
3. The worker replays workflow code from the beginning
4. Completed steps return cached outputs; new steps execute and persist results
Expand Down
10 changes: 5 additions & 5 deletions packages/docs/docs/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,14 @@ bun openworkflow/hello-world.run.ts

</CodeGroup>

This script calls `workflow.run()` to create a new workflow run in the database.
The worker in your first terminal picks it up, executes each step, and marks it
complete.
This script calls `ow.runWorkflow(helloWorld.spec, {})` to create a new workflow
run in the database. The worker in your first terminal picks it up, executes
each step, and marks it complete.

<Note>
The `hello-world.run.ts` file is a temporary helper for testing. In a real
app, you'd call `workflow.run()` from your API routes, scripts, or other
application code.
app, you'd call `ow.runWorkflow(workflow.spec, input)` from your API routes,
scripts, or other application code.
</Note>

## 4. View workflows in the dashboard
Expand Down
10 changes: 6 additions & 4 deletions packages/docs/docs/standard-schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,10 @@ is even enqueued — preventing invalid data from entering your system.
When you define a workflow, you can provide a `schema`. OpenWorkflow uses this
schema to:

1. **Validate inputs at runtime**: When `workflow.run()` is called, the input is
validated immediately. If validation fails, an error is thrown before the
workflow is enqueued, preventing invalid data from entering your system.
1. **Validate inputs at runtime**: When you start a run (for example, with
`ow.runWorkflow(workflow.spec, input)`), the input is validated immediately.
If validation fails, an error is thrown before the workflow is enqueued,
preventing invalid data from entering your system.
2. **Type Safety**: The `input` parameter in your workflow function is
automatically typed based on your schema.

Expand Down Expand Up @@ -141,10 +142,11 @@ When validation fails, OpenWorkflow throws a detailed error that includes
information about what went wrong:

```ts
import { ow } from "./openworkflow/client";
import { sendEmail } from "./workflows/send-email";
Comment on lines +145 to 146
Copy link

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new snippet imports ow from ./openworkflow/client without an extension. The CLI init template uses ./openworkflow/client.js, which is important for Node ESM after TS->JS compilation. Consider updating this import (or noting the expected tooling like tsx) to prevent copy/paste issues.

Suggested change
import { ow } from "./openworkflow/client";
import { sendEmail } from "./workflows/send-email";
import { ow } from "./openworkflow/client.js";
import { sendEmail } from "./workflows/send-email.js";

Copilot uses AI. Check for mistakes.

try {
await sendEmail.run({
await ow.runWorkflow(sendEmail.spec, {
to: "invalid-email", // Invalid email format
subject: "", // Too short
body: "Hello",
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/docs/type-safety.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ ow.implementWorkflow(emailSpec, async ({ input, step }) => {
When you run a workflow, the handle is typed with the output:

```ts
const handle = await processOrder.run({
const handle = await ow.runWorkflow(processOrder.spec, {
orderId: "123",
customerId: "456",
});
Expand Down
26 changes: 19 additions & 7 deletions packages/docs/docs/workflows.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,25 +43,34 @@ A workflow consists of:

## Running a Workflow

Start a workflow by calling `.run()`:
Start a workflow by calling `ow.runWorkflow()` with the workflow's `spec`:

```ts
import { ow } from "./openworkflow/client";
Copy link

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The examples import ow from ./openworkflow/client without a file extension, but the CLI init templates and repo examples use ./openworkflow/client.js (ESM-safe when compiling TS to JS). Consider updating these docs to use the .js extension (or add a short note explaining when extensionless imports work, e.g. with tsx).

Suggested change
import { ow } from "./openworkflow/client";
import { ow } from "./openworkflow/client.js";

Copilot uses AI. Check for mistakes.
import { sendWelcomeEmail } from "./workflows/send-welcome-email";

const handle = await sendWelcomeEmail.run({ userId: "user_123" });
const handle = await ow.runWorkflow(sendWelcomeEmail.spec, {
userId: "user_123",
});
```

The `run()` method returns a handle immediately. The actual workflow execution
`ow.runWorkflow()` returns a handle immediately. The actual workflow execution
happens in a worker process. This lets your application continue without waiting
for the workflow to complete.

<Note>
If you define a workflow with `ow.defineWorkflow(...)` instead, it returns a
runnable workflow that supports `.run(...)` directly.
</Note>

### Scheduling a Workflow Run

You can schedule a workflow run for a specific time by passing `availableAt`:

```ts
const runAt = new Date("2026-02-05T15:00:00.000Z");
const handle = await sendWelcomeEmail.run(
const handle = await ow.runWorkflow(
sendWelcomeEmail.spec,
{ userId: "user_123" },
{ availableAt: runAt },
);
Expand All @@ -71,7 +80,8 @@ You can also pass a duration string using the same [duration
format](/docs/sleeping#duration-formats) as `step.sleep`:

```ts
const handle = await sendWelcomeEmail.run(
const handle = await ow.runWorkflow(
sendWelcomeEmail.spec,
{ userId: "user_123" },
{ availableAt: "5m" },
);
Expand All @@ -85,7 +95,9 @@ it. If `availableAt` is in the past, the run is immediately available.
If you need to wait for a workflow to complete, use `.result()` on the handle:

```ts
const handle = await sendWelcomeEmail.run({ userId: "user_123" });
const handle = await ow.runWorkflow(sendWelcomeEmail.spec, {
userId: "user_123",
});

// Wait for completion (polls the database)
const result = await handle.result();
Expand Down Expand Up @@ -183,7 +195,7 @@ The workflow function receives an object with three properties:

| Parameter | Type | Description |
| --------- | ---------------- | ------------------------------------------------- |
| `input` | Generic | The input data passed to `workflow.run()` |
| `input` | Generic | The input data passed when starting the workflow |
| `step` | `StepApi` | API for defining steps (`step.run`, `step.sleep`) |
| `version` | `string \| null` | The workflow version, if specified |

Expand Down