@effect/platform-bun 4.0.0-beta.70 → 4.0.0-beta.72

package/src/BunRedis.ts

@@ -1,27 +1,36 @@
 /**
  * Bun Redis integration backed by Bun's built-in `RedisClient`.
  *
- * This module provides scoped layers that create a Bun `RedisClient` and expose
- * both the low-level `Redis` service used by Effect persistence modules and the
- * `BunRedis` service for direct access to the underlying client. Use it in Bun
- * applications that need Redis-backed persistence, persisted queues,
+ * This module creates scoped Bun `RedisClient` connections and exposes them as
+ * both the portable `Redis` service used by Effect persistence modules and the
+ * Bun-specific `BunRedis` service for direct access to the raw client. Use it in
+ * Bun applications that need Redis-backed persistence, persisted queues,
  * distributed rate limiting, custom Redis commands, or Bun Redis features such
- * as pub/sub through the raw client.
+ * as pub/sub.
  *
- * The client is acquired when the layer is built and closed with `close` when
- * the layer scope ends, so install the layer at the lifetime you want for the
- * connection and pass a Redis URL, Bun `RedisOptions`, or `layerConfig` for
- * connection settings. The portable `Redis` service sends ordinary commands
- * through `RedisClient.send`; pub/sub is available through `BunRedis.client`
- * or `BunRedis.use` and should normally use a separately scoped client so a
- * subscription does not interfere with command traffic used by persistence or
- * rate limiter stores.
+ * **Mental model**
  *
- * Persistence and rate limiter stores build keys and Lua scripts on top of this
- * service. Choose stable prefixes and store ids to avoid collisions, account
- * for persisted values that may fail to decode after schema changes, and avoid
- * unbounded high-cardinality rate-limit keys unless you have a cleanup or
- * bounding strategy.
+ * `layer` and `layerConfig` acquire one `RedisClient` for the layer scope. The
+ * same client backs the portable `Redis.Redis` command interface and the
+ * `BunRedis` service, and it is closed with `close` when the scope finalizes.
+ * Install the layer at the lifetime you want for that connection.
+ *
+ * **Common tasks**
+ *
+ * Pass a Redis URL or Bun `RedisOptions` to `layer` for direct configuration,
+ * or use `layerConfig` when connection settings should come from Effect
+ * configuration. Depend on `Redis.Redis` for persistence and rate limiter
+ * stores. Depend on `BunRedis` when you need `RedisClient` features that are
+ * not exposed by the portable service, including custom commands and pub/sub.
+ *
+ * **Gotchas**
+ *
+ * Pub/sub should normally use a separately scoped client so a subscription does
+ * not interfere with ordinary command traffic. Persistence and rate limiter
+ * stores build keys and Lua scripts on top of this service, so choose stable
+ * prefixes and store ids, account for persisted values that may fail to decode
+ * after schema changes, and avoid unbounded high-cardinality rate-limit keys
+ * without a cleanup or bounding strategy.
  *
  * @since 4.0.0
  */

package/src/BunRuntime.ts

@@ -1,19 +1,32 @@
 /**
- * Bun entry-point helpers for running Effect programs.
+ * Bun process runner for Effect programs.
  *
- * This module exposes `runMain`, the Bun runtime launcher used at the edge of
- * CLIs, scripts, servers, and worker processes. It runs an already
- * self-contained Effect as the process main program, using the shared
- * Node-compatible runtime implementation for error reporting, teardown, and
- * `process` signal handling available in Bun.
+ * This module exposes Bun's `runMain` entry point. It is the function to call
+ * at the outer edge of a Bun CLI, script, server, or worker when a single
+ * Effect should become the process main fiber and use Bun's Node-compatible
+ * process, signal, and teardown behavior.
  *
- * `BunRuntime` does not provide application services by itself. Provide any
- * required layers, such as `BunServices.layer` or narrower service-specific
- * layers, before passing the effect to `runMain`. On `SIGINT` or `SIGTERM`,
- * the main fiber is interrupted so scoped resources and finalizers can shut
- * down; keep long-running servers, workers, and subscriptions attached to that
- * scope and avoid finalizers that never complete, otherwise process shutdown
- * can be delayed.
+ * **Mental model**
+ *
+ * `runMain` delegates to the shared Node-compatible runner. It starts the
+ * supplied Effect as the process root, reports failures through the configured
+ * runtime reporting, and translates `SIGINT` or `SIGTERM` into interruption so
+ * scoped resources can finalize before teardown chooses an exit code.
+ *
+ * **Common tasks**
+ *
+ * - Launch a Bun CLI or one-off script from an Effect.
+ * - Start a long-running Bun server or worker under an Effect scope.
+ * - Customize error reporting or teardown with `runMain` options.
+ * - Provide `BunServices.layer` or narrower layers before calling `runMain`.
+ *
+ * **Gotchas**
+ *
+ * This module runs the program; it does not provide filesystem, network,
+ * terminal, or other platform services. Long-lived servers, subscriptions, and
+ * worker loops should be acquired in Effect scopes so interruption from process
+ * signals can release them. Finalizers that never complete can keep shutdown
+ * waiting.
  *
  * @since 4.0.0
  */
@@ -26,7 +39,7 @@ import type { Teardown } from "effect/Runtime"
  *
  * **When to use**
  *
- * Use this function to run an Effect as your application's main program,
+ * Use to run an Effect as your application's main program,
  * especially when you need structured error handling, log management,
  * interrupt support, or advanced teardown capabilities.
  *
@@ -52,7 +65,7 @@ export const runMain: {
    *
    * **When to use**
    *
-   * Use this function to run an Effect as your application's main program,
+   * Use to run an Effect as your application's main program,
    * especially when you need structured error handling, log management,
    * interrupt support, or advanced teardown capabilities.
    *
@@ -83,7 +96,7 @@ export const runMain: {
    *
    * **When to use**
    *
-   * Use this function to run an Effect as your application's main program,
+   * Use to run an Effect as your application's main program,
    * especially when you need structured error handling, log management,
    * interrupt support, or advanced teardown capabilities.
    *

package/src/BunStdio.ts

@@ -1,21 +1,33 @@
 /**
- * Bun-backed implementation of Effect's `Stdio` service.
+ * Process stdio for Bun applications.
  *
- * 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.
+ * This module provides the Bun layer for Effect's `Stdio` service by adapting
+ * the current process arguments and standard streams. Arguments come from
+ * `process.argv`, input is read from `process.stdin`, and output and error
+ * output write to `process.stdout` and `process.stderr`.
+ *
+ * **Mental model**
+ *
+ * `BunStdio.layer` is a thin Bun-facing wrapper around the shared
+ * Node-compatible stdio implementation. It does not create private streams for
+ * an application; it exposes the global streams owned by the running Bun
+ * process through the `Stdio` service.
+ *
+ * **Common tasks**
+ *
+ * - Provide `Stdio` for Bun CLIs, scripts, command runners, and tests.
+ * - Read process arguments or standard input through Effect services.
+ * - Write normal output and diagnostics without depending directly on
+ *   `process.stdout` or `process.stderr`.
+ *
+ * **Gotchas**
  *
- * 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.
+ * and terminal dimensions should be handled with terminal APIs such as
+ * `BunTerminal`, not inferred from this layer.
  *
  * @since 4.0.0
  */

package/src/BunStream.ts

@@ -1,24 +1,33 @@
 /**
  * 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`.
+ * This module is the Bun entry point for adapting runtime streams into Effect's
+ * streaming model. It re-exports the shared Node stream adapters for Bun's
+ * Node-compatible stream APIs and adds {@link fromReadableStream}, a Web
+ * `ReadableStream` adapter that uses Bun's `readMany` reader method to pull
+ * batches of 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.
+ * **Mental model**
  *
- * 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.
+ * Consuming the returned `Stream` drives reads from the underlying
+ * `ReadableStreamDefaultReader`. Each pull asks Bun for the next batch, empty
+ * batches are skipped, read failures are translated with `onError`, and the
+ * reader is finalized with the surrounding Effect scope.
+ *
+ * **Common tasks**
+ *
+ * Use {@link fromReadableStream} for Bun `Request` and `Response` bodies,
+ * multipart uploads, and other Web stream sources that should be transformed,
+ * decoded, or piped with Effect stream operators. Use the re-exported Node
+ * stream adapters for APIs that expose Bun's Node-compatible `stream` types.
+ *
+ * **Gotchas**
+ *
+ * Web stream readers hold an exclusive lock. Request and response bodies are
+ * also one-shot; once consumed they are disturbed and should not be read through
+ * another API. By default finalization cancels the reader; set
+ * `releaseLockOnEnd` when the stream is externally owned and only the reader
+ * lock should be released.
  *
  * @since 4.0.0
  */
@@ -37,8 +46,8 @@ import * as Stream from "effect/Stream"
 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`.
+ * Creates a stream from a `ReadableStream` using Bun's optimized `.readMany`
+ * API.
  *
  * @category constructors
  * @since 4.0.0

package/src/BunTerminal.ts

@@ -1,17 +1,35 @@
 /**
  * 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.
+ * This module adapts Bun's Node-compatible `stdin`, `stdout`, and `readline`
+ * support into a scoped `Terminal` service. It is intended for Bun CLIs,
+ * prompts, REPLs, and terminal interfaces that need prompt output, line input,
+ * keypress input, or terminal dimensions through Effect services.
+ *
+ * **Mental model**
+ *
+ * - {@link make} creates a scoped terminal from the current process streams.
+ * - {@link layer} provides the default live terminal service for Bun programs.
+ * - The implementation reuses the shared Node-compatible terminal adapter, so
+ *   behavior follows the capabilities of Bun's process streams and readline
+ *   support.
+ *
+ * **Common tasks**
+ *
+ * - Provide terminal access at the edge of a Bun CLI with {@link layer}.
+ * - Customize which key ends keypress input by calling {@link make} directly.
+ * - Read lines, read keypresses, display prompts, and inspect terminal size
+ *   through the `Terminal` service once it is provided.
+ *
+ * **Gotchas**
+ *
+ * - The service uses global process streams. Acquire it with a scope, or
+ *   provide {@link layer}, so raw mode and readline listeners are cleaned up.
+ * - When `stdin` is 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 stdin consumers.
+ * - 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
  */

package/src/BunWorker.ts

@@ -1,21 +1,38 @@
 /**
- * Parent-side Bun support for Effect workers.
+ * Parent-side worker support for Bun applications.
  *
- * This module provides the `WorkerPlatform` used by Bun programs that spawn
- * and communicate with `globalThis.Worker` instances through Effect's worker
+ * 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.
+ * **Mental model**
+ *
+ * `layer(spawn)` installs both the Bun `WorkerPlatform` and a `Worker.Spawner`.
+ * The supplied `spawn` function creates the Bun worker for each numeric worker
+ * id. The platform listens for worker messages and errors, wraps outgoing data
+ * in the Effect worker protocol, and buffers `send` calls until the worker
+ * runner posts its ready signal.
+ *
+ * **Common tasks**
+ *
+ * - Run Effect worker clients in a Bun parent process.
+ * - Move RPC handlers, CPU-bound computations, or Bun-only services into a
+ *   dedicated worker.
+ * - Provide custom worker creation logic while keeping message handling and
+ *   cleanup inside Effect scopes.
+ *
+ * **Gotchas**
+ *
+ * This module is for the parent side only; the worker entrypoint must start
+ * `BunWorkerRunner`. If the runner never starts or never posts readiness,
+ * buffered messages will not be delivered. Payloads and transfer lists use
+ * Bun's worker cloning and transfer semantics, so they must be accepted by the
+ * Bun worker runtime. 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
  */

package/src/BunWorkerRunner.ts

@@ -1,21 +1,35 @@
 /**
- * Bun runtime support for Effect worker runners.
+ * Worker-entrypoint support for Bun 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.
+ * This module provides the Bun `WorkerRunnerPlatform` for code already running
+ * inside a Bun `Worker`. It receives request messages from the parent-side
+ * `BunWorker` platform, runs the handler registered with `WorkerRunner.run`,
+ * and posts responses back through 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.
+ * **Mental model**
+ *
+ * The parent process installs `BunWorker.layer`; the worker entrypoint installs
+ * this `layer` and starts `WorkerRunner`. Bun exposes one worker port to this
+ * runner, so every message uses port id `0`. The first message sent by this
+ * layer is the ready signal consumed by the parent platform before buffered
+ * sends are flushed.
+ *
+ * **Common tasks**
+ *
+ * - Host Effect worker or RPC handlers inside a Bun worker entrypoint.
+ * - Move CPU-bound work or Bun-only services behind Effect's worker protocol.
+ * - Send structured-clone payloads and transferables back to the parent with
+ *   `WorkerRunner.send`.
+ *
+ * **Gotchas**
+ *
+ * Start this layer only in the worker entrypoint; it fails when
+ * `self.postMessage` is unavailable. Parent shutdown arrives as the worker
+ * close message and closes the port, so long-running handlers should stay
+ * interruptible and keep cleanup in scopes. Payloads, transfer lists, and
+ * `messageerror` events follow Bun's worker runtime behavior.
+ *
+ * @see {@link layer} for the Bun worker-runner platform layer.
  *
  * @since 4.0.0
  */