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

package/src/BrowserPersistence.ts

@@ -0,0 +1,376 @@
+/**
+ * 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"
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ */
+import type * as Arr from "effect/Array"
+import * as Clock from "effect/Clock"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Persistence from "effect/unstable/persistence/Persistence"
+
+/**
+ * Creates a `BackingPersistence` layer backed by IndexedDB, optionally using the provided database name.
+ *
+ * **When to use**
+ *
+ * Use when composing persistence manually and the lower-level
+ * `BackingPersistence` service should be backed by browser IndexedDB.
+ *
+ * **Details**
+ *
+ * The database name defaults to `"effect_persistence"`. Entries are stored by
+ * persistence store id and key in a shared object store, and TTL expiration is
+ * checked when values are read.
+ *
+ * **Gotchas**
+ *
+ * Opening the database is defected during layer acquisition if IndexedDB is
+ * unavailable or cannot be opened. Store operations report `PersistenceError`
+ * for IndexedDB request, transaction, quota, and structured-clone failures.
+ *
+ * @see {@link layerIndexedDb} for providing the higher-level `Persistence` service
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerBackingIndexedDb = (options?: {
+  readonly database?: string | undefined
+}): Layer.Layer<Persistence.BackingPersistence> =>
+  Layer.effect(Persistence.BackingPersistence)(Effect.gen(function*() {
+    const db = yield* Effect.acquireRelease(
+      openDatabase(options?.database ?? defaultDatabase),
+      (db) => Effect.sync(() => db.close())
+    ).pipe(Effect.orDie)
+
+    return Persistence.BackingPersistence.of({
+      make: Effect.fnUntraced(function*(storeId) {
+        const clock = yield* Clock.Clock
+        return {
+          get: (key) => get(db, clock, storeId, key),
+          getMany: (keys) => getMany(db, clock, storeId, keys),
+          set: (key, value, ttl) => set(db, clock, storeId, key, value, ttl),
+          setMany: (entries) => setMany(db, clock, storeId, entries),
+          remove: (key) => remove(db, storeId, key),
+          clear: clear(db, storeId)
+        }
+      })
+    })
+  }))
+
+const defaultDatabase = "effect_persistence"
+const databaseVersion = 1
+const entriesStoreName = "entries"
+const storeIdIndexName = "storeId"
+
+/**
+ * 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
+}): Layer.Layer<Persistence.Persistence> =>
+  Persistence.layer.pipe(
+    Layer.provide(layerBackingIndexedDb(options))
+  )
+
+const openDatabase = (database: string): Effect.Effect<IDBDatabase, Persistence.PersistenceError> =>
+  Effect.gen(function*() {
+    const openRequest = yield* Effect.try({
+      try: () => globalThis.indexedDB.open(database, databaseVersion),
+      catch: (cause) =>
+        new Persistence.PersistenceError({
+          message: "Failed to open backing store database",
+          cause
+        })
+    })
+
+    openRequest.onupgradeneeded = () => {
+      const db = openRequest.result
+      const entries = db.objectStoreNames.contains(entriesStoreName)
+        ? openRequest.transaction?.objectStore(entriesStoreName)
+        : db.createObjectStore(entriesStoreName, { keyPath: ["storeId", "id"] })
+      if (entries && !entries.indexNames.contains(storeIdIndexName)) {
+        entries.createIndex(storeIdIndexName, storeIdIndexName, { unique: false })
+      }
+    }
+
+    return yield* idbRequest("Failed to open backing store database", () => openRequest)
+  })
+
+interface EntryRow {
+  readonly storeId: string
+  readonly id: string
+  readonly value: object
+  readonly expires: number | null
+}
+
+const isExpired = (row: EntryRow, now: number): boolean => row.expires !== null && row.expires <= now
+
+const get = (
+  db: IDBDatabase,
+  clock: Clock.Clock,
+  storeId: string,
+  key: string
+): Effect.Effect<object | undefined, Persistence.PersistenceError> =>
+  withEntriesTransaction<object | undefined>(
+    db,
+    "readwrite",
+    `Failed to get key ${key} from backing store`,
+    (
+      entries,
+      setResult,
+      fail
+    ) => {
+      const now = clock.currentTimeMillisUnsafe()
+      const id: [string, string] = [storeId, key]
+      const request = entries.get(id)
+      request.onerror = () => fail(request.error)
+      request.onsuccess = () => {
+        const row = request.result as EntryRow | undefined
+        if (!row || !isExpired(row, now)) {
+          setResult(row?.value)
+          return
+        }
+
+        const deleteRequest = entries.delete(id)
+        deleteRequest.onerror = () => fail(deleteRequest.error)
+        deleteRequest.onsuccess = () => setResult(undefined)
+      }
+    }
+  )
+
+const getMany = (
+  db: IDBDatabase,
+  clock: Clock.Clock,
+  storeId: string,
+  keys: Arr.NonEmptyArray<string>
+): Effect.Effect<Arr.NonEmptyArray<object | undefined>, Persistence.PersistenceError> =>
+  withEntriesTransaction(
+    db,
+    "readwrite",
+    "Failed to getMany from backing store",
+    (entries, setResult, fail) => {
+      const now = clock.currentTimeMillisUnsafe()
+      const results = new Array<object | undefined>(keys.length)
+      setResult(results as any)
+
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i]
+        const keyPath = [storeId, key]
+        const request = entries.get(keyPath)
+        request.onerror = () => fail(request.error)
+        request.onsuccess = () => {
+          const row = request.result as EntryRow | undefined
+          if (!row) return
+          else if (!isExpired(row, now)) {
+            results[i] = row.value
+            return
+          }
+          const deleteRequest = entries.delete(keyPath)
+          deleteRequest.onerror = () => fail(deleteRequest.error)
+        }
+      }
+    }
+  )
+
+const set = (
+  db: IDBDatabase,
+  clock: Clock.Clock,
+  storeId: string,
+  key: string,
+  value: object,
+  ttl: Duration.Duration | undefined
+): Effect.Effect<void, Persistence.PersistenceError> =>
+  withEntriesTransaction(
+    db,
+    "readwrite",
+    `Failed to set key ${key} in backing store`,
+    (entries, setResult, fail) => {
+      const request = entries.put(
+        {
+          storeId,
+          id: key,
+          value,
+          expires: Persistence.unsafeTtlToExpires(clock, ttl)
+        } satisfies EntryRow
+      )
+      request.onerror = () => fail(request.error)
+      request.onsuccess = () => setResult(undefined)
+    }
+  )
+
+const setMany = (
+  db: IDBDatabase,
+  clock: Clock.Clock,
+  storeId: string,
+  entries: Arr.NonEmptyArray<readonly [key: string, value: object, ttl: Duration.Duration | undefined]>
+): Effect.Effect<void, Persistence.PersistenceError> =>
+  withEntriesTransaction(
+    db,
+    "readwrite",
+    "Failed to setMany in backing store",
+    (store, setResult, fail) => {
+      for (const [key, value, ttl] of entries) {
+        const request = store.put(
+          {
+            storeId,
+            id: key,
+            value,
+            expires: Persistence.unsafeTtlToExpires(clock, ttl)
+          } satisfies EntryRow
+        )
+        request.onerror = () => fail(request.error)
+        request.onsuccess = () => setResult(undefined)
+      }
+    }
+  )
+
+const remove = (
+  db: IDBDatabase,
+  storeId: string,
+  key: string
+): Effect.Effect<void, Persistence.PersistenceError> =>
+  withEntriesTransaction(
+    db,
+    "readwrite",
+    `Failed to remove key ${key} from backing store`,
+    (entries, setResult, fail) => {
+      const request = entries.delete([storeId, key])
+      request.onerror = () => fail(request.error)
+      request.onsuccess = () => setResult(undefined)
+    }
+  )
+
+const clear = (db: IDBDatabase, storeId: string): Effect.Effect<void, Persistence.PersistenceError> =>
+  withEntriesTransaction(db, "readwrite", "Failed to clear backing store", (entries, setResult, fail) => {
+    const index = entries.index(storeIdIndexName)
+    const cursorRequest = index.openCursor(storeId)
+    cursorRequest.onerror = () => fail(cursorRequest.error)
+    cursorRequest.onsuccess = () => {
+      const cursor = cursorRequest.result
+      if (!cursor) {
+        setResult(undefined)
+        return
+      }
+      const deleteRequest = cursor.delete()
+      deleteRequest.onerror = () => fail(deleteRequest.error)
+      deleteRequest.onsuccess = () => cursor.continue()
+    }
+  })
+
+const withEntriesTransaction = <A>(
+  db: IDBDatabase,
+  mode: IDBTransactionMode,
+  message: string,
+  run: (
+    entries: IDBObjectStore,
+    onResult: (result: A) => void,
+    fail: (cause: unknown) => void
+  ) => void
+): Effect.Effect<A, Persistence.PersistenceError> =>
+  Effect.callback<A, Persistence.PersistenceError>((resume) => {
+    const tx = db.transaction(entriesStoreName, mode)
+    const entries = tx.objectStore(entriesStoreName)
+
+    let result: A | undefined
+    let setResult = false
+    let done = false
+
+    const fail = (cause: unknown) => {
+      done = true
+      resume(Effect.fail(new Persistence.PersistenceError({ message, cause })))
+    }
+
+    tx.oncomplete = () => {
+      done = true
+      if (setResult) resume(Effect.succeed(result!))
+    }
+    tx.onerror = () => {
+      done = true
+      fail(tx.error)
+    }
+    tx.onabort = () => {
+      done = true
+      fail(tx.error)
+    }
+
+    run(entries, (next) => {
+      if (done) return resume(Effect.succeed(next))
+      setResult = true
+      result = next
+    }, fail)
+
+    return Effect.sync(() => {
+      tx.abort()
+    })
+  })
+
+const idbRequest = <A>(
+  message: string,
+  evaluate: () => IDBRequest<A>
+): Effect.Effect<A, Persistence.PersistenceError> =>
+  Effect.callback<A, Persistence.PersistenceError>((resume) => {
+    const request = evaluate()
+    const fail = (cause: unknown) => {
+      resume(Effect.fail(new Persistence.PersistenceError({ message, cause })))
+    }
+    if (request.readyState === "done") {
+      resume(Effect.succeed(request.result))
+    }
+    request.onsuccess = () => {
+      resume(Effect.succeed(request.result))
+    }
+    request.onerror = () => fail(request.error)
+  })

package/src/BrowserRuntime.ts

@@ -1,17 +1,74 @@
 /**
- * @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.
+ *
+ * **When to use**
+ *
+ * Use to launch a browser page, single-page application, demo, or browser test
+ * harness as a root Effect program.
+ *
+ * **Details**
+ *
+ * Supports both direct and curried call forms. Options are forwarded to
+ * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+ * behavior.
+ *
+ * **Gotchas**
+ *
+ * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+ * asynchronous finalizers, network work, timers, or prompts from completing.
+ *
  * @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.
+   *
+   * **When to use**
+   *
+   * Use to launch a browser page, single-page application, demo, or browser test
+   * harness as a root Effect program.
+   *
+   * **Details**
+   *
+   * Supports both direct and curried call forms. Options are forwarded to
+   * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+   * behavior.
+   *
+   * **Gotchas**
+   *
+   * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+   * asynchronous finalizers, network work, timers, or prompts from completing.
+   *
    * @category Runtime
+   * @since 4.0.0
    */
   (
     options?: {
@@ -20,8 +77,26 @@ 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.
+   *
+   * **When to use**
+   *
+   * Use to launch a browser page, single-page application, demo, or browser test
+   * harness as a root Effect program.
+   *
+   * **Details**
+   *
+   * Supports both direct and curried call forms. Options are forwarded to
+   * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+   * behavior.
+   *
+   * **Gotchas**
+   *
+   * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+   * asynchronous finalizers, network work, timers, or prompts from completing.
+   *
    * @category Runtime
+   * @since 4.0.0
    */
   <E, A>(
     effect: Effect.Effect<A, E>,

package/src/BrowserSocket.ts

@@ -1,12 +1,70 @@
 /**
- * @since 1.0.0
+ * Provide Effect sockets backed by the browser `WebSocket` implementation.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * **When to use**
+ *
+ * Use when browser or client-side code needs a complete `Socket` layer
+ * connected to a WebSocket URL.
+ *
+ * **Details**
+ *
+ * Delegates socket construction to `Socket.makeWebSocket` and provides the
+ * browser-backed `WebSocketConstructor` service.
+ *
+ * **Gotchas**
+ *
+ * Browser WebSocket rules still control URL schemes, mixed-content blocking,
+ * cookies, authentication, origin checks, subprotocols, and extensions. Close
+ * events are errors unless `closeCodeIsError` classifies the close code as
+ * clean.
+ *
+ * @see {@link layerWebSocketConstructor} for providing only the browser constructor service
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket = (url: string, options?: {
   readonly closeCodeIsError?: (code: number) => boolean
@@ -16,10 +74,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,42 @@
 /**
- * @since 1.0.0
+ * Convert browser DOM events into Effect 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.
+ *
+ * @since 4.0.0
  */
 
 import * as Stream from "effect/Stream"
@@ -7,11 +44,14 @@ import * as Stream from "effect/Stream"
 /**
  * Creates a `Stream` from `window.addEventListener`.
  *
+ * **Details**
+ *
  * 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.
+ * buffer size by passing 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,
@@ -26,11 +66,14 @@ export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
 /**
  * Creates a `Stream` from `document.addEventListener`.
  *
+ * **Details**
+ *
  * 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.
+ * buffer size by passing 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,