effect-cf 0.0.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# effect-cf
+
+## 0.2.0
+
+### Minor Changes
+
+- [#5](https://github.com/danieljvdm/effect-cf/pull/5) [`a17685f`](https://github.com/danieljvdm/effect-cf/commit/a17685fe3873c18994102fad6c6b4074f2b3b1e8) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Effect-native Durable Object WebSocket APIs for hibernatable application sockets.
+
+  `DurableObjectWebSocket.acceptUpgrade` now returns a wrapped `DurableWebSocket` server socket with Effect-based `send`, `close`, and attachment helpers. `DurableObjectState.getWebSockets` and `acceptWebSocket` now use the same wrapper, and schema-backed attachment helpers support typed rehydration of hibernated sockets.
+
+- [#7](https://github.com/danieljvdm/effect-cf/pull/7) [`2af014c`](https://github.com/danieljvdm/effect-cf/commit/2af014ca704bf0a170133cadebe4572ccc67e020) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Effect-native Cloudflare Queue and Workflow primitives with typed definitions, producer/control bindings, runtime entrypoints, and runnable examples.
+
+- [#3](https://github.com/danieljvdm/effect-cf/pull/3) [`219f568`](https://github.com/danieljvdm/effect-cf/commit/219f568639c324da9681de6c34e4e45189ac7972) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add a fetch-handler shorthand for `Worker.make(layer, effect)`.
+
+## 0.1.0
+
+Initial public release.
+
+- Add Effect-native Worker and Durable Object entrypoint helpers.
+- Add typed Worker service binding and Durable Object namespace helpers.
+- Add KV, Durable Object state/storage, RPC, and WebSocket primitives.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan van der Merwe
+
+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,70 +1,58 @@
 # effect-cf
 
-Effect-native primitives for Cloudflare Workers and bindings.
+Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, Queues, Workflows, and Durable Object storage.
 
-## Design Goal
+## Install
 
-Cloudflare services should be described as `Context`, `Layer`, and `Effect` values and executed through package-owned Cloudflare entrypoint/runtime boundaries. Consumer code should stay in `Effect`; bindings and storage helpers wrap Promise-returning Cloudflare APIs so applications do not call `Effect.runPromise` or manually bridge Promises.
+`effect-cf` currently targets Effect 4 beta.
 
-The low-level Worker entrypoint factory is exported as `Worker.make`. It returns a `WorkerEntrypoint` class with a `fetch` handler and optional typed RPC methods. Durable Object support starts with `DurableObject.make`, which routes Durable Object lifecycle methods and RPC handlers through one managed runtime for each Durable Object instance.
-
-Worker fetch handlers can return either web `Response` values or Effect `HttpServerResponse` values. `Worker.make` renders `HttpServerResponse` back to a web `Response` at the Cloudflare boundary, so application handlers can stay in Effect HTTP primitives.
-
-Request-scoped app services belong in the implementation layer that owns request semantics, such as `HttpRouter` middleware, RPC middleware, or explicit `Effect.provide(...)` inside a custom fetch effect. `Worker.make` stays focused on Cloudflare boundary services: `NativeRequest`, `HttpServerRequest`, `WorkerEnvironment`, `ExecutionContext`, and `WorkerContext`.
+```bash
+bun add effect-cf "effect@^4.0.0-beta.65"
+```
 
-For modules that need an `ExportedHandler` object instead of a `WorkerEntrypoint` class, use `Worker.makeFetchHandler`. This helper is fetch-only and intentionally does not accept Worker RPC methods.
+```bash
+pnpm add effect-cf "effect@^4.0.0-beta.65"
+```
 
-RPC contracts can be described as classes with `Worker.Tag` and `DurableObject.Tag`. Contract classes expose `.make(...)` for runtime entrypoint creation and `.Binding(...)` / `.Namespace(...)` for typed bindings. Bindings infer call types from the same code-owned contract classes. Definition-backed calls encode/decode arguments and success values with their Effect schemas at Worker and Durable Object boundaries.
+```bash
+npm install effect-cf "effect@^4.0.0-beta.65"
+```
 
-Binding helpers expose two RPC paths:
+## Goal
 
-- `call(...)` awaits one RPC result inside `Effect`. Use it for ordinary structured-cloneable values.
-- `rpc(...)` returns Cloudflare's native RPC thenable/stub without awaiting it, preserving promise pipelining.
-- `scopedCall(...)` awaits the result and registers any `Symbol.dispose` disposer with the current Effect `Scope`.
+Cloudflare APIs return promises and expose platform-specific bindings. `effect-cf` wraps those boundaries as `Context`, `Layer`, and `Effect` values so application code stays inside one managed Effect runtime.
 
-Client APIs use Cloudflare-style provider types, so object results expose pipelined property and method access. `ServerApi` remains available when a plain implementation-shaped `(...args) => Promise<A>` contract is needed.
+Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 
-## Current Exports
+## Exports
 
-- `Worker` - WorkerEntrypoint class factory, schema-backed RPC contract tags, and service binding helpers
-- `DurableObject` - Durable Object class factory, schema-backed RPC contract tags, and namespace helpers
-- `WorkerDefinition`, `DurableObjectDefinition` - compatibility exports for the lower-level definition modules
-- `DurableObjectNamespace` - typed Durable Object namespace binding helper
-- `DurableObjectState`, `DurableObjectStorage` - small Effect wrappers for Durable Object state, alarms, SQL, and embedded KV storage
-- `DurableObjectWebSocket` - Durable Object WebSocket upgrade helpers built on `WebSocketPair` and `acceptWebSocket`
-- `Binding` - low-level binding service helper
+- `Worker` - Worker entrypoint factory, request services, and typed Worker bindings
+- `DurableObject` - Durable Object entrypoint factory and typed namespace helpers
+- `DurableObjectState` / `DurableObjectStorage` - Effect wrappers for state, alarms, SQL, and embedded KV
+- `DurableObjectWebSocket` - WebSocket upgrade helpers for Durable Objects
 - `Kv` - typed KV namespace helper
-- `Rpc` - Cloudflare RPC type helpers, `RpcTarget` / `RpcStub` re-exports, and scoped disposal utilities
-- `ServiceBinding` - typed Worker-to-Worker service binding helper
-- `WorkerEnvironment` - request environment service
-- `WorkerConfig` - Effect `Config` helpers backed by Cloudflare worker `env`, including `layerWith` for custom env-to-config mapping
+- `Queue` / `QueueBinding` - typed Queue producer bindings and consumer handlers
+- `Workflow` / `WorkflowBinding` - typed Workflow entrypoints, steps, and starter bindings
+- `Rpc` - Cloudflare RPC type helpers and scoped disposal utilities
+- `WorkerConfig` - Effect `Config` helpers backed by Cloudflare `env`
 
-## RPC Values
-
-Definition-backed RPC methods are intended for schema-backed structured values. If a Cloudflare RPC method returns a lifecycle-managed RPC object or stub, expose that through a lower-level binding API instead of a `WorkerDefinition` / `DurableObjectDefinition` method so disposal remains explicit.
-
-## Durable Object WebSocket Example
+## Worker Example
 
 ```ts
-const request = yield * Worker.NativeRequest;
-
-if (!Worker.isWebSocketUpgrade(request)) {
-  return new Response("Expected WebSocket upgrade", { status: 426 });
-}
+import { HttpServerResponse } from "effect";
+import { Worker } from "effect-cf";
 
-const upgrade =
-  yield *
-  DurableObjectWebSocket.acceptUpgrade({
-    tags: ["room:general"],
-    attachment: { roomId: "general" },
-  });
-
-return upgrade.response;
+export default Worker.make({
+  fetch: () => HttpServerResponse.text("ok"),
+});
 ```
 
 ## Durable Object Example
 
 ```ts
+import { Effect, Layer, Schema as S } from "effect";
+import { DurableObject, DurableObjectState } from "effect-cf";
+
 export class Counter extends DurableObject.Tag<Counter>()("Counter", {
   get: DurableObject.method({ success: S.Number }),
 }) {}
@@ -83,4 +71,133 @@ export const CounterDurableObject = Counter.make(Layer.empty, {
 });
 ```
 
-Define the Wrangler binding and SQLite migration in the application. This package intentionally does not replace `wrangler.jsonc`.
+Define Wrangler bindings and migrations in the consuming application.
+
+## Queue Example
+
+Queues use the same definition + binding split as Workers and Durable Objects: define the message contract once, use `.binding(...)` or `.Binding(...)` to produce from any runtime with `WorkerEnvironment`, and use `.make(...)` for the consumer Worker entrypoint.
+
+```ts
+import { Effect, Layer, Schema as S } from "effect";
+import { Queue } from "effect-cf";
+
+class AvatarJobs extends Queue.Tag<AvatarJobs>()("AvatarJobs", {
+  message: S.Struct({ userId: S.String, imageKey: S.String }),
+}) {}
+
+export const AvatarQueue = AvatarJobs.binding("AvatarQueue", {
+  binding: "AVATAR_QUEUE",
+});
+
+export const AvatarQueueConsumer = AvatarJobs.make(Layer.empty, {
+  queue: (batch) =>
+    Effect.gen(function* () {
+      for (const message of batch.messages) {
+        yield* Effect.logInfo("process avatar", message.body.userId);
+        yield* message.ack;
+      }
+    }),
+});
+```
+
+Producers can use `AvatarQueue.send(...)`, `AvatarQueue.sendBatch(...)`, and `AvatarQueue.metrics` from any Worker, Durable Object, or Workflow layer that provides `WorkerEnvironment`.
+
+Queue handlers run inline failures through Cloudflare's normal retry path. If background work scheduled with `WorkerContext.waitUntil(...)` should also make the batch retry, use `WorkerContext.waitUntilPropagating(...)` or `waitUntil(..., { mode: "propagate" })`; the default `waitUntil` mode observes and logs failures without rejecting the native `waitUntil` promise.
+
+## Workflow Example
+
+Workflow definitions type the payload and result. Runtime handlers can access `Workflow.WorkflowEvent`, use durable `Workflow.step(...)`, and use normal binding services inside steps.
+
+```ts
+import { Effect, Layer, Schema as S } from "effect";
+import { Workflow } from "effect-cf";
+
+class ExportWorkflow extends Workflow.Tag<ExportWorkflow>()("ExportWorkflow", {
+  payload: S.Struct({ segmentId: S.String }),
+  result: S.Struct({ objectKey: S.String }),
+}) {}
+
+export const ExportWorkflowEntrypoint = ExportWorkflow.make(Layer.empty, {
+  run: (payload) =>
+    Effect.gen(function* () {
+      const objectKey = yield* Workflow.step(
+        "write-export",
+        Effect.succeed(`exports/${payload.segmentId}.json`),
+      );
+
+      return { objectKey };
+    }),
+});
+
+export const ExportWorkflowBinding = ExportWorkflow.binding("ExportWorkflow", {
+  binding: "EXPORT_WORKFLOW",
+});
+```
+
+Use `ExportWorkflowBinding.create(...)`, `createBatch(...)`, and `get(...)` to start and inspect instances.
+
+In definition-backed workflows, the `payload` argument is the typed decoded payload and is the source of truth. `Workflow.WorkflowEvent.payload` is also re-provided decoded for convenience; `Workflow.WorkflowEvent.raw.payload` remains the native Cloudflare event payload.
+
+## Durable Object WebSockets
+
+Durable Object application sockets should use the hibernation-compatible state API. Accept sockets with `DurableObjectWebSocket.acceptUpgrade(...)`; do not call `server.accept()` or attach native `message` listeners in application code.
+
+```ts
+import { Effect, Schema as S } from "effect";
+import { DurableObjectState, DurableObjectWebSocket, Worker } from "effect-cf";
+
+const ConnectionAttachment = S.Struct({
+  id: S.String,
+  roomId: S.String,
+});
+
+const Attachments = DurableObjectWebSocket.attachment(ConnectionAttachment);
+
+export const fetch = Effect.gen(function* () {
+  const request = yield* Worker.NativeRequest;
+
+  if (!Worker.isWebSocketUpgrade(request)) {
+    return new Response("Expected WebSocket upgrade", { status: 426 });
+  }
+
+  const upgrade = yield* DurableObjectWebSocket.acceptUpgrade({ tags: ["room:general"] });
+  yield* Attachments.serialize(upgrade.server, {
+    id: crypto.randomUUID(),
+    roomId: "general",
+  });
+  yield* upgrade.server.send(JSON.stringify({ type: "ready" }));
+
+  return upgrade.response;
+});
+```
+
+`DurableWebSocket` keeps the native socket available as `socket.raw`, while `send`, `close`, `serializeAttachment`, and `deserializeAttachment` return typed `Effect` failures. Use `state.getWebSockets(tag)` to retrieve wrapped sockets for broadcast and rehydration.
+
+Schema-backed attachments can rehydrate hibernated sockets:
+
+```ts
+const restored =
+  yield *
+  Attachments.rehydrate({
+    tag: "room:general",
+    onInvalid: "ignore-and-close",
+  });
+
+for (const { socket, attachment } of restored) {
+  yield * socket.send(`restored:${attachment.id}`).pipe(Effect.ignore);
+}
+```
+
+Worker-to-Durable-Object forwarding should stay native so WebSocket upgrade responses are preserved:
+
+```ts
+if (Worker.isWebSocketUpgrade(request)) {
+  return yield * ChatRooms.byName(roomId).fetch(request);
+}
+```
+
+Use `DurableObjectRpcWebSocket.layer(...)` for Effect RPC-over-WebSocket transports. It owns protocol parsing and RPC client bookkeeping; use `DurableWebSocket` for general application sockets, rooms, presence, and broadcast flows.
+
+## License
+
+MIT