effect-cf 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# effect-cf
+
+## 0.3.0
+
+### Minor Changes
+
+- [#10](https://github.com/danieljvdm/effect-cf/pull/10) [`a0e3f43`](https://github.com/danieljvdm/effect-cf/commit/a0e3f436df695b8ea3908fbb7813efea099ccd13) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Type Durable Object websocket lifecycle handlers with `DurableWebSocket` instead of raw `WebSocket`, so handlers can use the Effect-native durable socket API without manually wrapping Cloudflare sockets.
+
+## 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/README.md

@@ -1,6 +1,6 @@
 # effect-cf
 
-Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, and Durable Object storage.
+Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, Queues, Workflows, and Durable Object storage.
 
 ## Install
 
@@ -31,6 +31,8 @@ Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 - `DurableObjectState` / `DurableObjectStorage` - Effect wrappers for state, alarms, SQL, and embedded KV
 - `DurableObjectWebSocket` - WebSocket upgrade helpers for Durable Objects
 - `Kv` - typed KV namespace helper
+- `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`
 
@@ -71,6 +73,142 @@ export const CounterDurableObject = Counter.make(Layer.empty, {
 
 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 { DurableObject, 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.
+
+`DurableObject.make` lifecycle handlers receive wrapped sockets automatically:
+
+```ts
+export const RoomLive = DurableObject.make(layer, {
+  webSocketMessage: (socket, message) =>
+    Effect.gen(function* () {
+      yield* socket.send(message);
+    }),
+});
+```
+
+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