@effect/platform-node 4.0.0-beta.77 → 4.0.0-beta.79

package/src/NodeRuntime.ts

@@ -1,31 +1,10 @@
 /**
- * Node.js process runner for starting an Effect program at the application
- * edge.
+ * Node.js process runner for Effect programs.
  *
- * 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.
- *
- * **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.
+ * This module exports `runMain`, which runs one Effect as the main process
+ * fiber in Node.js. It reuses the shared Node runtime runner, including its
+ * error reporting, `SIGINT` / `SIGTERM` interruption, and optional teardown
+ * behavior.
  *
  * @since 4.0.0
  */

package/src/NodeServices.ts

@@ -1,35 +1,10 @@
 /**
- * Standard Node.js service bundle for Effect applications.
+ * Aggregate Node.js platform services layer.
  *
- * `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.
+ * This module defines the `NodeServices` union and a single `layer` that
+ * provides Node-backed child process spawning, crypto, filesystem, path, stdio,
+ * and terminal services. Use the layer when a Node program wants the standard
+ * platform services from one place.
  *
  * @since 4.0.0
  */

package/src/NodeSocket.ts

@@ -1,35 +1,11 @@
 /**
  * Node.js socket constructors and layers for Effect sockets.
  *
- * 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`.
- *
- * **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.
+ * This module re-exports the shared Node socket support for TCP connections,
+ * Unix domain socket connections, and Node `Duplex` streams. It also provides
+ * WebSocket constructor layers: one that uses `globalThis.WebSocket` when
+ * present and falls back to `ws`, one that always uses `ws`, and one that
+ * creates a `Socket.Socket` layer for a WebSocket URL.
  *
  * @since 4.0.0
  */

package/src/NodeStdio.ts

@@ -1,27 +1,10 @@
 /**
  * Node.js `Stdio` layer for the current process.
  *
- * 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.
- *
- * **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.
+ * The exported layer reuses the shared Node stdio implementation. It 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`.
  *
  * @since 4.0.0
  */

package/src/NodeTerminal.ts

@@ -1,23 +1,9 @@
 /**
  * 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.
+ * This module reuses the shared Node terminal implementation. `make` creates a
+ * scoped process-backed `Terminal` service, and `layer` provides the default
+ * service with the standard quit behavior for key input.
  *
  * @since 4.0.0
  */

package/src/NodeWorker.ts

@@ -1,35 +1,12 @@
 /**
  * Parent-side Node.js support for Effect workers.
  *
- * 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.
- *
- * **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`.
+ * `layerPlatform` 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. `layer`
+ * combines that platform with a `Spawner` callback, and the platform asks
+ * workers to close on scope finalization before forcefully terminating them on
+ * timeout.
  *
  * @since 4.0.0
  */

package/src/NodeWorkerRunner.ts

@@ -2,40 +2,11 @@
  * Node.js runtime support for workers that serve Effect worker requests.
  *
  * `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.
- *
- * **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.
+ * runner platform. The exported `layer` runs inside a `node:worker_threads`
+ * worker through `parentPort`, or inside a child process through
+ * `process.send`. It listens for parent messages, runs handlers registered with
+ * `WorkerRunner`, sends replies over the same channel, and closes when the
+ * parent sends the close message.
  *
  * @since 4.0.0
  */