@effect/platform-node 4.0.0-beta.70 → 4.0.0-beta.71

package/src/NodeMultipart.ts

@@ -1,20 +1,35 @@
 /**
- * Node-specific helpers for parsing HTTP `multipart/form-data` request bodies.
+ * Node.js multipart parsing for HTTP `multipart/form-data` request bodies.
  *
- * This module adapts a Node `Readable` request body plus its incoming headers
- * into the shared `Multipart` model. Use `stream` when an HTTP server route
- * wants to handle form fields and uploaded files incrementally, for example API
- * endpoints that validate text fields while piping file parts to storage. Use
- * `persisted` when the whole form should be collected into a record and uploaded
- * files should be written into scoped temporary files through the current
- * `FileSystem` and `Path` services.
+ * `NodeMultipart` adapts a Node `Readable` plus incoming HTTP headers into
+ * Effect's shared multipart model. It can expose form parts as a stream for
+ * incremental processing, or collect a complete persisted form by writing file
+ * uploads to scoped temporary files through the current `FileSystem` and `Path`
+ * services.
  *
- * Node request bodies are one-shot streams, so consume either `stream` or
- * `persisted`, and make sure file parts are drained, piped, or otherwise
- * deliberately handled. `contentEffect` loads a file into memory and should be
- * reserved for small uploads. Persisted paths live only for the surrounding
- * `Scope`, and filenames supplied by clients should be treated as metadata, not
- * trusted filesystem paths.
+ * **Mental model**
+ *
+ * Multipart request bodies are one-shot byte streams. {@link stream} parses the
+ * body as it arrives: fields are decoded to strings and file parts keep their
+ * underlying Node readable stream. {@link persisted} consumes the same kind of
+ * body, builds a `Multipart.Persisted` record, and ties temporary upload files
+ * to the surrounding `Scope`.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link stream} when a route validates fields while piping file uploads
+ *   to storage.
+ * - Use {@link persisted} when a route needs a complete form value with scoped
+ *   temporary files.
+ * - Use {@link fileToReadable} when a downstream Node library expects a
+ *   `Readable`.
+ *
+ * **Gotchas**
+ *
+ * Consume a request body with only one parser. File parts must be drained,
+ * piped, or persisted so the request can finish reading. `contentEffect` loads
+ * an uploaded file into memory, so reserve it for small files. Client-supplied
+ * filenames are metadata, not trusted filesystem paths.
  *
  * @since 4.0.0
  */

package/src/NodePath.ts

@@ -1,17 +1,30 @@
 /**
  * Node.js layers for Effect's `Path` service.
  *
- * Use this module when an Effect program running on Node needs path operations
- * from the `Path` service, such as joining and normalizing filesystem
- * locations, resolving configuration or static asset paths, working with CLI
- * path arguments, or converting between file paths and `file:` URLs.
- *
- * `layer` follows the host platform's `node:path` semantics. Use `layerPosix`
- * or `layerWin32` when code needs stable POSIX or Windows behavior regardless
- * of the operating system. These layers provide only path manipulation; they do
- * not read the filesystem or validate that paths exist. `NodeServices.layer`
- * already includes the default Node path layer, so provide this module directly
- * when you want the narrower service or one of the platform-specific variants.
+ * This module adapts Node's path and file URL behavior to the
+ * platform-independent `Path` service. Provide one of its layers when a Node
+ * program needs to build, normalize, parse, resolve, or convert paths without
+ * depending directly on `node:path`.
+ *
+ * **Mental model**
+ *
+ * `Path` is a syntactic service: it manipulates strings and `file:` URLs. It
+ * does not read the filesystem, check permissions, or validate that paths
+ * exist. The selected layer decides which separator, drive-letter, UNC, and URL
+ * conversion rules are used.
+ *
+ * **Common tasks**
+ *
+ * Use `layer` for host-platform Node semantics, `layerPosix` for stable POSIX
+ * behavior, and `layerWin32` for stable Windows behavior. `NodeServices.layer`
+ * already includes `layer`, so import this module directly when a program wants
+ * only path support or a platform-specific variant.
+ *
+ * **Gotchas**
+ *
+ * Results that are correct on one platform may not be portable to another.
+ * `fromFileUrl` and `toFileUrl` use Node's `node:url` conversion rules and
+ * report invalid conversions as `BadArgument` failures.
  *
  * @since 4.0.0
  */

package/src/NodeRedis.ts

@@ -1,22 +1,40 @@
 /**
  * Node.js Redis integration backed by `ioredis`.
  *
- * This module provides scoped layers that create an `ioredis` client and expose
- * both the low-level `Redis` service used by Effect persistence modules and the
- * `NodeRedis` service for direct access to the underlying client. It is useful
- * for Node applications that want Redis-backed persistence, persisted queues,
- * distributed rate limiting, or custom Redis commands alongside the Effect
- * services that build on Redis.
+ * This module creates a scoped `ioredis` client and exposes it in two forms:
+ * the generic `Redis` service consumed by Effect persistence modules, and the
+ * {@link NodeRedis} service for code that needs direct access to the underlying
+ * client.
  *
- * The client is acquired when the layer is built and closed with `quit` when
- * the layer scope ends, so install the layer at the lifetime you want for the
- * connection and pass `ioredis` options, or `layerConfig`, for connection,
- * TLS, database, retry, and reconnect settings. Persistence and rate limiter
- * stores build their own keys and Lua scripts on top of this service; choose
- * stable prefixes and store ids to avoid collisions, account for persisted
- * values that may fail to decode after schema changes, and avoid unbounded
- * high-cardinality rate-limit keys unless you have a cleanup or bounding
- * strategy.
+ * **Mental model**
+ *
+ * - {@link layer} creates one `ioredis` client from explicit client options
+ * - {@link layerConfig} reads the same options from `Config`
+ * - Building the layer opens the client, and closing the layer scope calls
+ *   `quit`
+ * - The generic `Redis` service sends command strings through `client.call`
+ * - {@link NodeRedis} exposes the raw client plus `use`, which maps promise
+ *   failures into `RedisError`
+ *
+ * **Common tasks**
+ *
+ * - Provide Redis-backed persistence, persisted queues, or distributed rate
+ *   limiting in Node.js
+ * - Configure connection, TLS, database, retry, and reconnect behavior with
+ *   standard `ioredis` options
+ * - Run custom Redis commands through {@link NodeRedis} when the generic
+ *   `Redis` service does not cover the command shape you need
+ *
+ * **Gotchas**
+ *
+ * - Install the layer at the lifetime you want for the connection; a short
+ *   scope opens and closes a Redis client for that scope
+ * - Persistence and rate limiter stores create their own keys and Lua scripts
+ *   on top of this service, so choose stable prefixes and store ids
+ * - Persisted values may fail to decode after schema changes; plan migrations
+ *   or cleanup for long-lived Redis data
+ * - Avoid unbounded high-cardinality rate-limit keys unless another process or
+ *   key policy bounds their lifetime
  *
  * @since 4.0.0
  */

package/src/NodeRuntime.ts

@@ -1,17 +1,31 @@
 /**
- * Node.js entry-point helpers for running Effect programs.
+ * Node.js process runner for starting an Effect program at the application
+ * edge.
  *
- * This module exposes `runMain`, the Node runtime launcher used at the edge of
- * CLI tools, scripts, servers, and worker processes. It runs an already
- * self-contained Effect as the process main program, with built-in error
- * reporting and Node signal handling.
+ * This module exposes `runMain`, the launcher used by Node CLIs, scripts,
+ * servers, and workers when a single Effect should become the process root. It
+ * handles runtime error reporting, Node process signals, and teardown so the
+ * rest of the program can stay inside Effect.
  *
- * `NodeRuntime` does not provide application services by itself. Provide any
- * required layers, such as `NodeServices.layer` or narrower service-specific
- * layers, before passing the effect to `runMain`. On `SIGINT` or `SIGTERM`,
- * the main fiber is interrupted so scoped resources and finalizers can shut
- * down; keep long-running work attached to that scope and avoid finalizers that
- * never complete, otherwise process shutdown can be delayed.
+ * **Mental model**
+ *
+ * `runMain` is the last call in `main.ts`: build the effect, provide the layers
+ * it needs, then hand the self-contained program to this module. The function
+ * does not provide Node services itself; use `NodeServices.layer` or narrower
+ * platform layers before launching.
+ *
+ * **Common tasks**
+ *
+ * - Run a CLI command or script and let failures become process failures.
+ * - Keep a server or worker fiber alive as the process main program.
+ * - Override teardown or disable automatic error reporting at the boundary.
+ *
+ * **Gotchas**
+ *
+ * `SIGINT` and `SIGTERM` interrupt the main fiber so scoped finalizers can run.
+ * Clean success lets the event loop drain naturally, while signal-triggered
+ * interruption or a non-zero teardown code exits the process. Keep long-lived
+ * resources in Effect scopes and avoid finalizers that never complete.
  *
  * @since 4.0.0
  */
@@ -24,7 +38,7 @@ import type * as Runtime from "effect/Runtime"
  *
  * **When to use**
  *
- * Use this function to run an Effect as your application's main program, especially
+ * Use to run an Effect as your application's main program, especially
  * when you need structured error handling, log management, interrupt support,
  * or advanced teardown capabilities.
  *
@@ -49,7 +63,7 @@ export const runMain: {
    *
    * **When to use**
    *
-   * Use this function to run an Effect as your application's main program, especially
+   * Use to run an Effect as your application's main program, especially
    * when you need structured error handling, log management, interrupt support,
    * or advanced teardown capabilities.
    *
@@ -79,7 +93,7 @@ export const runMain: {
    *
    * **When to use**
    *
-   * Use this function to run an Effect as your application's main program, especially
+   * Use to run an Effect as your application's main program, especially
    * when you need structured error handling, log management, interrupt support,
    * or advanced teardown capabilities.
    *

package/src/NodeServices.ts

@@ -1,20 +1,35 @@
 /**
- * Provides the aggregate Node platform services layer for applications that run
- * on the Node.js runtime.
- *
- * This module is useful when an application needs the standard Node-backed
- * implementations of filesystem access, path operations, stdio, terminal
- * interaction, and child process spawning from a single layer. Provide
- * `NodeServices.layer` near the edge of a program to satisfy effects that read
- * or write files, resolve paths, interact with stdin/stdout/stderr or a
- * terminal, or launch subprocesses.
- *
- * The layer only supplies the runtime services listed by `NodeServices`; it does
- * not provide unrelated platform services such as HTTP clients or servers.
- * Libraries should continue to depend on the individual service tags they use,
- * while applications, CLIs, and tests can choose this layer or narrower
- * service-specific layers depending on how much of the Node runtime they want to
- * expose.
+ * Standard Node.js service bundle for Effect applications.
+ *
+ * `NodeServices.layer` provides the Node implementations of the core services
+ * most command-line programs and server entrypoints need: child process
+ * spawning, cryptography, filesystem access, path operations, stdio, terminal
+ * interaction, and related process I/O.
+ *
+ * **Mental model**
+ *
+ * Application code should depend on the individual Effect service tags it uses,
+ * such as `FileSystem`, `Path`, or `Stdio`. This module is the composition
+ * point for a Node runtime: provide the aggregate layer once near the program
+ * boundary, and those service requirements are satisfied by Node-backed
+ * implementations.
+ *
+ * **Common tasks**
+ *
+ * - Install the default Node platform services for a CLI, script, or process
+ *   entrypoint with {@link layer}
+ * - Use narrower modules such as `NodeFileSystem`, `NodePath`, or `NodeStdio`
+ *   when a test or embedded runtime should expose only one service
+ * - Keep libraries platform-independent by requiring service tags instead of
+ *   importing this module directly
+ *
+ * **Gotchas**
+ *
+ * This is not every Node integration in `@effect/platform-node`. HTTP clients,
+ * HTTP servers, sockets, workers, Redis, and other specialized integrations
+ * still have their own modules and layers. Providing this layer also means
+ * effects can reach real process resources such as the filesystem, stdio,
+ * terminal handles, and child processes.
  *
  * @since 4.0.0
  */

package/src/NodeSocket.ts

@@ -1,20 +1,35 @@
 /**
- * Node platform socket entry point for Effect sockets backed by Node streams
- * and WebSocket implementations.
+ * Node.js socket constructors and layers for Effect sockets.
  *
- * This module re-exports the shared Node socket constructors for TCP clients,
- * Unix domain socket clients, and adapters from existing Node `Duplex` streams,
- * then adds Node-specific WebSocket constructor layers. Use it when connecting
- * to raw socket protocols, wiring RPC transports over TCP or Unix sockets, or
- * opening WebSocket clients in Node.
+ * This module combines shared Node stream-backed socket support with
+ * Node-specific WebSocket constructor layers. Use it to open TCP clients, Unix
+ * domain socket clients, adapt existing Node `Duplex` streams, or provide
+ * WebSocket clients to protocols built on Effect's `Socket.Socket`.
  *
- * TCP and Unix socket behavior comes from the shared Node layer: Unix sockets
- * are selected with `NetConnectOpts.path`, scoped sockets close or destroy the
- * underlying stream on finalization, and Node open, read, write, and close
- * events are translated into `SocketError` values. For WebSockets,
- * `layerWebSocketConstructor` prefers `globalThis.WebSocket` when available
- * and falls back to `ws`; use `layerWebSocketConstructorWS` when you need the
- * `ws` implementation consistently across Node versions.
+ * **Mental model**
+ *
+ * TCP and Unix sockets come from `node:net` and are exposed as scoped
+ * `Socket.Socket` values. Stream open, read, write, and close events are
+ * translated to `SocketError` values, and finalization closes or destroys the
+ * underlying stream. WebSocket layers provide only the constructor service used
+ * by `Socket.makeWebSocket`; `layerWebSocket` combines that constructor with a
+ * URL to provide a socket layer.
+ *
+ * **Common tasks**
+ *
+ * - Use `makeNet`, `makeNetChannel`, or `layerNet` for TCP connections.
+ * - Set `NetConnectOpts.path` for Unix domain sockets.
+ * - Use `fromDuplex` when another library already owns a Node `Duplex`.
+ * - Use `layerWebSocketConstructor` for the native WebSocket when present, with
+ *   fallback to `ws`; use `layerWebSocketConstructorWS` to force `ws`.
+ *
+ * **Gotchas**
+ *
+ * Socket lifetime is scoped, so release the layer or scope to close the
+ * connection. Writes complete when Node accepts or flushes the chunk, not when
+ * a peer processes it. Remote `end` events complete the socket run, while
+ * abnormal closes, open timeouts, and stream errors surface through
+ * `SocketError`; handle them in the Effect that runs the socket.
  *
  * @since 4.0.0
  */

package/src/NodeStdio.ts

@@ -1,19 +1,27 @@
 /**
- * Node.js implementation of the Effect `Stdio` service.
+ * Node.js `Stdio` layer for the current process.
  *
- * This module exposes a layer that connects `Stdio` to the current process:
- * command-line arguments come from `process.argv`, input is read from
- * `process.stdin`, and output and error output write to `process.stdout` and
- * `process.stderr`. It is intended for CLIs, scripts, command runners, and
- * other process-oriented programs that need standard input and output through
- * Effect services.
+ * The exported layer satisfies the platform-independent `Stdio` service by
+ * reading command-line arguments from `process.argv`, consuming input from
+ * `process.stdin`, and writing output streams to `process.stdout` and
+ * `process.stderr`. It is the stdio bridge used by CLIs, scripts, command
+ * runners, and tests that intentionally communicate through the host process.
  *
- * The underlying streams are owned by the Node process. The layer keeps stdin
- * open and does not end stdout or stderr when a stream finishes, which avoids
- * closing global process handles that other code may still use. Be mindful that
- * stdio may be a pipe, file, or TTY, so terminal-specific behavior such as raw
- * mode, echo, colors, and cursor control should be handled with the terminal
- * APIs instead of assuming an interactive console.
+ * **Mental model**
+ *
+ * Effects should depend on `Stdio`; this module decides that the backing
+ * streams are the global Node process handles. Provide `NodeStdio.layer` when a
+ * program only needs standard input and output, or `NodeServices.layer` when the
+ * same entrypoint also needs the other default Node services.
+ *
+ * **Gotchas**
+ *
+ * The process stdio streams are shared resources. The layer leaves stdin open
+ * and does not end stdout or stderr by default, avoiding accidental closure of
+ * handles that other code in the same process may still use. Stdio might be a
+ * pipe, file, or TTY; terminal-specific behavior such as raw mode, echo, color
+ * detection, and cursor movement belongs with terminal APIs rather than this
+ * service.
  *
  * @since 4.0.0
  */

package/src/NodeTerminal.ts

@@ -1,13 +1,23 @@
 /**
- * Provides the Node.js `Terminal` service for interactive command-line
- * programs, prompts, and tools that need to read lines, react to key presses,
- * write to stdout, or inspect terminal dimensions.
- *
- * The implementation is backed by the current process' stdin and stdout. When
- * stdin is a TTY, key input temporarily enables raw mode for the scope of the
- * service, so callers should acquire it with a scope or use the provided layer
- * to ensure terminal state is restored. In non-TTY environments, terminal
+ * Node.js implementation of the Effect `Terminal` service.
+ *
+ * `NodeTerminal` connects `Terminal` to the current process' stdin and stdout
+ * so Node programs can read lines, stream key presses, write display output,
+ * and inspect terminal dimensions through the Effect service environment.
+ *
+ * **Mental model**
+ *
+ * `make` acquires a scoped terminal backed by process streams, and `layer`
+ * provides that service with the default key sequence for quitting input. When
+ * stdin is a TTY, low-level key input temporarily enables raw mode for the
+ * lifetime of the scope; finalization restores the previous terminal state.
+ *
+ * **Gotchas**
+ *
+ * In non-TTY environments such as CI, pipes, or redirected input, terminal
  * dimensions may be reported as zero and raw-mode key handling is unavailable.
+ * For plain stdin/stdout byte streams, use the standard I/O service instead of
+ * the interactive terminal service.
  *
  * @since 4.0.0
  */

package/src/NodeWorker.ts

@@ -1,21 +1,35 @@
 /**
  * Parent-side Node.js support for Effect workers.
  *
- * This module provides the `WorkerPlatform` used by Node programs that spawn
- * and communicate with `node:worker_threads` workers or IPC-enabled child
- * processes through Effect's worker protocol. Pair it with `NodeWorkerRunner`
- * in the worker entrypoint when building worker-backed RPC clients, offloading
- * CPU-bound work, isolating Node resources, or hosting services that should
- * exchange typed messages with the parent process.
+ * This module installs the `WorkerPlatform` used by a Node program that owns
+ * workers. It supports both `node:worker_threads` workers and IPC-enabled child
+ * processes, routing messages through Effect's worker protocol so higher-level
+ * worker clients can treat either runtime as the same parent-side transport.
  *
- * Worker-thread spawners can use `postMessage` transfer lists for values such
- * as `ArrayBuffer` and `MessagePort`, but transferring moves ownership and
- * invalid transfer lists surface as worker send or receive failures.
- * Child-process spawners must provide an IPC channel, for example via
- * `child_process.fork` or `stdio: "ipc"`; their messages use Node IPC
- * serialization and this module does not forward transfer lists to
- * `ChildProcess.send`. Scope finalization sends the worker close signal and
- * waits for exit before falling back to `terminate()` or `SIGKILL`.
+ * **Mental model**
+ *
+ * `NodeWorker` runs in the parent process. The worker entrypoint should install
+ * `NodeWorkerRunner`, which receives parent messages, runs the registered
+ * Effect handler, and sends replies back over the same channel. Use `layer`
+ * when you want this module to provide both the platform and a `Worker.Spawner`;
+ * use `layerPlatform` when the spawner is provided elsewhere.
+ *
+ * **Common tasks**
+ *
+ * - Spawn CPU-bound or resource-isolated work in `worker_threads`.
+ * - Spawn a child process that was created with an IPC channel.
+ * - Share one parent-side worker implementation across both Node transports.
+ *
+ * **Gotchas**
+ *
+ * Worker-thread spawners can use `postMessage` transfer lists for values such as
+ * `ArrayBuffer` and `MessagePort`; transferring moves ownership, and invalid
+ * transfer lists surface as send or receive failures. Child-process spawners
+ * must provide an IPC channel, for example via `child_process.fork` or
+ * `stdio: "ipc"`; their messages use Node IPC serialization and transfer lists
+ * are not forwarded to `ChildProcess.send`. Scope finalization sends the worker
+ * close signal and waits for exit before falling back to `terminate()` or
+ * `SIGKILL`.
  *
  * @since 4.0.0
  */

package/src/NodeWorkerRunner.ts

@@ -1,21 +1,41 @@
 /**
- * Runtime support for Effect workers that are executed by Node.js.
+ * Node.js runtime support for workers that serve Effect worker requests.
  *
- * This module is intended to be installed in the program running inside a
- * `node:worker_threads` worker or an IPC-enabled child process. It provides the
- * `WorkerRunnerPlatform` used by `WorkerRunner` to receive request messages
- * from the parent, run the registered Effect handler, and send responses back
- * over the parent channel.
+ * `NodeWorkerRunner` supplies the Node implementation of the Effect worker
+ * runner platform. Install {@link layer} inside code that is already running in
+ * a `node:worker_threads` worker or in a child process with an IPC channel. The
+ * layer listens for parent messages, runs handlers registered through
+ * `WorkerRunner`, and replies over the same parent channel.
  *
- * Use it when the parent side is created with `NodeWorker` and the worker code
- * needs to perform CPU-bound work, isolate Node resources, or host services that
- * should communicate through the Effect worker protocol. The runner must be
- * started from an actual worker context: `parentPort` is required for worker
- * threads, while child processes must be spawned with an IPC channel so
- * `process.send` is available. Transfer lists only apply to worker-thread
- * `postMessage`; child-process messages go through Node IPC serialization.
- * Shutdown is coordinated by the parent message protocol, so long-running
- * handlers should remain interruptible and keep resource cleanup in scopes.
+ * **Mental model**
+ *
+ * - The parent process creates a worker with the Node worker APIs.
+ * - The worker process provides this module's {@link layer} to its runner program.
+ * - Startup sends a ready message to the parent, then request messages are
+ *   dispatched to the registered Effect handler.
+ * - Responses are sent with Node `postMessage` for worker threads or
+ *   `process.send` for child processes.
+ * - Shutdown is initiated by the parent protocol and closes or unreferences the
+ *   parent channel.
+ *
+ * **Common tasks**
+ *
+ * - Provide {@link layer} in the worker entrypoint before running `WorkerRunner`.
+ * - Host CPU-bound work or isolated Node resources behind the Effect worker protocol.
+ * - Return transferable values when using `worker_threads`.
+ *
+ * **Gotchas**
+ *
+ * - The runner must start inside an actual worker context; otherwise the layer
+ *   fails because neither `parentPort` nor `process.send` is available.
+ * - Transfer lists only apply to `worker_threads`; child-process IPC uses Node
+ *   serialization.
+ * - Long-running handlers should remain interruptible and keep cleanup in
+ *   scopes so parent-driven shutdown can release resources.
+ *
+ * **See also**
+ *
+ * - {@link layer} for the Node worker runner platform.
  *
  * @since 4.0.0
  */

package/src/Undici.ts

@@ -1,4 +1,17 @@
 /**
+ * Re-export of the Undici HTTP client package used by the Node platform.
+ *
+ * This module gives Effect applications a package-local import for Undici
+ * primitives while working with `@effect/platform-node`. Import named Undici
+ * APIs from here when configuring Node HTTP client dispatchers, creating agents
+ * or mock agents, setting the process-global dispatcher, or sharing the same
+ * Undici types with integrations that use the platform HTTP client.
+ *
+ * The module does not wrap or reinterpret Undici behavior. It forwards the
+ * installed `undici` named exports and default export, so connection pooling,
+ * dispatcher lifetimes, mocking, aborts, and request options follow Undici's
+ * own semantics.
+ *
  * @since 4.0.0
  */
 import Undici from "undici"