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

package/src/NodeRuntime.ts

@@ -1,5 +1,33 @@
 /**
- * @since 1.0.0
+ * Node.js process runner for starting an Effect program at the application
+ * edge.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as NodeRuntime from "@effect/platform-node-shared/NodeRuntime"
 import type { Effect } from "effect/Effect"
@@ -8,6 +36,12 @@ import type * as Runtime from "effect/Runtime"
 /**
  * Helps you run a main effect with built-in error handling, logging, and signal management.
  *
+ * **When to use**
+ *
+ * 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.
+ *
  * **Details**
  *
  * This function launches an Effect as the main entry point, setting exit codes
@@ -16,26 +50,23 @@ import type * as Runtime from "effect/Runtime"
  * behaviors can be turned off. You can also provide custom teardown logic to
  * finalize resources or produce different exit codes.
  *
- * **Options**
- *
- * An optional object that can include:
+ * The optional configuration object can include:
  * - `disableErrorReporting`: Turn off automatic error logging.
- * - `disablePrettyLogger`: Avoid adding the pretty logger.
  * - `teardown`: Provide custom finalization logic.
  *
- * **When to Use**
- *
- * Use this function 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.
- *
- * @since 1.0.0
- * @category Run main
+ * @category running
+ * @since 4.0.0
  */
 export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -44,21 +75,12 @@ export const runMain: {
    * behaviors can be turned off. You can also provide custom teardown logic to
    * finalize resources or produce different exit codes.
    *
-   * **Options**
-   *
-   * An optional object that can include:
+   * The optional configuration object can include:
    * - `disableErrorReporting`: Turn off automatic error logging.
-   * - `disablePrettyLogger`: Avoid adding the pretty logger.
    * - `teardown`: Provide custom finalization logic.
    *
-   * **When to Use**
-   *
-   * Use this function 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.
-   *
-   * @since 1.0.0
-   * @category Run main
+   * @category running
+   * @since 4.0.0
    */
   (
     options?: {
@@ -69,6 +91,12 @@ export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -77,21 +105,12 @@ export const runMain: {
    * behaviors can be turned off. You can also provide custom teardown logic to
    * finalize resources or produce different exit codes.
    *
-   * **Options**
-   *
-   * An optional object that can include:
+   * The optional configuration object can include:
    * - `disableErrorReporting`: Turn off automatic error logging.
-   * - `disablePrettyLogger`: Avoid adding the pretty logger.
    * - `teardown`: Provide custom finalization logic.
    *
-   * **When to Use**
-   *
-   * Use this function 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.
-   *
-   * @since 1.0.0
-   * @category Run main
+   * @category running
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect<A, E>,

package/src/NodeServices.ts

@@ -1,6 +1,39 @@
 /**
- * @since 1.0.0
+ * 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
  */
+import type { Crypto } from "effect/Crypto"
 import type { FileSystem } from "effect/FileSystem"
 import * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
@@ -8,25 +41,33 @@ import type { Stdio } from "effect/Stdio"
 import type { Terminal } from "effect/Terminal"
 import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
 import * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.ts"
+import * as NodeCrypto from "./NodeCrypto.ts"
 import * as NodeFileSystem from "./NodeFileSystem.ts"
 import * as NodePath from "./NodePath.ts"
 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
+export type NodeServices = ChildProcessSpawner | Crypto | FileSystem | Path | Stdio | Terminal
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the default Node implementations for child process spawning,
+ * filesystem, path, stdio, and terminal services.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<NodeServices> = Layer.provideMerge(
   NodeChildProcessSpawner.layer,
   Layer.mergeAll(
     NodeFileSystem.layer,
+    NodeCrypto.layer,
     NodePath.layer,
     NodeStdio.layer,
     NodeTerminal.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,37 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import { NodeWS as WS } from "@effect/platform-node-shared/NodeSocket"
 import type * as Duration from "effect/Duration"
@@ -9,13 +41,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 +62,25 @@ 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
+> = Layer.succeed(Socket.WebSocketConstructor)(
+  (url, protocols) => new WS.WebSocket(url, protocols) as unknown as globalThis.WebSocket
+)
+
+/**
+ * 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,39 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @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
- * @category layer
+ * Provides the `Stdio` service backed by the current process arguments,
+ * stdin, stdout, and stderr streams.
+ *
+ * @category layers
+ * @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,25 @@
 /**
- * @since 1.0.0
+ * 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
  */
 import * as NodeTerminal from "@effect/platform-node-shared/NodeTerminal"
 import type { Effect } from "effect/Effect"
@@ -8,13 +28,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,37 @@
 /**
- * @since 1.0.0
+ * 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`.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -12,8 +44,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>()({
@@ -63,7 +99,7 @@ export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(W
               message: "An messageerror event was emitted",
               cause
             })
-          }).asEffect()
+          })
         )
       })
       port.worker.on("error", (cause) => {
@@ -74,7 +110,7 @@ export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(W
               message: "An error event was emitted",
               cause
             })
-          }).asEffect()
+          })
         )
       })
       port.worker.on("exit", (code) => {
@@ -84,7 +120,7 @@ export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(W
             reason: new WorkerReceiveError({
               message: "The worker has exited with code: " + code
             })
-          }).asEffect()
+          })
         )
       })
       return Effect.void
@@ -93,8 +129,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,43 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -12,8 +50,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>() {
@@ -36,7 +78,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
         Effect.scopedWith(Effect.fnUntraced(function*(scope) {
           const closeLatch = Deferred.makeUnsafe<void, WorkerError>()
           const trackFiber = Fiber.runIn(scope)
-          const services = yield* Effect.services<R>()
+          const services = yield* Effect.context<R>()
           const runFork = Effect.runForkWith(services)
           const onExit = (exit: Exit.Exit<any, E>) => {
             if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) {
@@ -70,7 +112,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                     message: "received messageerror event",
                     cause
                   })
-                }).asEffect()
+                })
               )
             })
             WorkerThreads.parentPort.on("error", (cause) => {
@@ -81,7 +123,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                     message: "received messageerror event",
                     cause
                   })
-                }).asEffect()
+                })
               )
             })
           }

package/src/Undici.ts

@@ -1,16 +1,29 @@
 /**
- * @since 1.0.0
+ * 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"
 
 /**
- * @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