Durability API

createDurability(ctx, handlers, options?)

Creates a durability runtime and one typed operation method per handler.

Handler call

Every handler receives:

Field	Meaning
id	Stable call and idempotency key
operation	Registered handler name
payload	Inferred handler payload
attempt	One-based attempt number
signal	Attempt-scoped AbortSignal

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

Options

Option	Purpose
alarmConcurrency	Maximum immediate operations run by an alarm pool
backgroundConcurrency	Maximum operations run by the timer pool
alarmHandoffMs	Time before an alarm returns and hands pending work forward
attemptTimeoutMs	Default timeout for one handler attempt
retries.maxAttempts	Default total attempt limit
retries.jitter	none, equal, or full backoff jitter
methods	Per-operation timeout and retry overrides

Generated operations

For a handler named sendEmail:

await durability.sendEmail({ id, payload });
await durability.background.sendEmail({ id, payload });

const immediateResult = await durability.sendEmail.getResult(id);
const backgroundResult = await durability.background.sendEmail.getResult(id);

Both enqueue methods resolve after registration. Both result methods return:

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

durability.alarm(alarmInfo?)

Runs due calls and schedules the next alarm. Delegate the Durable Object alarm() method directly to it.

migrateDurability(ctx, target)

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

Errors

NonRetryableError

Marks the current call as terminal without another attempt.

DuplicateDurableCallError

Signals that an operation ID was reused for a different operation. IDs must be unique across the Durability instance, not only within one handler.

Lint package

@durability/lint provides Oxlint rules that enforce alarm delegation and namespaced migration ownership:

{
  "jsPlugins": [
    { "name": "durability", "specifier": "@durability/lint" }
  ],
  "rules": {
    "durability/alarm-runner-only": "error",
    "durability/durability-migrations-only": "error"
  }
}