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

package/src/BrowserKeyValueStore.ts

@@ -1,29 +1,177 @@
 /**
- * @since 1.0.0
+ * Browser-backed `KeyValueStore` layers for client-side Effect programs.
+ *
+ * This module provides browser implementations of the unstable persistence
+ * `KeyValueStore` service. Use {@link layerLocalStorage} for small
+ * 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. The IndexedDB layer requires the browser `IndexedDb` service and
+ * accepts an optional database name.
+ *
+ * @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.
+ * Creates a `KeyValueStore` layer that uses the browser's `localStorage` API and stores values between browser sessions.
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layerLocalStorage: Layer.Layer<KeyValueStore.KeyValueStore> = KeyValueStore.layerStorage(() =>
   globalThis.localStorage
 )
 
 /**
- * Creates a `KeyValueStore` layer that uses the browser's `sessionStorage` api.
+ * Creates a `KeyValueStore` layer that uses the browser's `sessionStorage` API and stores values only for the current session.
  *
- * 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.
+ *
+ * **When to use**
+ *
+ * Use when you need persistent asynchronous IndexedDB storage for a browser
+ * `KeyValueStore` instead of the synchronous Web Storage APIs.
+ *
+ * **Details**
+ *
+ * The database name defaults to `"effect_key_value_store"`. The layer requires
+ * the `IndexedDb` service and stores string and `Uint8Array` values in the same
+ * backing object store.
+ *
+ * **Gotchas**
+ *
+ * IndexedDB may be unavailable or blocked by browser settings, private browsing,
+ * quota limits, or restricted contexts. The string and `Uint8Array` accessors do
+ * not coerce values stored with the other representation.
+ *
+ * @see {@link layerLocalStorage} for synchronous persistent Web Storage
+ * @see {@link layerSessionStorage} for synchronous tab-session Web Storage
+ *
+ * @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

@@ -0,0 +1,334 @@
+/**
+ * IndexedDB-backed persistence layers for browser Effect programs.
+ *
+ * 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
+ */
+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,59 @@
 /**
- * @since 1.0.0
+ * Browser helper for running a root Effect program.
+ *
+ * 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
  */
 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 +62,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,39 @@
 /**
- * @since 1.0.0
+ * Browser WebSocket layers for Effect sockets.
+ *
+ * `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
  */
 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 you need browser code to satisfy the platform socket service from a
+ * URL without wiring the browser constructor service separately.
+ *
+ * **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 +43,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