@tanstack/db 0.0.27 → 0.0.30

package/dist/cjs/indexes/btree-index.cjs

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const comparison = require("../utils/comparison.cjs");
+const btree = require("../utils/btree.cjs");
+const baseIndex = require("./base-index.cjs");
+class BTreeIndex extends baseIndex.BaseIndex {
+  constructor(id, expression, name, options) {
+    super(id, expression, name, options);
+    this.supportedOperations = /* @__PURE__ */ new Set([
+      `eq`,
+      `gt`,
+      `gte`,
+      `lt`,
+      `lte`,
+      `in`
+    ]);
+    this.valueMap = /* @__PURE__ */ new Map();
+    this.indexedKeys = /* @__PURE__ */ new Set();
+    this.compareFn = comparison.ascComparator;
+    this.compareFn = (options == null ? void 0 : options.compareFn) ?? comparison.ascComparator;
+    this.orderedEntries = new btree.BTree(this.compareFn);
+  }
+  initialize(_options) {
+  }
+  /**
+   * Adds a value to the index
+   */
+  add(key, item) {
+    let indexedValue;
+    try {
+      indexedValue = this.evaluateIndexExpression(item);
+    } catch (error) {
+      throw new Error(
+        `Failed to evaluate index expression for key ${key}: ${error}`
+      );
+    }
+    if (this.valueMap.has(indexedValue)) {
+      this.valueMap.get(indexedValue).add(key);
+    } else {
+      const keySet = /* @__PURE__ */ new Set([key]);
+      this.valueMap.set(indexedValue, keySet);
+      this.orderedEntries.set(indexedValue, void 0);
+    }
+    this.indexedKeys.add(key);
+    this.updateTimestamp();
+  }
+  /**
+   * Removes a value from the index
+   */
+  remove(key, item) {
+    let indexedValue;
+    try {
+      indexedValue = this.evaluateIndexExpression(item);
+    } catch (error) {
+      console.warn(
+        `Failed to evaluate index expression for key ${key} during removal:`,
+        error
+      );
+      return;
+    }
+    if (this.valueMap.has(indexedValue)) {
+      const keySet = this.valueMap.get(indexedValue);
+      keySet.delete(key);
+      if (keySet.size === 0) {
+        this.valueMap.delete(indexedValue);
+        this.orderedEntries.delete(indexedValue);
+      }
+    }
+    this.indexedKeys.delete(key);
+    this.updateTimestamp();
+  }
+  /**
+   * Updates a value in the index
+   */
+  update(key, oldItem, newItem) {
+    this.remove(key, oldItem);
+    this.add(key, newItem);
+  }
+  /**
+   * Builds the index from a collection of entries
+   */
+  build(entries) {
+    this.clear();
+    for (const [key, item] of entries) {
+      this.add(key, item);
+    }
+  }
+  /**
+   * Clears all data from the index
+   */
+  clear() {
+    this.orderedEntries.clear();
+    this.valueMap.clear();
+    this.indexedKeys.clear();
+    this.updateTimestamp();
+  }
+  /**
+   * Performs a lookup operation
+   */
+  lookup(operation, value) {
+    const startTime = performance.now();
+    let result;
+    switch (operation) {
+      case `eq`:
+        result = this.equalityLookup(value);
+        break;
+      case `gt`:
+        result = this.rangeQuery({ from: value, fromInclusive: false });
+        break;
+      case `gte`:
+        result = this.rangeQuery({ from: value, fromInclusive: true });
+        break;
+      case `lt`:
+        result = this.rangeQuery({ to: value, toInclusive: false });
+        break;
+      case `lte`:
+        result = this.rangeQuery({ to: value, toInclusive: true });
+        break;
+      case `in`:
+        result = this.inArrayLookup(value);
+        break;
+      default:
+        throw new Error(`Operation ${operation} not supported by BTreeIndex`);
+    }
+    this.trackLookup(startTime);
+    return result;
+  }
+  /**
+   * Gets the number of indexed keys
+   */
+  get keyCount() {
+    return this.indexedKeys.size;
+  }
+  // Public methods for backward compatibility (used by tests)
+  /**
+   * Performs an equality lookup
+   */
+  equalityLookup(value) {
+    return new Set(this.valueMap.get(value) ?? []);
+  }
+  /**
+   * Performs a range query with options
+   * This is more efficient for compound queries like "WHERE a > 5 AND a < 10"
+   */
+  rangeQuery(options = {}) {
+    const { from, to, fromInclusive = true, toInclusive = true } = options;
+    const result = /* @__PURE__ */ new Set();
+    const fromKey = from ?? this.orderedEntries.minKey();
+    const toKey = to ?? this.orderedEntries.maxKey();
+    this.orderedEntries.forRange(
+      fromKey,
+      toKey,
+      toInclusive,
+      (indexedValue, _) => {
+        if (!fromInclusive && this.compareFn(indexedValue, from) === 0) {
+          return;
+        }
+        const keys = this.valueMap.get(indexedValue);
+        if (keys) {
+          keys.forEach((key) => result.add(key));
+        }
+      }
+    );
+    return result;
+  }
+  /**
+   * Performs an IN array lookup
+   */
+  inArrayLookup(values) {
+    const result = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const keys = this.valueMap.get(value);
+      if (keys) {
+        keys.forEach((key) => result.add(key));
+      }
+    }
+    return result;
+  }
+  // Getter methods for testing compatibility
+  get indexedKeysSet() {
+    return this.indexedKeys;
+  }
+  get orderedEntriesArray() {
+    return this.orderedEntries.keysArray().map((key) => [key, this.valueMap.get(key) ?? /* @__PURE__ */ new Set()]);
+  }
+  get valueMapData() {
+    return this.valueMap;
+  }
+}
+exports.BTreeIndex = BTreeIndex;
+//# sourceMappingURL=btree-index.cjs.map

package/dist/cjs/indexes/btree-index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"btree-index.cjs","sources":["../../../src/indexes/btree-index.ts"],"sourcesContent":["import { ascComparator } from \"../utils/comparison.js\"\nimport { BTree } from \"../utils/btree.js\"\nimport { BaseIndex } from \"./base-index.js\"\nimport type { BasicExpression } from \"../query/ir.js\"\nimport type { IndexOperation } from \"./base-index.js\"\n\n/**\n * Options for Ordered index\n */\nexport interface BTreeIndexOptions {\n  compareFn?: (a: any, b: any) => number\n}\n\n/**\n * Options for range queries\n */\nexport interface RangeQueryOptions {\n  from?: any\n  to?: any\n  fromInclusive?: boolean\n  toInclusive?: boolean\n}\n\n/**\n * B+Tree index for sorted data with range queries\n * This maintains items in sorted order and provides efficient range operations\n */\nexport class BTreeIndex<\n  TKey extends string | number = string | number,\n> extends BaseIndex<TKey> {\n  public readonly supportedOperations = new Set<IndexOperation>([\n    `eq`,\n    `gt`,\n    `gte`,\n    `lt`,\n    `lte`,\n    `in`,\n  ])\n\n  // Internal data structures - private to hide implementation details\n  // The `orderedEntries` B+ tree is used for efficient range queries\n  // The `valueMap` is used for O(1) lookups of PKs by indexed value\n  private orderedEntries: BTree<any, undefined> // we don't associate values with the keys of the B+ tree (the keys are indexed values)\n  private valueMap = new Map<any, Set<TKey>>() // instead we store a mapping of indexed values to a set of PKs\n  private indexedKeys = new Set<TKey>()\n  private compareFn: (a: any, b: any) => number = ascComparator\n\n  constructor(\n    id: number,\n    expression: BasicExpression,\n    name?: string,\n    options?: any\n  ) {\n    super(id, expression, name, options)\n    this.compareFn = options?.compareFn ?? ascComparator\n    this.orderedEntries = new BTree(this.compareFn)\n  }\n\n  protected initialize(_options?: BTreeIndexOptions): void {}\n\n  /**\n   * Adds a value to the index\n   */\n  add(key: TKey, item: any): void {\n    let indexedValue: any\n    try {\n      indexedValue = this.evaluateIndexExpression(item)\n    } catch (error) {\n      throw new Error(\n        `Failed to evaluate index expression for key ${key}: ${error}`\n      )\n    }\n\n    // Check if this value already exists\n    if (this.valueMap.has(indexedValue)) {\n      // Add to existing set\n      this.valueMap.get(indexedValue)!.add(key)\n    } else {\n      // Create new set for this value\n      const keySet = new Set<TKey>([key])\n      this.valueMap.set(indexedValue, keySet)\n      this.orderedEntries.set(indexedValue, undefined)\n    }\n\n    this.indexedKeys.add(key)\n    this.updateTimestamp()\n  }\n\n  /**\n   * Removes a value from the index\n   */\n  remove(key: TKey, item: any): void {\n    let indexedValue: any\n    try {\n      indexedValue = this.evaluateIndexExpression(item)\n    } catch (error) {\n      console.warn(\n        `Failed to evaluate index expression for key ${key} during removal:`,\n        error\n      )\n      return\n    }\n\n    if (this.valueMap.has(indexedValue)) {\n      const keySet = this.valueMap.get(indexedValue)!\n      keySet.delete(key)\n\n      // If set is now empty, remove the entry entirely\n      if (keySet.size === 0) {\n        this.valueMap.delete(indexedValue)\n\n        // Remove from ordered entries\n        this.orderedEntries.delete(indexedValue)\n      }\n    }\n\n    this.indexedKeys.delete(key)\n    this.updateTimestamp()\n  }\n\n  /**\n   * Updates a value in the index\n   */\n  update(key: TKey, oldItem: any, newItem: any): void {\n    this.remove(key, oldItem)\n    this.add(key, newItem)\n  }\n\n  /**\n   * Builds the index from a collection of entries\n   */\n  build(entries: Iterable<[TKey, any]>): void {\n    this.clear()\n\n    for (const [key, item] of entries) {\n      this.add(key, item)\n    }\n  }\n\n  /**\n   * Clears all data from the index\n   */\n  clear(): void {\n    this.orderedEntries.clear()\n    this.valueMap.clear()\n    this.indexedKeys.clear()\n    this.updateTimestamp()\n  }\n\n  /**\n   * Performs a lookup operation\n   */\n  lookup(operation: IndexOperation, value: any): Set<TKey> {\n    const startTime = performance.now()\n\n    let result: Set<TKey>\n\n    switch (operation) {\n      case `eq`:\n        result = this.equalityLookup(value)\n        break\n      case `gt`:\n        result = this.rangeQuery({ from: value, fromInclusive: false })\n        break\n      case `gte`:\n        result = this.rangeQuery({ from: value, fromInclusive: true })\n        break\n      case `lt`:\n        result = this.rangeQuery({ to: value, toInclusive: false })\n        break\n      case `lte`:\n        result = this.rangeQuery({ to: value, toInclusive: true })\n        break\n      case `in`:\n        result = this.inArrayLookup(value)\n        break\n      default:\n        throw new Error(`Operation ${operation} not supported by BTreeIndex`)\n    }\n\n    this.trackLookup(startTime)\n    return result\n  }\n\n  /**\n   * Gets the number of indexed keys\n   */\n  get keyCount(): number {\n    return this.indexedKeys.size\n  }\n\n  // Public methods for backward compatibility (used by tests)\n\n  /**\n   * Performs an equality lookup\n   */\n  equalityLookup(value: any): Set<TKey> {\n    return new Set(this.valueMap.get(value) ?? [])\n  }\n\n  /**\n   * Performs a range query with options\n   * This is more efficient for compound queries like \"WHERE a > 5 AND a < 10\"\n   */\n  rangeQuery(options: RangeQueryOptions = {}): Set<TKey> {\n    const { from, to, fromInclusive = true, toInclusive = true } = options\n    const result = new Set<TKey>()\n\n    const fromKey = from ?? this.orderedEntries.minKey()\n    const toKey = to ?? this.orderedEntries.maxKey()\n\n    this.orderedEntries.forRange(\n      fromKey,\n      toKey,\n      toInclusive,\n      (indexedValue, _) => {\n        if (!fromInclusive && this.compareFn(indexedValue, from) === 0) {\n          // the B+ tree `forRange` method does not support exclusive lower bounds\n          // so we need to exclude it manually\n          return\n        }\n\n        const keys = this.valueMap.get(indexedValue)\n        if (keys) {\n          keys.forEach((key) => result.add(key))\n        }\n      }\n    )\n\n    return result\n  }\n\n  /**\n   * Performs an IN array lookup\n   */\n  inArrayLookup(values: Array<any>): Set<TKey> {\n    const result = new Set<TKey>()\n\n    for (const value of values) {\n      const keys = this.valueMap.get(value)\n      if (keys) {\n        keys.forEach((key) => result.add(key))\n      }\n    }\n\n    return result\n  }\n\n  // Getter methods for testing compatibility\n  get indexedKeysSet(): Set<TKey> {\n    return this.indexedKeys\n  }\n\n  get orderedEntriesArray(): Array<[any, Set<TKey>]> {\n    return this.orderedEntries\n      .keysArray()\n      .map((key) => [key, this.valueMap.get(key) ?? new Set()])\n  }\n\n  get valueMapData(): Map<any, Set<TKey>> {\n    return this.valueMap\n  }\n}\n"],"names":["BaseIndex","ascComparator","BTree"],"mappings":"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"}

package/dist/cjs/indexes/btree-index.d.cts

@@ -0,0 +1,74 @@
+import { BaseIndex, IndexOperation } from './base-index.js';
+import { BasicExpression } from '../query/ir.js';
+/**
+ * Options for Ordered index
+ */
+export interface BTreeIndexOptions {
+    compareFn?: (a: any, b: any) => number;
+}
+/**
+ * Options for range queries
+ */
+export interface RangeQueryOptions {
+    from?: any;
+    to?: any;
+    fromInclusive?: boolean;
+    toInclusive?: boolean;
+}
+/**
+ * B+Tree index for sorted data with range queries
+ * This maintains items in sorted order and provides efficient range operations
+ */
+export declare class BTreeIndex<TKey extends string | number = string | number> extends BaseIndex<TKey> {
+    readonly supportedOperations: Set<"eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "ilike">;
+    private orderedEntries;
+    private valueMap;
+    private indexedKeys;
+    private compareFn;
+    constructor(id: number, expression: BasicExpression, name?: string, options?: any);
+    protected initialize(_options?: BTreeIndexOptions): void;
+    /**
+     * Adds a value to the index
+     */
+    add(key: TKey, item: any): void;
+    /**
+     * Removes a value from the index
+     */
+    remove(key: TKey, item: any): void;
+    /**
+     * Updates a value in the index
+     */
+    update(key: TKey, oldItem: any, newItem: any): void;
+    /**
+     * Builds the index from a collection of entries
+     */
+    build(entries: Iterable<[TKey, any]>): void;
+    /**
+     * Clears all data from the index
+     */
+    clear(): void;
+    /**
+     * Performs a lookup operation
+     */
+    lookup(operation: IndexOperation, value: any): Set<TKey>;
+    /**
+     * Gets the number of indexed keys
+     */
+    get keyCount(): number;
+    /**
+     * Performs an equality lookup
+     */
+    equalityLookup(value: any): Set<TKey>;
+    /**
+     * Performs a range query with options
+     * This is more efficient for compound queries like "WHERE a > 5 AND a < 10"
+     */
+    rangeQuery(options?: RangeQueryOptions): Set<TKey>;
+    /**
+     * Performs an IN array lookup
+     */
+    inArrayLookup(values: Array<any>): Set<TKey>;
+    get indexedKeysSet(): Set<TKey>;
+    get orderedEntriesArray(): Array<[any, Set<TKey>]>;
+    get valueMapData(): Map<any, Set<TKey>>;
+}

package/dist/cjs/indexes/index-options.d.cts

@@ -0,0 +1,13 @@
+import { IndexConstructor, IndexResolver } from './base-index.js';
+/**
+ * Enhanced index options that support both sync and async resolvers
+ */
+export interface IndexOptions<TResolver extends IndexResolver = IndexResolver> {
+    name?: string;
+    indexType?: TResolver;
+    options?: TResolver extends IndexConstructor<any> ? TResolver extends new (id: string, expr: any, name?: string, options?: infer O) => any ? O : never : TResolver extends () => Promise<infer TCtor> ? TCtor extends new (id: string, expr: any, name?: string, options?: infer O) => any ? O : never : never;
+}
+/**
+ * Utility type to extract the constructed index type from a resolver
+ */
+export type ResolvedIndexType<TResolver extends IndexResolver> = TResolver extends IndexConstructor<any> ? InstanceType<TResolver> : TResolver extends () => Promise<IndexConstructor<any>> ? TResolver extends () => Promise<infer TCtor> ? TCtor extends IndexConstructor<any> ? InstanceType<TCtor> : never : never : never;

package/dist/cjs/indexes/lazy-index.cjs

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function isConstructor(resolver) {
+  return typeof resolver === `function` && resolver.prototype !== void 0 && resolver.prototype.constructor === resolver;
+}
+async function resolveIndexConstructor(resolver) {
+  if (isConstructor(resolver)) {
+    return resolver;
+  } else {
+    return await resolver();
+  }
+}
+class LazyIndexWrapper {
+  constructor(id, expression, name, resolver, options, collectionEntries) {
+    this.id = id;
+    this.expression = expression;
+    this.name = name;
+    this.resolver = resolver;
+    this.options = options;
+    this.collectionEntries = collectionEntries;
+    this.indexPromise = null;
+    this.resolvedIndex = null;
+    if (isConstructor(this.resolver)) {
+      this.resolvedIndex = new this.resolver(
+        this.id,
+        this.expression,
+        this.name,
+        this.options
+      );
+      if (this.collectionEntries) {
+        this.resolvedIndex.build(this.collectionEntries);
+      }
+    }
+  }
+  /**
+   * Resolve the actual index
+   */
+  async resolve() {
+    if (this.resolvedIndex) {
+      return this.resolvedIndex;
+    }
+    if (!this.indexPromise) {
+      this.indexPromise = this.createIndex();
+    }
+    this.resolvedIndex = await this.indexPromise;
+    return this.resolvedIndex;
+  }
+  /**
+   * Check if already resolved
+   */
+  isResolved() {
+    return this.resolvedIndex !== null;
+  }
+  /**
+   * Get resolved index (throws if not ready)
+   */
+  getResolved() {
+    if (!this.resolvedIndex) {
+      throw new Error(
+        `Index ${this.id} has not been resolved yet. Ensure collection is synced.`
+      );
+    }
+    return this.resolvedIndex;
+  }
+  /**
+   * Get the index ID
+   */
+  getId() {
+    return this.id;
+  }
+  /**
+   * Get the index name
+   */
+  getName() {
+    return this.name;
+  }
+  /**
+   * Get the index expression
+   */
+  getExpression() {
+    return this.expression;
+  }
+  async createIndex() {
+    const IndexClass = await resolveIndexConstructor(this.resolver);
+    return new IndexClass(this.id, this.expression, this.name, this.options);
+  }
+}
+class IndexProxy {
+  constructor(indexId, lazyIndex) {
+    this.indexId = indexId;
+    this.lazyIndex = lazyIndex;
+  }
+  /**
+   * Get the resolved index (throws if not ready)
+   */
+  get index() {
+    return this.lazyIndex.getResolved();
+  }
+  /**
+   * Check if index is ready
+   */
+  get isReady() {
+    return this.lazyIndex.isResolved();
+  }
+  /**
+   * Wait for index to be ready
+   */
+  async whenReady() {
+    return await this.lazyIndex.resolve();
+  }
+  /**
+   * Get the index ID
+   */
+  get id() {
+    return this.indexId;
+  }
+  /**
+   * Get the index name (throws if not ready)
+   */
+  get name() {
+    if (this.isReady) {
+      return this.index.name;
+    }
+    return this.lazyIndex.getName();
+  }
+  /**
+   * Get the index expression (available immediately)
+   */
+  get expression() {
+    return this.lazyIndex.getExpression();
+  }
+  /**
+   * Check if index supports an operation (throws if not ready)
+   */
+  supports(operation) {
+    return this.index.supports(operation);
+  }
+  /**
+   * Get index statistics (throws if not ready)
+   */
+  getStats() {
+    return this.index.getStats();
+  }
+  /**
+   * Check if index matches a field path (available immediately)
+   */
+  matchesField(fieldPath) {
+    const expr = this.expression;
+    return expr.type === `ref` && expr.path.length === fieldPath.length && expr.path.every((part, i) => part === fieldPath[i]);
+  }
+  /**
+   * Get the key count (throws if not ready)
+   */
+  get keyCount() {
+    return this.index.keyCount;
+  }
+  // Test compatibility properties - delegate to resolved index
+  get indexedKeysSet() {
+    const resolved = this.index;
+    return resolved.indexedKeysSet;
+  }
+  get orderedEntriesArray() {
+    const resolved = this.index;
+    return resolved.orderedEntriesArray;
+  }
+  get valueMapData() {
+    const resolved = this.index;
+    return resolved.valueMapData;
+  }
+  // BTreeIndex compatibility methods
+  equalityLookup(value) {
+    var _a;
+    const resolved = this.index;
+    return ((_a = resolved.equalityLookup) == null ? void 0 : _a.call(resolved, value)) ?? /* @__PURE__ */ new Set();
+  }
+  rangeQuery(options) {
+    var _a;
+    const resolved = this.index;
+    return ((_a = resolved.rangeQuery) == null ? void 0 : _a.call(resolved, options)) ?? /* @__PURE__ */ new Set();
+  }
+  inArrayLookup(values) {
+    var _a;
+    const resolved = this.index;
+    return ((_a = resolved.inArrayLookup) == null ? void 0 : _a.call(resolved, values)) ?? /* @__PURE__ */ new Set();
+  }
+  // Internal method for the collection to get the lazy wrapper
+  _getLazyWrapper() {
+    return this.lazyIndex;
+  }
+}
+exports.IndexProxy = IndexProxy;
+exports.LazyIndexWrapper = LazyIndexWrapper;
+//# sourceMappingURL=lazy-index.cjs.map

package/dist/cjs/indexes/lazy-index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-index.cjs","sources":["../../../src/indexes/lazy-index.ts"],"sourcesContent":["import type {\n  BaseIndex,\n  IndexConstructor,\n  IndexResolver,\n} from \"./base-index.js\"\nimport type { BasicExpression } from \"../query/ir.js\"\n\n/**\n * Utility to determine if a resolver is a constructor or async loader\n */\nfunction isConstructor<TKey extends string | number>(\n  resolver: IndexResolver<TKey>\n): resolver is IndexConstructor<TKey> {\n  // Check if it's a function with a prototype (constructor)\n  return (\n    typeof resolver === `function` &&\n    resolver.prototype !== undefined &&\n    resolver.prototype.constructor === resolver\n  )\n}\n\n/**\n * Resolve index constructor from resolver\n */\nasync function resolveIndexConstructor<TKey extends string | number>(\n  resolver: IndexResolver<TKey>\n): Promise<IndexConstructor<TKey>> {\n  if (isConstructor(resolver)) {\n    return resolver\n  } else {\n    // It's an async loader function\n    return await resolver()\n  }\n}\n\n/**\n * Wrapper that defers index creation until first sync\n */\nexport class LazyIndexWrapper<TKey extends string | number = string | number> {\n  private indexPromise: Promise<BaseIndex<TKey>> | null = null\n  private resolvedIndex: BaseIndex<TKey> | null = null\n\n  constructor(\n    private id: number,\n    private expression: BasicExpression,\n    private name: string | undefined,\n    private resolver: IndexResolver<TKey>,\n    private options: any,\n    private collectionEntries?: Iterable<[TKey, any]>\n  ) {\n    // For synchronous constructors, resolve immediately\n    if (isConstructor(this.resolver)) {\n      this.resolvedIndex = new this.resolver(\n        this.id,\n        this.expression,\n        this.name,\n        this.options\n      )\n      // Build with initial data if provided\n      if (this.collectionEntries) {\n        this.resolvedIndex.build(this.collectionEntries)\n      }\n    }\n  }\n\n  /**\n   * Resolve the actual index\n   */\n  async resolve(): Promise<BaseIndex<TKey>> {\n    if (this.resolvedIndex) {\n      return this.resolvedIndex\n    }\n\n    if (!this.indexPromise) {\n      this.indexPromise = this.createIndex()\n    }\n\n    this.resolvedIndex = await this.indexPromise\n    return this.resolvedIndex\n  }\n\n  /**\n   * Check if already resolved\n   */\n  isResolved(): boolean {\n    return this.resolvedIndex !== null\n  }\n\n  /**\n   * Get resolved index (throws if not ready)\n   */\n  getResolved(): BaseIndex<TKey> {\n    if (!this.resolvedIndex) {\n      throw new Error(\n        `Index ${this.id} has not been resolved yet. Ensure collection is synced.`\n      )\n    }\n    return this.resolvedIndex\n  }\n\n  /**\n   * Get the index ID\n   */\n  getId(): number {\n    return this.id\n  }\n\n  /**\n   * Get the index name\n   */\n  getName(): string | undefined {\n    return this.name\n  }\n\n  /**\n   * Get the index expression\n   */\n  getExpression(): BasicExpression {\n    return this.expression\n  }\n\n  private async createIndex(): Promise<BaseIndex<TKey>> {\n    const IndexClass = await resolveIndexConstructor(this.resolver)\n    return new IndexClass(this.id, this.expression, this.name, this.options)\n  }\n}\n\n/**\n * Proxy that provides synchronous interface while index loads asynchronously\n */\nexport class IndexProxy<TKey extends string | number = string | number> {\n  constructor(\n    private indexId: number,\n    private lazyIndex: LazyIndexWrapper<TKey>\n  ) {}\n\n  /**\n   * Get the resolved index (throws if not ready)\n   */\n  get index(): BaseIndex<TKey> {\n    return this.lazyIndex.getResolved()\n  }\n\n  /**\n   * Check if index is ready\n   */\n  get isReady(): boolean {\n    return this.lazyIndex.isResolved()\n  }\n\n  /**\n   * Wait for index to be ready\n   */\n  async whenReady(): Promise<BaseIndex<TKey>> {\n    return await this.lazyIndex.resolve()\n  }\n\n  /**\n   * Get the index ID\n   */\n  get id(): number {\n    return this.indexId\n  }\n\n  /**\n   * Get the index name (throws if not ready)\n   */\n  get name(): string | undefined {\n    if (this.isReady) {\n      return this.index.name\n    }\n    return this.lazyIndex.getName()\n  }\n\n  /**\n   * Get the index expression (available immediately)\n   */\n  get expression(): BasicExpression {\n    return this.lazyIndex.getExpression()\n  }\n\n  /**\n   * Check if index supports an operation (throws if not ready)\n   */\n  supports(operation: any): boolean {\n    return this.index.supports(operation)\n  }\n\n  /**\n   * Get index statistics (throws if not ready)\n   */\n  getStats() {\n    return this.index.getStats()\n  }\n\n  /**\n   * Check if index matches a field path (available immediately)\n   */\n  matchesField(fieldPath: Array<string>): boolean {\n    const expr = this.expression\n    return (\n      expr.type === `ref` &&\n      expr.path.length === fieldPath.length &&\n      expr.path.every((part, i) => part === fieldPath[i])\n    )\n  }\n\n  /**\n   * Get the key count (throws if not ready)\n   */\n  get keyCount(): number {\n    return this.index.keyCount\n  }\n\n  // Test compatibility properties - delegate to resolved index\n  get indexedKeysSet(): Set<TKey> {\n    const resolved = this.index as any\n    return resolved.indexedKeysSet\n  }\n\n  get orderedEntriesArray(): Array<[any, Set<TKey>]> {\n    const resolved = this.index as any\n    return resolved.orderedEntriesArray\n  }\n\n  get valueMapData(): Map<any, Set<TKey>> {\n    const resolved = this.index as any\n    return resolved.valueMapData\n  }\n\n  // BTreeIndex compatibility methods\n  equalityLookup(value: any): Set<TKey> {\n    const resolved = this.index as any\n    return resolved.equalityLookup?.(value) ?? new Set()\n  }\n\n  rangeQuery(options: any): Set<TKey> {\n    const resolved = this.index as any\n    return resolved.rangeQuery?.(options) ?? new Set()\n  }\n\n  inArrayLookup(values: Array<any>): Set<TKey> {\n    const resolved = this.index as any\n    return resolved.inArrayLookup?.(values) ?? new Set()\n  }\n\n  // Internal method for the collection to get the lazy wrapper\n  _getLazyWrapper(): LazyIndexWrapper<TKey> {\n    return this.lazyIndex\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/indexes/lazy-index.d.cts

@@ -0,0 +1,96 @@
+import { BaseIndex, IndexResolver } from './base-index.js';
+import { BasicExpression } from '../query/ir.js';
+/**
+ * Wrapper that defers index creation until first sync
+ */
+export declare class LazyIndexWrapper<TKey extends string | number = string | number> {
+    private id;
+    private expression;
+    private name;
+    private resolver;
+    private options;
+    private collectionEntries?;
+    private indexPromise;
+    private resolvedIndex;
+    constructor(id: number, expression: BasicExpression, name: string | undefined, resolver: IndexResolver<TKey>, options: any, collectionEntries?: Iterable<[TKey, any]> | undefined);
+    /**
+     * Resolve the actual index
+     */
+    resolve(): Promise<BaseIndex<TKey>>;
+    /**
+     * Check if already resolved
+     */
+    isResolved(): boolean;
+    /**
+     * Get resolved index (throws if not ready)
+     */
+    getResolved(): BaseIndex<TKey>;
+    /**
+     * Get the index ID
+     */
+    getId(): number;
+    /**
+     * Get the index name
+     */
+    getName(): string | undefined;
+    /**
+     * Get the index expression
+     */
+    getExpression(): BasicExpression;
+    private createIndex;
+}
+/**
+ * Proxy that provides synchronous interface while index loads asynchronously
+ */
+export declare class IndexProxy<TKey extends string | number = string | number> {
+    private indexId;
+    private lazyIndex;
+    constructor(indexId: number, lazyIndex: LazyIndexWrapper<TKey>);
+    /**
+     * Get the resolved index (throws if not ready)
+     */
+    get index(): BaseIndex<TKey>;
+    /**
+     * Check if index is ready
+     */
+    get isReady(): boolean;
+    /**
+     * Wait for index to be ready
+     */
+    whenReady(): Promise<BaseIndex<TKey>>;
+    /**
+     * Get the index ID
+     */
+    get id(): number;
+    /**
+     * Get the index name (throws if not ready)
+     */
+    get name(): string | undefined;
+    /**
+     * Get the index expression (available immediately)
+     */
+    get expression(): BasicExpression;
+    /**
+     * Check if index supports an operation (throws if not ready)
+     */
+    supports(operation: any): boolean;
+    /**
+     * Get index statistics (throws if not ready)
+     */
+    getStats(): import('./base-index.js').IndexStats;
+    /**
+     * Check if index matches a field path (available immediately)
+     */
+    matchesField(fieldPath: Array<string>): boolean;
+    /**
+     * Get the key count (throws if not ready)
+     */
+    get keyCount(): number;
+    get indexedKeysSet(): Set<TKey>;
+    get orderedEntriesArray(): Array<[any, Set<TKey>]>;
+    get valueMapData(): Map<any, Set<TKey>>;
+    equalityLookup(value: any): Set<TKey>;
+    rangeQuery(options: any): Set<TKey>;
+    inArrayLookup(values: Array<any>): Set<TKey>;
+    _getLazyWrapper(): LazyIndexWrapper<TKey>;
+}

package/dist/cjs/local-storage.cjs

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const errors = require("./errors.cjs");
 function validateJsonSerializable(value, operation) {
   try {
     JSON.stringify(value);
   } catch (error) {
-    throw new Error(
-      `Cannot ${operation} item because it cannot be JSON serialized: ${error instanceof Error ? error.message : String(error)}`
+    throw new errors.SerializationError(
+      operation,
+      error instanceof Error ? error.message : String(error)
     );
   }
 }
@@ -14,19 +16,15 @@ function generateUuid() {
 }
 function localStorageCollectionOptions(config) {
   if (!config.storageKey) {
-    throw new Error(`[LocalStorageCollection] storageKey must be provided.`);
+    throw new errors.StorageKeyRequiredError();
   }
   const storage = config.storage || (typeof window !== `undefined` ? window.localStorage : null);
   if (!storage) {
-    throw new Error(
-      `[LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available.`
-    );
+    throw new errors.NoStorageAvailableError();
   }
   const storageEventApi = config.storageEventApi || (typeof window !== `undefined` ? window : null);
   if (!storageEventApi) {
-    throw new Error(
-      `[LocalStorageCollection] No storage event API available. Please provide a storageEventApi option or ensure window is available.`
-    );
+    throw new errors.NoStorageEventApiError();
   }
   const lastKnownData = /* @__PURE__ */ new Map();
   const sync = createLocalStorageSync(
@@ -167,15 +165,11 @@ function loadFromStorage(storageKey, storage) {
           const storedItem = value;
           dataMap.set(key, storedItem);
         } else {
-          throw new Error(
-            `[LocalStorageCollection] Invalid data format in storage key "${storageKey}" for key "${key}".`
-          );
+          throw new errors.InvalidStorageDataFormatError(storageKey, key);
         }
       });
     } else {
-      throw new Error(
-        `[LocalStorageCollection] Invalid data format in storage key "${storageKey}". Expected object format.`
-      );
+      throw new errors.InvalidStorageObjectFormatError(storageKey);
     }
     return dataMap;
   } catch (error) {