@effect/platform-browser 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Geolocation.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * 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`.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Context from "effect/Context"
@@ -13,8 +29,10 @@ 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.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Geolocation {
   readonly [TypeId]: typeof TypeId
@@ -31,14 +49,18 @@ export interface Geolocation {
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the browser `Geolocation` service.
+ *
+ * @category services
+ * @since 4.0.0
  */
 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 +82,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 +96,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 +110,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 +124,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 +171,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 +194,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

@@ -1,18 +1,40 @@
 /**
+ * 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 Config from "effect/Config"
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Schema from "effect/Schema"
-import * as SchemaIssue from "effect/SchemaIssue"
 
 const TypeId = "~@effect/platform-browser/IndexedDb"
 
 /**
- * @since 4.0.0
+ * Service interface that provides the browser `indexedDB` factory and `IDBKeyRange` constructor.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface IndexedDb {
   readonly [TypeId]: typeof TypeId
@@ -21,8 +43,10 @@ export interface IndexedDb {
 }
 
 /**
- * @since 4.0.0
+ * Service tag for browser IndexedDB primitives.
+ *
  * @category tag
+ * @since 4.0.0
  */
 export const IndexedDb: Context.Service<IndexedDb, IndexedDb> = Context.Service<IndexedDb, IndexedDb>(TypeId)
 
@@ -39,18 +63,18 @@ const IDBFlatKey = Schema.Union([
 ])
 
 /**
- * Schema for `IDBValidKey` (`number | string | Date | BufferSource | IDBValidKey[]`).
+ * Schema for IndexedDB keys: strings, non-NaN numbers, valid dates, buffer sources, or arrays of those flat key values.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const IDBValidKey = Schema.Union([IDBFlatKey, Schema.Array(IDBFlatKey)])
 
 /**
- * Schema for `autoIncrement` key path (`number`).
+ * Schema for auto-incremented IndexedDB keys, accepting integers from 1 through `2 ** 53`.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const AutoIncrement = Schema.Int.check(
   Schema.isBetween({ minimum: 1, maximum: 2 ** 53 })
@@ -61,18 +85,20 @@ export const AutoIncrement = Schema.Int.check(
 })
 
 /**
+ * Creates an `IndexedDb` service from an `IDBFactory` and `IDBKeyRange` constructor.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category constructor
  */
 export const make = (impl: Omit<IndexedDb, typeof TypeId>): IndexedDb => IndexedDb.of({ [TypeId]: TypeId, ...impl })
 
 /**
- * Instance of IndexedDb from the `window` object.
+ * Layer that provides `IndexedDb` from `window.indexedDB` and `window.IDBKeyRange`, failing with a config error when they are unavailable.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
-export const layerWindow: Layer.Layer<IndexedDb, Config.ConfigError> = Layer.effect(
+export const layerWindow: Layer.Layer<IndexedDb> = Layer.effect(
   IndexedDb,
   Effect.suspend(() => {
     if (window.indexedDB && window.IDBKeyRange) {
@@ -83,15 +109,7 @@ export const layerWindow: Layer.Layer<IndexedDb, Config.ConfigError> = Layer.eff
         })
       )
     } else {
-      return Effect.fail(
-        new Config.ConfigError(
-          new Schema.SchemaError(
-            new SchemaIssue.MissingKey({
-              messageMissingKey: "window.indexedDB is not available"
-            })
-          )
-        )
-      )
+      return Effect.die(new Error("window.indexedDB is not available"))
     }
   })
 )

package/src/IndexedDbDatabase.ts

@@ -1,4 +1,29 @@
 /**
+ * Builds and opens typed IndexedDB databases from versioned schema migrations.
+ *
+ * This module turns an `IndexedDbVersion` migration chain into an
+ * `IndexedDbDatabase` layer. The layer opens the browser database, runs any
+ * pending upgrade migrations, provides a query builder for the current schema,
+ * and exposes a `rebuild` effect that deletes and reopens the database. It is
+ * the database-level companion to the table, version, and query builder
+ * modules.
+ *
+ * Use it for browser-local persistence such as offline-first application
+ * state, cached server data, background queues, drafts, and other client-side
+ * stores that need typed reads and writes backed by IndexedDB transactions.
+ *
+ * IndexedDB schema changes can only happen inside upgrade transactions, so
+ * every call to `make` or `.add` represents the next browser database version
+ * and only migrations after the existing browser version are run. Table and
+ * index definitions type the migration and query APIs, but object stores and
+ * indexes still need to be created or removed explicitly with the migration
+ * transaction helpers. Include the complete target table set in each version,
+ * create indexes before querying them, and treat key path or auto-increment
+ * changes as store migrations that copy data into a replacement object store.
+ * Upgrades can be blocked by other open connections, and all migration reads,
+ * writes, store changes, and index changes share the single upgrade
+ * transaction supplied by the browser.
+ *
  * @since 4.0.0
  */
 import * as Context from "effect/Context"
@@ -60,8 +85,10 @@ const SchemaProto = {
 }
 
 /**
- * @since 4.0.0
+ * String union describing the failure categories for IndexedDB database opening, migration, and schema operations.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type ErrorReason =
   | "TransactionError"
@@ -73,8 +100,10 @@ export type ErrorReason =
   | "MissingIndex"
 
 /**
- * @since 4.0.0
+ * Tagged error for IndexedDB database operations, carrying a database error reason and the original cause.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class IndexedDbDatabaseError extends Data.TaggedError(
   "IndexedDbDatabaseError"
@@ -83,6 +112,8 @@ export class IndexedDbDatabaseError extends Data.TaggedError(
   cause: unknown
 }> {
   /**
+   * Marks this value as an IndexedDB database error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ErrorTypeId]: typeof ErrorTypeId = ErrorTypeId
@@ -90,8 +121,10 @@ export class IndexedDbDatabaseError extends Data.TaggedError(
 }
 
 /**
- * @since 4.0.0
+ * Service tag for an open IndexedDB database, its `IDBKeyRange` constructor, reactivity service, and rebuild effect.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class IndexedDbDatabase extends Context.Service<
   IndexedDbDatabase,
@@ -104,8 +137,10 @@ export class IndexedDbDatabase extends Context.Service<
 >()(TypeId) {}
 
 /**
- * @since 4.0.0
+ * Describes an IndexedDB schema version and its migrations, and acts as an effect that yields a query builder for the target version.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface IndexedDbSchema<
   in out FromVersion extends IndexedDbVersion.AnyWithProps,
@@ -155,8 +190,10 @@ export interface IndexedDbSchema<
 }
 
 /**
- * @since 4.0.0
+ * Query builder available during a database migration, extended with object-store and index management helpers for the active `IDBTransaction`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Transaction<
   Source extends IndexedDbVersion.AnyWithProps = never
@@ -192,8 +229,10 @@ export interface Transaction<
 }
 
 /**
- * @since 4.0.0
+ * Extracts the string-literal index names defined by an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type IndexFromTable<Table extends IndexedDbTable.AnyWithProps> = IsStringLiteral<
   Extract<keyof IndexedDbTable.Indexes<Table>, string>
@@ -201,8 +240,10 @@ export type IndexFromTable<Table extends IndexedDbTable.AnyWithProps> = IsString
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the valid index names for a table name within an IndexedDB version.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type IndexFromTableName<
   Version extends IndexedDbVersion.AnyWithProps,
@@ -212,8 +253,10 @@ export type IndexFromTableName<
 >
 
 /**
- * @since 4.0.0
+ * Type-erased IndexedDB schema shape used when traversing schema migration chains.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly previous?: Any | undefined
@@ -227,8 +270,10 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased `IndexedDbSchema` covering any source version, target version, and migration error type.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnySchema = IndexedDbSchema<
   IndexedDbVersion.AnyWithProps,
@@ -237,8 +282,10 @@ export type AnySchema = IndexedDbSchema<
 >
 
 /**
- * @since 4.0.0
+ * Creates the initial `IndexedDbSchema` from a version and an initialization migration run during database upgrade.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <
   InitialVersion extends IndexedDbVersion.AnyWithProps,