Skip to content

Commit cd03f0b

Browse files
committed
docs: absorb unique accuracy fixes from PR #1200
Cherry-picked 6 still-needed fixes from #1200 that aren't covered by this audit PR or #1516: - Fix npx workflow description (observability) - Remove fetch from restricted modules list (errors) - Fix package name @workflow-worlds/postgres → @workflow/world-postgres (deploying) - Fix stream wording (foundations/starting-workflows) - Fix import path simple → simple-streaming (foundations/streaming) - Add close(), getEncryptionKeyForRun(), writeToStreamMulti() to World interface, update create() and streamer signatures (deploying/building-a-world)
1 parent 533c85b commit cd03f0b

6 files changed

Lines changed: 22 additions & 12 deletions

File tree

docs/content/docs/deploying/building-a-world.mdx

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,13 @@ A World connects workflows to the infrastructure that powers them. The World int
3434
```typescript
3535
interface World extends Storage, Queue, Streamer {
3636
start?(): Promise<void>;
37+
close?(): Promise<void>;
38+
getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
39+
getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
3740
}
3841
```
3942

40-
The optional `start()` method initializes any background tasks needed by your World (e.g., queue polling).
43+
The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
4144

4245
## The Event Log Model
4346

@@ -63,8 +66,8 @@ interface Storage {
6366
};
6467

6568
events: {
66-
// Create a new workflow run (runId must be null - server generates it)
67-
create(runId: null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
69+
// Create a new workflow run (runId may be client-provided or null for server generation)
70+
create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
6871

6972
// Create an event for an existing run
7073
create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
@@ -88,7 +91,7 @@ interface Storage {
8891
2. Atomically update the affected entity (run, step, or hook)
8992
3. Return both the created event and the updated entity
9093

91-
**Run Creation:** For `run_created` events, the `runId` parameter is `null`. Your World generates and returns a new `runId`.
94+
**Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
9295

9396
**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.
9497

@@ -165,13 +168,19 @@ The Streamer interface enables real-time data streaming:
165168
interface Streamer {
166169
writeToStream(
167170
name: string,
168-
runId: string | Promise<string>,
171+
runId: string,
169172
chunk: string | Uint8Array
170173
): Promise<void>;
171174

175+
writeToStreamMulti?(
176+
name: string,
177+
runId: string,
178+
chunks: (string | Uint8Array)[]
179+
): Promise<void>;
180+
172181
closeStream(
173182
name: string,
174-
runId: string | Promise<string>
183+
runId: string
175184
): Promise<void>;
176185

177186
readFromStream(
@@ -202,6 +211,7 @@ interface Streamer {
202211
```
203212

204213
Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
214+
`writeToStreamMulti()` is an optional optimization for batching multiple writes.
205215

206216
`getStreamChunks` returns a paginated snapshot of currently available chunks (unlike `readFromStream` which returns a live `ReadableStream` that waits for new chunks). `getStreamInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
207217

docs/content/docs/deploying/index.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ For self-hosting or deploying to other cloud providers, you can use community-ma
7373
To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
7474

7575
```bash
76-
export WORKFLOW_TARGET_WORLD=@workflow-worlds/postgres
76+
export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
7777
# Plus any world-specific configuration
7878
export DATABASE_URL=postgres://...
7979
```
@@ -89,7 +89,7 @@ The [Observability tools](/docs/observability) work with any World backend. By d
8989
npx workflow inspect runs
9090

9191
# Inspect remote workflows
92-
npx workflow inspect runs --backend @workflow-worlds/postgres
92+
npx workflow inspect runs --backend @workflow/world-postgres
9393
```
9494

9595
Learn more about [Observability](/docs/observability) tools.

docs/content/docs/errors/node-js-module-in-workflow.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ async function read(filePath: string) {
6969
These common Node.js core modules cannot be used in workflow functions:
7070

7171
- File system: `fs`, `path`
72-
- Network: `http`, `https`, `net`, `dns`, `fetch`
72+
- Network: `http`, `https`, `net`, `dns`
7373
- Process: `child_process`, `cluster`
7474
- Crypto: `crypto` (use Web Crypto API instead)
7575
- Operating system: `os`

docs/content/docs/foundations/starting-workflows.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ export async function POST(request: Request) {
144144
}
145145
```
146146

147-
Your workflow can write to the stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
147+
Your workflow can obtain a writable stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
148148

149149
```typescript lineNumbers
150150
import { getWritable } from "workflow";

docs/content/docs/foundations/streaming.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Use the `Run` object's `readable` property to consume the stream from your API r
4444

4545
```typescript title="app/api/stream/route.ts" lineNumbers
4646
import { start } from "workflow/api";
47-
import { simpleStreamingWorkflow } from "./workflows/simple";
47+
import { simpleStreamingWorkflow } from "./workflows/simple-streaming";
4848

4949
export async function POST() {
5050
const run = await start(simpleStreamingWorkflow);

docs/content/docs/observability/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Workflow DevKit provides powerful tools to inspect, monitor, and debug your work
1818
npx workflow
1919
```
2020

21-
The CLI comes pre-installed with the Workflow DevKit and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will install it globally, or use the local installed version if available.
21+
The CLI comes pre-installed with the Workflow DevKit and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the local installed version if available.
2222

2323
Get started inspecting your local workflows:
2424

0 commit comments

Comments
 (0)