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

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>
@@ -66,6 +96,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,23 @@
 /**
- * @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"
+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 +27,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 +62,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 +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>,
@@ -89,7 +114,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 +138,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 +191,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 +229,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 +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
@@ -230,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,7 +1,25 @@
 /**
- * @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"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
@@ -11,7 +29,6 @@ import * as Function from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as References from "effect/References"
 import * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Socket from "effect/unstable/socket/Socket"
 import * as SocketServer from "effect/unstable/socket/SocketServer"
 import type * as Http from "node:http"
@@ -20,17 +37,24 @@ 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 ServiceMap.Service<
+export class IncomingMessage extends Context.Service<
   IncomingMessage,
   Http.IncomingMessage
 >()("@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
@@ -69,7 +93,7 @@ export const make = Effect.fnUntraced(function*(
 
   const run = Effect.fnUntraced(function*<R, E, _>(handler: (socket: Socket.Socket) => Effect.Effect<_, E, R>) {
     const scope = yield* Scope.make()
-    const services = ServiceMap.omit(Scope.Scope)(yield* Effect.services<R>()) as ServiceMap.ServiceMap<R>
+    const services = Context.omit(Scope.Scope)(yield* Effect.context<R>()) as Context.Context<R>
     const trackFiber = Fiber.runIn(scope)
     const prevOnConnection = onConnection
     onConnection = function(conn: Net.Socket) {
@@ -109,7 +133,7 @@ export const make = Effect.fnUntraced(function*(
         ),
         Effect.flatMap(handler),
         Effect.catchCause(reportUnhandledError),
-        Effect.runForkWith(ServiceMap.add(services, NodeSocket.NetSocket, conn)),
+        Effect.runForkWith(Context.add(services, NodeSocket.NetSocket, conn)),
         trackFiber
       )
     }
@@ -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>
@@ -202,7 +233,7 @@ export const makeWebSocket: (
 
   const run = Effect.fnUntraced(function*<R, E, _>(handler: (socket: Socket.Socket) => Effect.Effect<_, E, R>) {
     const scope = yield* Scope.make()
-    const services = ServiceMap.omit(Scope.Scope)(yield* Effect.services<R>()) as ServiceMap.ServiceMap<R>
+    const services = Context.omit(Scope.Scope)(yield* Effect.context<R>()) as Context.Context<R>
     const trackFiber = Fiber.runIn(scope)
     const prevOnConnection = onConnection
     onConnection = function(conn: globalThis.WebSocket, req: Http.IncomingMessage) {
@@ -221,7 +252,7 @@ export const makeWebSocket: (
         ),
         Effect.flatMap(handler),
         Effect.catchCause(reportUnhandledError),
-        Effect.runForkWith(ServiceMap.makeUnsafe(map)),
+        Effect.runForkWith(Context.makeUnsafe(map)),
         trackFiber
       )
     }
@@ -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,6 +1,23 @@
 /**
- * @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"
 import { systemError } from "effect/PlatformError"
 import * as Stdio from "effect/Stdio"
@@ -8,32 +25,41 @@ 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,
   Stdio.make({
-    stdout: fromWritable({
-      evaluate: () => process.stdout,
-      onError: (cause) =>
-        systemError({
-          module: "Stdio",
-          method: "stdout",
-          _tag: "Unknown",
-          cause
-        })
-    }),
-    stderr: fromWritable({
-      evaluate: () => process.stderr,
-      onError: (cause) =>
-        systemError({
-          module: "Stdio",
-          method: "stderr",
-          _tag: "Unknown",
-          cause
-        })
-    }),
+    args: Effect.sync(() => process.argv.slice(2)),
+    stdout: (options) =>
+      fromWritable({
+        evaluate: () => process.stdout,
+        onError: (cause) =>
+          systemError({
+            module: "Stdio",
+            method: "stdout",
+            _tag: "Unknown",
+            cause
+          }),
+        endOnDone: options?.endOnDone ?? false
+      }),
+    stderr: (options) =>
+      fromWritable({
+        evaluate: () => process.stderr,
+        onError: (cause) =>
+          systemError({
+            module: "Stdio",
+            method: "stderr",
+            _tag: "Unknown",
+            cause
+          }),
+        endOnDone: options?.endOnDone ?? false
+      }),
     stdin: fromReadable({
       evaluate: () => process.stdin,
       onError: (cause) =>