@effect/platform-browser 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Geolocation.ts

@@ -1,19 +1,35 @@
 /**
- * Browser geolocation support for Effect programs.
- *
- * This module provides a `Geolocation` service and browser-backed layer for
- * reading device location through `navigator.geolocation`. Use
- * `getCurrentPosition` when an application needs one location fix, such as a
- * nearby-search, check-in, or delivery estimate, and `watchPosition` when it
- * needs a stream of updates for navigation, tracking, or location-aware UI.
- *
- * The implementation is browser-only and relies on the browser permission and
- * policy model for geolocation. Calls may prompt the user, fail when permission
- * is denied, time out, or report that position data is unavailable because of
- * device, browser, privacy, origin, or secure-context restrictions. Watched
- * positions are scoped so the underlying browser watch is cleared when the
- * stream is finalized, and slow consumers should account for the sliding
- * buffer used by `watchPosition`.
+ * 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
  */
@@ -29,7 +45,27 @@ const TypeId = "~@effect/platform-browser/Geolocation"
 const ErrorTypeId = "~@effect/platform-browser/Geolocation/GeolocationError"
 
 /**
- * Service interface for browser geolocation, providing effects for the current position and streams of watched positions.
+ * 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
@@ -49,7 +85,14 @@ export interface Geolocation {
 }
 
 /**
- * Service tag for the browser `Geolocation` service.
+ * Service tag for browser geolocation capabilities.
+ *
+ * **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
@@ -194,9 +237,10 @@ export const layer: Layer.Layer<Geolocation> = Layer.succeed(
 )
 
 /**
- * Streams positions from the `Geolocation` service using `watchPosition`, with an optional sliding buffer size.
+ * Reads geolocation positions from the `Geolocation` service as a stream, with
+ * an optional sliding buffer size.
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const watchPosition = (

package/src/IndexedDb.ts

@@ -73,6 +73,18 @@ 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
  */

package/src/IndexedDbDatabase.ts

@@ -123,6 +123,25 @@ export class IndexedDbDatabaseError extends Data.TaggedError(
 /**
  * Service tag for an open IndexedDB database, its `IDBKeyRange` constructor, reactivity service, and rebuild effect.
  *
+ * **When to use**
+ *
+ * Use when an effect needs access to the live database service after an
+ * `IndexedDbSchema` layer has been provided, especially for `rebuild` or
+ * lower-level database primitives.
+ *
+ * **Details**
+ *
+ * `database` is a mutable reference to the current `IDBDatabase`. `IDBKeyRange`
+ * and `reactivity` are shared with query builders created from the schema.
+ *
+ * **Gotchas**
+ *
+ * `rebuild` closes and deletes the browser database, then reopens it and reruns
+ * migrations. Records not recreated by migrations are removed.
+ *
+ * @see {@link IndexedDb.IndexedDb} for the lower-level browser IndexedDB primitives
+ * @see {@link make} for creating a schema that provides this service as a layer
+ *
  * @category models
  * @since 4.0.0
  */

package/src/IndexedDbQueryBuilder.ts

@@ -84,6 +84,14 @@ export type ErrorReason =
 /**
  * Tagged error for IndexedDB query operations, carrying a query error reason and the original cause.
  *
+ * **Details**
+ *
+ * `reason` is the query failure category, `cause` preserves the underlying
+ * schema, IndexedDB request, transaction, or user callback failure, and
+ * `message` is set to the reason.
+ *
+ * @see {@link ErrorReason} for the supported failure categories
+ *
  * @category errors
  * @since 4.0.0
  */

package/src/IndexedDbTable.ts

@@ -1,21 +1,38 @@
 /**
- * Defines typed table descriptors for the browser IndexedDB integration.
- *
- * An `IndexedDbTable` records the object store name, row schema, primary key
- * path, indexes, auto-increment behavior, and transaction durability used by
- * database versions, migrations, and typed queries. These descriptors are
- * useful for local caches, offline-first application state, background queues,
- * drafts, and other browser-persisted data that should be validated through
- * `Schema`.
- *
- * Key paths and index paths must reference encoded schema fields whose values
- * are valid IndexedDB keys, and compound paths are represented as readonly
- * arrays. Tables without a key path use an out-of-line `key` that is added to
- * reads and required for writes, so the row schema itself cannot define a
- * `key` field. Auto-increment tables require a numeric key path; when that key
- * is omitted on write, the module uses a derived schema without the generated
- * key. Declaring indexes here types query builder index selection, but the
- * indexes still need to be created during database migrations.
+ * Typed object-store descriptors for the browser IndexedDB integration.
+ *
+ * An {@link IndexedDbTable} is the schema-backed description of one IndexedDB
+ * object store. It carries the store name, row schema, key path, index key
+ * paths, auto-increment mode, and transaction durability used by database
+ * versions, migrations, and typed queries.
+ *
+ * **Mental model**
+ *
+ * A table value is metadata. `make` does not create an object store; it gives
+ * database versions, migration helpers, and the query builder the information
+ * they need to type table names, validate rows, and choose schemas for reads
+ * and writes. The stored values are the encoded schema values accepted by
+ * IndexedDB, with derived schemas for out-of-line keys and generated
+ * auto-increment keys.
+ *
+ * **Common tasks**
+ *
+ * - Define object stores for browser caches, offline state, drafts, and
+ *   background queues.
+ * - Reuse the same table descriptor in database versions, migrations, and
+ *   typed queries.
+ * - Declare index key paths so query builders can restrict index names and key
+ *   values.
+ *
+ * **Gotchas**
+ *
+ * Key paths and index paths point at encoded schema fields whose values must be
+ * valid IndexedDB keys. Tables without an inline key path use an out-of-line
+ * `key`, so the row schema cannot define a `key` field. Auto-increment tables
+ * require a numeric key path, and declared indexes still have to be created in
+ * migrations.
+ *
+ * @see {@link make} for constructing table descriptors.
  *
  * @since 4.0.0
  */
@@ -176,6 +193,27 @@ const Proto = {
 /**
  * Creates a typed IndexedDB table definition from its name, schema, optional key path, indexes, auto-increment flag, and durability.
  *
+ * **When to use**
+ *
+ * Use to define a typed object-store descriptor for inclusion in an
+ * `IndexedDbVersion` and for migration or query APIs.
+ *
+ * **Details**
+ *
+ * `autoIncrement` defaults to `false` and `durability` defaults to `"relaxed"`.
+ * Tables without a key path get a read schema that includes an out-of-line
+ * `key`, while auto-increment tables use a write schema where the generated key
+ * may be omitted.
+ *
+ * **Gotchas**
+ *
+ * Tables without a key path cannot define a `key` field in their row schema.
+ * Key paths and index paths must point to encoded fields whose values are valid
+ * IndexedDB keys, and declared indexes still need to be created during
+ * database migrations.
+ *
+ * @see `IndexedDbVersion.make` for grouping table definitions into a schema version
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/IndexedDbVersion.ts

@@ -106,6 +106,20 @@ const makeProto = <Tables extends IndexedDbTable.AnyWithProps>(options: {
 /**
  * Creates an `IndexedDbVersion` from one or more table definitions.
  *
+ * **Details**
+ *
+ * The returned version exposes a `tables` map keyed by each table's
+ * `tableName`, and its type is the union of the supplied table definitions.
+ *
+ * **Gotchas**
+ *
+ * This constructor only describes the target schema; object stores and indexes
+ * still need to be created in the corresponding `IndexedDbDatabase` migration.
+ * Duplicate table names are not rejected, and the runtime map keeps the later
+ * table for a repeated key.
+ *
+ * @see {@link IndexedDbTable.make} for creating table definitions consumed by this constructor
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/Permissions.ts

@@ -1,20 +1,35 @@
 /**
- * Browser Permissions API support for Effect programs.
- *
- * This module provides a `Permissions` service and browser-backed layer for
- * querying `navigator.permissions` from Effect code. Use it to check whether a
- * browser capability is currently `granted`, `prompt`, or `denied` before
- * showing UI for flows such as geolocation, notifications, clipboard access,
- * camera, microphone, or persistent storage.
- *
- * Permission queries do not request access by themselves and should not replace
- * the feature API that actually performs the operation. Browser support for
- * permission names and states is uneven, queries may reject for unsupported or
- * invalid descriptors, and some permissions are only meaningful in secure
- * contexts or after user activation. Returned `PermissionStatus` objects can
- * change when the user updates browser settings or responds to prompts; when
- * watching `change` or `onchange`, account for browser differences and clean up
- * listeners when the surrounding Effect scope ends.
+ * Effect service for the browser Permissions API.
+ *
+ * This module wraps `navigator.permissions` in a `Permissions` service and a
+ * browser-backed layer. It lets browser programs query whether a capability is
+ * currently `granted`, `prompt`, or `denied` before deciding which UI or
+ * feature flow to show for geolocation, notifications, clipboard access,
+ * camera, microphone, persistent storage, and other browser-gated features.
+ *
+ * **Mental model**
+ *
+ * A permission query is a status read, not an access request. The service
+ * delegates to `navigator.permissions.query({ name })` and returns the browser's
+ * `PermissionStatus`, while browser rejections are represented as
+ * `PermissionsError` values.
+ *
+ * **Common tasks**
+ *
+ * - Check whether a feature is already available before rendering a prompt or
+ *   settings path.
+ * - Require permission querying through Effect context instead of reaching for
+ *   the ambient `navigator` in application code.
+ * - Provide the live browser implementation with `layer`.
+ *
+ * **Gotchas**
+ *
+ * Browser support for permission names and states is uneven, and unsupported or
+ * invalid descriptors may reject. Some permissions are only meaningful in
+ * secure contexts or after user activation. Returned `PermissionStatus` objects
+ * can change when the user updates browser settings or responds to prompts; if
+ * you subscribe to `change` or `onchange`, clean up listeners with the
+ * surrounding Effect scope.
  *
  * @since 4.0.0
  */
@@ -109,7 +124,12 @@ export class PermissionsError extends Data.TaggedError("PermissionsError")<{
 }
 
 /**
- * Service tag for the browser `Permissions` service.
+ * Service tag for browser permission querying.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to require or provide browser permission querying
+ * through the context.
  *
  * @category services
  * @since 4.0.0
@@ -117,7 +137,17 @@ export class PermissionsError extends Data.TaggedError("PermissionsError")<{
 export const Permissions: Context.Service<Permissions, Permissions> = Context.Service<Permissions>(TypeId)
 
 /**
- * A layer that directly interfaces with the `navigator.permissions` api
+ * Provides the `Permissions` service using the browser `navigator.permissions` API.
+ *
+ * **When to use**
+ *
+ * Use when browser programs need a live `Permissions` service backed by the
+ * ambient `navigator.permissions` implementation.
+ *
+ * **Details**
+ *
+ * `query` delegates to `navigator.permissions.query({ name })` and wraps
+ * rejected browser operations in `PermissionsError`.
  *
  * @category layers
  * @since 4.0.0