effect-cf 0.17.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # effect-cf
 
+## 0.20.0
+
+### Minor Changes
+
+- [#64](https://github.com/danieljvdm/effect-cf/pull/64) [`d333039`](https://github.com/danieljvdm/effect-cf/commit/d33303949ac38d2a2e942954d0edbfeeebc16b81) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Upgrade Effect to `4.0.0-beta.105`. The `effect`, `@effect/sql-d1`, `@effect/sql-pg`, and `@effect/sql-sqlite-do` peer ranges now require `^4.0.0-beta.105`, so upgrade Effect alongside this release.
+
+  `CloudflareOtlp` resource precedence has flipped to match Effect's `OtlpResource.fromConfig`. Explicit `resource.serviceName` and `resource.serviceVersion` now take precedence over `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, and `OTEL_RESOURCE_ATTRIBUTES`; previously the environment won. Omit an option to keep letting operators set it from the environment.
+
+## 0.19.0
+
+### Minor Changes
+
+- [#61](https://github.com/danieljvdm/effect-cf/pull/61) [`7aa75de`](https://github.com/danieljvdm/effect-cf/commit/7aa75de93408b1eb345ab530f852db9038923f3d) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Cloudflare Email Service sending support to `Email`.
+
+  Structured messages sent through a `send_email` binding are now validated against documented Email Sending limits — combined `to`/`cc`/`bcc` recipients, attachment count, custom header sizes, and required fields — and fail with `EmailValidationError` before the binding is called. Opt out with `layer({ binding, send: { validate: false } })`. Raw RFC 5322 `EmailMessage` values are still passed through untouched, so the legacy `cloudflare:email` API keeps working.
+
+  Cloudflare's `E_*` error codes are now reported on `EmailOperationError.code`, with the documented set exported as `Email.emailErrorCodes` and `Email.EmailErrorCode`. Documented limits are exported as `Email.sendLimits`.
+
+## 0.18.0
+
+### Minor Changes
+
+- [#58](https://github.com/danieljvdm/effect-cf/pull/58) [`c5bac36`](https://github.com/danieljvdm/effect-cf/commit/c5bac367587c314a17b32e984faee546a488f1ff) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Effect-native support for Cloudflare's default and named Cache API instances, including typed operation errors and `Option`-based cache misses.
+
 ## 0.17.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # effect-cf
 
-Effect-native Cloudflare primitives for Workers, Durable Objects, Containers, bindings, KV, D1, Queues, Email, Analytics Engine, Workflows, and Durable Object storage.
+Effect-native Cloudflare primitives for Workers, Durable Objects, Containers, bindings, Cache, KV, D1, Queues, Email, Analytics Engine, Workflows, and Durable Object storage.
 
 ## Install
 
@@ -31,12 +31,13 @@ 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
 - `ContainerNamespace` - named Cloudflare Container instances with Effect-wrapped request and lifecycle operations
+- `Cache` - Effect wrapper for Cloudflare's default and named Cache API instances
 - `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
+- `Email` - typed Cloudflare Email Service binding helper for `send_email` bindings, with limit validation and typed error codes
 - `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
@@ -161,6 +162,38 @@ Producers should usually use `const queue = yield* AvatarQueue` and then call `q
 
 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.
 
+## Cache Example
+
+`Cache.layer` exposes Cloudflare's global Cache API as an Effect service. Cache misses are represented by `Option.none()`, and named caches are available through `open(...)`.
+
+```ts
+import { Effect, Option } from "effect";
+import { Cache, Worker } from "effect-cf";
+
+export default Worker.make(Cache.layer, {
+  fetch: Effect.gen(function* () {
+    const request = yield* Worker.NativeRequest;
+    const storage = yield* Cache.CacheStorage;
+    const cached = yield* storage.default.match(request);
+
+    if (Option.isSome(cached)) {
+      return cached.value;
+    }
+
+    const response = new Response("fresh", {
+      headers: { "Cache-Control": "public, max-age=300" },
+    });
+
+    const context = yield* Worker.WorkerContext;
+    yield* context.waitUntil(storage.default.put(request, response.clone()));
+
+    return response;
+  }),
+});
+```
+
+Use `const cache = yield* storage.open("api-cache")` for a named cache. `match`, `put`, `delete`, and `open` failures are reported as `CacheOperationError` values.
+
 ## R2 Example
 
 R2 bucket tags expose Cloudflare object operations as Effects and map nullable reads to `Option`.
@@ -251,7 +284,7 @@ export const resizeAvatar = (image: Images.ImageInputValue) =>
 
 ## Email Example
 
-Email tags expose Cloudflare Send Email bindings as Effect-wrapped `send(...)` operations.
+Email tags expose Cloudflare Email Service `send_email` bindings as Effect-wrapped `send(...)` operations. Structured messages are validated against documented Email Sending limits before reaching the binding, and Cloudflare's `E_*` error codes are surfaced on `EmailOperationError.code`.
 
 ```ts
 import { Effect } from "effect";
@@ -275,6 +308,20 @@ export const sendWelcomeEmail = (to: string) =>
   });
 ```
 
+Onboard the sending domain under **Compute > Email Service > Email Sending**, then declare the binding in the consuming Worker's `wrangler.jsonc`:
+
+```jsonc
+{
+  "send_email": [{ "name": "EMAIL" }],
+}
+```
+
+Messages that violate a documented limit fail with `EmailValidationError` carrying every violation, without calling the binding. Use `layer({ binding, send: { validate: false } })` to skip validation and let Cloudflare reject the message instead. Raw RFC 5322 `EmailMessage` values are always passed through untouched, so the legacy `cloudflare:email` API keeps working.
+
+Cloudflare's total message size limit is exposed as `Email.sendLimits.maxMessageBytes` but is not enforced, because the encoded MIME size is only known once Cloudflare composes the message. Oversized messages fail at the binding with `E_CONTENT_TOO_LARGE`.
+
+See [`examples/email/README.md`](../../examples/email/README.md) for domain onboarding, binding restrictions, and typed recovery from `EmailValidationError` and `EmailOperationError`.
+
 ## 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.

package/dist/{Hyperdrive-C0vfrPeG.d.mts → Hyperdrive-RTjgirMV.d.mts}

@@ -1,9 +1,4 @@
 import { Config, ConfigProvider, Context, Effect, Layer } from "effect";
-import * as _$effect_Types0 from "effect/Types";
-import * as _$effect_Cause0 from "effect/Cause";
-import * as _$effect_Redacted0 from "effect/Redacted";
-import * as _$effect_Layer0 from "effect/Layer";
-
 //#region src/Environment.d.ts
 /** Cloudflare worker environment object (`env`). */
 type WorkerEnv = Cloudflare.Env;
@@ -13,7 +8,7 @@ declare const WorkerEnvironment_base: Context.ServiceClass<WorkerEnvironment, "e
  */
 declare class WorkerEnvironment extends WorkerEnvironment_base {}
 type ScalarConfigValue = string | number | boolean;
-type ScalarConfigKey = Extract<{ readonly [Key in keyof Cloudflare.Env]-?: NonNullable<Cloudflare.Env[Key]> extends ScalarConfigValue ? Key : never }[keyof Cloudflare.Env], string>;
+type ScalarConfigKey = Extract<{ readonly [Key in keyof Cloudflare.Env]-?: NonNullable<Cloudflare.Env[Key]> extends ScalarConfigValue ? Key : never; }[keyof Cloudflare.Env], string>;
 /**
  * Effect `Config` helpers for scalar Cloudflare vars and secrets declared on
  * `Cloudflare.Env`.
@@ -49,7 +44,7 @@ declare namespace WorkerConfig {
   /** Read a scalar Cloudflare var or secret as a string. */
   const string: <const Name extends Key>(name: Name) => Config.Config<string>;
   /** Read a scalar Cloudflare secret as a redacted string. */
-  const redacted: <const Name extends Key>(name: Name) => Config.Config<_$effect_Redacted0.Redacted<string>>;
+  const redacted: <const Name extends Key>(name: Name) => Config.Config<import("effect/Redacted").Redacted<string>>;
   /** Read a scalar Cloudflare var or secret as a number. */
   const number: <const Name extends Key>(name: Name) => Config.Config<number>;
   /** Read a scalar Cloudflare var or secret as an integer. */
@@ -69,18 +64,18 @@ declare namespace WorkerConfig {
    * Replace the active Effect `ConfigProvider` with one backed by the current
    * Cloudflare worker `env` object.
    */
-  const providerLayer: _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+  const providerLayer: import("effect/Layer").Layer<never, never, WorkerEnvironment>;
   /** Alias for `providerLayer` for concise use in worker layers. */
-  const layer: _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+  const layer: import("effect/Layer").Layer<never, never, WorkerEnvironment>;
   /** Build a `ConfigProvider` layer with a custom `env` conversion function. */
-  const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+  const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => import("effect/Layer").Layer<never, never, WorkerEnvironment>;
 }
 declare namespace Binding_d_exports {
   export { BindingNotFoundError, BindingService, BindingValidationError, Service, TypeId, ValidationOptions, layer$1 as layer };
 }
 /** Internal type id marker used by binding helper services. */
 declare const TypeId: "effect-cf/Binding";
-declare const BindingNotFoundError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const BindingNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "BindingNotFoundError";
 } & Readonly<A>;
 /** Error raised when a configured binding does not exist on `env`. */
@@ -88,7 +83,7 @@ declare class BindingNotFoundError extends BindingNotFoundError_base<{
   readonly binding: string;
   readonly message: string;
 }> {}
-declare const BindingValidationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const BindingValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "BindingValidationError";
 } & Readonly<A>;
 /** Error raised when a binding exists but does not match the expected shape. */

package/dist/HyperdrivePg.d.mts

@@ -1,14 +1,10 @@
-import { i as BindingNotFoundError, n as LayerOptions, o as BindingValidationError, r as TagClass, u as WorkerEnvironment } from "./Hyperdrive-C0vfrPeG.mjs";
+import { i as BindingNotFoundError, n as LayerOptions, o as BindingValidationError, r as TagClass, u as WorkerEnvironment } from "./Hyperdrive-RTjgirMV.mjs";
 import { Layer } from "effect";
 import { PgClient } from "@effect/sql-pg";
-import * as _$effect_unstable_sql_SqlClient0 from "effect/unstable/sql/SqlClient";
-import * as _$effect_unstable_sql_SqlError0 from "effect/unstable/sql/SqlError";
-import * as _$effect_Scope0 from "effect/Scope";
-
 //#region src/HyperdrivePg.d.ts
 type PgLayerOptions = Omit<PgClient.PgClientConfig & {
   readonly acquireForStream?: boolean;
 }, "url" | "host" | "port" | "path" | "ssl" | "database" | "username" | "password" | "stream">;
-declare const layer: <Self, Id extends string>(tag: TagClass<Self, Id>, binding: LayerOptions, options?: PgLayerOptions) => Layer.Layer<PgClient.PgClient | _$effect_unstable_sql_SqlClient0.SqlClient, BindingNotFoundError | BindingValidationError | _$effect_unstable_sql_SqlError0.SqlError, WorkerEnvironment | Exclude<Exclude<Self, _$effect_Scope0.Scope>, Self>>;
+declare const layer: <Self, Id extends string>(tag: TagClass<Self, Id>, binding: LayerOptions, options?: PgLayerOptions) => Layer.Layer<PgClient.PgClient | import("effect/unstable/sql/SqlClient").SqlClient, BindingNotFoundError | BindingValidationError | import("effect/unstable/sql/SqlError").SqlError, WorkerEnvironment | Exclude<Exclude<Self, import("effect/Scope").Scope>, Self>>;
 //#endregion
 export { PgLayerOptions, layer };

package/dist/HyperdrivePg.mjs

@@ -1,4 +1,3 @@
-import "./Hyperdrive-89hg_Fck.mjs";
 import { Effect, Layer, Redacted } from "effect";
 import { PgClient } from "@effect/sql-pg";
 //#region src/HyperdrivePg.ts