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

package/src/BrowserKeyValueStore.ts

@@ -6,49 +6,8 @@
  * origin-scoped values that should survive reloads and browser restarts, use
  * {@link layerSessionStorage} for tab / page-session state, and use
  * {@link layerIndexedDb} when the store should be asynchronous and backed by
- * IndexedDB.
- *
- * ## Mental model
- *
- * All exports provide the same `KeyValueStore.KeyValueStore` service; the layer
- * chooses the browser storage backend. The Web Storage layers delegate to
- * `globalThis.localStorage` or `globalThis.sessionStorage` and adapt the
- * string-only API, encoding `Uint8Array` values as base64. The IndexedDB layer
- * stores strings and `Uint8Array` values in an object store and requires the
- * browser `IndexedDb` service to open the database.
- *
- * ## Common tasks
- *
- * - Persist user preferences, lightweight caches, or drafts with
- *   {@link layerLocalStorage}.
- * - Keep tab-scoped workflow state with {@link layerSessionStorage}.
- * - Avoid blocking the main thread for larger client-side stores by using
- *   {@link layerIndexedDb}.
- *
- * ## Gotchas
- *
- * These layers only work where browser storage APIs are available. Browsers may
- * deny storage in private modes, sandboxed frames, disabled-storage settings, or
- * quota-limited contexts. Web Storage is synchronous and origin-scoped, so keep
- * payloads small and do not use it as a secure store for secrets. IndexedDB is
- * asynchronous but can still be blocked by permissions, quota limits, version
- * upgrades, or other open tabs.
- *
- * **Example** (Provide localStorage to a program)
- *
- * ```ts
- * import { BrowserKeyValueStore } from "@effect/platform-browser"
- * import { Effect } from "effect"
- * import { KeyValueStore } from "effect/unstable/persistence"
- *
- * const program = Effect.gen(function*() {
- *   const store = yield* KeyValueStore.KeyValueStore
- *   yield* store.set("theme", "dark")
- *   return yield* store.get("theme")
- * }).pipe(
- *   Effect.provide(BrowserKeyValueStore.layerLocalStorage)
- * )
- * ```
+ * IndexedDB. The IndexedDB layer requires the browser `IndexedDb` service and
+ * accepts an optional database name.
  *
  * @since 4.0.0
  */

package/src/BrowserPersistence.ts

@@ -1,53 +1,11 @@
 /**
  * IndexedDB-backed persistence layers for browser Effect programs.
  *
- * `BrowserPersistence` connects the unstable persistence services to the
- * browser's IndexedDB storage. Use it for client-side caches that should
- * survive page reloads, offline-capable workflows, remembered query results,
- * and other application-managed values that can be recomputed or invalidated
- * when storage is unavailable.
- *
- * **Mental model**
- *
- * - {@link layerIndexedDb} provides the higher-level `Persistence` service by
- *   composing the IndexedDB backing layer with the core persistence layer.
- * - {@link layerBackingIndexedDb} provides only `BackingPersistence` for code
- *   that composes persistence services manually.
- * - Entries live in one IndexedDB database, defaulting to
- *   `"effect_persistence"`, and one object store keyed by `[storeId, key]`.
- * - The `storeId` namespaces persisted request results; the key identifies one
- *   entry inside that store.
- * - Finite TTLs are stored as expiration timestamps and expired entries are
- *   removed lazily when they are read.
- *
- * **Common tasks**
- *
- * - Provide browser persistence to `PersistedCache` or other persistence
- *   workflows with {@link layerIndexedDb}.
- * - Isolate tests, apps, or migrations by passing a custom `database` option.
- * - Use {@link layerBackingIndexedDb} when another layer should decide how to
- *   construct the higher-level `Persistence` service.
- *
- * **Gotchas**
- *
- * - This module requires browser IndexedDB and stores data per origin.
- * - Opening IndexedDB is defected during layer acquisition if the database
- *   cannot be opened; later store operations report `PersistenceError`.
- * - Values must be structured-cloneable objects, and writes can fail because of
- *   quota limits, browser settings, private browsing modes, or user-cleared
- *   storage.
- * - Lazy TTL cleanup makes this suitable for caches, not for authoritative or
- *   security-sensitive state.
- *
- * **Example** (Providing browser persistence)
- *
- * ```ts
- * import { BrowserPersistence } from "@effect/platform-browser"
- *
- * export const PersistenceLive = BrowserPersistence.layerIndexedDb({
- *   database: "my-app-cache"
- * })
- * ```
+ * This module provides a low-level `BackingPersistence` layer and a higher-level
+ * `Persistence` layer that store object values in IndexedDB. Values are stored
+ * by persistence store id and key, and reads check TTL expiration before
+ * returning stored data. The database name can be customized and defaults to
+ * `"effect_persistence"`.
  *
  * @since 4.0.0
  */

package/src/BrowserRuntime.ts

@@ -1,24 +1,9 @@
 /**
- * Browser entry-point helpers for running Effect programs.
+ * Browser helper for running a root Effect program.
  *
- * 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.
+ * This module exports `runMain`, a browser version of the main Effect runner.
+ * It forwards runner options to the core runtime and adds a `beforeunload`
+ * listener that interrupts the main fiber when the page is unloading.
  *
  * @since 4.0.0
  */

package/src/BrowserSocket.ts

@@ -1,40 +1,9 @@
 /**
- * Provide Effect sockets backed by the browser `WebSocket` implementation.
+ * Browser WebSocket layers for Effect sockets.
  *
- * This module is the browser entry point for Effect's socket abstraction. Use
- * {@link layerWebSocket} when a client-side Effect program needs a complete
- * `Socket.Socket` connected to a WebSocket URL. Use
- * {@link layerWebSocketConstructor} when lower-level socket code only needs the
- * browser-backed constructor service.
- *
- * ## Mental model
- *
- * `layerWebSocket` delegates socket behavior to Effect's WebSocket support and
- * supplies `globalThis.WebSocket` as the constructor. Incoming browser messages
- * are normalized to strings or binary `Uint8Array` values. Browser `Blob`
- * messages are read into bytes before they reach the socket consumer.
- *
- * Outgoing data should already be serialized to a string or bytes. To close the
- * underlying browser socket with a specific code and reason, send a
- * `CloseEvent` value so the close metadata is preserved.
- *
- * ## Common tasks
- *
- * - Connect RPC transports, browser tests, or realtime UI features to a
- *   WebSocket URL with {@link layerWebSocket}.
- * - Provide only the browser constructor service with
- *   {@link layerWebSocketConstructor} when another socket layer builds the
- *   connection.
- * - Customize `closeCodeIsError` for protocols that treat specific close codes
- *   as normal completion instead of socket failure.
- *
- * ## Gotchas
- *
- * Browser WebSocket rules still apply. URL schemes, subprotocol negotiation,
- * mixed-content blocking, cookies, authentication, server origin checks, and
- * extension negotiation are controlled by the browser and server rather than by
- * Effect. Close events become socket errors unless `closeCodeIsError`
- * classifies the close code as clean.
+ * `layerWebSocket` creates a `Socket.Socket` connected to a WebSocket URL using
+ * the browser `WebSocket` constructor. `layerWebSocketConstructor` provides
+ * only the browser-backed constructor service for lower-level socket code.
  *
  * @since 4.0.0
  */

package/src/BrowserStream.ts

@@ -1,40 +1,9 @@
 /**
- * Convert browser DOM events into Effect streams.
+ * Browser DOM event streams.
  *
- * This module provides typed constructors for listening to `window` and
- * `document` events from Effect programs. Use {@link fromEventListenerWindow}
- * for viewport, network, focus, pointer, keyboard, and other `Window` events,
- * and use {@link fromEventListenerDocument} for document lifecycle,
- * visibility, selection, fullscreen, and other `Document` events.
- *
- * ## Mental model
- *
- * Each constructor registers a DOM `addEventListener` callback when the stream
- * is consumed and removes it when the stream is finalized. Browser events are
- * push-based `EventTarget` notifications, so the browser does not slow down the
- * event source when downstream stream processing is busy. Events are buffered
- * inside the stream until a consumer pulls them.
- *
- * ## Common tasks
- *
- * - Track browser state such as resize, online / offline, focus, visibility, or
- *   pointer activity with Effect stream operators.
- * - Scope DOM listeners to a fiber so they are removed when the consuming
- *   effect is interrupted or completes.
- * - Set `bufferSize` for bursty event sources before applying sampling,
- *   throttling, debouncing, or dropping logic downstream.
- *
- * ## Gotchas
- *
- * The default buffer is unbounded. High-frequency sources such as `scroll`,
- * `pointermove`, or `mousemove` should usually specify `bufferSize` and reduce
- * the event rate with stream operators.
- *
- * These helpers are for DOM events, not for `ReadableStream` request or
- * response bodies. Fetch bodies follow Web Streams rules such as
- * single-consumer locking and disturbed bodies after reads. When using the DOM
- * `once` option, also use `Stream.take(1)` if the consuming code needs a finite
- * stream.
+ * This module provides typed constructors that turn `window.addEventListener`
+ * and `document.addEventListener` events into Effect `Stream` values. Both
+ * helpers accept the usual listener options and an optional stream buffer size.
  *
  * @since 4.0.0
  */

package/src/BrowserWorker.ts

@@ -1,38 +1,10 @@
 /**
- * Parent-side browser platform for running Effect workers.
+ * Parent-side browser platform for Effect workers.
  *
- * This module provides the `WorkerPlatform` used by browser code that spawns or
- * connects 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.
- *
- * **Mental model**
- *
- * Browser worker communication is normalized to a message port. Dedicated
- * workers post messages on the worker object itself, shared workers post
- * through `worker.port`, and raw `MessagePort` values can be supplied directly.
- * `layerPlatform` provides only the browser platform, while `layer` combines
- * the platform with a `Spawner` that creates a worker endpoint for each worker
- * id.
- *
- * **Common tasks**
- *
- * Use `layer` when parent code should both provide browser worker messaging and
- * define how workers are spawned. Use `layerPlatform` when a spawner is already
- * provided elsewhere. Return a `MessagePort` from the spawner for tests or
- * custom channels, a `Worker` for dedicated workers, or a `SharedWorker` when
- * multiple browser contexts should share one worker runtime.
- *
- * **Gotchas**
- *
- * Messages use the browser structured-clone algorithm, so payloads and transfer
- * lists must be accepted by the target runtime. Transferring an `ArrayBuffer` or
- * `MessagePort` moves ownership away from the sender. Scope finalization sends
- * the worker close signal over the port, but code that created a dedicated
- * `Worker` remains responsible for broader lifecycle concerns such as
- * terminating it.
+ * `layerPlatform` provides the `WorkerPlatform` used to communicate with a
+ * browser `Worker`, `SharedWorker`, or `MessagePort` through Effect's worker
+ * protocol. `layer` combines that platform with a `Spawner` built from a
+ * callback that creates or returns the worker endpoint for each worker id.
  *
  * @since 4.0.0
  */

package/src/BrowserWorkerRunner.ts

@@ -1,33 +1,11 @@
 /**
  * Runner-side browser platform for Effect worker handlers.
  *
- * This module is for code already executing inside a browser worker, or for
- * tests and adapters that pass a `MessagePort` or `Window` endpoint directly.
- * It provides the `WorkerRunnerPlatform` used by `WorkerRunner` and protocols
- * such as `RpcServer.layerProtocolWorkerRunner` to receive parent or client
- * requests, run Effect handlers, and post responses back through the browser
- * messaging channel.
- *
- * **Mental model**
- *
- * Dedicated workers use the ambient `self` endpoint. Shared workers receive one
- * `MessagePort` per `onconnect` event, and this module caches ports that arrive
- * before the runner layer starts. `layer` reads from the global worker `self`;
- * `make` and `layerMessagePort` are for explicit endpoints supplied by tests,
- * custom channels, or adapter code.
- *
- * **Common tasks**
- *
- * Pair this module with `BrowserWorker` in the parent page when moving RPC
- * handlers, CPU-bound computations, or browser-only services into a dedicated
- * worker or shared worker. Use `layer` in normal worker entry points and
- * `layerMessagePort` when a test or integration already owns the transport.
- *
- * **Gotchas**
- *
- * Payloads and transfer lists must satisfy the browser structured-clone
- * algorithm. `messageerror` and `error` events fail the runner, and each
- * connected `MessagePort` is closed when its scope finalizes.
+ * `make` builds a `WorkerRunnerPlatform` over a `MessagePort` or `Window`.
+ * `layer` provides the platform from the global worker `self`, and
+ * `layerMessagePort` provides it from an explicit endpoint. The platform
+ * receives parent or client messages, runs Effect handlers, and posts responses
+ * back through the browser messaging channel.
  *
  * @since 4.0.0
  */

package/src/Clipboard.ts

@@ -1,35 +1,11 @@
 /**
  * Browser clipboard integration for Effect programs.
  *
- * This module provides a `Clipboard` service backed by `navigator.clipboard`.
- * It keeps copy, paste, clear, and rich clipboard operations inside the Effect
- * environment so browser UI code can require clipboard capability without
- * calling the global API directly. Text helpers cover portable copy and paste
- * flows, while `read`, `write`, and `writeBlob` expose `ClipboardItem` payloads
- * for browsers that support richer MIME types.
- *
- * **Mental model**
- *
- * `Clipboard` is a capability service. Application code depends on the service
- * tag, {@link layer} supplies the live browser implementation, and {@link make}
- * builds custom implementations for tests, unsupported browsers, or constrained
- * capabilities. Browser failures are converted to {@link ClipboardError}.
- *
- * **Common tasks**
- *
- * - Provide {@link layer} near the browser application edge.
- * - Use `writeString` for copy buttons and generated text.
- * - Use `readString` for paste or import workflows.
- * - Use `write` or `writeBlob` for rich clipboard payloads when
- *   `ClipboardItem` is available.
- * - Use `clear` to replace the clipboard with an empty string.
- *
- * **Gotchas**
- *
- * Clipboard access requires a secure context in modern browsers and may also
- * require user activation, permissions, and a focused document. Support differs
- * between reads, writes, text, and custom MIME payloads, so feature detection or
- * graceful fallback is often needed around `ClipboardItem` usage.
+ * This module defines the `Clipboard` service, the `ClipboardError` raised by
+ * failed browser operations, a `make` constructor for custom implementations,
+ * and a browser-backed `layer` that uses `navigator.clipboard`. The service
+ * supports reading and writing text, reading and writing `ClipboardItem`
+ * payloads, writing one `Blob`, and clearing the clipboard.
  *
  * @since 4.0.0
  */

package/src/Geolocation.ts

@@ -1,35 +1,12 @@
 /**
  * Browser geolocation integration for Effect programs.
  *
- * This module exposes a `Geolocation` service backed by
- * `navigator.geolocation`. Use it for browser features that need a single
- * position fix, such as nearby search or delivery estimates, or a stream of
- * position updates for navigation, tracking, and location-aware interfaces.
- * Browser failures are represented as typed `GeolocationError` values instead
- * of raw callback errors.
- *
- * **Mental model**
- *
- * - The service delegates to the browser Geolocation API and follows the
- *   browser's permission, privacy, origin, and secure-context rules.
- * - `getCurrentPosition` reads one position fix from the service.
- * - {@link watchPosition} turns browser position callbacks into a `Stream` and
- *   clears the underlying browser watch when the stream is finalized.
- *
- * **Common tasks**
- *
- * - Provide the live browser implementation with {@link layer}.
- * - Read a one-shot position from the `Geolocation` service.
- * - Stream position updates with {@link watchPosition}.
- * - Handle denied permissions, timeouts, and unavailable position data with
- *   {@link GeolocationError}.
- *
- * **Gotchas**
- *
- * - Browsers may prompt the user, reject access outside secure contexts, block
- *   access by permissions policy, or report that position data is unavailable.
- * - {@link watchPosition} uses a sliding buffer; increase `bufferSize` if slow
- *   consumers must not skip older positions.
+ * This module defines a `Geolocation` service backed by
+ * `navigator.geolocation`. The service can read one current position or stream
+ * watched position updates with a sliding buffer. Browser callback failures are
+ * represented as `GeolocationError` values with `PositionUnavailable`,
+ * `PermissionDenied`, or `Timeout` reasons. The module also provides the
+ * browser-backed layer and a `watchPosition` accessor.
  *
  * @since 4.0.0
  */

package/src/IndexedDb.ts

@@ -7,20 +7,6 @@
  * wiring those primitives from `window`, and schemas for the key shapes accepted
  * by IndexedDB object stores and indexes.
  *
- * Use it when building typed local persistence for browser caches,
- * offline-first state, background queues, drafts, or other client-side data
- * that should be validated before it reaches IndexedDB. Higher-level database,
- * version, table, and query modules build on these primitives for migrations
- * and typed transactions.
- *
- * IndexedDB still follows the browser rules: schema changes happen only during
- * version upgrades, upgrades may be blocked by other open tabs or connections,
- * and reads or writes must run in transactions scoped to the object stores they
- * touch. The `layerWindow` constructor should be used only where browser
- * globals are available, and code that also runs during SSR or in restricted
- * browser contexts should account for `indexedDB` or `IDBKeyRange` being
- * missing.
- *
  * @since 4.0.0
  */
 import * as Context from "effect/Context"

package/src/IndexedDbDatabase.ts

@@ -4,25 +4,9 @@
  * This module turns an `IndexedDbVersion` migration chain into an
  * `IndexedDbDatabase` layer. The layer opens the browser database, runs any
  * pending upgrade migrations, provides a query builder for the current schema,
- * and exposes a `rebuild` effect that deletes and reopens the database. It is
- * the database-level companion to the table, version, and query builder
- * modules.
- *
- * Use it for browser-local persistence such as offline-first application
- * state, cached server data, background queues, drafts, and other client-side
- * stores that need typed reads and writes backed by IndexedDB transactions.
- *
- * IndexedDB schema changes can only happen inside upgrade transactions, so
- * every call to `make` or `.add` represents the next browser database version
- * and only migrations after the existing browser version are run. Table and
- * index definitions type the migration and query APIs, but object stores and
- * indexes still need to be created or removed explicitly with the migration
- * transaction helpers. Include the complete target table set in each version,
- * create indexes before querying them, and treat key path or auto-increment
- * changes as store migrations that copy data into a replacement object store.
- * Upgrades can be blocked by other open connections, and all migration reads,
- * writes, store changes, and index changes share the single upgrade
- * transaction supplied by the browser.
+ * and exposes a `rebuild` effect that deletes and reopens the database.
+ * Migration transactions can create or delete object stores and indexes, and
+ * database failures are represented as `IndexedDbDatabaseError` values.
  *
  * @since 4.0.0
  */

package/src/IndexedDbQueryBuilder.ts

@@ -3,27 +3,11 @@
  *
  * An `IndexedDbQueryBuilder` is created from an open database and a version's
  * table descriptors, then exposes `from(tableName)` as the entry point for
- * table operations. The resulting query objects can select, count, delete,
- * insert, upsert, clear tables, stream paged reads, react to invalidations, and
- * run multiple effects in a shared `IDBTransaction` with `withTransaction`.
- *
- * Use this module for local browser persistence such as caches, offline-first
- * state, background queues, drafts, and other client-side data where writes
- * should be encoded through `Schema` and reads should be decoded before they
- * reach application code.
- *
- * Index and range helpers are thinly typed wrappers around IndexedDB object
- * stores, indexes, `IDBKeyRange`, and cursors. Index names must be declared on
- * the table and created during migrations; without an index, queries use the
- * object store key path. Range values are encoded IndexedDB key values, and
- * compound key paths must follow the declared key order. Filters, offsets,
- * reverse reads, out-of-line keys, and limited deletes require cursor-based
- * scans, while simpler selects can use `getAll`.
- *
- * Table schema details affect runtime behavior: auto-increment writes may omit
- * the generated numeric key, stores without a key path require an out-of-line
- * `key` for writes and add that `key` back to selected rows, and schema
- * mismatches surface as `EncodeError` or `DecodeError` query failures.
+ * table operations. Query objects can select, count, delete, insert, upsert,
+ * clear tables, stream paged reads, react to invalidations, and run multiple
+ * effects in a shared `IDBTransaction` with `withTransaction`. Reads decode
+ * stored rows with the table schema, and writes encode input values before
+ * sending them to IndexedDB.
  *
  * @since 4.0.0
  */

package/src/IndexedDbTable.ts

@@ -4,33 +4,8 @@
  * An {@link IndexedDbTable} is the schema-backed description of one IndexedDB
  * object store. It carries the store name, row schema, key path, index key
  * paths, auto-increment mode, and transaction durability used by database
- * versions, migrations, and typed queries.
- *
- * **Mental model**
- *
- * A table value is metadata. `make` does not create an object store; it gives
- * database versions, migration helpers, and the query builder the information
- * they need to type table names, validate rows, and choose schemas for reads
- * and writes. The stored values are the encoded schema values accepted by
- * IndexedDB, with derived schemas for out-of-line keys and generated
- * auto-increment keys.
- *
- * **Common tasks**
- *
- * - Define object stores for browser caches, offline state, drafts, and
- *   background queues.
- * - Reuse the same table descriptor in database versions, migrations, and
- *   typed queries.
- * - Declare index key paths so query builders can restrict index names and key
- *   values.
- *
- * **Gotchas**
- *
- * Key paths and index paths point at encoded schema fields whose values must be
- * valid IndexedDB keys. Tables without an inline key path use an out-of-line
- * `key`, so the row schema cannot define a `key` field. Auto-increment tables
- * require a numeric key path, and declared indexes still have to be created in
- * migrations.
+ * versions, migrations, and typed queries. The `make` constructor also derives
+ * the read, array, and auto-increment write schemas used by the query builder.
  *
  * @see {@link make} for constructing table descriptors.
  *

package/src/Permissions.ts

@@ -1,35 +1,11 @@
 /**
  * Effect service for the browser Permissions API.
  *
- * This module wraps `navigator.permissions` in a `Permissions` service and a
- * browser-backed layer. It lets browser programs query whether a capability is
- * currently `granted`, `prompt`, or `denied` before deciding which UI or
- * feature flow to show for geolocation, notifications, clipboard access,
- * camera, microphone, persistent storage, and other browser-gated features.
- *
- * **Mental model**
- *
- * A permission query is a status read, not an access request. The service
- * delegates to `navigator.permissions.query({ name })` and returns the browser's
- * `PermissionStatus`, while browser rejections are represented as
- * `PermissionsError` values.
- *
- * **Common tasks**
- *
- * - Check whether a feature is already available before rendering a prompt or
- *   settings path.
- * - Require permission querying through Effect context instead of reaching for
- *   the ambient `navigator` in application code.
- * - Provide the live browser implementation with `layer`.
- *
- * **Gotchas**
- *
- * Browser support for permission names and states is uneven, and unsupported or
- * invalid descriptors may reject. Some permissions are only meaningful in
- * secure contexts or after user activation. Returned `PermissionStatus` objects
- * can change when the user updates browser settings or responds to prompts; if
- * you subscribe to `change` or `onchange`, clean up listeners with the
- * surrounding Effect scope.
+ * This module defines a `Permissions` service backed by
+ * `navigator.permissions`. The service exposes `query`, which returns the
+ * browser `PermissionStatus` for a permission name. Failed browser operations
+ * are represented as `PermissionsError` values with `InvalidStateError` or
+ * `TypeError` reasons, and `layer` provides the browser-backed service.
  *
  * @since 4.0.0
  */