@effect/platform-browser 4.0.0-beta.8 → 4.0.0-beta.81

package/src/BrowserStream.ts

@@ -1,5 +1,11 @@
 /**
- * @since 1.0.0
+ * Browser DOM event streams.
+ *
+ * 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
  */
 
 import * as Stream from "effect/Stream"
@@ -7,11 +13,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
+ * @category streams
+ * @since 4.0.0
  */
 export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
   type: K,
@@ -26,11 +35,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
+ * @category streams
+ * @since 4.0.0
  */
 export const fromEventListenerDocument = <K extends keyof DocumentEventMap>(
   type: K,

package/src/BrowserWorker.ts

@@ -1,5 +1,12 @@
 /**
- * @since 1.0.0
+ * Parent-side browser platform for Effect workers.
+ *
+ * `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
  */
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
@@ -9,8 +16,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 you need 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 +47,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 +78,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,13 @@
 /**
- * @since 1.0.0
+ * Runner-side browser platform for Effect worker handlers.
+ *
+ * `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
  */
 import * as Cause from "effect/Cause"
 import * as Deferred from "effect/Deferred"
@@ -22,8 +30,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 +54,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 +93,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 +104,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 +161,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 you need a browser worker entry point to use 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,45 @@
 /**
- * @since 1.0.0
+ * Browser clipboard integration for Effect programs.
+ *
+ * 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
  */
+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
+ * Defines the service interface for reading from, writing to, and clearing the browser clipboard.
+ *
+ * **When to use**
+ *
+ * Use when an application needs clipboard operations through an Effect service
+ * so browser failures stay in the error channel.
+ *
+ * **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 +52,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 +65,26 @@ export class ClipboardError extends Data.TaggedError("ClipboardError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for browser clipboard capabilities.
+ *
+ * **When to use**
+ *
+ * Use when you need to require or provide clipboard capabilities through
+ * Effect's 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>
@@ -55,10 +97,10 @@ export const make = (
   })
 
 /**
- * A layer that directly interfaces with the navigator.clipboard api
+ * Layer that directly interfaces with the browser 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,51 @@
 /**
- * @since 1.0.0
+ * Browser geolocation integration for Effect programs.
+ *
+ * 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
  */
 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
+ * Defines the 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 +62,25 @@ export interface Geolocation {
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for browser geolocation capabilities.
+ *
+ * **When to use**
+ *
+ * Use when you need to access or provide geolocation capabilities through
+ * Effect's 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 +102,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 +116,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 +130,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 +144,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 +191,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 +214,11 @@ export const layer: Layer.Layer<Geolocation> = Layer.succeed(
 )
 
 /**
- * @since 1.0.0
- * @category Accessors
+ * Reads geolocation positions from the `Geolocation` service as a stream, with
+ * an optional sliding buffer size.
+ *
+ * @category accessors
+ * @since 4.0.0
  */
 export const watchPosition = (
   options?:

package/src/IndexedDb.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ *
+ * @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 services
+ * @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 you need to define 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"))
+    }
+  })
+)