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

package/src/IndexedDbQueryBuilder.ts

@@ -1,7 +1,34 @@
 /**
+ * Builds effectful, schema-aware queries for typed browser IndexedDB versions.
+ *
+ * An `IndexedDbQueryBuilder` is created from an open database and a version's
+ * table descriptors, then exposes `from(tableName)` as the entry point for
+ * table operations. The resulting query objects can select, count, delete,
+ * insert, upsert, clear tables, stream paged reads, react to invalidations, and
+ * run multiple effects in a shared `IDBTransaction` with `withTransaction`.
+ *
+ * Use this module for local browser persistence such as caches, offline-first
+ * state, background queues, drafts, and other client-side data where writes
+ * should be encoded through `Schema` and reads should be decoded before they
+ * reach application code.
+ *
+ * Index and range helpers are thinly typed wrappers around IndexedDB object
+ * stores, indexes, `IDBKeyRange`, and cursors. Index names must be declared on
+ * the table and created during migrations; without an index, queries use the
+ * object store key path. Range values are encoded IndexedDB key values, and
+ * compound key paths must follow the declared key order. Filters, offsets,
+ * reverse reads, out-of-line keys, and limited deletes require cursor-based
+ * scans, while simpler selects can use `getAll`.
+ *
+ * Table schema details affect runtime behavior: auto-increment writes may omit
+ * the generated numeric key, stores without a key path require an out-of-line
+ * `key` for writes and add that `key` back to selected rows, and schema
+ * mismatches surface as `EncodeError` or `DecodeError` query failures.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "effect/Array"
+import * as Cause from "effect/Cause"
 import * as Context from "effect/Context"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
@@ -43,19 +70,22 @@ const CommonProto = {
 }
 
 /**
- * @since 4.0.0
+ * String union describing IndexedDB query failure categories such as decoding, encoding, and transaction errors.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export type ErrorReason =
-  | "NotFoundError"
   | "UnknownError"
   | "DecodeError"
   | "EncodeError"
   | "TransactionError"
 
 /**
- * @since 4.0.0
+ * Tagged error for IndexedDB query operations, carrying a query error reason and the original cause.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class IndexedDbQueryError extends Data.TaggedError(
   "IndexedDbQueryError"
@@ -64,6 +94,8 @@ export class IndexedDbQueryError extends Data.TaggedError(
   cause: unknown
 }> {
   /**
+   * Marks this value as an IndexedDB query builder error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ErrorTypeId]: typeof ErrorTypeId = ErrorTypeId
@@ -72,8 +104,10 @@ export class IndexedDbQueryError extends Data.TaggedError(
 }
 
 /**
- * @since 4.0.0
+ * Typed query builder for an IndexedDB version, with helpers for table queries, database access, clearing data, and running effects in a shared transaction.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface IndexedDbQueryBuilder<
   Source extends IndexedDbVersion.AnyWithProps
@@ -96,6 +130,9 @@ export interface IndexedDbQueryBuilder<
     table: Name
   ) => IndexedDbQuery.From<IndexedDbVersion.TableWithName<Source, Name>>
 
+  /** @internal */
+  readonly fromCache: Map<string, IndexedDbQuery.From<IndexedDbVersion.TableWithName<Source, any>>>
+
   readonly clearAll: Effect.Effect<void, IndexedDbQueryError>
 
   readonly withTransaction: <
@@ -111,29 +148,36 @@ export interface IndexedDbQueryBuilder<
 }
 
 /**
- * @since 4.0.0
+ * Valid key-path type for a table schema, using encoded fields whose values are IndexedDB-valid keys.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type KeyPath<TableSchema extends IndexedDbTable.AnySchemaStruct> =
   | IndexedDbValidKeys<TableSchema>
   | NonEmptyReadonlyArray<IndexedDbValidKeys<TableSchema>>
 
 /**
- * @since 4.0.0
+ * Valid numeric key-path type for a table schema, used for auto-increment key paths.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type KeyPathNumber<TableSchema extends IndexedDbTable.AnySchemaStruct> =
   | IndexedDbValidNumberKeys<TableSchema>
   | NonEmptyReadonlyArray<IndexedDbValidNumberKeys<TableSchema>>
 
 /**
+ * Namespace containing the typed IndexedDB query model interfaces and helper types.
+ *
  * @since 4.0.0
- * @category models
  */
 export declare namespace IndexedDbQuery {
   /**
-   * @since 4.0.0
+   * Decoded row type returned by select queries, adding a `key` field when the table does not define a key path.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type SelectType<
     Table extends IndexedDbTable.AnyWithProps
@@ -143,8 +187,10 @@ export declare namespace IndexedDbQuery {
     IndexedDbTable.TableSchema<Table>["Type"]
 
   /**
-   * @since 4.0.0
+   * Input type for insert and upsert operations, adjusted for auto-increment keys and out-of-line keys.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type ModifyType<
     Table extends IndexedDbTable.AnyWithProps
@@ -175,8 +221,10 @@ export declare namespace IndexedDbQuery {
       : {})
 
   /**
-   * @since 4.0.0
+   * Value type accepted by `equals` comparisons for a table key path or index.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type EqualsType<
     Table extends IndexedDbTable.AnyWithProps,
@@ -187,8 +235,10 @@ export declare namespace IndexedDbQuery {
     : { [I in keyof KeyPath]: KeyPath[I] extends keyof Type ? Type[KeyPath[I]] | [] : never }
 
   /**
-   * @since 4.0.0
+   * Value type accepted by range comparisons for a table key path or index, including partial tuples for compound indexes.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type ExtractIndexType<
     Table extends IndexedDbTable.AnyWithProps,
@@ -204,14 +254,18 @@ export declare namespace IndexedDbQuery {
     never
 
   /**
-   * @since 4.0.0
+   * Mutation input type for insert and upsert operations, including any required key fields.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type ModifyWithKey<Table extends IndexedDbTable.AnyWithProps> = ModifyType<Table>
 
   /**
-   * @since 4.0.0
+   * Query entry point for a table, exposing clear, select, count, delete, insert, and upsert operations.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface From<Table extends IndexedDbTable.AnyWithProps> {
     readonly table: Table
@@ -228,6 +282,12 @@ export declare namespace IndexedDbQuery {
       (): Select<Table, never>
     }
 
+    /** @internal */
+    readonly selectCache: Map<
+      string | undefined,
+      IndexedDbQuery.Select<any, never>
+    >
+
     readonly count: {
       <Index extends IndexedDbDatabase.IndexFromTable<Table>>(
         index: Index
@@ -235,6 +295,12 @@ export declare namespace IndexedDbQuery {
       (): Count<Table, never>
     }
 
+    /** @internal */
+    readonly countCache: Map<
+      string | undefined,
+      IndexedDbQuery.Count<any, never>
+    >
+
     readonly delete: {
       <Index extends IndexedDbDatabase.IndexFromTable<Table>>(
         index: Index
@@ -242,6 +308,12 @@ export declare namespace IndexedDbQuery {
       (): DeletePartial<Table, never>
     }
 
+    /** @internal */
+    readonly deleteCache: Map<
+      string | undefined,
+      IndexedDbQuery.DeletePartial<any, never>
+    >
+
     readonly insert: (value: ModifyWithKey<Table>) => Modify<Table>
     readonly insertAll: (
       values: Array<ModifyWithKey<Table>>
@@ -253,8 +325,10 @@ export declare namespace IndexedDbQuery {
   }
 
   /**
-   * @since 4.0.0
+   * Effect model for clearing all rows from a table.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Clear<
     Table extends IndexedDbTable.AnyWithProps
@@ -265,8 +339,10 @@ export declare namespace IndexedDbQuery {
   type ComparisonKeys = "equals" | "gte" | "lte" | "gt" | "lt" | "between"
 
   /**
-   * @since 4.0.0
+   * Effect model for counting table rows, optionally constrained by an index and key-range comparisons.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Count<
     Table extends IndexedDbTable.AnyWithProps,
@@ -308,8 +384,10 @@ export declare namespace IndexedDbQuery {
   }
 
   /**
-   * @since 4.0.0
+   * Intermediate delete builder used to choose a key range or limit before producing an executable delete query.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface DeletePartial<
     Table extends IndexedDbTable.AnyWithProps,
@@ -356,8 +434,10 @@ export declare namespace IndexedDbQuery {
   > = Omit<Delete<Table, Index, ExcludedKeys>, ExcludedKeys>
 
   /**
-   * @since 4.0.0
+   * Effect model for deleting rows from a table, with optional key-range, limit, filter, and reactivity invalidation helpers.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Delete<
     Table extends IndexedDbTable.AnyWithProps,
@@ -399,8 +479,10 @@ export declare namespace IndexedDbQuery {
   > = Omit<Select<Table, Index, ExcludedKeys>, ExcludedKeys>
 
   /**
-   * @since 4.0.0
+   * Effect model for selecting rows from a table, with chainable range, paging, filtering, streaming, and reactive query helpers.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Select<
     Table extends IndexedDbTable.AnyWithProps,
@@ -502,8 +584,10 @@ export declare namespace IndexedDbQuery {
   }
 
   /**
-   * @since 4.0.0
+   * Effect model for selecting the first matching row, failing with `NoSuchElementError` when no row is found.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface First<
     Table extends IndexedDbTable.AnyWithProps,
@@ -511,7 +595,7 @@ export declare namespace IndexedDbQuery {
   > extends
     Effect.Effect<
       SelectType<Table>,
-      IndexedDbQueryError,
+      IndexedDbQueryError | Cause.NoSuchElementError,
       IndexedDbTable.Context<Table>
     >
   {
@@ -526,7 +610,7 @@ export declare namespace IndexedDbQuery {
       keys?: ReadonlyArray<unknown> | Record.ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
     ) => Stream.Stream<
       SelectType<Table>,
-      IndexedDbQueryError,
+      IndexedDbQueryError | Cause.NoSuchElementError,
       IndexedDbTable.Context<Table>
     >
 
@@ -538,15 +622,17 @@ export declare namespace IndexedDbQuery {
     readonly reactiveQueue: (
       keys: ReadonlyArray<unknown> | Record.ReadonlyRecord<string, ReadonlyArray<unknown>>
     ) => Effect.Effect<
-      Queue.Dequeue<SelectType<Table>, IndexedDbQueryError>,
+      Queue.Dequeue<SelectType<Table>, IndexedDbQueryError | Cause.NoSuchElementError>,
       never,
       Scope.Scope | IndexedDbTable.Context<Table>
     >
   }
 
   /**
-   * @since 4.0.0
+   * Effect model for a select query filtered by one or more predicates over encoded table rows.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Filter<
     Table extends IndexedDbTable.AnyWithProps,
@@ -566,8 +652,10 @@ export declare namespace IndexedDbQuery {
   }
 
   /**
-   * @since 4.0.0
+   * Effect model for inserting or upserting one row, returning the resulting IndexedDB key and supporting reactivity invalidation.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Modify<
     Table extends IndexedDbTable.AnyWithProps
@@ -593,8 +681,10 @@ export declare namespace IndexedDbQuery {
   }
 
   /**
-   * @since 4.0.0
+   * Effect model for inserting or upserting multiple rows, returning the resulting IndexedDB keys and supporting reactivity invalidation.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface ModifyAll<
     Table extends IndexedDbTable.AnyWithProps
@@ -621,8 +711,10 @@ export declare namespace IndexedDbQuery {
 }
 
 /**
- * @since 4.0.0
+ * Service tag for the active `IDBTransaction` used to share a transaction across IndexedDB query effects.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class IndexedDbTransaction extends Context.Service<IndexedDbTransaction, globalThis.IDBTransaction>()(
   "@effect/platform-browser/IndexedDbQueryBuilder/IndexedDbTransaction"
@@ -885,7 +977,7 @@ const applyFirst = Effect.fnUntraced(function*(
 ) {
   const keyPath = query.select.from.table.keyPath
 
-  const data = yield* Effect.callback<any, IndexedDbQueryError>((resume) => {
+  const data = yield* Effect.callback<any, IndexedDbQueryError | Cause.NoSuchElementError>((resume) => {
     const { keyRange, store } = getReadonlyObjectStore(query.select)
 
     if (keyRange !== undefined) {
@@ -925,12 +1017,7 @@ const applyFirst = Effect.fnUntraced(function*(
 
         if (value === undefined) {
           resume(
-            Effect.fail(
-              new IndexedDbQueryError({
-                reason: "NotFoundError",
-                cause: request.error
-              })
-            )
+            Effect.fail(new Cause.NoSuchElementError(`No such element in table ${query.select.from.table.tableName}`))
           )
         } else {
           resume(
@@ -964,15 +1051,11 @@ const applyModify = Effect.fnUntraced(function*({
   const autoIncrement = query.from.table.autoIncrement as boolean
   const keyPath = query.from.table.keyPath
   const table = query.from.table
-  const schema = autoIncrement && value[keyPath] === undefined
+  const schema: Schema.Top = autoIncrement && value[keyPath] === undefined
     ? table.autoincrementSchema
     : table.tableSchema
 
-  const encodedValue = yield* SchemaParser.makeEffect(
-    autoIncrement && value[keyPath] === undefined
-      ? table.autoincrementSchema
-      : table.tableSchema
-  )(value).pipe(
+  const encodedValue = yield* schema.makeEffect(value).pipe(
     Effect.flatMap(Schema.encodeUnknownEffect(schema)),
     Effect.mapError(
       (error) =>
@@ -1229,34 +1312,52 @@ const FromProto: Omit<
   | "IDBKeyRange"
   | "transaction"
   | "reactivity"
+  | "selectCache"
+  | "countCache"
+  | "deleteCache"
 > = {
   ...CommonProto,
   select<Index extends IndexedDbDatabase.IndexFromTable<any>>(
     this: IndexedDbQuery.From<any>,
     index?: Index
   ) {
-    return makeSelect({
-      from: this,
-      index
-    }) as any
+    let select = this.selectCache.get(index)
+    if (select === undefined) {
+      select = makeSelect({
+        from: this,
+        index
+      })
+      this.selectCache.set(index, select)
+    }
+    return select
   },
   count<Index extends IndexedDbDatabase.IndexFromTable<any>>(
     this: IndexedDbQuery.From<any>,
     index?: Index
   ) {
-    return makeCount({
-      from: this,
-      index
-    }) as any
+    let count = this.countCache.get(index)
+    if (count === undefined) {
+      count = makeCount({
+        from: this,
+        index
+      })
+      this.countCache.set(index, count)
+    }
+    return count
   },
   delete<Index extends IndexedDbDatabase.IndexFromTable<any>>(
     this: IndexedDbQuery.From<any>,
     index?: Index
   ) {
-    return makeDeletePartial({
-      from: this,
-      index
-    }) as any
+    let cached = this.deleteCache.get(index)
+    if (cached === undefined) {
+      cached = makeDeletePartial({
+        from: this,
+        index
+      })
+      this.deleteCache.set(index, cached)
+    }
+    return cached
   },
   insert(this: IndexedDbQuery.From<any>, value: any) {
     return makeModify({ from: this, value, operation: "add" })
@@ -1292,6 +1393,9 @@ const makeFrom = <
   self.database = options.database
   self.IDBKeyRange = options.IDBKeyRange
   self.reactivity = options.reactivity
+  self.selectCache = new Map()
+  self.countCache = new Map()
+  self.deleteCache = new Map()
   return self
 }
 
@@ -1825,6 +1929,7 @@ const makeModifyAll = <
 
 const QueryBuilderProto: Omit<
   IndexedDbQueryBuilder<any>,
+  | "fromCache"
   | "tables"
   | "database"
   | "IDBKeyRange"
@@ -1843,12 +1948,17 @@ const QueryBuilderProto: Omit<
     })
   },
   from(this: IndexedDbQueryBuilder<any>, table: any) {
-    return makeFrom({
-      database: this.database,
-      IDBKeyRange: this.IDBKeyRange,
-      table: this.tables.get(table)!,
-      reactivity: this.reactivity
-    }) as any
+    let cached = this.fromCache.get(table)
+    if (cached === undefined) {
+      cached = makeFrom({
+        database: this.database,
+        IDBKeyRange: this.IDBKeyRange,
+        table: this.tables.get(table)!,
+        reactivity: this.reactivity
+      })
+      this.fromCache.set(table, cached)
+    }
+    return cached as any
   },
   get clearAll() {
     const self = this as IndexedDbQueryBuilder<any>
@@ -1871,8 +1981,10 @@ const QueryBuilderProto: Omit<
 }
 
 /**
- * @since 4.0.0
+ * Creates an `IndexedDbQueryBuilder` from an open database reference, key-range constructor, table map, and reactivity service.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <Source extends IndexedDbVersion.AnyWithProps>({
   IDBKeyRange,
@@ -1890,6 +2002,7 @@ export const make = <Source extends IndexedDbVersion.AnyWithProps>({
   self.database = database
   self.reactivity = reactivity
   self.IDBKeyRange = IDBKeyRange
+  self.fromCache = new Map()
   return self
 }
 

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,