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

package/src/IndexedDbTable.ts

@@ -0,0 +1,285 @@
+/**
+ * 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
+ */
+import { type Pipeable, pipeArguments } from "effect/Pipeable"
+import * as Schema from "effect/Schema"
+import * as Struct from "effect/Struct"
+import type { NoInfer } from "effect/Types"
+import * as IndexedDb from "./IndexedDb.ts"
+import type * as IndexedDbQueryBuilder from "./IndexedDbQueryBuilder.ts"
+
+const TypeId = "~@effect/platform-browser/IndexedDbTable"
+
+/**
+ * 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,
+  out TableSchema extends AnySchemaStruct,
+  out Indexes extends Record<
+    string,
+    IndexedDbQueryBuilder.KeyPath<TableSchema>
+  >,
+  out KeyPath extends Readonly<IDBValidKey | undefined>,
+  out AutoIncrement extends boolean
+> extends Pipeable {
+  new(_: never): {}
+  readonly [TypeId]: typeof TypeId
+  readonly tableName: Name
+  readonly tableSchema: TableSchema
+  readonly readSchema: Schema.Top
+  readonly autoincrementSchema: Schema.Top
+  readonly arraySchema: Schema.Top
+  readonly keyPath: KeyPath
+  readonly indexes: Indexes
+  readonly autoIncrement: AutoIncrement
+  readonly durability: IDBTransactionDurability
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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
+  readonly keyPath: any
+  readonly tableName: string
+  readonly tableSchema: Schema.Top
+  readonly readSchema: Schema.Top
+  readonly autoincrementSchema: Schema.Top
+  readonly arraySchema: Schema.Top
+  readonly autoIncrement: boolean
+  readonly indexes: any
+}
+
+/**
+ * Type-erased `IndexedDbTable` retaining the table interface properties with broad type parameters.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type AnyWithProps = IndexedDbTable<
+  string,
+  AnySchemaStruct,
+  any,
+  any,
+  boolean
+>
+
+/**
+ * Extracts the table name type from an `IndexedDbTable`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type TableName<Table extends Any> = Table["tableName"]
+/**
+ * Extracts the key-path type from an `IndexedDbTable`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type KeyPath<Table extends Any> = Table["keyPath"]
+
+/**
+ * Extracts the auto-increment flag type from an `IndexedDbTable`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type AutoIncrement<Table extends Any> = Table["autoIncrement"]
+
+/**
+ * Extracts the schema type from an `IndexedDbTable`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type TableSchema<Table extends Any> = Table["tableSchema"]
+/**
+ * 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"]
+
+/**
+ * Extracts the encoded row type from an `IndexedDbTable` schema.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Encoded<Table extends Any> = Table["tableSchema"]["Encoded"]
+
+/**
+ * Extracts the index definition map from an `IndexedDbTable`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Indexes<Table extends Any> = Table["indexes"]
+
+/**
+ * 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,
+  { readonly tableName: TableName }
+>
+
+const Proto = {
+  [TypeId]: TypeId,
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * 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
+ */
+export const make = <
+  const Name extends string,
+  TableSchema extends AnySchemaStruct,
+  const Indexes extends Record<
+    string,
+    IndexedDbQueryBuilder.KeyPath<TableSchema>
+  >,
+  const KeyPath extends
+    | (AutoIncrement extends true ? IndexedDbQueryBuilder.KeyPathNumber<NoInfer<TableSchema>>
+      : IndexedDbQueryBuilder.KeyPath<NoInfer<TableSchema>>)
+    | undefined = undefined,
+  const AutoIncrement extends boolean = false
+>(options: {
+  readonly name: Name
+  readonly schema: [KeyPath] extends [undefined]
+    ? "key" extends keyof TableSchema["fields"] ? "Cannot have a 'key' field when keyPath is undefined"
+    : TableSchema
+    : TableSchema
+  readonly keyPath?: KeyPath
+  readonly indexes?: Indexes | undefined
+  readonly autoIncrement?: IsValidAutoIncrementKeyPath<
+    TableSchema,
+    KeyPath
+  > extends true ? AutoIncrement | undefined
+    : never
+  readonly durability?: IDBTransactionDurability | undefined
+}): IndexedDbTable<
+  Name,
+  TableSchema,
+  Indexes,
+  Extract<KeyPath, Readonly<IDBValidKey | undefined>>,
+  AutoIncrement
+> => {
+  // oxlint-disable-next-line typescript/no-extraneous-class
+  class Table {}
+  Object.assign(Table, Proto)
+  const readSchema = options.keyPath === undefined
+    ? Schema.Struct({
+      ...(options.schema as Schema.Struct<{}>).fields,
+      key: IndexedDb.IDBValidKey
+    })
+    : options.schema
+  ;(Table as any).tableName = options.name
+  ;(Table as any).tableSchema = options.schema
+  ;(Table as any).readSchema = readSchema
+  ;(Table as any).arraySchema = Schema.Array(readSchema as any)
+  ;(Table as any).autoincrementSchema = options.autoIncrement
+    ? Schema.Struct(Struct.omit((options.schema as Schema.Struct<{}>).fields, [options.keyPath!] as any))
+    : options.schema
+  ;(Table as any).keyPath = options.keyPath
+  ;(Table as any).indexes = options.indexes
+  ;(Table as any).autoIncrement = options.autoIncrement === true
+  ;(Table as any).durability = options.durability ?? "relaxed"
+  return Table as any
+}
+
+// -----------------------------------------------------------------------------
+// internal
+// -----------------------------------------------------------------------------
+
+type IsValidAutoIncrementKeyPath<
+  TableSchema extends AnySchemaStruct,
+  KeyPath
+> = KeyPath extends keyof TableSchema["Encoded"] ? TableSchema["Encoded"][KeyPath] extends number ? true
+  : false
+  : false

package/src/IndexedDbVersion.ts

@@ -0,0 +1,133 @@
+/**
+ * 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"
+import type { Pipeable } from "effect/Pipeable"
+import { pipeArguments } from "effect/Pipeable"
+import type * as IndexedDbTable from "./IndexedDbTable.ts"
+
+const TypeId = "~@effect/platform-browser/IndexedDbVersion"
+
+/**
+ * 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
+> extends Pipeable {
+  new(_: never): {}
+  readonly [TypeId]: typeof TypeId
+  readonly tables: ReadonlyMap<string, Tables>
+}
+
+/**
+ * Type-erased shape of an `IndexedDbVersion`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Any {
+  readonly [TypeId]: typeof TypeId
+}
+
+/**
+ * Type-erased `IndexedDbVersion` retaining version properties with broad table types.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type AnyWithProps = IndexedDbVersion<IndexedDbTable.AnyWithProps>
+
+/**
+ * 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
+
+/**
+ * Selects a table by name from an `IndexedDbVersion`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type TableWithName<
+  Db extends Any,
+  TableName extends string
+> = IndexedDbTable.WithName<Tables<Db>, TableName>
+
+/**
+ * Extracts the schema for a named table within an `IndexedDbVersion`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type SchemaWithName<
+  Db extends Any,
+  TableName extends string
+> = IndexedDbTable.TableSchema<IndexedDbTable.WithName<Tables<Db>, TableName>>
+
+const Proto = {
+  [TypeId]: TypeId,
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+const makeProto = <Tables extends IndexedDbTable.AnyWithProps>(options: {
+  readonly tables: ReadonlyMap<string, Tables>
+}): IndexedDbVersion<Tables> => {
+  // oxlint-disable-next-line typescript/no-extraneous-class
+  class Version {}
+  Object.assign(Version, Proto)
+  ;(Version as any).tables = options.tables
+  return Version as any
+}
+
+/**
+ * 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
+ */
+export const make = <
+  const Tables extends NonEmptyReadonlyArray<IndexedDbTable.AnyWithProps>
+>(
+  ...tables: Tables
+): IndexedDbVersion<Tables[number]> =>
+  makeProto({
+    tables: new Map(tables.map((table) => [table.tableName, table]))
+  })

package/src/Permissions.ts

@@ -1,10 +1,42 @@
 /**
- * @since 1.0.0
+ * 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
  */
+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/Permissions"
 const ErrorTypeId = "~@effect/platform-browser/Permissions/PermissionsError"
@@ -13,8 +45,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
+ * @category models
+ * @since 4.0.0
  */
 export interface Permissions {
   readonly [TypeId]: typeof TypeId
@@ -33,8 +65,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 +79,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 +93,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 +124,33 @@ export class PermissionsError extends Data.TaggedError("PermissionsError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the browser `Permissions` service.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to require or provide browser permission querying
+ * through the context.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export const Permissions: ServiceMap.Service<Permissions, Permissions> = ServiceMap.Service<Permissions>(TypeId)
+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`.
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Permissions> = Layer.succeed(
   Permissions,

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
@@ -7,49 +7,84 @@
 /**
  * @since 1.0.0
  */
+export * as BrowserCrypto from "./BrowserCrypto.ts"
+
+/**
+ * @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 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"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
+ */
+export * as IndexedDb from "./IndexedDb.ts"
+
+/**
+ * @since 4.0.0
+ */
+export * as IndexedDbDatabase from "./IndexedDbDatabase.ts"
+
+/**
+ * @since 4.0.0
+ */
+export * as IndexedDbQueryBuilder from "./IndexedDbQueryBuilder.ts"
+
+/**
+ * @since 4.0.0
+ */
+export * as IndexedDbTable from "./IndexedDbTable.ts"
+
+/**
+ * @since 4.0.0
+ */
+export * as IndexedDbVersion from "./IndexedDbVersion.ts"
+
+/**
+ * @since 4.0.0
  */
 export * as Permissions from "./Permissions.ts"