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

package/src/NodeFileSystem.ts

@@ -1,5 +1,36 @@
 /**
- * @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
+ * `FileSystem` layer for Effect programs running on Node-compatible runtimes.
+ * Platform packages use it to provide file and directory I/O, permissions,
+ * links, metadata, temporary files and directories, and file watching through
+ * the shared `FileSystem` service.
+ *
+ * **Mental model**
+ *
+ * {@link layer} installs a process-backed `FileSystem` service. Each operation
+ * delegates to the corresponding Node filesystem API, then maps Node failures
+ * into `PlatformError` values and invalid arguments into `BadArgument` failures.
+ * Paths keep Node's normal behavior: relative paths resolve from the current
+ * working directory and platform path rules still apply.
+ *
+ * **Common tasks**
+ *
+ * Provide {@link layer} at the Node runtime boundary, then depend on the
+ * `FileSystem` service from application code. Use the service for ordinary
+ * reads and writes, directory management, metadata inspection, links, temporary
+ * resources, and file watching without importing Node's `fs` APIs directly.
+ *
+ * **Gotchas**
+ *
+ * Open files are scoped resources with tracked read and write positions; append
+ * mode lets the operating system choose the write offset. File watching follows
+ * `node:fs.watch` semantics unless a custom watch backend is supplied, so
+ * recursive support, event coalescing, and reported paths vary by runtime and
+ * platform.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
@@ -232,7 +263,7 @@ const makeFile = (() => {
     readonly fd: FileSystem.File.Descriptor
     private readonly append: boolean
 
-    private position: bigint = 0n
+    private position: bigint = BigInt(0)
 
     constructor(
       fd: FileSystem.File.Descriptor,
@@ -285,19 +316,19 @@ const makeFile = (() => {
         const position = this.position
         return Effect.map(
           nodeReadAlloc(this.fd, { buffer, position }),
-          (bytesRead): Buffer | undefined => {
+          (bytesRead): Option.Option<Buffer> => {
             if (bytesRead === 0) {
-              return undefined
+              return Option.none()
             }
 
             this.position = position + BigInt(bytesRead)
             if (bytesRead === sizeNumber) {
-              return buffer
+              return Option.some(buffer)
             }
 
             const dst = Buffer.allocUnsafeSlow(bytesRead)
             buffer.copy(dst, 0, 0, bytesRead)
-            return dst
+            return Option.some(dst)
           }
         )
       })
@@ -468,19 +499,19 @@ const makeFileInfo = (stat: NFS.Stats): FileSystem.File.Info => ({
     stat.isSocket() ?
     "Socket" :
     "Unknown",
-  mtime: stat.mtime,
-  atime: stat.atime,
-  birthtime: stat.birthtime,
+  mtime: Option.fromNullishOr(stat.mtime),
+  atime: Option.fromNullishOr(stat.atime),
+  birthtime: Option.fromNullishOr(stat.birthtime),
   dev: stat.dev,
-  rdev: stat.rdev,
-  ino: stat.ino,
+  rdev: Option.fromNullishOr(stat.rdev),
+  ino: Option.fromNullishOr(stat.ino),
   mode: stat.mode,
-  nlink: stat.nlink,
-  uid: stat.uid,
-  gid: stat.gid,
+  nlink: Option.fromNullishOr(stat.nlink),
+  uid: Option.fromNullishOr(stat.uid),
+  gid: Option.fromNullishOr(stat.gid),
   size: FileSystem.Size(stat.size),
-  blksize: FileSystem.Size(stat.blksize),
-  blocks: stat.blocks
+  blksize: stat.blksize !== undefined ? Option.some(FileSystem.Size(stat.blksize)) : Option.none(),
+  blocks: Option.fromNullishOr(stat.blocks)
 })
 const stat = (() => {
   const nodeStat = effectify(
@@ -531,7 +562,9 @@ const watchNode = (path: string) =>
   Stream.callback<FileSystem.WatchEvent, Error.PlatformError>((queue) =>
     Effect.acquireRelease(
       Effect.sync(() => {
-        const watcher = NFS.watch(path, {}, (event, path) => {
+        const watcher = NFS.watch(path, {
+          recursive: true
+        }, (event, path) => {
           if (!path) return
           switch (event) {
             case "rename": {
@@ -570,15 +603,14 @@ const watchNode = (path: string) =>
     )
   )
 
-const watch = (backend: FileSystem.WatchBackend["Service"] | undefined, path: string) =>
+const watch = (backend: Option.Option<FileSystem.WatchBackend["Service"]>, path: string) =>
   stat(path).pipe(
-    Effect.map((stat) => {
-      if (backend) {
-        const stream = backend.register(path, stat)
-        if (stream) return stream
-      }
-      return watchNode(path)
-    }),
+    Effect.map((stat) =>
+      backend.pipe(
+        Option.flatMap((_) => _.register(path, stat)),
+        Option.getOrElse(() => watchNode(path))
+      )
+    ),
     Stream.unwrap
   )
 
@@ -628,13 +660,16 @@ const makeFileSystem = Effect.map(Effect.serviceOption(FileSystem.WatchBackend),
     truncate,
     utimes,
     watch(path) {
-      return watch(Option.getOrUndefined(backend), path)
+      return watch(backend, path)
     },
     writeFile
   }))
 
 /**
- * @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,28 @@
 /**
- * @since 1.0.0
+ * Node-backed provider for Effect's `Path` service.
+ *
+ * This module turns Node's `node:path` and `node:url` APIs into `Layer`s for
+ * programs that depend on `Path`. Use it when code should receive path
+ * operations from the Effect environment instead of importing `node:path`
+ * directly, including configuration loading, filesystem composition, and file
+ * URL conversion.
+ *
+ * **Mental model**
+ *
+ * `layer` follows the platform semantics of the current Node runtime. The
+ * `layerPosix` and `layerWin32` variants pin the syntax rules to POSIX or
+ * Windows, which is useful for deterministic parsing, formatting, and tests.
+ * All three layers include `fromFileUrl` and `toFileUrl` behavior backed by
+ * Node's URL conversion functions.
+ *
+ * **Gotchas**
+ *
+ * Path operations are syntactic: they normalize separators, roots, drive
+ * letters, UNC segments, extensions, and relative segments without checking the
+ * filesystem. File URL conversion follows Node's validation and encoding
+ * rules, and invalid conversions fail with `BadArgument`.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -31,8 +54,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 +68,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 +82,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,54 @@
 /**
- * @since 1.0.0
+ * Node-compatible process runner for Effect programs.
+ *
+ * This module provides the shared `runMain` implementation used by
+ * Node-compatible platform packages. Use it at the outer edge of a CLI, script,
+ * worker, server, or test harness when a single Effect should become the main
+ * fiber for the process while still following Node signal and exit-code
+ * conventions.
+ *
+ * **Mental model**
+ *
+ * `runMain` starts the supplied Effect as the process root. While that fiber is
+ * running, `SIGINT` and `SIGTERM` are translated into fiber interruption so
+ * scoped resources and finalizers get a chance to run. After the fiber exits,
+ * the signal listeners are removed and the configured teardown decides the
+ * process exit code.
+ *
+ * **Common tasks**
+ *
+ * - Launch a command-line program or long-running service from an Effect.
+ * - Share the same main-runner behavior across Node-compatible packages.
+ * - Customize teardown or runtime error reporting with the `runMain` options.
+ *
+ * **Gotchas**
+ *
+ * Clean success lets the Node event loop drain naturally instead of forcing
+ * `process.exit(0)`. Signal-triggered interruption or a non-zero teardown code
+ * calls `process.exit`, so long-lived handles should be acquired in Effect
+ * scopes and released by finalizers.
+ *
+ * @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 +57,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>,
@@ -37,10 +78,8 @@ export const runMain: {
   let receivedSignal = false
 
   fiber.addObserver((exit) => {
-    if (!receivedSignal) {
-      process.removeListener("SIGINT", onSigint)
-      process.removeListener("SIGTERM", onSigint)
-    }
+    process.removeListener("SIGINT", onSigint)
+    process.removeListener("SIGTERM", onSigint)
     teardown(exit, (code) => {
       if (receivedSignal || code !== 0) {
         process.exit(code)
@@ -50,8 +89,6 @@ export const runMain: {
 
   function onSigint() {
     receivedSignal = true
-    process.removeListener("SIGINT", onSigint)
-    process.removeListener("SIGTERM", onSigint)
     fiber.interruptUnsafe(fiber.id)
   }
 

package/src/NodeSink.ts

@@ -1,5 +1,37 @@
 /**
- * @since 1.0.0
+ * Sink adapters for writing Effect stream chunks into Node writable streams.
+ *
+ * This module is the writable-stream boundary for Node APIs: push Effect
+ * `Stream` or `Channel` chunks into file streams, HTTP request or response
+ * bodies, process stdio, sockets, and transform inputs such as compression or
+ * encryption streams. It exposes a `Sink` constructor for ordinary stream
+ * pipelines plus lower-level `Channel` and pull helpers used by other Node
+ * stream adapters.
+ *
+ * **Mental model**
+ *
+ * {@link fromWritable} builds a `Sink` for normal stream pipelines.
+ * {@link fromWritableChannel} exposes the same bridge as a `Channel`, and
+ * {@link pullIntoWritable} is the lower-level loop for adapters that already
+ * have a pull and a Node writable. All three write chunks in order and follow
+ * Node writable backpressure.
+ *
+ * **Common tasks**
+ *
+ * Use {@link fromWritable} to pipe an Effect stream into a Node destination.
+ * Use {@link fromWritableChannel} when composing at the `Channel` level. Use
+ * {@link pullIntoWritable} inside custom Node stream adapters that need direct
+ * control over the upstream pull.
+ *
+ * **Gotchas**
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "effect/Array"
 import * as Cause from "effect/Cause"
@@ -11,8 +43,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 +61,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 +82,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>
@@ -66,6 +111,13 @@ export const pullIntoWritable = <A, IE, E>(options: {
       })
     }),
     Effect.forever({ disableYield: true }),
+    Effect.raceFirst(Effect.callback<never, E>((resume) => {
+      const onError = (error: unknown) => resume(Effect.fail(options.onError(error)))
+      options.writable.once("error", onError)
+      return Effect.sync(() => {
+        options.writable.off("error", onError)
+      })
+    })),
     options.endOnDone !== false ?
       Pull.catchDone((_) => {
         if ("closed" in options.writable && options.writable.closed) {

package/src/NodeSocket.ts

@@ -1,8 +1,33 @@
 /**
- * @since 1.0.0
+ * Node socket adapters for Effect sockets.
+ *
+ * This module opens `node:net` connections or wraps existing Node `Duplex`
+ * streams and presents them as `Socket.Socket` values, socket channels, or
+ * layers. It is the low-level bridge for TCP clients, Unix domain socket
+ * clients, and protocols that already expose a Node duplex stream.
+ *
+ * **Mental model**
+ *
+ * A socket acquired here is scoped. `makeNet` dials with
+ * `net.createConnection`, `fromDuplex` adapts any duplex returned by an Effect,
+ * `makeNetChannel` exposes the socket as a `Channel`, and `layerNet` provides
+ * it through the Effect environment. While a socket handler is running,
+ * `NetSocket` gives access to the underlying Node `net.Socket` for cases that
+ * need Node-specific operations.
+ *
+ * **Gotchas**
+ *
+ * `openTimeout` only limits opening the connection. Writes complete when Node
+ * accepts or flushes a chunk, close events are translated to `SocketError`
+ * values, and finalizers close or destroy the stream when the surrounding scope
+ * ends. Unix socket paths are supplied through `NetConnectOpts.path`, so use
+ * the same platform path rules as Node.
+ *
+ * @since 4.0.0
  */
 import type { Array } from "effect"
 import * as Channel from "effect/Channel"
+import * as Context from "effect/Context"
 import * as Deferred from "effect/Deferred"
 import type * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
@@ -12,28 +37,34 @@ import { identity } from "effect/Function"
 import * as Latch from "effect/Latch"
 import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Socket from "effect/unstable/socket/Socket"
 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 ServiceMap.Service<NetSocket, Net.Socket>()(
+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 & {
@@ -41,11 +72,11 @@ export const makeNet = (
   }
 ): Effect.Effect<Socket.Socket> =>
   fromDuplex(
-    Effect.servicesWith((services: ServiceMap.ServiceMap<Scope.Scope>) => {
+    Effect.contextWith((context: Context.Context<Scope.Scope>) => {
       let conn: Net.Socket | undefined
       return Effect.flatMap(
         Scope.addFinalizer(
-          ServiceMap.get(services, Scope.Scope),
+          Context.get(context, Scope.Scope),
           Effect.sync(() => {
             if (!conn) return
             if (conn.closed === false) {
@@ -77,8 +108,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>,
@@ -89,7 +124,7 @@ export const fromDuplex = <RO>(
   Effect.withFiber<Socket.Socket, never, Exclude<RO, Scope.Scope>>((fiber) => {
     let currentSocket: Duplex | undefined
     const latch = Latch.makeUnsafe(false)
-    const openServices = fiber.services as ServiceMap.ServiceMap<RO>
+    const openServices = fiber.context as Context.Context<RO>
 
     const run = <R, E, _>(handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void, opts?: {
       readonly onOpen?: Effect.Effect<void> | undefined
@@ -113,7 +148,7 @@ export const fromDuplex = <RO>(
           options?.openTimeout ?
             Effect.timeoutOrElse({
               duration: options.openTimeout,
-              onTimeout: () =>
+              orElse: () =>
                 Effect.fail(
                   new Socket.SocketError({
                     reason: new Socket.SocketOpenError({ kind: "Timeout", cause: new Error("Connection timed out") })
@@ -166,7 +201,7 @@ export const fromDuplex = <RO>(
           )
         }
       })).pipe(
-        Effect.updateServices((input: ServiceMap.ServiceMap<R>) => ServiceMap.merge(openServices, input)),
+        Effect.updateContext((input: Context.Context<R>) => Context.merge(openServices, input)),
         Effect.onExit(() =>
           Effect.sync(() => {
             latch.closeUnsafe()
@@ -204,8 +239,7 @@ export const fromDuplex = <RO>(
         })
     )
 
-    return Effect.succeed(Socket.Socket.of({
-      [Socket.TypeId]: Socket.TypeId,
+    return Effect.succeed(Socket.make({
       run,
       runRaw: run,
       writer
@@ -213,8 +247,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
@@ -230,8 +267,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,