@effect/platform-node-shared 4.0.0-beta.8 → 4.0.0-beta.81

package/src/NodeRuntime.ts

@@ -1,17 +1,32 @@
 /**
- * @since 1.0.0
+ * Node-compatible process runner for Effect programs.
+ *
+ * This module provides the shared `runMain` implementation used by
+ * Node-compatible platform packages. It runs one Effect as the main process
+ * fiber, interrupts that fiber on `SIGINT` or `SIGTERM`, and delegates final
+ * exit-code handling to the configured teardown.
+ *
+ * @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 +35,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 +56,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 +67,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,13 @@
 /**
- * @since 1.0.0
+ * Sink adapters for writing Effect chunks into Node writable streams.
+ *
+ * `fromWritable` creates a `Sink`, `fromWritableChannel` creates a lower-level
+ * `Channel`, and `pullIntoWritable` writes from an existing pull loop. All
+ * three adapters respect writable-stream backpressure, map writable errors with
+ * the supplied `onError` function, and can end the writable when the upstream
+ * data is done.
+ *
+ * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "effect/Array"
 import * as Cause from "effect/Cause"
@@ -11,8 +19,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 +37,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 +58,20 @@ export const fromWritableChannel = <IE, E, A = Uint8Array | string>(
   })
 
 /**
- * @since 1.0.0
+ * Writes Effect chunks into a Node writable stream.
+ *
+ * **When to use**
+ *
+ * Use to implement custom Node stream adapters that already have an upstream
+ * pull and need direct control over a writable stream.
+ *
+ * **Details**
+ *
+ * The loop waits for `drain` when needed, fails on writable errors, and ends
+ * the writable on upstream completion unless `endOnDone` is `false`.
+ *
+ * @category converting
+ * @since 4.0.0
  */
 export const pullIntoWritable = <A, IE, E>(options: {
   readonly pull: Pull.Pull<NonEmptyReadonlyArray<A>, IE, unknown>
@@ -66,6 +95,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,16 @@
 /**
- * @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 also exposes the current underlying `NetSocket` service for code
+ * running inside a socket handler and re-exports the `ws` package namespace.
+ *
+ * @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 +20,41 @@ 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
- * @category tags
+ * Service tag for the underlying Node `net.Socket` associated with the current
+ * socket connection.
+ *
+ * @category services
+ * @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 Node TCP connection as an Effect socket.
+ *
+ * **When to use**
+ *
+ * Use to create a scoped `Socket.Socket` from Node `net.createConnection`.
+ *
+ * **Details**
+ *
+ * Supports `openTimeout` and closes or destroys the underlying 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,17 @@
 /**
- * @since 1.0.0
+ * Node socket server adapters for Effect's unstable socket server API.
+ *
+ * This module turns `node:net` TCP or Unix-domain servers and `ws` WebSocket
+ * servers into scoped `SocketServer.SocketServer` services. Use the TCP
+ * constructors when handlers should receive a `Socket.Socket` backed by a Node
+ * `net.Socket`; use the WebSocket constructors when handlers should receive a
+ * `Socket.Socket` backed by `ws` and have access to the per-connection
+ * WebSocket and `IncomingMessage` services.
+ *
+ * @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 +21,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 +29,24 @@ import * as NodeSocket from "./NodeSocket.ts"
 import { NodeWS } from "./NodeSocket.ts"
 
 /**
- * @since 1.0.0
- * @category tags
+ * Service tag for the Node `IncomingMessage` associated with the current
+ * WebSocket server connection.
+ *
+ * @category services
+ * @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 +85,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 +125,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 +160,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 +174,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 +225,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 +244,7 @@ export const makeWebSocket: (
         ),
         Effect.flatMap(handler),
         Effect.catchCause(reportUnhandledError),
-        Effect.runForkWith(ServiceMap.makeUnsafe(map)),
+        Effect.runForkWith(Context.makeUnsafe(map)),
         trackFiber
       )
     }
@@ -255,8 +278,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,15 @@
 /**
- * @since 1.0.0
+ * Shared Node.js implementation of the Effect `Stdio` service.
+ *
+ * `NodeStdio` provides {@link Stdio.Stdio} from the current Node process. The
+ * exported {@link layer} reads command-line arguments from `process.argv`,
+ * consumes input from `process.stdin`, and writes normal and error output to
+ * `process.stdout` and `process.stderr`. Standard input remains open, and
+ * standard output and error output are not ended unless requested.
+ *
+ * @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 +17,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) =>