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

package/src/NodeHttpServerRequest.ts

@@ -1,18 +1,44 @@
 /**
- * @since 1.0.0
+ * Accessors for the Node.js objects backing a platform Node
+ * `HttpServerRequest`.
+ *
+ * Use this module at interop boundaries when an Effect HTTP handler needs the
+ * original `http.IncomingMessage` or `http.ServerResponse` for APIs that are
+ * specific to Node, such as existing middleware, socket inspection, raw stream
+ * piping, or response customization that cannot be expressed with the portable
+ * `HttpServerRequest` and `HttpServerResponse` interfaces.
+ *
+ * The returned request is the original Node request supplied to the server. It
+ * does not reflect Effect request overrides made by middleware, such as a
+ * rewritten URL, adjusted headers, or a substituted remote address. Its body is
+ * also Node's one-shot readable stream, so avoid mixing raw stream consumption
+ * with Effect body, multipart, or stream helpers unless ownership of the body
+ * is clear. The returned response is the Node response owned by the platform
+ * server; writing to it directly bypasses the usual Effect response writer and
+ * must be coordinated carefully to avoid duplicate writes. Upgrade requests may
+ * create that response lazily when it is first requested.
+ *
+ * @since 4.0.0
  */
 import type { HttpServerRequest } from "effect/unstable/http/HttpServerRequest"
 import type * as Http from "node:http"
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node `IncomingMessage` for a platform Node
+ * `HttpServerRequest`.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const toIncomingMessage = (self: HttpServerRequest): Http.IncomingMessage => self.source as any
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node `ServerResponse` for a platform Node
+ * `HttpServerRequest`, evaluating the stored response thunk when the response
+ * was created lazily.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const toServerResponse = (self: HttpServerRequest): Http.ServerResponse => {
   const res = (self as any).response

package/src/NodeMultipart.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Node-specific helpers for parsing 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.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import type * as FileSystem from "effect/FileSystem"
@@ -16,8 +33,12 @@ import * as NodeStreamP from "node:stream/promises"
 import * as NodeStream from "./NodeStream.ts"
 
 /**
- * @since 1.0.0
+ * Parses multipart data from a Node readable request body and headers into a
+ * stream of `Multipart.Part` values, converting parser failures to
+ * `MultipartError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const stream = (
   source: Readable,
@@ -39,8 +60,11 @@ export const stream = (
   )
 
 /**
- * @since 1.0.0
+ * Parses multipart data from a Node readable request body and persists file
+ * parts using the current `FileSystem`, `Path`, and `Scope` services.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const persisted = (
   source: Readable,
@@ -57,7 +81,10 @@ export const persisted = (
     }))
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node readable stream for a multipart file produced by
+ * the Node multipart parser.
+ *
+ * @since 4.0.0
  */
 export const fileToReadable = (file: Multipart.File): Readable => (file as FileImpl).file
 

package/src/NodePath.ts

@@ -1,24 +1,47 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as NodePath from "@effect/platform-node-shared/NodePath"
 import type * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
 
 /**
- * @since 1.0.0
+ * Provides the default Node `Path` service using the platform's `node:path`
+ * implementation.
+ *
  * @category layer
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = NodePath.layer
 
 /**
- * @since 1.0.0
+ * Provides the `Path` service using Node's POSIX path implementation,
+ * regardless of the host platform.
+ *
  * @category layer
+ * @since 4.0.0
  */
 export const layerPosix: Layer.Layer<Path> = NodePath.layerPosix
 
 /**
- * @since 1.0.0
+ * Provides the `Path` service using Node's Windows path implementation,
+ * regardless of the host platform.
+ *
  * @category layer
+ * @since 4.0.0
  */
 export const layerWin32: Layer.Layer<Path> = NodePath.layerWin32

package/src/NodeRedis.ts

@@ -1,5 +1,24 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Config from "effect/Config"
 import * as Context from "effect/Context"
@@ -11,8 +30,12 @@ import * as Redis from "effect/unstable/persistence/Redis"
 import * as IoRedis from "ioredis"
 
 /**
- * @since 1.0.0
+ * Service tag for the Node Redis integration, exposing the underlying
+ * `ioredis` client and a `use` helper that maps client failures to
+ * `RedisError`.
+ *
  * @category Service
+ * @since 4.0.0
  */
 export class NodeRedis extends Context.Service<NodeRedis, {
   readonly client: IoRedis.Redis
@@ -51,16 +74,22 @@ const make = Effect.fnUntraced(function*(
 })
 
 /**
- * @since 1.0.0
+ * Provides `Redis` and `NodeRedis` services backed by an `ioredis` client
+ * created with the supplied options and closed when the layer scope ends.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer = (
   options?: IoRedis.RedisOptions | undefined
 ): Layer.Layer<Redis.Redis | NodeRedis> => Layer.effectContext(make(options))
 
 /**
- * @since 1.0.0
+ * Provides `Redis` and `NodeRedis` services from `Config`-backed ioredis
+ * options, closing the client when the layer scope ends.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerConfig: (
   options: Config.Wrap<IoRedis.RedisOptions>

package/src/NodeRuntime.ts

@@ -1,5 +1,19 @@
 /**
- * @since 1.0.0
+ * Node.js entry-point helpers for running Effect programs.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * @since 4.0.0
  */
 import * as NodeRuntime from "@effect/platform-node-shared/NodeRuntime"
 import type { Effect } from "effect/Effect"
@@ -28,8 +42,8 @@ import type * as Runtime from "effect/Runtime"
  * when you need structured error handling, log management, interrupt support,
  * or advanced teardown capabilities.
  *
- * @since 1.0.0
  * @category Run main
+ * @since 4.0.0
  */
 export const runMain: {
   /**
@@ -55,8 +69,8 @@ export const runMain: {
    * when you need structured error handling, log management, interrupt support,
    * or advanced teardown capabilities.
    *
-   * @since 1.0.0
    * @category Run main
+   * @since 4.0.0
    */
   (
     options?: {
@@ -87,8 +101,8 @@ export const runMain: {
    * when you need structured error handling, log management, interrupt support,
    * or advanced teardown capabilities.
    *
-   * @since 1.0.0
    * @category Run main
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect<A, E>,

package/src/NodeServices.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import type { FileSystem } from "effect/FileSystem"
 import * as Layer from "effect/Layer"
@@ -14,14 +31,20 @@ import * as NodeStdio from "./NodeStdio.ts"
 import * as NodeTerminal from "./NodeTerminal.ts"
 
 /**
- * @since 1.0.0
+ * The union of core services provided by the Node platform layer, including
+ * child process spawning, filesystem, path, stdio, and terminal services.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type NodeServices = ChildProcessSpawner | FileSystem | Path | Stdio | Terminal
 
 /**
- * @since 1.0.0
+ * Provides the default Node implementations for child process spawning,
+ * filesystem, path, stdio, and terminal services.
+ *
  * @category layer
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<NodeServices> = Layer.provideMerge(
   NodeChildProcessSpawner.layer,

package/src/NodeSink.ts

@@ -1,8 +1,8 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSink"

package/src/NodeSocket.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Node platform socket entry point for Effect sockets backed by Node streams
+ * and WebSocket implementations.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import { NodeWS as WS } from "@effect/platform-node-shared/NodeSocket"
 import type * as Duration from "effect/Duration"
@@ -9,13 +26,16 @@ import * as Layer from "effect/Layer"
 import * as Socket from "effect/unstable/socket/Socket"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSocket"
 
 /**
- * @since 1.0.0
+ * Provides a `Socket.WebSocketConstructor`, using `globalThis.WebSocket` when
+ * available and falling back to the `ws` package otherwise.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocketConstructor: Layer.Layer<
   Socket.WebSocketConstructor
@@ -27,8 +47,11 @@ export const layerWebSocketConstructor: Layer.Layer<
 })
 
 /**
- * @since 1.0.0
+ * Provides a `Socket.WebSocketConstructor` backed explicitly by the `ws`
+ * package.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocketConstructorWS: Layer.Layer<
   Socket.WebSocketConstructor
@@ -37,8 +60,12 @@ export const layerWebSocketConstructorWS: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
+ * Creates a `Socket.Socket` layer for a WebSocket URL using the Node WebSocket
+ * constructor layer, honoring protocol, open-timeout, and close-code error
+ * options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket: (
   url: string | Effect.Effect<string>,

package/src/NodeSocketServer.ts

@@ -1,8 +1,8 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSocketServer"

package/src/NodeStdio.ts

@@ -1,12 +1,31 @@
 /**
- * @since 1.0.0
+ * Node.js implementation of the Effect `Stdio` service.
+ *
+ * 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 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.
+ *
+ * @since 4.0.0
  */
 import * as NodeStdio from "@effect/platform-node-shared/NodeStdio"
 import type * as Layer from "effect/Layer"
 import type { Stdio } from "effect/Stdio"
 
 /**
- * @since 1.0.0
+ * Provides the `Stdio` service backed by the current process arguments,
+ * stdin, stdout, and stderr streams.
+ *
  * @category layer
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Stdio> = NodeStdio.layer

package/src/NodeStream.ts

@@ -1,8 +1,8 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeStream"

package/src/NodeTerminal.ts

@@ -1,5 +1,15 @@
 /**
- * @since 1.0.0
+ * 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
+ * dimensions may be reported as zero and raw-mode key handling is unavailable.
+ *
+ * @since 4.0.0
  */
 import * as NodeTerminal from "@effect/platform-node-shared/NodeTerminal"
 import type { Effect } from "effect/Effect"
@@ -8,13 +18,19 @@ import type { Scope } from "effect/Scope"
 import type { Terminal, UserInput } from "effect/Terminal"
 
 /**
- * @since 1.0.0
+ * Creates a scoped `Terminal` service backed by process stdin/stdout, using the
+ * optional predicate to decide when key input should end the input stream.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (shouldQuit?: (input: UserInput) => boolean) => Effect<Terminal, never, Scope> = NodeTerminal.make
 
 /**
- * @since 1.0.0
+ * Provides the default process-backed `Terminal` service, ending key input on
+ * the default quit keys.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer<Terminal> = NodeTerminal.layer

package/src/NodeWorker.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * 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`.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -12,8 +30,12 @@ import type * as ChildProcess from "node:child_process"
 import type * as WorkerThreads from "node:worker_threads"
 
 /**
- * @since 1.0.0
+ * Provides the Node `WorkerPlatform` for `worker_threads` workers and child
+ * process workers, wiring messages, errors, and exits into Effect workers and
+ * terminating the worker if graceful shutdown times out.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(Worker.WorkerPlatform)(
   Worker.makePlatform<WorkerThreads.Worker | ChildProcess.ChildProcess>()({
@@ -93,8 +115,11 @@ export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(W
 )
 
 /**
- * @since 1.0.0
+ * Provides the Node `WorkerPlatform` together with a `Worker.Spawner` created
+ * from the supplied worker or child-process spawning function.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   spawn: (id: number) => WorkerThreads.Worker | ChildProcess.ChildProcess

package/src/NodeWorkerRunner.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Runtime support for Effect workers that are executed by Node.js.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -12,8 +30,12 @@ import * as WorkerRunner from "effect/unstable/workers/WorkerRunner"
 import * as WorkerThreads from "node:worker_threads"
 
 /**
- * @since 1.0.0
+ * Provides the `WorkerRunnerPlatform` for code running inside a Node worker
+ * thread or child process, routing parent messages to the registered handler
+ * and sending responses back through the parent channel.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succeed(WorkerRunner.WorkerRunnerPlatform)({
   start<O = unknown, I = unknown>() {

package/src/Undici.ts

@@ -1,16 +1,16 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 import Undici from "undici"
 
 /**
- * @since 1.0.0
  * @category undici
+ * @since 4.0.0
  */
 export * from "undici"
 
 /**
- * @since 1.0.0
  * @category undici
+ * @since 4.0.0
  */
 export default Undici