Durability

@repo/durability registers operations in Durable Object SQLite storage and executes them through alarms or background timers. It provides stable call IDs, bounded retries, attempt timeouts, concurrency controls, and typed result lookup.

Delivery guarantee

Calls are delivered at least once. Stable IDs deduplicate completed and concurrent calls, but an external side effect can succeed before its completion record commits. Pass the call ID to external services as an idempotency key for effectively-once behavior.

Core flow

1. An operation and the first alarm are registered in one storage transaction.
2. The generated method resolves after registration commits; it does not wait for execution.
3. An alarm claims up to 100 due calls and runs them with bounded concurrency.
4. Success or terminal failure is persisted and available through getResult(id).
5. Retryable failures are scheduled with exponential backoff and jitter.

Persistent

Pending calls survive eviction and restarts in SQLite.

Typed

Handler input and output flow into enqueue and result APIs.

Bounded

Queue scans, retries, attempt duration, and concurrency have limits.

Idempotent

Stable operation IDs deduplicate concurrent and completed work.

Minimal example

import { DurableObject } from 'cloudflare:workers';
import { createDurability, type DurableHandler } from '@repo/durability';

type ResizeInput = { imageId: string };

export class ImageJobs extends DurableObject<Env> {
  private readonly durability = createDurability(this.ctx, {
    resizeImage: (async ({ id, payload, signal }) => {
      return this.env.IMAGES.resize(payload.imageId, {
        idempotencyKey: id,
        signal,
      });
    }) satisfies DurableHandler<ResizeInput, string>,
  });

  resize(imageId: string) {
    return this.durability.resizeImage({
      id: `resize:${imageId}`,
      payload: { imageId },
    });
  }

  alarm(alarmInfo?: AlarmInvocationInfo) {
    return this.durability.alarm(alarmInfo);
  }
}

Requirements

• A SQLite-backed Durable Object class.
• JSON-serializable payloads and results.
• Exclusive delegation of the class alarm to Durability.
• Stable, operation-specific IDs for safe retries.

Continue with setup and execution or review reliability semantics.