@effect/platform-node-shared 4.0.0-beta.66 → 4.0.0-beta.68

package/src/NodeCrypto.ts

@@ -0,0 +1,55 @@
+/**
+ * Node.js implementation of the Crypto service.
+ *
+ * @since 1.0.0
+ */
+import * as EffectCrypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as PlatformError from "effect/PlatformError"
+import * as NodeCrypto from "node:crypto"
+
+const toHashAlgorithm = (algorithm: EffectCrypto.DigestAlgorithm): string => {
+  switch (algorithm) {
+    case "SHA-1":
+      return "sha1"
+    case "SHA-256":
+      return "sha256"
+    case "SHA-384":
+      return "sha384"
+    case "SHA-512":
+      return "sha512"
+  }
+}
+
+const digest: EffectCrypto.Crypto["digest"] = (algorithm, data) =>
+  Effect.try({
+    try: () => Uint8Array.from(NodeCrypto.createHash(toHashAlgorithm(algorithm)).update(data).digest()),
+    catch: (cause) =>
+      PlatformError.systemError({
+        module: "Crypto",
+        method: "digest",
+        _tag: "Unknown",
+        description: "Could not compute digest",
+        cause
+      })
+  })
+
+/**
+ * The default Node.js Crypto service implementation.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make: EffectCrypto.Crypto = EffectCrypto.make({
+  randomBytes: NodeCrypto.randomBytes,
+  digest
+})
+
+/**
+ * A layer that provides the Node.js Crypto service implementation.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer: Layer.Layer<EffectCrypto.Crypto> = Layer.succeed(EffectCrypto.Crypto, make)

package/src/NodeFileSystem.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Shared Node-compatible implementation of Effect's `FileSystem` service.
+ *
+ * This module adapts Node's `node:fs`, `node:os`, and `node:path` APIs into a
+ * layer that can be provided to Effect programs running on Node-compatible
+ * runtimes. It is used by platform packages to provide file and directory I/O,
+ * permissions, links, metadata, temporary files and directories, and file
+ * watching through the `FileSystem` service.
+ *
+ * Paths are passed to Node filesystem APIs, so relative paths are resolved by
+ * the current working directory and platform path rules still apply. Node
+ * filesystem failures are translated into `PlatformError` values, while invalid
+ * arguments become `BadArgument` failures. Open files are scoped resources with
+ * tracked read and write positions; append mode lets the operating system choose
+ * the write offset. File watching is exposed as a stream and follows
+ * `node:fs.watch` semantics unless a `WatchBackend` is provided, so recursive
+ * support, event coalescing, and reported paths can vary by runtime and
+ * platform.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
@@ -635,7 +653,10 @@ const makeFileSystem = Effect.map(Effect.serviceOption(FileSystem.WatchBackend),
   }))
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the `FileSystem` service backed by Node filesystem APIs, including
+ * file operations, directory operations, links, metadata, and file watching.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<FileSystem.FileSystem> = Layer.effect(FileSystem.FileSystem)(makeFileSystem)

package/src/NodePath.ts

@@ -1,5 +1,19 @@
 /**
- * @since 1.0.0
+ * Shared Node-compatible implementation of Effect's `Path` service.
+ *
+ * This module adapts Node's `node:path` and `node:url` APIs into layers that
+ * can be provided to Effect programs needing path manipulation, such as
+ * resolving configuration files, building file system locations, parsing
+ * names and extensions, or converting between file paths and `file:` URLs.
+ *
+ * The default layer follows the host platform semantics exposed by
+ * `node:path`, while `layerPosix` and `layerWin32` provide stable POSIX or
+ * Windows behavior regardless of the current runtime. Path operations are
+ * syntactic and do not check whether files exist; separators, drive letters,
+ * UNC paths, and URL encoding rules can also differ by platform. Invalid
+ * file URL conversions are reported through `BadArgument`.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -31,8 +45,11 @@ const toFileUrl = (path: string): Effect.Effect<URL, BadArgument> =>
   })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the `Path` service using Node's POSIX path implementation plus
+ * file URL conversion helpers.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerPosix: Layer.Layer<Path> = Layer.succeed(Path)({
   [TypeId]: TypeId,
@@ -42,8 +59,11 @@ export const layerPosix: Layer.Layer<Path> = Layer.succeed(Path)({
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the `Path` service using Node's Windows path implementation plus
+ * file URL conversion helpers.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWin32: Layer.Layer<Path> = Layer.succeed(Path)({
   [TypeId]: TypeId,
@@ -53,8 +73,11 @@ export const layerWin32: Layer.Layer<Path> = Layer.succeed(Path)({
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the default `Path` service using the host platform's Node path
+ * implementation plus file URL conversion helpers.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = Layer.succeed(Path)({
   [TypeId]: TypeId,

package/src/NodeRuntime.ts

@@ -1,17 +1,42 @@
 /**
- * @since 1.0.0
+ * Shared runtime helpers for running Effect programs as Node-compatible
+ * process entry points.
+ *
+ * This module provides the common `runMain` implementation used by
+ * Node-compatible platform packages. It is intended for CLIs, scripts,
+ * workers, servers, and other process-oriented programs that should run an
+ * Effect as their main fiber while still following Node process conventions.
+ *
+ * The runner installs `SIGINT` and `SIGTERM` handlers for the lifetime of the
+ * main fiber, translating those process signals into fiber interruption so
+ * Effect finalizers and the configured teardown can run. When the fiber exits,
+ * the signal listeners are removed and teardown determines the exit code. Clean
+ * success lets the Node event loop drain naturally instead of forcing
+ * `process.exit(0)`, while signal-triggered or non-zero exits call
+ * `process.exit` after teardown, so long-running resources should be modeled
+ * in the Effect scope and finalized explicitly.
+ *
+ * @since 4.0.0
  */
 import type { Effect } from "effect/Effect"
 import * as Runtime from "effect/Runtime"
 
 /**
- * @since 1.0.0
- * @category Run main
+ * Runs an Effect as the Node process main program, interrupting the fiber on
+ * `SIGINT` or `SIGTERM` and invoking the configured teardown to determine the
+ * process exit code.
+ *
+ * @category running
+ * @since 4.0.0
  */
 export const runMain: {
   /**
-   * @since 1.0.0
-   * @category Run main
+   * Runs an Effect as the Node process main program, interrupting the fiber on
+   * `SIGINT` or `SIGTERM` and invoking the configured teardown to determine the
+   * process exit code.
+   *
+   * @category running
+   * @since 4.0.0
    */
   (
     options?: {
@@ -20,8 +45,12 @@ export const runMain: {
     }
   ): <E, A>(effect: Effect<A, E>) => void
   /**
-   * @since 1.0.0
-   * @category Run main
+   * Runs an Effect as the Node process main program, interrupting the fiber on
+   * `SIGINT` or `SIGTERM` and invoking the configured teardown to determine the
+   * process exit code.
+   *
+   * @category running
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect<A, E>,

package/src/NodeSink.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Sink adapters for writing Effect stream chunks into Node writable streams.
+ *
+ * This module is used at the boundary where Effect `Stream`s or `Channel`s need
+ * to push data into Node's writable side: file streams, HTTP request or
+ * response bodies, process stdio, sockets, and transform inputs such as
+ * compression or encryption streams. It exposes both a `Sink` constructor for
+ * ordinary stream pipelines and lower-level `Channel` and pull helpers used by
+ * other Node stream adapters.
+ *
+ * The implementation follows Node writable semantics. Chunks are written in
+ * order; when `write` returns `false`, pulling pauses until `drain` so upstream
+ * producers do not overrun the writable buffer. Writable `error` events are
+ * mapped through `onError`, and the writable is ended and awaited via `finish`
+ * when upstream completes unless `endOnDone` is `false`. Use `endOnDone: false`
+ * for externally owned or long-lived writables, and make sure `onError` keeps
+ * Node's untyped errors meaningful for the calling Effect workflow.
+ *
+ * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "effect/Array"
 import * as Cause from "effect/Cause"
@@ -11,8 +28,12 @@ import * as Sink from "effect/Sink"
 import type { Writable } from "node:stream"
 
 /**
+ * Creates a `Sink` that writes chunks to a Node writable stream, respecting
+ * backpressure, mapping writable errors with `onError`, and ending the stream
+ * on completion unless `endOnDone` is `false`.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const fromWritable = <E, A = Uint8Array | string>(
   options: {
@@ -25,8 +46,12 @@ export const fromWritable = <E, A = Uint8Array | string>(
   Sink.fromChannel(Channel.mapDone(fromWritableChannel<never, E, A>(options), (_) => [_]))
 
 /**
+ * Creates a `Channel` that pulls chunks from upstream and writes them to a
+ * Node writable stream, respecting backpressure and optionally ending the
+ * writable when upstream is done.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const fromWritableChannel = <IE, E, A = Uint8Array | string>(
   options: {
@@ -42,7 +67,12 @@ export const fromWritableChannel = <IE, E, A = Uint8Array | string>(
   })
 
 /**
- * @since 1.0.0
+ * Repeatedly pulls non-empty chunks and writes them to a Node writable stream,
+ * waiting for `drain` when needed, failing on writable errors, and ending the
+ * writable on upstream completion unless disabled.
+ *
+ * @category converting
+ * @since 4.0.0
  */
 export const pullIntoWritable = <A, IE, E>(options: {
   readonly pull: Pull.Pull<NonEmptyReadonlyArray<A>, IE, unknown>

package/src/NodeSocket.ts

@@ -1,5 +1,19 @@
 /**
- * @since 1.0.0
+ * Shared Node socket constructors for adapting `node:net` connections and
+ * other Node `Duplex` streams to Effect's `Socket.Socket` interface.
+ *
+ * Use this module when building TCP clients, Unix domain socket clients, or
+ * higher-level protocols that already expose a Node `Duplex`. Connections are
+ * scoped, so finalizers close or destroy the underlying stream, open timeouts
+ * are reported as socket open errors, and Node read, write, and close events
+ * are translated into `SocketError` values.
+ *
+ * Node sockets have a few operational details worth keeping in mind: Unix
+ * socket paths are supplied through `NetConnectOpts.path`, writes complete only
+ * after Node accepts or flushes the chunk, and abnormal close events are
+ * surfaced as close errors while normal remote ends complete the socket run.
+ *
+ * @since 4.0.0
  */
 import type { Array } from "effect"
 import * as Channel from "effect/Channel"
@@ -18,22 +32,29 @@ import * as Net from "node:net"
 import type { Duplex } from "node:stream"
 
 /**
- * @since 1.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * as NodeWS from "ws"
 
 /**
- * @since 1.0.0
+ * Service tag for the underlying Node `net.Socket` associated with the current
+ * socket connection.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class NetSocket extends Context.Service<NetSocket, Net.Socket>()(
   "@effect/platform-node/NodeSocket/NetSocket"
 ) {}
 
 /**
- * @since 1.0.0
+ * Opens a TCP connection with Node `net.createConnection` and exposes it as a
+ * `Socket.Socket`, supporting `openTimeout` and closing or destroying the
+ * socket when the enclosing scope is finalized.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeNet = (
   options: Net.NetConnectOpts & {
@@ -77,8 +98,12 @@ export const makeNet = (
   )
 
 /**
- * @since 1.0.0
+ * Adapts a Node `Duplex` into a `Socket.Socket`, wiring data events to socket
+ * handlers, providing a scoped writer, and mapping open, read, write, and close
+ * failures to `SocketError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromDuplex = <RO>(
   open: Effect.Effect<Duplex, Socket.SocketError, RO>,
@@ -212,8 +237,11 @@ export const fromDuplex = <RO>(
   })
 
 /**
- * @since 1.0.0
+ * Creates a `Channel` over a TCP socket, reading arrays of `Uint8Array`
+ * chunks and writing arrays of bytes, strings, or socket close events.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeNetChannel = <IE = never>(
   options: Net.NetConnectOpts
@@ -229,8 +257,11 @@ export const makeNetChannel = <IE = never>(
   )
 
 /**
- * @since 1.0.0
+ * Provides a `Socket.Socket` by opening a TCP connection with the supplied
+ * Node `net` connection options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerNet: (options: Net.NetConnectOpts) => Layer.Layer<
   Socket.Socket,

package/src/NodeSocketServer.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Shared Node socket server constructors for exposing `node:net` servers and
+ * `ws` WebSocket servers as Effect `SocketServer.SocketServer` services.
+ *
+ * Use this module when implementing TCP services, Unix domain socket services,
+ * WebSocket endpoints, or higher-level protocols such as RPC transports that
+ * need to accept incoming connections through Effect's socket APIs. TCP
+ * connections are adapted through `NodeSocket.fromDuplex`, while WebSocket
+ * handlers also receive the underlying `WebSocket` and Node `IncomingMessage`
+ * in their fiber context.
+ *
+ * The server starts listening before the constructor returns, and the exported
+ * `address` is derived from the actual Node server after binding. Prefer that
+ * address when using port `0`, wildcard hosts, or Unix socket paths. Incoming
+ * connections accepted before `run` is installed are queued and then handed to
+ * the handler, each `run` call owns the scope for its connection fibers, and
+ * the enclosing scope closes the underlying Node server.
+ *
+ * @since 4.0.0
  */
 import type { Cause } from "effect/Cause"
 import * as Context from "effect/Context"
@@ -20,8 +37,11 @@ import * as NodeSocket from "./NodeSocket.ts"
 import { NodeWS } from "./NodeSocket.ts"
 
 /**
- * @since 1.0.0
+ * Service tag for the Node `IncomingMessage` associated with the current
+ * WebSocket server connection.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class IncomingMessage extends Context.Service<
   IncomingMessage,
@@ -29,8 +49,12 @@ export class IncomingMessage extends Context.Service<
 >()("@effect/platform-node-shared/NodeSocketServer/IncomingMessage") {}
 
 /**
- * @since 1.0.0
+ * Creates a scoped TCP `SocketServer` from a Node `net.Server`, starts
+ * listening with the supplied options, queues pending connections until `run`
+ * is called, and closes the server when the scope ends.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*(
   options: Net.ServerOpts & Net.ListenOptions
@@ -144,8 +168,11 @@ export const make = Effect.fnUntraced(function*(
 })
 
 /**
- * @since 1.0.0
+ * Provides a TCP `SocketServer` by creating and managing a scoped Node
+ * `net.Server` with the supplied server and listen options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: (
   options: Net.ServerOpts & Net.ListenOptions
@@ -155,8 +182,12 @@ export const layer: (
 > = Function.flow(make, Layer.effect(SocketServer.SocketServer))
 
 /**
- * @since 1.0.0
+ * Creates a scoped WebSocket `SocketServer` backed by the `ws` package,
+ * providing the WebSocket and its Node `IncomingMessage` to connection
+ * handlers and closing the server when the scope ends.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWebSocket: (
   options: NodeWS.ServerOptions<typeof NodeWS.WebSocket, typeof Http.IncomingMessage>
@@ -255,8 +286,11 @@ export const makeWebSocket: (
 })
 
 /**
- * @since 1.0.0
+ * Provides a WebSocket `SocketServer` backed by the `ws` package and managed
+ * with the supplied server options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket: (
   options: NodeSocket.NodeWS.ServerOptions<typeof NodeSocket.NodeWS.WebSocket, typeof Http.IncomingMessage>

package/src/NodeStdio.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * Shared Node.js implementation of the Effect `Stdio` service.
+ *
+ * This module builds the `Stdio` layer used by Node platform packages by
+ * wiring the service to the current process: command-line arguments come from
+ * `process.argv`, input is read from `process.stdin`, and output and error
+ * output are written to `process.stdout` and `process.stderr`. It is intended
+ * for CLIs, scripts, command runners, test harnesses, and other
+ * process-oriented programs that need standard I/O through Effect services.
+ *
+ * The process stdio streams are global resources owned by Node. This layer
+ * leaves stdin open and does not end stdout or stderr by default, avoiding
+ * accidental closure of handles other code in the process may still use. Those
+ * streams may be pipes, files, or TTYs; interactive terminal behavior such as
+ * raw mode, echo, colors, and cursor movement should be coordinated with the
+ * terminal APIs instead of assuming this layer has exclusive control.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -9,8 +25,12 @@ import { fromWritable } from "./NodeSink.ts"
 import { fromReadable } from "./NodeStream.ts"
 
 /**
- * @category Layers
- * @since 1.0.0
+ * Provides `Stdio` from `process.argv`, `process.stdin`, `process.stdout`,
+ * and `process.stderr`; stdin remains open and stdout/stderr are not ended by
+ * default.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Stdio.Stdio> = Layer.succeed(
   Stdio.Stdio,