Services Overview
services contains WOML's supervised capabilities and imported module aliases.
Built-in capabilities
WOML provides managed HTTP, SQLite/PostgreSQL, object storage, cache, durable state, events, workflow calls, workflow starts, and provider messaging.
Managed operations report bounded metadata to Rust for attempts, cancellation, limits, recovery, and stable effect identity. Results must remain JSON-compatible.
Native JavaScript remains available
Use native Bun APIs when their exact compatibility matters. For example, fetch() supports the familiar Response and streaming interface. Prefer managed services when you need a simpler bounded result and explicit operation semantics.
Why managed capabilities exist
JavaScript can contact external systems directly, but the durable engine needs an explicit boundary to supervise important effects. Managed services give operations stable names, bounded inputs and outputs, typed failures, cancellation, limits, and recoverable outcome records.
They do not make every external system exactly once. When a remote API supports idempotency, pass attempt.idempotencyKey through its reviewed idempotency mechanism.
Choose by data meaning
| Need | Service |
|---|---|
| Standard streaming Web API | Native fetch() |
| Bounded supervised HTTP | services.http.request() |
| Application records and queries | services.db() |
| Files and larger durable objects | services.storage |
| Disposable optimization data | services.cache |
| Small permanent workflow memory | services.state |
| Broadcast a fact | services.events.emit() |
| Call or start another workflow | services.workflows |
| Send a provider message | Telegram, Discord, or WhatsApp messaging service |
Handle failures
Managed failures are catchable as WomlServiceError with stable fields including code, service, operation, retryable, and ambiguous. Catch only failures your business logic can genuinely handle; otherwise let the step fail and allow its retry policy to decide.
Give repeated effectful operations in one script distinct stable names. Do not derive names from attempt number or completion order.