getWorld
Access the World instance for low-level storage, queuing, and streaming operations.
Retrieves the World instance for direct access to workflow storage, queuing, and streaming backends. This function returns a World which provides low-level access to manage workflow runs, steps, events, and hooks.
Use this function when you need direct access to the underlying workflow infrastructure, such as listing all runs, querying events, or implementing custom workflow management logic.
import { getWorld } from "workflow/runtime";
const world = getWorld();API Signature
Parameters
This function does not accept any parameters.
Returns
Returns a World object:
| Name | Type | Description |
|---|---|---|
start | () => Promise<void> | A function that will be called to start any background tasks needed by the World implementation. For example, in the case of a queue backed World, this would start the queue processing. |
getEncryptorForRun | (runId: string) => Promise<Encryptor> | Resolve an Encryptor that can encrypt/decrypt data for a specific workflow run.
This is needed when operating on data that belongs to a different deployment
context (e.g., resumeHook() called from a newer deployment targeting a
workflow run from an older deployment). The returned Encryptor uses the
correct key for the target run's deployment.
When not implemented, the World itself is used as the Encryptor (which works
for same-deployment operations). |
getDeploymentId | () => Promise<string> | |
queue | (queueName: __wkf_step_${string} | __wkf_workflow_${string}, message: { runId: string; traceCarrier?: Record<string, string> | undefined; requestedAt?: Date | undefined; } | { workflowName: string; ... 4 more ...; requestedAt?: Date | undefined; } | { ...; }, opts?: QueueOptions | undefined) => Promise<...> | Enqueues a message to the specified queue. |
createQueueHandler | (queueNamePrefix: "__wkf_step_" | "__wkf_workflow_", handler: (message: unknown, meta: { attempt: number; queueName: __wkf_step_${string} | __wkf_workflow_${string}; messageId: string & $brand<"MessageId">; }) => Promise<...>) => (req: Request) => Promise<...> | Creates an HTTP queue handler for processing messages from a specific queue. |
runs | { get(id: string, params: GetWorkflowRunParams & { resolveData: "none"; }): Promise<WorkflowRunWithoutData>; get(id: string, params?: (GetWorkflowRunParams & { ...; }) | undefined): Promise<...>; get(id: string, params?: GetWorkflowRunParams | undefined): Promise<...>; list(params: ListWorkflowRunsParams & { ...; })... | |
steps | { get(runId: string | undefined, stepId: string, params: GetStepParams & { resolveData: "none"; }): Promise<StepWithoutData>; get(runId: string | undefined, stepId: string, params?: (GetStepParams & { ...; }) | undefined): Promise<...>; get(runId: string | undefined, stepId: string, params?: GetStepParams | undefine... | |
events | { create(runId: string | null, data: { eventType: "run_created"; eventData: { deploymentId: string; workflowName: string; input: unknown; executionContext?: Record<string, any> | undefined; }; correlationId?: string | undefined; specVersion?: number | undefined; }, params?: CreateEventParams | undefined): Promise<..... | |
hooks | { get(hookId: string, params?: GetHookParams | undefined): Promise<Hook>; getByToken(token: string, params?: GetHookParams | undefined): Promise<...>; list(params: ListHooksParams): Promise<...>; } | |
writeToStream | (name: string, runId: string, chunk: string | Uint8Array<ArrayBufferLike>) => Promise<void> | |
writeToStreamMulti | (name: string, runId: string, chunks: (string | Uint8Array<ArrayBufferLike>)[]) => Promise<void> | Write multiple chunks to a stream in a single operation. This is an optional optimization for world implementations that can batch multiple writes efficiently (e.g., single HTTP request for world-vercel). If not implemented, the caller should fall back to sequential writeToStream() calls. |
closeStream | (name: string, runId: string) => Promise<void> | |
readFromStream | (name: string, startIndex?: number | undefined) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>>> | |
listStreamsByRunId | (runId: string) => Promise<string[]> | |
encrypt | (data: Uint8Array<ArrayBufferLike>, context: EncryptionContext) => Promise<Uint8Array<ArrayBufferLike>> | Encrypt data with the given context |
decrypt | (data: Uint8Array<ArrayBufferLike>, context: EncryptionContext) => Promise<Uint8Array<ArrayBufferLike>> | Decrypt data with the given context |
getKeyMaterial | (options: Record<string, unknown>) => Promise<KeyMaterial | null> | Retrieve key material for external decryption (e.g., o11y tooling) |
Examples
List Workflow Runs
List all workflow runs with pagination:
import { getWorld } from "workflow/runtime";
export async function GET(req: Request) {
const url = new URL(req.url);
const cursor = url.searchParams.get("cursor") ?? undefined;
try {
const world = getWorld();
const runs = await world.runs.list({
pagination: { cursor },
});
return Response.json(runs);
} catch (error) {
return Response.json(
{ error: "Failed to list workflow runs" },
{ status: 500 }
);
}
}Cancel a Workflow Run
Cancel a running workflow:
import { getWorld } from "workflow/runtime";
export async function POST(req: Request) {
const { runId } = await req.json();
if (!runId) {
return Response.json({ error: "No runId provided" }, { status: 400 });
}
try {
const world = getWorld();
const run = await world.runs.cancel(runId);
return Response.json({ status: run.status });
} catch (error) {
return Response.json(
{ error: "Failed to cancel workflow run" },
{ status: 500 }
);
}
}