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

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"
@@ -8,6 +22,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 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.
+ *
  * **Details**
  *
  * This function launches an Effect as the main entry point, setting exit codes
@@ -16,26 +36,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 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -44,21 +61,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 +77,12 @@ export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -77,21 +91,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,24 @@
 /**
- * @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 { Crypto } from "effect/Crypto"
 import type { FileSystem } from "effect/FileSystem"
 import * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
@@ -8,25 +26,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,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,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,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
- * @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,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>()({
@@ -63,7 +85,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 +96,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 +106,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 +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>() {
@@ -36,7 +58,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 +92,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                     message: "received messageerror event",
                     cause
                   })
-                }).asEffect()
+                })
               )
             })
             WorkerThreads.parentPort.on("error", (cause) => {
@@ -81,7 +103,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                     message: "received messageerror event",
                     cause
                   })
-                }).asEffect()
+                })
               )
             })
           }

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