@effect/platform-browser 4.0.0-beta.8 → 4.0.0-beta.80

package/src/IndexedDbTable.ts

@@ -0,0 +1,260 @@
+/**
+ * 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. The `make` constructor also derives
+ * the read, array, and auto-increment write schemas used by the query builder.
+ *
+ * @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,138 @@
+/**
+ * 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.
+ *
+ * **When to use**
+ *
+ * Use when you need a typed description of the target IndexedDB schema that a
+ * database migration will materialize.
+ *
+ * **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,18 @@
 /**
- * @since 1.0.0
+ * Effect service for the browser Permissions API.
+ *
+ * This module defines a `Permissions` service backed by
+ * `navigator.permissions`. The service exposes `query`, which returns the
+ * browser `PermissionStatus` for a permission name. Failed browser operations
+ * are represented as `PermissionsError` values with `InvalidStateError` or
+ * `TypeError` reasons, and `layer` provides the browser-backed service.
+ *
+ * @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 +21,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 +41,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 +55,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 +69,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 +100,33 @@ export class PermissionsError extends Data.TaggedError("PermissionsError")<{
 }
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for browser permission querying.
+ *
+ * **When to use**
+ *
+ * Use when you need to require or provide browser permission querying through
+ * Effect's 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 you need a live browser `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"