effect-cf 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # effect-cf
 
+## 0.37.0
+
+### Minor Changes
+
+- [#135](https://github.com/danieljvdm/effect-cf/pull/135) [`9dea62e`](https://github.com/danieljvdm/effect-cf/commit/9dea62e74818b7fc9da919e8bdbfcc49991aef36) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add `DurableObjectAlarm.transaction` to commit application storage and logical alarm schedule, replacement, or cancellation together in one native SQLite Durable Object transaction. Application queries can use the existing storage wrapper or a `SqlClient` from `@effect/sql-sqlite-do` backed by the same object. The callback receives transaction-only alarm mutations and preserves the caller's success value, typed errors, and service requirements.
+
+  Failures before commit roll back application rows, logical alarms, and native alarm reconciliation together. Interruption or a lost reply after commit does not undo committed state. Keep external effects outside the transaction and durably pre-arm a later wake before fallible external work; Cloudflare's native alarm retries remain bounded.
+
 ## 0.36.0
 
 ### Minor Changes

package/README.md

@@ -47,6 +47,8 @@ Declare `SETTINGS` in `wrangler.jsonc` and pass `SettingsLive` to `Worker.make`.
 
 The [counter example](https://github.com/danieljvdm/effect-cf/tree/main/examples/counter) shows `DurableObject.Tag`, storage, a typed RPC call, and the complete Wrangler configuration.
 
+For atomic application writes and alarm changes, see the [alarm transaction example](tests/fixtures/alarm-transaction-consumer.ts) and [API contract](src/DurableObjectAlarm.ts).
+
 ## Native RPC tracing
 
 `call()`, `scopedCall()`, and definition methods create one CLIENT span named `binding/method`, covering argument encoding, the native RPC wait, and success decoding. Raw `rpc()` retains Cloudflare's pipelined result without creating a span. Wrap its complete lifetime with `RpcTracing.withRpcClientSpan` when tracing raw calls.

package/dist/ComputerWorkspace.mjs

@@ -1,4 +1,4 @@
-import { t as DurableObjectState } from "./DurableObjectState-DCh4PZMN.mjs";
+import { t as DurableObjectState } from "./DurableObjectState-DLL0YgBd.mjs";
 import { fromClient } from "./ComputerArtifacts.mjs";
 import { t as lookup } from "./ComputerWorkspaceHostRegistry-CY5Fv4Ng.mjs";
 import { Context, Effect, Layer, Predicate, Schema, Stream } from "effect";

package/dist/{DurableObjectState-DCh4PZMN.mjs → DurableObjectState-DLL0YgBd.mjs}

@@ -288,4 +288,4 @@ const runExitPreservingTypedFailures = async (run, effect) => {
 	return exit;
 };
 //#endregion
-export { DurableWebSocketAttachmentError as a, DurableObjectWebSocket_exports as i, DurableObjectState_exports as n, fromWebSocket as o, fromDurableObjectState as r, DurableObjectStorage_exports as s, DurableObjectState as t };
+export { DurableWebSocketAttachmentError as a, StorageOperationError as c, DurableObjectWebSocket_exports as i, DurableObjectState_exports as n, fromWebSocket as o, fromDurableObjectState as r, DurableObjectStorage_exports as s, DurableObjectState as t };

package/dist/Vitest.mjs

@@ -1,6 +1,6 @@
 import { a as WorkerEnvironment, i as WorkerConfig } from "./ErrorMessage-Byx2OgNd.mjs";
 import { r as runNativeCallback } from "./WorkerContext-Yobnfw-K.mjs";
-import { r as fromDurableObjectState, t as DurableObjectState } from "./DurableObjectState-DCh4PZMN.mjs";
+import { r as fromDurableObjectState, t as DurableObjectState } from "./DurableObjectState-DLL0YgBd.mjs";
 import { ConfigProvider, Effect, Exit, Layer } from "effect";
 import { env } from "cloudflare:workers";
 import { abortAllDurableObjects as abortAllDurableObjects$1, adminSecretsStore as adminSecretsStore$1, applyD1Migrations as applyD1Migrations$1, createExecutionContext, createMessageBatch, createPagesEventContext, createScheduledController, evictAllDurableObjects as evictAllDurableObjects$1, evictDurableObject as evictDurableObject$1, getQueueResult, introspectWorkflow as introspectWorkflow$1, introspectWorkflowInstance as introspectWorkflowInstance$1, listDurableObjectIds as listDurableObjectIds$1, reset as reset$1, runDurableObjectAlarm as runDurableObjectAlarm$1, runInDurableObject as runInDurableObject$1, waitOnExecutionContext } from "cloudflare:test";

package/dist/index.d.mts

@@ -853,7 +853,7 @@ type DurableObjectClass<Rpc extends DurableObjectRpc<ROut>, ROut> = new (state:
  */
 declare const make$6: <ROut, LayerError, REvent = never, EventLayerError = never, const Rpc extends DurableObjectRpc<ROut | REvent> = Record<never, never>>(layer: Layer.Layer<ROut, LayerError, DurableObjectState | WorkerEnvironment>, options?: DurableObjectOptions<ROut, REvent, EventLayerError, Rpc>) => DurableObjectClass<Rpc, ROut | REvent>;
 declare namespace DurableObjectAlarm_d_exports {
-  export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRetryPolicy, AlarmScheduler, DefinedAlarmEvent, DefinedAlarmHandlers, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsMode, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, StoredAlarmDecodeError, define, processDue };
+  export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRetryPolicy, AlarmScheduler, AlarmTransaction, DefinedAlarmEvent, DefinedAlarmHandlers, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsMode, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, StoredAlarmDecodeError, define, processDue };
 }
 type AlarmPayload = Schema.Json;
 declare const InvalidAlarmRefError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
@@ -946,8 +946,26 @@ interface ProcessDueAlarmsOptions<OnFailureR = never, OnFailureE = never> {
   readonly retryFailedAfter?: Duration.Input;
 }
 type ProcessDueAlarmsHandler<R = never, E = never> = (event: DurableObjectAlarmEvent) => Effect.Effect<void, E, R>;
+/**
+ * Alarm mutations owned by one transaction callback. Run them in the callback's
+ * fiber; forked work and use after the callback ends fail with StorageOperationError.
+ */
+type AlarmTransaction = Pick<AlarmScheduler, "scheduleAlarm" | "cancelAlarm">;
 /** Own `storage.setAlarm()` exclusively: a Durable Object has one platform alarm timestamp. */
 type AlarmScheduler = {
+  /**
+   * Commits local application storage and logical alarms in one native SQLite
+   * Durable Object transaction, reconciling the native alarm before commit.
+   * Use the supplied mutations, not standalone alarm methods or nested transactions.
+   * SqlClient queries must use this same Durable Object's storage.
+   *
+   * Failure, defects and interruption before commit roll back. A lost reply or
+   * interruption after commit does not undo committed state. Keep RPC and other
+   * external effects outside; atomically pre-arm a later wake before fallible work.
+   * Cloudflare's native retries are bounded; composition does not remove the
+   * pre-arm requirement or promise infinite retry liveness.
+   */
+  readonly transaction: <A, E, R>(closure: (alarms: AlarmTransaction) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StorageOperationError, R>;
   readonly cancelAlarm: (input: AlarmRef) => Effect.Effect<void, InvalidAlarmRefError | StorageOperationError>;
   /** Acknowledge after handling. Conditional writes preserve handler replacements; alarms are at-least-once. */
   readonly processDueAlarms: <R = never, E = never, OnFailureR = never, OnFailureE = never>(handle: ProcessDueAlarmsHandler<R, E>, options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>) => Effect.Effect<ProcessDueAlarmsResult, E | OnFailureE | DurableObjectAlarmError, R | OnFailureR>;

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { a as WorkerEnvironment, i as WorkerConfig, n as violationsMessage, r as
 import { n as Service$1, r as layer$17, t as Binding_exports } from "./Binding-C82jRhdr.mjs";
 import { n as Artifacts_exports } from "./Artifacts-CBxWGeZB.mjs";
 import { t as fromExecutionContext } from "./WorkerContext-Yobnfw-K.mjs";
-import { a as DurableWebSocketAttachmentError, i as DurableObjectWebSocket_exports, n as DurableObjectState_exports, o as fromWebSocket, r as fromDurableObjectState, s as DurableObjectStorage_exports, t as DurableObjectState } from "./DurableObjectState-DCh4PZMN.mjs";
+import { a as DurableWebSocketAttachmentError, c as StorageOperationError, i as DurableObjectWebSocket_exports, n as DurableObjectState_exports, o as fromWebSocket, r as fromDurableObjectState, s as DurableObjectStorage_exports, t as DurableObjectState } from "./DurableObjectState-DLL0YgBd.mjs";
 import { A as QueueDefinition_exports, C as decodeSuccess, D as method$1, E as make$15, O as reservedMethodNames$2, S as decodeArgs, T as encodeSuccess, _ as RpcTracing_exports, a as WorkerDefinition_exports, b as RpcDefinition_exports, c as resolve, d as makeEntrypointRuntime, f as runEventPromise, g as recordDecodedArgs, h as invokeRpcMethod, i as Worker_exports, j as QueueBinding_exports, k as Queue_exports, l as scoped, m as defineEntrypointRpcMethods, n as NativeRequest, o as ServiceBinding_exports, p as assumeEntrypointClass, r as WorkerContext, s as Rpc_exports, t as ExecutionContext, u as scheduleTelemetryFlush$1, v as withRpcClientSpan, w as encodeArgs, x as assertNoReservedMethods, y as withRpcTraceContext } from "./Worker-XsGJsCJX.mjs";
 import { Cause, Clock, Config, ConfigProvider, Context, Data, DateTime, Duration, Effect, Exit, FiberSet, Function as Function$1, Layer, Option, Predicate, Queue, Result, Schema, Tracer } from "effect";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
@@ -1430,25 +1430,35 @@ var DurableObjectAlarm = class DurableObjectAlarm extends Context.Service()("eff
 		});
 		const cancelAlarm = Effect.fn("DurableObjectAlarm.cancelAlarm")(function* (input) {
 			const ref = yield* decodeAlarmRef(input);
-			yield* state.storage.transaction(() => Effect.gen(function* () {
-				yield* ensureTable(state);
-				yield* state.storage.sql.exec(`DELETE FROM effect_cf_scheduled_alarms WHERE storage_id = ?`, getScheduledEventId(ref)).pipe(Effect.asVoid);
-				yield* reconcileAlarm();
-			}));
+			yield* state.storage.sql.exec(`DELETE FROM effect_cf_scheduled_alarms WHERE storage_id = ?`, getScheduledEventId(ref));
 		});
 		const scheduleAlarm = Effect.fn("DurableObjectAlarm.scheduleAlarm")(function* (input) {
 			const ref = yield* decodeAlarmRef(input);
 			const repeatEveryMillis = yield* toRepeatEveryMillis(input.repeatEvery);
 			const payload = yield* encodeStoredPayload(input.payload);
 			const runAt = DateTime.toEpochMillis(input.runAt);
-			yield* state.storage.transaction(() => Effect.gen(function* () {
-				yield* ensureTable(state);
-				yield* state.storage.sql.exec(`INSERT OR REPLACE INTO effect_cf_scheduled_alarms
+			yield* state.storage.sql.exec(`INSERT OR REPLACE INTO effect_cf_scheduled_alarms
                    (storage_id, alarm_id, tag, run_at, repeat_every_ms, payload)
-                 VALUES (?, ?, ?, ?, ?, ?)`, getScheduledEventId(ref), ref.id, ref.tag, runAt, repeatEveryMillis, payload).pipe(Effect.asVoid);
-				yield* reconcileAlarm();
-			}));
+                 VALUES (?, ?, ?, ?, ?, ?)`, getScheduledEventId(ref), ref.id, ref.tag, runAt, repeatEveryMillis, payload);
 		});
+		const transaction = (closure) => state.storage.transaction(() => Effect.withFiber((owner) => {
+			let active = true;
+			const requireActive = (effect) => Effect.withFiber((fiber) => active && fiber === owner ? effect : Effect.fail(new StorageOperationError({
+				operation: "alarm.transaction",
+				cause: /* @__PURE__ */ new Error("Alarm mutations require their active transaction callback")
+			})));
+			return Effect.gen(function* () {
+				yield* ensureTable(state);
+				const result = yield* Effect.suspend(() => closure({
+					cancelAlarm: (input) => requireActive(cancelAlarm(input)),
+					scheduleAlarm: (input) => requireActive(scheduleAlarm(input))
+				})).pipe(Effect.ensuring(Effect.sync(() => {
+					active = false;
+				})));
+				yield* reconcileAlarm();
+				return result;
+			});
+		}));
 		const processDueAlarms = Effect.fn("DurableObjectAlarm.processDueAlarms")(function* (handle, options) {
 			yield* ensureTable(state);
 			const mode = options?.mode ?? "isolated";
@@ -1507,9 +1517,10 @@ var DurableObjectAlarm = class DurableObjectAlarm extends Context.Service()("eff
 			};
 		});
 		return DurableObjectAlarm.of({
-			cancelAlarm,
+			cancelAlarm: (input) => transaction((alarms) => alarms.cancelAlarm(input)),
 			processDueAlarms,
-			scheduleAlarm
+			scheduleAlarm: (input) => transaction((alarms) => alarms.scheduleAlarm(input)),
+			transaction
 		});
 	}).pipe(Effect.withSpan("DurableObjectAlarm.layer")));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {

package/src/DurableObjectAlarm.ts

@@ -12,7 +12,7 @@ import {
 } from "effect";
 
 import { DurableObjectState } from "./DurableObjectState";
-import type { SqlStorageValue, StorageOperationError } from "./DurableObjectStorage";
+import { type SqlStorageValue, StorageOperationError } from "./DurableObjectStorage";
 import * as ErrorMessage from "./internal/ErrorMessage";
 
 const INIT_TABLE_SQL = `
@@ -177,8 +177,30 @@ export type ProcessDueAlarmsHandler<R = never, E = never> = (
   event: DurableObjectAlarmEvent,
 ) => Effect.Effect<void, E, R>;
 
+/**
+ * Alarm mutations owned by one transaction callback. Run them in the callback's
+ * fiber; forked work and use after the callback ends fail with StorageOperationError.
+ */
+export type AlarmTransaction = Pick<AlarmScheduler, "scheduleAlarm" | "cancelAlarm">;
+
 /** Own `storage.setAlarm()` exclusively: a Durable Object has one platform alarm timestamp. */
 export type AlarmScheduler = {
+  /**
+   * Commits local application storage and logical alarms in one native SQLite
+   * Durable Object transaction, reconciling the native alarm before commit.
+   * Use the supplied mutations, not standalone alarm methods or nested transactions.
+   * SqlClient queries must use this same Durable Object's storage.
+   *
+   * Failure, defects and interruption before commit roll back. A lost reply or
+   * interruption after commit does not undo committed state. Keep RPC and other
+   * external effects outside; atomically pre-arm a later wake before fallible work.
+   * Cloudflare's native retries are bounded; composition does not remove the
+   * pre-arm requirement or promise infinite retry liveness.
+   */
+  readonly transaction: <A, E, R>(
+    closure: (alarms: AlarmTransaction) => Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E | StorageOperationError, R>;
+
   readonly cancelAlarm: (
     input: AlarmRef,
   ) => Effect.Effect<void, InvalidAlarmRefError | StorageOperationError>;
@@ -523,17 +545,9 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
       const cancelAlarm = Effect.fn("DurableObjectAlarm.cancelAlarm")(function* (input: AlarmRef) {
         const ref = yield* decodeAlarmRef(input);
 
-        yield* state.storage.transaction(() =>
-          Effect.gen(function* () {
-            yield* ensureTable(state);
-            yield* state.storage.sql
-              .exec(
-                `DELETE FROM effect_cf_scheduled_alarms WHERE storage_id = ?`,
-                getScheduledEventId(ref),
-              )
-              .pipe(Effect.asVoid);
-            yield* reconcileAlarm();
-          }),
+        yield* state.storage.sql.exec(
+          `DELETE FROM effect_cf_scheduled_alarms WHERE storage_id = ?`,
+          getScheduledEventId(ref),
         );
       });
 
@@ -545,27 +559,62 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
         const payload = yield* encodeStoredPayload(input.payload);
         const runAt = DateTime.toEpochMillis(input.runAt);
 
-        yield* state.storage.transaction(() =>
-          Effect.gen(function* () {
-            yield* ensureTable(state);
-            yield* state.storage.sql
-              .exec(
-                `INSERT OR REPLACE INTO effect_cf_scheduled_alarms
+        yield* state.storage.sql.exec(
+          `INSERT OR REPLACE INTO effect_cf_scheduled_alarms
                    (storage_id, alarm_id, tag, run_at, repeat_every_ms, payload)
                  VALUES (?, ?, ?, ?, ?, ?)`,
-                getScheduledEventId(ref),
-                ref.id,
-                ref.tag,
-                runAt,
-                repeatEveryMillis,
-                payload,
-              )
-              .pipe(Effect.asVoid);
-            yield* reconcileAlarm();
-          }),
+          getScheduledEventId(ref),
+          ref.id,
+          ref.tag,
+          runAt,
+          repeatEveryMillis,
+          payload,
         );
       });
 
+      const transaction: AlarmScheduler["transaction"] = (closure) =>
+        state.storage.transaction(() =>
+          Effect.withFiber((owner) => {
+            let active = true;
+
+            // A callback-owned handle cannot escape via a returned Effect or a
+            // detached fiber and write after reconciliation or rollback.
+            const requireActive = <A, E>(effect: Effect.Effect<A, E>) =>
+              Effect.withFiber<A, E | StorageOperationError>((fiber) =>
+                active && fiber === owner
+                  ? effect
+                  : Effect.fail(
+                      new StorageOperationError({
+                        operation: "alarm.transaction",
+                        cause: new Error(
+                          "Alarm mutations require their active transaction callback",
+                        ),
+                      }),
+                    ),
+              );
+
+            return Effect.gen(function* () {
+              yield* ensureTable(state);
+              const result = yield* Effect.suspend(() =>
+                closure({
+                  cancelAlarm: (input) => requireActive(cancelAlarm(input)),
+                  scheduleAlarm: (input) => requireActive(scheduleAlarm(input)),
+                }),
+              ).pipe(
+                Effect.ensuring(
+                  Effect.sync(() => {
+                    active = false;
+                  }),
+                ),
+              );
+
+              yield* reconcileAlarm();
+
+              return result;
+            });
+          }),
+        );
+
       const processDueAlarms = Effect.fn("DurableObjectAlarm.processDueAlarms")(function* <
         R,
         E,
@@ -669,9 +718,10 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
       });
 
       return DurableObjectAlarm.of({
-        cancelAlarm,
+        cancelAlarm: (input) => transaction((alarms) => alarms.cancelAlarm(input)),
         processDueAlarms,
-        scheduleAlarm,
+        scheduleAlarm: (input) => transaction((alarms) => alarms.scheduleAlarm(input)),
+        transaction,
       });
     }).pipe(Effect.withSpan("DurableObjectAlarm.layer")),
   );