@effect/platform-bun 4.0.0-beta.77 → 4.0.0-beta.79

package/src/BunFileSystem.ts

@@ -1,25 +1,9 @@
 /**
  * Bun layer for Effect's `FileSystem` service.
  *
- * Use this module at the edge of Bun applications, CLIs, scripts, and tests
- * that need real local filesystem access through `effect/FileSystem`: reading
- * and writing files, creating directories and temporary files, inspecting
- * metadata, managing links, or watching paths for changes. It exposes only the
- * Bun `FileSystem` layer; the operations themselves are accessed from the
- * `FileSystem` service once the layer is provided, or from `BunServices.layer`
- * when the program also needs the standard Bun path, stdio, terminal, and child
- * process services.
- *
- * Bun supports Node-compatible filesystem APIs, so this layer reuses the shared
- * Node filesystem implementation. Paths therefore follow the current process and
- * host platform rules: relative paths are resolved from the current working
- * directory, separators and drive/UNC behavior are platform-dependent, and
- * request URLs should be decoded and validated before being mapped to local
- * paths. The service works with bytes, scoped file handles, and Effect
- * streams/sinks; use `FileSystem.stream` for large files instead of
- * `readFile`, and remember that stream offsets and lengths are byte positions.
- * Bun `File` and `Blob` values are not filesystem handles here; path-based HTTP
- * file responses are handled by the Bun HTTP platform adapter with `Bun.file`.
+ * This module exposes one `layer` that provides `FileSystem` in Bun by using
+ * the shared Node file-system implementation. Once the layer is provided,
+ * programs use the standard `effect/FileSystem` service operations.
  *
  * @since 4.0.0
  */

package/src/BunHttpPlatform.ts

@@ -1,25 +1,11 @@
 /**
  * Bun implementation of the Effect HTTP platform service.
  *
- * This module connects the portable `HttpPlatform` file response helpers to
- * Bun's Web-compatible runtime. `BunHttpServer` provides this layer when
- * applications serve local files, public assets, downloads, byte ranges, or
- * Web `File` values from Effect `HttpServerResponse` constructors.
- *
- * Path-based responses are backed by `Bun.file`, and Web `File` responses are
- * returned directly as raw response bodies. The shared `HttpPlatform` service
- * still computes file metadata such as ETags and last-modified headers, while
- * this adapter lets Bun's `Response` implementation handle the platform body.
- *
- * Because the Bun server adapter sits on top of Web `Request` and `Response`,
- * request bodies follow the usual single-consumption rules: choose the
- * streamed, text, URL-encoded, or multipart view that matches the route. For
- * `FormData` responses, let the `Response` constructor create the multipart
- * content type and boundary unless you intentionally override it. File
- * responses take filesystem paths, not request URLs; Bun request URLs are
- * absolute at the runtime edge, and route paths are normalized by
- * `BunHttpServer`, so decode and validate URL pathnames before mapping them to
- * files.
+ * This module provides one `layer` for `HttpPlatform`. It implements file
+ * responses with `Bun.file`, supports sliced file responses for byte ranges,
+ * and returns Web `File` values as raw HTTP server responses. The layer also
+ * provides the Bun file-system layer and ETag generator required by
+ * `HttpPlatform`.
  *
  * @since 4.0.0
  */

package/src/BunHttpServer.ts

@@ -1,34 +1,13 @@
 /**
  * Bun implementation of the Effect `HttpServer`.
  *
- * This module builds an Effect HTTP server from `Bun.serve`, translating Bun's
- * Web `Request` objects into `HttpServerRequest` values and Effect
- * `HttpServerResponse` values back into Web `Response` objects. It is the Bun
- * runtime entry point for serving `HttpApp`s, streaming responses, file
- * responses through `BunHttpPlatform`, multipart requests, and websocket
- * endpoints through `HttpServerRequest.upgrade`.
- *
- * Common use cases include using {@link layer} or {@link layerConfig} to serve
- * an application from Bun configuration, {@link layerServer} when only the
- * `HttpServer` service is needed, and {@link layerTest} for tests that need an
- * ephemeral Bun listener and fetch-compatible client.
- *
- * Bun supplies absolute request URLs and Web-standard request bodies. This
- * adapter stores the normalized path-and-query URL on `HttpServerRequest.url`,
- * while the underlying `Request` still follows Web body rules: pick the
- * streamed, text, JSON, URL-encoded, or multipart view that matches the route
- * instead of consuming the same body in incompatible ways. Because `Bun.serve`
- * has a single active `fetch` handler, each `serve` call reloads that handler
- * and restores the previous one when the serve scope finalizes.
- *
- * WebSocket upgrades must happen from the Bun request handler. The
- * `HttpServerRequest.upgrade` effect calls `server.upgrade`, fails when Bun says
- * the request is not upgradeable, buffers messages that arrive before the
- * Effect socket handler is installed, and maps non-normal close codes into
- * `Socket` errors. The server is stopped with `server.stop()` when its
- * acquisition scope closes; unless preemptive shutdown is disabled, finalizing
- * a serve scope also starts that stop with the configured graceful shutdown
- * timeout or the default timeout.
+ * `make` creates a scoped HTTP server from `Bun.serve`, converting Bun
+ * `Request` values into `HttpServerRequest` values and Effect
+ * `HttpServerResponse` values back into Web `Response` values. The server
+ * supports streaming bodies, multipart requests, file responses through
+ * `BunHttpPlatform`, and WebSocket upgrades. This module also provides layers
+ * for the server alone, the Bun HTTP support services, the combined server,
+ * configurable server options, and a test server with an HTTP client.
  *
  * @since 4.0.0
  */

package/src/BunHttpServerRequest.ts

@@ -1,25 +1,9 @@
 /**
- * Accessors for the Bun `Request` object backing a platform Bun
- * `HttpServerRequest`.
+ * Accessor for the Bun request behind an Effect HTTP server request.
  *
- * Use this module at interop boundaries when an Effect HTTP handler needs the
- * original `Bun.BunRequest`, for example to read Bun route parameters, pass the
- * request to Bun-specific APIs, inspect Web `Request` fields that are not
- * exposed by the portable `HttpServerRequest` interface, or coordinate with code
- * that already works directly with Bun's server request type.
- *
- * The returned request is the original Web request supplied by `Bun.serve`. It
- * does not reflect Effect request overrides made by middleware, such as a
- * rewritten URL, adjusted headers, or a substituted remote address. Its body is
- * the same one-shot Web `ReadableStream` used by the Effect body helpers, so
- * calling `text`, `json`, `formData`, `arrayBuffer`, or reading `body` directly
- * can disturb the request and conflict with Effect body, multipart, or stream
- * helpers unless ownership of the body is clear.
- *
- * Bun stores client IP information on the server rather than on the request
- * object. Prefer `HttpServerRequest.remoteAddress` when you need the address
- * seen by Effect or middleware; the raw request returned here will not expose
- * middleware-provided remote address overrides.
+ * This module exports `toBunServerRequest`, which returns the underlying
+ * `Bun.BunRequest` stored inside a Bun-backed `HttpServerRequest`. It is meant
+ * for code that needs to interoperate with Bun-specific request APIs.
  *
  * @since 4.0.0
  */

package/src/BunMultipart.ts

@@ -2,21 +2,9 @@
  * Bun-specific helpers for parsing HTTP `multipart/form-data` request bodies.
  *
  * This module adapts a Bun `Request` body and headers into the shared
- * `Multipart` model. Use `stream` from Bun HTTP handlers when form fields and
- * uploaded files should be consumed incrementally, for example validating text
- * fields while piping large file parts to storage. Use `persisted` when the
- * whole form should be collected into a record and file parts should be written
- * to scoped temporary files through the current `FileSystem`, `Path`, and
- * `Scope` services.
- *
- * Bun requests expose one-shot web streams, so choose one body reader and do
- * not call `formData`, `text`, `json`, or `arrayBuffer` before using this
- * module. Incoming `FormData` uploads must include a `multipart/form-data`
- * content type with the boundary generated by the client; when constructing
- * `FormData` requests, let the runtime set that header. Stream file content for
- * large uploads, reserve `contentEffect` for small files, and treat client
- * filenames as metadata rather than trusted filesystem paths. Persisted file
- * paths remain valid only for the surrounding scope.
+ * `Multipart` model. `stream` returns multipart parts as a `Stream`, while
+ * `persisted` collects the form and writes file parts to scoped temporary files
+ * through the current `FileSystem`, `Path`, and `Scope` services.
  *
  * @since 4.0.0
  */

package/src/BunPath.ts

@@ -6,28 +6,6 @@
  * Bun code should receive path operations from the Effect environment instead
  * of importing runtime path helpers directly.
  *
- * **Mental model**
- *
- * Bun exposes Node-compatible path and file URL behavior, so the default
- * {@link layer} follows the host operating system's rules. The
- * {@link layerPosix} and {@link layerWin32} variants pin parsing and formatting
- * to POSIX or Windows semantics for portable tests, generated paths, and
- * cross-platform tooling.
- *
- * **Common tasks**
- *
- * Use {@link layer} for normal Bun applications and CLIs. Use
- * {@link layerPosix} or {@link layerWin32} when code must produce stable path
- * syntax regardless of the machine running Bun. `BunServices.layer` already
- * includes {@link layer}, so import this module directly when only `Path` or a
- * fixed platform variant is needed.
- *
- * **Gotchas**
- *
- * Path operations are syntactic. They normalize and convert strings and
- * `file:` URLs, but they do not read the filesystem, check permissions, confirm
- * that a path exists, or make request URLs safe to use as local paths.
- *
  * @since 4.0.0
  */
 import * as NodePath from "@effect/platform-node-shared/NodePath"

package/src/BunRedis.ts

@@ -2,35 +2,10 @@
  * Bun Redis integration backed by Bun's built-in `RedisClient`.
  *
  * 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.
- *
- * **Mental model**
- *
- * `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.
+ * both the portable `Redis` service and the Bun-specific `BunRedis` service for
+ * direct access to the raw client. The `layer` helper accepts Redis options
+ * directly, while `layerConfig` reads them from Effect config. Both close the
+ * underlying client when the layer scope finalizes.
  *
  * @since 4.0.0
  */

package/src/BunRuntime.ts

@@ -1,32 +1,9 @@
 /**
  * Bun process runner for Effect programs.
  *
- * 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.
- *
- * **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.
+ * This module exports `runMain`, which runs one Effect as the main process
+ * fiber in Bun. It reuses the shared Node runtime runner, including its error
+ * reporting, signal handling, and optional teardown behavior.
  *
  * @since 4.0.0
  */

package/src/BunServices.ts

@@ -1,23 +1,10 @@
 /**
- * Provides the aggregate Bun platform services layer for applications that run
- * on the Bun runtime.
+ * Aggregate Bun platform services layer.
  *
- * This module is useful when an application needs the standard Bun-backed
- * implementations of filesystem access, path operations, stdio, terminal
- * interaction, and child process spawning from a single layer. Provide
- * `BunServices.layer` near the edge of a program to satisfy effects that read
- * or write files, resolve paths, interact with stdin/stdout/stderr or a
- * terminal, or launch subprocesses.
- *
- * The layer only supplies the runtime services listed by `BunServices`; it does
- * not provide unrelated platform services such as HTTP clients, HTTP servers,
- * sockets, workers, or Redis. Several of these core Bun services are backed by
- * the shared Node-compatible implementations used by the Bun adapters, so the
- * default path, stdio, terminal, and subprocess behavior follows the current
- * process and host platform. Libraries should continue to depend on the
- * individual service tags they use, while Bun applications, CLIs, and tests can
- * choose this layer or narrower service-specific layers depending on how much
- * of the Bun runtime they want to expose.
+ * This module defines the `BunServices` union and a single `layer` that
+ * provides Bun-backed child process spawning, crypto, filesystem, path, stdio,
+ * and terminal services. Use the layer when a Bun program wants the standard
+ * platform services from one place.
  *
  * @since 4.0.0
  */

package/src/BunSocket.ts

@@ -1,22 +1,10 @@
 /**
- * Bun platform socket entry point for Effect sockets backed by Bun-compatible
- * Node streams and Bun's native WebSocket implementation.
+ * Bun platform socket entry point for Effect sockets.
  *
  * 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.
+ * Unix domain socket clients, and adapters from existing Node `Duplex` streams.
+ * It also provides Bun WebSocket layers using `globalThis.WebSocket`, including
+ * a constructor layer and a `Socket.Socket` layer for a WebSocket URL.
  *
  * @since 4.0.0
  */

package/src/BunStdio.ts

@@ -1,33 +1,10 @@
 /**
  * Process stdio for Bun applications.
  *
- * 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 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 handled with terminal APIs such as
- * `BunTerminal`, not inferred from this layer.
+ * This module provides the Bun layer for Effect's `Stdio` service by using the
+ * shared Node stdio implementation. Arguments come from `process.argv`, input
+ * is read from `process.stdin`, and output and error output write to
+ * `process.stdout` and `process.stderr`.
  *
  * @since 4.0.0
  */

package/src/BunStream.ts

@@ -7,28 +7,6 @@
  * `ReadableStream` adapter that uses Bun's `readMany` reader method to pull
  * batches of values into an Effect `Stream`.
  *
- * **Mental model**
- *
- * 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
  */
 import * as Arr from "effect/Array"

package/src/BunTerminal.ts

@@ -1,35 +1,9 @@
 /**
  * Bun-backed implementation of Effect's `Terminal` service.
  *
- * 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.
+ * This module reuses the shared Node terminal implementation for Bun. `make`
+ * creates a scoped process-backed `Terminal` service, and `layer` provides the
+ * default terminal service with the standard quit behavior for key input.
  *
  * @since 4.0.0
  */

package/src/BunWorker.ts

@@ -1,38 +1,12 @@
 /**
  * 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
- * 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.
- *
- * **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.
+ * `layerPlatform` provides the `WorkerPlatform` used to communicate with
+ * `globalThis.Worker` instances through Effect's worker protocol. `layer`
+ * combines that platform with a `Spawner` built from a callback that creates a
+ * worker for each worker id. The platform forwards worker messages and errors,
+ * asks workers to close on scope finalization, and terminates them if graceful
+ * shutdown times out.
  *
  * @since 4.0.0
  */

package/src/BunWorkerRunner.ts

@@ -1,35 +1,11 @@
 /**
  * Worker-entrypoint support for Bun worker runners.
  *
- * 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.
- *
- * **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.
+ * This module exports a `layer` that provides `WorkerRunnerPlatform` for code
+ * already running inside a Bun `Worker`. The platform receives request messages
+ * from the parent-side `BunWorker` platform, runs the registered handler, sends
+ * responses through the worker `postMessage` channel, and closes when the
+ * parent sends the close message.
  *
  * @since 4.0.0
  */