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

package/src/IndexedDbTable.ts

@@ -0,0 +1,247 @@
+/**
+ * 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"
+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.
+ *
+ * @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,119 @@
+/**
+ * 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.
+ *
+ * @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,27 @@
 /**
- * @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"
 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 +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
+ * @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
- * @category Service
+ * Service tag for the browser `Permissions` service.
+ *
+ * @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
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Permissions> = Layer.succeed(
   Permissions,