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

package/src/BrowserWorker.ts

@@ -1,5 +1,40 @@
 /**
- * @since 1.0.0
+ * Parent-side browser platform for running 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.
+ *
+ * @since 4.0.0
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -9,8 +44,27 @@ 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.
+ *
+ * **When to use**
+ *
+ * Use when browser parent or client code needs both the browser
+ * `WorkerPlatform` and a `Spawner` from one layer.
+ *
+ * **Details**
+ *
+ * The `spawn` callback receives the numeric worker id and may return a
+ * `Worker`, `SharedWorker`, or `MessagePort`.
+ *
+ * **Gotchas**
+ *
+ * Scope finalization sends the worker close protocol over the port. Dedicated
+ * workers created by `spawn` are not terminated by this layer.
+ *
+ * @see {@link layerPlatform} for providing only the browser worker platform
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   spawn: (id: number) => Worker | SharedWorker | MessagePort
@@ -21,8 +75,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>()({
@@ -50,7 +106,7 @@ export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(W
               message: "An error event was emitter",
               cause: event.error ?? event.message
             })
-          }).asEffect()
+          })
         )
       }
       port.addEventListener("message", onMessage as any)

package/src/BrowserWorkerRunner.ts

@@ -1,5 +1,35 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -22,8 +52,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>() {
@@ -44,7 +76,7 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
       Effect.scopedWith(Effect.fnUntraced(function*(scope) {
         const closeLatch = Deferred.makeUnsafe<void, WorkerError>()
         const trackFiber = Fiber.runIn(scope)
-        const services = yield* Effect.services<R>()
+        const services = yield* Effect.context<R>()
         const runFork = Effect.runForkWith(services)
         const onExit = (exit: Exit.Exit<any, E>) => {
           if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) {
@@ -83,7 +115,7 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
                 message: "An messageerror event was emitted",
                 cause: error.data
               })
-            }).asEffect()
+            })
           )
         }
         function onError(error: any) {
@@ -94,7 +126,7 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
                 message: "An error event was emitted",
                 cause: error.data
               })
-            }).asEffect()
+            })
           )
         }
         function handlePort(port: MessagePort) {
@@ -151,16 +183,39 @@ 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.
+ *
+ * **When to use**
+ *
+ * Use when a browser worker entry point uses the ambient `self` object as the
+ * worker transport.
+ *
+ * **Details**
+ *
+ * Delegates to `make(self)` and provides the runner-side platform used by
+ * protocols such as `RpcServer.layerProtocolWorkerRunner`.
+ *
+ * **Gotchas**
+ *
+ * This layer depends on the browser worker global `self`. Use
+ * `layerMessagePort` when the transport is an explicit `MessagePort` or
+ * `Window`.
+ *
+ * @see {@link make} for constructing a runner platform from an explicit endpoint
+ * @see {@link layerMessagePort} for providing a platform from an explicit endpoint
+ *
+ * @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,17 +1,64 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
+import * as Context from "effect/Context"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
-import * as ServiceMap from "effect/ServiceMap"
 
 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.
+ *
+ * **Details**
+ *
+ * `read` and `write` work with `ClipboardItem` arrays. `readString` and
+ * `writeString` use text, `writeBlob` writes one `Blob`, and `clear` writes an
+ * empty string.
+ *
+ * **Gotchas**
+ *
+ * Clipboard access generally requires a secure context and may require user
+ * activation, permissions, or a focused document. `ClipboardItem` and non-text
+ * MIME type support varies by browser. Failed browser operations are surfaced
+ * as `ClipboardError`.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Clipboard {
   readonly [TypeId]: typeof TypeId
@@ -24,8 +71,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 +84,26 @@ export class ClipboardError extends Data.TaggedError("ClipboardError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the browser `Clipboard` service.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to require or provide clipboard capabilities through
+ * the context.
+ *
+ * @see {@link make} for building a custom clipboard service
+ * @see {@link layer} for providing the browser-backed clipboard service
+ *
+ * @category services
+ * @since 4.0.0
  */
-export const Clipboard: ServiceMap.Service<Clipboard, Clipboard> = ServiceMap.Service<Clipboard>(TypeId)
+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 +118,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,

package/src/Geolocation.ts

@@ -1,20 +1,74 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Queue from "effect/Queue"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 
 const TypeId = "~@effect/platform-browser/Geolocation"
 const ErrorTypeId = "~@effect/platform-browser/Geolocation/GeolocationError"
 
 /**
- * @since 1.0.0
- * @category Models
+ * Service interface for browser geolocation, providing effects for the current position and streams of watched positions.
+ *
+ * **When to use**
+ *
+ * Use when browser code needs a typed Effect service for one-shot location
+ * reads or streamed location updates.
+ *
+ * **Details**
+ *
+ * `getCurrentPosition` returns one position effect. `watchPosition` returns a
+ * stream and accepts the browser `PositionOptions` plus an optional sliding
+ * `bufferSize`.
+ *
+ * **Gotchas**
+ *
+ * Browser permission prompts, denied permissions, timeouts, unavailable
+ * position data, secure-context restrictions, and policy restrictions are
+ * surfaced as `GeolocationError`.
+ *
+ * @see {@link GeolocationError} for represented browser geolocation failures
+ * @see {@link layer} for the browser-backed service implementation
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Geolocation {
   readonly [TypeId]: typeof TypeId
@@ -31,14 +85,25 @@ export interface Geolocation {
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the browser `Geolocation` service.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to access or provide geolocation capabilities
+ * through the context.
+ *
+ * @see {@link layer} for providing the browser-backed geolocation service
+ *
+ * @category services
+ * @since 4.0.0
  */
-export const Geolocation: ServiceMap.Service<Geolocation, Geolocation> = ServiceMap.Service<Geolocation>(TypeId)
+export const Geolocation: Context.Service<Geolocation, Geolocation> = Context.Service<Geolocation>(TypeId)
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Tagged error wrapping a browser geolocation failure reason.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export class GeolocationError extends Data.TaggedError("GeolocationError")<{
   readonly reason: GeolocationErrorReason
@@ -60,8 +125,10 @@ export class GeolocationError extends Data.TaggedError("GeolocationError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Error reason for the browser geolocation `POSITION_UNAVAILABLE` failure.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export class PositionUnavailable extends Data.TaggedError("PositionUnavailable")<{
   readonly cause: unknown
@@ -72,8 +139,10 @@ export class PositionUnavailable extends Data.TaggedError("PositionUnavailable")
 }
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Error reason for the browser geolocation `PERMISSION_DENIED` failure.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
   readonly cause: unknown
@@ -84,8 +153,10 @@ export class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
 }
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Error reason for the browser geolocation `TIMEOUT` failure.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export class Timeout extends Data.TaggedError("Timeout")<{
   readonly cause: unknown
@@ -96,8 +167,10 @@ export class Timeout extends Data.TaggedError("Timeout")<{
 }
 
 /**
- * @since 1.0.0
- * @category Errors
+ * Union of browser geolocation error reasons represented by the service.
+ *
+ * @category errors
+ * @since 4.0.0
  */
 export type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout
 
@@ -141,8 +214,10 @@ const makeQueue = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides `Geolocation` using `navigator.geolocation`, with watched positions buffered in a sliding queue.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Geolocation> = Layer.succeed(
   Geolocation,
@@ -162,8 +237,10 @@ export const layer: Layer.Layer<Geolocation> = Layer.succeed(
 )
 
 /**
- * @since 1.0.0
+ * Streams positions from the `Geolocation` service using `watchPosition`, with an optional sliding buffer size.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const watchPosition = (
   options?:

package/src/IndexedDb.ts

@@ -0,0 +1,127 @@
+/**
+ * Browser IndexedDB primitives and key schemas for Effect applications.
+ *
+ * This module is the low-level bridge used by the platform-browser IndexedDB
+ * integration. It provides an `IndexedDb` service around the browser
+ * `indexedDB` factory and `IDBKeyRange` constructor, a `layerWindow` layer for
+ * 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"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+const TypeId = "~@effect/platform-browser/IndexedDb"
+
+/**
+ * Service interface that provides the browser `indexedDB` factory and `IDBKeyRange` constructor.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface IndexedDb {
+  readonly [TypeId]: typeof TypeId
+  readonly indexedDB: globalThis.IDBFactory
+  readonly IDBKeyRange: typeof globalThis.IDBKeyRange
+}
+
+/**
+ * Service tag for browser IndexedDB primitives.
+ *
+ * @category tag
+ * @since 4.0.0
+ */
+export const IndexedDb: Context.Service<IndexedDb, IndexedDb> = Context.Service<IndexedDb, IndexedDb>(TypeId)
+
+/** @internal */
+const IDBFlatKey = Schema.Union([
+  Schema.String,
+  Schema.Number.check(Schema.makeFilter((input) => !Number.isNaN(input))),
+  Schema.DateValid,
+  Schema.declare(
+    (input): input is BufferSource =>
+      input instanceof ArrayBuffer ||
+      (ArrayBuffer.isView(input) && input.buffer instanceof ArrayBuffer)
+  )
+])
+
+/**
+ * Schema for IndexedDB keys: strings, non-NaN numbers, valid dates, buffer sources, or arrays of those flat key values.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const IDBValidKey = Schema.Union([IDBFlatKey, Schema.Array(IDBFlatKey)])
+
+/**
+ * Schema for auto-incremented IndexedDB keys, accepting integers from 1 through `2 ** 53`.
+ *
+ * **When to use**
+ *
+ * Use when defining numeric key-path fields for `IndexedDbTable` definitions
+ * that use IndexedDB auto-increment keys.
+ *
+ * **Details**
+ *
+ * The schema accepts integer values from `1` through `2 ** 53`, matching the
+ * range used for generated IndexedDB auto-increment keys.
+ *
+ * @see {@link IDBValidKey} for the broader IndexedDB key schema
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const AutoIncrement = Schema.Int.check(
+  Schema.isBetween({ minimum: 1, maximum: 2 ** 53 })
+).annotate({
+  identifier: "AutoIncrement",
+  title: "autoIncrement",
+  description: "Defines a valid autoIncrement key path for the IndexedDb table"
+})
+
+/**
+ * Creates an `IndexedDb` service from an `IDBFactory` and `IDBKeyRange` constructor.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (impl: Omit<IndexedDb, typeof TypeId>): IndexedDb => IndexedDb.of({ [TypeId]: TypeId, ...impl })
+
+/**
+ * Layer that provides `IndexedDb` from `window.indexedDB` and `window.IDBKeyRange`, failing with a config error when they are unavailable.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const layerWindow: Layer.Layer<IndexedDb> = Layer.effect(
+  IndexedDb,
+  Effect.suspend(() => {
+    if (window.indexedDB && window.IDBKeyRange) {
+      return Effect.succeed(
+        make({
+          indexedDB: window.indexedDB,
+          IDBKeyRange: window.IDBKeyRange
+        })
+      )
+    } else {
+      return Effect.die(new Error("window.indexedDB is not available"))
+    }
+  })
+)