effect-cf 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # effect-cf
 
+## 0.17.0
+
+### Minor Changes
+
+- [#53](https://github.com/danieljvdm/effect-cf/pull/53) [`b36fc21`](https://github.com/danieljvdm/effect-cf/commit/b36fc2111670c6404a80d51a3c12b10080260256) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add `ContainerNamespace` services for named Cloudflare Container request forwarding and lifecycle operations.
+
+## 0.16.0
+
+### Minor Changes
+
+- [#51](https://github.com/danieljvdm/effect-cf/pull/51) [`9a6abd2`](https://github.com/danieljvdm/effect-cf/commit/9a6abd27366c71867a420f872459b3d5fc1b2143) Thanks [@owensbla](https://github.com/owensbla)! - Add Effect-native Cloudflare Analytics Engine helpers. `AnalyticsEngine.Tag(...)` now provides validated dataset writes, configurable invalid-write policy, and batch write helpers. `AnalyticsEngine.QueryTag(...)` / `makeQueryClient(...)` provide SQL API querying backed by Effect `HttpClient`, config and redacted API token support, typed result envelopes, and row decoding through Effect schemas.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # effect-cf
 
-Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, D1, Queues, Email, Workflows, and Durable Object storage.
+Effect-native Cloudflare primitives for Workers, Durable Objects, Containers, bindings, KV, D1, Queues, Email, Analytics Engine, Workflows, and Durable Object storage.
 
 ## Install
 
@@ -30,12 +30,14 @@ Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 - `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
+- `ContainerNamespace` - named Cloudflare Container instances with Effect-wrapped request and lifecycle operations
 - `Kv` - typed KV namespace helper
 - `D1` - typed D1 database binding helper with an `@effect/sql-d1` backed SQL layer
 - `R2` - typed R2 bucket binding helper with Effect-wrapped object and multipart operations
 - `Hyperdrive` - typed Hyperdrive binding helper for connection strings and optional Postgres SQL integration
 - `Images` - typed Cloudflare Images binding helper with transformation APIs and optional hosted image operations
 - `Email` - typed Cloudflare Send Email binding helper for `send_email` bindings
+- `AnalyticsEngine` - typed Cloudflare Analytics Engine write bindings and SQL API query helpers
 - `Queue` - typed Queue producer/consumer tags plus client and error types
 - `Workflow` - typed Workflow entrypoints, steps, starter clients, and instance types
 - `Rpc` - Cloudflare RPC type helpers and scoped disposal utilities
@@ -84,6 +86,46 @@ export const readCounter = Effect.gen(function* () {
 
 Define Wrangler bindings and migrations in the consuming application. Durable Object namespace bindings are provided with `YourObject.layer({ binding })`, and consumers use `const namespace = yield* YourObject`.
 
+## Container Example
+
+Container entrypoints remain owned by `@cloudflare/containers`; `effect-cf`
+wraps the Container namespace used by a calling Worker.
+
+```ts
+import { Container, switchPort } from "@cloudflare/containers";
+import { Effect, Layer } from "effect";
+import { ContainerNamespace, Worker } from "effect-cf";
+
+export class RendererContainer extends Container {
+  defaultPort = 8080;
+  sleepAfter = "10m";
+}
+
+class Renderers extends ContainerNamespace.Tag<Renderers>()("Renderers") {}
+
+const RenderersLive = Renderers.layer({ binding: "RENDERERS" });
+
+export default Worker.make(RenderersLive, {
+  fetch: Effect.gen(function* () {
+    const request = yield* Worker.NativeRequest;
+    const renderer = Renderers.byName(new URL(request.url).pathname);
+
+    yield* renderer.startAndWaitForPorts({ ports: 8080 });
+    return yield* renderer.fetch(switchPort(request, 8080));
+  }),
+});
+```
+
+The instance client exposes `state`, `fetch`, `start`,
+`startAndWaitForPorts`, `stop`, `destroy`, and the Effect-valued native
+`unsafeRaw` stub.
+Responses are returned unchanged, including non-2xx and WebSocket upgrade
+responses. If the Container uses outbound interception, also export
+`ContainerProxy` from `@cloudflare/containers`.
+
+See [`examples/containers/README.md`](../../examples/containers/README.md) for
+the corresponding Wrangler configuration and entrypoint responsibilities.
+
 ## Queue Example
 
 Queues define the message contract once. The same class is the producer service tag and the consumer Worker definition: use `YourQueue.layer({ binding })` to provide a Cloudflare producer binding from `WorkerEnvironment`, and use `.make(...)` for the consumer Worker entrypoint.
@@ -233,6 +275,87 @@ export const sendWelcomeEmail = (to: string) =>
   });
 ```
 
+## Analytics Engine Example
+
+Analytics Engine tags expose Cloudflare dataset bindings as Effect-wrapped `writeDataPoint(...)` operations. Writes use Cloudflare's native non-blocking runtime API and are validated against Workers Analytics Engine limits before reaching the binding.
+
+```ts
+import { Effect } from "effect";
+import { AnalyticsEngine } from "effect-cf";
+
+class RequestAnalytics extends AnalyticsEngine.Tag<RequestAnalytics>()("RequestAnalytics") {}
+
+export const RequestAnalyticsLayer = RequestAnalytics.layer({
+  binding: "REQUEST_ANALYTICS",
+  write: {
+    onInvalid: "error",
+    batchSize: 100,
+  },
+});
+
+export const recordPageView = (request: Request) =>
+  Effect.gen(function* () {
+    const analytics = yield* RequestAnalytics;
+    const url = new URL(request.url);
+
+    yield* analytics.writeDataPoint({
+      indexes: [url.hostname],
+      blobs: [url.pathname, request.headers.get("cf-connecting-country") ?? "unknown"],
+      doubles: [1],
+    });
+
+    yield* analytics.writeBatch(
+      [
+        {
+          indexes: [url.hostname],
+          blobs: [url.pathname, "page-view"],
+          doubles: [1],
+        },
+      ],
+      { onInvalid: "drop" },
+    );
+  });
+```
+
+Define the dataset binding in the consuming Worker's `wrangler.jsonc` with `analytics_engine_datasets`, then provide `RequestAnalytics.layer({ binding: "REQUEST_ANALYTICS" })` from the Worker layer. Invalid writes fail with `AnalyticsEngineWriteValidationError` by default. Use `write: { onInvalid: "drop" }` on the layer or `{ onInvalid: "drop" }` per call when dropping invalid points is preferable.
+
+Analytics Engine query tags wrap Cloudflare's HTTP SQL API. Configuration can stay in Effect `Config`, including a redacted API token, the outbound transport is an Effect `HttpClient` dependency, and rows can be decoded with Effect schemas at the query boundary. Use `fetchLayerConfig(...)` as shorthand when the platform fetch-backed client is enough.
+
+```ts
+import { Effect, Layer, Schema as S } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { AnalyticsEngine, WorkerConfig } from "effect-cf";
+
+class AnalyticsQuery extends AnalyticsEngine.QueryTag<AnalyticsQuery>()("AnalyticsQuery") {}
+
+export const AnalyticsQueryLayer = AnalyticsQuery.layerConfig(
+  AnalyticsEngine.queryConfig({
+    accountId: WorkerConfig.string("CLOUDFLARE_ACCOUNT_ID"),
+    apiToken: WorkerConfig.redacted("CLOUDFLARE_API_TOKEN"),
+  }),
+).pipe(Layer.provide(FetchHttpClient.layer));
+
+const PageView = S.Struct({
+  path: S.String,
+  views: S.Number,
+});
+
+export const topPages = Effect.gen(function* () {
+  const analytics = yield* AnalyticsQuery;
+
+  return yield* analytics.queryRows(
+    PageView,
+    `
+      SELECT blob1 AS path, SUM(_sample_interval) AS views
+      FROM request_metrics
+      GROUP BY path
+      ORDER BY views DESC
+      LIMIT 10
+    `,
+  );
+});
+```
+
 ## 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.