API Reference
Complete API reference for Worlds Engine
API Reference
World Class
The main entry point for the engine.
new World(config?: WorldConfig)
Methods
register(...items: (Workflow | Activity)[]): void- Register workflows and activitiesstart(): Promise<void>- Start the world and workersshutdown(): Promise<void>- Gracefully shut downexecute<T, R>(name: string, input: T, options?: WorkflowOptions): Promise<WorkflowHandle<R>>- Execute a workflowquery(workflowId: string): Promise<WorkflowState>- Get workflow statequeryWorkflows(filters: WorkflowQueryFilter): Promise<WorkflowState[]>- Query multiple workflowsschedule(id: string, name: string, input: any, cron: string): Promise<void>- Schedule a recurring workflowgetMetrics(): WorldMetrics- Get current metricsgetWorkers(): WorkerInfo[]- Get worker status
Workflow Functions
workflow()
Creates a workflow definition.
workflow<T, R>(
name: string,
handler: (ctx: WorkflowContext, input: T) => Promise<R>,
options?: WorkflowOptions
): Workflow<T, R>
activity()
Creates an activity definition.
activity<T, R>(
name: string,
handler: (ctx: ActivityContext, input: T) => Promise<R>,
options?: ActivityOptions
): Activity<T, R>
Workflow Context
Available inside workflow handlers.
interface WorkflowContext {
// Execution
run<T, R>(activity: Activity<T, R>, input: T): Promise<R>;
executeChild<T, R>(name: string, input: T, options?: WorkflowOptions): Promise<WorkflowHandle<R>>;
// Saga Pattern
addCompensation(fn: () => Promise<void>): void;
// Control Flow
sleep(ms: number): Promise<void>;
isCancelled(): boolean;
// External Integration
fetch(url: string, init?: RequestInit): Promise<Response>;
createHook<T>(): Promise<Hook<T>>;
createWebhook(): Promise<Webhook>;
getWritable(): WritableStream<any>;
// Metadata
getMetadata(): WorkflowMetadata;
workflowId: string;
runId: string;
parentId?: string;
}
Workflow Dev Kit API
Alternative functional API.
import {
getWorkflowMetadata,
getStepMetadata,
sleep,
fetch,
createHook,
defineHook,
createWebhook,
getWritable
} from 'worlds-engine';
getWorkflowMetadata()- Returns context about current workflow executiongetStepMetadata()- Returns context about current step executionsleep(ms)- Suspends workflow deterministicallyfetch(url)- Makes HTTP requests with automatic retrycreateHook<T>()- Creates low-level hookdefineHook<T>()- Creates type-safe hook factorycreateWebhook()- Suspends workflow until HTTP request receivedgetWritable()- Accesses current workflow run default stream
Runtime API
Functions used outside workflow handlers.
import {
start,
resumeHook,
resumeWebhook,
getRun,
queryRuns,
initializeRuntime
} from 'worlds-engine';
start(name, input, options)- Enqueues new workflow runresumeHook(token, payload)- Resumes workflow via hookresumeWebhook(token, request)- Resumes workflow via webhookgetRun(workflowId)- Gets status without waitingqueryRuns(filters)- Filters multiple workflow runsinitializeRuntime(world)- Connects runtime API to world instance
Type Definitions
Configuration Types
interface WorldConfig {
minWorkers?: number;
maxWorkers?: number;
scaleThreshold?: number;
scaleDownThreshold?: number;
persistence?: 'memory' | 'file' | 'hybrid';
persistencePath?: string;
failureStrategy?: FailureStrategy;
heartbeatInterval?: number;
heartbeatTimeout?: number;
}
interface WorkflowOptions {
retry?: RetryConfig;
timeout?: string | number;
failureStrategy?: FailureStrategy;
taskQueue?: string;
priority?: number;
}
Metric Types
interface WorldMetrics {
uptime: number;
workers: {
total: number;
idle: number;
busy: number;
};
workflows: {
queued: number;
running: number;
completed: number;
failed: number;
};
throughput: {
perMinute: number;
perHour: number;
};
workload: number;
}