effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/socket/Socket.ts

@@ -1,4 +1,26 @@
 /**
+ * Effect-based socket abstractions for bidirectional connections that exchange
+ * text frames, binary frames, and close events.
+ *
+ * This module defines the `Socket` service, constructors for WebSocket-backed
+ * and transform-stream-backed sockets, typed socket errors, and adapters that
+ * expose a socket as a bidirectional `Channel`. It is intended for WebSocket
+ * clients, HTTP server upgrades, protocol clients and servers, and tests or
+ * adapters that need a scoped duplex transport inside Effect programs.
+ *
+ * Incoming data can be consumed as raw frames, binary bytes, or strings.
+ * `runRaw` preserves whether the transport delivered a string or `Uint8Array`,
+ * while `run` encodes string frames as UTF-8 bytes and `runString` decodes
+ * binary frames with `TextDecoder`. Use the raw or mapping APIs when preserving
+ * frame boundaries, binary payloads, or text encodings matters.
+ *
+ * Writers are scoped to an active run and are gated until the underlying
+ * connection is open; use `onOpen` when startup writes must wait for that
+ * point. Outgoing strings and bytes are sent as data frames, while `CloseEvent`
+ * values request a close. Close events are modeled as `SocketCloseError` by
+ * default, and `closeCodeIsError` controls which close codes should fail a run
+ * versus complete cleanly.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -21,26 +43,35 @@ import * as Schema from "../../Schema.ts"
 import * as Scope from "../../Scope.ts"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier attached to `Socket` services.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export const TypeId = "~effect/socket/Socket"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `Socket`.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isSocket = (u: unknown): u is Socket => Predicate.hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Context service tag for the current `Socket` implementation.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const Socket: Context.Service<Socket, Socket> = Context.Service<Socket>("effect/socket/Socket")
 
 /**
- * @since 4.0.0
+ * Effect-based socket abstraction for running string or binary read handlers
+ * and obtaining a scoped writer for outgoing frames and close events.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Socket {
   readonly [TypeId]: typeof TypeId
@@ -70,8 +101,11 @@ export interface Socket {
 }
 
 /**
- * @since 4.0.0
+ * Constructs a `Socket` from a raw read loop and scoped writer, deriving binary
+ * and string read loops when they are not provided.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = (options: {
   readonly runRaw: <_, E, R>(
@@ -127,11 +161,15 @@ const decoder = new TextDecoder()
 const CloseEventTypeId = "~effect/socket/Socket/CloseEvent"
 
 /**
- * @since 4.0.0
+ * Socket close event value carrying a close code and optional reason.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class CloseEvent {
   /**
+   * Marks this value as a socket close event for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [CloseEventTypeId]: typeof CloseEventTypeId
@@ -144,6 +182,8 @@ export class CloseEvent {
     this.reason = reason
   }
   /**
+   * Formats the close code and optional reason for display.
+   *
    * @since 4.0.0
    */
   toString() {
@@ -152,60 +192,79 @@ export class CloseEvent {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `CloseEvent`.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isCloseEvent = (u: unknown): u is CloseEvent => Predicate.hasProperty(u, CloseEventTypeId)
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to mark `SocketError` values.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export type SocketErrorTypeId = "~effect/socket/Socket/SocketError"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier attached to `SocketError` values.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export const SocketErrorTypeId: SocketErrorTypeId = "~effect/socket/Socket/SocketError"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `SocketError`.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isSocketError = (u: unknown): u is SocketError => Predicate.hasProperty(u, SocketErrorTypeId)
 
 /**
- * @since 4.0.0
+ * Typed error for failures that occur while reading from a socket.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketReadError extends Schema.ErrorClass<SocketReadError>("effect/socket/Socket/SocketReadError")({
   _tag: Schema.tag("SocketReadError"),
   cause: Schema.Defect
 }) {
   /**
+   * Default message used for socket read failures.
+   *
    * @since 4.0.0
    */
   override readonly message = `An error occurred during Read`
 }
 
 /**
- * @since 4.0.0
+ * Typed error for failures that occur while writing to a socket.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketWriteError extends Schema.ErrorClass<SocketWriteError>("effect/socket/Socket/SocketWriteError")({
   _tag: Schema.tag("SocketWriteError"),
   cause: Schema.Defect
 }) {
   /**
+   * Default message used for socket write failures.
+   *
    * @since 4.0.0
    */
   override readonly message = `An error occurred during Write`
 }
 
 /**
- * @since 4.0.0
+ * Typed error for failures that occur while opening a socket, including
+ * unknown open failures and open timeouts.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketOpenError extends Schema.ErrorClass<SocketOpenError>("effect/socket/Socket/SocketOpenError")({
   _tag: Schema.tag("SocketOpenError"),
@@ -213,6 +272,8 @@ export class SocketOpenError extends Schema.ErrorClass<SocketOpenError>("effect/
   cause: Schema.Defect
 }) {
   /**
+   * Formats timeout and unknown open failures for display.
+   *
    * @since 4.0.0
    */
   override get message() {
@@ -223,8 +284,11 @@ export class SocketOpenError extends Schema.ErrorClass<SocketOpenError>("effect/
 }
 
 /**
- * @since 4.0.0
+ * Typed error for a socket close event, carrying the close code and optional
+ * close reason.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketCloseError extends Schema.ErrorClass<SocketCloseError>("effect/socket/Socket/SocketCloseError")({
   _tag: Schema.tag("SocketCloseError"),
@@ -232,6 +296,8 @@ export class SocketCloseError extends Schema.ErrorClass<SocketCloseError>("effec
   closeReason: Schema.optional(Schema.String)
 }) {
   /**
+   * Separates clean socket close errors from errors that should remain failures.
+   *
    * @since 4.0.0
    */
   static filterClean(isClean: (code: number) => boolean): <E>(u: E) => Result.Result<SocketCloseError, E> {
@@ -251,8 +317,10 @@ export class SocketCloseError extends Schema.ErrorClass<SocketCloseError>("effec
 }
 
 /**
- * @since 4.0.0
+ * Schema for all socket-specific error reasons.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const SocketErrorReason = Schema.Union([
   SocketReadError,
@@ -262,8 +330,10 @@ export const SocketErrorReason = Schema.Union([
 ])
 
 /**
- * @since 4.0.0
+ * Union of socket-specific read, write, open, and close error reasons.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type SocketErrorReason =
   | SocketReadError
@@ -272,8 +342,11 @@ export type SocketErrorReason =
   | SocketCloseError
 
 /**
- * @since 4.0.0
+ * Tagged error that wraps socket read, write, open, and close failures while
+ * preserving the underlying reason.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketError extends Schema.TaggedErrorClass<SocketError>(SocketErrorTypeId)("SocketError", {
   _tag: Schema.tag("SocketError"),
@@ -294,11 +367,15 @@ export class SocketError extends Schema.TaggedErrorClass<SocketError>(SocketErro
   }
 
   /**
+   * Marks this value as a socket error wrapper for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [SocketErrorTypeId]: SocketErrorTypeId = SocketErrorTypeId
 
   /**
+   * Returns `true` when the value is a `SocketError`.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is SocketError {
@@ -309,8 +386,11 @@ export class SocketError extends Schema.TaggedErrorClass<SocketError>(SocketErro
 }
 
 /**
- * @since 4.0.0
+ * Converts a `Socket` into a bidirectional `Channel`, mapping incoming string
+ * or binary frames and writing outgoing frame batches to the socket.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const toChannelMap = <IE, A>(
   self: Socket,
@@ -364,8 +444,11 @@ export const toChannelMap = <IE, A>(
   }))
 
 /**
- * @since 4.0.0
+ * Converts a `Socket` into a binary `Channel`, encoding incoming string frames
+ * as UTF-8 bytes.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const toChannel = <IE>(
   self: Socket
@@ -381,13 +464,19 @@ export const toChannel = <IE>(
 }
 
 /**
- * @since 4.0.0
+ * Converts a `Socket` into a string `Channel`, decoding binary frames with the
+ * optional text encoding.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const toChannelString: {
   /**
-   * @since 4.0.0
+   * Converts a `Socket` into a string `Channel`, decoding binary frames with the
+   * optional text encoding.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (encoding?: string | undefined): <IE>(self: Socket) => Channel.Channel<
     NonEmptyReadonlyArray<string>,
@@ -397,8 +486,11 @@ export const toChannelString: {
     IE
   >
   /**
-   * @since 4.0.0
+   * Converts a `Socket` into a string `Channel`, decoding binary frames with the
+   * optional text encoding.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <IE>(self: Socket, encoding?: string | undefined): Channel.Channel<
     NonEmptyReadonlyArray<string>,
@@ -422,8 +514,11 @@ export const toChannelString: {
 })
 
 /**
- * @since 4.0.0
+ * Creates a `Socket` to binary `Channel` adapter with a fixed upstream error
+ * type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const toChannelWith = <IE = never>() =>
 (
@@ -437,8 +532,11 @@ export const toChannelWith = <IE = never>() =>
 > => toChannel(self)
 
 /**
- * @since 4.0.0
+ * Creates a binary socket `Channel` from the `Socket` service in the
+ * environment.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeChannel = <IE = never>(): Channel.Channel<
   NonEmptyReadonlyArray<Uint8Array>,
@@ -451,21 +549,30 @@ export const makeChannel = <IE = never>(): Channel.Channel<
 > => Channel.unwrap(Effect.map(Socket, toChannelWith<IE>()))
 
 /**
+ * Default close-code classifier that treats every socket close code as an
+ * error.
+ *
  * @since 4.0.0
  */
 export const defaultCloseCodeIsError = (_code: number) => true
 
 /**
- * @since 4.0.0
+ * Context service for the active `WebSocket` instance available while a
+ * WebSocket-backed socket run is handling events.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class WebSocket extends Context.Service<WebSocket, globalThis.WebSocket>()(
   "~effect/socket/Socket/WebSocket"
 ) {}
 
 /**
- * @since 4.0.0
+ * Context service for constructing `WebSocket` instances from a URL and
+ * optional protocols.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class WebSocketConstructor extends Context.Service<
   WebSocketConstructor,
@@ -473,16 +580,22 @@ export class WebSocketConstructor extends Context.Service<
 >()("@effect/platform/Socket/WebSocketConstructor") {}
 
 /**
- * @since 4.0.0
+ * Layer that provides `WebSocketConstructor` using `globalThis.WebSocket`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocketConstructorGlobal: Layer.Layer<WebSocketConstructor> = Layer.succeed(WebSocketConstructor)(
   (url, protocols) => new globalThis.WebSocket(url, protocols)
 )
 
 /**
- * @since 4.0.0
+ * Creates a `Socket` backed by a `WebSocketConstructor`, acquiring the
+ * WebSocket for each run and using the close-code classifier to decide which
+ * closes fail the run.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWebSocket = (url: string | Effect.Effect<string>, options?: {
   readonly closeCodeIsError?: ((code: number) => boolean) | undefined
@@ -502,8 +615,12 @@ export const makeWebSocket = (url: string | Effect.Effect<string>, options?: {
   )
 
 /**
- * @since 4.0.0
+ * Builds a `Socket` from a scoped WebSocket acquisition effect, waiting for the
+ * socket to open, dispatching message handlers in fibers, and translating
+ * open, read, and close events into `SocketError` values.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromWebSocket = <RO>(
   acquire: Effect.Effect<globalThis.WebSocket, SocketError, RO>,
@@ -642,8 +759,11 @@ export const fromWebSocket = <RO>(
   })
 
 /**
- * @since 4.0.0
+ * Creates a binary `Channel` backed by a WebSocket URL, requiring a
+ * `WebSocketConstructor` service.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWebSocketChannel = <IE = never>(
   url: string,
@@ -664,8 +784,11 @@ export const makeWebSocketChannel = <IE = never>(
   )
 
 /**
- * @since 4.0.0
+ * Layer that provides a `Socket` service backed by a WebSocket URL or URL
+ * effect.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket: (
   url: string | Effect.Effect<string>,
@@ -677,16 +800,21 @@ export const layerWebSocket: (
 ) => Layer.Layer<Socket, never, WebSocketConstructor> = flow(makeWebSocket, Layer.effect(Socket))
 
 /**
- * @since 4.0.0
+ * Context reference for socket send queue capacity, defaulting to `16`.
+ *
  * @category fiber refs
+ * @since 4.0.0
  */
 export const SendQueueCapacity = Context.Reference<number>("~effect/socket/Socket/SendQueueCapacity", {
   defaultValue: () => 16
 })
 
 /**
- * @since 4.0.0
+ * Readable and writable stream pair used to adapt transform-style streams into
+ * a `Socket`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface InputTransformStream {
   readonly readable: ReadableStream<Uint8Array> | ReadableStream<string> | ReadableStream<Uint8Array | string>
@@ -694,8 +822,13 @@ export interface InputTransformStream {
 }
 
 /**
- * @since 4.0.0
+ * Builds a `Socket` from a scoped `InputTransformStream`, reading incoming
+ * chunks through socket handlers and writing outgoing chunks to the writable
+ * stream, encoding strings as UTF-8 and using close-code classification for
+ * `CloseEvent` values.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromTransformStream = <R>(acquire: Effect.Effect<InputTransformStream, SocketError, R>, options?: {
   readonly closeCodeIsError?: (code: number) => boolean

package/src/unstable/socket/SocketServer.ts

@@ -1,4 +1,26 @@
 /**
+ * Effect service model for servers that accept socket connections and hand each
+ * accepted connection to an Effect handler as a `Socket.Socket`.
+ *
+ * This module contains the shared, platform-independent contract for socket
+ * servers: a bound `address`, a long-running `run` accept loop, the TCP and
+ * Unix socket address models, and the server-level errors reported while
+ * opening or running a server. Concrete transports, such as Node TCP servers or
+ * WebSocket servers, provide this service through platform-specific layers.
+ *
+ * `SocketServer` is commonly used as the server transport for RPC protocols,
+ * cluster runners, developer tools, and tests that need an ephemeral TCP port or
+ * Unix-domain socket. A server address may differ from the requested listen
+ * options after binding, for example when listening on port `0`, so consumers
+ * should read the provided `address` from the service.
+ *
+ * The `run` effect represents the server accept loop and is expected to remain
+ * alive until interrupted or until the providing scope is closed. Protocol
+ * framing is intentionally outside this module: handlers receive a generic
+ * `Socket.Socket`, so callers are responsible for choosing byte, string, raw
+ * frame, or higher-level protocol adapters and for treating connection-level
+ * failures separately from `SocketServerError` values.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -7,8 +29,11 @@ import type * as Effect from "../../Effect.ts"
 import type * as Socket from "./Socket.ts"
 
 /**
- * @since 4.0.0
+ * Context service for a socket server, exposing its bound address and a run
+ * loop that handles each accepted `Socket`.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class SocketServer extends Context.Service<SocketServer, {
   readonly address: Address
@@ -18,20 +43,26 @@ export class SocketServer extends Context.Service<SocketServer, {
 }>()("@effect/platform/SocketServer") {}
 
 /**
- * @since 4.0.0
+ * Runtime type identifier attached to `SocketServerError` values.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const ErrorTypeId: ErrorTypeId = "@effect/platform/SocketServer/SocketServerError"
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to mark `SocketServerError` values.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type ErrorTypeId = "@effect/platform/SocketServer/SocketServerError"
 
 /**
- * @since 4.0.0
+ * Error reason for failures that occur while opening a socket server.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketServerOpenError extends Data.TaggedError("SocketServerOpenError")<{
   readonly cause: unknown
@@ -42,8 +73,10 @@ export class SocketServerOpenError extends Data.TaggedError("SocketServerOpenErr
 }
 
 /**
- * @since 4.0.0
+ * Error reason for uncategorized socket server failures.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketServerUnknownError extends Data.TaggedError("SocketServerUnknownError")<{
   readonly cause: unknown
@@ -54,14 +87,19 @@ export class SocketServerUnknownError extends Data.TaggedError("SocketServerUnkn
 }
 
 /**
- * @since 4.0.0
+ * Union of socket server error reasons.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type SocketServerErrorReason = SocketServerOpenError | SocketServerUnknownError
 
 /**
- * @since 4.0.0
+ * Tagged socket server error that wraps a server error reason and exposes its
+ * cause.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class SocketServerError extends Data.TaggedError("SocketServerError")<{
   readonly reason: SocketServerErrorReason
@@ -75,11 +113,15 @@ export class SocketServerError extends Data.TaggedError("SocketServerError")<{
     } as any)
   }
   /**
+   * Marks this value as a socket server error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ErrorTypeId]: ErrorTypeId = ErrorTypeId
 
   /**
+   * Delegates the public message to the underlying socket server error reason.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -88,14 +130,18 @@ export class SocketServerError extends Data.TaggedError("SocketServerError")<{
 }
 
 /**
- * @since 4.0.0
+ * Socket server address, either a TCP host and port or a Unix socket path.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Address = UnixAddress | TcpAddress
 
 /**
- * @since 4.0.0
+ * TCP socket server address with hostname and port.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface TcpAddress {
   readonly _tag: "TcpAddress"
@@ -104,8 +150,10 @@ export interface TcpAddress {
 }
 
 /**
- * @since 4.0.0
+ * Unix socket server address identified by a filesystem path.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface UnixAddress {
   readonly _tag: "UnixAddress"