Durability API

createDurability(ctx, handlers, options?)

Creates typed operation methods and one alarm handler. The operation map is inferred from handlers; named scheduler methods are inferred from options.alarms.

Operation handler

type DurableHandler<TPayload, TResult> = (
  call: DurableCall<TPayload>
) => TResult | Promise<TResult>;

DurableCall field	Meaning
id	Stable caller-provided idempotency key
operation	Handler name
payload	JSON-serializable typed input
attempt	One-based attempt number
signal	Attempt-scoped timeout signal

Generated operation

For a sendEmail handler:

await durability.sendEmail({ id, payload });
const state = await durability.sendEmail.getResult(id);

Registration resolves after its storage transaction. getResult returns one of:

• { status: 'not_found' }
• { status: 'pending', attempt, nextAttemptAt, lastError }
• { status: 'failed', attempt, error }
• { status: 'completed', result }

Options

Option	Default	Purpose
alarms	none	Named logical alarm handlers
alarmMethods	none	Per-name timeout, retry, and retryTimeouts overrides
alarmConcurrency	10	Maximum immediate operations executed concurrently
alarmHandoffMs	14 minutes	Time before unfinished work is handed to a fresh alarm invocation
attemptTimeoutMs	5 minutes	Maximum duration of one attempt
methods	none	Per-operation timeout and retry overrides
retries.maxAttempts	5	Total attempts, including the first
retries.delay	jittered exponential	Delay function returning milliseconds

Named alarm handler

type DurableAlarmHandler = (
  info: DurableAlarmInfo
) => unknown | Promise<unknown>;

Schedule a configured name with a Unix timestamp in milliseconds:

await durability.alarm.cleanup(Date.now() + 60_000);

Call durability.alarm(info?) from the Durable Object’s platform alarm callback.

Migrations

migrateDurability(ctx, target)

Moves the package schema to a named migration or null for complete rollback.

durabilityMigrations

Exposes the ordered package migration list for inspection. createDurability normally applies it automatically.

Utilities

Import retry helpers from durability/utils:

import { exponential, jitter } from 'durability/utils';

Errors

Error	Meaning
NonRetryableError	Fail the operation or named alarm without another attempt
DuplicateDurableCallError	An ID belongs to a different operation
DurableAttemptTimeoutError	An operation exceeded its attempt timeout
DurableAlarmTimeoutError	A named alarm exceeded its attempt timeout

Persisted terminal errors retain their serialized name and message.