@effect/platform-browser 4.0.0-beta.66 → 4.0.0-beta.68

package/src/BrowserKeyValueStore.ts

@@ -1,16 +1,34 @@
 /**
- * @since 1.0.0
+ * Browser-backed `KeyValueStore` layers for Effect programs.
+ *
+ * This module provides `KeyValueStore` implementations backed by the browser's
+ * synchronous Web Storage APIs: `localStorage` for origin-scoped data that
+ * persists across page reloads and browser sessions, and `sessionStorage` for
+ * page-session data that is cleared when that tab or window's page session
+ * ends. They are useful for small client-side values such as user preferences,
+ * feature flags, lightweight caches, persisted drafts, or session-only workflow
+ * state.
+ *
+ * Web Storage is only available in browser environments and is scoped by origin.
+ * Browsers may deny access in private modes or restricted contexts, and writes
+ * can fail when storage quotas are exceeded. The API stores strings and runs
+ * synchronously on the main thread, so prefer it for small payloads and avoid
+ * treating it as a database or a secure place for sensitive data.
+ *
+ * @since 4.0.0
  */
-import type * as Layer from "effect/Layer"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
 import * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+import { IndexedDb } from "./IndexedDb.ts"
 
 /**
  * Creates a `KeyValueStore` layer that uses the browser's `localStorage` api.
  *
  * Values are stored between sessions.
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layerLocalStorage: Layer.Layer<KeyValueStore.KeyValueStore> = KeyValueStore.layerStorage(() =>
   globalThis.localStorage
@@ -21,9 +39,129 @@ export const layerLocalStorage: Layer.Layer<KeyValueStore.KeyValueStore> = KeyVa
  *
  * Values are stored only for the current session.
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layerSessionStorage: Layer.Layer<KeyValueStore.KeyValueStore> = KeyValueStore.layerStorage(() =>
   globalThis.sessionStorage
 )
+
+/**
+ * Creates a `KeyValueStore` layer backed by IndexedDB.
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerIndexedDb = (options?: {
+  readonly database?: string | undefined
+}): Layer.Layer<KeyValueStore.KeyValueStore, never, IndexedDb> =>
+  Layer.effect(KeyValueStore.KeyValueStore)(
+    Effect.gen(function*() {
+      const db = yield* Effect.acquireRelease(
+        openDatabase(options?.database ?? "effect_key_value_store"),
+        (db) => Effect.sync(() => db.close())
+      ).pipe(Effect.orDie)
+
+      return KeyValueStore.make({
+        clear: Effect.suspend(() => {
+          const store = getKvsEntriesStore(db, "readwrite")
+          return idbRequest({ method: "clear", message: "Failed to clear backing store" }, () => store.clear())
+        }),
+        get: (key: string) =>
+          Effect.map(
+            Effect.suspend(() => {
+              const store = getKvsEntriesStore(db, "readonly")
+              return idbRequest<{ key: string; value: string } | undefined>({
+                method: "get",
+                message: "Failed to get value from backing store",
+                key
+              }, () => store.get(key))
+            }),
+            (found) => typeof found?.value === "string" ? found.value : undefined
+          ),
+        getUint8Array: (key: string) =>
+          Effect.map(
+            Effect.suspend(() => {
+              const store = getKvsEntriesStore(db, "readonly")
+              return idbRequest<{ key: string; value: Uint8Array } | undefined>({
+                method: "getUint8Array",
+                message: "Failed to get value from backing store",
+                key
+              }, () => store.get(key))
+            }),
+            (found) => found?.value && found.value instanceof Uint8Array ? found.value : undefined
+          ),
+        set: (key: string, value: string | Uint8Array) =>
+          Effect.asVoid(Effect.suspend(() => {
+            const store = getKvsEntriesStore(db, "readwrite")
+            return idbRequest(
+              { method: "set", message: "Failed to set value in backing store", key },
+              () => store.put({ key, value })
+            )
+          })),
+        size: Effect.suspend(() => {
+          const store = getKvsEntriesStore(db, "readonly")
+          return idbRequest<number>(
+            { method: "size", message: "Failed to get backing store size" },
+            () => store.count()
+          )
+        }),
+        remove: (key: string) =>
+          Effect.asVoid(Effect.suspend(() => {
+            const store = getKvsEntriesStore(db, "readwrite")
+            return idbRequest(
+              { method: "remove", message: "Failed to remove value from backing store", key },
+              () => store.delete(key)
+            )
+          }))
+      })
+    })
+  )
+
+const databaseVersion = 1
+const entriesStoreName = "entries"
+const openDatabase = Effect.fnUntraced(function*(database: string) {
+  const idb = (yield* IndexedDb).indexedDB
+  const openRequest = yield* Effect.try({
+    try: () => idb.open(database, databaseVersion),
+    catch: (cause) =>
+      new KeyValueStore.KeyValueStoreError({
+        method: "open",
+        message: "Failed to open backing store database",
+        cause
+      })
+  })
+  openRequest.onupgradeneeded = () => {
+    const db = openRequest.result
+    if (!db.objectStoreNames.contains(entriesStoreName)) {
+      db.createObjectStore(entriesStoreName, { keyPath: "key" })
+    }
+  }
+  return yield* idbRequest({ method: "open", message: "Failed to open backing store database" }, () => openRequest)
+})
+
+const idbRequest = <A>(
+  failArgs: { method: string; message: string; key?: string },
+  evaluate: () => IDBRequest<A>
+): Effect.Effect<A, KeyValueStore.KeyValueStoreError> =>
+  Effect.callback<A, KeyValueStore.KeyValueStoreError>((resume) => {
+    const request = evaluate()
+    if (request.readyState === "done") {
+      return resume(Effect.succeed(request.result))
+    }
+    request.onsuccess = () => {
+      resume(Effect.succeed(request.result))
+    }
+    request.onerror = () =>
+      resume(Effect.fail(
+        new KeyValueStore.KeyValueStoreError({
+          ...failArgs,
+          cause: request.error
+        })
+      ))
+  })
+
+const getKvsEntriesStore = (db: IDBDatabase, mode: IDBTransactionMode) => {
+  const transaction = db.transaction(entriesStoreName, mode)
+  return transaction.objectStore(entriesStoreName)
+}

package/src/BrowserPersistence.ts

@@ -1,5 +1,17 @@
 /**
- * @since 1.0.0
+ * Browser-backed persistence layers for Effect's persistence service.
+ *
+ * This module provides IndexedDB implementations of the Effect persistence services for applications that need a
+ * durable client-side cache, such as remembered query results, offline-capable workflows, or values that should survive
+ * page reloads. Entries are stored by persistence store id and key in a shared IndexedDB object store, with optional
+ * expiration timestamps for TTL-based invalidation.
+ *
+ * Because this storage depends on browser IndexedDB, operations can fail when storage is unavailable, quota is exceeded,
+ * data is cleared by the user or browser, or the payload cannot be structured-cloned by IndexedDB. Expired entries are
+ * removed lazily when they are read, so this module is best suited for application-managed cached objects rather than
+ * security-sensitive or authoritative data.
+ *
+ * @since 4.0.0
  */
 import type * as Arr from "effect/Array"
 import * as Clock from "effect/Clock"
@@ -9,8 +21,10 @@ import * as Layer from "effect/Layer"
 import * as Persistence from "effect/unstable/persistence/Persistence"
 
 /**
- * @since 1.0.0
+ * Creates a `BackingPersistence` layer backed by IndexedDB, optionally using the provided database name.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerBackingIndexedDb = (options?: {
   readonly database?: string | undefined
@@ -42,8 +56,10 @@ const entriesStoreName = "entries"
 const storeIdIndexName = "storeId"
 
 /**
- * @since 1.0.0
+ * Creates a `Persistence` layer backed by IndexedDB, optionally using the provided database name.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerIndexedDb = (options?: {
   readonly database?: string | undefined

package/src/BrowserRuntime.ts

@@ -1,17 +1,42 @@
 /**
- * @since 1.0.0
+ * Browser entry-point helpers for running Effect programs.
+ *
+ * This module exposes `runMain`, a browser-oriented main runner for launching
+ * an Effect as the root program of a page, single-page application, demo, or
+ * browser test harness. It delegates execution to the core Effect runtime while
+ * adding the browser lifecycle hook needed to interrupt the main fiber when the
+ * page receives `beforeunload`.
+ *
+ * `BrowserRuntime` does not provide application services by itself. Provide
+ * any required layers, such as browser HTTP, storage, worker, geolocation, or
+ * permission services, before passing the effect to `runMain`. Keep long-lived
+ * browser resources scoped so interruption can run their finalizers while the
+ * page is still active.
+ *
+ * Browser unload is more constrained than a process signal. Finalizers that
+ * need the network, timers, prompts, or long asynchronous work may not complete
+ * once navigation or tab close has started, and browsers do not expose a
+ * process exit status. Use `runMain` to connect the page lifecycle to Effect
+ * interruption, and use browser-specific persistence or delivery APIs for work
+ * that must survive page teardown.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect"
 import { makeRunMain, type Teardown } from "effect/Runtime"
 
 /**
- * @since 1.0.0
+ * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
+ *
  * @category Runtime
+ * @since 4.0.0
  */
 export const runMain: {
   /**
-   * @since 1.0.0
+   * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
+   *
    * @category Runtime
+   * @since 4.0.0
    */
   (
     options?: {
@@ -20,8 +45,10 @@ export const runMain: {
     }
   ): <E, A>(effect: Effect.Effect<A, E>) => void
   /**
-   * @since 1.0.0
+   * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
+   *
    * @category Runtime
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect.Effect<A, E>,

package/src/BrowserSocket.ts

@@ -1,12 +1,37 @@
 /**
- * @since 1.0.0
+ * Browser WebSocket layers for Effect sockets.
+ *
+ * This module provides the browser entry point for `Socket.Socket` values
+ * backed by the platform `WebSocket` implementation. Use `layerWebSocket` when
+ * client-side Effect programs, browser tests, RPC transports, or realtime UI
+ * features need a bidirectional socket connected to a WebSocket URL, and use
+ * `layerWebSocketConstructor` when lower-level socket APIs need access to the
+ * browser constructor service.
+ *
+ * Browser WebSocket rules still apply. Connections are created through
+ * `globalThis.WebSocket`, so URL schemes, subprotocol negotiation, mixed-content
+ * blocking, cookies, authentication, CORS-like origin checks, and extension
+ * negotiation are controlled by the browser and server rather than by Effect.
+ * Close events are translated into socket errors unless the provided
+ * `closeCodeIsError` predicate classifies the close code as clean, which is
+ * useful for protocols that use application-specific close codes.
+ *
+ * Messages are delivered as strings or binary `Uint8Array` values; browser
+ * `Blob` messages are read into bytes before they reach the socket handler.
+ * Outgoing data should already be serialized to a string or bytes, and protocol
+ * frames that represent an intentional close should be sent as `CloseEvent`
+ * values so the underlying `WebSocket.close` code and reason are preserved.
+ *
+ * @since 4.0.0
  */
 import * as Layer from "effect/Layer"
 import * as Socket from "effect/unstable/socket/Socket"
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a `Socket` layer connected to the given URL using the browser `WebSocket` constructor.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket = (url: string, options?: {
   readonly closeCodeIsError?: (code: number) => boolean
@@ -16,10 +41,10 @@ export const layerWebSocket = (url: string, options?: {
   )
 
 /**
- * A WebSocket constructor that uses `globalThis.WebSocket`.
+ * Layer that provides a `WebSocketConstructor` service backed by `globalThis.WebSocket`.
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocketConstructor: Layer.Layer<Socket.WebSocketConstructor> =
   Socket.layerWebSocketConstructorGlobal

package/src/BrowserStream.ts

@@ -1,5 +1,27 @@
 /**
- * @since 1.0.0
+ * Browser `Stream` constructors for DOM event targets.
+ *
+ * This module provides typed helpers for turning `window.addEventListener` and
+ * `document.addEventListener` callbacks into Effect `Stream`s. They are useful
+ * for UI and runtime signals such as resize, visibility, keyboard, pointer,
+ * focus, online / offline, and other browser events that should be composed
+ * with Effect stream operators and finalized with the consuming fiber.
+ *
+ * Browser events are push-based `EventTarget` notifications, so they do not
+ * apply Web Streams backpressure to the browser event source. Events are
+ * buffered until downstream pulls them; the default buffer is unbounded, so
+ * high-frequency sources like scroll, pointermove, or mousemove should usually
+ * set `bufferSize` and use stream operators that sample, debounce, throttle, or
+ * drop work as appropriate.
+ *
+ * These helpers are for DOM events, not for adapting `ReadableStream` request
+ * or response bodies. Fetch bodies follow the Web Streams body rules, including
+ * single-consumer locking and disturbed bodies after reads, and should be
+ * handled with body-specific HTTP or Web Streams APIs instead. When using the
+ * browser `once` option, pair the stream with `Stream.take(1)` if a finite
+ * stream is required.
+ *
+ * @since 4.0.0
  */
 
 import * as Stream from "effect/Stream"
@@ -10,8 +32,8 @@ import * as Stream from "effect/Stream"
  * By default, the underlying buffer is unbounded in size. You can customize the
  * buffer size an object as the second argument with the `bufferSize` field.
  *
- * @since 1.0.0
  * @category Streams
+ * @since 4.0.0
  */
 export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
   type: K,
@@ -29,8 +51,8 @@ export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
  * By default, the underlying buffer is unbounded in size. You can customize the
  * buffer size an object as the second argument with the `bufferSize` field.
  *
- * @since 1.0.0
  * @category Streams
+ * @since 4.0.0
  */
 export const fromEventListenerDocument = <K extends keyof DocumentEventMap>(
   type: K,

package/src/BrowserWorker.ts

@@ -1,5 +1,25 @@
 /**
- * @since 1.0.0
+ * Parent-side browser support for Effect workers.
+ *
+ * This module provides the `WorkerPlatform` used by browser applications that
+ * spawn or connect to `Worker`, `SharedWorker`, and `MessagePort` endpoints
+ * through Effect's worker protocol. Pair it with `BrowserWorkerRunner` in the
+ * worker entrypoint when building worker-backed RPC clients, moving CPU-bound
+ * work off the main thread, isolating browser-only services, or adapting an
+ * existing `MessageChannel` in tests and custom transports.
+ *
+ * Dedicated workers communicate through the worker object itself, while shared
+ * workers communicate through `worker.port`; raw `MessagePort` values are also
+ * accepted and are started when supported. Messages are posted with the browser
+ * structured-clone algorithm, so payloads must be cloneable by the target
+ * runtime. Transfer lists can avoid copying values such as `ArrayBuffer` or
+ * `MessagePort`, but transferring moves ownership away from the sender and
+ * invalid or mismatched transferables can fail the send. Scope finalization
+ * sends the worker close signal over the port; the application that created a
+ * dedicated `Worker` remains responsible for any broader lifecycle such as
+ * terminating it.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -9,8 +29,10 @@ import * as Worker from "effect/unstable/workers/Worker"
 import { WorkerError, WorkerReceiveError } from "effect/unstable/workers/WorkerError"
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates browser worker layers by combining the default `WorkerPlatform` with a spawner for `Worker`, `SharedWorker`, or `MessagePort` instances.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   spawn: (id: number) => Worker | SharedWorker | MessagePort
@@ -21,8 +43,10 @@ export const layer = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides the browser `WorkerPlatform` for `Worker`, `SharedWorker`, and `MessagePort` communication.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(Worker.WorkerPlatform)(
   Worker.makePlatform<globalThis.SharedWorker | globalThis.Worker | MessagePort>()({

package/src/BrowserWorkerRunner.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Browser runtime support for Effect worker runners.
+ *
+ * This module is intended for code that is already executing in a browser
+ * worker context, or for tests and adapters that supply a `MessagePort` or
+ * `Window` endpoint directly. It provides the `WorkerRunnerPlatform` used by
+ * `WorkerRunner` and `RpcServer.layerProtocolWorkerRunner` to receive parent
+ * or client requests, run Effect handlers, and send responses through the
+ * browser `postMessage` channel.
+ *
+ * Use it with `BrowserWorker` when a browser application needs to move RPC
+ * handlers, CPU-bound computations, or browser-only services into a dedicated
+ * worker or shared worker. Dedicated workers communicate through the current
+ * `self` endpoint; shared workers accept multiple `onconnect` ports and cache
+ * ports that connect before the runner layer starts. Messages still use the
+ * browser structured-clone algorithm, so payload schemas, transfer lists,
+ * `messageerror` events, and the lifetime of each `MessagePort` must be
+ * considered when crossing worker boundaries.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -22,8 +40,10 @@ if (typeof self !== "undefined" && "onconnect" in self) {
 }
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Creates a `WorkerRunnerPlatform` service that runs worker handlers over a `MessagePort` or `Window`.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatform["Service"] => ({
   start: Effect.fnUntraced(function*<O = unknown, I = unknown>() {
@@ -151,16 +171,20 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides a browser `WorkerRunnerPlatform` using the global `self` worker context.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.sync(WorkerRunner.WorkerRunnerPlatform)(() =>
   make(self)
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides a `WorkerRunnerPlatform` using the supplied `MessagePort` or `Window`.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerMessagePort = (port: MessagePort | Window): Layer.Layer<WorkerRunner.WorkerRunnerPlatform> =>
   Layer.succeed(WorkerRunner.WorkerRunnerPlatform)(make(port))

package/src/Clipboard.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * Browser clipboard service for Effect programs.
+ *
+ * This module wraps the browser `navigator.clipboard` API in a `Clipboard`
+ * service so client-side applications can read, write, and clear clipboard
+ * contents as typed Effects. It is useful for common UI workflows such as copy
+ * buttons, paste/import actions, sharing generated text, and moving rich
+ * clipboard payloads like `Blob`-backed `ClipboardItem`s through an Effect
+ * environment.
+ *
+ * Browser clipboard rules still apply. Clipboard access generally requires a
+ * secure context, and browsers may require a user gesture, permission prompt, or
+ * active focused document before reads or writes are allowed. Support also
+ * varies by operation and payload type: text helpers are the most portable,
+ * while `ClipboardItem` and non-text MIME types may be unavailable or restricted
+ * in some browsers. Failed browser operations are surfaced as `ClipboardError`.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Data from "effect/Data"
@@ -10,8 +26,10 @@ const TypeId = "~@effect/platform-browser/Clipboard"
 const ErrorTypeId = "~@effect/platform-browser/Clipboard/ClipboardError"
 
 /**
- * @since 1.0.0
- * @category Models
+ * Service interface for reading from, writing to, and clearing the browser clipboard.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Clipboard {
   readonly [TypeId]: typeof TypeId
@@ -24,8 +42,10 @@ export interface Clipboard {
 }
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Tagged error raised when a browser clipboard operation fails.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export class ClipboardError extends Data.TaggedError("ClipboardError")<{
   readonly message: string
@@ -35,14 +55,18 @@ export class ClipboardError extends Data.TaggedError("ClipboardError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the browser `Clipboard` service.
+ *
+ * @category services
+ * @since 4.0.0
  */
 export const Clipboard: Context.Service<Clipboard, Clipboard> = Context.Service<Clipboard>(TypeId)
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Builds a `Clipboard` service from primitive read and write operations, deriving `clear` and `writeBlob` helpers.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = (
   impl: Omit<Clipboard, "clear" | "writeBlob" | typeof TypeId>
@@ -57,8 +81,8 @@ export const make = (
 /**
  * A layer that directly interfaces with the navigator.clipboard api
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Clipboard> = Layer.succeed(
   Clipboard,