effect-cf 0.18.0 → 0.20.0

package/src/DurableObjectWebSocket.ts

@@ -46,6 +46,7 @@ export const fromWebSocket = <Attachment = unknown>(
   raw: WebSocket,
 ): DurableWebSocket<Attachment> => {
   const existing = wrappers.get(raw);
+
   if (existing !== undefined) {
     return existing as DurableWebSocket<Attachment>;
   }
@@ -74,6 +75,7 @@ export const fromWebSocket = <Attachment = unknown>(
   };
 
   wrappers.set(raw, socket);
+
   return socket as DurableWebSocket<Attachment>;
 };
 
@@ -189,7 +191,8 @@ export const attachment = <const AttachmentSchema extends S.Codec<any, any, neve
   const deserialize = (socket: DurableWebSocket<unknown>) =>
     Effect.gen(function* () {
       const value = yield* socket.deserializeAttachment;
-      if (value == null) {
+
+      if (value === null || value === undefined) {
         return Option.none<Attachment>();
       }
 

package/src/Email.ts

@@ -11,12 +11,71 @@ import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
 
 const expectedSendEmailBinding = "Send Email binding with send()";
+const textEncoder = new TextEncoder();
+
+/** Documented Cloudflare Email Sending limits. */
+export const sendLimits = {
+  /** Combined `to`, `cc`, and `bcc` addresses per message. */
+  maxRecipients: 50,
+  maxAttachments: 32,
+  /** Total message size, including attachments. Not enforced client side. */
+  maxMessageBytes: 5 * 1024 * 1024,
+  maxHeaderNameBytes: 100,
+  maxHeaderValueBytes: 2048,
+  maxHeadersBytes: 16 * 1024,
+  /** Allowlisted custom headers, excluding `X-` prefixed headers. */
+  maxAllowlistHeaders: 20,
+} as const;
+
+/** Error codes reported by Cloudflare Email Sending. */
+export const emailErrorCodes = [
+  "E_VALIDATION_ERROR",
+  "E_FIELD_MISSING",
+  "E_TOO_MANY_RECIPIENTS",
+  "E_TOO_MANY_ATTACHMENTS",
+  "E_SENDER_NOT_VERIFIED",
+  "E_RECIPIENT_NOT_ALLOWED",
+  "E_RECIPIENT_SUPPRESSED",
+  "E_SENDER_DOMAIN_NOT_AVAILABLE",
+  "E_CONTENT_TOO_LARGE",
+  "E_DELIVERY_FAILED",
+  "E_RATE_LIMIT_EXCEEDED",
+  "E_DAILY_LIMIT_EXCEEDED",
+  "E_INTERNAL_SERVER_ERROR",
+  "E_HEADER_NOT_ALLOWED",
+  "E_HEADER_USE_API_FIELD",
+  "E_HEADER_VALUE_INVALID",
+  "E_HEADER_VALUE_TOO_LONG",
+  "E_HEADER_NAME_INVALID",
+  "E_HEADERS_TOO_LARGE",
+  "E_HEADERS_TOO_MANY",
+] as const;
+
+/** A documented Cloudflare Email Sending error code. */
+export type EmailErrorCode = (typeof emailErrorCodes)[number];
 
 /** Error raised when a Cloudflare Send Email operation fails. */
 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. */
+  readonly code?: EmailErrorCode | (string & {});
+}> {}
+
+/** A single message field that violates a documented Email Sending limit. */
+export interface EmailViolation {
+  readonly path: string;
+  readonly message: string;
+  readonly limit?: number;
+  readonly actual?: number;
+}
+
+/** Error raised when a message violates documented Cloudflare Email Sending limits. */
+export class EmailValidationError extends Data.TaggedError("EmailValidationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly violations: ReadonlyArray<EmailViolation>;
 }> {}
 
 /** Typed Cloudflare Send Email binding definition. */
@@ -32,6 +91,13 @@ export type EmailMessageBuilder = Parameters<CloudflareSendEmail["send"]>[0];
 export type EmailSendInput = EmailMessage | EmailMessageBuilder;
 export type EmailSendResult = CloudflareEmailSendResult;
 export type EmailBinding = CloudflareSendEmail;
+export type EmailRecipients = string | EmailAddress | ReadonlyArray<string | EmailAddress>;
+export type EmailSendError = EmailOperationError | EmailValidationError;
+
+export interface EmailSendOptions {
+  /** Validates builder messages against documented limits. Defaults to `true`. */
+  readonly validate?: boolean;
+}
 
 interface EmailRuntimeBinding {
   readonly send: (message: EmailSendInput) => Promise<EmailSendResult>;
@@ -39,8 +105,8 @@ interface EmailRuntimeBinding {
 
 export interface EmailClient {
   readonly send: {
-    (message: EmailMessage): Effect.Effect<EmailSendResult, EmailOperationError>;
-    (builder: EmailMessageBuilder): Effect.Effect<EmailSendResult, EmailOperationError>;
+    (message: EmailMessage): Effect.Effect<EmailSendResult, EmailSendError>;
+    (builder: EmailMessageBuilder): Effect.Effect<EmailSendResult, EmailSendError>;
   };
   readonly unsafeRaw: Effect.Effect<EmailBinding>;
   readonly definition: EmailDefinition;
@@ -57,6 +123,7 @@ export interface EmailService<Id extends string> {
 
 export type LayerOptions = {
   readonly binding: string;
+  readonly send?: EmailSendOptions;
 };
 
 export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
@@ -74,8 +141,24 @@ export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
   >;
 }
 
+const emailErrorCode = (cause: unknown): EmailOperationError["code"] => {
+  if (typeof cause !== "object" || cause === null) {
+    return undefined;
+  }
+
+  const code = Reflect.get(cause, "code");
+
+  return typeof code === "string" ? code : undefined;
+};
+
 const emailError = (binding: string, operation: string, cause: unknown) =>
-  new EmailOperationError({ binding, operation, cause });
+  new EmailOperationError({ binding, operation, cause, code: emailErrorCode(cause) });
+
+const emailValidationError = (
+  binding: string,
+  operation: string,
+  violations: ReadonlyArray<EmailViolation>,
+) => new EmailValidationError({ binding, operation, violations });
 
 const tryEmailPromise = <A>(
   binding: string,
@@ -87,6 +170,260 @@ const tryEmailPromise = <A>(
     catch: (cause) => emailError(binding, operation, cause),
   });
 
+const builderFields = [
+  "subject",
+  "html",
+  "text",
+  "cc",
+  "bcc",
+  "replyTo",
+  "attachments",
+  "headers",
+] as const;
+
+/**
+ * Distinguishes structured Email Sending messages from raw MIME `EmailMessage`
+ * values, which only carry envelope `from` and `to` addresses.
+ */
+export const isEmailMessageBuilder = (message: EmailSendInput): message is EmailMessageBuilder => {
+  if (typeof message !== "object" || message === null) {
+    return false;
+  }
+
+  return builderFields.some((field) => Reflect.get(message, field) !== undefined);
+};
+
+const byteLength = (value: string) => textEncoder.encode(value).byteLength;
+
+const limitViolation = (
+  path: string,
+  label: string,
+  actual: number,
+  limit: number,
+): EmailViolation => ({
+  path,
+  message: `${label} exceeds Cloudflare Email Sending limit`,
+  actual,
+  limit,
+});
+
+const addressList = (value: EmailRecipients | undefined): ReadonlyArray<string | EmailAddress> => {
+  if (value === undefined) {
+    return [];
+  }
+
+  return Array.isArray(value) ? value : [value as string | EmailAddress];
+};
+
+const addressViolations = (path: string, value: unknown): ReadonlyArray<EmailViolation> => {
+  if (typeof value === "string") {
+    return value.includes("@") ? [] : [{ path, message: "Email address must contain an @ symbol" }];
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return [{ path, message: "Email address must be a string or { name, email } object" }];
+  }
+
+  const email = Reflect.get(value, "email");
+
+  if (typeof email !== "string" || !email.includes("@")) {
+    return [{ path: `${path}.email`, message: "Email address must contain an @ symbol" }];
+  }
+
+  return [];
+};
+
+const recipientViolations = (
+  field: "to" | "cc" | "bcc",
+  value: EmailRecipients | undefined,
+): ReadonlyArray<EmailViolation> =>
+  addressList(value).flatMap((address, index) => addressViolations(`${field}[${index}]`, address));
+
+const attachmentViolations = (
+  attachments: ReadonlyArray<EmailAttachment>,
+): ReadonlyArray<EmailViolation> => {
+  const violations: Array<EmailViolation> = [];
+
+  if (attachments.length > sendLimits.maxAttachments) {
+    violations.push(
+      limitViolation("attachments", "attachments", attachments.length, sendLimits.maxAttachments),
+    );
+  }
+
+  for (let index = 0; index < attachments.length; index++) {
+    const attachment = attachments[index];
+    const path = `attachments[${index}]`;
+
+    if (typeof attachment !== "object" || attachment === null) {
+      violations.push({ path, message: "Attachment must be an object" });
+      continue;
+    }
+
+    if (typeof attachment.filename !== "string" || attachment.filename === "") {
+      violations.push({ path: `${path}.filename`, message: "Attachment filename is required" });
+    }
+
+    if (typeof attachment.type !== "string" || attachment.type === "") {
+      violations.push({ path: `${path}.type`, message: "Attachment MIME type is required" });
+    }
+
+    if (attachment.content === undefined || attachment.content === null) {
+      violations.push({ path: `${path}.content`, message: "Attachment content is required" });
+    }
+
+    if (attachment.disposition === "inline" && typeof attachment.contentId !== "string") {
+      violations.push({
+        path: `${path}.contentId`,
+        message: "Inline attachments require a contentId",
+      });
+    }
+  }
+
+  return violations;
+};
+
+const headerViolations = (headers: Record<string, string>): ReadonlyArray<EmailViolation> => {
+  const violations: Array<EmailViolation> = [];
+  const entries = Object.entries(headers);
+  let totalBytes = 0;
+  let allowlistHeaders = 0;
+
+  for (const [name, value] of entries) {
+    const path = `headers["${name}"]`;
+    const nameBytes = byteLength(name);
+
+    if (nameBytes > sendLimits.maxHeaderNameBytes) {
+      violations.push(
+        limitViolation(path, "header name bytes", nameBytes, sendLimits.maxHeaderNameBytes),
+      );
+    }
+
+    if (typeof value !== "string") {
+      violations.push({ path, message: "Header value must be a string" });
+      continue;
+    }
+
+    const valueBytes = byteLength(value);
+
+    if (valueBytes > sendLimits.maxHeaderValueBytes) {
+      violations.push(
+        limitViolation(path, "header value bytes", valueBytes, sendLimits.maxHeaderValueBytes),
+      );
+    }
+
+    totalBytes += nameBytes + valueBytes;
+
+    if (!name.toLowerCase().startsWith("x-")) {
+      allowlistHeaders += 1;
+    }
+  }
+
+  if (totalBytes > sendLimits.maxHeadersBytes) {
+    violations.push(
+      limitViolation("headers", "header bytes", totalBytes, sendLimits.maxHeadersBytes),
+    );
+  }
+
+  if (allowlistHeaders > sendLimits.maxAllowlistHeaders) {
+    violations.push(
+      limitViolation(
+        "headers",
+        "allowlisted custom headers",
+        allowlistHeaders,
+        sendLimits.maxAllowlistHeaders,
+      ),
+    );
+  }
+
+  return violations;
+};
+
+/**
+ * Validates a structured message against documented Cloudflare Email Sending
+ * limits and returns every violation found. Total message size is not checked
+ * because the encoded MIME size is only known once Cloudflare composes it.
+ */
+export const validateMessage = (message: EmailMessageBuilder): ReadonlyArray<EmailViolation> => {
+  const violations: Array<EmailViolation> = [];
+  const fields = message as {
+    readonly to?: EmailRecipients;
+    readonly cc?: EmailRecipients;
+    readonly bcc?: EmailRecipients;
+    readonly from?: unknown;
+    readonly replyTo?: unknown;
+    readonly subject?: unknown;
+    readonly text?: unknown;
+    readonly html?: unknown;
+    readonly attachments?: ReadonlyArray<EmailAttachment>;
+    readonly headers?: Record<string, string>;
+  };
+
+  if (fields.from === undefined) {
+    violations.push({ path: "from", message: "A from address is required" });
+  } else {
+    violations.push(...addressViolations("from", fields.from));
+  }
+
+  if (fields.replyTo !== undefined) {
+    violations.push(...addressViolations("replyTo", fields.replyTo));
+  }
+
+  if (typeof fields.subject !== "string" || fields.subject === "") {
+    violations.push({ path: "subject", message: "A subject is required" });
+  }
+
+  if (typeof fields.text !== "string" && typeof fields.html !== "string") {
+    violations.push({ path: "$", message: "A message requires either text or html content" });
+  }
+
+  const recipients =
+    addressList(fields.to).length + addressList(fields.cc).length + addressList(fields.bcc).length;
+
+  if (recipients === 0) {
+    violations.push({
+      path: "$",
+      message: "A message requires at least one to, cc, or bcc address",
+    });
+  }
+
+  if (recipients > sendLimits.maxRecipients) {
+    violations.push(
+      limitViolation(
+        "$",
+        "combined to, cc, and bcc addresses",
+        recipients,
+        sendLimits.maxRecipients,
+      ),
+    );
+  }
+
+  violations.push(...recipientViolations("to", fields.to));
+  violations.push(...recipientViolations("cc", fields.cc));
+  violations.push(...recipientViolations("bcc", fields.bcc));
+
+  if (fields.attachments !== undefined) {
+    violations.push(...attachmentViolations(fields.attachments));
+  }
+
+  if (fields.headers !== undefined) {
+    violations.push(...headerViolations(fields.headers));
+  }
+
+  return violations;
+};
+
+const validateSendInput = (
+  binding: string,
+  operation: string,
+  message: EmailMessageBuilder,
+): Effect.Effect<EmailMessageBuilder, EmailValidationError> => {
+  const violations = validateMessage(message);
+
+  return violations.length > 0
+    ? Effect.fail(emailValidationError(binding, operation, violations))
+    : Effect.succeed(message);
+};
+
 export const isEmailBinding = (value: unknown): value is EmailBinding => {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -98,13 +435,20 @@ export const isEmailBinding = (value: unknown): value is EmailBinding => {
 };
 
 export const makeClient =
-  (definition: EmailDefinition) =>
+  (definition: EmailDefinition, options?: EmailSendOptions) =>
   (email: EmailBinding): EmailClient => {
     const runtime = email as EmailRuntimeBinding;
-    const send = ((message: EmailSendInput) =>
-      tryEmailPromise(definition.binding, "send", () =>
-        runtime.send(message),
-      )) as EmailClient["send"];
+    const validate = options?.validate ?? true;
+    const send = ((message: EmailSendInput) => {
+      const dispatch = () =>
+        tryEmailPromise(definition.binding, "send", () => runtime.send(message));
+
+      if (!validate || !isEmailMessageBuilder(message)) {
+        return dispatch();
+      }
+
+      return validateSendInput(definition.binding, "send", message).pipe(Effect.flatMap(dispatch));
+    }) as EmailClient["send"];
 
     return {
       definition,
@@ -113,8 +457,8 @@ export const makeClient =
     };
   };
 
-export const layer = <Self>(tag: Context.Service<Self, EmailClient>, definition: EmailDefinition) =>
-  Binding.layer(tag, definition.binding, isEmailBinding, makeClient(definition), {
+export const layer = <Self>(tag: Context.Service<Self, EmailClient>, definition: LayerOptions) =>
+  Binding.layer(tag, definition.binding, isEmailBinding, makeClient(definition, definition.send), {
     expected: expectedSendEmailBinding,
   });
 

package/src/HyperdrivePg.ts

@@ -1,7 +1,7 @@
 import { PgClient } from "@effect/sql-pg";
 import { Effect, Layer, Redacted } from "effect";
 
-import * as Hyperdrive from "./Hyperdrive";
+import type * as Hyperdrive from "./Hyperdrive";
 
 export type PgLayerOptions = Omit<
   PgClient.PgClientConfig & { readonly acquireForStream?: boolean },

package/src/Kv.ts

@@ -124,7 +124,7 @@ export interface TagClass<
 }
 
 const maybeString = (value: string | null | undefined): Option.Option<string> =>
-  value == null ? Option.none() : Option.some(value);
+  value === null || value === undefined ? Option.none() : Option.some(value);
 
 const maybeNumber = (value: number | undefined): Option.Option<number> =>
   value === undefined ? Option.none() : Option.some(value);
@@ -171,6 +171,7 @@ export const makeClient = <Key, Value, EncodedValue>(
     put: Effect.fnUntraced(function* (key: Key, value: Value, options?: KvPutOptions) {
       const keyEncoded = yield* encodeKey(key);
       const valueEncoded = yield* encodeValue(value);
+
       yield* tryKvPromise(definition.binding, "put", () =>
         kv.put(keyEncoded, valueEncoded, options),
       );
@@ -242,6 +243,7 @@ export const makeClient = <Key, Value, EncodedValue>(
     }),
     remove: Effect.fnUntraced(function* (key: Key) {
       const keyEncoded = yield* encodeKey(key);
+
       yield* tryKvPromise(definition.binding, "delete", () => kv.delete(keyEncoded));
     }),
     unsafeRaw: Effect.succeed(kv),

package/src/QueueBinding.ts

@@ -7,7 +7,7 @@ import type {
   QueueSendOptions as CloudflareQueueSendOptions,
   QueueSendResponse as CloudflareQueueSendResponse,
 } from "@cloudflare/workers-types";
-import { Context, Data, Effect, Schema as S } from "effect";
+import { type Context, Data, Effect, Schema as S } from "effect";
 
 import * as Binding from "./Binding";
 import type * as RpcDefinition from "./RpcDefinition";
@@ -110,6 +110,7 @@ export const makeClient = <Message extends RpcDefinition.ServiceFreeSchema>(
         yield* tryQueuePromise(definition.binding, "sendBatch", () =>
           sendBatch.call(queue, encodedMessages, options),
         );
+
         return;
       }
 

package/src/QueueDefinition.ts

@@ -1,6 +1,6 @@
 import { Context, Effect, Schema as S, type Layer, type Scope } from "effect";
 
-import * as Binding from "./Binding";
+import type * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
 import * as QueueEntrypoint from "./Queue";
 import * as QueueBinding from "./QueueBinding";
@@ -121,6 +121,7 @@ export const Tag =
       options?: QueueBinding.QueueSendOptions,
     ) {
       const queue = yield* tag;
+
       yield* queue.send(message, options);
     });
 
@@ -129,16 +130,19 @@ export const Tag =
       options?: QueueBinding.QueueSendBatchOptions,
     ) {
       const queue = yield* tag;
+
       yield* queue.sendBatch(messages, options);
     });
 
     const metrics = Effect.fnUntraced(function* () {
       const queue = yield* tag;
+
       return yield* queue.metrics();
     });
 
     const unsafeRaw = Effect.fnUntraced(function* () {
       const queue = yield* tag;
+
       return yield* queue.unsafeRaw;
     });
 
@@ -165,6 +169,7 @@ const wrapHandler = <ROut, const Self extends Definition.Any>(
   return (batch) =>
     Effect.gen(function* () {
       const decoded = yield* QueueEntrypoint.decodeBatch(batch.raw, decodeBody);
+
       yield* handler(decoded);
     });
 };

package/src/R2.ts

@@ -280,6 +280,7 @@ export const makeClient = (
         ),
       delete: (keys) => {
         const nativeKeys = typeof keys === "string" ? keys : [...keys];
+
         return tryR2Promise(definition.binding, "delete", () => bucket.delete(nativeKeys));
       },
       list: (options) => tryR2Promise(definition.binding, "list", () => bucket.list(options)),

package/src/RpcDefinition.ts

@@ -218,6 +218,7 @@ export const decodeArgs = <
 
     for (let index = 0; index < methodDefinition.args.length; index++) {
       const schema = methodDefinition.args[index];
+
       decoded.push(
         yield* (S.decodeUnknownEffect(schema)(args[index]) as Effect.Effect<unknown, unknown>).pipe(
           Effect.mapError(
@@ -265,6 +266,7 @@ export const encodeArgs = <
 
     for (let index = 0; index < methodDefinition.args.length; index++) {
       const schema = methodDefinition.args[index];
+
       encoded.push(
         yield* (S.encodeEffect(schema)(args[index]) as Effect.Effect<unknown, unknown>).pipe(
           Effect.mapError(

package/src/ServiceBinding.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Effect, type Scope } from "effect";
+import { Data, Effect, type Context, type Scope } from "effect";
 
 import * as Binding from "./Binding";
 import * as CloudflareRpc from "./Rpc";
@@ -333,6 +333,7 @@ export const makeClient = <
         const methodName = String(method);
         const result = yield* rpc(method, ...args);
         const value = yield* CloudflareRpc.scoped(result);
+
         return yield* decodeSuccess<Method>(methodName, value);
       });
 
@@ -413,6 +414,7 @@ export const Service =
     const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
       Effect.gen(function* () {
         const service = yield* tag;
+
         return yield* service.fetch(input, init);
       });
 
@@ -422,6 +424,7 @@ export const Service =
     ) =>
       Effect.gen(function* () {
         const service = yield* tag;
+
         return yield* service.rpc(method, ...args);
       });
 
@@ -431,6 +434,7 @@ export const Service =
     ) =>
       Effect.gen(function* () {
         const service = yield* tag;
+
         return yield* service.call(method, ...args);
       });
 
@@ -440,6 +444,7 @@ export const Service =
     ) =>
       Effect.gen(function* () {
         const service = yield* tag;
+
         return yield* service.scopedCall(method, ...args);
       });
 

package/src/Worker.ts

@@ -1,6 +1,14 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
-import { Cause, ConfigProvider, Context, Effect, Layer, ManagedRuntime, type Scope } from "effect";
-import type { Schema as S } from "effect";
+import {
+  type Cause,
+  ConfigProvider,
+  Context,
+  Effect,
+  Layer,
+  ManagedRuntime,
+  type Schema as S,
+  type Scope,
+} from "effect";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
 import type * as Binding from "./Binding";