@effect/platform-node-shared 4.0.0-beta.9 → 4.0.0-beta.91

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @since 4.0.0
+ */
+// @barrel: Auto-generated exports. Do not edit manually.
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./NodeClusterSocket.js";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./NodeCrypto.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./NodeFileSystem.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./NodePath.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./NodeRuntime.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./NodeSink.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./NodeSocket.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./NodeSocketServer.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./NodeStdio.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./NodeStream.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./NodeTerminal.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["NodeChildProcessSpawner","NodeClusterSocket","NodeCrypto","NodeFileSystem","NodePath","NodeRuntime","NodeSink","NodeSocket","NodeSocketServer","NodeStdio","NodeStream","NodeTerminal"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,uBAAuB,MAAM,8BAA8B;AAEvE;;;AAGA,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAE3D;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/platform-node-shared",
   "type": "module",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.0-beta.91",
   "license": "MIT",
   "description": "Unified interfaces for common platform-specific services",
   "homepage": "https://effect.website",
@@ -46,18 +46,19 @@
     "provenance": true
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.9"
+    "effect": "^4.0.0-beta.91"
   },
   "devDependencies": {
-    "@types/node": "^25.2.0",
-    "tar": "^7.5.7",
-    "effect": "^4.0.0-beta.9"
+    "@types/node": "^25.7.0",
+    "tar": "^7.5.15",
+    "effect": "^4.0.0-beta.91"
   },
   "dependencies": {
     "@types/ws": "^8.18.1",
-    "ws": "^8.19.0"
+    "ws": "^8.20.0"
   },
   "scripts": {
+    "codegen": "effect-utils codegen",
     "build": "tsc -b tsconfig.json && pnpm babel",
     "build:tsgo": "tsgo -b tsconfig.json && pnpm babel",
     "babel": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",

package/src/NodeChildProcessSpawner.ts

@@ -1,5 +1,19 @@
 /**
- * Node.js implementation of `ChildProcessSpawner`.
+ * Shared Node.js implementation of the child process spawner service.
+ *
+ * This module adapts `node:child_process.spawn` to the Effect
+ * `ChildProcessSpawner` service. Provide {@link layer} to run `ChildProcess`
+ * commands in Node-compatible runtimes: commands get scoped process handles
+ * with stdin sinks, stdout and stderr streams, exit-code waiting,
+ * interruption-time cleanup, process killing, and custom file-descriptor pipes.
+ *
+ * The implementation sits below the command-building API. It validates and
+ * resolves `cwd` through the Effect `FileSystem` and `Path` services,
+ * translates Node errno failures to `PlatformError`, and uses scopes to
+ * terminate referenced children when the owning effect is interrupted or
+ * finalized. Pipelines are flattened by {@link flattenCommand} and spawned one
+ * process at a time, wiring the selected source stream (`stdout`, `stderr`,
+ * `all`, or `fdN`) to the destination `stdin` or `fdN`.
  *
  * @since 4.0.0
  */
@@ -17,7 +31,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 +357,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 +405,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 +450,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 +477,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 +494,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 +551,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 +568,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 +576,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.
+ * Layer that provides the `NodeChildProcessSpawner` implementation.
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer: Layer.Layer<
   ChildProcessSpawner,
@@ -569,8 +657,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 +669,8 @@ export interface FlattenedPipeline {
  * Flattens a `Command` into an array of `StandardCommand`s along with pipe
  * options for each connection.
  *
+ * @category transforming
  * @since 4.0.0
- * @category Utilities
  */
 export const flattenCommand = (
   command: ChildProcess.Command

package/src/NodeClusterSocket.ts

@@ -1,8 +1,16 @@
 /**
- * @since 1.0.0
+ * Node TCP socket transport for Effect Cluster runner-to-runner RPC.
+ *
+ * This module provides the shared Node layers used by socket-based cluster
+ * transports. `layerClientProtocol` opens TCP sockets to peer runner addresses
+ * and wraps them in the current RPC serialization protocol. `layerSocketServer`
+ * exposes the socket server that receives incoming runner RPC traffic.
+ *
+ * @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 +21,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 +50,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 +62,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,60 @@
+/**
+ * Node-compatible implementation of Effect's `Crypto` service.
+ *
+ * This module builds the service from `node:crypto`, using `randomBytes` for
+ * random data and `createHash` for supported digest algorithms. It exports
+ * `make` as the concrete service value and `layer` for providing it through
+ * Effect context.
+ *
+ * @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
+})
+
+/**
+ * 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,13 @@
 /**
- * @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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
@@ -232,7 +240,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 +293,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 +476,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 +539,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 +580,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 +637,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,12 @@
 /**
- * @since 1.0.0
+ * Node-backed provider for Effect's `Path` service.
+ *
+ * This module turns Node's `node:path` and `node:url` APIs into `Path` layers.
+ * `layer` uses the host platform path implementation, while `layerPosix` and
+ * `layerWin32` provide fixed POSIX and Windows variants. All three layers also
+ * include helpers for converting between file paths and file URLs.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -31,8 +38,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 +52,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 +66,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,