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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/dist/Mime.d.ts +3 -3
  2. package/dist/Mime.js +3 -3
  3. package/dist/NodeChildProcessSpawner.d.ts +1 -1
  4. package/dist/NodeChildProcessSpawner.js +1 -1
  5. package/dist/NodeClusterHttp.d.ts +49 -7
  6. package/dist/NodeClusterHttp.d.ts.map +1 -1
  7. package/dist/NodeClusterHttp.js +20 -10
  8. package/dist/NodeClusterHttp.js.map +1 -1
  9. package/dist/NodeClusterSocket.d.ts +57 -11
  10. package/dist/NodeClusterSocket.d.ts.map +1 -1
  11. package/dist/NodeClusterSocket.js +57 -11
  12. package/dist/NodeClusterSocket.js.map +1 -1
  13. package/dist/NodeCrypto.d.ts +10 -0
  14. package/dist/NodeCrypto.d.ts.map +1 -0
  15. package/dist/NodeCrypto.js +14 -0
  16. package/dist/NodeCrypto.js.map +1 -0
  17. package/dist/NodeFileSystem.d.ts +4 -2
  18. package/dist/NodeFileSystem.d.ts.map +1 -1
  19. package/dist/NodeFileSystem.js +22 -3
  20. package/dist/NodeFileSystem.js.map +1 -1
  21. package/dist/NodeHttpClient.d.ts +102 -24
  22. package/dist/NodeHttpClient.d.ts.map +1 -1
  23. package/dist/NodeHttpClient.js +124 -28
  24. package/dist/NodeHttpClient.js.map +1 -1
  25. package/dist/NodeHttpIncomingMessage.d.ts +30 -9
  26. package/dist/NodeHttpIncomingMessage.d.ts.map +1 -1
  27. package/dist/NodeHttpIncomingMessage.js +34 -8
  28. package/dist/NodeHttpIncomingMessage.js.map +1 -1
  29. package/dist/NodeHttpPlatform.d.ts +10 -4
  30. package/dist/NodeHttpPlatform.d.ts.map +1 -1
  31. package/dist/NodeHttpPlatform.js +34 -7
  32. package/dist/NodeHttpPlatform.js.map +1 -1
  33. package/dist/NodeHttpServer.d.ts +56 -16
  34. package/dist/NodeHttpServer.d.ts.map +1 -1
  35. package/dist/NodeHttpServer.js +117 -49
  36. package/dist/NodeHttpServer.js.map +1 -1
  37. package/dist/NodeHttpServerRequest.d.ts +29 -3
  38. package/dist/NodeHttpServerRequest.d.ts.map +1 -1
  39. package/dist/NodeHttpServerRequest.js +9 -2
  40. package/dist/NodeHttpServerRequest.js.map +1 -1
  41. package/dist/NodeMultipart.d.ts +32 -4
  42. package/dist/NodeMultipart.d.ts.map +1 -1
  43. package/dist/NodeMultipart.js +32 -4
  44. package/dist/NodeMultipart.js.map +1 -1
  45. package/dist/NodePath.d.ts +15 -6
  46. package/dist/NodePath.d.ts.map +1 -1
  47. package/dist/NodePath.js +30 -7
  48. package/dist/NodePath.js.map +1 -1
  49. package/dist/NodeRedis.d.ts +38 -9
  50. package/dist/NodeRedis.d.ts.map +1 -1
  51. package/dist/NodeRedis.js +41 -12
  52. package/dist/NodeRedis.js.map +1 -1
  53. package/dist/NodeRuntime.d.ts +27 -36
  54. package/dist/NodeRuntime.d.ts.map +1 -1
  55. package/dist/NodeRuntime.js +24 -13
  56. package/dist/NodeRuntime.js.map +1 -1
  57. package/dist/NodeServices.d.ts +29 -5
  58. package/dist/NodeServices.d.ts.map +1 -1
  59. package/dist/NodeServices.js +7 -3
  60. package/dist/NodeServices.js.map +1 -1
  61. package/dist/NodeSink.d.ts +2 -2
  62. package/dist/NodeSink.js +2 -2
  63. package/dist/NodeSocket.d.ts +18 -3
  64. package/dist/NodeSocket.d.ts.map +1 -1
  65. package/dist/NodeSocket.js +36 -4
  66. package/dist/NodeSocket.js.map +1 -1
  67. package/dist/NodeSocketServer.d.ts +2 -2
  68. package/dist/NodeSocketServer.js +2 -2
  69. package/dist/NodeStdio.d.ts +5 -2
  70. package/dist/NodeStdio.d.ts.map +1 -1
  71. package/dist/NodeStdio.js +22 -3
  72. package/dist/NodeStdio.js.map +1 -1
  73. package/dist/NodeStream.d.ts +2 -2
  74. package/dist/NodeStream.js +2 -2
  75. package/dist/NodeTerminal.d.ts +8 -2
  76. package/dist/NodeTerminal.d.ts.map +1 -1
  77. package/dist/NodeTerminal.js +19 -3
  78. package/dist/NodeTerminal.js.map +1 -1
  79. package/dist/NodeWorker.d.ts +9 -2
  80. package/dist/NodeWorker.d.ts.map +1 -1
  81. package/dist/NodeWorker.js +31 -6
  82. package/dist/NodeWorker.js.map +1 -1
  83. package/dist/NodeWorkerRunner.d.ts +5 -1
  84. package/dist/NodeWorkerRunner.d.ts.map +1 -1
  85. package/dist/NodeWorkerRunner.js +27 -5
  86. package/dist/NodeWorkerRunner.js.map +1 -1
  87. package/dist/Undici.d.ts +3 -3
  88. package/dist/Undici.js +3 -3
  89. package/dist/index.d.ts +376 -24
  90. package/dist/index.d.ts.map +1 -1
  91. package/dist/index.js +376 -24
  92. package/dist/index.js.map +1 -1
  93. package/package.json +9 -9
  94. package/src/Mime.ts +3 -3
  95. package/src/NodeChildProcessSpawner.ts +1 -1
  96. package/src/NodeClusterHttp.ts +54 -11
  97. package/src/NodeClusterSocket.ts +57 -11
  98. package/src/NodeCrypto.ts +16 -0
  99. package/src/NodeFileSystem.ts +22 -3
  100. package/src/NodeHttpClient.ts +132 -33
  101. package/src/NodeHttpIncomingMessage.ts +42 -12
  102. package/src/NodeHttpPlatform.ts +35 -6
  103. package/src/NodeHttpServer.ts +139 -53
  104. package/src/NodeHttpServerRequest.ts +29 -3
  105. package/src/NodeMultipart.ts +32 -4
  106. package/src/NodePath.ts +30 -7
  107. package/src/NodeRedis.ts +43 -14
  108. package/src/NodeRuntime.ts +42 -37
  109. package/src/NodeServices.ts +31 -5
  110. package/src/NodeSink.ts +2 -2
  111. package/src/NodeSocket.ts +41 -4
  112. package/src/NodeSocketServer.ts +2 -2
  113. package/src/NodeStdio.ts +22 -3
  114. package/src/NodeStream.ts +2 -2
  115. package/src/NodeTerminal.ts +19 -3
  116. package/src/NodeWorker.ts +31 -6
  117. package/src/NodeWorkerRunner.ts +27 -5
  118. package/src/Undici.ts +3 -3
  119. package/src/index.ts +377 -24
package/dist/index.d.ts CHANGED
@@ -1,102 +1,454 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
  /**
5
- * @since 1.0.0
5
+ * @since 4.0.0
6
6
  */
7
7
  export * as Mime from "./Mime.ts";
8
8
  /**
9
9
  * Node.js implementation of `ChildProcessSpawner`.
10
10
  *
11
- * @since 1.0.0
11
+ * @since 4.0.0
12
12
  */
13
13
  export * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.ts";
14
14
  /**
15
- * @since 1.0.0
15
+ * The `NodeClusterHttp` module provides the Node.js HTTP and WebSocket
16
+ * transports for Effect Cluster runners. It wires `HttpRunner` to the Node HTTP
17
+ * server, supplies Undici and WebSocket client protocols, and builds a complete
18
+ * sharding layer with serialization, runner health, runner storage, and message
19
+ * storage.
20
+ *
21
+ * **Common tasks**
22
+ *
23
+ * - Run a Node process as a cluster runner over HTTP or WebSocket with
24
+ * {@link layer}
25
+ * - Connect a client-only process to an existing HTTP cluster without starting
26
+ * a runner server
27
+ * - Use SQL-backed storage for durable multi-process clusters, `local` storage
28
+ * for short-lived development, or `byo` storage when the deployment owns the
29
+ * persistence boundary
30
+ * - Check runner health with protocol pings or Kubernetes pod readiness through
31
+ * {@link layerK8sHttpClient}
32
+ *
33
+ * **Gotchas**
34
+ *
35
+ * - `runnerAddress` is the host and port advertised to other runners; set
36
+ * `runnerListenAddress` when the local bind address differs from the
37
+ * externally reachable address
38
+ * - The HTTP and WebSocket transports serve runner RPCs at the default
39
+ * `HttpRunner` route, so proxies and load balancers must preserve the path
40
+ * and allow WebSocket upgrades when `transport` is `"websocket"`
41
+ * - `clientOnly` does not start an HTTP server or receive shard assignments
42
+ * - SQL storage is the default; `local` storage is in-memory/noop and `byo`
43
+ * requires the surrounding application to provide both runner and message
44
+ * storage services
45
+ * - Ping health checks use the selected transport and serialization, so route,
46
+ * port, proxy, or codec mismatches can make a runner appear unhealthy
47
+ *
48
+ * @since 4.0.0
16
49
  */
17
50
  export * as NodeClusterHttp from "./NodeClusterHttp.ts";
18
51
  /**
19
- * @since 1.0.0
52
+ * The `NodeClusterSocket` module provides the Node.js socket transport for
53
+ * Effect Cluster runners. It wires `SocketRunner` to Node TCP sockets, supplies
54
+ * RPC client and server protocol layers, and builds a complete sharding layer
55
+ * with serialization, runner health, runner storage, and message storage.
56
+ *
57
+ * **Common tasks**
58
+ *
59
+ * - Run a Node process as a cluster runner over raw TCP sockets with
60
+ * {@link layer}
61
+ * - Connect a client-only process to an existing socket cluster without
62
+ * starting a runner server
63
+ * - Use SQL-backed storage for durable multi-process clusters, `local` storage
64
+ * for short-lived development, or `byo` storage when the deployment owns the
65
+ * persistence boundary
66
+ * - Check runner health with socket pings or Kubernetes pod readiness through
67
+ * {@link layerK8sHttpClient}
68
+ *
69
+ * **Gotchas**
70
+ *
71
+ * - `runnerAddress` is the host and port advertised to other runners; set
72
+ * `runnerListenAddress` when the local bind address differs from the
73
+ * externally reachable address
74
+ * - The socket transport is point-to-point RPC, not cluster gossip: runner
75
+ * membership, shard ownership, and persisted delivery are coordinated through
76
+ * `RunnerStorage`, `MessageStorage`, and `RunnerHealth`
77
+ * - `clientOnly` does not start a socket server or receive shard assignments
78
+ * - Ping health checks use the same socket protocol, so unreachable ports,
79
+ * firewalls, or serialization mismatches can make a runner appear unhealthy
80
+ *
81
+ * @since 4.0.0
20
82
  */
21
83
  export * as NodeClusterSocket from "./NodeClusterSocket.ts";
22
84
  /**
85
+ * Node.js platform Crypto service layer.
86
+ *
23
87
  * @since 1.0.0
24
88
  */
89
+ export * as NodeCrypto from "./NodeCrypto.ts";
90
+ /**
91
+ * Provides the Node.js `FileSystem` layer for Effect programs.
92
+ *
93
+ * Use this module when a Node application, CLI, script, or test needs to
94
+ * satisfy the `FileSystem` service with real filesystem access for reading and
95
+ * writing files, creating directories and temporary files, inspecting metadata,
96
+ * managing links, or watching paths for changes.
97
+ *
98
+ * This module only exposes the Node-backed layer; filesystem operations are
99
+ * accessed through the `FileSystem` service from `effect/FileSystem`. Provide
100
+ * `NodeFileSystem.layer` at the edge of the program, or use
101
+ * `NodeServices.layer` when you also want the standard Node path, stdio,
102
+ * terminal, and child process services. The implementation is shared with
103
+ * other Node-compatible platform packages, so optional services such as
104
+ * `FileSystem.WatchBackend` are honored when present; otherwise file watching
105
+ * follows Node's `node:fs.watch` behavior. Paths are interpreted by Node, so
106
+ * relative paths use the current working directory and platform path rules.
107
+ *
108
+ * @since 4.0.0
109
+ */
25
110
  export * as NodeFileSystem from "./NodeFileSystem.ts";
26
111
  /**
27
- * @since 1.0.0
112
+ * Node.js implementations of the Effect `HttpClient`.
113
+ *
114
+ * This module provides the Node-specific layers and constructors for sending
115
+ * Effect HTTP client requests. It re-exports the fetch-based client for
116
+ * programs that want to use `globalThis.fetch`, provides an Undici-backed
117
+ * client for applications that need Undici dispatcher control, and provides a
118
+ * lower-level `node:http` / `node:https` client for integrations that need
119
+ * native Node agent configuration.
120
+ *
121
+ * Use these clients in server-side applications, CLIs, tests, and integrations
122
+ * where requests should participate in Effect resource management, interruption,
123
+ * streaming, and typed transport / decode errors. The Undici path sends each
124
+ * request through the current `Dispatcher`; `layerUndici` owns a scoped
125
+ * `Agent`, while `dispatcherLayerGlobal` uses Undici's process-global dispatcher
126
+ * without destroying it. The `node:http` path uses separate scoped HTTP and
127
+ * HTTPS agents, making it the right choice when native agent options such as
128
+ * TLS, proxy, keep-alive, or socket behavior need to be configured directly.
129
+ *
130
+ * The backends are not completely interchangeable. Fetch, Undici, and
131
+ * `node:http` expose different agent and dispatcher hooks, body implementations,
132
+ * abort behavior, upgrade support, and response body readers. This module
133
+ * converts Effect request bodies to the selected runtime representation:
134
+ * streams remain streaming, `FormData` may contribute generated content headers,
135
+ * and body read failures are reported as `HttpClientError` decode or transport
136
+ * errors.
137
+ *
138
+ * @since 4.0.0
28
139
  */
29
140
  export * as NodeHttpClient from "./NodeHttpClient.ts";
30
141
  /**
31
- * @since 1.0.0
142
+ * Utilities for adapting Node `http.IncomingMessage` values to the Effect HTTP
143
+ * incoming message interface used by the platform Node server and client
144
+ * implementations.
145
+ *
146
+ * This module is useful when code needs to keep access to Node's request or
147
+ * response object while also exposing Effect's typed headers, remote address,
148
+ * body decoders, and stream interface. The body helpers consume Node's readable
149
+ * stream, cache decoded text and array-buffer results, and honor the
150
+ * `HttpIncomingMessage.MaxBodySize` fiber ref. Prefer a single body access
151
+ * strategy per message: raw `stream` access is not cached, and Node request
152
+ * bodies cannot be replayed once the underlying stream has been consumed.
153
+ *
154
+ * @since 4.0.0
32
155
  */
33
156
  export * as NodeHttpIncomingMessage from "./NodeHttpIncomingMessage.ts";
34
157
  /**
35
- * @since 1.0.0
158
+ * Node.js implementation of the Effect HTTP platform service.
159
+ *
160
+ * This module connects the portable `HttpPlatform` file response helpers to
161
+ * Node runtime primitives. It is used by Node HTTP servers and static file
162
+ * handlers when returning local files, public assets, downloads, byte ranges,
163
+ * or Web `File` values as `HttpServerResponse` bodies.
164
+ *
165
+ * Path-based responses are served with `node:fs.createReadStream`; Web `File`
166
+ * responses are bridged with `Readable.fromWeb`. The implementation fills in
167
+ * `content-type` from `Mime`, falls back to `application/octet-stream`, and
168
+ * writes the `content-length` for the selected range or whole file. Node's
169
+ * stream `end` option is inclusive, so the platform converts Effect's half-open
170
+ * range before reading. Empty bodies use an empty readable stream.
171
+ *
172
+ * Provide `layer` at the Node runtime edge when file responses, static serving,
173
+ * or response bodies created from files need real filesystem and ETag support.
174
+ * These responses are raw Node streams, so they are intended for the Node HTTP
175
+ * server adapter; keep files available until the response body has been
176
+ * consumed and prefer the portable `HttpServerResponse` constructors when a
177
+ * response does not depend on Node file or stream behavior.
178
+ *
179
+ * @since 4.0.0
36
180
  */
37
181
  export * as NodeHttpPlatform from "./NodeHttpPlatform.ts";
38
182
  /**
39
- * @since 1.0.0
183
+ * Node.js implementation of the Effect `HttpServer`.
184
+ *
185
+ * This module adapts a supplied Node `http.Server` into Effect's
186
+ * platform-independent HTTP server service. It starts the server with Node
187
+ * `listen` options, converts `request` events into `HttpServerRequest` values,
188
+ * writes `HttpServerResponse` bodies through Node's `ServerResponse`, and
189
+ * handles `upgrade` events by exposing the upgraded socket through
190
+ * `HttpServerRequest.upgrade`.
191
+ *
192
+ * Common use cases include serving an Effect HTTP application with {@link layer}
193
+ * or {@link layerConfig}, embedding request or upgrade handlers into an
194
+ * existing Node server with {@link makeHandler} and {@link makeUpgradeHandler},
195
+ * and using {@link layerTest} for integration tests that need an ephemeral
196
+ * listening port and a client pointed at it.
197
+ *
198
+ * Listen options are passed directly to Node, so host, port, backlog, and Unix
199
+ * socket path behavior follow `node:http`. The server begins listening when the
200
+ * `HttpServer` is acquired, and handlers are installed when `serve` is run.
201
+ * Request fibers are interrupted with `ClientAbort` when the client disconnects
202
+ * before a response finishes. WebSocket support only applies to Node `upgrade`
203
+ * requests, and ordinary HTTP requests fail if their application attempts to use
204
+ * `HttpServerRequest.upgrade`.
205
+ *
206
+ * Scope ownership is important: the server is closed when the acquiring scope
207
+ * finalizes, while each `serve` call installs its own request and upgrade
208
+ * listeners and removes them on finalization. Unless preemptive shutdown is
209
+ * disabled, finalizing a serve scope also starts a graceful server close, using
210
+ * the configured timeout or the default timeout.
211
+ *
212
+ * @since 4.0.0
40
213
  */
41
214
  export * as NodeHttpServer from "./NodeHttpServer.ts";
42
215
  /**
43
- * @since 1.0.0
216
+ * Accessors for the Node.js objects backing a platform Node
217
+ * `HttpServerRequest`.
218
+ *
219
+ * Use this module at interop boundaries when an Effect HTTP handler needs the
220
+ * original `http.IncomingMessage` or `http.ServerResponse` for APIs that are
221
+ * specific to Node, such as existing middleware, socket inspection, raw stream
222
+ * piping, or response customization that cannot be expressed with the portable
223
+ * `HttpServerRequest` and `HttpServerResponse` interfaces.
224
+ *
225
+ * The returned request is the original Node request supplied to the server. It
226
+ * does not reflect Effect request overrides made by middleware, such as a
227
+ * rewritten URL, adjusted headers, or a substituted remote address. Its body is
228
+ * also Node's one-shot readable stream, so avoid mixing raw stream consumption
229
+ * with Effect body, multipart, or stream helpers unless ownership of the body
230
+ * is clear. The returned response is the Node response owned by the platform
231
+ * server; writing to it directly bypasses the usual Effect response writer and
232
+ * must be coordinated carefully to avoid duplicate writes. Upgrade requests may
233
+ * create that response lazily when it is first requested.
234
+ *
235
+ * @since 4.0.0
44
236
  */
45
237
  export * as NodeHttpServerRequest from "./NodeHttpServerRequest.ts";
46
238
  /**
47
- * @since 1.0.0
239
+ * Node-specific helpers for parsing HTTP `multipart/form-data` request bodies.
240
+ *
241
+ * This module adapts a Node `Readable` request body plus its incoming headers
242
+ * into the shared `Multipart` model. Use `stream` when an HTTP server route
243
+ * wants to handle form fields and uploaded files incrementally, for example API
244
+ * endpoints that validate text fields while piping file parts to storage. Use
245
+ * `persisted` when the whole form should be collected into a record and uploaded
246
+ * files should be written into scoped temporary files through the current
247
+ * `FileSystem` and `Path` services.
248
+ *
249
+ * Node request bodies are one-shot streams, so consume either `stream` or
250
+ * `persisted`, and make sure file parts are drained, piped, or otherwise
251
+ * deliberately handled. `contentEffect` loads a file into memory and should be
252
+ * reserved for small uploads. Persisted paths live only for the surrounding
253
+ * `Scope`, and filenames supplied by clients should be treated as metadata, not
254
+ * trusted filesystem paths.
255
+ *
256
+ * @since 4.0.0
48
257
  */
49
258
  export * as NodeMultipart from "./NodeMultipart.ts";
50
259
  /**
51
- * @since 1.0.0
260
+ * Node.js layers for Effect's `Path` service.
261
+ *
262
+ * Use this module when an Effect program running on Node needs path operations
263
+ * from the `Path` service, such as joining and normalizing filesystem
264
+ * locations, resolving configuration or static asset paths, working with CLI
265
+ * path arguments, or converting between file paths and `file:` URLs.
266
+ *
267
+ * `layer` follows the host platform's `node:path` semantics. Use `layerPosix`
268
+ * or `layerWin32` when code needs stable POSIX or Windows behavior regardless
269
+ * of the operating system. These layers provide only path manipulation; they do
270
+ * not read the filesystem or validate that paths exist. `NodeServices.layer`
271
+ * already includes the default Node path layer, so provide this module directly
272
+ * when you want the narrower service or one of the platform-specific variants.
273
+ *
274
+ * @since 4.0.0
52
275
  */
53
276
  export * as NodePath from "./NodePath.ts";
54
277
  /**
55
- * @since 1.0.0
278
+ * Node.js Redis integration backed by `ioredis`.
279
+ *
280
+ * This module provides scoped layers that create an `ioredis` client and expose
281
+ * both the low-level `Redis` service used by Effect persistence modules and the
282
+ * `NodeRedis` service for direct access to the underlying client. It is useful
283
+ * for Node applications that want Redis-backed persistence, persisted queues,
284
+ * distributed rate limiting, or custom Redis commands alongside the Effect
285
+ * services that build on Redis.
286
+ *
287
+ * The client is acquired when the layer is built and closed with `quit` when
288
+ * the layer scope ends, so install the layer at the lifetime you want for the
289
+ * connection and pass `ioredis` options, or `layerConfig`, for connection,
290
+ * TLS, database, retry, and reconnect settings. Persistence and rate limiter
291
+ * stores build their own keys and Lua scripts on top of this service; choose
292
+ * stable prefixes and store ids to avoid collisions, account for persisted
293
+ * values that may fail to decode after schema changes, and avoid unbounded
294
+ * high-cardinality rate-limit keys unless you have a cleanup or bounding
295
+ * strategy.
296
+ *
297
+ * @since 4.0.0
56
298
  */
57
299
  export * as NodeRedis from "./NodeRedis.ts";
58
300
  /**
59
- * @since 1.0.0
301
+ * Node.js entry-point helpers for running Effect programs.
302
+ *
303
+ * This module exposes `runMain`, the Node runtime launcher used at the edge of
304
+ * CLI tools, scripts, servers, and worker processes. It runs an already
305
+ * self-contained Effect as the process main program, with built-in error
306
+ * reporting and Node signal handling.
307
+ *
308
+ * `NodeRuntime` does not provide application services by itself. Provide any
309
+ * required layers, such as `NodeServices.layer` or narrower service-specific
310
+ * layers, before passing the effect to `runMain`. On `SIGINT` or `SIGTERM`,
311
+ * the main fiber is interrupted so scoped resources and finalizers can shut
312
+ * down; keep long-running work attached to that scope and avoid finalizers that
313
+ * never complete, otherwise process shutdown can be delayed.
314
+ *
315
+ * @since 4.0.0
60
316
  */
61
317
  export * as NodeRuntime from "./NodeRuntime.ts";
62
318
  /**
63
- * @since 1.0.0
319
+ * Provides the aggregate Node platform services layer for applications that run
320
+ * on the Node.js runtime.
321
+ *
322
+ * This module is useful when an application needs the standard Node-backed
323
+ * implementations of filesystem access, path operations, stdio, terminal
324
+ * interaction, and child process spawning from a single layer. Provide
325
+ * `NodeServices.layer` near the edge of a program to satisfy effects that read
326
+ * or write files, resolve paths, interact with stdin/stdout/stderr or a
327
+ * terminal, or launch subprocesses.
328
+ *
329
+ * The layer only supplies the runtime services listed by `NodeServices`; it does
330
+ * not provide unrelated platform services such as HTTP clients or servers.
331
+ * Libraries should continue to depend on the individual service tags they use,
332
+ * while applications, CLIs, and tests can choose this layer or narrower
333
+ * service-specific layers depending on how much of the Node runtime they want to
334
+ * expose.
335
+ *
336
+ * @since 4.0.0
64
337
  */
65
338
  export * as NodeServices from "./NodeServices.ts";
66
339
  /**
67
- * @since 1.0.0
340
+ * @since 4.0.0
68
341
  */
69
342
  export * as NodeSink from "./NodeSink.ts";
70
343
  /**
71
- * @since 1.0.0
344
+ * Node platform socket entry point for Effect sockets backed by Node streams
345
+ * and WebSocket implementations.
346
+ *
347
+ * This module re-exports the shared Node socket constructors for TCP clients,
348
+ * Unix domain socket clients, and adapters from existing Node `Duplex` streams,
349
+ * then adds Node-specific WebSocket constructor layers. Use it when connecting
350
+ * to raw socket protocols, wiring RPC transports over TCP or Unix sockets, or
351
+ * opening WebSocket clients in Node.
352
+ *
353
+ * TCP and Unix socket behavior comes from the shared Node layer: Unix sockets
354
+ * are selected with `NetConnectOpts.path`, scoped sockets close or destroy the
355
+ * underlying stream on finalization, and Node open, read, write, and close
356
+ * events are translated into `SocketError` values. For WebSockets,
357
+ * `layerWebSocketConstructor` prefers `globalThis.WebSocket` when available
358
+ * and falls back to `ws`; use `layerWebSocketConstructorWS` when you need the
359
+ * `ws` implementation consistently across Node versions.
360
+ *
361
+ * @since 4.0.0
72
362
  */
73
363
  export * as NodeSocket from "./NodeSocket.ts";
74
364
  /**
75
- * @since 1.0.0
365
+ * @since 4.0.0
76
366
  */
77
367
  export * as NodeSocketServer from "./NodeSocketServer.ts";
78
368
  /**
79
- * @since 1.0.0
369
+ * Node.js implementation of the Effect `Stdio` service.
370
+ *
371
+ * This module exposes a layer that connects `Stdio` to the current process:
372
+ * command-line arguments come from `process.argv`, input is read from
373
+ * `process.stdin`, and output and error output write to `process.stdout` and
374
+ * `process.stderr`. It is intended for CLIs, scripts, command runners, and
375
+ * other process-oriented programs that need standard input and output through
376
+ * Effect services.
377
+ *
378
+ * The underlying streams are owned by the Node process. The layer keeps stdin
379
+ * open and does not end stdout or stderr when a stream finishes, which avoids
380
+ * closing global process handles that other code may still use. Be mindful that
381
+ * stdio may be a pipe, file, or TTY, so terminal-specific behavior such as raw
382
+ * mode, echo, colors, and cursor control should be handled with the terminal
383
+ * APIs instead of assuming an interactive console.
384
+ *
385
+ * @since 4.0.0
80
386
  */
81
387
  export * as NodeStdio from "./NodeStdio.ts";
82
388
  /**
83
- * @since 1.0.0
389
+ * @since 4.0.0
84
390
  */
85
391
  export * as NodeStream from "./NodeStream.ts";
86
392
  /**
87
- * @since 1.0.0
393
+ * Provides the Node.js `Terminal` service for interactive command-line
394
+ * programs, prompts, and tools that need to read lines, react to key presses,
395
+ * write to stdout, or inspect terminal dimensions.
396
+ *
397
+ * The implementation is backed by the current process' stdin and stdout. When
398
+ * stdin is a TTY, key input temporarily enables raw mode for the scope of the
399
+ * service, so callers should acquire it with a scope or use the provided layer
400
+ * to ensure terminal state is restored. In non-TTY environments, terminal
401
+ * dimensions may be reported as zero and raw-mode key handling is unavailable.
402
+ *
403
+ * @since 4.0.0
88
404
  */
89
405
  export * as NodeTerminal from "./NodeTerminal.ts";
90
406
  /**
91
- * @since 1.0.0
407
+ * Parent-side Node.js support for Effect workers.
408
+ *
409
+ * This module provides the `WorkerPlatform` used by Node programs that spawn
410
+ * and communicate with `node:worker_threads` workers or IPC-enabled child
411
+ * processes through Effect's worker protocol. Pair it with `NodeWorkerRunner`
412
+ * in the worker entrypoint when building worker-backed RPC clients, offloading
413
+ * CPU-bound work, isolating Node resources, or hosting services that should
414
+ * exchange typed messages with the parent process.
415
+ *
416
+ * Worker-thread spawners can use `postMessage` transfer lists for values such
417
+ * as `ArrayBuffer` and `MessagePort`, but transferring moves ownership and
418
+ * invalid transfer lists surface as worker send or receive failures.
419
+ * Child-process spawners must provide an IPC channel, for example via
420
+ * `child_process.fork` or `stdio: "ipc"`; their messages use Node IPC
421
+ * serialization and this module does not forward transfer lists to
422
+ * `ChildProcess.send`. Scope finalization sends the worker close signal and
423
+ * waits for exit before falling back to `terminate()` or `SIGKILL`.
424
+ *
425
+ * @since 4.0.0
92
426
  */
93
427
  export * as NodeWorker from "./NodeWorker.ts";
94
428
  /**
95
- * @since 1.0.0
429
+ * Runtime support for Effect workers that are executed by Node.js.
430
+ *
431
+ * This module is intended to be installed in the program running inside a
432
+ * `node:worker_threads` worker or an IPC-enabled child process. It provides the
433
+ * `WorkerRunnerPlatform` used by `WorkerRunner` to receive request messages
434
+ * from the parent, run the registered Effect handler, and send responses back
435
+ * over the parent channel.
436
+ *
437
+ * Use it when the parent side is created with `NodeWorker` and the worker code
438
+ * needs to perform CPU-bound work, isolate Node resources, or host services that
439
+ * should communicate through the Effect worker protocol. The runner must be
440
+ * started from an actual worker context: `parentPort` is required for worker
441
+ * threads, while child processes must be spawned with an IPC channel so
442
+ * `process.send` is available. Transfer lists only apply to worker-thread
443
+ * `postMessage`; child-process messages go through Node IPC serialization.
444
+ * Shutdown is coordinated by the parent message protocol, so long-running
445
+ * handlers should remain interruptible and keep resource cleanup in scopes.
446
+ *
447
+ * @since 4.0.0
96
448
  */
97
449
  export * as NodeWorkerRunner from "./NodeWorkerRunner.ts";
98
450
  /**
99
- * @since 1.0.0
451
+ * @since 4.0.0
100
452
  */
101
453
  export * as Undici from "./Undici.ts";
102
454
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;;GAIG;AACH,OAAO,KAAK,uBAAuB,MAAM,8BAA8B,CAAA;AAEvE;;GAEG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;GAEG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;GAEG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;GAEG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;GAEG;AACH,OAAO,KAAK,uBAAuB,MAAM,8BAA8B,CAAA;AAEvE;;GAEG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;GAEG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;GAEG;AACH,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAA;AAEnE;;GAEG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;;GAIG;AACH,OAAO,KAAK,uBAAuB,MAAM,8BAA8B,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;;GAIG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,uBAAuB,MAAM,8BAA8B,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}