@effect/platform-browser 4.0.0-beta.65 → 4.0.0-beta.67

package/src/IndexedDbTable.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import { type Pipeable, pipeArguments } from "effect/Pipeable"
@@ -11,8 +29,10 @@ import type * as IndexedDbQueryBuilder from "./IndexedDbQueryBuilder.ts"
 const TypeId = "~@effect/platform-browser/IndexedDbTable"
 
 /**
- * @since 4.0.0
+ * Typed IndexedDB table definition containing its name, schema, key path, indexes, auto-increment setting, and transaction durability.
+ *
  * @category interface
+ * @since 4.0.0
  */
 export interface IndexedDbTable<
   out Name extends string,
@@ -38,16 +58,20 @@ export interface IndexedDbTable<
 }
 
 /**
- * @since 4.0.0
+ * Schema constraint for table schemas that expose struct fields.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnySchemaStruct = Schema.Top & {
   readonly fields: Schema.Struct.Fields
 }
 
 /**
- * @since 4.0.0
+ * Type-erased shape of an `IndexedDbTable` used when table type parameters are not needed.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
@@ -62,8 +86,10 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased `IndexedDbTable` retaining the table interface properties with broad type parameters.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnyWithProps = IndexedDbTable<
   string,
@@ -74,50 +100,66 @@ export type AnyWithProps = IndexedDbTable<
 >
 
 /**
- * @since 4.0.0
+ * Extracts the table name type from an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type TableName<Table extends Any> = Table["tableName"]
 /**
- * @since 4.0.0
+ * Extracts the key-path type from an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type KeyPath<Table extends Any> = Table["keyPath"]
 
 /**
- * @since 4.0.0
+ * Extracts the auto-increment flag type from an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AutoIncrement<Table extends Any> = Table["autoIncrement"]
 
 /**
- * @since 4.0.0
+ * Extracts the schema type from an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type TableSchema<Table extends Any> = Table["tableSchema"]
 /**
- * @since 4.0.0
+ * Extracts the decoding or encoding service requirements needed by an `IndexedDbTable` schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Context<Table extends Any> =
   | Table["tableSchema"]["DecodingServices"]
   | Table["tableSchema"]["EncodingServices"]
 
 /**
- * @since 4.0.0
+ * Extracts the encoded row type from an `IndexedDbTable` schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Encoded<Table extends Any> = Table["tableSchema"]["Encoded"]
 
 /**
- * @since 4.0.0
+ * Extracts the index definition map from an `IndexedDbTable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Indexes<Table extends Any> = Table["indexes"]
 
 /**
- * @since 4.0.0
+ * Selects the table with the given name from a union of `IndexedDbTable` types.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type WithName<Table extends Any, TableName extends string> = Extract<
   Table,
@@ -132,8 +174,10 @@ const Proto = {
 }
 
 /**
- * @since 4.0.0
+ * Creates a typed IndexedDB table definition from its name, schema, optional key path, indexes, auto-increment flag, and durability.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <
   const Name extends string,

package/src/IndexedDbVersion.ts

@@ -1,4 +1,20 @@
 /**
+ * Typed IndexedDB schema version definitions.
+ *
+ * This module represents one logical IndexedDB database version as a non-empty set of `IndexedDbTable` definitions.
+ * Versions are consumed by `IndexedDbDatabase.make` and `.add` to type query builders and migration transactions, so
+ * applications can describe the tables available after initialization or after each schema upgrade.
+ *
+ * Use an `IndexedDbVersion` when defining the initial stores for a browser database, adding or removing object stores,
+ * changing indexes, or moving data between differently shaped table schemas. The version value is a typed description of
+ * the target schema; creating and deleting object stores or indexes still happens explicitly inside the corresponding
+ * `IndexedDbDatabase` migration callback.
+ *
+ * IndexedDB versioning is ordered by the migration chain rather than by a number stored here. Each `.add` step becomes
+ * the next browser database version, and only migrations after the browser's current version are run. Include every table
+ * that should be queryable in each target version, avoid duplicate table names, and remember that key-path or
+ * auto-increment changes usually require creating a new object store and copying data during the upgrade transaction.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "effect/Array"
@@ -9,8 +25,10 @@ import type * as IndexedDbTable from "./IndexedDbTable.ts"
 const TypeId = "~@effect/platform-browser/IndexedDbVersion"
 
 /**
- * @since 4.0.0
+ * Typed IndexedDB version definition containing the tables available in that schema version.
+ *
  * @category interface
+ * @since 4.0.0
  */
 export interface IndexedDbVersion<
   out Tables extends IndexedDbTable.AnyWithProps
@@ -21,28 +39,36 @@ export interface IndexedDbVersion<
 }
 
 /**
- * @since 4.0.0
+ * Type-erased shape of an `IndexedDbVersion`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
 }
 
 /**
- * @since 4.0.0
+ * Type-erased `IndexedDbVersion` retaining version properties with broad table types.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnyWithProps = IndexedDbVersion<IndexedDbTable.AnyWithProps>
 
 /**
- * @since 4.0.0
+ * Extracts the table union from an `IndexedDbVersion`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Tables<Db extends Any> = Db extends IndexedDbVersion<infer _Tables> ? _Tables : never
 
 /**
- * @since 4.0.0
+ * Selects a table by name from an `IndexedDbVersion`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type TableWithName<
   Db extends Any,
@@ -50,8 +76,10 @@ export type TableWithName<
 > = IndexedDbTable.WithName<Tables<Db>, TableName>
 
 /**
- * @since 4.0.0
+ * Extracts the schema for a named table within an `IndexedDbVersion`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type SchemaWithName<
   Db extends Any,
@@ -76,8 +104,10 @@ const makeProto = <Tables extends IndexedDbTable.AnyWithProps>(options: {
 }
 
 /**
- * @since 4.0.0
+ * Creates an `IndexedDbVersion` from one or more table definitions.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <
   const Tables extends NonEmptyReadonlyArray<IndexedDbTable.AnyWithProps>

package/src/Permissions.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * 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.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Data from "effect/Data"
@@ -13,8 +30,8 @@ const ErrorTypeId = "~@effect/platform-browser/Permissions/PermissionsError"
  * Wrapper on the Permission API (`navigator.permissions`) with methods for
  * querying status of permissions.
  *
- * @since 1.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface Permissions {
   readonly [TypeId]: typeof TypeId
@@ -33,8 +50,10 @@ export interface Permissions {
 }
 
 /**
- * @since 1.0.0
+ * Error reason for an `InvalidStateError` raised by the browser Permissions API.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class PermissionsInvalidStateError extends Data.TaggedError("InvalidStateError")<{
   readonly cause: unknown
@@ -45,8 +64,10 @@ export class PermissionsInvalidStateError extends Data.TaggedError("InvalidState
 }
 
 /**
- * @since 1.0.0
+ * Error reason for a `TypeError` raised by the browser Permissions API.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class PermissionsTypeError extends Data.TaggedError("TypeError")<{
   readonly cause: unknown
@@ -57,14 +78,18 @@ export class PermissionsTypeError extends Data.TaggedError("TypeError")<{
 }
 
 /**
- * @since 1.0.0
+ * Union of browser Permissions API error reasons represented by the service.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type PermissionsErrorReason = PermissionsInvalidStateError | PermissionsTypeError
 
 /**
- * @since 1.0.0
+ * Tagged error wrapping a browser Permissions API failure reason.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class PermissionsError extends Data.TaggedError("PermissionsError")<{
   readonly reason: PermissionsErrorReason
@@ -84,16 +109,18 @@ export class PermissionsError extends Data.TaggedError("PermissionsError")<{
 }
 
 /**
- * @since 1.0.0
+ * Service tag for the browser `Permissions` service.
+ *
  * @category Service
+ * @since 4.0.0
  */
 export const Permissions: Context.Service<Permissions, Permissions> = Context.Service<Permissions>(TypeId)
 
 /**
  * A layer that directly interfaces with the `navigator.permissions` api
  *
- * @since 1.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Permissions> = Layer.succeed(
   Permissions,

package/src/index.ts

@@ -1,56 +1,56 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserHttpClient from "./BrowserHttpClient.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserKeyValueStore from "./BrowserKeyValueStore.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserPersistence from "./BrowserPersistence.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserRuntime from "./BrowserRuntime.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserSocket from "./BrowserSocket.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserStream from "./BrowserStream.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserWorker from "./BrowserWorker.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as BrowserWorkerRunner from "./BrowserWorkerRunner.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Clipboard from "./Clipboard.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Geolocation from "./Geolocation.ts"
 
@@ -80,6 +80,6 @@ export * as IndexedDbTable from "./IndexedDbTable.ts"
 export * as IndexedDbVersion from "./IndexedDbVersion.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Permissions from "./Permissions.ts"