@gjermundgaraba/effect-actions-cloudflare 0.0.0-stage → 0.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# effect-actions-cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@gjermundgaraba/effect-actions-cloudflare` serves Effect RPC from Cloudflare Durable Objects, over WebSockets the runtime holds while an object hibernates and over an object's stub, and calls it from a Worker: any plain `RpcGroup`, with no action at all, served by Effect's own `RpcServer`. [effect-actions](https://github.com/gjermundgaraba/effect-actions) bindings are the option: the same routes `ActionRpc.layer`, `ActionHttp.layer` and `ActionMcp.layerHttp` serve elsewhere, in an object, with events followed over its sockets, over MCP or by webhook across its hibernation. It is released with `@gjermundgaraba/effect-actions`, at the same version, and requires it.
+
+```sh
+pnpm add @gjermundgaraba/effect-actions @gjermundgaraba/effect-actions-cloudflare effect@~4.0.5
+```
+
+Its declarations name the Workers runtime's types, such as `Fetcher`: generate them with `wrangler types`, or install `@cloudflare/workers-types`, as a Worker project does.
+
+Serve an Effect `RpcGroup` from an object, over WebSockets the runtime holds while it hibernates:
+
+```ts
+class ChatRoom extends ActionDurableObject.make({
+  services: () =>
+    Layer.mergeAll(layerSql, Layer.effect(Room)(ActionDurableObject.name)),
+  routes: RpcServer.layer(RoomRpcs).pipe(
+    Layer.provide(handlers),
+    Layer.provide(ActionDurableObject.layerWebSocket({ path: "/rpc" }))
+  ),
+}) {}
+```
+
+Or serve actions there, authenticated, as `ActionRpc.layer` serves them elsewhere:
+
+```ts
+routes: ActionRpc.layer(RoomRpc, room).pipe(
+  Layer.provide(ActionDurableObject.layerWebSocket({ path: "/rpc" })),
+  Layer.provide(authenticate),
+),
+```
+
+Call an object's own API, an Effect `RpcGroup` it serves as its `calls`, from a Worker or another object with Cloudflare's own RPC, a new stub for each call, its declared errors typed:
+
+```ts
+Effect.gen(function* () {
+  const lobby = yield* ActionDurableObject.client(LobbyCalls);
+
+  return yield* lobby(() => env.CHAT_LOBBY.getByName("lobby")).previews();
+});
+```
+
+Call an object's routes from a Worker with the core's own clients, through the stub:
+
+```ts
+ActionHttp.client(RoomHttp, { baseUrl: "https://room" }).pipe(
+  Effect.provide(
+    ActionDurableObject.layerHttpClient(env.CHAT_ROOM.getByName("design"))
+  )
+);
+```
+
+Its pages are in [docs/](docs/README.md), with an example, [chat-rooms](examples/chat-rooms/): one Durable Object per room, served over hibernating WebSockets, JSON and its stub, with an alarm and a Worker in front. In a project that installs it, both are in `node_modules/@gjermundgaraba/effect-actions-cloudflare/`.
+
+MIT licensed.

package/dist/ActionDurableObject.d.mts

@@ -0,0 +1,240 @@
+import { State, name } from "./state.mjs";
+import { Alarm } from "./alarm.mjs";
+import { StubRequest } from "./calls.mjs";
+import { AnyPlacement, Placement, PlacementKeys, placed, reaching } from "./placed.mjs";
+import { LayerWebSocketOptions, Sockets, layerWebSocket, refuseUpgrade } from "./sockets.mjs";
+import { Tasks } from "./tasks.mjs";
+import { LayerWebhooksOptions, Waits, layerWebhooks } from "./webhooks.mjs";
+import { Client, Stub, client, layerStubClient } from "./stub.mjs";
+import { layerHttpClient } from "./fetcher.mjs";
+import { DurableObject } from "cloudflare:workers";
+import { Effect, Layer, Scope } from "effect";
+import { HttpRouter, HttpServer, HttpServerRequest } from "effect/http";
+import { RpcMessage, RpcServer } from "effect/rpc";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+type ServedPerRequest = Scope.Scope | HttpServerRequest.HttpServerRequest;
+type ObjectServices = State | Alarm | Tasks | Event.Events | Action.Idempotency | Sockets | Waits;
+type Allowed<A, S> = ObjectServices | S | HttpRouter.HttpRouter | Layer.Success<typeof HttpServer.layerServices> | HttpRouter.Request<"Requires", ServedPerRequest | ObjectServices | A | S> | HttpRouter.Request<"GlobalRequires", ServedPerRequest | ObjectServices | A | S> | HttpRouter.Request<"Error", unknown> | HttpRouter.Request<"GlobalError", unknown>;
+/** `handlers`' and `make`'s options. */
+export interface Options<S = never, SE = never, SR = never, A = never, E = never, R = never, AE = never, AR = never, CA = never, CE = never, CR = never> {
+  /**
+   * The object's startup services, such as a store over `State`'s `storage.sql`: built once per
+   * instance, before the routes, again after every eviction, and never finalized. The routes,
+   * every request, the alarm and `run` share that one build, and an implementation the services
+   * build, such as an in-process `Action.client`'s, is the one the routes serve. They may
+   * require `State`, `Alarm`, `Tasks`, `Event.Events` and `Action.Idempotency` alone, the last
+   * keeping the answers of calls given an idempotency key in the object's storage. A store over
+   * the object's storage, what the object is, such as its name, a store scheduling its expiries,
+   * or a handler announcing an event, is a Layer requiring them.
+   *
+   * **Gotchas**
+   *
+   * - A service only the routes need may be provided to them instead, but the alarm and `run` see only these: one they read too belongs here.
+   * - A module-level Layer reading `env` from `cloudflare:workers` as the module evaluates finds it unset: read it as the Layer builds or serves, or give `make` a function of the instance's `env`.
+   * - They build under the instance's gate, which holds every event of the object until they end: one calling another object as it builds, rather than only making its client, waits on that object's gate, and two objects calling each other as they build wait on each other until the runtime resets both, 30 seconds on. Call other objects from a handler or the alarm.
+   */
+  readonly services?: Layer.Layer<S, SE, SR> | undefined;
+  /**
+   * What `fetch` serves: routes, as `HttpRouter.toWebHandler` serves them, such as
+   * `ActionRpc.layer` over `layerWebSocket` and `ActionHttp.layer`. Built after the services, again
+   * after every eviction, and never finalized. They may require `State`, `Alarm`, `Tasks`,
+   * `Event.Events`, `Action.Idempotency`, `Sockets`, `Waits` and the services, as Layers and as
+   * handlers; any other request-time requirement must be provided by their middleware or
+   * authentication, or be a service they provide themselves. Without them, `fetch` answers 404, and
+   * no protocol accepts a socket.
+   *
+   * **Gotchas**
+   *
+   * - Router middleware and `HttpRouter.provideRequest` around the routes run for a socket's upgrade request alone: a service only they provide is missing from every call over the socket, which dies with `Internal server error`; list an `RpcMiddleware` in `ActionRpc.layer`'s `middleware`, or make it a startup service.
+   * - `toWebHandler` reads no `HttpServerRequest.MaxBodySize`: the platform limits request bodies.
+   */
+  readonly routes?: Layer.Layer<A, E, R> | undefined;
+  /**
+   * What the object serves over its stub, on `effectActionsRpc`: an rpc server, such as
+   * `RpcServer.layer(group)` with its handlers, or `ActionRpc.layer`, given the stub's protocol,
+   * over which each call of `effectActionsRpc` is one call, its messages in and its responses out,
+   * as values Workers RPC's structured clone copies, each schema's plain form
+   * (`Schema.toCodecIso`), never a JSON string. Built after the services, beside the routes,
+   * again after every eviction, and never finalized. It may require the protocol, `State`,
+   * `Alarm`, `Tasks`, `Event.Events`, `Action.Idempotency` and the services; every call's own
+   * requirement must be provided by its middleware or be one of those. Without it, a call over
+   * the stub rejects once the object is built, naming the option.
+   *
+   * **Gotchas**
+   *
+   * - The calls serve one group on the one protocol `make` and `handlers` give them: serve several groups as one, `group.merge(other)`.
+   * - Calls running no rpc server on the protocol, such as a group's handlers given without `RpcServer.layer(group)`, fail the object's build, naming it.
+   * - A `Date`, bytes, `undefined` and an `Error` defect cross as themselves; an `Option`, an exit and a tagged error as their tagged objects, a `Map` and a `Set` as arrays.
+   * - A schema with no JSON form, such as `Schema.instanceOf(Date)`, works over the stub, not over `layerWebSocket`, which speaks JSON; an `ActionRpc` binding's values cross as JSON over either.
+   * - A value the clone refuses, such as a class instance in a `Schema.Unknown`, or a defect that is a class instance other than an `Error`, fails the whole call with workerd's `DataCloneError`, whatever its exit.
+   * - Unary: a call answers once every request it carries has its exit, so an rpc that streams is answered with a defect at its first chunk, naming it: stream over `layerWebSocket`.
+   * - An `ActionRpc.layer` here fails its build when the binding serves a streaming action or an event type: list the others in its `actions`.
+   * - A defect Effect's server sends as fatal to the whole client, such as a handler's die, is answered as the exit of each request of the call still without one, a die: the call fails with that defect alone, and the client's next call is answered.
+   * - In a raw `effectActionsRpc` call batching several requests, a handler's die before another request's answer gives that request two exits, the defect first, which Effect's client takes, then its own; `layerStubClient` sends one request per call and never meets it.
+   * - Nothing authenticates a call: a stub is reachable only through a binding, so the caller is the Worker or another object of the deployment, and one acting for a principal forwards it in a header, with `RpcClient.withHeaders`, read by an `RpcMiddleware` or an `ActionRpc` binding's authentication, or in the payload.
+   * - A plain group suits an object's own API, which only its Worker and other objects call; an `ActionRpc.layer` suits actions served on other surfaces too, called with `ActionRpc.client` over `layerStubClient`.
+   */
+  readonly calls?: Layer.Layer<CA, CE, CR> | undefined;
+  /**
+   * What runs at the time `Alarm.set` gave, given its `scheduledTime` and `retryCount`, 0 at that
+   * time and counting each failed or cut-off run as it is retried. It may require the services,
+   * `State`, `Alarm`, `Tasks`, `Event.Events`, `Action.Idempotency` and a `Scope`, closed when it
+   * ends. It runs through `run`, once the services and routes are built.
+   *
+   * **Gotchas**
+   *
+   * - A failure is logged and retried 2 seconds later, doubling, six times, as the runtime retries a plain object's alarm, then hourly until a run succeeds, never dropped: the object's `alarm` resolves, so the runtime records no failure.
+   * - A run an eviction, a deploy or a crash cuts off runs again at its retry's time, counted in `retryCount` as a failure, so a run may repeat: make what it sends idempotent.
+   * - It runs once for every time `Alarm.set` gave before its run, at the earliest: the option sets its next one itself.
+   */
+  readonly alarm?: ((info: AlarmInvocationInfo) => Effect.Effect<void, AE, AR>) | undefined;
+  /**
+   * Work the object does at least once, by name, such as telling another object of a change:
+   * `Tasks.runAfter(name, change)` marks it due now in the object's storage and runs the change,
+   * and the object's alarm runs it, after the call, until it succeeds. Each may require what
+   * `alarm` may.
+   */
+  readonly tasks?: {
+    readonly [name: string]: Effect.Effect<void, unknown, NoInfer<S> | State | Alarm | Tasks | Event.Events | Action.Idempotency | Scope.Scope>;
+  } | undefined;
+  /**
+   * The placement whose objects these are, `placed`'s answer, which the Worker serves: each call
+   * and subscription of one of its contracts, on every surface, sockets and the stub included, is
+   * refused `Forbidden` where its input's key names another object.
+   */
+  readonly placed?: AnyPlacement | undefined;
+  /**
+   * Whether to leave out the request logger `HttpRouter.toWebHandler` adds by default, which logs
+   * every request the routes serve, a socket's upgrade included: Effect's default, kept.
+   */
+  readonly disableLogger?: boolean | undefined;
+}
+type HandlerOf<K extends keyof DurableObject> = NonNullable<DurableObject[K]>;
+/**
+ * The handlers `handlers` returns and the class `make` returns defines, each taking the runtime's
+ * own arguments, so a Durable Object class delegates those it serves this way and writes the
+ * others itself. Each awaits the object's build, started by the first of them called, and
+ * rejects with its failure.
+ */
+export interface Handlers<S = never> {
+  /** Serves the routes, or answers 404 when there are none. */
+  fetch(...args: Parameters<HandlerOf<"fetch">>): Promise<Response>;
+  /**
+   * Hands the message to the protocol whose socket it is, and resolves for a socket no protocol
+   * accepted.
+   */
+  webSocketMessage(...args: Parameters<HandlerOf<"webSocketMessage">>): Promise<void>;
+  /**
+   * Completes the closing handshake of any socket, replying with the client's code and reason,
+   * and ends the socket's protocol client, if a protocol accepted it.
+   */
+  webSocketClose(...args: Parameters<HandlerOf<"webSocketClose">>): Promise<void>;
+  /** Ends the socket's protocol client, and resolves for a socket no protocol accepted. */
+  webSocketError(...args: Parameters<HandlerOf<"webSocketError">>): Promise<void>;
+  /**
+   * Answers one call over the object's stub, the messages `layerStubClient` sends, with its
+   * responses, as values, through the `calls` option's server, once every request it carries
+   * has its exit, or rejects without `calls`. Workers RPC calls it by this name, the package's,
+   * so it does not collide with the class's own methods.
+   */
+  effectActionsRpc(request: StubRequest): Promise<readonly RpcMessage.FromServerEncoded[]>;
+  /**
+   * Runs, through `run`, each time the object's schedule holds that has come: the `alarm`
+   * option's, which `Alarm.set` gave, and the package's own.
+   */
+  alarm(...args: Parameters<HandlerOf<"alarm">>): Promise<void>;
+  /**
+   * Runs `effect` in the object, with the services the instance built, `State`, `Alarm`,
+   * `Tasks`, `Event.Events`, `Action.Idempotency` and a `Scope`, closed when it ends, once the
+   * services and routes are built: what the alarm runs through, and what the object's own methods
+   * run their Effects with, such as a method a Worker calls over the object's stub. A Layer the
+   * effect provides itself, or an `Action.client` it acquires, is built for that call alone: give
+   * what calls share as `services`.
+   *
+   * **Gotchas**
+   *
+   * - A Durable Object's public methods are callable over its stub, the `run` of a class `make` returns too, but it takes an Effect, which no stub can send: a caller over the stub gets a rejection, nothing more.
+   */
+  run<A, E>(effect: Effect.Effect<A, E, S | State | Alarm | Tasks | Event.Events | Action.Idempotency | Scope.Scope>): Promise<A>;
+}
+/**
+ * The object's lifecycle, for a Durable Object class that cannot extend the one `make` returns:
+ * given its `ctx`, the handlers that build `services`, then `calls`, with the stub's protocol,
+ * and `routes`, with `Sockets`, once per instance, as it is constructed, with the object's own
+ * services provided, its `Event.Events`' logs kept in its storage, under `effect-actions/log/`,
+ * and its current sources' revisions beside them, so a cursor outlives an eviction, and share
+ * that one build across every event, which awaits it. `fetch` serves the routes, the socket
+ * handlers dispatch through `Sockets`, `effectActionsRpc` through the calls' server, `alarm` runs
+ * the times `Alarm` keeps and `run` runs an Effect in the object.
+ * Delegate the handlers the class serves this way, as methods:
+ * `effectActionsRpc(request: StubRequest)` returning the handlers' own.
+ *
+ * **Gotchas**
+ *
+ * - An instance lasts until the runtime evicts it, and the next event builds everything again on a new one: nothing the services, calls or routes build is finalized, and in-memory state is lost, so keep state in storage.
+ * - A build that fails is dropped with all it built, and the events waiting on it are rejected with its failure: the next event builds again, under the same gate.
+ * - The events arriving while a build runs, such as the one building again after a failure, run once it ends, one after another, each to its end before the next: a slow one holds those after it.
+ * - An instance builds as it is constructed, under `blockConcurrencyWhile`, so the runtime holds every event, the first included, until the build ends, then delivers them one by one, as to a built instance: a build longer than 30 seconds resets the object.
+ * - Every Effect of the object runs under Effect's microtask scheduler, `new Scheduler.MixedScheduler("sync")`, where its default's timers would let the next event in between any two steps: CPU-heavy work holds every other event until it ends.
+ * - Calls still interleave where a plain method's would: while one waits on I/O, another object or a timer, such as `Effect.sleep`, the next event runs, so serialize a read and the write that depends on it with a `Semaphore`, or make both one synchronous `storage.kv` or `storage.sql` step.
+ * - Without `routes`, `fetch` answers 404; without `calls`, `effectActionsRpc` rejects once the object is built, naming the option.
+ * - A socket the class accepts itself, with `State`'s `acceptWebSocket`, carries no protocol's tag: the socket handlers resolve for it, `webSocketClose` once it has replied to the client's close, so the class answers the sockets carrying its own tag in `webSocketMessage` and delegates the rest.
+ * - Delegate `alarm` too: the object's one alarm is the package's, which also ends `layerWebhooks`' long waits, and workerd refuses `storage.setAlarm`, which `Alarm.set` calls, on a class without an `alarm` method, where celld 0.6.2 accepts it and drops the alarm when it is due.
+ * - Its `Event.Events` reads a check or current source when a subscriber subscribes and on each `notify`, never on its `nextPoll`, a timer that would keep the object from hibernating: an upstream outside the object notifies it through a call, such as a method a Worker calls over its stub.
+ * - Its `Event.Events` keeps a logged occurrence's data as its payload's JSON: one that does not encode as it is published is logged then, and one that no longer decodes, such as after a deployment changed the payload, is reported as it is read; each is sent as a gap.
+ * - Provide no other `Event.Events`, such as the core's `Event.layerMemory`, to the services or routes: it shadows the object's, its logs lost at each eviction and its check sources read on a timer that keeps the object awake.
+ * - A log's entries live beside the application's data: a store deleting every key deletes them too, and a subscriber resuming from one of their cursors receives a gap.
+ * - A current source's revisions live beside them, under `effect-actions/revisions/`: a store deleting every key starts them again, and until the object is evicted their ids repeat ones its watches have seen, which drop them.
+ * - Two log sources of event types sharing a name die as the second attaches, naming it: each log is kept under its event's name.
+ * - A log source fed by `emit` dies as it attaches, naming `publish`: an evicted object would miss what the stream sends meanwhile, with no gap, and its open stream would keep the object awake.
+ * - A subscriber's read that fails is tried again 5 seconds later, on a timer, until one succeeds: a source failing for good keeps the object awake, billed, and sends each subscriber a `Failed` each time.
+ * - A poll's `subscription` hook is held until 5 minutes after its last poll, on a timer that keeps the object awake, and an eviction tears down no hook: one it ends is set up again as its subscription resumes, its teardown never run.
+ *
+ * Guide: `docs/ActionDurableObject-own-class.md` in this package.
+ */
+export declare const handlers: <S = never, SE = never, SR extends State | Alarm | Tasks | Event.Events | Action.Idempotency = never, A = never, E = never, R extends Allowed<A, S> = never, AE = never, AR extends S | State | Alarm | Tasks | Event.Events | Action.Idempotency | Scope.Scope = never, CA = never, CE = never, CR extends RpcServer.Protocol | S | State | Alarm | Tasks | Event.Events | Action.Idempotency = never>(ctx: DurableObjectState, options: Options<S, SE, SR, A, E, R, AE, AR, CA, CE, CR>) => Handlers<S>;
+/**
+ * An instance of a class `make` returns: a Durable Object with the handlers it defines, each
+ * taking the runtime's own arguments, so a class extending it overrides them as `Handlers`
+ * declares them, returning a promise, and reaches `make`'s through `super`, its `env` the one its
+ * `services` function takes.
+ */
+export type Instance<S = never, Env = Cloudflare.Env> = Handlers<S> & DurableObject<Env>;
+/**
+ * `make` with `services`, a function of the instance's `env`, whose parameter's type is the
+ * class's `env`: the class `make` returns otherwise.
+ *
+ * Guide: `docs/ActionDurableObject.md` in this package.
+ */
+export declare function make<S, SE, SR extends State | Alarm | Tasks | Event.Events | Action.Idempotency, A = never, E = never, R extends Allowed<A, S> = never, AE = never, AR extends S | State | Alarm | Tasks | Event.Events | Action.Idempotency | Scope.Scope = never, CA = never, CE = never, CR extends RpcServer.Protocol | S | State | Alarm | Tasks | Event.Events | Action.Idempotency = never, Env = Cloudflare.Env>(options: Omit<Options<S, SE, SR, A, E, R, AE, AR, CA, CE, CR>, "services"> & {
+  /**
+   * The object's startup services, as `handlers`' `services`, returned by a function of the
+   * instance's `env`, `this.env`, called as each instance is constructed: a service reads a
+   * binding or a variable from the `env` it is given, whose type, the function's parameter's,
+   * is the class's `env`.
+   */
+  readonly services: (env: Env) => Layer.Layer<S, SE, SR>;
+}): new (ctx: DurableObjectState, env: Env) => Instance<S, Env>;
+/**
+ * A Durable Object class delegating every handler, and `run`, to `handlers` over its own `ctx`,
+ * with the services `services` returns for its `env`: it serves `routes` on `fetch`, the
+ * sockets their protocols accept on `webSocketMessage`, `webSocketClose` and `webSocketError`,
+ * and `calls` on `effectActionsRpc`, the method a caller's `layerStubClient` or `client` calls
+ * over the stub, and runs `alarm`. Export it, or a class extending it, under the name the
+ * Wrangler configuration binds; a class extending it overrides only the handlers it has reason
+ * to write, and reaches `make`'s through `super`.
+ *
+ * **Gotchas**
+ *
+ * - Its socket handlers resolve for a socket no protocol accepted, such as one a class extending it accepts itself, `webSocketClose` once it has replied to the client's close: an override answers its own sockets and calls `super` for the rest.
+ * - The `services` function's parameter type is the class's `env`, so an application's own `Env` needs no augmenting of `Cloudflare.Env`; services reading no `env` are `() => layer`, and a class without one has `Cloudflare.Env`.
+ * - It always has `alarm`, the package's, which runs the `alarm` option at the time `Alarm.set` gave: an override reaches it with `await super.alarm(info)`, and one that does not call it runs none of the times `Alarm` keeps.
+ *
+ * Guide: `docs/ActionDurableObject.md` in this package; in an application:
+ * `examples/chat-rooms/`.
+ */
+export declare function make<S = never, SE = never, SR extends State | Alarm | Tasks | Event.Events | Action.Idempotency = never, A = never, E = never, R extends Allowed<A, S> = never, AE = never, AR extends S | State | Alarm | Tasks | Event.Events | Action.Idempotency | Scope.Scope = never, CA = never, CE = never, CR extends RpcServer.Protocol | S | State | Alarm | Tasks | Event.Events | Action.Idempotency = never>(options: Omit<Options<S, SE, SR, A, E, R, AE, AR, CA, CE, CR>, "services"> & {
+  readonly services?: ((env: Cloudflare.Env) => Layer.Layer<S, SE, SR>) | undefined;
+}): new (ctx: DurableObjectState, env: Cloudflare.Env) => Instance<S>;
+export { Alarm, type AnyPlacement, type Client, type LayerWebSocketOptions, type LayerWebhooksOptions, type Placement, type PlacementKeys, type Sockets, State, type Stub, type StubRequest, Tasks, type Waits, client, layerHttpClient, layerStubClient, layerWebSocket, layerWebhooks, name, placed, reaching, refuseUpgrade };

package/dist/ActionDurableObject.mjs

@@ -0,0 +1,190 @@
+import { State, name } from "./state.mjs";
+import { Alarm, alarmOf, applicationOwner, makeSchedule } from "./alarm.mjs";
+import { makeStubProtocol } from "./calls.mjs";
+import { layerEvents } from "./events.mjs";
+import { layerIdempotency } from "./idempotency.mjs";
+import { layerInputCheck, placed, reaching } from "./placed.mjs";
+import { Sockets, layerWebSocket, refuseUpgrade } from "./sockets.mjs";
+import { Tasks, makeTasks } from "./tasks.mjs";
+import { Waits, clockOwner, layerWebhooks, makeWaits } from "./webhooks.mjs";
+import { client, layerStubClient } from "./stub.mjs";
+import { layerHttpClient } from "./fetcher.mjs";
+import { DurableObject } from "cloudflare:workers";
+import { Cause, Context, Effect, Exit, Function, Layer, Scheduler, Scope } from "effect";
+import { HttpEffect, HttpMiddleware, HttpRouter, HttpServer } from "effect/http";
+import { RpcServer } from "effect/rpc";
+// src/durable/ActionDurableObject.ts
+const scheduler = new Scheduler.MixedScheduler("sync");
+const handlersOf = (ctx, options) => {
+	const services = options.services ?? Layer.empty;
+	const routes = options.routes;
+	const { calls } = options;
+	const state = Layer.succeed(State, ctx);
+	const schedule = makeSchedule(ctx);
+	const { waits, wakeDue } = makeWaits(schedule);
+	const tasks = makeTasks(schedule, options.tasks ?? {});
+	const build = Effect.gen(function* () {
+		const memoMap = yield* Layer.makeMemoMap;
+		const scope = yield* Scope.make();
+		return yield* Effect.gen(function* () {
+			const context = yield* Layer.buildWithMemoMap(services.pipe(Layer.provideMerge(Layer.mergeAll(Layer.succeed(Alarm)(alarmOf(schedule)), Layer.succeed(Waits)(waits), Layer.succeed(Tasks)(tasks.tasks), layerEvents, layerIdempotency(ctx))), Layer.provideMerge(state), Layer.provideMerge(Layer.merge(Layer.succeed(Scheduler.Scheduler)(scheduler), options.placed === void 0 ? Layer.empty : layerInputCheck(options.placed, ctx.id.name)))), memoMap, scope);
+			const given = Layer.succeedContext(context);
+			yield* schedule.restore;
+			const call = calls === void 0 ? async () => {
+				throw new Error("This Durable Object serves no rpcs over its stub: give handlers or make a calls Layer");
+			} : yield* Effect.gen(function* () {
+				const stub = yield* Effect.provideContext(makeStubProtocol, context);
+				yield* Layer.buildWithMemoMap(calls.pipe(Layer.provide(Layer.succeed(RpcServer.Protocol)(stub.protocol)), Layer.provide(given)), memoMap, scope);
+				yield* stub.served;
+				return async (request) => await Effect.runPromise(stub.serve(request));
+			});
+			const sockets = yield* Layer.buildWithMemoMap(Sockets.layer.pipe(Layer.provide(given)), memoMap, scope);
+			const serve = routes === void 0 ? async () => new Response(null, { status: 404 }) : yield* Effect.gen(function* () {
+				const routed = yield* Layer.buildWithMemoMap(routes.pipe(Layer.provideMerge(Layer.succeedContext(Context.merge(context, sockets))), Layer.provide(HttpServer.layerServices), Layer.provideMerge(HttpRouter.layer)), memoMap, scope);
+				return yield* Effect.sync(() => HttpEffect.toWebHandlerWith(routed)(Context.get(routed, HttpRouter.HttpRouter).asHttpEffect(), options.disableLogger === true ? void 0 : HttpMiddleware.logger));
+			});
+			return {
+				context,
+				call,
+				sockets: Context.get(sockets, Sockets),
+				serve
+			};
+		}).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
+	});
+	let instance;
+	let building = false;
+	const waiting = [];
+	const start = () => {
+		building = true;
+		(async () => {
+			const built = await ctx.blockConcurrencyWhile(async () => {
+				const exit = await Effect.runPromiseExit(build, { scheduler });
+				building = false;
+				if (Exit.isFailure(exit)) {
+					for (const next of waiting.splice(0)) next.fail(exit.cause);
+					return;
+				}
+				instance = exit.value;
+				return instance;
+			});
+			if (built === void 0) return;
+			for (let next = waiting.shift(); next !== void 0; next = waiting.shift()) await next.use(built);
+		})();
+	};
+	start();
+	const withBuilt = async (use) => {
+		const held = instance;
+		if (held !== void 0) return await use(held);
+		const { promise, resolve, reject } = Promise.withResolvers();
+		waiting.push({
+			use: async (built) => {
+				const used = (async () => await use(built))();
+				resolve(used);
+				await used.then(Function.constUndefined, Function.constUndefined);
+			},
+			fail: (cause) => {
+				reject(Cause.squash(cause));
+			}
+		});
+		if (!building) start();
+		return await promise;
+	};
+	const provided = ({ context }, effect) => Effect.scopedWith((scope) => Effect.provideContext(effect, context.pipe(Context.add(Scope.Scope, scope), Context.add(Layer.CurrentMemoMap, Layer.makeMemoMapUnsafe()))));
+	const run = async (effect) => await withBuilt(async (built) => await Effect.runPromise(provided(built, effect)));
+	const dispatch = async (event) => {
+		await withBuilt(async ({ sockets }) => {
+			await Effect.runPromise(Effect.asVoid(event(sockets)));
+		});
+	};
+	return {
+		fetch: async (request) => await withBuilt(async ({ serve }) => await serve(request)),
+		webSocketMessage: async (socket, message) => {
+			await dispatch((sockets) => sockets.message(socket, message));
+		},
+		webSocketClose: async (socket, code, reason) => {
+			await dispatch((sockets) => sockets.close(socket, code, reason));
+		},
+		webSocketError: async (socket) => {
+			await dispatch((sockets) => sockets.error(socket));
+		},
+		effectActionsRpc: async (request) => await withBuilt(async ({ call }) => await call(request)),
+		alarm: async () => {
+			await run(schedule.runDue({
+				[applicationOwner]: (info) => options.alarm?.(info) ?? Effect.void,
+				[clockOwner]: () => wakeDue,
+				...tasks.owners
+			}));
+		},
+		run
+	};
+};
+/**
+* The object's lifecycle, for a Durable Object class that cannot extend the one `make` returns:
+* given its `ctx`, the handlers that build `services`, then `calls`, with the stub's protocol,
+* and `routes`, with `Sockets`, once per instance, as it is constructed, with the object's own
+* services provided, its `Event.Events`' logs kept in its storage, under `effect-actions/log/`,
+* and its current sources' revisions beside them, so a cursor outlives an eviction, and share
+* that one build across every event, which awaits it. `fetch` serves the routes, the socket
+* handlers dispatch through `Sockets`, `effectActionsRpc` through the calls' server, `alarm` runs
+* the times `Alarm` keeps and `run` runs an Effect in the object.
+* Delegate the handlers the class serves this way, as methods:
+* `effectActionsRpc(request: StubRequest)` returning the handlers' own.
+*
+* **Gotchas**
+*
+* - An instance lasts until the runtime evicts it, and the next event builds everything again on a new one: nothing the services, calls or routes build is finalized, and in-memory state is lost, so keep state in storage.
+* - A build that fails is dropped with all it built, and the events waiting on it are rejected with its failure: the next event builds again, under the same gate.
+* - The events arriving while a build runs, such as the one building again after a failure, run once it ends, one after another, each to its end before the next: a slow one holds those after it.
+* - An instance builds as it is constructed, under `blockConcurrencyWhile`, so the runtime holds every event, the first included, until the build ends, then delivers them one by one, as to a built instance: a build longer than 30 seconds resets the object.
+* - Every Effect of the object runs under Effect's microtask scheduler, `new Scheduler.MixedScheduler("sync")`, where its default's timers would let the next event in between any two steps: CPU-heavy work holds every other event until it ends.
+* - Calls still interleave where a plain method's would: while one waits on I/O, another object or a timer, such as `Effect.sleep`, the next event runs, so serialize a read and the write that depends on it with a `Semaphore`, or make both one synchronous `storage.kv` or `storage.sql` step.
+* - Without `routes`, `fetch` answers 404; without `calls`, `effectActionsRpc` rejects once the object is built, naming the option.
+* - A socket the class accepts itself, with `State`'s `acceptWebSocket`, carries no protocol's tag: the socket handlers resolve for it, `webSocketClose` once it has replied to the client's close, so the class answers the sockets carrying its own tag in `webSocketMessage` and delegates the rest.
+* - Delegate `alarm` too: the object's one alarm is the package's, which also ends `layerWebhooks`' long waits, and workerd refuses `storage.setAlarm`, which `Alarm.set` calls, on a class without an `alarm` method, where celld 0.6.2 accepts it and drops the alarm when it is due.
+* - Its `Event.Events` reads a check or current source when a subscriber subscribes and on each `notify`, never on its `nextPoll`, a timer that would keep the object from hibernating: an upstream outside the object notifies it through a call, such as a method a Worker calls over its stub.
+* - Its `Event.Events` keeps a logged occurrence's data as its payload's JSON: one that does not encode as it is published is logged then, and one that no longer decodes, such as after a deployment changed the payload, is reported as it is read; each is sent as a gap.
+* - Provide no other `Event.Events`, such as the core's `Event.layerMemory`, to the services or routes: it shadows the object's, its logs lost at each eviction and its check sources read on a timer that keeps the object awake.
+* - A log's entries live beside the application's data: a store deleting every key deletes them too, and a subscriber resuming from one of their cursors receives a gap.
+* - A current source's revisions live beside them, under `effect-actions/revisions/`: a store deleting every key starts them again, and until the object is evicted their ids repeat ones its watches have seen, which drop them.
+* - Two log sources of event types sharing a name die as the second attaches, naming it: each log is kept under its event's name.
+* - A log source fed by `emit` dies as it attaches, naming `publish`: an evicted object would miss what the stream sends meanwhile, with no gap, and its open stream would keep the object awake.
+* - A subscriber's read that fails is tried again 5 seconds later, on a timer, until one succeeds: a source failing for good keeps the object awake, billed, and sends each subscriber a `Failed` each time.
+* - A poll's `subscription` hook is held until 5 minutes after its last poll, on a timer that keeps the object awake, and an eviction tears down no hook: one it ends is set up again as its subscription resumes, its teardown never run.
+*
+* Guide: `docs/ActionDurableObject-own-class.md` in this package.
+*/
+const handlers = (ctx, options) => handlersOf(ctx, options);
+function make(options) {
+	return class ActionDurableObject extends DurableObject {
+		#handlers;
+		constructor(ctx, env) {
+			super(ctx, env);
+			this.#handlers = handlersOf(this.ctx, {
+				...options,
+				services: options.services?.(this.env)
+			});
+		}
+		async fetch(...args) {
+			return await this.#handlers.fetch(...args);
+		}
+		async webSocketMessage(...args) {
+			await this.#handlers.webSocketMessage(...args);
+		}
+		async webSocketClose(...args) {
+			await this.#handlers.webSocketClose(...args);
+		}
+		async webSocketError(...args) {
+			await this.#handlers.webSocketError(...args);
+		}
+		async effectActionsRpc(request) {
+			return await this.#handlers.effectActionsRpc(request);
+		}
+		async alarm(info) {
+			await this.#handlers.alarm(info);
+		}
+		async run(effect) {
+			return await this.#handlers.run(effect);
+		}
+	};
+}
+export { Alarm, State, Tasks, client, handlers, layerHttpClient, layerStubClient, layerWebSocket, layerWebhooks, make, name, placed, reaching, refuseUpgrade };

package/dist/alarm.d.mts

@@ -0,0 +1,42 @@
+import { State } from "./state.mjs";
+import { Context, DateTime, Effect, Layer } from "effect";
+declare const Alarm_base: Context.ServiceClass<Alarm, "effect-actions-cloudflare/ActionDurableObject/Alarm", {
+  /**
+   * Runs the object's `alarm` option no later than `at`: the earliest time set since it last
+   * ran, or a failed run's retry if earlier, so each deadline sets its own. A failed run's
+   * retry stays unless it was cleared as it ran with no time set afterwards, or a time set as
+   * it ran is earlier.
+   *
+   * **Gotchas**
+   *
+   * - A later time leaves an earlier one in place, so the option runs early: postpone with `clear`, then `set`.
+   */
+  readonly set: (at: DateTime.DateTime) => Effect.Effect<void>;
+  /** Cancels the time set, if any. */
+  readonly clear: Effect.Effect<void>;
+}>;
+/**
+ * When the object's `alarm` option runs: `set(at)` has it run no later than `at`, and `clear`
+ * cancels it. A startup service of the object's services, routes, calls and `run`, as `State`
+ * is. The object's one runtime alarm is the package's, set for the earliest of the times it
+ * keeps, the package's own work among them, so an application never sets it itself.
+ *
+ * **Gotchas**
+ *
+ * - `State`'s `storage.setAlarm` replaces the package's alarm: the times it keeps then run at that alarm, early or late, or never, and the `alarm` option runs only for a time `Alarm.set` gave, so schedule with `Alarm`.
+ * - A firing before every time it keeps, as a repeated one or `runDurableObjectAlarm` in a test, runs none and sets the alarm again: a test runs a time once it has come.
+ * - A time already past runs at once; the option runs once for every time set before its run, and sets its next itself.
+ * - The times live in the object's storage, under `effect-actions/alarm/`, beside the application's data: a store deleting every key deletes them too.
+ */
+export declare class Alarm extends Alarm_base {
+  /**
+   * The application's alarm, over the schedule of the instance whose `State` it is given.
+   *
+   * **Gotchas**
+   *
+   * - Only `handlers`' and `make`'s `alarm` runs the times it keeps: provide this layer alone only where nothing calls `set`, as to a store under test.
+   * - Each build makes a schedule of its own, which takes no turns with the object's: a `set` through it while the object's alarm runs may be lost, so an object's own code uses the `Alarm` `handlers` and `make` provide.
+   */
+  static readonly layer: Layer.Layer<Alarm, never, State>;
+}
+export {};