Skip to content

Socket.ts

Socket.ts overview

Models bidirectional socket connections in Effect.

The Socket service runs handlers for binary, string, or raw frames and provides a scoped writer for outgoing bytes, text, or close events. This module also includes socket errors, channel adapters, WebSocket layers, and transform-stream-backed sockets.

Since v4.0.0

Exports Grouped by Category

combinators
constructors
errors
fiber refs
- SendQueueCapacity
guards
- isSocket
layers
- layerWebSocket
- layerWebSocketConstructorGlobal
models
predicates
- defaultCloseCodeIsError
refinements
- isCloseEvent
- isSocketError
services
type IDs

combinators

toChannel

Converts a Socket into a binary Channel, encoding incoming string frames as UTF-8 bytes.

Signature

declare const toChannel: <IE>(
  self: Socket
) => Channel.Channel<
  NonEmptyReadonlyArray<Uint8Array>,
  SocketError | IE,
  void,
  NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
  IE
>

Since v4.0.0

toChannelMap

Converts a Socket into a bidirectional Channel, mapping incoming string or binary frames and writing outgoing frame batches to the socket.

Signature

declare const toChannelMap: <IE, A>(
  self: Socket,
  f: (data: Uint8Array | string) => A
) => Channel.Channel<
  NonEmptyReadonlyArray<A>,
  SocketError | IE,
  void,
  NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
  IE
>

Since v4.0.0

toChannelString

Converts a Socket into a string Channel, decoding binary frames with the optional text encoding.

Signature

declare const toChannelString: {
  (
    encoding?: string | undefined
  ): <IE>(
    self: Socket
  ) => Channel.Channel<
    NonEmptyReadonlyArray<string>,
    SocketError | IE,
    void,
    NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
    IE
  >
  <IE>(
    self: Socket,
    encoding?: string | undefined
  ): Channel.Channel<
    NonEmptyReadonlyArray<string>,
    SocketError | IE,
    void,
    NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
    IE
  >
}

Since v4.0.0

toChannelWith

Creates a Socket to binary Channel adapter with a fixed upstream error type.

Signature

declare const toChannelWith: <IE = never>() => (
  self: Socket
) => Channel.Channel<
  NonEmptyReadonlyArray<Uint8Array>,
  SocketError | IE,
  void,
  NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
  IE
>

Since v4.0.0

constructors

fromTransformStream

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.

Signature

declare const fromTransformStream: <R>(
  acquire: Effect.Effect<InputTransformStream, SocketError, R>,
  options?: { readonly closeCodeIsError?: (code: number) => boolean }
) => Effect.Effect<Socket, never, Exclude<R, Scope.Scope>>

Since v4.0.0

fromWebSocket

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.

Signature

declare const fromWebSocket: <RO>(
  acquire: Effect.Effect<globalThis.WebSocket, SocketError, RO>,
  options?:
    | {
        readonly closeCodeIsError?: ((code: number) => boolean) | undefined
        readonly openTimeout?: Duration.Input | undefined
      }
    | undefined
) => Effect.Effect<Socket, never, Exclude<RO, Scope.Scope>>

Since v4.0.0

make

Constructs a Socket from a raw read loop and scoped writer, deriving binary and string read loops when they are not provided.

Signature

declare const make: (options: {
  readonly runRaw: <_, E, R>(
    handler: (_: string | Uint8Array) => Effect.Effect<_, E, R> | void,
    options?: { readonly onOpen?: Effect.Effect<void> | undefined }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly run?: <_, E, R>(
    handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void,
    options?: { readonly onOpen?: Effect.Effect<void> | undefined }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly runString?: <_, E, R>(
    handler: (_: string) => Effect.Effect<_, E, R> | void,
    options?: { readonly onOpen?: Effect.Effect<void> | undefined }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly writer: Effect.Effect<
    (chunk: Uint8Array | string | CloseEvent) => Effect.Effect<void, SocketError>,
    never,
    Scope.Scope
  >
}) => Socket

Since v4.0.0

makeChannel

Creates a binary socket Channel from the Socket service in the environment.

Signature

declare const makeChannel: <IE = never>() => Channel.Channel<
  NonEmptyReadonlyArray<Uint8Array>,
  SocketError | IE,
  void,
  NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
  IE,
  unknown,
  Socket
>

Since v4.0.0

makeWebSocket

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.

Signature

declare const makeWebSocket: (
  url: string | Effect.Effect<string>,
  options?: {
    readonly closeCodeIsError?: ((code: number) => boolean) | undefined
    readonly openTimeout?: Duration.Input | undefined
    readonly protocols?: string | Array<string> | undefined
  }
) => Effect.Effect<Socket, never, WebSocketConstructor>

Since v4.0.0

makeWebSocketChannel

Creates a binary Channel backed by a WebSocket URL, requiring a WebSocketConstructor service.

Signature

declare const makeWebSocketChannel: <IE = never>(
  url: string,
  options?: { readonly closeCodeIsError?: (code: number) => boolean }
) => Channel.Channel<
  NonEmptyReadonlyArray<Uint8Array>,
  SocketError | IE,
  void,
  NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
  IE,
  unknown,
  WebSocketConstructor
>

Since v4.0.0

errors

SocketCloseError (class)

Typed error for a socket close event, carrying the close code and optional close reason.

Signature

declare class SocketCloseError

Since v4.0.0

filterClean (static method)

Separates clean socket close errors from errors that should remain failures.

Signature

declare const filterClean: (isClean: (code: number) => boolean) => <E>(u: E) => Result.Result<SocketCloseError, E>

Since v4.0.0

SocketError (class)

Tagged error that wraps socket read, write, open, and close failures while preserving the underlying reason.

Signature

declare class SocketError {
  constructor(props: { readonly reason: SocketReadError | SocketWriteError | SocketOpenError | SocketCloseError })
}

Since v4.0.0

is (static method)

Returns true when the value is a SocketError.

Signature

declare const is: (u: unknown) => u is SocketError

Since v4.0.0

[SocketErrorTypeId] (property)

Marks this value as a socket error wrapper for runtime guards.

Signature

readonly [SocketErrorTypeId]: "~effect/socket/Socket/SocketError"

Since v4.0.0

message (property)

Signature

readonly message: string

SocketErrorReason

Schema for all socket-specific error reasons.

Signature

declare const SocketErrorReason: Schema.Union<
  readonly [typeof SocketReadError, typeof SocketWriteError, typeof SocketOpenError, typeof SocketCloseError]
>

Since v4.0.0

SocketErrorReason (type alias)

Union of socket-specific read, write, open, and close error reasons.

Signature

type SocketErrorReason = SocketReadError | SocketWriteError | SocketOpenError | SocketCloseError

Since v4.0.0

SocketOpenError (class)

Typed error for failures that occur while opening a socket, including unknown open failures and open timeouts.

Signature

declare class SocketOpenError

Since v4.0.0

SocketReadError (class)

Typed error for failures that occur while reading from a socket.

Signature

declare class SocketReadError

Since v4.0.0

message (property)

Default message used for socket read failures.

Signature

readonly message: "An error occurred during Read"

Since v4.0.0

SocketWriteError (class)

Typed error for failures that occur while writing to a socket.

Signature

declare class SocketWriteError

Since v4.0.0

message (property)

Default message used for socket write failures.

Signature

readonly message: "An error occurred during Write"

Since v4.0.0

fiber refs

SendQueueCapacity

Context reference for socket send queue capacity, defaulting to 16.

Signature

declare const SendQueueCapacity: Context.Reference<number>

Since v4.0.0

guards

isSocket

Returns true when a value is a Socket.

Signature

declare const isSocket: (u: unknown) => u is Socket

Since v4.0.0

layers

layerWebSocket

Layer that provides a Socket service backed by a WebSocket URL or URL effect.

Signature

declare const layerWebSocket: (
  url: string | Effect.Effect<string>,
  options?:
    | {
        readonly closeCodeIsError?: ((code: number) => boolean) | undefined
        readonly openTimeout?: Duration.Input | undefined
        readonly protocols?: string | Array<string> | undefined
      }
    | undefined
) => Layer.Layer<Socket, never, WebSocketConstructor>

Since v4.0.0

layerWebSocketConstructorGlobal

Layer that provides WebSocketConstructor using globalThis.WebSocket.

Signature

declare const layerWebSocketConstructorGlobal: Layer.Layer<WebSocketConstructor, never, never>

Since v4.0.0

models

CloseEvent (class)

Represents a socket close event value carrying a close code and optional reason.

Signature

declare class CloseEvent {
  constructor(code = 1000, reason?: string)
}

Since v4.0.0

toString (method)

Formats the close code and optional reason for display.

Signature

declare const toString: () => string

Since v4.0.0

[CloseEventTypeId] (property)

Marks this value as a socket close event for runtime guards.

Signature

readonly [CloseEventTypeId]: "~effect/socket/Socket/CloseEvent"

Since v4.0.0

code (property)

Signature

readonly code: number

reason (property)

Signature

readonly reason: string | undefined

InputTransformStream (interface)

Readable and writable stream pair used to adapt transform-style streams into a Socket.

Signature

export interface InputTransformStream {
  readonly readable: ReadableStream<Uint8Array> | ReadableStream<string> | ReadableStream<Uint8Array | string>
  readonly writable: WritableStream<Uint8Array>
}

Since v4.0.0

Socket (interface)

Effect-based socket abstraction for running string or binary read handlers and obtaining a scoped writer for outgoing frames and close events.

Signature

export interface Socket {
  readonly [TypeId]: typeof TypeId
  readonly run: <_, E = never, R = never>(
    handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void,
    options?: {
      readonly onOpen?: Effect.Effect<void> | undefined
    }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly runString: <_, E = never, R = never>(
    handler: (_: string) => Effect.Effect<_, E, R> | void,
    options?: {
      readonly onOpen?: Effect.Effect<void> | undefined
    }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly runRaw: <_, E = never, R = never>(
    handler: (_: string | Uint8Array) => Effect.Effect<_, E, R> | void,
    options?: {
      readonly onOpen?: Effect.Effect<void> | undefined
    }
  ) => Effect.Effect<void, SocketError | E, R>
  readonly writer: Effect.Effect<
    (chunk: Uint8Array | string | CloseEvent) => Effect.Effect<void, SocketError>,
    never,
    Scope.Scope
  >
}

Since v4.0.0

predicates

defaultCloseCodeIsError

Default close-code classifier that treats every socket close code as an error.

Signature

declare const defaultCloseCodeIsError: (_code: number) => boolean

Since v4.0.0

isCloseEvent

Returns true when a value is a CloseEvent.

Signature

declare const isCloseEvent: (u: unknown) => u is CloseEvent

Since v4.0.0

isSocketError

Returns true when a value is a SocketError.

Signature

declare const isSocketError: (u: unknown) => u is SocketError

Since v4.0.0

services

Socket

Service tag for bidirectional socket transports.

When to use

Use to access or provide the socket implementation used by programs that read and write frames through the Effect environment.

Signature

declare const Socket: Context.Service<Socket, Socket>

Since v4.0.0

WebSocket (class)

Context service for the active WebSocket instance available while a WebSocket-backed socket run is handling events.

Signature

declare class WebSocket

Since v4.0.0

WebSocketConstructor (class)

Context service for constructing WebSocket instances from a URL and optional protocols.

Signature

declare class WebSocketConstructor

Since v4.0.0

type IDs

SocketErrorTypeId

Runtime type identifier attached to SocketError values.

Signature

declare const SocketErrorTypeId: "~effect/socket/Socket/SocketError"

Since v4.0.0

SocketErrorTypeId (type alias)

Type-level identifier used to mark SocketError values.

Signature

type SocketErrorTypeId = "~effect/socket/Socket/SocketError"

Since v4.0.0

TypeId

Runtime type identifier attached to Socket services.

Signature

declare const TypeId: "~effect/socket/Socket"

Since v4.0.0