effect-cf 0.0.3 → 0.1.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-import { Cause, Config, ConfigProvider, Context, Data, Effect, Exit, Layer, ManagedRuntime, Option, Queue, Schema } from "effect";
+import { Cause, Clock, Config, ConfigProvider, Context, Data, DateTime, Duration, Effect, Exit, Layer, ManagedRuntime, Option, Queue, Schema } from "effect";
 import { DurableObject, RpcStub, RpcTarget, WorkerEntrypoint } from "cloudflare:workers";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import * as RpcMessage from "effect/unstable/rpc/RpcMessage";
@@ -484,9 +484,7 @@ const make$3 = (layer, options) => {
 			const fetchHandler = options.fetch;
 			if (fetchHandler === void 0) return Promise.resolve(new Response("Not Found", { status: 404 }));
 			const requestServices = Layer.mergeAll(Layer.succeed(NativeRequest, request), Layer.succeed(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromWeb(request)));
-			const fetchEffect = renderFetchSuccess(fetchHandler);
-			const requestEffect = options.requestLayer === void 0 ? fetchEffect : fetchEffect.pipe(Effect.provide(options.requestLayer));
-			return this[RunSymbol$1](requestEffect.pipe(Effect.provide(requestServices)));
+			return this[RunSymbol$1](renderFetchSuccess(fetchHandler).pipe(Effect.provide(requestServices)));
 		}
 	}
 	defineEntrypointRpcMethods("Worker", EffectWorker.prototype, options.rpc, reservedMethodNames$2, (self, effect) => self[RunSymbol$1](effect));
@@ -912,7 +910,14 @@ const make$1 = (layer, options = {}) => {
 			return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request));
 		}
 		alarm(alarmInfo) {
-			if (options.alarm !== void 0) return this[RunSymbol](options.alarm(alarmInfo));
+			const logicalAlarms = options.alarms?.pipe(Effect.asVoid);
+			const rawAlarm = options.alarm?.(alarmInfo);
+			if (logicalAlarms !== void 0 && rawAlarm !== void 0) return this[RunSymbol](Effect.gen(function* () {
+				yield* logicalAlarms;
+				yield* rawAlarm;
+			}));
+			if (logicalAlarms !== void 0) return this[RunSymbol](logicalAlarms);
+			if (rawAlarm !== void 0) return this[RunSymbol](rawAlarm);
 		}
 		webSocketMessage(socket, message) {
 			if (options.webSocketMessage !== void 0) return this[RunSymbol](options.webSocketMessage(socket, message));
@@ -931,6 +936,328 @@ const Tag = Tag$1;
 const method = method$1;
 const implement = implement$1;
 //#endregion
+//#region src/DurableObjectAlarm.ts
+var DurableObjectAlarm_exports = /* @__PURE__ */ __exportAll({
+	DurableObjectAlarm: () => DurableObjectAlarm,
+	DurableObjectAlarmEvent: () => DurableObjectAlarmEvent,
+	InvalidAlarmPayloadError: () => InvalidAlarmPayloadError,
+	InvalidAlarmRefError: () => InvalidAlarmRefError,
+	InvalidProcessDueAlarmsOptionsError: () => InvalidProcessDueAlarmsOptionsError,
+	InvalidRepeatEveryError: () => InvalidRepeatEveryError,
+	StoredAlarmDecodeError: () => StoredAlarmDecodeError,
+	define: () => define,
+	process: () => process,
+	processDue: () => processDue
+});
+const INIT_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS effect_cf_scheduled_alarms (
+  storage_id TEXT PRIMARY KEY,
+  alarm_id TEXT NOT NULL,
+  tag TEXT NOT NULL,
+  run_at INTEGER NOT NULL,
+  repeat_every_ms INTEGER,
+  payload TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_effect_cf_scheduled_alarms_run_at_storage_id
+  ON effect_cf_scheduled_alarms (run_at, storage_id);
+`;
+const DEFAULT_PROCESS_DUE_ALARMS_LIMIT = 100;
+const DEFAULT_PROCESS_DUE_ALARMS_FAILURE_RESCHEDULE_AFTER = "30 seconds";
+const getScheduledEventId = (input) => `effect-cf-alarm:${encodeURIComponent(input.tag)}:${encodeURIComponent(input.id)}`;
+var InvalidAlarmRefError = class extends Data.TaggedError("InvalidAlarmRefError") {};
+var InvalidAlarmPayloadError = class extends Data.TaggedError("InvalidAlarmPayloadError") {};
+var InvalidRepeatEveryError = class extends Data.TaggedError("InvalidRepeatEveryError") {};
+var InvalidProcessDueAlarmsOptionsError = class extends Data.TaggedError("InvalidProcessDueAlarmsOptionsError") {};
+var StoredAlarmDecodeError = class extends Data.TaggedError("StoredAlarmDecodeError") {};
+/**
+* Events handled by `processDueAlarms`.
+*
+* `AlarmDue` represents one durable alarm whose scheduled time is now due. The
+* `tag` is the consumer-owned routing key, while `id` is the stable alarm id
+* within that tag.
+*
+* `scheduledAt` is the logical due-after timestamp from durable storage. It is
+* not expected to match the current Durable Object alarm invocation time,
+* especially during retries. Retries re-scan durable rows with `run_at <= now`
+* and identify logical events by `{ tag, id }`.
+*
+* @example Handling events by tag
+* ```ts
+* yield* durableObjectAlarm.processDueAlarms((event) =>
+*   event.tag === "heartbeat"
+*     ? heartbeatManager.handleAlarmEvent(event).pipe(Effect.asVoid)
+*     : Effect.void
+* );
+* ```
+*/
+const DurableObjectAlarmEvent = Schema.TaggedUnion({ AlarmDue: {
+	id: Schema.NonEmptyString,
+	payload: Schema.Json,
+	scheduledAt: Schema.DateTimeUtc,
+	tag: Schema.NonEmptyString
+} });
+const AlarmRefSchema = Schema.Struct({
+	id: Schema.NonEmptyString,
+	tag: Schema.NonEmptyString
+});
+const decodeAlarmRef = (input) => Schema.decodeUnknownEffect(AlarmRefSchema)(input).pipe(Effect.mapError((cause) => new InvalidAlarmRefError({ cause })));
+const StoredPayloadString = Schema.fromJsonString(Schema.Json);
+const decodeStoredPayload = (row) => Schema.decodeUnknownEffect(StoredPayloadString)(row.payload).pipe(Effect.mapError((cause) => new StoredAlarmDecodeError({
+	cause,
+	storageId: row.storage_id
+})));
+const encodeStoredPayload = (payload) => Schema.encodeEffect(StoredPayloadString)(payload).pipe(Effect.mapError((cause) => new InvalidAlarmPayloadError({ cause })));
+const ensureTable = (state) => state.storage.sql.exec(INIT_TABLE_SQL).pipe(Effect.asVoid);
+const toRepeatEveryMillis = (input) => {
+	if (input === void 0) return Effect.succeed(null);
+	return Effect.try({
+		try: () => {
+			const millis = Duration.toMillis(Duration.fromInputUnsafe(input));
+			if (!Number.isFinite(millis) || millis <= 0) throw new Error("Alarm repeatEvery must be a positive finite duration");
+			return Math.ceil(millis);
+		},
+		catch: (cause) => new InvalidRepeatEveryError({ cause })
+	});
+};
+const toAlarmDue = (row) => Effect.gen(function* () {
+	if (!Number.isFinite(row.run_at)) return yield* Effect.fail(new StoredAlarmDecodeError({
+		cause: /* @__PURE__ */ new Error("Stored alarm run_at must be a finite number"),
+		storageId: row.storage_id
+	}));
+	return DurableObjectAlarmEvent.make({
+		_tag: "AlarmDue",
+		id: row.alarm_id,
+		payload: yield* decodeStoredPayload(row),
+		scheduledAt: DateTime.toUtc(DateTime.makeUnsafe(row.run_at)),
+		tag: row.tag
+	});
+});
+const getProcessLimit = (options) => {
+	const limit = options?.limit ?? DEFAULT_PROCESS_DUE_ALARMS_LIMIT;
+	if (!Number.isSafeInteger(limit) || limit <= 0) return Effect.fail(new InvalidProcessDueAlarmsOptionsError({ cause: /* @__PURE__ */ new Error("processDueAlarms limit must be a positive safe integer") }));
+	return Effect.succeed(limit);
+};
+const toFailureRescheduleMillis = (input) => Effect.try({
+	try: () => {
+		const millis = Duration.toMillis(Duration.fromInputUnsafe(input));
+		if (!Number.isFinite(millis) || millis <= 0) throw new Error("Alarm failure rescheduleAfter must be a positive finite duration");
+		return Math.ceil(millis);
+	},
+	catch: (cause) => new InvalidProcessDueAlarmsOptionsError({ cause })
+});
+const getFailureRetryDelay = (options) => toFailureRescheduleMillis(options?.retryFailedAfter ?? DEFAULT_PROCESS_DUE_ALARMS_FAILURE_RESCHEDULE_AFTER);
+const getFailureActionMode = (action) => typeof action === "string" ? action : action.mode;
+const getFailureActionRetryDelay = (action) => typeof action === "string" || action.mode !== "retry" ? void 0 : action.retryFailedAfter;
+const processDue = (handle, options = {}) => Effect.gen(function* () {
+	return yield* (yield* DurableObjectAlarm).processDueAlarms(handle, options);
+});
+const process = processDue;
+const isAlarmDefinitionConfig = (definition) => typeof definition === "object" && definition !== null && "payload" in definition;
+const getAlarmDefinitionSchema = (definition) => isAlarmDefinitionConfig(definition) ? definition.payload : definition;
+const getAlarmDefinitionFailureAction = (definition) => {
+	if (definition === void 0 || !isAlarmDefinitionConfig(definition)) return;
+	if (definition.failure === void 0) return;
+	return definition.failure === "retry" ? {
+		mode: "retry",
+		retryFailedAfter: definition.retry?.initialDelay
+	} : { mode: definition.failure };
+};
+const define = (definitions) => ({ handlers: (handlers, options) => processDue((event) => Effect.gen(function* () {
+	const definition = definitions[event.tag];
+	if (definition === void 0) return;
+	const schema = getAlarmDefinitionSchema(definition);
+	const payload = yield* Schema.decodeUnknownEffect(schema)(event.payload).pipe(Effect.mapError((cause) => new StoredAlarmDecodeError({
+		cause,
+		storageId: getScheduledEventId(event)
+	})));
+	const handler = handlers[event.tag];
+	yield* handler({
+		...event,
+		payload
+	});
+}), {
+	...options,
+	onFailure: (failure) => Effect.gen(function* () {
+		const action = getAlarmDefinitionFailureAction(definitions[failure.tag]);
+		const optionAction = options?.onFailure === void 0 ? void 0 : yield* options.onFailure(failure);
+		return action ?? optionAction;
+	})
+}) });
+/**
+* SQLite-backed Durable Object alarm scheduler.
+*
+* `DurableObjectAlarm` stores alarms in the current Durable Object's SQLite storage
+* and keeps the platform alarm set to the earliest pending scheduled alarm. The
+* platform alarm timestamp is only a wake-up hint; logical event identity comes
+* from persisted `{ tag, id }` rows.
+*
+* Retry safety depends on acknowledgement ordering. `processDueAlarms` runs the
+* caller's handler first and only then conditionally deletes or advances the
+* same selected row. By default, handler failures are isolated: the failed row
+* is retried after a delay, later due rows continue, and the platform alarm is
+* reconciled once at the end. Use `mode: "ordered"` for strict workflows where
+* one failed logical alarm should block later due alarms.
+*
+* Provide `DurableObjectAlarm.layer` anywhere `DurableObjectState` is available.
+*
+* @example Providing the service
+* ```ts
+* const program = Effect.gen(function* () {
+*   const durableObjectAlarm = yield* DurableObjectAlarm;
+*   const now = yield* DateTime.now;
+*
+*   yield* durableObjectAlarm.scheduleAlarm({
+*     tag: "heartbeat",
+*     id: "heartbeat-check",
+*     runAt: DateTime.add(now, { seconds: 5 }),
+*     repeatEvery: Duration.seconds(5),
+*     payload: null,
+*   });
+* }).pipe(Effect.provide(DurableObjectAlarm.layer));
+* ```
+*
+* @example Processing due alarms
+* ```ts
+* const handledEvents = yield* durableObjectAlarm.processDueAlarms((event) =>
+*   Effect.gen(function* () {
+*     if (event.tag === "heartbeat") {
+*       yield* heartbeatManager.handleAlarmEvent(event);
+*     }
+*   })
+* );
+* ```
+*/
+var DurableObjectAlarm = class DurableObjectAlarm extends Context.Service()("effect-cf/DurableObjectAlarm") {
+	static layer = Layer.effect(DurableObjectAlarm, Effect.gen(function* () {
+		const state = yield* DurableObjectState;
+		const reconcileAlarm = Effect.fn("DurableObjectAlarm.reconcileAlarm")(function* () {
+			const next = (yield* (yield* state.storage.sql.exec(`SELECT run_at FROM effect_cf_scheduled_alarms ORDER BY run_at ASC, storage_id ASC LIMIT 1`)).toArray())[0];
+			if (next === void 0) {
+				yield* state.storage.deleteAlarm();
+				return;
+			}
+			yield* state.storage.setAlarm(next.run_at);
+		});
+		const rescheduleFailedAlarm = Effect.fn("DurableObjectAlarm.rescheduleFailedAlarm")(function* (row, retryDelayMillis) {
+			const retryAt = (yield* Clock.currentTimeMillis) + retryDelayMillis;
+			if (row.repeat_every_ms === null) {
+				yield* (yield* state.storage.sql.exec(`UPDATE effect_cf_scheduled_alarms
+                  SET run_at = ?
+                WHERE storage_id = ?
+                  AND run_at = ?
+                  AND repeat_every_ms IS NULL
+                  AND payload = ?`, retryAt, row.storage_id, row.run_at, row.payload)).rowsWritten;
+				return;
+			}
+			yield* (yield* state.storage.sql.exec(`UPDATE effect_cf_scheduled_alarms
+                SET run_at = ?
+              WHERE storage_id = ?
+                AND run_at = ?
+                AND repeat_every_ms = ?
+                AND payload = ?`, retryAt, row.storage_id, row.run_at, row.repeat_every_ms, row.payload)).rowsWritten;
+		});
+		const acknowledgeAlarm = Effect.fn("DurableObjectAlarm.acknowledgeAlarm")(function* (row) {
+			if (row.repeat_every_ms === null) {
+				yield* (yield* state.storage.sql.exec(`DELETE FROM effect_cf_scheduled_alarms
+              WHERE storage_id = ?
+                AND run_at = ?
+                AND repeat_every_ms IS NULL
+                AND payload = ?`, row.storage_id, row.run_at, row.payload)).rowsWritten;
+				return;
+			}
+			const acknowledgedAt = yield* Clock.currentTimeMillis;
+			yield* (yield* state.storage.sql.exec(`UPDATE effect_cf_scheduled_alarms
+              SET run_at = ?
+            WHERE storage_id = ?
+              AND run_at = ?
+              AND repeat_every_ms = ?
+              AND payload = ?`, acknowledgedAt + row.repeat_every_ms, row.storage_id, row.run_at, row.repeat_every_ms, row.payload)).rowsWritten;
+		});
+		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();
+			}));
+		});
+		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
+                   (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();
+			}));
+		});
+		const processDueAlarms = Effect.fn("DurableObjectAlarm.processDueAlarms")(function* (handle, options) {
+			yield* ensureTable(state);
+			const mode = options?.mode ?? "isolated";
+			const limit = yield* getProcessLimit(options);
+			const now = yield* Clock.currentTimeMillis;
+			const dueRows = yield* (yield* state.storage.sql.exec(`SELECT storage_id, alarm_id, tag, run_at, repeat_every_ms, payload
+             FROM effect_cf_scheduled_alarms
+            WHERE run_at <= ?
+            ORDER BY run_at ASC, storage_id ASC
+            LIMIT ?`, now, limit)).toArray();
+			const handled = [];
+			const failed = [];
+			const handleFailure = function* (row, event, cause) {
+				const failure = {
+					cause,
+					event,
+					id: row.alarm_id,
+					storageId: row.storage_id,
+					tag: row.tag
+				};
+				failed.push(failure);
+				const failureAction = options?.onFailure === void 0 ? void 0 : yield* options.onFailure(failure);
+				const actionMode = failureAction === void 0 ? mode : getFailureActionMode(failureAction);
+				if (actionMode === "retry" || actionMode === "isolated") {
+					const actionRetryDelay = failureAction === void 0 ? void 0 : getFailureActionRetryDelay(failureAction);
+					yield* rescheduleFailedAlarm(row, actionRetryDelay === void 0 ? yield* getFailureRetryDelay(options) : yield* toFailureRescheduleMillis(actionRetryDelay));
+					return "continue";
+				}
+				if (actionMode === "skip-and-advance-repeat") {
+					yield* acknowledgeAlarm(row);
+					return "continue";
+				}
+				yield* reconcileAlarm();
+				return "stop";
+			};
+			for (const row of dueRows) {
+				const eventExit = yield* Effect.exit(toAlarmDue(row));
+				if (Exit.isFailure(eventExit)) {
+					if ((yield* handleFailure(row, void 0, eventExit.cause)) === "stop") return yield* Effect.failCause(eventExit.cause);
+					continue;
+				}
+				const event = eventExit.value;
+				const handleExit = yield* Effect.exit(handle(event));
+				if (Exit.isFailure(handleExit)) {
+					if ((yield* handleFailure(row, event, handleExit.cause)) === "stop") return yield* Effect.failCause(handleExit.cause);
+					continue;
+				}
+				yield* acknowledgeAlarm(row);
+				handled.push(event);
+			}
+			yield* reconcileAlarm();
+			return {
+				failed,
+				handled
+			};
+		});
+		return DurableObjectAlarm.of({
+			cancelAlarm,
+			processDueAlarms,
+			scheduleAlarm
+		});
+	}).pipe(Effect.withSpan("DurableObjectAlarm.layer")));
+};
+//#endregion
 //#region src/DurableObjectRpcWebSocket.ts
 var DurableObjectRpcWebSocket_exports = /* @__PURE__ */ __exportAll({
 	DurableObjectRpcWebSocket: () => DurableObjectRpcWebSocket,
@@ -1209,4 +1536,4 @@ const Service = () => (id, definition) => {
 	});
 };
 //#endregion
-export { Binding_exports as Binding, DurableObject_exports as DurableObject, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Kv_exports as Kv, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, ServiceBinding_exports as ServiceBinding, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment };
+export { Binding_exports as Binding, DurableObject_exports as DurableObject, DurableObjectAlarm_exports as DurableObjectAlarm, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Kv_exports as Kv, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, ServiceBinding_exports as ServiceBinding, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment };

package/package.json

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

package/src/DurableObject.ts

@@ -72,6 +72,14 @@ export interface DurableObjectOptions<ROut, Rpc extends DurableObjectRpc<ROut>>
   readonly rpc?: Rpc;
   /** Optional fetch handler for HTTP/WebSocket requests. */
   readonly fetch?: Effect.Effect<Response, unknown, FetchContext<ROut>>;
+  /**
+   * Optional logical alarm processing effect.
+   *
+   * This runs before `alarm` and should be built with helpers such as
+   * `DurableObjectAlarm.processDue(...)` so the reusable scheduler stays inside
+   * the Durable Object's single managed runtime boundary.
+   */
+  readonly alarms?: Effect.Effect<unknown, unknown, HandlerContext<ROut>>;
   readonly alarm?: (
     alarmInfo?: globalThis.AlarmInvocationInfo,
   ) => Effect.Effect<void, unknown, HandlerContext<ROut>>;
@@ -141,8 +149,24 @@ export const make = <
     }
 
     alarm(alarmInfo?: globalThis.AlarmInvocationInfo): Promise<void> | void {
-      if (options.alarm !== undefined) {
-        return this[RunSymbol](options.alarm(alarmInfo));
+      const logicalAlarms = options.alarms?.pipe(Effect.asVoid);
+      const rawAlarm = options.alarm?.(alarmInfo);
+
+      if (logicalAlarms !== undefined && rawAlarm !== undefined) {
+        return this[RunSymbol](
+          Effect.gen(function* () {
+            yield* logicalAlarms;
+            yield* rawAlarm;
+          }),
+        );
+      }
+
+      if (logicalAlarms !== undefined) {
+        return this[RunSymbol](logicalAlarms);
+      }
+
+      if (rawAlarm !== undefined) {
+        return this[RunSymbol](rawAlarm);
       }
     }