effect-cf 0.33.0 → 0.34.0

package/src/DurableObjectNamespace.ts

@@ -7,6 +7,7 @@ import type * as DurableObjectDefinition from "./DurableObjectDefinition";
 import * as RpcDefinition from "./RpcDefinition";
 import * as ErrorMessage from "./internal/ErrorMessage";
 import * as RpcInvocation from "./internal/RpcInvocation";
+import * as RpcTracing from "./RpcTracing";
 
 const expectedDurableObjectNamespace =
   "Durable Object namespace binding with getByName(), get(), idFromName(), idFromString(), newUniqueId(), and jurisdiction()";
@@ -39,29 +40,20 @@ export type DurableObjectStubClient<Api extends object> = DurableObjectFetcher &
     readonly name?: string;
   };
 
-/**
- * Native Durable Object namespace binding shape.
- */
 export interface DurableObjectNamespaceClient<Api extends object> {
-  /** Creates a globally unique Durable Object id. */
   newUniqueId(
     options?: globalThis.DurableObjectNamespaceNewUniqueIdOptions,
   ): globalThis.DurableObjectId;
-  /** Deterministically maps a name to a Durable Object id. */
   idFromName(name: string): globalThis.DurableObjectId;
-  /** Rehydrates a Durable Object id from its string form. */
   idFromString(id: string): globalThis.DurableObjectId;
-  /** Returns a stub for an existing Durable Object id. */
   get(
     id: globalThis.DurableObjectId,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
   ): DurableObjectStubClient<Api>;
-  /** Returns a stub by deterministic name. */
   getByName(
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
   ): DurableObjectStubClient<Api>;
-  /** Selects a namespace pinned to a specific jurisdiction. */
   jurisdiction(
     jurisdiction: globalThis.DurableObjectJurisdiction,
   ): DurableObjectNamespaceClient<Api>;
@@ -80,10 +72,10 @@ export interface DurableObjectNamespaceDefinition {
 export interface DurableObjectNamespaceBindingDefinition<
   Definition extends DurableObjectDefinition.Definition.Any | undefined = undefined,
 > {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
-  /** Optional RPC schema used for argument/result encoding. */
   readonly definition?: Definition;
+  /** Append live trace context only when the receiver also enables rpcTracing. */
+  readonly rpcTracing?: boolean;
 }
 
 /**
@@ -199,46 +191,22 @@ export type DurableObjectNamespaceEffectClient<
   Api extends object,
   Definition extends DurableObjectDefinition.Definition.Any | undefined = undefined,
 > = DirectMethods<never, Api, Definition> & {
-  /** Creates a globally unique Durable Object id. */
   readonly newUniqueId: (
     options?: globalThis.DurableObjectNamespaceNewUniqueIdOptions,
   ) => Effect.Effect<globalThis.DurableObjectId>;
-  /** Deterministically maps a name to a Durable Object id. */
   readonly idFromName: (name: string) => Effect.Effect<globalThis.DurableObjectId>;
-  /** Rehydrates a Durable Object id from its string form. */
   readonly idFromString: (id: string) => Effect.Effect<globalThis.DurableObjectId>;
-  /** Returns a stub for an existing Durable Object id. */
   readonly get: (
     id: globalThis.DurableObjectId,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
   ) => Effect.Effect<DurableObjectStubClient<Api>>;
-  /** Returns a stub by deterministic name. */
   readonly getByName: (
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
   ) => Effect.Effect<DurableObjectStubClient<Api>>;
-  /** Selects a namespace pinned to a specific jurisdiction. */
   readonly jurisdiction: (
     jurisdiction: globalThis.DurableObjectJurisdiction,
   ) => Effect.Effect<DurableObjectNamespaceClient<Api>>;
-  /**
-   * Forwards an HTTP request to a Durable Object stub.
-   *
-   * Use this for fetch-based Durable Object APIs, including WebSocket upgrade
-   * forwarding where the native response must be preserved.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const rooms = yield* ChatRooms;
-   *   const room = yield* rooms.getByName("general");
-   *
-   *   return yield* rooms.fetch(room, new Request("https://worker.example/room"));
-   * });
-   * ```
-   */
   readonly fetch: (
     stub: DurableObjectStubClient<Api>,
     input: RequestInfo | URL,
@@ -252,21 +220,6 @@ export type DurableObjectNamespaceEffectClient<
    * promise-like value and it does not decode definition-backed success schemas.
    *
    * Most application code should use {@link call} instead.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const counters = yield* Counters;
-   *   const counter = yield* counters.getByName("main");
-   *
-   *   const result = yield* counters.rpc(counter, "get");
-   *   const value = yield* Effect.promise(() => result);
-   *
-   *   return value;
-   * });
-   * ```
    */
   readonly rpc: <Method extends StubMethodKey<Api>>(
     stub: DurableObjectStubClient<Api>,
@@ -278,18 +231,6 @@ export type DurableObjectNamespaceEffectClient<
    * decodes the success value when the namespace was created from a definition.
    *
    * This is the normal choice when application code wants the final typed value.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const counters = yield* Counters;
-   *   const counter = yield* counters.getByName("main");
-   *
-   *   return yield* counters.call(counter, "increment", 1);
-   * });
-   * ```
    */
   readonly call: <Method extends StubMethodKey<Api>>(
     stub: DurableObjectStubClient<Api>,
@@ -304,21 +245,6 @@ export type DurableObjectNamespaceEffectClient<
    *
    * Use this for RPC methods that return Cloudflare RPC resources or other
    * disposable objects whose lifetime should be tied to an Effect scope.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.scoped(
-   *   Effect.gen(function* () {
-   *     const rooms = yield* ChatRooms;
-   *     const room = yield* rooms.getByName("general");
-   *     const handle = yield* rooms.scopedCall(room, "openStream");
-   *
-   *     return yield* handle.read();
-   *   }),
-   * );
-   * ```
    */
   readonly scopedCall: <Method extends StubMethodKey<Api>>(
     stub: DurableObjectStubClient<Api>,
@@ -429,9 +355,11 @@ export const makeClient = <
         catch: (cause) => new DurableObjectFetchError({ binding: definition.binding, cause }),
       });
 
-    const rpc = Effect.fn("DurableObjectNamespace.rpc")(function* <
-      Method extends StubMethodKey<Api>,
-    >(stub: StubClient, method: Method, ...args: StubMethodArgs<Api, Method>) {
+    const rpc = Effect.fnUntraced(function* <Method extends StubMethodKey<Api>>(
+      stub: StubClient,
+      method: Method,
+      ...args: StubMethodArgs<Api, Method>
+    ): Effect.fn.Return<StubMethodCloudflareReturn<Api, Method>, DurableObjectRpcError> {
       const methodName = String(method);
       // SAFETY: the runtime definition and method name select the same method schemas as Method.
       const encodedArgs =
@@ -452,11 +380,15 @@ export const makeClient = <
               ),
             );
 
-      // SAFETY: encodedArgs preserves the selected method's positional argument contract.
+      const nativeArgs = definition.rpcTracing
+        ? yield* RpcTracing.withRpcTraceContext(encodedArgs)
+        : encodedArgs;
+
+      // SAFETY: domain arguments retain their encoded order; an opted-in receiver strips only valid trace metadata.
       return yield* RpcInvocation.invokeRpcMethod(
         stub,
         method,
-        encodedArgs as StubMethodArgs<Api, Method>,
+        nativeArgs as StubMethodArgs<Api, Method>,
         (cause) =>
           new DurableObjectRpcError({
             binding: definition.binding,
@@ -466,9 +398,10 @@ export const makeClient = <
       );
     });
 
-    const decodeSuccess = Effect.fn("DurableObjectNamespace.decodeSuccess")(function* <
-      Method extends StubMethodKey<Api>,
-    >(methodName: string, value: Awaited<StubMethodCloudflareReturn<Api, Method>>) {
+    const decodeSuccess = Effect.fnUntraced(function* <Method extends StubMethodKey<Api>>(
+      methodName: string,
+      value: Awaited<StubMethodCloudflareReturn<Api, Method>>,
+    ): Effect.fn.Return<StubMethodSuccess<Api, Method>, DurableObjectRpcError> {
       if (definition.definition === undefined) {
         // SAFETY: without a schema codec, the native RPC result is already the declared success type.
         return value as StubMethodSuccess<Api, Method>;
@@ -494,33 +427,45 @@ export const makeClient = <
       return decoded as StubMethodSuccess<Api, Method>;
     });
 
-    const call = Effect.fn("DurableObjectNamespace.call")(function* <
-      Method extends StubMethodKey<Api>,
-    >(stub: StubClient, method: Method, ...args: StubMethodArgs<Api, Method>) {
-      const methodName = String(method);
-      const value = yield* CloudflareRpc.resolve(yield* rpc(stub, method, ...args)).pipe(
-        Effect.mapError(
-          (cause) =>
-            new DurableObjectRpcError({
-              binding: definition.binding,
-              method: methodName,
-              cause,
-            }),
-        ),
-      );
-
-      return yield* decodeSuccess<Method>(methodName, value);
-    });
-
-    const scopedCall = Effect.fn("DurableObjectNamespace.scopedCall")(function* <
-      Method extends StubMethodKey<Api>,
-    >(stub: StubClient, method: Method, ...args: StubMethodArgs<Api, Method>) {
-      const methodName = String(method);
-      const result = yield* rpc(stub, method, ...args);
-      const value = yield* CloudflareRpc.scoped(result);
-
-      return yield* decodeSuccess<Method>(methodName, value);
-    });
+    const call = Effect.fnUntraced(
+      function* <Method extends StubMethodKey<Api>>(
+        stub: StubClient,
+        method: Method,
+        ...args: StubMethodArgs<Api, Method>
+      ): Effect.fn.Return<StubMethodSuccess<Api, Method>, DurableObjectRpcError> {
+        const methodName = String(method);
+        const value = yield* CloudflareRpc.resolve(yield* rpc(stub, method, ...args)).pipe(
+          Effect.mapError(
+            (cause) =>
+              new DurableObjectRpcError({
+                binding: definition.binding,
+                method: methodName,
+                cause,
+              }),
+          ),
+        );
+
+        return yield* decodeSuccess<Method>(methodName, value);
+      },
+      (effect, ...args) =>
+        RpcTracing.withRpcClientSpan(effect, definition.binding, String(args[1])),
+    );
+
+    const scopedCall = Effect.fnUntraced(
+      function* <Method extends StubMethodKey<Api>>(
+        stub: StubClient,
+        method: Method,
+        ...args: StubMethodArgs<Api, Method>
+      ): Effect.fn.Return<StubMethodSuccess<Api, Method>, unknown, Scope.Scope> {
+        const methodName = String(method);
+        const result = yield* rpc(stub, method, ...args);
+        const value = yield* CloudflareRpc.scoped(result);
+
+        return yield* decodeSuccess<Method>(methodName, value);
+      },
+      (effect, ...args) =>
+        RpcTracing.withRpcClientSpan(effect, definition.binding, String(args[1])),
+    );
 
     const directMethods = makeDirectMethods<never, Api, Definition>(definition.definition, {
       call,

package/src/DurableObjectRpcWebSocket.ts

@@ -22,14 +22,12 @@ const serviceRestartReason = "Durable Object RPC activation reset";
 /** Heartbeat handling for Effect's application-level RPC Ping messages. */
 export type HeartbeatPolicy = "auto-response" | "passthrough";
 
-/** Object-shaped application attachment fields that can coexist with adapter metadata. */
 export type RpcWebSocketAttachment = object;
 
 /** A resumable RPC stream declaration understood by the websocket transport. */
 export interface ResumableStreamDeclaration<ResumeDescriptor = unknown, Checkpoint = unknown> {
   /** Stable declaration identifier. Change it when the persisted representation changes. */
   readonly id: string;
-  /** RPC tag matched against encoded client requests. */
   readonly rpcTag: string;
   /** Validates a resume descriptor restored from a websocket attachment. */
   readonly resumeDescriptorSchema: Schema.Decoder<ResumeDescriptor>;
@@ -45,7 +43,6 @@ export interface ResumableStreamDeclaration<ResumeDescriptor = unknown, Checkpoi
     readonly resumeDescriptor: ResumeDescriptor;
     readonly acknowledgedCheckpoint: Checkpoint;
   }>;
-  /** Rebuilds the encoded request fields used to restart a handler. */
   readonly rebuild: (options: {
     readonly subscriptionKey: string;
     readonly resumeDescriptor: ResumeDescriptor;
@@ -80,9 +77,7 @@ export const resumableStream = <ResumeDescriptor, Checkpoint>(
  * Configuration for {@link layer}.
  */
 export interface LayerOptions {
-  /** Tag used to select hibernated sockets. */
   readonly tag?: string | undefined;
-  /** Socket attachment namespace used to persist adapter metadata across hibernation. */
   readonly attachmentKey?: string | undefined;
   /**
    * Heartbeat behavior. `"auto-response"` (the default) installs Cloudflare's
@@ -95,24 +90,16 @@ export interface LayerOptions {
    * when RPC and unrelated websocket protocols share one object.
    */
   readonly heartbeat?: HeartbeatPolicy | undefined;
-  /** Explicit stream declarations that may be reconstructed after activation loss. */
   readonly resumableStreams?: ReadonlyArray<AnyResumableStreamDeclaration> | undefined;
 }
 
-/** Native websocket event payload accepted by Cloudflare Durable Objects. */
 export type NativeWebSocketMessage = string | ArrayBuffer;
 
-/**
- * Service API used to wire websocket lifecycle events to Effect RPC server protocol.
- */
 export interface DurableObjectRpcWebSocketService {
-  /** Accepts a new, not-yet-accepted socket with the RPC tag and any application tags. */
+  /** Accept a server socket that has not already been accepted. */
   readonly accept: (socket: DurableWebSocket, tags?: ReadonlyArray<string>) => Effect.Effect<void>;
-  /**
-   * Creates and accepts a websocket upgrade without double-accepting the server
-   * socket. Application attachment fields are shallow-merged with the adapter's
-   * metadata namespace.
-   */
+
+  /** Shallow-merges application attachment fields with the adapter's metadata namespace. */
   readonly acceptUpgrade: <Attachment extends RpcWebSocketAttachment = RpcWebSocketAttachment>(
     options?: AcceptUpgradeOptions<Attachment>,
   ) => Effect.Effect<AcceptedUpgrade<Attachment>, DurableWebSocketAttachmentError>;
@@ -211,9 +198,6 @@ const ResumableAttachmentMetadataSchema = Schema.Struct({
 
 const decodeResumableAttachment = Schema.decodeUnknownOption(ResumableAttachmentMetadataSchema);
 
-/**
- * Context tag for the Durable Object RPC websocket service.
- */
 export class DurableObjectRpcWebSocket extends Context.Service<
   DurableObjectRpcWebSocket,
   DurableObjectRpcWebSocketService

package/src/DurableObjectSqlite.ts

@@ -4,20 +4,8 @@ import type { SqlClient } from "effect/unstable/sql";
 
 import { DurableObjectState } from "./DurableObjectState";
 
-/** Options forwarded to `@effect/sql-sqlite-do` when building a SQL client layer. */
 export type SqliteLayerOptions = Omit<SqliteClient.SqliteClientConfig, "db" | "storage">;
 
-/**
- * Provides `effect/unstable/sql` from the current Durable Object SQLite storage.
- *
- * @example
- * ```ts
- * const RoomLayer = Layer.mergeAll(
- *   DurableObjectSqlite.layer(),
- *   OtherRoomServices,
- * );
- * ```
- */
 export const layer = (
   options?: SqliteLayerOptions,
 ): Layer.Layer<SqliteClient.SqliteClient | SqlClient.SqlClient, never, DurableObjectState> =>

package/src/DurableObjectState.ts

@@ -9,13 +9,9 @@ import { makeWaitUntilScheduler } from "./internal/WorkerContext";
  * Effect-friendly wrapper around Cloudflare `DurableObjectState`.
  */
 export interface DurableObjectStateService {
-  /** Underlying Cloudflare state instance. */
   readonly raw: globalThis.DurableObjectState;
-  /** Durable Object id for the current instance. */
   readonly id: globalThis.DurableObjectId;
-  /** Wrapped storage API. */
   readonly storage: DurableObjectStorage;
-  /** Registers background work with Cloudflare's lifecycle. */
   waitUntil(promise: Promise<unknown>): Effect.Effect<void>;
   /**
    * Runs a background Effect via Cloudflare's `waitUntil` with the caller's
@@ -47,21 +43,13 @@ export interface DurableObjectStateService {
    * documented timeout (currently 30 seconds).
    */
   blockConcurrencyWhileOrReset<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
-  /** Accepts a websocket connection for hibernation-capable Durable Objects. */
   acceptWebSocket(ws: DurableWebSocket, tags?: Array<string>): Effect.Effect<void>;
-  /** Lists active sockets, optionally filtered by tag. */
   getWebSockets(tag?: string): Effect.Effect<Array<DurableWebSocket>>;
-  /** Configures automatic request/response handling for sockets. */
   setWebSocketAutoResponse(pair?: WebSocketRequestResponsePair): Effect.Effect<void>;
-  /** Gets the configured websocket auto-response pair. */
   getWebSocketAutoResponse: Effect.Effect<WebSocketRequestResponsePair | null>;
-  /** Timestamp of the last automatic websocket response for a socket. */
   getWebSocketAutoResponseTimestamp(ws: DurableWebSocket): Effect.Effect<Date | null>;
-  /** Sets the timeout for hibernatable websocket events. */
   setHibernatableWebSocketEventTimeout(timeoutMs?: number): Effect.Effect<void>;
-  /** Gets the timeout for hibernatable websocket events. */
   getHibernatableWebSocketEventTimeout: Effect.Effect<number | null>;
-  /** Reads tags attached to a websocket. */
   getTags(ws: DurableWebSocket): Effect.Effect<Array<string>>;
   /**
    * Forcibly resets the Durable Object. Cloudflare logs an uncaught Error using
@@ -73,17 +61,11 @@ export interface DurableObjectStateService {
   abort(reason?: string, options?: globalThis.DurableObjectAbortOptions): Effect.Effect<void>;
 }
 
-/**
- * Context tag for accessing the current Durable Object state service.
- */
 export class DurableObjectState extends Context.Service<
   DurableObjectState,
   DurableObjectStateService
 >()("effect-cf/DurableObjectState") {}
 
-/**
- * Wraps a native Cloudflare `DurableObjectState` as a {@link DurableObjectStateService}.
- */
 export const fromDurableObjectState = (
   state: globalThis.DurableObjectState,
 ): DurableObjectStateService => {

package/src/DurableObjectStorage.ts

@@ -2,10 +2,8 @@ import { Clock, Data, Duration, Effect, Exit, Option, Predicate, Schema as S } f
 
 import * as ErrorMessage from "./internal/ErrorMessage";
 
-/** Supported primitive value types for Durable Object SQL APIs. */
 export type SqlStorageValue = globalThis.SqlStorageValue;
 
-/** Error type used when a storage operation throws or rejects. */
 export class StorageOperationError extends Data.TaggedError("StorageOperationError")<{
   readonly operation: string;
   readonly cause: unknown;
@@ -17,9 +15,6 @@ export class StorageOperationError extends Data.TaggedError("StorageOperationErr
 
 type StorageEffect<A> = Effect.Effect<A, StorageOperationError>;
 
-/**
- * Effect wrapper for Cloudflare SQL cursor operations.
- */
 export interface SqlCursor<T extends Record<string, SqlStorageValue>> {
   next(): StorageEffect<{ done?: false; value: T } | { done: true; value?: never }>;
   toArray(): StorageEffect<Array<T>>;
@@ -30,11 +25,7 @@ export interface SqlCursor<T extends Record<string, SqlStorageValue>> {
   readonly rowsWritten: StorageEffect<number>;
 }
 
-/**
- * Effect wrapper for Durable Object SQLite APIs.
- */
 export interface SqlStorage {
-  /** Executes a SQL statement and returns a typed cursor. */
   exec<T extends Record<string, SqlStorageValue>>(
     query: string,
     ...bindings: Array<SqlStorageValue>
@@ -42,9 +33,6 @@ export interface SqlStorage {
   readonly databaseSize: number;
 }
 
-/**
- * Schema pair used by `SyncKvStorage.schema(...)`.
- */
 export interface SyncKvDefinition<Key, Value, EncodedValue> {
   readonly key: S.Codec<Key, string>;
   readonly value: S.Codec<Value, EncodedValue>;
@@ -60,9 +48,6 @@ export interface SchemaBackedSyncKvStorage<Key, Value> {
   list(options?: globalThis.SyncKvListOptions): Effect.Effect<Array<[Key, Value]>, unknown>;
 }
 
-/**
- * Effect wrapper for synchronous KV attached to Durable Object SQLite storage.
- */
 export interface SyncKvStorage {
   get<T = unknown>(key: string): StorageEffect<T | undefined>;
   put<T>(key: string, value: T): StorageEffect<void>;
@@ -99,7 +84,6 @@ export interface DurableObjectTransaction {
     scheduledTime: number | Date,
     options?: globalThis.DurableObjectSetAlarmOptions,
   ): StorageEffect<void>;
-  /** Schedules the alarm after a delay measured by the Effect clock. */
   setAlarmAfter(
     delay: Duration.Input,
     options?: globalThis.DurableObjectSetAlarmOptions,
@@ -107,19 +91,6 @@ export interface DurableObjectTransaction {
   deleteAlarm(options?: globalThis.DurableObjectSetAlarmOptions): StorageEffect<void>;
 }
 
-/**
- * Effect wrapper around Cloudflare Durable Object storage.
- *
- * @example
- * ```ts
- * const program = Effect.gen(function* () {
- *   const state = yield* DurableObjectState;
- *   yield* state.storage.put("counter", 1);
- *   const value = yield* state.storage.get<number>("counter");
- *   return value;
- * });
- * ```
- */
 export interface DurableObjectStorage {
   get<T = unknown>(
     key: string,
@@ -137,7 +108,6 @@ export interface DurableObjectStorage {
     scheduledTime: number | Date,
     options?: globalThis.DurableObjectSetAlarmOptions,
   ): StorageEffect<void>;
-  /** Schedules the alarm after a delay measured by the Effect clock. */
   setAlarmAfter(
     delay: Duration.Input,
     options?: globalThis.DurableObjectSetAlarmOptions,
@@ -161,9 +131,9 @@ export interface DurableObjectStorage {
   ): Effect.Effect<A, E | StorageOperationError, R>;
   /** Flushes pending writes to disk. */
   sync(): StorageEffect<void>;
-  /** SQLite-backed Durable Object storage point-in-time recovery API only. */
+  /** Requires SQLite-backed Durable Object storage. */
   getCurrentBookmark(): StorageEffect<string>;
-  /** SQLite-backed Durable Object storage point-in-time recovery API only. */
+  /** Requires SQLite-backed Durable Object storage. */
   onNextSessionRestoreBookmark(bookmark: string): StorageEffect<string>;
   readonly sql: SqlStorage;
   readonly kv: SyncKvStorage;
@@ -329,9 +299,6 @@ const fromDurableObjectTransaction = (
       tryStoragePromise("transaction.deleteAlarm", () => txn.deleteAlarm(options)),
   }) as DurableObjectTransaction;
 
-/**
- * Wraps native Cloudflare storage APIs as Effect-returning helpers.
- */
 export const fromDurableObjectStorage = (
   storage: globalThis.DurableObjectStorage,
 ): DurableObjectStorage => ({

package/src/DurableObjectWebSocket.ts

@@ -3,10 +3,8 @@ import { Data, Effect, Option, Result, Schema as S } from "effect";
 import { DurableObjectState } from "./DurableObjectState";
 import * as ErrorMessage from "./internal/ErrorMessage";
 
-/** Data supported by Cloudflare websocket `send`. */
 export type DurableWebSocketSendData = string | ArrayBuffer | ArrayBufferView;
 
-/** Error raised when sending on a Durable Object websocket fails. */
 export class DurableWebSocketSendError extends Data.TaggedError("DurableWebSocketSendError")<{
   readonly cause: unknown;
 }> {
@@ -15,7 +13,6 @@ export class DurableWebSocketSendError extends Data.TaggedError("DurableWebSocke
   }
 }
 
-/** Error raised when closing a Durable Object websocket fails. */
 export class DurableWebSocketCloseError extends Data.TaggedError("DurableWebSocketCloseError")<{
   readonly cause: unknown;
 }> {
@@ -36,13 +33,9 @@ export class DurableWebSocketAttachmentError extends Data.TaggedError(
   }
 }
 
-/** Effect-native wrapper around a hibernatable Durable Object websocket. */
 export interface DurableWebSocket<Attachment = unknown> {
-  /** Underlying Cloudflare websocket. */
   readonly raw: WebSocket;
-  /** Sends a message through the socket. */
   send(data: DurableWebSocketSendData): Effect.Effect<void, DurableWebSocketSendError>;
-  /** Closes the socket. */
   close(code?: number, reason?: string): Effect.Effect<void, DurableWebSocketCloseError>;
   /** Serializes hibernation attachment metadata onto the socket. */
   serializeAttachment<A = Attachment>(
@@ -54,7 +47,6 @@ export interface DurableWebSocket<Attachment = unknown> {
 
 const wrappers = new WeakMap<WebSocket, DurableWebSocket<unknown>>();
 
-/** Wraps a native Cloudflare websocket in the Effect-native Durable Object API. */
 export const fromWebSocket = <Attachment = unknown>(
   raw: WebSocket,
 ): DurableWebSocket<Attachment> => {
@@ -94,37 +86,18 @@ export const fromWebSocket = <Attachment = unknown>(
   return socket as DurableWebSocket<Attachment>;
 };
 
-/**
- * Options for accepting an incoming websocket request in a Durable Object.
- */
 export interface AcceptUpgradeOptions<Attachment = unknown> {
-  /** Optional websocket tags for Durable Object hibernation filtering. */
   readonly tags?: ReadonlyArray<string> | undefined;
   /** Optional attachment serialized onto the server socket. */
   readonly attachment?: Attachment | undefined;
 }
 
-/**
- * Result of a websocket upgrade accepted by {@link acceptUpgrade}.
- */
 export interface AcceptedUpgrade<Attachment = unknown> {
   readonly client: WebSocket;
   readonly server: DurableWebSocket<Attachment>;
   readonly response: Response;
 }
 
-/**
- * Accepts a websocket upgrade and registers the server socket on `DurableObjectState`.
- *
- * @example
- * ```ts
- * const response = yield* DurableObjectWebSocket.acceptUpgrade({
- *   tags: ["room:general"],
- * });
- *
- * return response.response;
- * ```
- */
 export const acceptUpgrade = Effect.fn("DurableObjectWebSocket.acceptUpgrade")(function* <
   Attachment = unknown,
 >(
@@ -158,9 +131,7 @@ export const acceptUpgrade = Effect.fn("DurableObjectWebSocket.acceptUpgrade")(f
 export type AttachmentInvalidPolicy = "ignore" | "ignore-and-close" | "fail";
 
 export interface AttachmentRehydrateOptions {
-  /** Optional Durable Object websocket tag filter. */
   readonly tag?: string | undefined;
-  /** Invalid attachment behavior. Defaults to skipping invalid sockets. */
   readonly onInvalid?: AttachmentInvalidPolicy | undefined;
 }
 
@@ -187,7 +158,6 @@ export interface DurableWebSocketAttachment<Attachment, Encoded> {
   readonly schema: S.Codec<Attachment, Encoded, never, never>;
 }
 
-/** Creates typed attachment helpers for accepted and rehydrated sockets. */
 export const attachment = <const AttachmentSchema extends S.Codec<any, any, never, never>>(
   schema: AttachmentSchema,
 ): DurableWebSocketAttachment<
@@ -267,7 +237,6 @@ export interface DurableWebSocketHandlers<R = never, E = unknown> {
   readonly error?: (socket: DurableWebSocket, cause: unknown) => Effect.Effect<void, E, R>;
 }
 
-/** Maps compact websocket lifecycle handler names to `DurableObject.make` options. */
 export const handlers = <R = never, E = unknown>(options: DurableWebSocketHandlers<R, E>) => ({
   webSocketMessage: options.message,
   webSocketClose: options.close,