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

package/src/BunMultipart.ts

@@ -1,5 +1,24 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect"
 import type { FileSystem } from "effect/FileSystem"
@@ -10,20 +29,31 @@ import * as Multipart from "effect/unstable/http/Multipart"
 import * as BunStream from "./BunStream.ts"
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Parses a Bun `Request` body as multipart data and returns a stream of multipart parts.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const stream = (source: Request): Stream.Stream<Multipart.Part, Multipart.MultipartError> =>
   BunStream.fromReadableStream({
-    evaluate: () => source.body!,
+    evaluate: () => source.body ?? emptyReadbleStream,
     onError: (cause) => Multipart.MultipartError.fromReason("InternalError", cause)
   }).pipe(
     Stream.pipeThroughChannel(Multipart.makeChannel(Object.fromEntries(source.headers)))
   )
 
+const emptyReadbleStream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(new Uint8Array())
+    controller.close()
+  }
+})
+
 /**
- * @since 1.0.0
- * @category Constructors
+ * Parses and persists multipart data from a Bun `Request`, requiring file-system, path, and scope services.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const persisted = (
   source: Request

package/src/BunPath.ts

@@ -1,24 +1,47 @@
 /**
- * @since 1.0.0
+ * Bun layers for Effect's `Path` service.
+ *
+ * Use this module when an Effect program running on Bun needs path
+ * manipulation from the `Path` service, such as joining and normalizing local
+ * filesystem locations, resolving configuration or static asset paths, handling
+ * CLI path arguments, or converting between filesystem paths and `file:` URLs.
+ *
+ * Bun exposes Node-compatible path behavior, so these layers reuse the shared
+ * Node path implementation. The default `layer` follows the host operating
+ * system's path rules, including separators, absolute paths, drive letters, and
+ * UNC paths where applicable. Use `layerPosix` or `layerWin32` when code needs
+ * stable POSIX or Windows semantics regardless of where Bun is running. These
+ * layers only manipulate path strings; they do not read the filesystem, validate
+ * that paths exist, or turn request URLs into safe local paths. `BunServices`
+ * already includes the default Bun path layer, so provide this module directly
+ * when you need only `Path` or one of the platform-specific variants.
+ *
+ * @since 4.0.0
  */
 import * as NodePath from "@effect/platform-node-shared/NodePath"
 import type * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
 
 /**
- * @since 1.0.0
- * @category layer
+ * Layer that provides the default `Path` service for Bun using the shared Node path implementation.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = NodePath.layer
 
 /**
- * @since 1.0.0
- * @category layer
+ * Layer that provides the POSIX `Path` service for Bun using the shared Node path implementation.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerPosix: Layer.Layer<Path> = NodePath.layerPosix
 
 /**
- * @since 1.0.0
- * @category layer
+ * Layer that provides the Win32 `Path` service for Bun using the shared Node path implementation.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWin32: Layer.Layer<Path> = NodePath.layerWin32

package/src/BunRedis.ts

@@ -1,20 +1,46 @@
 /**
- * @since 1.0.0
+ * 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,
+ * distributed rate limiting, custom Redis commands, or Bun Redis features such
+ * as pub/sub through the raw client.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
 import { RedisClient, type RedisOptions } from "bun"
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Fn from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Redis from "effect/unstable/persistence/Redis"
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for Bun Redis integration, exposing the raw `RedisClient` and a `use` helper that maps client promise failures to `RedisError`.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class BunRedis extends ServiceMap.Service<BunRedis, {
+export class BunRedis extends Context.Service<BunRedis, {
   readonly client: RedisClient
   readonly use: <A>(f: (client: RedisClient) => Promise<A>) => Effect.Effect<A, Redis.RedisError>
 }>()("@effect/platform-bun/BunRedis") {}
@@ -47,28 +73,32 @@ const make = Effect.fnUntraced(function*(
     use
   })
 
-  return ServiceMap.make(BunRedis, bunRedis).pipe(
-    ServiceMap.add(Redis.Redis, redis)
+  return Context.make(BunRedis, bunRedis).pipe(
+    Context.add(Redis.Redis, redis)
   )
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates scoped Bun Redis layers for `Redis.Redis` and `BunRedis`, closing the underlying client when the scope finalizes.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   options?: ({ readonly url?: string } & RedisOptions) | undefined
-): Layer.Layer<Redis.Redis | BunRedis> => Layer.effectServices(make(options))
+): Layer.Layer<Redis.Redis | BunRedis> => Layer.effectContext(make(options))
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates scoped Bun Redis layers from configurable Redis options, closing the underlying client when the scope finalizes.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (
   options: Config.Wrap<{ readonly url?: string } & RedisOptions>
 ): Layer.Layer<Redis.Redis | BunRedis, Config.ConfigError> =>
-  Layer.effectServices(
-    Config.unwrap(options).asEffect().pipe(
+  Layer.effectContext(
+    Config.unwrap(options).pipe(
       Effect.flatMap(make)
     )
   )

package/src/BunRuntime.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * Bun entry-point helpers for running 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.
+ *
+ * `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.
+ *
+ * @since 4.0.0
  */
 import * as NodeRuntime from "@effect/platform-node-shared/NodeRuntime"
 import type { Effect } from "effect/Effect"
@@ -8,6 +24,12 @@ import type { Teardown } from "effect/Runtime"
 /**
  * Helps you run a main effect with built-in error handling, logging, and signal management.
  *
+ * **When to use**
+ *
+ * Use this function 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.
+ *
  * **Details**
  *
  * This function launches an Effect as the main entry point, setting exit codes
@@ -16,26 +38,24 @@ import type { Teardown } from "effect/Runtime"
  * behaviors can be turned off. You can also provide custom teardown logic to
  * finalize resources or produce different exit codes.
  *
- * **Options**
- *
  * An optional object that can include:
  * - `disableErrorReporting`: Turn off automatic error logging.
  * - `disablePrettyLogger`: Avoid adding the pretty logger.
  * - `teardown`: Provide custom finalization logic.
  *
- * **When to Use**
- *
- * Use this function 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.
- *
- * @since 1.0.0
- * @category Run main
+ * @category running
+ * @since 4.0.0
  */
 export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **When to use**
+   *
+   * Use this function 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -44,21 +64,13 @@ export const runMain: {
    * behaviors can be turned off. You can also provide custom teardown logic to
    * finalize resources or produce different exit codes.
    *
-   * **Options**
-   *
    * An optional object that can include:
    * - `disableErrorReporting`: Turn off automatic error logging.
    * - `disablePrettyLogger`: Avoid adding the pretty logger.
    * - `teardown`: Provide custom finalization logic.
    *
-   * **When to Use**
-   *
-   * Use this function 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.
-   *
-   * @since 1.0.0
-   * @category Run main
+   * @category running
+   * @since 4.0.0
    */
   (
     options?: {
@@ -69,6 +81,12 @@ export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **When to use**
+   *
+   * Use this function 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -77,21 +95,13 @@ export const runMain: {
    * behaviors can be turned off. You can also provide custom teardown logic to
    * finalize resources or produce different exit codes.
    *
-   * **Options**
-   *
    * An optional object that can include:
    * - `disableErrorReporting`: Turn off automatic error logging.
    * - `disablePrettyLogger`: Avoid adding the pretty logger.
    * - `teardown`: Provide custom finalization logic.
    *
-   * **When to Use**
-   *
-   * Use this function 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.
-   *
-   * @since 1.0.0
-   * @category Run main
+   * @category running
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect<A, E>,

package/src/BunServices.ts

@@ -1,6 +1,27 @@
 /**
- * @since 1.0.0
+ * Provides the aggregate Bun platform services layer for applications that run
+ * on the Bun runtime.
+ *
+ * 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.
+ *
+ * @since 4.0.0
  */
+import type { Crypto } from "effect/Crypto"
 import type { FileSystem } from "effect/FileSystem"
 import * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
@@ -8,24 +29,32 @@ import type { Stdio } from "effect/Stdio"
 import type { Terminal } from "effect/Terminal"
 import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
 import * as BunChildProcessSpawner from "./BunChildProcessSpawner.ts"
+import * as BunCrypto from "./BunCrypto.ts"
 import * as BunFileSystem from "./BunFileSystem.ts"
 import * as BunPath from "./BunPath.ts"
 import * as BunStdio from "./BunStdio.ts"
 import * as BunTerminal from "./BunTerminal.ts"
 
 /**
- * @since 1.0.0
+ * The union of core services provided by the Bun platform layer, including child
+ * process spawning, filesystem, path, stdio, and terminal services.
+ *
  * @category models
+ * @since 4.0.0
  */
-export type BunServices = ChildProcessSpawner | FileSystem | Path | Terminal | Stdio
+export type BunServices = ChildProcessSpawner | Crypto | FileSystem | Path | Terminal | Stdio
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the default Bun implementations for child process spawning,
+ * filesystem, path, stdio, and terminal services.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<BunServices> = BunChildProcessSpawner.layer.pipe(
   Layer.provideMerge(Layer.mergeAll(
     BunFileSystem.layer,
+    BunCrypto.layer,
     BunPath.layer,
     BunStdio.layer,
     BunTerminal.layer

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