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

package/dist/index.js

@@ -7,333 +7,62 @@
  */
 export * as Mime from "./Mime.js";
 /**
- * Node.js implementation of `ChildProcessSpawner`.
- *
  * @since 4.0.0
  */
 export * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.js";
 /**
- * The `NodeClusterHttp` module provides the Node.js HTTP and WebSocket
- * transports for Effect Cluster runners. It wires `HttpRunner` to the Node HTTP
- * server, supplies Undici and WebSocket client protocols, and builds a complete
- * sharding layer with serialization, runner health, runner storage, and message
- * storage.
- *
- * **Common tasks**
- *
- * - Run a Node process as a cluster runner over HTTP or WebSocket with
- *   {@link layer}
- * - Connect a client-only process to an existing HTTP cluster without starting
- *   a runner server
- * - Use SQL-backed storage for durable multi-process clusters, `local` storage
- *   for short-lived development, or `byo` storage when the deployment owns the
- *   persistence boundary
- * - Check runner health with protocol pings or Kubernetes pod readiness through
- *   {@link layerK8sHttpClient}
- *
- * **Gotchas**
- *
- * - `runnerAddress` is the host and port advertised to other runners; set
- *   `runnerListenAddress` when the local bind address differs from the
- *   externally reachable address
- * - The HTTP and WebSocket transports serve runner RPCs at the default
- *   `HttpRunner` route, so proxies and load balancers must preserve the path
- *   and allow WebSocket upgrades when `transport` is `"websocket"`
- * - `clientOnly` does not start an HTTP server or receive shard assignments
- * - SQL storage is the default; `local` storage is in-memory/noop and `byo`
- *   requires the surrounding application to provide both runner and message
- *   storage services
- * - Ping health checks use the selected transport and serialization, so route,
- *   port, proxy, or codec mismatches can make a runner appear unhealthy
- *
  * @since 4.0.0
  */
 export * as NodeClusterHttp from "./NodeClusterHttp.js";
 /**
- * The `NodeClusterSocket` module provides the Node.js socket transport for
- * Effect Cluster runners. It wires `SocketRunner` to Node TCP sockets, supplies
- * RPC client and server protocol layers, and builds a complete sharding layer
- * with serialization, runner health, runner storage, and message storage.
- *
- * **Common tasks**
- *
- * - Run a Node process as a cluster runner over raw TCP sockets with
- *   {@link layer}
- * - Connect a client-only process to an existing socket cluster without
- *   starting a runner server
- * - Use SQL-backed storage for durable multi-process clusters, `local` storage
- *   for short-lived development, or `byo` storage when the deployment owns the
- *   persistence boundary
- * - Check runner health with socket pings or Kubernetes pod readiness through
- *   {@link layerK8sHttpClient}
- *
- * **Gotchas**
- *
- * - `runnerAddress` is the host and port advertised to other runners; set
- *   `runnerListenAddress` when the local bind address differs from the
- *   externally reachable address
- * - The socket transport is point-to-point RPC, not cluster gossip: runner
- *   membership, shard ownership, and persisted delivery are coordinated through
- *   `RunnerStorage`, `MessageStorage`, and `RunnerHealth`
- * - `clientOnly` does not start a socket server or receive shard assignments
- * - Ping health checks use the same socket protocol, so unreachable ports,
- *   firewalls, or serialization mismatches can make a runner appear unhealthy
- *
  * @since 4.0.0
  */
 export * as NodeClusterSocket from "./NodeClusterSocket.js";
 /**
- * Node.js platform Crypto service layer.
- *
  * @since 1.0.0
  */
 export * as NodeCrypto from "./NodeCrypto.js";
 /**
- * Provides the Node.js `FileSystem` layer for Effect programs.
- *
- * Use this module when a Node application, CLI, script, or test needs to
- * satisfy the `FileSystem` service with real filesystem access for reading and
- * writing files, creating directories and temporary files, inspecting metadata,
- * managing links, or watching paths for changes.
- *
- * This module only exposes the Node-backed layer; filesystem operations are
- * accessed through the `FileSystem` service from `effect/FileSystem`. Provide
- * `NodeFileSystem.layer` at the edge of the program, or use
- * `NodeServices.layer` when you also want the standard Node path, stdio,
- * terminal, and child process services. The implementation is shared with
- * other Node-compatible platform packages, so optional services such as
- * `FileSystem.WatchBackend` are honored when present; otherwise file watching
- * follows Node's `node:fs.watch` behavior. Paths are interpreted by Node, so
- * relative paths use the current working directory and platform path rules.
- *
  * @since 4.0.0
  */
 export * as NodeFileSystem from "./NodeFileSystem.js";
 /**
- * Node.js implementations of the Effect `HttpClient`.
- *
- * This module provides the Node-specific layers and constructors for sending
- * Effect HTTP client requests. It re-exports the fetch-based client for
- * programs that want to use `globalThis.fetch`, provides an Undici-backed
- * client for applications that need Undici dispatcher control, and provides a
- * lower-level `node:http` / `node:https` client for integrations that need
- * native Node agent configuration.
- *
- * Use these clients in server-side applications, CLIs, tests, and integrations
- * where requests should participate in Effect resource management, interruption,
- * streaming, and typed transport / decode errors. The Undici path sends each
- * request through the current `Dispatcher`; `layerUndici` owns a scoped
- * `Agent`, while `dispatcherLayerGlobal` uses Undici's process-global dispatcher
- * without destroying it. The `node:http` path uses separate scoped HTTP and
- * HTTPS agents, making it the right choice when native agent options such as
- * TLS, proxy, keep-alive, or socket behavior need to be configured directly.
- *
- * The backends are not completely interchangeable. Fetch, Undici, and
- * `node:http` expose different agent and dispatcher hooks, body implementations,
- * abort behavior, upgrade support, and response body readers. This module
- * converts Effect request bodies to the selected runtime representation:
- * streams remain streaming, `FormData` may contribute generated content headers,
- * and body read failures are reported as `HttpClientError` decode or transport
- * errors.
- *
  * @since 4.0.0
  */
 export * as NodeHttpClient from "./NodeHttpClient.js";
 /**
- * Utilities for adapting Node `http.IncomingMessage` values to the Effect HTTP
- * incoming message interface used by the platform Node server and client
- * implementations.
- *
- * This module is useful when code needs to keep access to Node's request or
- * response object while also exposing Effect's typed headers, remote address,
- * body decoders, and stream interface. The body helpers consume Node's readable
- * stream, cache decoded text and array-buffer results, and honor the
- * `HttpIncomingMessage.MaxBodySize` fiber ref. Prefer a single body access
- * strategy per message: raw `stream` access is not cached, and Node request
- * bodies cannot be replayed once the underlying stream has been consumed.
- *
  * @since 4.0.0
  */
 export * as NodeHttpIncomingMessage from "./NodeHttpIncomingMessage.js";
 /**
- * Node.js implementation of the Effect HTTP platform service.
- *
- * This module connects the portable `HttpPlatform` file response helpers to
- * Node runtime primitives. It is used by Node HTTP servers and static file
- * handlers when returning local files, public assets, downloads, byte ranges,
- * or Web `File` values as `HttpServerResponse` bodies.
- *
- * Path-based responses are served with `node:fs.createReadStream`; Web `File`
- * responses are bridged with `Readable.fromWeb`. The implementation fills in
- * `content-type` from `Mime`, falls back to `application/octet-stream`, and
- * writes the `content-length` for the selected range or whole file. Node's
- * stream `end` option is inclusive, so the platform converts Effect's half-open
- * range before reading. Empty bodies use an empty readable stream.
- *
- * Provide `layer` at the Node runtime edge when file responses, static serving,
- * or response bodies created from files need real filesystem and ETag support.
- * These responses are raw Node streams, so they are intended for the Node HTTP
- * server adapter; keep files available until the response body has been
- * consumed and prefer the portable `HttpServerResponse` constructors when a
- * response does not depend on Node file or stream behavior.
- *
  * @since 4.0.0
  */
 export * as NodeHttpPlatform from "./NodeHttpPlatform.js";
 /**
- * Node.js implementation of the Effect `HttpServer`.
- *
- * This module adapts a supplied Node `http.Server` into Effect's
- * platform-independent HTTP server service. It starts the server with Node
- * `listen` options, converts `request` events into `HttpServerRequest` values,
- * writes `HttpServerResponse` bodies through Node's `ServerResponse`, and
- * handles `upgrade` events by exposing the upgraded socket through
- * `HttpServerRequest.upgrade`.
- *
- * Common use cases include serving an Effect HTTP application with {@link layer}
- * or {@link layerConfig}, embedding request or upgrade handlers into an
- * existing Node server with {@link makeHandler} and {@link makeUpgradeHandler},
- * and using {@link layerTest} for integration tests that need an ephemeral
- * listening port and a client pointed at it.
- *
- * Listen options are passed directly to Node, so host, port, backlog, and Unix
- * socket path behavior follow `node:http`. The server begins listening when the
- * `HttpServer` is acquired, and handlers are installed when `serve` is run.
- * Request fibers are interrupted with `ClientAbort` when the client disconnects
- * before a response finishes. WebSocket support only applies to Node `upgrade`
- * requests, and ordinary HTTP requests fail if their application attempts to use
- * `HttpServerRequest.upgrade`.
- *
- * Scope ownership is important: the server is closed when the acquiring scope
- * finalizes, while each `serve` call installs its own request and upgrade
- * listeners and removes them on finalization. Unless preemptive shutdown is
- * disabled, finalizing a serve scope also starts a graceful server close, using
- * the configured timeout or the default timeout.
- *
  * @since 4.0.0
  */
 export * as NodeHttpServer from "./NodeHttpServer.js";
 /**
- * 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
  */
 export * as NodeHttpServerRequest from "./NodeHttpServerRequest.js";
 /**
- * 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
  */
 export * as NodeMultipart from "./NodeMultipart.js";
 /**
- * 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
  */
 export * as NodePath from "./NodePath.js";
 /**
- * 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
  */
 export * as NodeRedis from "./NodeRedis.js";
 /**
- * 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
  */
 export * as NodeRuntime from "./NodeRuntime.js";
 /**
- * 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
  */
 export * as NodeServices from "./NodeServices.js";
@@ -342,23 +71,6 @@ export * as NodeServices from "./NodeServices.js";
  */
 export * as NodeSink from "./NodeSink.js";
 /**
- * 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
  */
 export * as NodeSocket from "./NodeSocket.js";
@@ -367,22 +79,6 @@ export * as NodeSocket from "./NodeSocket.js";
  */
 export * as NodeSocketServer from "./NodeSocketServer.js";
 /**
- * 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
  */
 export * as NodeStdio from "./NodeStdio.js";
@@ -391,60 +87,14 @@ export * as NodeStdio from "./NodeStdio.js";
  */
 export * as NodeStream from "./NodeStream.js";
 /**
- * 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
  */
 export * as NodeTerminal from "./NodeTerminal.js";
 /**
- * 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
  */
 export * as NodeWorker from "./NodeWorker.js";
 /**
- * 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
  */
 export * as NodeWorkerRunner from "./NodeWorkerRunner.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Mime","NodeChildProcessSpawner","NodeClusterHttp","NodeClusterSocket","NodeCrypto","NodeFileSystem","NodeHttpClient","NodeHttpIncomingMessage","NodeHttpPlatform","NodeHttpServer","NodeHttpServerRequest","NodeMultipart","NodePath","NodeRedis","NodeRuntime","NodeServices","NodeSink","NodeSocket","NodeSocketServer","NodeStdio","NodeStream","NodeTerminal","NodeWorker","NodeWorkerRunner","Undici"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,IAAI,MAAM,WAAW;AAEjC;;;;;AAKA,OAAO,KAAKC,uBAAuB,MAAM,8BAA8B;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAE3D;;;;;AAKA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;;;;;;;;;;;;;AAeA,OAAO,KAAKC,uBAAuB,MAAM,8BAA8B;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,KAAKC,qBAAqB,MAAM,4BAA4B;AAEnE;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;;;;;;;;;;;;;;;AAiBA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;AAiBA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;;;;;;;;;;;AAaA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,MAAM,MAAM,aAAa","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Mime","NodeChildProcessSpawner","NodeClusterHttp","NodeClusterSocket","NodeCrypto","NodeFileSystem","NodeHttpClient","NodeHttpIncomingMessage","NodeHttpPlatform","NodeHttpServer","NodeHttpServerRequest","NodeMultipart","NodePath","NodeRedis","NodeRuntime","NodeServices","NodeSink","NodeSocket","NodeSocketServer","NodeStdio","NodeStream","NodeTerminal","NodeWorker","NodeWorkerRunner","Undici"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,IAAI,MAAM,WAAW;AAEjC;;;AAGA,OAAO,KAAKC,uBAAuB,MAAM,8BAA8B;AAEvE;;;AAGA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;AAGA,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAE3D;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,uBAAuB,MAAM,8BAA8B;AAEvE;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,qBAAqB,MAAM,4BAA4B;AAEnE;;;AAGA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,MAAM,MAAM,aAAa","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/platform-node",
   "type": "module",
-  "version": "4.0.0-beta.70",
+  "version": "4.0.0-beta.71",
   "license": "MIT",
   "description": "Platform specific implementations for the Node.js runtime",
   "homepage": "https://effect.website",
@@ -50,18 +50,18 @@
   "dependencies": {
     "mime": "^4.1.0",
     "undici": "^8.2.0",
-    "@effect/platform-node-shared": "^4.0.0-beta.70"
+    "@effect/platform-node-shared": "^4.0.0-beta.71"
   },
   "peerDependencies": {
     "ioredis": "^5.7.0",
-    "effect": "^4.0.0-beta.70"
+    "effect": "^4.0.0-beta.71"
   },
   "devDependencies": {
     "@testcontainers/mysql": "^11.14.0",
     "@testcontainers/postgresql": "^11.14.0",
     "@testcontainers/redis": "^11.14.0",
     "@types/node": "^25.7.0",
-    "effect": "^4.0.0-beta.70"
+    "effect": "^4.0.0-beta.71"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/Mime.ts

@@ -1,3 +1,10 @@
+/**
+ * Re-exports the `mime` package through the `@effect/platform-node/Mime`
+ * module and the `Mime` namespace in the package barrel.
+ *
+ * @since 4.0.0
+ */
+
 /* oxlint-disable no-named-as-default */
 
 /**

package/src/NodeCrypto.ts

@@ -1,5 +1,13 @@
 /**
- * Node.js platform Crypto service layer.
+ * The `NodeCrypto` module provides the Node.js `Crypto` service layer for
+ * Effect programs. Provide {@link layer} at the edge of a Node application,
+ * CLI, script, or test to satisfy `effect/Crypto` with Node's `node:crypto`
+ * implementation for secure random bytes, UUID generation, random values, and
+ * SHA digest operations.
+ *
+ * This module is the public Node adapter around the shared Node-compatible
+ * implementation. Digest failures are reported as platform errors, and SHA-1
+ * remains available only for interoperability with existing protocols.
  *
  * @since 1.0.0
  */

package/src/NodeFileSystem.ts

@@ -1,20 +1,28 @@
 /**
- * Provides the Node.js `FileSystem` layer for Effect programs.
+ * Node.js `FileSystem` layer for programs that perform real filesystem I/O.
  *
- * Use this module when a Node application, CLI, script, or test needs to
- * satisfy the `FileSystem` service with real filesystem access for reading and
- * writing files, creating directories and temporary files, inspecting metadata,
- * managing links, or watching paths for changes.
+ * The exported layer satisfies the platform-independent `FileSystem` service
+ * with Node-backed operations for files, directories, metadata, permissions,
+ * links, temporary paths, and path watching. Effects still call the service from
+ * `effect/FileSystem`; this module only chooses the Node implementation.
  *
- * This module only exposes the Node-backed layer; filesystem operations are
- * accessed through the `FileSystem` service from `effect/FileSystem`. Provide
- * `NodeFileSystem.layer` at the edge of the program, or use
- * `NodeServices.layer` when you also want the standard Node path, stdio,
- * terminal, and child process services. The implementation is shared with
- * other Node-compatible platform packages, so optional services such as
- * `FileSystem.WatchBackend` are honored when present; otherwise file watching
- * follows Node's `node:fs.watch` behavior. Paths are interpreted by Node, so
- * relative paths use the current working directory and platform path rules.
+ * **Mental model**
+ *
+ * Provide `NodeFileSystem.layer` at the process boundary when filesystem
+ * effects should touch the host filesystem. Use `NodeServices.layer` instead
+ * when the same program also needs the standard Node path, stdio, terminal,
+ * crypto, and child process services. Tests that need isolation can provide a
+ * different `FileSystem` layer without changing the code that performs the
+ * reads and writes.
+ *
+ * **Gotchas**
+ *
+ * Paths are interpreted by Node, so relative paths resolve against the current
+ * working directory and platform-specific path rules apply. Filesystem failures
+ * are reported through Effect platform errors rather than thrown exceptions.
+ * File watching uses `FileSystem.WatchBackend` when one is available; otherwise
+ * it follows `node:fs.watch`, whose recursive support, event batching, and
+ * reported path names vary across operating systems.
  *
  * @since 4.0.0
  */

package/src/NodeHttpClient.ts

@@ -1,28 +1,37 @@
 /**
  * Node.js implementations of the Effect `HttpClient`.
  *
- * This module provides the Node-specific layers and constructors for sending
- * Effect HTTP client requests. It re-exports the fetch-based client for
- * programs that want to use `globalThis.fetch`, provides an Undici-backed
- * client for applications that need Undici dispatcher control, and provides a
- * lower-level `node:http` / `node:https` client for integrations that need
- * native Node agent configuration.
+ * This module supplies Node runtime backends for the platform-independent
+ * Effect HTTP client API. It re-exports the fetch-based client, defines an
+ * Undici-backed client, and defines a lower-level `node:http` / `node:https`
+ * client for integrations that need native agent configuration.
  *
- * Use these clients in server-side applications, CLIs, tests, and integrations
- * where requests should participate in Effect resource management, interruption,
- * streaming, and typed transport / decode errors. The Undici path sends each
- * request through the current `Dispatcher`; `layerUndici` owns a scoped
- * `Agent`, while `dispatcherLayerGlobal` uses Undici's process-global dispatcher
- * without destroying it. The `node:http` path uses separate scoped HTTP and
- * HTTPS agents, making it the right choice when native agent options such as
- * TLS, proxy, keep-alive, or socket behavior need to be configured directly.
+ * **Mental model**
  *
- * The backends are not completely interchangeable. Fetch, Undici, and
- * `node:http` expose different agent and dispatcher hooks, body implementations,
- * abort behavior, upgrade support, and response body readers. This module
- * converts Effect request bodies to the selected runtime representation:
- * streams remain streaming, `FormData` may contribute generated content headers,
- * and body read failures are reported as `HttpClientError` decode or transport
+ * All backends provide the same `HttpClient` service, so application code can
+ * depend on the Effect HTTP client interface while the layer chooses the Node
+ * implementation. The difference is where request execution and connection
+ * ownership live: fetch uses `globalThis.fetch`, Undici sends through a
+ * `Dispatcher`, and the `node:http` backend sends through scoped HTTP and HTTPS
+ * agents.
+ *
+ * **Common tasks**
+ *
+ * Use `layerFetch` when the built-in fetch implementation is enough. Use
+ * `layerUndici` for a scoped Undici `Agent`, or `layerUndiciNoDispatcher` when
+ * the caller provides the `Dispatcher` service, including the process-global
+ * dispatcher from `dispatcherLayerGlobal`. Use `layerNodeHttp` or
+ * `layerAgentOptions` when TLS, proxy, keep-alive, socket, or other native
+ * Node agent options must be configured directly.
+ *
+ * **Gotchas**
+ *
+ * Fetch, Undici, and `node:http` are not exact substitutes. They differ in
+ * dispatcher and agent hooks, request body support, abort behavior, upgrade
+ * support, and response body readers. Scoped layers destroy the agents or
+ * dispatchers they create when the layer scope ends; `dispatcherLayerGlobal`
+ * intentionally does not own or destroy Undici's process-global dispatcher.
+ * Body read failures are reported as `HttpClientError` decode or transport
  * errors.
  *
  * @since 4.0.0

package/src/NodeHttpIncomingMessage.ts

@@ -1,15 +1,28 @@
 /**
- * Utilities for adapting Node `http.IncomingMessage` values to the Effect HTTP
- * incoming message interface used by the platform Node server and client
- * implementations.
+ * Adapter base for exposing Node `http.IncomingMessage` values as Effect HTTP
+ * incoming messages.
  *
- * This module is useful when code needs to keep access to Node's request or
- * response object while also exposing Effect's typed headers, remote address,
- * body decoders, and stream interface. The body helpers consume Node's readable
- * stream, cache decoded text and array-buffer results, and honor the
- * `HttpIncomingMessage.MaxBodySize` fiber ref. Prefer a single body access
- * strategy per message: raw `stream` access is not cached, and Node request
- * bodies cannot be replayed once the underlying stream has been consumed.
+ * Server requests and Node client responses both arrive as Node readable
+ * streams with raw header objects, socket metadata, and one-shot body
+ * consumption. This module's `NodeHttpIncomingMessage` class keeps the original
+ * Node message available while presenting Effect's `HttpIncomingMessage` shape:
+ * typed headers, remote address lookup, stream access, and text, JSON,
+ * URL-encoded, and array-buffer body readers.
+ *
+ * **Mental model**
+ *
+ * The Node message remains the source of truth. The adapter translates headers
+ * and remote address on demand, delegates raw streaming to `NodeStream`, and
+ * lets subclasses choose how unknown Node errors are mapped into their HTTP
+ * error type.
+ *
+ * **Gotchas**
+ *
+ * Node request and response bodies are one-shot streams. The `text` and
+ * `arrayBuffer` readers are cached and share decoded values with each other,
+ * but direct `stream` access is not cached and can consume the underlying Node
+ * stream before a decoder reads it. Body readers honor
+ * `HttpIncomingMessage.MaxBodySize`.
  *
  * @since 4.0.0
  */