CloudflareDurableObjectPrograms

Class-independent Durable Object programs behind the Cloudflare cluster integration.

The bundled classes in CloudflareDurableObjects bind these behaviors to cloudflare:workers base classes for the Wrangler path. A framework that creates its own Durable Object classes (for example the Alchemy integration in AlchemyCloudflareCluster) runs these programs instead and forwards its class methods to the returned handles.

15 exports Since v4.1.3 Source

Constructors

makeClusterDurableQueueProgram

Since v4.1.3

Creates the program behind one durable queue Durable Object.

When to use

Use when a framework creates the native Durable Object class itself and needs the queue persistence, leasing, and alarm behavior without extending the bundled ClusterDurableQueue class.

Details

Run the returned Effect once per Durable Object activation. It ensures the queue table and re-arms the single alarm from the earliest pending lease expiry before returning the handler object.

Signature

declare const makeClusterDurableQueueProgram: (...args: [state: DurableObjectProgramState]) => Effect<ClusterDurableQueueProgram, never, never>

makeClusterEntityProgram

Since v4.1.3

Creates the program behind one cluster entity Durable Object.

When to use

Use when a framework creates the native Durable Object class itself and needs the entity mailbox, alarm, and same-Worker RPC behavior without extending the bundled ClusterEntity class.

Details

Run the returned Effect once per Durable Object activation, after the Worker application (the entity handler registrations) is initialized. It ensures the mailbox tables and re-arms the single alarm from the earliest pending deliver_at, or the keep-alive heartbeat when that alarm is missing, before returning the handler object. The host class must be exported from the Worker entry as ClusterEntity; keep-alive and reply delivery resolve that export through state.exports.

Signature

declare const makeClusterEntityProgram: (...args: [state: DurableObjectProgramState]) => Effect<ClusterEntityProgram, never, never>

makeClusterSingletonProgram

Since v4.1.3

Creates the program behind one cluster singleton Durable Object.

When to use

Use when a framework creates the native Durable Object class itself and needs the singleton wake and watchdog behavior without extending the bundled ClusterSingleton class.

Details

Run the returned Effect once per Durable Object activation, after the Worker application (the singleton registrations) is initialized. It ensures the singleton state table and re-arms the watchdog alarm for a wake interrupted by isolate loss before returning the handler object.

Signature

declare const makeClusterSingletonProgram: (...args: [state: DurableObjectProgramState]) => Effect<ClusterSingletonProgram, never, never>

makeClusterWorkflowProgram

Since v4.1.3

Creates the program behind one workflow execution Durable Object.

When to use

Use when a framework creates the native Durable Object class itself and needs the Effect Workflow journal, alarm, and same-Worker RPC behavior without extending the bundled ClusterWorkflow class.

Details

Run the returned Effect once per Durable Object activation, after the Worker application (the workflow handler registrations) is initialized. It ensures the workflow tables and re-arms the single alarm from the earliest pending clock before returning the handler object. The host class must be exported from the Worker entry as ClusterWorkflow; child and parent workflow delivery resolves that export through state.exports.

Signature

declare const makeClusterWorkflowProgram: (...args: [state: DurableObjectProgramState]) => Effect<ClusterWorkflowProgram, never, never>

Models

ClusterDurableQueueProgram

type

Since v4.1.3

Effect-valued program for one durable queue Durable Object.

Signature

type ClusterDurableQueueProgram = {
  readonly alarm: () => Effect.Effect<void>;
  readonly cancelTake: (takerId: string) => Effect.Effect<void>;
  readonly complete: (id: string, takerId: string) => Effect.Effect<void>;
  readonly extend: (id: string, leaseMillis: number, takerId: string) => Effect.Effect<void>;
  readonly fail: (id: string, lastFailure: string, takerId: string, terminal?: boolean, retryDelayMillis?: number) => Effect.Effect<void>;
  readonly offer: (id: string, element: string, delayMillis?: number, deduplicate?: "untilExecuted" | "untilRemoved") => Effect.Effect<void>;
  readonly release: (id: string, takerId: string) => Effect.Effect<void>;
  readonly take: (takerId: string, maxAttempts: number, leaseMillis: number) => Effect.Effect<DurableQueueItem>;
}

ClusterEntityProgram

type

Since v4.1.3

Effect-valued program for one cluster entity Durable Object instance.

Gotchas

All program methods must keep their error channel never: Alchemy encodes typed failures as envelopes, but the native namespace transport expects plain results and rejected defects.

Signature

type ClusterEntityProgram = {
  readonly acknowledge: (requestId: string, replyId: string) => Effect.Effect<ReadonlyArray<string>>;
  readonly alarm: () => Effect.Effect<void>;
  readonly deliverReply: (requestId: string, reply: string) => Effect.Effect<boolean>;
  readonly hold: () => Effect.Effect<void>;
  readonly interrupt: (storageRequestId: string, clientRequestId?: string) => Effect.Effect<void>;
  readonly invoke: (envelopeText: string, discard: boolean, delivery?: EntityDeliveryOptions) => Effect.Effect<EntityInvokeResult>;
  readonly reset: (requestId: string) => Effect.Effect<void>;
}

ClusterSingletonProgram

type

Since v4.1.3

Effect-valued program for one cluster singleton Durable Object.

Signature

type ClusterSingletonProgram = {
  readonly alarm: () => Effect.Effect<void>;
  readonly wake: () => Effect.Effect<SingletonWakeResult>;
}

ClusterWorkflowProgram

type

Since v4.1.3

Effect-valued program for one workflow execution Durable Object.

Signature

type ClusterWorkflowProgram = {
  readonly alarm: () => Effect.Effect<void>;
  readonly deferredDone: (name: string, exit: string) => Effect.Effect<void>;
  readonly interrupt: () => Effect.Effect<void>;
  readonly interruptUnsafe: () => Effect.Effect<void>;
  readonly poll: () => Effect.Effect<string | undefined>;
  readonly resume: (mode?: ClusterWorkflowWakeMode) => Effect.Effect<void>;
  readonly run: (payload: string, options: ClusterWorkflowRunOptions) => Effect.Effect<string>;
  readonly scheduleClock: (name: string, deferredName: string, wakeUp: number) => Effect.Effect<void>;
}

ClusterWorkflowRunOptions

interface

Since v4.1.3

Execution options accepted by the workflow program's run.

Signature

interface ClusterWorkflowRunOptions {
  readonly discard: boolean;
  readonly parent?: {
    readonly executionId: string;
    readonly workflowName: string;
  };
}

ClusterWorkflowWakeMode

type

Since v4.1.3

How a workflow resume was requested. "explicit" (the default) always replays the execution; "automatic", used for a child's completion wake, leaves an execution suspended by Workflow.SuspendOnFailure parked until an explicit resume.

Signature

type ClusterWorkflowWakeMode = "explicit" | "automatic"

DurableObjectProgramState

interface

Since v4.1.3

The native Durable Object capabilities a cluster program is built from.

Details

A DurableObjectState from cloudflare:workers satisfies this shape directly, so pass it as is. The program only reads the object name, opens SQLite storage, resolves same-Worker class exports, and extends the current event with waitUntil.

Signature

interface DurableObjectProgramState {
  readonly exports: object;
  readonly id: {
    readonly name?: string;
  };
  readonly storage: DurableObjectStorage;
  readonly waitUntil: (promise: Promise<unknown>) => void;
}

DurableQueueItem

interface

Since v4.1.3

Item leased from the durable queue program.

Signature

interface DurableQueueItem {
  readonly attempts: number;
  readonly element: string;
  readonly id: string;
}

EntityDeliveryOptions

interface

Since v4.1.3

Delivery options accepted by the cluster entity transport program.

Signature

interface EntityDeliveryOptions {
  readonly deliverAt?: number;
  readonly primaryKey?: string | null;
  readonly replyTo?: string;
}

EntityInvokeResult

type

Since v4.1.3

Result returned by the cluster entity transport program.

Signature

type EntityInvokeResult = {
  readonly _tag: "Success";
  readonly replies: ReadonlyArray<string>;
  readonly requestId: string;
} | {
  readonly _tag: "MailboxFull";
} | {
  readonly _tag: "EncodedMessageTooLarge";
} | {
  readonly _tag: "AskDeduplicatedToTell";
}

SingletonWakeResult

type

Since v4.1.3

How one singleton wake ended.

Details

A failed singleton run resolves wake() with a Failure instead of rejecting it, so a rejected wake() always means the call itself failed in transit and is safe to retry. Retrying a failed run would rerun user code.

Signature

type SingletonWakeResult = {
  readonly _tag: "Success";
} | {
  readonly _tag: "Failure";
  readonly message: string;
}