@effect/platform-bun 4.0.0-beta.9 → 4.0.0-beta.91

package/src/BunClusterHttp.ts

@@ -1,9 +1,17 @@
 /**
- * @since 1.0.0
+ * Bun HTTP and WebSocket layers for Effect Cluster runners.
+ *
+ * `layerHttpServer` provides the Bun HTTP server used by cluster runners. The
+ * main `layer` builds a sharding layer for HTTP or WebSocket transport,
+ * choosing serialization, runner health checks, runner storage, message
+ * storage, and optional client-only mode from the supplied options.
+ *
+ * @since 4.0.0
  */
 import type * as Config from "effect/Config"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as HttpRunner from "effect/unstable/cluster/HttpRunner"
 import * as MessageStorage from "effect/unstable/cluster/MessageStorage"
 import * as RunnerHealth from "effect/unstable/cluster/RunnerHealth"
@@ -28,15 +36,19 @@ import * as BunSocket from "./BunSocket.ts"
 
 export {
   /**
-   * @since 1.0.0
-   * @category Re-exports
+   * Layer that provides a Kubernetes HTTP client for runner health checks.
+   *
+   * @category re-exports
+   * @since 4.0.0
    */
   layerK8sHttpClient
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides a Bun HTTP server for cluster runners.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerHttpServer: Layer.Layer<
   | HttpPlatform
@@ -47,16 +59,42 @@ export const layerHttpServer: Layer.Layer<
   ShardingConfig.ShardingConfig
 > = Effect.gen(function*() {
   const config = yield* ShardingConfig.ShardingConfig
-  const listenAddress = config.runnerListenAddress ?? config.runnerAddress
-  if (listenAddress === undefined) {
-    return yield* Effect.die("BunClusterHttp.layerHttpServer: ShardingConfig.runnerAddress is undefined")
+  const listenAddress = Option.orElse(config.runnerListenAddress, () => config.runnerAddress)
+  if (Option.isNone(listenAddress)) {
+    return yield* Effect.die("BunClusterHttp.layerHttpServer: ShardingConfig.runnerAddress is None")
   }
-  return BunHttpServer.layer(listenAddress)
+  return BunHttpServer.layer(listenAddress.value)
 }).pipe(Layer.unwrap)
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates Bun cluster layers for HTTP or WebSocket transport, configuring serialization, storage, runner health, and optional client-only mode.
+ *
+ * **When to use**
+ *
+ * Use to install the complete Bun HTTP or WebSocket cluster layer, including
+ * client-only cluster access when a process should connect without serving
+ * runner RPCs.
+ *
+ * **Details**
+ *
+ * `serialization` defaults to MessagePack, `runnerHealth` defaults to ping
+ * checks, SQL-backed storage is used by default, and `shardingConfig` is
+ * overlaid on environment-loaded sharding configuration. `local` storage uses
+ * no-op message storage plus in-memory runner storage, while `byo` leaves both
+ * message and runner storage for the caller to provide.
+ *
+ * **Gotchas**
+ *
+ * `clientOnly` does not start the HTTP server or receive shard assignments.
+ * Non-client-only mode listens with `runnerListenAddress` when present, falling
+ * back to `runnerAddress`. HTTP and WebSocket runner RPCs use the default
+ * `HttpRunner` route.
+ *
+ * @see {@link layerHttpServer} for the server layer used by non-client-only transports
+ * @see {@link layerK8sHttpClient} for Kubernetes runner health support
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = <
   const ClientOnly extends boolean = false,

package/src/BunClusterSocket.ts

@@ -1,5 +1,13 @@
 /**
- * @since 1.0.0
+ * Bun socket layers for Effect Cluster runners.
+ *
+ * The main `layer` builds a sharding layer for socket transport, choosing
+ * serialization, runner health checks, runner storage, message storage, and
+ * optional client-only mode from the supplied options. This module also
+ * re-exports the shared socket client and server protocol layers and provides
+ * `layerK8sHttpClient` for Kubernetes runner health checks.
+ *
+ * @since 4.0.0
  */
 import { layerClientProtocol, layerSocketServer } from "@effect/platform-node-shared/NodeClusterSocket"
 import type * as Config from "effect/Config"
@@ -24,20 +32,28 @@ import * as BunFileSystem from "./BunFileSystem.ts"
 
 export {
   /**
-   * @since 1.0.0
-   * @category Re-exports
+   * Provides the cluster `RpcClientProtocol` using the shared socket client
+   * implementation.
+   *
+   * @category re-exports
+   * @since 4.0.0
    */
   layerClientProtocol,
   /**
-   * @since 1.0.0
-   * @category Re-exports
+   * Provides the socket server used by Bun cluster runners through the shared
+   * socket server implementation.
+   *
+   * @category re-exports
+   * @since 4.0.0
    */
   layerSocketServer
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates Bun socket cluster layers, configuring serialization, storage, runner health, and optional client-only mode.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = <
   const ClientOnly extends boolean = false,
@@ -110,8 +126,10 @@ export const layer = <
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides `K8sHttpClient`, using the Kubernetes service-account CA certificate when it is available.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerK8sHttpClient: Layer.Layer<K8sHttpClient.K8sHttpClient> = K8sHttpClient.layer.pipe(
   Layer.provide(Layer.unwrap(Effect.gen(function*() {

package/src/BunCrypto.ts

@@ -0,0 +1,24 @@
+/**
+ * The `BunCrypto` module provides Bun's `Crypto` service layer for Effect
+ * programs. Provide {@link layer} at the edge of a Bun app, CLI, script, or
+ * test to satisfy `effect/Crypto` with cryptographically secure random bytes,
+ * UUID generation, random values, and SHA digest operations.
+ *
+ * This adapter reuses the shared Node-compatible implementation, so randomness
+ * and digest behavior follow Bun's `node:crypto` compatibility layer. SHA-1 is
+ * present for interoperability with existing protocols, not for new
+ * security-sensitive designs.
+ *
+ * @since 1.0.0
+ */
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+import type * as Crypto from "effect/Crypto"
+import type * as Layer from "effect/Layer"
+
+/**
+ * Layer that provides the Bun Crypto service implementation.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer: Layer.Layer<Crypto.Crypto> = NodeCrypto.layer

package/src/BunFileSystem.ts

@@ -1,12 +1,20 @@
 /**
- * @since 1.0.0
+ * Bun layer for Effect's `FileSystem` service.
+ *
+ * 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
  */
 import * as NodeFileSystem from "@effect/platform-node-shared/NodeFileSystem"
 import type { FileSystem } from "effect/FileSystem"
 import type * as Layer from "effect/Layer"
 
 /**
- * @since 1.0.0
- * @category layer
+ * Layer that provides the `FileSystem` service for Bun using the shared Node file-system implementation.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<FileSystem, never, never> = NodeFileSystem.layer

package/src/BunHttpClient.ts

@@ -1,9 +1,9 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "effect/unstable/http/FetchHttpClient"

package/src/BunHttpPlatform.ts

@@ -1,5 +1,13 @@
 /**
- * @since 1.0.0
+ * Bun implementation of the Effect HTTP platform service.
+ *
+ * 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
  */
 import type { Effect } from "effect"
 import type { FileSystem } from "effect/FileSystem"
@@ -10,8 +18,8 @@ import * as Response from "effect/unstable/http/HttpServerResponse"
 import * as BunFileSystem from "./BunFileSystem.ts"
 
 /**
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 const make: Effect.Effect<
   Platform.HttpPlatform["Service"],
@@ -31,8 +39,10 @@ const make: Effect.Effect<
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides the Bun `HttpPlatform`, including file responses backed by `Bun.file`.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = Layer.effect(Platform.HttpPlatform)(make).pipe(
   Layer.provide(BunFileSystem.layer),

package/src/BunHttpServer.ts

@@ -1,10 +1,22 @@
 /**
- * @since 1.0.0
+ * Bun implementation of the Effect `HttpServer`.
+ *
+ * `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
  */
 import type { Server as BunServer, ServerWebSocket } from "bun"
 import * as Config from "effect/Config"
 import type { ConfigError } from "effect/Config"
+import * as Context from "effect/Context"
 import * as Deferred from "effect/Deferred"
+import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
 import * as Fiber from "effect/Fiber"
@@ -13,11 +25,12 @@ import type * as FileSystem from "effect/FileSystem"
 import { flow } from "effect/Function"
 import * as Inspectable from "effect/Inspectable"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import type * as Path from "effect/Path"
 import type * as Record from "effect/Record"
-import type * as Scope from "effect/Scope"
+import type * as Schema from "effect/Schema"
+import * as Scope from "effect/Scope"
 import * as Semaphore from "effect/Semaphore"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import * as Cookies from "effect/unstable/http/Cookies"
 import * as Etag from "effect/unstable/http/Etag"
@@ -41,8 +54,10 @@ import * as BunServices from "./BunServices.ts"
 import * as BunStream from "./BunStream.ts"
 
 /**
- * @since 1.0.0
- * @category Options
+ * Bun serve options accepted by the HTTP server, extended with typed route definitions.
+ *
+ * @category options
+ * @since 4.0.0
  */
 export type ServeOptions<R extends string> =
   & (
@@ -52,13 +67,19 @@ export type ServeOptions<R extends string> =
   & { readonly routes?: Bun.Serve.Routes<WebSocketContext, R> }
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Creates a scoped Bun `HttpServer` from `Bun.serve` options, stopping the server on scope finalization with optional graceful shutdown settings.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(
   function*<R extends string>(
-    options: ServeOptions<R>
+    options: ServeOptions<R> & {
+      readonly disablePreemptiveShutdown?: boolean | undefined
+      readonly gracefulShutdownTimeout?: Duration.Input | undefined
+    }
   ) {
+    const scope = yield* Effect.scope
     const handlerStack: Array<(request: Request, server: BunServer<WebSocketContext>) => Response | Promise<Response>> =
       [
         function(_request, _server) {
@@ -76,6 +97,7 @@ export const make = Effect.fnUntraced(
           ws.data.run(message)
         },
         close(ws, code, closeReason) {
+          code = typeof code === "number" ? code : 1001
           Deferred.doneUnsafe(
             ws.data.closeDeferred,
             Socket.defaultCloseCodeIsError(code)
@@ -90,13 +112,24 @@ export const make = Effect.fnUntraced(
       }
     })
 
-    yield* Effect.addFinalizer(() => Effect.promise(() => server.stop()))
+    const shutdown = yield* Effect.promise(() => server.stop()).pipe(
+      Effect.cached
+    )
+    const preemptiveShutdown = options.disablePreemptiveShutdown ? Effect.void : Effect.timeoutOrElse(shutdown, {
+      duration: options.gracefulShutdownTimeout ?? Duration.seconds(20),
+      orElse: () => Effect.void
+    })
+
+    yield* Scope.addFinalizer(scope, shutdown)
 
     return Server.make({
       address: { _tag: "TcpAddress", port: server.port!, hostname: server.hostname! },
       serve: Effect.fnUntraced(function*(httpApp, middleware) {
-        const scope = yield* Effect.scope
-        const services = yield* Effect.services<never>()
+        const parent = yield* Effect.fiber
+        const services = parent.context
+        const serveScope = Context.getUnsafe(services, Scope.Scope)
+        const scope = Scope.forkUnsafe(serveScope, "parallel")
+
         const httpEffect = HttpEffect.toHandled(httpApp, (request, response) =>
           Effect.sync(() => {
             ;(request as BunServerRequest).resolve(makeResponse(request, response, services, scope))
@@ -109,24 +142,20 @@ export const make = Effect.fnUntraced(
               ServerRequest.HttpServerRequest.key,
               new BunServerRequest(request, resolve, removeHost(request.url), server)
             )
-            const fiber = Fiber.runIn(Effect.runForkWith(ServiceMap.makeUnsafe<any>(map))(httpEffect), scope)
+            const fiber = Fiber.runIn(Effect.runForkWith(Context.makeUnsafe<any>(map))(httpEffect), scope)
             request.signal.addEventListener("abort", () => {
-              fiber.interruptUnsafe(Error.clientAbortFiberId)
+              fiber.interruptUnsafe(parent.id, Error.ClientAbort.annotation)
             }, { once: true })
           })
         }
 
-        yield* Effect.acquireRelease(
-          Effect.sync(() => {
-            handlerStack.push(handler)
-            server.reload({ fetch: handler })
-          }),
-          () =>
-            Effect.sync(() => {
-              handlerStack.pop()
-              server.reload({ fetch: handlerStack[handlerStack.length - 1] })
-            })
-        )
+        yield* Scope.addFinalizerExit(serveScope, () => {
+          handlerStack.pop()
+          server.reload({ fetch: handlerStack[handlerStack.length - 1] })
+          return preemptiveShutdown
+        })
+        handlerStack.push(handler)
+        server.reload({ fetch: handler })
       })
     })
   }
@@ -135,7 +164,7 @@ export const make = Effect.fnUntraced(
 const makeResponse = (
   request: ServerRequest.HttpServerRequest,
   response: ServerResponse.HttpServerResponse,
-  services: ServiceMap.ServiceMap<never>,
+  context: Context.Context<never>,
   scope: Scope.Scope
 ): Response => {
   const fields: {
@@ -186,7 +215,7 @@ const makeResponse = (
             Fiber.runIn(fiber, scope)
             return Effect.succeed(body.stream)
           })),
-          services
+          context
         ),
         fields
       )
@@ -195,16 +224,23 @@ const makeResponse = (
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides only `HttpServer` by constructing a scoped Bun server from the supplied serve options.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerServer: <R extends string>(
-  options: ServeOptions<R>
+  options: ServeOptions<R> & {
+    readonly disablePreemptiveShutdown?: boolean | undefined
+    readonly gracefulShutdownTimeout?: Duration.Input | undefined
+  }
 ) => Layer.Layer<Server.HttpServer> = flow(make, Layer.effect(Server.HttpServer)) as any
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides Bun HTTP support services: `HttpPlatform`, weak ETag generation, and `BunServices`.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerHttpServices: Layer.Layer<
   | HttpPlatform
@@ -217,11 +253,16 @@ export const layerHttpServices: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides a Bun `HttpServer` together with the Bun HTTP platform, ETag generator, and Bun services.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = <R extends string>(
-  options: ServeOptions<R>
+  options: ServeOptions<R> & {
+    readonly disablePreemptiveShutdown?: boolean | undefined
+    readonly gracefulShutdownTimeout?: Duration.Input | undefined
+  }
 ): Layer.Layer<
   | Server.HttpServer
   | HttpPlatform
@@ -230,8 +271,10 @@ export const layer = <R extends string>(
 > => Layer.mergeAll(layerServer(options), layerHttpServices)
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that starts a Bun HTTP server on an ephemeral port for tests.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerTest: Layer.Layer<
   Server.HttpServer | HttpPlatform | FileSystem.FileSystem | Etag.Generator | Path.Path | HttpClient
@@ -243,17 +286,24 @@ export const layerTest: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates the Bun HTTP server and support-services layer from configurable serve options.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = <R extends string>(
-  options: Config.Wrap<ServeOptions<R>>
+  options: Config.Wrap<
+    ServeOptions<R> & {
+      readonly disablePreemptiveShutdown?: boolean | undefined
+      readonly gracefulShutdownTimeout?: Duration.Input | undefined
+    }
+  >
 ): Layer.Layer<
   Server.HttpServer | HttpPlatform | FileSystem.FileSystem | Etag.Generator | Path.Path,
   ConfigError
 > =>
   Layer.mergeAll(
-    Layer.effect(Server.HttpServer)(Effect.flatMap(Config.unwrap(options).asEffect(), make)),
+    Layer.effect(Server.HttpServer)(Effect.flatMap(Config.unwrap(options), make)),
     layerHttpServices
   )
 
@@ -280,7 +330,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
   readonly url: string
   private bunServer: BunServer<WebSocketContext>
   public headersOverride?: Headers.Headers | undefined
-  private remoteAddressOverride?: string | undefined
+  private remoteAddressOverride?: Option.Option<string> | undefined
 
   constructor(
     source: Request,
@@ -288,7 +338,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
     url: string,
     bunServer: BunServer<WebSocketContext>,
     headersOverride?: Headers.Headers,
-    remoteAddressOverride?: string
+    remoteAddressOverride?: Option.Option<string>
   ) {
     super()
     this[ServerRequest.TypeId] = ServerRequest.TypeId
@@ -311,7 +361,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
     options: {
       readonly url?: string | undefined
       readonly headers?: Headers.Headers | undefined
-      readonly remoteAddress?: string | undefined
+      readonly remoteAddress?: Option.Option<string> | undefined
     }
   ) {
     return new BunServerRequest(
@@ -320,7 +370,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
       options.url ?? this.url,
       this.bunServer,
       options.headers ?? this.headersOverride,
-      options.remoteAddress ?? this.remoteAddressOverride
+      "remoteAddress" in options ? options.remoteAddress : this.remoteAddressOverride
     )
   }
   get method(): HttpMethod {
@@ -329,8 +379,8 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
   get originalUrl() {
     return this.source.url
   }
-  get remoteAddress(): string | undefined {
-    return this.remoteAddressOverride ?? this.bunServer.requestIP(this.source)?.address
+  get remoteAddress(): Option.Option<string> {
+    return this.remoteAddressOverride ?? Option.fromNullishOr(this.bunServer.requestIP(this.source)?.address)
   }
   get headers(): Headers.Headers {
     this.headersOverride ??= Headers.fromInput(this.source.headers)
@@ -348,7 +398,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
   get stream(): Stream.Stream<Uint8Array, Error.HttpServerError> {
     return this.source.body
       ? BunStream.fromReadableStream({
-        evaluate: () => this.source.body as any,
+        evaluate: () => this.source.body ?? emptyReadbleStream,
         onError: (cause) =>
           new Error.HttpServerError({
             reason: new Error.RequestParseError({
@@ -387,10 +437,10 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
     return this.textEffect
   }
 
-  get json(): Effect.Effect<unknown, Error.HttpServerError> {
+  get json(): Effect.Effect<Schema.Json, Error.HttpServerError> {
     return Effect.flatMap(this.text, (_) =>
       Effect.try({
-        try: () => JSON.parse(_) as unknown,
+        try: () => JSON.parse(_) as Schema.Json,
         catch: (cause) =>
           new Error.HttpServerError({
             reason: new Error.RequestParseError({
@@ -457,6 +507,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
           })
       })
     ))
+    this.textEffect = Effect.map(this.arrayBufferEffect, (_) => new TextDecoder().decode(_))
     return this.arrayBufferEffect
   }
 
@@ -524,14 +575,7 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
           semaphore.withPermits(1)
         )
 
-        const encoder = new TextEncoder()
-        const run = <R, E, _>(handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void, opts?: {
-          readonly onOpen?: Effect.Effect<void> | undefined
-        }) => runRaw((data) => typeof data === "string" ? handler(encoder.encode(data)) : handler(data), opts)
-
-        return Socket.Socket.of({
-          [Socket.TypeId]: Socket.TypeId as typeof Socket.TypeId,
-          run,
+        return Socket.make({
           runRaw,
           writer
         })
@@ -540,6 +584,13 @@ class BunServerRequest extends Inspectable.Class implements ServerRequest.HttpSe
   }
 }
 
+const emptyReadbleStream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(new Uint8Array())
+    controller.close()
+  }
+})
+
 const removeHost = (url: string) => {
   if (url[0] === "/") {
     return url

package/src/BunHttpServerRequest.ts

@@ -1,11 +1,19 @@
 /**
- * @since 1.0.0
+ * Accessor for the Bun request behind an Effect HTTP server request.
+ *
+ * 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
  */
 import type { HttpServerRequest } from "effect/unstable/http/HttpServerRequest"
 
 /**
- * @since 1.0.0
- * @category Accessors
+ * Returns the underlying `Bun.BunRequest` from an Effect `HttpServerRequest`.
+ *
+ * @category accessors
+ * @since 4.0.0
  */
 export const toBunServerRequest = <T extends string = string>(self: HttpServerRequest): Bun.BunRequest<T> =>
   (self as any).source

package/src/BunMultipart.ts

@@ -1,5 +1,12 @@
 /**
- * @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. `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
  */
 import type * as Effect from "effect/Effect"
 import type { FileSystem } from "effect/FileSystem"
@@ -10,20 +17,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