effect-cf 0.20.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # effect-cf
 
+## 0.23.0
+
+### Minor Changes
+
+- [#78](https://github.com/danieljvdm/effect-cf/pull/78) [`f753742`](https://github.com/danieljvdm/effect-cf/commit/f753742500603ea604f4f11d4c7840a41efb849b) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Extend the `ContainerNamespace` client with the remaining caller-side Container primitives: `waitForPort` (preserving the native retry-count result), the runtime host-policy operations (`setAllowedHosts`, `setDeniedHosts`, `allowHost`, `denyHost`, `removeAllowedHost`, `removeDeniedHost`), and numeric stop signals alongside the named ones. `ContainerNamespace.Tag` now accepts an optional exact native namespace type (for example `DurableObjectNamespace<CodexSandbox>`) so `rawUnsafe` on the namespace and on named instances preserves the exact native namespace and stub types, including extra subclass methods. Existing consumers compile unchanged via default type parameters.
+
+- [#78](https://github.com/danieljvdm/effect-cf/pull/78) [`f753742`](https://github.com/danieljvdm/effect-cf/commit/f753742500603ea604f4f11d4c7840a41efb849b) Thanks [@danieljvdm](https://github.com/danieljvdm)! - `DurableObjectState.waitUntil` now also accepts an Effect, running it in the background with the caller's Effect context and the same failure modes as `WorkerContext.waitUntil` (`"observe"` logs or routes failures to `onFailure`; `"propagate"` also rejects the native `waitUntil` promise). The existing Promise form is unchanged, so Durable Objects no longer need to capture a Context and call `Effect.runPromiseWith` to schedule background Effects.
+
+## 0.22.0
+
+### Minor Changes
+
+- [#73](https://github.com/danieljvdm/effect-cf/pull/73) [`9096e1e`](https://github.com/danieljvdm/effect-cf/commit/9096e1e6801bb9ac29ce8de0fa30902d9e210983) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Encode RPC method schemas through their canonical JSON codec at the Workers RPC boundary. Declaration schemas such as `Schema.Result` keep their container instance in their encoded form, so Durable Object, Worker entrypoint, and service binding RPC methods declared with them crashed in production with `DataCloneError` even though local same-isolate calls worked. Wire values are now plain JSON in both directions: clients encode arguments and decode results back into real instances, servers decode arguments and encode results, and codec failures still surface as tagged errors naming the definition and method. The `Method.EncodedArgs` and `Method.EncodedSuccess` utility types now report the JSON wire form.
+
+## 0.21.0
+
+### Minor Changes
+
+- [#69](https://github.com/danieljvdm/effect-cf/pull/69) [`16d6190`](https://github.com/danieljvdm/effect-cf/commit/16d6190bc022f040b6e9ddb1f583a973357598c3) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Align effect-cf with effect 4.0.0-beta.105 canonical APIs. This release contains breaking renames alongside behavior fixes surfaced by a full audit of the beta.65 → beta.105 upgrade.
+
+  Breaking changes:
+
+  - `unsafeRaw` is now `rawUnsafe` on every binding client and definition tag, following the effect v4 `Unsafe`-suffix convention. Definition tag statics are now Effect properties (matching the client shape) rather than zero-arg functions.
+  - `Kv` clients: `remove` is now `delete`.
+  - Layer variants renamed: `AnalyticsEngine.queryFetchLayer`/`queryFetchLayerConfig` → `layerFetch`/`layerFetchConfig` (tag fields `fetchLayer`/`fetchLayerConfig` likewise); `CloudflareOtlp.workerLayer`/`durableObjectLayer` → `layerWorker`/`layerDurableObject`.
+  - Definition tags (Durable Objects, Queues, Workflows, Containers, Bindings) are keyed as `effect-cf/<Module>/<id>` instead of the bare user id, so a definition named `"X"` no longer silently collides with an unrelated service keyed `"X"`. `definition.id` is unchanged.
+  - Queue producers must provide `sendBatch`; the silent sequential-send fallback (which lost batch atomicity) was removed and now fails with `QueueOperationError`.
+  - `Worker.renderHttpResponse` removed — return `HttpServerResponse` values directly from fetch handlers to get canonical response handling, including streaming-scope transfer.
+  - `RpcDefinition`: the plain-Error `ReservedMethodNameError` and `assertNoReservedMethodNames` were removed (use `assertNoReservedMethods`, which now throws the tagged `RpcReservedMethodNameError`); the `index` field was removed from argument encode/decode errors (positional info lives in the schema issue path).
+  - `Worker.TagFactory` / `DurableObject.TagFactory` types removed; the definition type surface is now re-exported from `WorkerDefinition`/`DurableObjectDefinition`.
+  - The unexported legacy `Entry` module and the internal Cloudflare clock were deleted; the effect default clock is used (its epoch time is monotonic-anchored, so it may skew from `Date.now()` by microseconds).
+  - effect peer dependencies are pinned exactly to `4.0.0-beta.105` while the package depends on `effect/unstable/*` modules.
+
+  Fixes:
+
+  - `DurableObjectSqlite.layer` now passes Durable Object storage to the SQL client, so `sql.withTransaction` works — previously every transaction failed at runtime.
+  - `CloudflareOtlp` layers now expose `OtlpExporter.Flusher`, and Worker fetch handlers automatically flush buffered telemetry via `ctx.waitUntil` after each response — telemetry is no longer lost when the isolate freezes after responding.
+  - Worker fetch handlers built with `makeFetchHandler` cache the runtime per environment instead of rebuilding every layer on each request.
+  - RPC method errors keep their tags across the Workers RPC wire: `RpcArgumentCountError`, `RpcArgumentDecodeError`, and `RpcSuccessEncodeError` are schema-serialized at the entrypoint and rehydrated as tagged instances on the caller side.
+  - The Durable Object RPC WebSocket transport closes the socket with code 1009 when a frame exceeds the serialization buffer limit instead of leaving the connection in a poisoned state.
+  - `DurableObjectWebSocket.acceptUpgrade` fails with a typed `DurableWebSocketAttachmentError` for non-serializable attachments instead of an untyped defect.
+  - Cloudflare Workflow steps fail with a typed `WorkflowStepError` carrying the step name, operation, and cause instead of leaking raw `unknown` rejections.
+  - `AiGateway` HTTP requests abort in-flight fetches when the running fiber is interrupted, and merge a caller-supplied `AbortSignal`.
+
+  Additions:
+
+  - Named tracing spans across the public client surface (`Kv.put`, `R2.get`, `DurableObject.call`, `QueueBinding.send`, `Email.send`, ...) with binding/operation attributes, so operations show up in the OTLP traces the package exports.
+  - Error classes render actionable messages by default: `Cause.pretty` and logs now show the binding, operation, error code when present, and the underlying cause instead of an empty message with a stack trace.
+  - `WorkerConfig.providerFromEnv` accepts `{ preserveEmptyStrings: true }` for environments where an empty-string var must decode as `""` rather than as absent.
+  - `Email` error `code` extraction is documented as best-effort (dev-time remote-proxy bindings can strip the property).
+  - `package.json` declares `sideEffects: []` for better tree-shaking of Workers bundles, and `@cloudflare/workers-types` is an optional peer for consumers type-checking against the public declarations.
+
 ## 0.20.1
 
 ### Patch Changes

package/README.md

@@ -87,6 +87,12 @@ 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`.
 
+`DurableObjectState.waitUntil` accepts either a raw Promise or an Effect. The
+Effect form runs in the background with the caller's Effect context and the
+same failure modes as `WorkerContext.waitUntil`, so Durable Objects can
+schedule background Effects (for example a pump consuming an outbound
+WebSocket) without capturing a Context and calling `Effect.runPromiseWith`.
+
 ## Container Example
 
 Container entrypoints remain owned by `@cloudflare/containers`; `effect-cf`
@@ -118,12 +124,30 @@ export default Worker.make(RenderersLive, {
 ```
 
 The instance client exposes `state`, `fetch`, `start`,
-`startAndWaitForPorts`, `stop`, `destroy`, and the Effect-valued native
-`unsafeRaw` stub.
+`startAndWaitForPorts`, `waitForPort`, `stop` (named or numeric signals),
+`destroy`, the runtime host-policy operations (`setAllowedHosts`,
+`setDeniedHosts`, `allowHost`, `denyHost`, `removeAllowedHost`,
+`removeDeniedHost`), and the Effect-valued native `rawUnsafe` stub.
+Host-policy operations only forward the native remote calls; applications
+continue to own hostname policy and outbound handlers.
 Responses are returned unchanged, including non-2xx and WebSocket upgrade
 responses. If the Container uses outbound interception, also export
 `ContainerProxy` from `@cloudflare/containers`.
 
+`ContainerNamespace.Tag` accepts an optional second type parameter carrying
+the exact native namespace type. `rawUnsafe` on the namespace and on named
+instances then preserves that exact type, including extra subclass methods,
+instead of the minimal structural shape:
+
+```ts
+class Sandboxes extends ContainerNamespace.Tag<Sandboxes, DurableObjectNamespace<CodexSandbox>>()(
+  "Sandboxes",
+) {}
+
+// Effect<DurableObjectStub<CodexSandbox>, ContainerOperationError, Sandboxes>
+const stub = Sandboxes.byName("codex").rawUnsafe;
+```
+
 See [`examples/containers/README.md`](../../examples/containers/README.md) for
 the corresponding Wrangler configuration and entrypoint responsibilities.
 
@@ -366,7 +390,7 @@ export const recordPageView = (request: Request) =>
 
 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.
+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 `layerFetchConfig(...)` as shorthand when the platform fetch-backed client is enough.
 
 ```ts
 import { Effect, Layer, Schema as S } from "effect";

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

@@ -1,5 +1,7 @@
 import { Config, ConfigProvider, Context, Effect, Layer } from "effect";
-//#region src/Environment.d.ts
+declare namespace Environment_d_exports {
+  export { WorkerConfig, WorkerEnv, WorkerEnvironment };
+}
 /** Cloudflare worker environment object (`env`). */
 type WorkerEnv = Cloudflare.Env;
 declare const WorkerEnvironment_base: Context.ServiceClass<WorkerEnvironment, "effect-cf/WorkerEnvironment", Cloudflare.Env>;
@@ -51,8 +53,23 @@ declare namespace WorkerConfig {
   const integer: <const Name extends Key>(name: Name) => Config.Config<number>;
   /** Read a scalar Cloudflare var or secret as a boolean. */
   const boolean: <const Name extends Key>(name: Name) => Config.Config<boolean>;
-  /** Build a `ConfigProvider` from a Cloudflare worker `env` object. */
-  const providerFromEnv: (env: WorkerEnv) => ConfigProvider.ConfigProvider;
+  /** Options for building a `ConfigProvider` from a Cloudflare worker `env` object. */
+  interface ProviderOptions {
+    /**
+     * Keep empty-string env values as explicit `""` config values.
+     *
+     * By default (absent or `false`), empty strings are treated as missing
+     * config, matching `ConfigProvider.fromUnknown`.
+     */
+    readonly preserveEmptyStrings?: boolean;
+  }
+  /**
+   * Build a `ConfigProvider` from a Cloudflare worker `env` object.
+   *
+   * Empty-string values are treated as missing config by default; pass
+   * `{ preserveEmptyStrings: true }` to keep them as explicit values.
+   */
+  const providerFromEnv: (env: WorkerEnv, options?: ProviderOptions) => ConfigProvider.ConfigProvider;
   /**
    * Build a `ConfigProvider` from the current `WorkerEnvironment` with a custom
    * conversion function.
@@ -64,17 +81,19 @@ declare namespace WorkerConfig {
    * Replace the active Effect `ConfigProvider` with one backed by the current
    * Cloudflare worker `env` object.
    */
-  const providerLayer: import("effect/Layer").Layer<never, never, WorkerEnvironment>;
+  const providerLayer: Layer.Layer<never, never, WorkerEnvironment>;
   /** Alias for `providerLayer` for concise use in worker layers. */
-  const layer: import("effect/Layer").Layer<never, never, WorkerEnvironment>;
+  const layer: Layer.Layer<never, never, WorkerEnvironment>;
   /** Build a `ConfigProvider` layer with a custom `env` conversion function. */
-  const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => import("effect/Layer").Layer<never, never, WorkerEnvironment>;
+  const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => 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 TypeId: "~effect-cf/Binding";
+/** Internal type id marker used by binding helper services. */
+type TypeId = typeof TypeId;
 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>;
@@ -98,14 +117,22 @@ interface ValidationOptions {
 }
 /**
  * Creates a Context tag + layer for reading and validating a Cloudflare binding.
+ *
+ * The Context key is namespaced as `effect-cf/Binding/<id>`; `id` stays the
+ * bare user-supplied identifier.
  */
-interface BindingService<Self, Id extends string, Service> extends Context.ServiceClass<Self, Id, Service> {
-  readonly [TypeId]: typeof TypeId;
+interface BindingService<Self, Id extends string, Service> extends Context.ServiceClass<Self, `effect-cf/Binding/${Id}`, Service> {
+  readonly [TypeId]: TypeId;
+  readonly id: Id;
   readonly binding: string;
   readonly layer: Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
 }
-declare const layer$1: <Self, Resource, Service = Resource>(tag: Context.Service<Self, Service>, binding: string, isResource: (value: unknown) => value is Resource, wrap?: (resource: Resource) => Service, options?: ValidationOptions) => Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
-declare const Service: <Self>() => <Id extends string, Resource, Service = Resource>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap?: (resource: Resource) => Service, options?: ValidationOptions) => BindingService<Self, Id, Service>;
+declare function layer$1<Self, Resource>(tag: Context.Service<Self, Resource>, binding: string, isResource: (value: unknown) => value is Resource, wrap?: undefined, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+declare function layer$1<Self, Resource, Service>(tag: Context.Service<Self, Service>, binding: string, isResource: (value: unknown) => value is Resource, wrap: (resource: Resource) => Service, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+declare const Service: <Self>() => {
+  <Id extends string, Resource>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap?: undefined, options?: ValidationOptions): BindingService<Self, Id, Resource>;
+  <Id extends string, Resource, Service>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap: (resource: Resource) => Service, options?: ValidationOptions): BindingService<Self, Id, Service>;
+};
 declare namespace Hyperdrive_d_exports {
   export { HyperdriveClient, HyperdriveDefinition, HyperdriveService, LayerOptions, Tag, TagClass, isHyperdrive, layer, make, makeClient };
 }
@@ -116,7 +143,7 @@ interface HyperdriveDefinition {
 }
 interface HyperdriveClient {
   readonly connectionString: string;
-  readonly unsafeRaw: Effect.Effect<Hyperdrive>;
+  readonly rawUnsafe: Effect.Effect<Hyperdrive>;
   readonly definition: HyperdriveDefinition;
 }
 declare const HyperdriveServiceTypeId: unique symbol;
@@ -139,4 +166,4 @@ declare const layer: <Self>(tag: Context.Service<Self, HyperdriveClient>, defini
 declare const make: <Id extends string>(id: Id) => TagClass<HyperdriveService<Id>, Id>;
 declare const Tag: <Self>() => <Id extends string>(id: Id) => TagClass<Self, Id>;
 //#endregion
-export { BindingService as a, WorkerConfig as c, BindingNotFoundError as i, WorkerEnv as l, LayerOptions as n, BindingValidationError as o, TagClass as r, Binding_d_exports as s, Hyperdrive_d_exports as t, WorkerEnvironment as u };
+export { BindingService as a, Environment_d_exports as c, WorkerEnvironment as d, BindingNotFoundError as i, WorkerConfig as l, LayerOptions as n, BindingValidationError as o, TagClass as r, Binding_d_exports as s, Hyperdrive_d_exports as t, WorkerEnv as u };

package/dist/HyperdrivePg.d.mts

@@ -1,10 +1,18 @@
-import { i as BindingNotFoundError, n as LayerOptions, o as BindingValidationError, r as TagClass, u as WorkerEnvironment } from "./Hyperdrive-RTjgirMV.mjs";
+import { d as WorkerEnvironment, i as BindingNotFoundError, n as LayerOptions, o as BindingValidationError, r as TagClass } from "./Hyperdrive-COyg7R26.mjs";
 import { Layer } from "effect";
 import { PgClient } from "@effect/sql-pg";
+import { SqlClient, SqlError } from "effect/unstable/sql";
 //#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 | import("effect/unstable/sql/SqlClient").SqlClient, BindingNotFoundError | BindingValidationError | import("effect/unstable/sql/SqlError").SqlError, WorkerEnvironment | Exclude<Exclude<Self, import("effect/Scope").Scope>, Self>>;
+/** Hyperdrive owns database pooling, so app-side pool and connection options are not exposed. */
+type PgLayerOptions = Omit<Parameters<typeof PgClient.makeClient>[0], "url" | "host" | "port" | "path" | "ssl" | "database" | "username" | "password" | "stream">;
+/**
+ * Provides `PgClient` and `SqlClient` backed by a Hyperdrive binding.
+ *
+ * Note: since Effect `4.0.0-beta.99`, `PgClient.makeClient` connects eagerly,
+ * so the TCP connection to Hyperdrive is opened when this layer is built.
+ * In per-request Workers runtimes, build the layer within the request
+ * lifecycle rather than sharing it across requests.
+ */
+declare const layer: <Self, Id extends string>(tag: TagClass<Self, Id>, binding: LayerOptions, options?: PgLayerOptions) => Layer.Layer<PgClient.PgClient | SqlClient.SqlClient, BindingNotFoundError | BindingValidationError | SqlError.SqlError, WorkerEnvironment>;
 //#endregion
 export { PgLayerOptions, layer };

package/dist/HyperdrivePg.mjs

@@ -1,12 +1,17 @@
 import { Effect, Layer, Redacted } from "effect";
 import { PgClient } from "@effect/sql-pg";
 //#region src/HyperdrivePg.ts
-const layer = (tag, binding, options) => Layer.unwrap(Effect.gen(function* () {
-	const hyperdrive = yield* tag;
-	return PgClient.layerFrom(PgClient.makeClient({
-		...options,
-		url: Redacted.make(hyperdrive.connectionString)
-	}));
-})).pipe(Layer.provide(tag.layer(binding)));
+/**
+* Provides `PgClient` and `SqlClient` backed by a Hyperdrive binding.
+*
+* Note: since Effect `4.0.0-beta.99`, `PgClient.makeClient` connects eagerly,
+* so the TCP connection to Hyperdrive is opened when this layer is built.
+* In per-request Workers runtimes, build the layer within the request
+* lifecycle rather than sharing it across requests.
+*/
+const layer = (tag, binding, options) => PgClient.layerFrom(Effect.flatMap(tag, (hyperdrive) => PgClient.makeClient({
+	...options,
+	url: Redacted.make(hyperdrive.connectionString)
+}))).pipe(Layer.provide(tag.layer(binding)));
 //#endregion
 export { layer };