effect-cf 0.20.1 → 0.23.0

package/src/Email.ts

@@ -9,6 +9,7 @@ import { Context, Data, Effect, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedSendEmailBinding = "Send Email binding with send()";
 const textEncoder = new TextEncoder();
@@ -27,7 +28,14 @@ export const sendLimits = {
   maxAllowlistHeaders: 20,
 } as const;
 
-/** Error codes reported by Cloudflare Email Sending. */
+/**
+ * Error codes reported by Cloudflare Email Sending.
+ *
+ * Surfaced on {@link EmailOperationError} `code` on a best-effort basis: the
+ * runtime attaches them as a non-standard `code` property on thrown errors,
+ * which may be missing depending on the runtime or dev-time proxying
+ * (miniflare remote bindings serialize errors and can strip it).
+ */
 export const emailErrorCodes = [
   "E_VALIDATION_ERROR",
   "E_FIELD_MISSING",
@@ -59,9 +67,21 @@ export class EmailOperationError extends Data.TaggedError("EmailOperationError")
   readonly binding: string;
   readonly operation: string;
   readonly cause: unknown;
-  /** Cloudflare error code taken from the thrown error, when present. */
+  /**
+   * Cloudflare error code taken from the thrown error, when present.
+   *
+   * Best-effort: may be `undefined` depending on the runtime or dev-time
+   * proxying — miniflare remote bindings (`"remote": true`) serialize thrown
+   * errors and can strip the non-standard `code` property.
+   */
   readonly code?: EmailErrorCode | (string & {});
-}> {}
+}> {
+  override get message(): string {
+    const code = this.code === undefined ? "" : ` (${this.code})`;
+
+    return `Email ${this.operation} failed for binding "${this.binding}"${code}: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** A single message field that violates a documented Email Sending limit. */
 export interface EmailViolation {
@@ -76,7 +96,11 @@ export class EmailValidationError extends Data.TaggedError("EmailValidationError
   readonly binding: string;
   readonly operation: string;
   readonly violations: ReadonlyArray<EmailViolation>;
-}> {}
+}> {
+  override get message(): string {
+    return `Email ${this.operation} for binding "${this.binding}" failed validation: ${ErrorMessage.violationsMessage(this.violations)}`;
+  }
+}
 
 /** Typed Cloudflare Send Email binding definition. */
 export interface EmailDefinition {
@@ -108,7 +132,7 @@ export interface EmailClient {
     (message: EmailMessage): Effect.Effect<EmailSendResult, EmailSendError>;
     (builder: EmailMessageBuilder): Effect.Effect<EmailSendResult, EmailSendError>;
   };
-  readonly unsafeRaw: Effect.Effect<EmailBinding>;
+  readonly rawUnsafe: Effect.Effect<EmailBinding>;
   readonly definition: EmailDefinition;
 }
 
@@ -141,6 +165,12 @@ export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
   >;
 }
 
+/**
+ * Best-effort extraction of the Cloudflare error `code` from a thrown error.
+ * Returns `undefined` when the property is absent — e.g. when a dev-time
+ * proxy such as a miniflare remote binding (`"remote": true`) serializes the
+ * error and strips non-standard properties.
+ */
 const emailErrorCode = (cause: unknown): EmailOperationError["code"] => {
   if (typeof cause !== "object" || cause === null) {
     return undefined;
@@ -439,21 +469,18 @@ export const makeClient =
   (email: EmailBinding): EmailClient => {
     const runtime = email as EmailRuntimeBinding;
     const validate = options?.validate ?? true;
-    const send = ((message: EmailSendInput) => {
-      const dispatch = () =>
-        tryEmailPromise(definition.binding, "send", () => runtime.send(message));
-
-      if (!validate || !isEmailMessageBuilder(message)) {
-        return dispatch();
+    const send = Effect.fn("Email.send")(function* (message: EmailSendInput) {
+      if (validate && isEmailMessageBuilder(message)) {
+        yield* validateSendInput(definition.binding, "send", message);
       }
 
-      return validateSendInput(definition.binding, "send", message).pipe(Effect.flatMap(dispatch));
+      return yield* tryEmailPromise(definition.binding, "send", () => runtime.send(message));
     }) as EmailClient["send"];
 
     return {
       definition,
       send,
-      unsafeRaw: Effect.succeed(email),
+      rawUnsafe: Effect.succeed(email),
     };
   };
 

package/src/Environment.ts

@@ -1,4 +1,4 @@
-import { Config, ConfigProvider, Context, Effect } from "effect";
+import { Config, ConfigProvider, Context, Effect, type Layer } from "effect";
 
 /** Cloudflare worker environment object (`env`). */
 export type WorkerEnv = Cloudflare.Env;
@@ -72,8 +72,25 @@ export namespace WorkerConfig {
   /** Read a scalar Cloudflare var or secret as a boolean. */
   export const boolean = <const Name extends Key>(name: Name) => Config.boolean(name);
 
-  /** Build a `ConfigProvider` from a Cloudflare worker `env` object. */
-  export const providerFromEnv = (env: WorkerEnv) => ConfigProvider.fromUnknown(env);
+  /** Options for building a `ConfigProvider` from a Cloudflare worker `env` object. */
+  export 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.
+   */
+  export const providerFromEnv = (env: WorkerEnv, options?: ProviderOptions) =>
+    ConfigProvider.fromUnknown(env, options);
 
   /**
    * Build a `ConfigProvider` from the current `WorkerEnvironment` with a custom
@@ -89,12 +106,15 @@ export namespace WorkerConfig {
    * Replace the active Effect `ConfigProvider` with one backed by the current
    * Cloudflare worker `env` object.
    */
-  export const providerLayer = ConfigProvider.layer(provider);
+  export const providerLayer: Layer.Layer<never, never, WorkerEnvironment> =
+    ConfigProvider.layer(provider);
 
   /** Alias for `providerLayer` for concise use in worker layers. */
-  export const layer = providerLayer;
+  export const layer: Layer.Layer<never, never, WorkerEnvironment> = providerLayer;
 
   /** Build a `ConfigProvider` layer with a custom `env` conversion function. */
-  export const layerWith = (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) =>
+  export const layerWith = (
+    makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider,
+  ): Layer.Layer<never, never, WorkerEnvironment> =>
     ConfigProvider.layer(providerWith(makeProvider));
 }

package/src/Hyperdrive.ts

@@ -13,7 +13,7 @@ export interface HyperdriveDefinition {
 
 export interface HyperdriveClient {
   readonly connectionString: string;
-  readonly unsafeRaw: Effect.Effect<Hyperdrive>;
+  readonly rawUnsafe: Effect.Effect<Hyperdrive>;
   readonly definition: HyperdriveDefinition;
 }
 
@@ -60,7 +60,7 @@ export const makeClient =
   (hyperdrive: Hyperdrive): HyperdriveClient => ({
     definition,
     connectionString: hyperdrive.connectionString,
-    unsafeRaw: Effect.succeed(hyperdrive),
+    rawUnsafe: Effect.succeed(hyperdrive),
   });
 
 export const layer = <Self>(

package/src/HyperdrivePg.ts

@@ -1,27 +1,39 @@
 import { PgClient } from "@effect/sql-pg";
 import { Effect, Layer, Redacted } from "effect";
+import type { SqlClient, SqlError } from "effect/unstable/sql";
 
+import type * as Binding from "./Binding";
+import type { WorkerEnvironment } from "./Environment";
 import type * as Hyperdrive from "./Hyperdrive";
 
+/** Hyperdrive owns database pooling, so app-side pool and connection options are not exposed. */
 export type PgLayerOptions = Omit<
-  PgClient.PgClientConfig & { readonly acquireForStream?: boolean },
+  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.
+ */
 export const layer = <Self, Id extends string>(
   tag: Hyperdrive.TagClass<Self, Id>,
   binding: Hyperdrive.LayerOptions,
   options?: PgLayerOptions,
-) =>
-  Layer.unwrap(
-    Effect.gen(function* () {
-      const hyperdrive = yield* tag;
-
-      return PgClient.layerFrom(
-        PgClient.makeClient({
-          ...options,
-          url: Redacted.make(hyperdrive.connectionString),
-        }),
-      );
-    }),
+): Layer.Layer<
+  PgClient.PgClient | SqlClient.SqlClient,
+  Binding.BindingNotFoundError | Binding.BindingValidationError | SqlError.SqlError,
+  WorkerEnvironment
+> =>
+  PgClient.layerFrom(
+    Effect.flatMap(tag, (hyperdrive) =>
+      PgClient.makeClient({
+        ...options,
+        url: Redacted.make(hyperdrive.connectionString),
+      }),
+    ),
   ).pipe(Layer.provide(tag.layer(binding)));

package/src/Images.ts

@@ -16,12 +16,16 @@ import type {
   ImageUploadOptions as CloudflareImageUploadOptions,
   Response as CloudflareResponse,
 } from "@cloudflare/workers-types";
-import { Context, Data, Effect, Option, type Layer } from "effect";
+import { Context, Data, Effect, Function, Option, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
+
+const TypeId = "~effect-cf/Images/Steps" as const;
+
+export type TypeId = typeof TypeId;
 
-const TypeId = "effect-cf/Images/Steps" as const;
 const expectedImagesBinding = "Images binding with info() and input()";
 
 /** Error raised when a Cloudflare Images operation fails. */
@@ -29,7 +33,11 @@ export class ImagesOperationError extends Data.TaggedError("ImagesOperationError
   readonly binding: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Images ${this.operation} failed for binding "${this.binding}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Typed Cloudflare Images binding definition. */
 export interface ImagesDefinition {
@@ -64,6 +72,8 @@ export type Step = Data.TaggedEnum<{
   readonly Draw: DrawStepOptions;
 }>;
 
+export const Step = Data.taggedEnum<Step>();
+
 export interface Steps {
   readonly [TypeId]: typeof TypeId;
   readonly steps: ReadonlyArray<Step>;
@@ -101,7 +111,7 @@ export interface HostedImagesClient {
     options?: ImageUploadOptions,
   ) => Effect.Effect<ImageMetadata, ImagesOperationError>;
   readonly list: (options?: ImageListOptions) => Effect.Effect<ImageList, ImagesOperationError>;
-  readonly unsafeRaw: Effect.Effect<CloudflareHostedImagesBinding>;
+  readonly rawUnsafe: Effect.Effect<CloudflareHostedImagesBinding>;
 }
 
 export interface ImagesRuntimeBinding {
@@ -130,7 +140,7 @@ export interface ImagesClient {
     options: ProcessOptions,
   ) => Effect.Effect<ImagesTransformationResultClient, ImagesOperationError>;
   readonly hosted: Option.Option<HostedImagesClient>;
-  readonly unsafeRaw: Effect.Effect<ImagesRuntimeBinding>;
+  readonly rawUnsafe: Effect.Effect<ImagesRuntimeBinding>;
   readonly definition: ImagesDefinition;
 }
 
@@ -170,47 +180,23 @@ const makeSteps = (steps: ReadonlyArray<Step>): Steps => ({
 /** Empty Images transformation pipeline. */
 export const empty: Steps = makeSteps([]);
 
-export function transform(transform: ImageTransform): (steps: Steps) => Steps;
-export function transform(steps: Steps, transform: ImageTransform): Steps;
-export function transform(
-  stepsOrTransform: Steps | ImageTransform,
-  transformValue?: ImageTransform,
-): Steps | ((steps: Steps) => Steps) {
-  if (transformValue === undefined) {
-    return (steps) => transform(steps, stepsOrTransform as ImageTransform);
-  }
-
-  const steps = stepsOrTransform as Steps;
-
-  return makeSteps([
-    ...steps.steps,
-    {
-      _tag: "Transform",
-      transform: transformValue,
-    },
-  ]);
-}
-
-export function draw(draw: DrawStepOptions): (steps: Steps) => Steps;
-export function draw(steps: Steps, draw: DrawStepOptions): Steps;
-export function draw(
-  stepsOrDraw: Steps | DrawStepOptions,
-  drawValue?: DrawStepOptions,
-): Steps | ((steps: Steps) => Steps) {
-  if (drawValue === undefined) {
-    return (steps) => draw(steps, stepsOrDraw as DrawStepOptions);
-  }
-
-  const steps = stepsOrDraw as Steps;
-
-  return makeSteps([
-    ...steps.steps,
-    {
-      _tag: "Draw",
-      ...drawValue,
-    },
-  ]);
-}
+export const transform: {
+  (transform: ImageTransform): (steps: Steps) => Steps;
+  (steps: Steps, transform: ImageTransform): Steps;
+} = Function.dual(
+  2,
+  (steps: Steps, transformValue: ImageTransform): Steps =>
+    makeSteps([...steps.steps, Step.Transform({ transform: transformValue })]),
+);
+
+export const draw: {
+  (draw: DrawStepOptions): (steps: Steps) => Steps;
+  (steps: Steps, draw: DrawStepOptions): Steps;
+} = Function.dual(
+  2,
+  (steps: Steps, drawValue: DrawStepOptions): Steps =>
+    makeSteps([...steps.steps, Step.Draw(drawValue)]),
+);
 
 const imagesError = (binding: string, operation: string, cause: unknown) =>
   new ImagesOperationError({ binding, operation, cause });
@@ -266,10 +252,20 @@ const wrapResult = (
 
 const wrapHandle = (binding: string, handle: CloudflareImageHandle): ImageHandleClient => ({
   raw: handle,
-  details: tryImagesPromise(binding, "details", () => handle.details()).pipe(Effect.map(maybe)),
-  bytes: tryImagesPromise(binding, "bytes", () => handle.bytes()).pipe(Effect.map(maybe)),
-  update: (options) => tryImagesPromise(binding, "update", () => handle.update(options)),
-  delete: tryImagesPromise(binding, "delete", () => handle.delete()),
+  details: tryImagesPromise(binding, "details", () => handle.details()).pipe(
+    Effect.map(maybe),
+    Effect.withSpan("Images.details"),
+  ),
+  bytes: tryImagesPromise(binding, "bytes", () => handle.bytes()).pipe(
+    Effect.map(maybe),
+    Effect.withSpan("Images.bytes"),
+  ),
+  update: Effect.fn("Images.update")((options: ImageUpdateOptions) =>
+    tryImagesPromise(binding, "update", () => handle.update(options)),
+  ),
+  delete: tryImagesPromise(binding, "delete", () => handle.delete()).pipe(
+    Effect.withSpan("Images.delete"),
+  ),
 });
 
 const wrapHosted = (
@@ -277,10 +273,13 @@ const wrapHosted = (
   hosted: CloudflareHostedImagesBinding,
 ): HostedImagesClient => ({
   image: (imageId) => wrapHandle(binding, hosted.image(imageId)),
-  upload: (image, options) =>
+  upload: Effect.fn("Images.upload")((image: ImageUploadValue, options?: ImageUploadOptions) =>
     tryImagesPromise(binding, "upload", () => hosted.upload(image, options)),
-  list: (options) => tryImagesPromise(binding, "list", () => hosted.list(options)),
-  unsafeRaw: Effect.succeed(hosted),
+  ),
+  list: Effect.fn("Images.list")((options?: ImageListOptions) =>
+    tryImagesPromise(binding, "list", () => hosted.list(options)),
+  ),
+  rawUnsafe: Effect.succeed(hosted),
 });
 
 export const makeClient =
@@ -289,44 +288,40 @@ export const makeClient =
     const input = (image: ImageInputValue, options?: ImageInputOptions) =>
       tryImagesSync(definition.binding, "input", () => images.input(image, options));
 
-    const process = (steps: Steps, options: ProcessOptions) =>
-      Effect.gen(function* () {
-        let transformer = yield* input(options.stream, options.inputOptions);
-
-        for (const step of steps.steps) {
-          switch (step._tag) {
-            case "Draw": {
-              transformer = yield* tryImagesSync(definition.binding, "draw", () =>
-                transformer.draw(step.image, step.options),
-              );
-              break;
-            }
-            case "Transform": {
-              transformer = yield* tryImagesSync(definition.binding, "transform", () =>
-                transformer.transform(step.transform),
-              );
-              break;
-            }
-          }
-        }
-
-        const result = yield* tryImagesPromise(definition.binding, "output", () =>
-          transformer.output(options.outputOptions),
-        );
-
-        return wrapResult(definition.binding, result);
-      });
+    const process = Effect.fn("Images.process")(function* (steps: Steps, options: ProcessOptions) {
+      let transformer = yield* input(options.stream, options.inputOptions);
+
+      for (const step of steps.steps) {
+        transformer = yield* Step.$match(step, {
+          Draw: (drawStep) =>
+            tryImagesSync(definition.binding, "draw", () =>
+              transformer.draw(drawStep.image, drawStep.options),
+            ),
+          Transform: (transformStep) =>
+            tryImagesSync(definition.binding, "transform", () =>
+              transformer.transform(transformStep.transform),
+            ),
+        });
+      }
+
+      const result = yield* tryImagesPromise(definition.binding, "output", () =>
+        transformer.output(options.outputOptions),
+      );
+
+      return wrapResult(definition.binding, result);
+    });
 
     return {
       definition,
-      info: (image, options) =>
+      info: Effect.fn("Images.info")((image: ImageInputValue, options?: ImageInputOptions) =>
         tryImagesPromise(definition.binding, "info", () => images.info(image, options)),
+      ),
       input,
       process,
       hosted: isHostedImagesBinding(images.hosted)
         ? Option.some(wrapHosted(definition.binding, images.hosted))
         : Option.none(),
-      unsafeRaw: Effect.succeed(images),
+      rawUnsafe: Effect.succeed(images),
     };
   };
 

package/src/Kv.ts

@@ -6,16 +6,24 @@ import { Context, Data, Effect, Option, Schema as S, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedKvNamespace =
   "KV namespace binding with get(), put(), delete(), getWithMetadata(), and list()";
 
+/** KV operation represented by {@link KvOperationError}. */
+export type KvOperation = "put" | "get" | "getWithMetadata" | "list" | "delete";
+
 /** Error raised when a KV operation fails. */
 export class KvOperationError extends Data.TaggedError("KvOperationError")<{
   readonly binding: string;
-  readonly operation: string;
+  readonly operation: KvOperation;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Kv ${this.operation} failed for binding "${this.binding}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** `KVNamespace.put` options. */
 export type KvPutOptions = CloudflareKVNamespacePutOptions;
@@ -95,8 +103,8 @@ export interface KvClient<Key, Value, EncodedValue> {
   readonly list: <Metadata = unknown>(
     options?: KvListOptions<Metadata>,
   ) => Effect.Effect<KvListResult<Key, Metadata>, KvOperationError | S.SchemaError>;
-  readonly remove: (key: Key) => Effect.Effect<void, KvOperationError | S.SchemaError>;
-  readonly unsafeRaw: Effect.Effect<KVNamespace>;
+  readonly delete: (key: Key) => Effect.Effect<void, KvOperationError | S.SchemaError>;
+  readonly rawUnsafe: Effect.Effect<KVNamespace>;
   readonly definition: KvDefinition<Key, Value, EncodedValue>;
 }
 
@@ -123,18 +131,12 @@ export interface TagClass<
   >;
 }
 
-const maybeString = (value: string | null | undefined): Option.Option<string> =>
-  value === null || value === undefined ? Option.none() : Option.some(value);
-
-const maybeNumber = (value: number | undefined): Option.Option<number> =>
-  value === undefined ? Option.none() : Option.some(value);
-
-const kvError = (binding: string, operation: string, cause: unknown) =>
+const kvError = (binding: string, operation: KvOperation, cause: unknown) =>
   new KvOperationError({ binding, operation, cause });
 
 const tryKvPromise = <A>(
   binding: string,
-  operation: string,
+  operation: KvOperation,
   evaluate: () => Promise<A>,
 ): Effect.Effect<A, KvOperationError> =>
   Effect.tryPromise({
@@ -163,12 +165,15 @@ export const makeClient = <Key, Value, EncodedValue>(
 ): ((kv: KVNamespace) => KvClient<Key, Value, EncodedValue>) => {
   const encodeKey = S.encodeEffect(definition.key);
   const decodeKey = S.decodeUnknownEffect(definition.key);
-  const encodeValue = S.encodeEffect(S.fromJsonString(S.toCodecJson(definition.value)));
-  const decodeValue = S.decodeUnknownEffect(S.fromJsonString(S.toCodecJson(definition.value)));
+  const jsonValue = S.fromJsonString(S.toCodecJson(definition.value));
+  const encodeValue = S.encodeEffect(jsonValue);
+  const decodeValue = S.decodeUnknownEffect(jsonValue);
 
   return (kv) => ({
     definition,
-    put: Effect.fnUntraced(function* (key: Key, value: Value, options?: KvPutOptions) {
+    put: Effect.fn("Kv.put", {
+      attributes: { binding: definition.binding, operation: "put" },
+    })(function* (key: Key, value: Value, options?: KvPutOptions) {
       const keyEncoded = yield* encodeKey(key);
       const valueEncoded = yield* encodeValue(value);
 
@@ -176,7 +181,9 @@ export const makeClient = <Key, Value, EncodedValue>(
         kv.put(keyEncoded, valueEncoded, options),
       );
     }),
-    get: Effect.fnUntraced(function* (key: Key) {
+    get: Effect.fn("Kv.get", {
+      attributes: { binding: definition.binding, operation: "get" },
+    })(function* (key: Key) {
       const keyEncoded = yield* encodeKey(key);
       const valueEncoded = yield* tryKvPromise(definition.binding, "get", () => kv.get(keyEncoded));
 
@@ -186,10 +193,9 @@ export const makeClient = <Key, Value, EncodedValue>(
 
       return yield* decodeValue(valueEncoded).pipe(Effect.map(Option.some));
     }),
-    getWithMetadata: Effect.fnUntraced(function* <Metadata>(
-      key: Key,
-      metadataSchema: S.Codec<Metadata, unknown>,
-    ) {
+    getWithMetadata: Effect.fn("Kv.getWithMetadata", {
+      attributes: { binding: definition.binding, operation: "getWithMetadata" },
+    })(function* <Metadata>(key: Key, metadataSchema: S.Codec<Metadata, unknown>) {
       const keyEncoded = yield* encodeKey(key);
       const result = yield* tryKvPromise(definition.binding, "getWithMetadata", () =>
         kv.getWithMetadata<Metadata>(keyEncoded),
@@ -208,10 +214,12 @@ export const makeClient = <Key, Value, EncodedValue>(
       return Option.some({
         value,
         metadata,
-        cacheStatus: maybeString(result.cacheStatus),
+        cacheStatus: Option.fromNullishOr(result.cacheStatus),
       });
     }),
-    list: Effect.fnUntraced(function* <Metadata = unknown>(options?: KvListOptions<Metadata>) {
+    list: Effect.fn("Kv.list", {
+      attributes: { binding: definition.binding, operation: "list" },
+    })(function* <Metadata = unknown>(options?: KvListOptions<Metadata>) {
       const { metadataSchema, ...kvOptions } = options ?? {};
       const result = yield* tryKvPromise(definition.binding, "list", () =>
         kv.list<Metadata>(kvOptions),
@@ -229,7 +237,7 @@ export const makeClient = <Key, Value, EncodedValue>(
 
         keys.push({
           name: decodedName,
-          expiration: maybeNumber(key.expiration),
+          expiration: Option.fromUndefinedOr(key.expiration),
           metadata: decodedMetadata,
         });
       }
@@ -237,16 +245,18 @@ export const makeClient = <Key, Value, EncodedValue>(
       return {
         keys,
         listComplete: result.list_complete,
-        cursor: maybeString("cursor" in result ? result.cursor : undefined),
-        cacheStatus: maybeString(result.cacheStatus),
+        cursor: Option.fromNullishOr("cursor" in result ? result.cursor : undefined),
+        cacheStatus: Option.fromNullishOr(result.cacheStatus),
       };
     }),
-    remove: Effect.fnUntraced(function* (key: Key) {
+    delete: Effect.fn("Kv.delete", {
+      attributes: { binding: definition.binding, operation: "delete" },
+    })(function* (key: Key) {
       const keyEncoded = yield* encodeKey(key);
 
       yield* tryKvPromise(definition.binding, "delete", () => kv.delete(keyEncoded));
     }),
-    unsafeRaw: Effect.succeed(kv),
+    rawUnsafe: Effect.succeed(kv),
   });
 };
 

package/src/Queue.ts

@@ -3,6 +3,7 @@ import { Data, Effect, type Scope } from "effect";
 import type { ExecutionContext, WorkerContext } from "./Worker";
 import type { WorkerEnvironment } from "./Environment";
 import * as QueueDefinition from "./QueueDefinition";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 export interface QueueMessage<Body> {
   readonly raw: globalThis.Message<unknown>;
@@ -28,7 +29,11 @@ export class QueueMessageDecodeError extends Data.TaggedError("QueueMessageDecod
   readonly messageId: string;
   readonly index: number;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Queue "${this.queue}" failed to decode message "${this.messageId}" at index ${this.index}: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 type RuntimeContext<ROut> = ExecutionContext | WorkerContext | WorkerEnvironment | ROut;