@effect/platform-bun 4.0.0-beta.66 → 4.0.0-beta.68

package/src/BunSink.ts

@@ -1,8 +1,8 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSink"

package/src/BunSocket.ts

@@ -1,5 +1,24 @@
 /**
- * @since 1.0.0
+ * Bun platform socket entry point for Effect sockets backed by Bun-compatible
+ * Node streams and Bun's native WebSocket implementation.
+ *
+ * This module re-exports the shared Node socket constructors for TCP clients,
+ * Unix domain socket clients, and adapters from existing Node `Duplex` streams,
+ * then adds Bun-specific WebSocket layers using `globalThis.WebSocket`. Use it
+ * in Bun applications that connect to raw socket protocols, Unix sockets,
+ * realtime WebSocket services, or Effect RPC transports that need a
+ * `Socket.Socket` layer.
+ *
+ * TCP lifecycle behavior comes from the shared Node layer: sockets are scoped,
+ * finalizers close or destroy the underlying stream, open timeouts become
+ * socket open errors, and read, write, and close events are mapped to
+ * `SocketError` values. TLS concerns depend on the transport being used: `wss:`
+ * URLs are handled by Bun's WebSocket implementation, while TLS-wrapped
+ * `Duplex` streams can be adapted after they have been created elsewhere.
+ * When closing intentionally, send `Socket.CloseEvent` values so the close code
+ * and reason are preserved through the socket lifecycle.
+ *
+ * @since 4.0.0
  */
 import type * as Duration from "effect/Duration"
 import type { Effect } from "effect/Effect"
@@ -8,13 +27,16 @@ import * as Layer from "effect/Layer"
 import * as Socket from "effect/unstable/socket/Socket"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSocket"
 
 /**
- * @since 1.0.0
+ * Provides a `Socket.WebSocketConstructor` backed by Bun's global
+ * `WebSocket` implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocketConstructor: Layer.Layer<
   Socket.WebSocketConstructor
@@ -23,8 +45,12 @@ export const layerWebSocketConstructor: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
+ * Creates a `Socket.Socket` layer for a WebSocket URL using Bun's global
+ * `WebSocket` constructor, honoring protocol, open-timeout, and close-code
+ * error options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket: (
   url: string | Effect<string>,

package/src/BunSocketServer.ts

@@ -1,8 +1,8 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeSocketServer"

package/src/BunStdio.ts

@@ -1,12 +1,33 @@
 /**
- * @since 1.0.0
+ * Bun-backed implementation of Effect's `Stdio` service.
+ *
+ * This module provides the process stdio layer for Bun applications by reusing
+ * the shared Node-compatible implementation. The layer connects `Stdio` to the
+ * current Bun process: arguments come from `process.argv`, input is read from
+ * `process.stdin`, and output and error output write to `process.stdout` and
+ * `process.stderr`. It is intended for CLIs, scripts, command runners, test
+ * harnesses, and other process-oriented programs that need standard input and
+ * output through Effect services.
+ *
+ * The underlying stdio streams are global resources owned by the Bun process.
+ * The layer keeps stdin open and does not end stdout or stderr by default,
+ * which avoids closing handles that prompts, loggers, or other code may still
+ * use. Stdio may be attached to a TTY, pipe, or redirected file, so
+ * terminal-specific behavior such as raw mode, echo, colors, cursor control,
+ * and terminal dimensions should be coordinated with terminal APIs rather than
+ * assumed from this layer.
+ *
+ * @since 4.0.0
  */
 import * as NodeStdio from "@effect/platform-node-shared/NodeStdio"
 import type * as Layer from "effect/Layer"
 import type { Stdio } from "effect/Stdio"
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the `Stdio` service backed by the current process arguments,
+ * stdin, stdout, and stderr streams.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Stdio> = NodeStdio.layer

package/src/BunStream.ts

@@ -1,5 +1,26 @@
 /**
- * @since 1.0.0
+ * Bun stream interoperability for Effect streams.
+ *
+ * This module provides Bun-specific adapters for working with streaming data at
+ * the boundary between Bun APIs and Effect. It re-exports the shared Node stream
+ * adapters for Bun's Node-compatible stream APIs, and adds an optimized
+ * `ReadableStream` constructor that uses Bun's `readMany` support to pull
+ * batches of Web Stream values into an Effect `Stream`.
+ *
+ * Common uses include adapting Bun `Request` and `Response` bodies, multipart
+ * uploads, and other Web `ReadableStream` sources so they can be transformed,
+ * decoded, or piped with Effect stream operators. Pulling from the Effect stream
+ * drives reads from the underlying reader, while Bun and the Web Streams runtime
+ * still control their own internal buffering and source backpressure.
+ *
+ * Web `ReadableStream` readers take an exclusive lock on the source. Request and
+ * response bodies are also one-shot: once consumed they become disturbed and
+ * should not be read through another API. The adapter cancels the reader when
+ * the consuming scope is finalized by default; set `releaseLockOnEnd` when the
+ * stream is externally owned and should only have its lock released. Read errors
+ * are mapped through the provided `onError` function.
+ *
+ * @since 4.0.0
  */
 import * as Arr from "effect/Array"
 import * as Cause from "effect/Cause"
@@ -11,7 +32,7 @@ import * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "@effect/platform-node-shared/NodeStream"
 
@@ -19,7 +40,8 @@ export * from "@effect/platform-node-shared/NodeStream"
  * An optimized version of `Stream.fromReadableStream` that uses the Bun
  * .readMany API to read multiple values at once from a `ReadableStream`.
  *
- * @since 1.0.0
+ * @category constructors
+ * @since 4.0.0
  */
 export const fromReadableStream = <A, E>(
   options: {

package/src/BunTerminal.ts

@@ -1,5 +1,19 @@
 /**
- * @since 1.0.0
+ * Bun-backed implementation of Effect's `Terminal` service.
+ *
+ * This module provides a scoped, process-backed terminal for Bun programs by
+ * adapting the runtime's Node-compatible stdin, stdout, and `readline` support.
+ * It is useful for CLIs, prompts, REPLs, and terminal interfaces that need
+ * prompt output, line input, keypress input, or terminal dimensions.
+ *
+ * The service uses the current process streams, so acquire it with a scope or
+ * provide `layer` to ensure cleanup. When stdin is attached to a TTY, raw mode
+ * is enabled while the terminal is active and restored when the scope closes;
+ * this changes how keys are delivered and can affect other consumers of stdin.
+ * In pipes, redirected input, or CI, raw mode may be unavailable, keypress input
+ * is limited, and stdout dimensions may be reported as zero.
+ *
+ * @since 4.0.0
  */
 import * as NodeTerminal from "@effect/platform-node-shared/NodeTerminal"
 import type { Effect } from "effect/Effect"
@@ -8,13 +22,19 @@ import type { Scope } from "effect/Scope"
 import type { Terminal, UserInput } from "effect/Terminal"
 
 /**
- * @since 1.0.0
+ * Creates a scoped `Terminal` service backed by process stdin/stdout, using the
+ * optional predicate to decide when key input should end the input stream.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (shouldQuit?: (input: UserInput) => boolean) => Effect<Terminal, never, Scope> = NodeTerminal.make
 
 /**
- * @since 1.0.0
+ * Provides the default process-backed `Terminal` service, ending key input on
+ * the default quit keys.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer<Terminal> = NodeTerminal.layer

package/src/BunWorker.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Parent-side Bun support for Effect workers.
+ *
+ * This module provides the `WorkerPlatform` used by Bun programs that spawn
+ * and communicate with `globalThis.Worker` instances through Effect's worker
+ * protocol. Pair it with `BunWorkerRunner` in the worker entrypoint when
+ * building worker-backed RPC clients, moving CPU-bound work off the main
+ * thread, isolating Bun-only services, or hosting long-lived handlers behind a
+ * typed message boundary.
+ *
+ * The supplied spawner is responsible for creating the Bun worker for each
+ * numeric worker id. Messages follow Bun's worker cloning and transfer
+ * semantics, so payloads and transfer lists must be accepted by the Bun worker
+ * runtime. Calls to `send` are buffered until the worker runner posts its ready
+ * signal; if the worker entrypoint never starts `BunWorkerRunner`, those
+ * buffered messages will not be delivered. Scope finalization sends the Effect
+ * worker close signal, waits for Bun's `close` event for a short grace period,
+ * and then terminates the worker if graceful shutdown does not complete.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -10,8 +28,11 @@ import * as Worker from "effect/unstable/workers/Worker"
 import { WorkerError, WorkerUnknownError } from "effect/unstable/workers/WorkerError"
 
 /**
- * @since 1.0.0
+ * Provides the Bun `WorkerPlatform` together with a `Worker.Spawner` created
+ * from the supplied worker spawning function.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   spawn: (id: number) => globalThis.Worker
@@ -22,8 +43,12 @@ export const layer = (
   )
 
 /**
- * @since 1.0.0
+ * Provides the Bun `WorkerPlatform`, wiring worker messages and errors into
+ * Effect workers and requesting graceful worker shutdown during scope
+ * finalization before terminating on timeout.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerPlatform = Layer.succeed(Worker.WorkerPlatform)(
   Worker.makePlatform<globalThis.Worker>()({

package/src/BunWorkerRunner.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Bun runtime support for Effect worker runners.
+ *
+ * This module is intended for code that is already executing inside a Bun
+ * `Worker`. It provides the `WorkerRunnerPlatform` used by `WorkerRunner` to
+ * receive request messages from the parent, run the registered Effect handler,
+ * and send responses back over Bun's worker `postMessage` channel.
+ *
+ * Use it with `BunWorker` when a Bun program needs to move RPC handlers,
+ * CPU-bound computations, or Bun-only services into an isolated worker while
+ * communicating through the Effect worker protocol. The runner must be started
+ * from the worker entrypoint, not the parent process; startup fails when the
+ * current global worker scope does not expose `postMessage`. Shutdown is driven
+ * by the parent protocol message, which closes the worker port, so long-running
+ * handlers should remain interruptible and keep resource cleanup in scopes.
+ * Messages follow Bun's worker cloning and transfer semantics, so payload
+ * schemas, transfer lists, `messageerror` events, and worker `error` events
+ * should be considered at the boundary.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -15,8 +33,12 @@ import * as WorkerRunner from "effect/unstable/workers/WorkerRunner"
 declare const self: MessagePort
 
 /**
- * @since 1.0.0
+ * Provides the `WorkerRunnerPlatform` for code running inside a Bun worker,
+ * routing parent messages to the registered handler and sending responses back
+ * through the worker port.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succeed(WorkerRunner.WorkerRunnerPlatform)({
   start: Effect.fnUntraced(function*<O = unknown, I = unknown>() {