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

package/src/NodeChildProcessSpawner.ts

@@ -17,7 +17,13 @@ import * as Sink from "effect/Sink"
 import * as Stream from "effect/Stream"
 import * as ChildProcess from "effect/unstable/process/ChildProcess"
 import type { ChildProcessHandle } from "effect/unstable/process/ChildProcessSpawner"
-import { ChildProcessSpawner, ExitCode, makeHandle, ProcessId } from "effect/unstable/process/ChildProcessSpawner"
+import {
+  ChildProcessSpawner,
+  ExitCode,
+  make as makeSpawner,
+  makeHandle,
+  ProcessId
+} from "effect/unstable/process/ChildProcessSpawner"
 import * as NodeChildProcess from "node:child_process"
 import { handleErrnoException } from "./internal/utils.ts"
 import * as NodeSink from "./NodeSink.ts"
@@ -337,6 +343,23 @@ const make = Effect.gen(function*() {
     })
   }
 
+  const killProcessGroupOnExit = (
+    childProcess: NodeChildProcess.ChildProcess,
+    signal: NodeJS.Signals
+  ): void => {
+    if (globalThis.process.platform === "win32") {
+      NodeChildProcess.exec(`taskkill /pid ${childProcess.pid} /T /F`, () => {
+        // ignore errors during best-effort cleanup
+      })
+      return
+    }
+    try {
+      globalThis.process.kill(-childProcess.pid!, signal)
+    } catch {
+      // ignore errors during best-effort cleanup
+    }
+  }
+
   const killProcess = (
     command: ChildProcess.StandardCommand,
     childProcess: NodeChildProcess.ChildProcess,
@@ -368,7 +391,7 @@ const make = Effect.gen(function*() {
       ? kill(command, childProcess, killSignal)
       : Effect.timeoutOrElse(kill(command, childProcess, killSignal), {
         duration: options.forceKillAfter,
-        onTimeout: () => kill(command, childProcess, "SIGKILL")
+        orElse: () => kill(command, childProcess, "SIGKILL")
       })
   }
 
@@ -413,6 +436,8 @@ const make = Effect.gen(function*() {
         const stdoutConfig = resolveOutputOption(cmd.options, "stdout")
         const stderrConfig = resolveOutputOption(cmd.options, "stderr")
         const resolvedAdditionalFds = resolveAdditionalFds(cmd.options)
+        let isReferenced = true
+        let cleanupOnNonZeroExit = false
 
         const cwd = yield* resolveWorkingDirectory(cmd.options)
         const env = resolveEnvironment(cmd.options)
@@ -438,6 +463,9 @@ const make = Effect.gen(function*() {
               }
               return yield* Effect.void
             }
+            if (!isReferenced) {
+              return yield* Effect.void
+            }
             // Process is still running, kill it
             return yield* killWithTimeout((command, childProcess, signal) =>
               Effect.catch(
@@ -452,6 +480,26 @@ const make = Effect.gen(function*() {
         )
 
         const pid = ProcessId(childProcess.pid!)
+        childProcess.on("exit", (code) => {
+          if (cleanupOnNonZeroExit && code !== 0 && Predicate.isNotNull(code)) {
+            killProcessGroupOnExit(childProcess, cmd.options.killSignal ?? "SIGTERM")
+          }
+        })
+        const reref = Effect.sync(() => {
+          if (!isReferenced) {
+            childProcess.ref()
+            isReferenced = true
+            cleanupOnNonZeroExit = false
+          }
+        })
+        const unref = Effect.sync(() => {
+          if (isReferenced) {
+            childProcess.unref()
+            isReferenced = false
+            cleanupOnNonZeroExit = true
+          }
+          return reref
+        })
         const stdin = yield* setupChildStdin(cmd, childProcess, stdinConfig)
         const { all, stderr, stdout } = setupChildOutputStreams(cmd, childProcess, stdoutConfig, stderrConfig)
         const { getInputFd, getOutputFd } = yield* setupAdditionalFds(cmd, childProcess, resolvedAdditionalFds)
@@ -489,14 +537,15 @@ const make = Effect.gen(function*() {
           stderr,
           all,
           getInputFd,
-          getOutputFd
+          getOutputFd,
+          unref
         })
       }
       case "PipedCommand": {
         const { commands, pipeOptions } = flattenCommand(cmd)
         const [root, ...pipeline] = commands
 
-        let handle = spawnCommand(root)
+        const handles = [yield* spawnCommand(root)]
 
         for (let i = 0; i < pipeline.length; i++) {
           const command = pipeline[i]
@@ -505,7 +554,7 @@ const make = Effect.gen(function*() {
 
           // Get the appropriate stream from the source based on `from` option
           const sourceStream = Stream.unwrap(
-            Effect.map(handle, (h) => getSourceStream(h, options.from))
+            Effect.succeed(getSourceStream(handles[handles.length - 1], options.from))
           )
 
           // Determine where to pipe: stdin or custom fd
@@ -513,48 +562,73 @@ const make = Effect.gen(function*() {
 
           if (toOption === "stdin") {
             // Pipe to stdin (default behavior)
-            handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-              ...command.options,
-              stdin: { ...stdinConfig, stream: sourceStream }
-            }))
+            handles.push(
+              yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                ...command.options,
+                stdin: { ...stdinConfig, stream: sourceStream }
+              }))
+            )
           } else {
             // Pipe to custom fd (fd3, fd4, etc.)
             const fd = ChildProcess.parseFdName(toOption)
             if (Predicate.isNotUndefined(fd)) {
               const fdName = ChildProcess.fdName(fd) as `fd${number}`
               const existingFds = command.options.additionalFds ?? {}
-              handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-                ...command.options,
-                additionalFds: {
-                  ...existingFds,
-                  [fdName]: { type: "input" as const, stream: sourceStream }
-                }
-              }))
+              handles.push(
+                yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                  ...command.options,
+                  additionalFds: {
+                    ...existingFds,
+                    [fdName]: { type: "input" as const, stream: sourceStream }
+                  }
+                }))
+              )
             } else {
               // Invalid fd name, fall back to stdin
-              handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-                ...command.options,
-                stdin: { ...stdinConfig, stream: sourceStream }
-              }))
+              handles.push(
+                yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                  ...command.options,
+                  stdin: { ...stdinConfig, stream: sourceStream }
+                }))
+              )
             }
           }
         }
 
-        return yield* handle
+        const handle = handles[handles.length - 1]
+        const unref = Effect.gen(function*() {
+          const rerefs: Array<Effect.Effect<void, PlatformError.PlatformError>> = []
+          for (const handle of handles) {
+            rerefs.push(yield* handle.unref)
+          }
+          return Effect.forEach([...rerefs].reverse(), (reref) => reref, { discard: true })
+        })
+
+        return makeHandle({
+          pid: handle.pid,
+          exitCode: handle.exitCode,
+          isRunning: handle.isRunning,
+          kill: handle.kill,
+          stdin: handle.stdin,
+          stdout: handle.stdout,
+          stderr: handle.stderr,
+          all: handle.all,
+          getInputFd: handle.getInputFd,
+          getOutputFd: handle.getOutputFd,
+          unref
+        })
       }
     }
   })
 
-  return ChildProcessSpawner.of({
-    spawn: spawnCommand
-  })
+  return makeSpawner(spawnCommand)
 })
 
 /**
  * Layer providing the `NodeChildProcessSpawner` implementation.
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer: Layer.Layer<
   ChildProcessSpawner,
@@ -569,8 +643,8 @@ export const layer: Layer.Layer<
 /**
  * Result of flattening a pipeline of commands.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface FlattenedPipeline {
   readonly commands: Arr.NonEmptyReadonlyArray<ChildProcess.StandardCommand>
@@ -581,8 +655,8 @@ export interface FlattenedPipeline {
  * Flattens a `Command` into an array of `StandardCommand`s along with pipe
  * options for each connection.
  *
+ * @category utils
  * @since 4.0.0
- * @category Utilities
  */
 export const flattenCommand = (
   command: ChildProcess.Command

package/src/NodeClusterSocket.ts

@@ -1,8 +1,27 @@
 /**
- * @since 1.0.0
+ * Node TCP socket integration for Effect Cluster runner communication.
+ *
+ * This module provides the shared Node layers used by socket-based cluster
+ * transports: a client protocol that opens TCP sockets to runner addresses and
+ * a socket server that listens for incoming runner RPC traffic. It is useful
+ * when wiring Node or Node-compatible cluster runners, sharing the same socket
+ * implementation across platform packages, or building tests and deployments
+ * that need direct runner-to-runner RPC over TCP rather than HTTP.
+ *
+ * Cluster runners must advertise an address that peers can reach while the
+ * server may listen on a different address via `runnerListenAddress`, which is
+ * common behind containers, port mappings, or Kubernetes services. Serialization
+ * is supplied by the surrounding layer, and gossip, shard discovery, health
+ * checks, and storage-backed delivery are coordinated by the cluster services
+ * that use this transport. Keep those responsibilities separate when debugging:
+ * a reachable socket does not by itself guarantee that runner membership,
+ * shard ownership, or persisted message notification is current.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Runners from "effect/unstable/cluster/Runners"
 import * as ShardingConfig from "effect/unstable/cluster/ShardingConfig"
 import * as RpcClient from "effect/unstable/rpc/RpcClient"
@@ -13,8 +32,11 @@ import * as NodeSocket from "./NodeSocket.ts"
 import * as NodeSocketServer from "./NodeSocketServer.ts"
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the cluster `RpcClientProtocol` by opening TCP sockets to runner
+ * addresses and using the current RPC serialization service.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerClientProtocol: Layer.Layer<
   Runners.RpcClientProtocol,
@@ -39,8 +61,11 @@ export const layerClientProtocol: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the socket server used by cluster runners, listening on
+ * `ShardingConfig.runnerListenAddress` or `runnerAddress`.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerSocketServer: Layer.Layer<
   SocketServer.SocketServer,
@@ -48,9 +73,9 @@ export const layerSocketServer: Layer.Layer<
   ShardingConfig.ShardingConfig
 > = Effect.gen(function*() {
   const config = yield* ShardingConfig.ShardingConfig
-  const listenAddress = config.runnerListenAddress ?? config.runnerAddress
-  if (listenAddress === undefined) {
+  const listenAddress = Option.orElse(config.runnerListenAddress, () => config.runnerAddress)
+  if (Option.isNone(listenAddress)) {
     return yield* Effect.die("layerSocketServer: ShardingConfig.runnerListenAddress is None")
   }
-  return NodeSocketServer.layer(listenAddress)
+  return NodeSocketServer.layer(listenAddress.value)
 }).pipe(Layer.unwrap)

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"
@@ -232,7 +250,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 +303,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 +486,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 +549,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 +590,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 +647,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,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>,
@@ -37,10 +66,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 +77,6 @@ export const runMain: {
 
   function onSigint() {
     receivedSignal = true
-    process.removeListener("SIGINT", onSigint)
-    process.removeListener("SIGTERM", onSigint)
     fiber.interruptUnsafe(fiber.id)
   }