@effect/platform-node-shared 4.0.0-beta.66 → 4.0.0-beta.67

package/src/NodeSocket.ts

@@ -1,5 +1,19 @@
 /**
- * @since 1.0.0
+ * Shared Node socket constructors for adapting `node:net` connections and
+ * other Node `Duplex` streams to Effect's `Socket.Socket` interface.
+ *
+ * Use this module when building TCP clients, Unix domain socket clients, or
+ * higher-level protocols that already expose a Node `Duplex`. Connections are
+ * scoped, so finalizers close or destroy the underlying stream, open timeouts
+ * are reported as socket open errors, and Node read, write, and close events
+ * are translated into `SocketError` values.
+ *
+ * Node sockets have a few operational details worth keeping in mind: Unix
+ * socket paths are supplied through `NetConnectOpts.path`, writes complete only
+ * after Node accepts or flushes the chunk, and abnormal close events are
+ * surfaced as close errors while normal remote ends complete the socket run.
+ *
+ * @since 4.0.0
  */
 import type { Array } from "effect"
 import * as Channel from "effect/Channel"
@@ -18,22 +32,29 @@ import * as Net from "node:net"
 import type { Duplex } from "node:stream"
 
 /**
- * @since 1.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * as NodeWS from "ws"
 
 /**
- * @since 1.0.0
+ * Service tag for the underlying Node `net.Socket` associated with the current
+ * socket connection.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class NetSocket extends Context.Service<NetSocket, Net.Socket>()(
   "@effect/platform-node/NodeSocket/NetSocket"
 ) {}
 
 /**
- * @since 1.0.0
+ * Opens a TCP connection with Node `net.createConnection` and exposes it as a
+ * `Socket.Socket`, supporting `openTimeout` and closing or destroying the
+ * socket when the enclosing scope is finalized.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeNet = (
   options: Net.NetConnectOpts & {
@@ -77,8 +98,12 @@ export const makeNet = (
   )
 
 /**
- * @since 1.0.0
+ * Adapts a Node `Duplex` into a `Socket.Socket`, wiring data events to socket
+ * handlers, providing a scoped writer, and mapping open, read, write, and close
+ * failures to `SocketError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromDuplex = <RO>(
   open: Effect.Effect<Duplex, Socket.SocketError, RO>,
@@ -212,8 +237,11 @@ export const fromDuplex = <RO>(
   })
 
 /**
- * @since 1.0.0
+ * Creates a `Channel` over a TCP socket, reading arrays of `Uint8Array`
+ * chunks and writing arrays of bytes, strings, or socket close events.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeNetChannel = <IE = never>(
   options: Net.NetConnectOpts
@@ -229,8 +257,11 @@ export const makeNetChannel = <IE = never>(
   )
 
 /**
- * @since 1.0.0
+ * Provides a `Socket.Socket` by opening a TCP connection with the supplied
+ * Node `net` connection options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerNet: (options: Net.NetConnectOpts) => Layer.Layer<
   Socket.Socket,

package/src/NodeSocketServer.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Shared Node socket server constructors for exposing `node:net` servers and
+ * `ws` WebSocket servers as Effect `SocketServer.SocketServer` services.
+ *
+ * Use this module when implementing TCP services, Unix domain socket services,
+ * WebSocket endpoints, or higher-level protocols such as RPC transports that
+ * need to accept incoming connections through Effect's socket APIs. TCP
+ * connections are adapted through `NodeSocket.fromDuplex`, while WebSocket
+ * handlers also receive the underlying `WebSocket` and Node `IncomingMessage`
+ * in their fiber context.
+ *
+ * The server starts listening before the constructor returns, and the exported
+ * `address` is derived from the actual Node server after binding. Prefer that
+ * address when using port `0`, wildcard hosts, or Unix socket paths. Incoming
+ * connections accepted before `run` is installed are queued and then handed to
+ * the handler, each `run` call owns the scope for its connection fibers, and
+ * the enclosing scope closes the underlying Node server.
+ *
+ * @since 4.0.0
  */
 import type { Cause } from "effect/Cause"
 import * as Context from "effect/Context"
@@ -20,8 +37,11 @@ import * as NodeSocket from "./NodeSocket.ts"
 import { NodeWS } from "./NodeSocket.ts"
 
 /**
- * @since 1.0.0
+ * Service tag for the Node `IncomingMessage` associated with the current
+ * WebSocket server connection.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class IncomingMessage extends Context.Service<
   IncomingMessage,
@@ -29,8 +49,12 @@ export class IncomingMessage extends Context.Service<
 >()("@effect/platform-node-shared/NodeSocketServer/IncomingMessage") {}
 
 /**
- * @since 1.0.0
+ * Creates a scoped TCP `SocketServer` from a Node `net.Server`, starts
+ * listening with the supplied options, queues pending connections until `run`
+ * is called, and closes the server when the scope ends.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*(
   options: Net.ServerOpts & Net.ListenOptions
@@ -144,8 +168,11 @@ export const make = Effect.fnUntraced(function*(
 })
 
 /**
- * @since 1.0.0
+ * Provides a TCP `SocketServer` by creating and managing a scoped Node
+ * `net.Server` with the supplied server and listen options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: (
   options: Net.ServerOpts & Net.ListenOptions
@@ -155,8 +182,12 @@ export const layer: (
 > = Function.flow(make, Layer.effect(SocketServer.SocketServer))
 
 /**
- * @since 1.0.0
+ * Creates a scoped WebSocket `SocketServer` backed by the `ws` package,
+ * providing the WebSocket and its Node `IncomingMessage` to connection
+ * handlers and closing the server when the scope ends.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWebSocket: (
   options: NodeWS.ServerOptions<typeof NodeWS.WebSocket, typeof Http.IncomingMessage>
@@ -255,8 +286,11 @@ export const makeWebSocket: (
 })
 
 /**
- * @since 1.0.0
+ * Provides a WebSocket `SocketServer` backed by the `ws` package and managed
+ * with the supplied server options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket: (
   options: NodeSocket.NodeWS.ServerOptions<typeof NodeSocket.NodeWS.WebSocket, typeof Http.IncomingMessage>

package/src/NodeStdio.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * Shared Node.js implementation of the Effect `Stdio` service.
+ *
+ * This module builds the `Stdio` layer used by Node platform packages by
+ * wiring the service to the current process: command-line arguments come from
+ * `process.argv`, input is read from `process.stdin`, and output and error
+ * output are written to `process.stdout` and `process.stderr`. It is intended
+ * for CLIs, scripts, command runners, test harnesses, and other
+ * process-oriented programs that need standard I/O through Effect services.
+ *
+ * The process stdio streams are global resources owned by Node. This layer
+ * leaves stdin open and does not end stdout or stderr by default, avoiding
+ * accidental closure of handles other code in the process may still use. Those
+ * streams may be pipes, files, or TTYs; interactive terminal behavior such as
+ * raw mode, echo, colors, and cursor movement should be coordinated with the
+ * terminal APIs instead of assuming this layer has exclusive control.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -9,8 +25,12 @@ import { fromWritable } from "./NodeSink.ts"
 import { fromReadable } from "./NodeStream.ts"
 
 /**
+ * Provides `Stdio` from `process.argv`, `process.stdin`, `process.stdout`,
+ * and `process.stderr`; stdin remains open and stdout/stderr are not ended by
+ * default.
+ *
  * @category Layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Stdio.Stdio> = Layer.succeed(
   Stdio.Stdio,

package/src/NodeStream.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * Interoperability between Node streams and Effect streams and channels.
+ *
+ * This module adapts `Readable` and `Duplex` instances at the boundary with
+ * Node APIs: wrapping sources such as files, HTTP responses, child process
+ * output, and compression transforms as Effect `Stream`s or `Channel`s, piping
+ * Effect streams through Node duplex transforms, exposing an Effect `Stream`
+ * back to Node as a `Readable`, and collecting small readable payloads into
+ * strings or binary buffers.
+ *
+ * The adapters preserve the Node stream semantics that matter for production
+ * code. Writes wait for `drain` when a writable side applies backpressure,
+ * readable streams are destroyed on scope finalization by default, and stream
+ * failures are routed through `onError` or `Cause.UnknownError`. For long-lived
+ * or externally owned streams, pass `closeOnDone` or `endOnDone` carefully, and
+ * use `maxBytes` on collection helpers to avoid buffering unbounded input.
+ *
+ * @since 4.0.0
  */
 import * as Arr from "effect/Array"
 import * as Cause from "effect/Cause"
@@ -20,8 +36,12 @@ import { Readable } from "node:stream"
 import { pullIntoWritable } from "./NodeSink.ts"
 
 /**
+ * Converts a Node readable stream into an Effect `Stream`, reading chunks with
+ * an optional chunk size, mapping stream errors with `onError`, and destroying
+ * the readable on completion unless `closeOnDone` is `false`.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const fromReadable = <A = Uint8Array, E = Cause.UnknownError>(options: {
   readonly evaluate: LazyArg<Readable | NodeJS.ReadableStream>
@@ -32,8 +52,12 @@ export const fromReadable = <A = Uint8Array, E = Cause.UnknownError>(options: {
 }): Stream.Stream<A, E> => Stream.fromChannel(fromReadableChannel<A, E>(options))
 
 /**
+ * Creates a `Channel` that pulls chunks from a Node readable stream, mapping
+ * errors with `onError` and destroying the readable on completion unless
+ * `closeOnDone` is `false`.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const fromReadableChannel = <A = Uint8Array, E = Cause.UnknownError>(options: {
   readonly evaluate: LazyArg<Readable | NodeJS.ReadableStream>
@@ -52,8 +76,12 @@ export const fromReadableChannel = <A = Uint8Array, E = Cause.UnknownError>(opti
   )
 
 /**
+ * Creates a `Channel` over a Node `Duplex`, writing upstream chunks with
+ * backpressure while emitting chunks read from the duplex and optionally ending
+ * the writable side when upstream completes.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const fromDuplex = <IE, I = Uint8Array, O = Uint8Array, E = Cause.UnknownError>(
   options: {
@@ -95,13 +123,19 @@ export const fromDuplex = <IE, I = Uint8Array, O = Uint8Array, E = Cause.Unknown
   })
 
 /**
+ * Pipes an Effect `Stream` through a Node `Duplex`, writing the stream's
+ * chunks to the duplex and emitting chunks read back from it.
+ *
  * @category combinators
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const pipeThroughDuplex: {
   /**
+   * Pipes an Effect `Stream` through a Node `Duplex`, writing the stream's
+   * chunks to the duplex and emitting chunks read back from it.
+   *
    * @category combinators
-   * @since 1.0.0
+   * @since 4.0.0
    */
   <B = Uint8Array, E2 = Cause.UnknownError>(
     options: {
@@ -114,8 +148,11 @@ export const pipeThroughDuplex: {
     }
   ): <R, E, A>(self: Stream.Stream<A, E, R>) => Stream.Stream<B, E2 | E, R>
   /**
+   * Pipes an Effect `Stream` through a Node `Duplex`, writing the stream's
+   * chunks to the duplex and emitting chunks read back from it.
+   *
    * @category combinators
-   * @since 1.0.0
+   * @since 4.0.0
    */
   <R, E, A, B = Uint8Array, E2 = Cause.UnknownError>(
     self: Stream.Stream<A, E, R>,
@@ -145,18 +182,27 @@ export const pipeThroughDuplex: {
   ))
 
 /**
+ * Pipes a stream of strings or bytes through a Node `Duplex` using default
+ * options and `Cause.UnknownError` for stream failures.
+ *
  * @category combinators
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const pipeThroughSimple: {
   /**
+   * Pipes a stream of strings or bytes through a Node `Duplex` using default
+   * options and `Cause.UnknownError` for stream failures.
+   *
    * @category combinators
-   * @since 1.0.0
+   * @since 4.0.0
    */
   (duplex: LazyArg<Duplex>): <R, E>(self: Stream.Stream<string | Uint8Array, E, R>) => Stream.Stream<Uint8Array, E | Cause.UnknownError, R>
   /**
+   * Pipes a stream of strings or bytes through a Node `Duplex` using default
+   * options and `Cause.UnknownError` for stream failures.
+   *
    * @category combinators
-   * @since 1.0.0
+   * @since 4.0.0
    */
   <R, E>(self: Stream.Stream<string | Uint8Array, E, R>, duplex: LazyArg<Duplex>): Stream.Stream<Uint8Array, Cause.UnknownError | E, R>
 } = dual(2, <R, E>(
@@ -165,8 +211,12 @@ export const pipeThroughSimple: {
 ): Stream.Stream<Uint8Array, Cause.UnknownError | E, R> => pipeThroughDuplex(self, { evaluate: duplex }))
 
 /**
- * @since 1.0.0
+ * Converts an Effect `Stream` into a Node `Readable`, using the caller's
+ * Effect context to run the stream and destroying the readable if the stream
+ * fails.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toReadable = <E, R>(stream: Stream.Stream<string | Uint8Array, E, R>): Effect.Effect<Readable, never, R> =>
   Effect.map(
@@ -175,8 +225,11 @@ export const toReadable = <E, R>(stream: Stream.Stream<string | Uint8Array, E, R
   )
 
 /**
- * @since 1.0.0
+ * Converts a service-free Effect `Stream` into a Node `Readable` using an
+ * empty Effect context.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toReadableNever = <E>(stream: Stream.Stream<string | Uint8Array, E, never>): Readable =>
   new StreamAdapter(
@@ -185,8 +238,12 @@ export const toReadableNever = <E>(stream: Stream.Stream<string | Uint8Array, E,
   )
 
 /**
- * @since 1.0.0
+ * Consumes a Node readable stream into a string using the selected encoding,
+ * failing through `onError` on stream errors or when `maxBytes` is exceeded
+ * and destroying the stream on interruption or failure.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toString = <E = Cause.UnknownError>(
   readable: LazyArg<Readable | NodeJS.ReadableStream>,
@@ -234,8 +291,12 @@ export const toString = <E = Cause.UnknownError>(
 }
 
 /**
- * @since 1.0.0
+ * Consumes a Node readable stream into an `ArrayBuffer`, failing through
+ * `onError` on stream errors or when `maxBytes` is exceeded and destroying the
+ * stream on interruption or failure.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toArrayBuffer = <E = Cause.UnknownError>(
   readable: LazyArg<Readable | NodeJS.ReadableStream>,
@@ -281,8 +342,11 @@ export const toArrayBuffer = <E = Cause.UnknownError>(
 }
 
 /**
- * @since 1.0.0
+ * Consumes a Node readable stream into a `Uint8Array`, using the same error
+ * mapping and `maxBytes` handling as `toArrayBuffer`.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toUint8Array = <E = Cause.UnknownError>(
   readable: LazyArg<Readable | NodeJS.ReadableStream>,

package/src/NodeTerminal.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Shared Node.js implementation of Effect's `Terminal` service.
+ *
+ * This module is the process-backed terminal implementation used by Node
+ * platform packages. It adapts Node's `readline` APIs and the current
+ * process' `stdin` and `stdout` streams into a `Terminal`, making it suitable
+ * for CLIs, REPLs, prompts, full-screen terminal programs, and other
+ * command-line tools that need line input, keypress input, terminal
+ * dimensions, or prompt output.
+ *
+ * The implementation works with global process streams, so callers should
+ * acquire it with a scope or provide `layer` to ensure cleanup. When `stdin`
+ * is a TTY, raw mode is enabled while the scoped readline interface is active
+ * and restored on release; raw mode changes how keys are delivered and can
+ * affect other code reading stdin. In non-TTY environments such as pipes,
+ * redirected input, or CI, raw mode is unavailable, keypress behavior is
+ * limited, and stdout dimensions may be reported as zero.
+ *
+ * @since 4.0.0
  */
 import type * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
@@ -14,8 +31,12 @@ import * as Terminal from "effect/Terminal"
 import * as readline from "node:readline"
 
 /**
- * @since 1.0.0
+ * Creates a scoped process-backed `Terminal` using Node `readline`, enabling
+ * TTY raw mode while in scope and using the supplied predicate to decide when
+ * key input should end.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (
   shouldQuit?: (input: Terminal.UserInput) => boolean
@@ -47,6 +68,7 @@ export const make: (
     })
 
     const columns = Effect.sync(() => stdout.columns ?? 0)
+    const rows = Effect.sync(() => stdout.rows ?? 0)
 
     const readInput = Effect.gen(function*() {
       yield* RcRef.get(rlRef)
@@ -94,6 +116,7 @@ export const make: (
 
     return Terminal.make({
       columns,
+      rows,
       readInput,
       readLine,
       display
@@ -102,8 +125,11 @@ export const make: (
 )
 
 /**
- * @since 1.0.0
+ * Provides the default process-backed `Terminal` service, ending key input on
+ * Ctrl+C or Ctrl+D.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Terminal.Terminal> = Layer.effect(Terminal.Terminal, make(defaultShouldQuit))