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

package/src/BrowserHttpClient.ts

@@ -1,13 +1,45 @@
 /**
- * @since 1.0.0
+ * Browser implementations of the Effect `HttpClient`.
+ *
+ * This module exposes HTTP client layers for code that runs in a browser. It
+ * re-exports the fetch-based client for the common case, where requests should
+ * use the platform `fetch` implementation and optional `RequestInit` defaults,
+ * and it provides an `XMLHttpRequest`-backed layer for integrations that need
+ * XHR semantics such as response type control or environments where XHR is the
+ * required transport.
+ *
+ * Use these layers for single-page applications, browser tests, generated
+ * `HttpApiClient`s, and other client-side Effect programs that need HTTP
+ * requests to participate in interruption, typed transport / decode errors, and
+ * Effect's response body readers.
+ *
+ * Browser networking rules still apply. Cross-origin requests are subject to
+ * CORS preflights and server allowlists, especially when using custom headers,
+ * non-simple methods, or non-simple content types. Only CORS-exposed response
+ * headers are readable, and cookies / authentication are controlled by the
+ * browser and the configured fetch `RequestInit.credentials` policy. The XHR
+ * layer uses the browser's `XMLHttpRequest` defaults for credentials.
+ *
+ * Body handling differs between the transports. Fetch delegates body framing to
+ * the Web Fetch implementation. The XHR client sends empty, raw, `Uint8Array`,
+ * and `FormData` bodies directly, buffers `Stream` request bodies before
+ * sending, defaults responses to text, and can be switched to `ArrayBuffer`
+ * responses with `withXHRArrayBuffer`. When sending `FormData`, avoid setting
+ * an incompatible `Content-Type` header so the browser can generate the
+ * multipart boundary.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import type { LazyArg } from "effect/Function"
 import * as Inspectable from "effect/Inspectable"
 import type * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import { type Pipeable, pipeArguments } from "effect/Pipeable"
 import * as Queue from "effect/Queue"
-import * as ServiceMap from "effect/ServiceMap"
+import type * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
 import * as Cookies from "effect/unstable/http/Cookies"
 import * as Headers from "effect/unstable/http/Headers"
@@ -25,18 +57,24 @@ import * as HeaderParser from "multipasta/HeadersParser"
 
 export {
   /**
-   * @since 1.0.0
+   * Context reference for the `fetch` implementation used by the fetch-based HTTP client.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   Fetch,
   /**
-   * @since 1.0.0
+   * Layer that provides an `HttpClient` implementation backed by the configured `Fetch` function.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   layer as layerFetch,
   /**
-   * @since 1.0.0
+   * Service containing default `RequestInit` options for the fetch-based HTTP client.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   RequestInit
 } from "effect/unstable/http/FetchHttpClient"
@@ -46,23 +84,37 @@ export {
 // =============================================================================
 
 /**
- * @since 1.0.0
- * @category Models
+ * Allowed response body modes for the browser XHR HTTP client.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type XHRResponseType = "arraybuffer" | "text"
 
 /**
- * @since 1.0.0
- * @category References
+ * Reference that controls the `XMLHttpRequest.responseType` used by the browser XHR HTTP client, defaulting to `"text"`.
+ *
+ * **When to use**
+ *
+ * Use when XHR-backed HTTP requests need to receive response bodies as text or
+ * as raw `ArrayBuffer` values.
+ *
+ * @see {@link XHRResponseType} for the allowed response body modes
+ * @see {@link withXHRArrayBuffer} for scoping XHR response handling to `ArrayBuffer`
+ *
+ * @category references
+ * @since 4.0.0
  */
-export const CurrentXHRResponseType: ServiceMap.Reference<XHRResponseType> = ServiceMap.Reference(
+export const CurrentXHRResponseType: Context.Reference<XHRResponseType> = Context.Reference(
   "@effect/platform-browser/BrowserHttpClient/CurrentXHRResponseType",
   { defaultValue: (): XHRResponseType => "text" }
 )
 
 /**
- * @since 1.0.0
- * @category References
+ * Runs an effect with `CurrentXHRResponseType` set to `"arraybuffer"` so the XHR HTTP client receives response bodies as `ArrayBuffer` values.
+ *
+ * @category references
+ * @since 4.0.0
  */
 export const withXHRArrayBuffer = <A, E, R>(
   self: Effect.Effect<A, E, R>
@@ -74,10 +126,12 @@ export const withXHRArrayBuffer = <A, E, R>(
   )
 
 /**
- * @since 1.0.0
- * @category Services
+ * Service tag for the `XMLHttpRequest` constructor used by the browser XHR HTTP client.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class XMLHttpRequest extends ServiceMap.Service<
+export class XMLHttpRequest extends Context.Service<
   XMLHttpRequest,
   LazyArg<globalThis.XMLHttpRequest>
 >()("@effect/platform-browser/BrowserHttpClient/XMLHttpRequest") {}
@@ -87,8 +141,8 @@ const makeXhrRequest = () => new globalThis.XMLHttpRequest()
 const makeXmlHttpRequest = HttpClient.make(
   (request, url, signal, fiber) =>
     Effect.suspend(() => {
-      const xhr = ServiceMap.getOrElse(
-        fiber.services,
+      const xhr = Context.getOrElse(
+        fiber.context,
         XMLHttpRequest,
         () => makeXhrRequest
       )()
@@ -213,7 +267,7 @@ abstract class IncomingMessageImpl<E> extends Inspectable.Class implements HttpI
   }
 
   get remoteAddress() {
-    return undefined
+    return Option.none()
   }
 
   _textEffect: Effect.Effect<string, E> | undefined
@@ -247,10 +301,10 @@ abstract class IncomingMessageImpl<E> extends Inspectable.Class implements HttpI
     )
   }
 
-  get json(): Effect.Effect<unknown, E> {
+  get json(): Effect.Effect<Schema.Json, E> {
     return Effect.flatMap(this.text, (text) =>
       Effect.try({
-        try: () => text === "" ? null : JSON.parse(text) as unknown,
+        try: () => text === "" ? null : JSON.parse(text),
         catch: this.onError
       }))
   }
@@ -334,7 +388,7 @@ abstract class IncomingMessageImpl<E> extends Inspectable.Class implements HttpI
 }
 
 class ClientResponseImpl extends IncomingMessageImpl<HttpClientError.HttpClientError>
-  implements HttpClientResponse.HttpClientResponse
+  implements HttpClientResponse.HttpClientResponse, Pipeable
 {
   readonly [HttpClientResponse.TypeId]: typeof HttpClientResponse.TypeId
   readonly request: HttpClientRequest.HttpClientRequest
@@ -374,12 +428,18 @@ class ClientResponseImpl extends IncomingMessageImpl<HttpClientError.HttpClientE
       status: this.status
     })
   }
+
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides an `HttpClient` implementation backed by the browser `XMLHttpRequest` API.
+ *
+ * @category layers
+ * @since 4.0.0
  */
-export const layerXMLHttpRequest: Layer.Layer<HttpClient.HttpClient> = HttpClient.layerMergedServices(
+export const layerXMLHttpRequest: Layer.Layer<HttpClient.HttpClient> = HttpClient.layerMergedContext(
   Effect.succeed(makeXmlHttpRequest)
 )

package/src/BrowserKeyValueStore.ts

@@ -1,29 +1,218 @@
 /**
- * @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.
+ *
+ * ## 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)
+ * )
+ * ```
+ *
+ * @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.
+ * Creates a `KeyValueStore` layer that uses the browser's `localStorage` API and stores values between browser sessions.
  *
- * 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
 )
 
 /**
- * Creates a `KeyValueStore` layer that uses the browser's `sessionStorage` api.
- *
- * Values are stored only for the current session.
+ * Creates a `KeyValueStore` layer that uses the browser's `sessionStorage` API and stores values 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 a browser `KeyValueStore` needs persistent asynchronous IndexedDB
+ * storage 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)
+}