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

package/src/BunRuntime.ts

@@ -1,5 +1,34 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as NodeRuntime from "@effect/platform-node-shared/NodeRuntime"
 import type { Effect } from "effect/Effect"
@@ -8,6 +37,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 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 +51,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 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 +77,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 +94,12 @@ export const runMain: {
   /**
    * Helps you run a main effect with built-in error handling, logging, and signal management.
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * This function launches an Effect as the main entry point, setting exit codes
@@ -77,21 +108,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,45 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @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,35 @@
 /**
- * @since 1.0.0
+ * Bun stream interoperability for Effect streams.
+ *
+ * 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`.
+ *
+ * **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"
 import * as Cause from "effect/Cause"
@@ -11,7 +41,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 +49,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,37 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as NodeTerminal from "@effect/platform-node-shared/NodeTerminal"
 import type { Effect } from "effect/Effect"
@@ -8,13 +40,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,40 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -10,8 +45,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 +60,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>()({
@@ -59,7 +101,7 @@ export const layerPlatform = Layer.succeed(Worker.WorkerPlatform)(
               message: "An error event was emitted",
               cause: event.error ?? event.message
             })
-          }).asEffect()
+          })
         )
       }
       port.addEventListener("message", onMessage)

package/src/BunWorkerRunner.ts

@@ -1,5 +1,37 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -15,8 +47,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>() {
@@ -32,7 +68,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
       Effect.scopedWith(Effect.fnUntraced(function*(scope) {
         const closeLatch = Deferred.makeUnsafe<void, WorkerError>()
         const trackFiber = Fiber.runIn(scope)
-        const services = yield* Effect.services<R>()
+        const services = yield* Effect.context<R>()
         const runFork = Effect.runForkWith(services)
         const onExit = (exit: Exit.Exit<any, E>) => {
           if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) {
@@ -62,7 +98,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                 message: "received messageerror event",
                 cause: error.data
               })
-            }).asEffect()
+            })
           )
         }
         function onError(error: MessageEvent) {
@@ -73,7 +109,7 @@ export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.succe
                 message: "received error event",
                 cause: error.data
               })
-            }).asEffect()
+            })
           )
         }
         yield* Scope.addFinalizer(