@tanstack/db 0.0.27 → 0.0.30

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;"}

package/dist/esm/indexes/auto-index.d.ts

@@ -0,0 +1,9 @@
+import { BasicExpression } from '../query/ir.js';
+import { CollectionImpl } from '../collection.js';
+export interface AutoIndexConfig {
+    autoIndex?: `off` | `eager`;
+}
+/**
+ * Analyzes a where expression and creates indexes for all simple operations on single fields
+ */
+export declare function ensureIndexForExpression<T extends Record<string, any>, TKey extends string | number>(expression: BasicExpression, collection: CollectionImpl<T, TKey, any, any, any>): void;

package/dist/esm/indexes/auto-index.js

@@ -0,0 +1,64 @@
+import { BTreeIndex } from "./btree-index.js";
+function ensureIndexForExpression(expression, collection) {
+  if (collection.config.autoIndex !== `eager`) {
+    return;
+  }
+  if (collection.status === `loading` || collection.status === `initialCommit`) {
+    return;
+  }
+  const indexableExpressions = extractIndexableExpressions(expression);
+  for (const { fieldName, fieldPath } of indexableExpressions) {
+    const existingIndex = Array.from(collection.indexes.values()).find(
+      (index) => index.matchesField(fieldPath)
+    );
+    if (existingIndex) {
+      continue;
+    }
+    try {
+      collection.createIndex((row) => row[fieldName], {
+        name: `auto_${fieldName}`,
+        indexType: BTreeIndex
+      });
+    } catch (error) {
+      console.warn(
+        `Failed to create auto-index for field "${fieldName}":`,
+        error
+      );
+    }
+  }
+}
+function extractIndexableExpressions(expression) {
+  const results = [];
+  function extractFromExpression(expr) {
+    if (expr.type !== `func`) {
+      return;
+    }
+    const func = expr;
+    if (func.name === `and`) {
+      for (const arg of func.args) {
+        extractFromExpression(arg);
+      }
+      return;
+    }
+    const supportedOperations = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`];
+    if (!supportedOperations.includes(func.name)) {
+      return;
+    }
+    if (func.args.length < 1 || func.args[0].type !== `ref`) {
+      return;
+    }
+    const fieldRef = func.args[0];
+    const fieldPath = fieldRef.path;
+    if (fieldPath.length !== 1) {
+      return;
+    }
+    const fieldName = fieldPath[0];
+    results.push({ fieldName, fieldPath });
+  }
+  extractFromExpression(expression);
+  return results;
+}
+export {
+  ensureIndexForExpression
+};
+//# sourceMappingURL=auto-index.js.map

package/dist/esm/indexes/auto-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-index.js","sources":["../../../src/indexes/auto-index.ts"],"sourcesContent":["import { BTreeIndex } from \"./btree-index\"\nimport type { BasicExpression } from \"../query/ir\"\nimport type { CollectionImpl } from \"../collection\"\n\nexport interface AutoIndexConfig {\n  autoIndex?: `off` | `eager`\n}\n\n/**\n * Analyzes a where expression and creates indexes for all simple operations on single fields\n */\nexport function ensureIndexForExpression<\n  T extends Record<string, any>,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionImpl<T, TKey, any, any, any>\n): void {\n  // Only proceed if auto-indexing is enabled\n  if (collection.config.autoIndex !== `eager`) {\n    return\n  }\n\n  // Don't auto-index during sync operations\n  if (\n    collection.status === `loading` ||\n    collection.status === `initialCommit`\n  ) {\n    return\n  }\n\n  // Extract all indexable expressions and create indexes for them\n  const indexableExpressions = extractIndexableExpressions(expression)\n\n  for (const { fieldName, fieldPath } of indexableExpressions) {\n    // Check if we already have an index for this field\n    const existingIndex = Array.from(collection.indexes.values()).find(\n      (index) => index.matchesField(fieldPath)\n    )\n\n    if (existingIndex) {\n      continue // Index already exists\n    }\n\n    // Create a new index for this field using the collection's createIndex method\n    try {\n      collection.createIndex((row) => (row as any)[fieldName], {\n        name: `auto_${fieldName}`,\n        indexType: BTreeIndex,\n      })\n    } catch (error) {\n      console.warn(\n        `Failed to create auto-index for field \"${fieldName}\":`,\n        error\n      )\n    }\n  }\n}\n\n/**\n * Extracts all indexable expressions from a where expression\n */\nfunction extractIndexableExpressions(\n  expression: BasicExpression\n): Array<{ fieldName: string; fieldPath: Array<string> }> {\n  const results: Array<{ fieldName: string; fieldPath: Array<string> }> = []\n\n  function extractFromExpression(expr: BasicExpression): void {\n    if (expr.type !== `func`) {\n      return\n    }\n\n    const func = expr as any\n\n    // Handle 'and' expressions by recursively processing all arguments\n    if (func.name === `and`) {\n      for (const arg of func.args) {\n        extractFromExpression(arg)\n      }\n      return\n    }\n\n    // Check if this is a supported operation\n    const supportedOperations = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`]\n    if (!supportedOperations.includes(func.name)) {\n      return\n    }\n\n    // Check if the first argument is a property reference (single field)\n    if (func.args.length < 1 || func.args[0].type !== `ref`) {\n      return\n    }\n\n    const fieldRef = func.args[0]\n    const fieldPath = fieldRef.path\n\n    // Skip if it's not a simple field (e.g., nested properties or array access)\n    if (fieldPath.length !== 1) {\n      return\n    }\n\n    const fieldName = fieldPath[0]\n    results.push({ fieldName, fieldPath })\n  }\n\n  extractFromExpression(expression)\n  return results\n}\n"],"names":[],"mappings":";AAWO,SAAS,yBAId,YACA,YACM;AAEN,MAAI,WAAW,OAAO,cAAc,SAAS;AAC3C;AAAA,EACF;AAGA,MACE,WAAW,WAAW,aACtB,WAAW,WAAW,iBACtB;AACA;AAAA,EACF;AAGA,QAAM,uBAAuB,4BAA4B,UAAU;AAEnE,aAAW,EAAE,WAAW,UAAA,KAAe,sBAAsB;AAE3D,UAAM,gBAAgB,MAAM,KAAK,WAAW,QAAQ,OAAA,CAAQ,EAAE;AAAA,MAC5D,CAAC,UAAU,MAAM,aAAa,SAAS;AAAA,IAAA;AAGzC,QAAI,eAAe;AACjB;AAAA,IACF;AAGA,QAAI;AACF,iBAAW,YAAY,CAAC,QAAS,IAAY,SAAS,GAAG;AAAA,QACvD,MAAM,QAAQ,SAAS;AAAA,QACvB,WAAW;AAAA,MAAA,CACZ;AAAA,IACH,SAAS,OAAO;AACd,cAAQ;AAAA,QACN,0CAA0C,SAAS;AAAA,QACnD;AAAA,MAAA;AAAA,IAEJ;AAAA,EACF;AACF;AAKA,SAAS,4BACP,YACwD;AACxD,QAAM,UAAkE,CAAA;AAExE,WAAS,sBAAsB,MAA6B;AAC1D,QAAI,KAAK,SAAS,QAAQ;AACxB;AAAA,IACF;AAEA,UAAM,OAAO;AAGb,QAAI,KAAK,SAAS,OAAO;AACvB,iBAAW,OAAO,KAAK,MAAM;AAC3B,8BAAsB,GAAG;AAAA,MAC3B;AACA;AAAA,IACF;AAGA,UAAM,sBAAsB,CAAC,MAAM,MAAM,OAAO,MAAM,OAAO,IAAI;AACjE,QAAI,CAAC,oBAAoB,SAAS,KAAK,IAAI,GAAG;AAC5C;AAAA,IACF;AAGA,QAAI,KAAK,KAAK,SAAS,KAAK,KAAK,KAAK,CAAC,EAAE,SAAS,OAAO;AACvD;AAAA,IACF;AAEA,UAAM,WAAW,KAAK,KAAK,CAAC;AAC5B,UAAM,YAAY,SAAS;AAG3B,QAAI,UAAU,WAAW,GAAG;AAC1B;AAAA,IACF;AAEA,UAAM,YAAY,UAAU,CAAC;AAC7B,YAAQ,KAAK,EAAE,WAAW,UAAA,CAAW;AAAA,EACvC;AAEA,wBAAsB,UAAU;AAChC,SAAO;AACT;"}

package/dist/esm/indexes/base-index.d.ts

@@ -0,0 +1,54 @@
+import { comparisonFunctions } from '../query/builder/functions.js';
+import { BasicExpression } from '../query/ir.js';
+/**
+ * Operations that indexes can support, imported from available comparison functions
+ */
+export declare const IndexOperation: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"];
+/**
+ * Type for index operation values
+ */
+export type IndexOperation = (typeof comparisonFunctions)[number];
+/**
+ * Statistics about index usage and performance
+ */
+export interface IndexStats {
+    readonly entryCount: number;
+    readonly lookupCount: number;
+    readonly averageLookupTime: number;
+    readonly lastUpdated: Date;
+}
+/**
+ * Base abstract class that all index types extend
+ */
+export declare abstract class BaseIndex<TKey extends string | number = string | number> {
+    readonly id: number;
+    readonly name?: string;
+    readonly expression: BasicExpression;
+    abstract readonly supportedOperations: Set<IndexOperation>;
+    protected lookupCount: number;
+    protected totalLookupTime: number;
+    protected lastUpdated: Date;
+    constructor(id: number, expression: BasicExpression, name?: string, options?: any);
+    abstract add(key: TKey, item: any): void;
+    abstract remove(key: TKey, item: any): void;
+    abstract update(key: TKey, oldItem: any, newItem: any): void;
+    abstract build(entries: Iterable<[TKey, any]>): void;
+    abstract clear(): void;
+    abstract lookup(operation: IndexOperation, value: any): Set<TKey>;
+    abstract get keyCount(): number;
+    supports(operation: IndexOperation): boolean;
+    matchesField(fieldPath: Array<string>): boolean;
+    getStats(): IndexStats;
+    protected abstract initialize(options?: any): void;
+    protected evaluateIndexExpression(item: any): any;
+    protected trackLookup(startTime: number): void;
+    protected updateTimestamp(): void;
+}
+/**
+ * Type for index constructor
+ */
+export type IndexConstructor<TKey extends string | number = string | number> = new (id: number, expression: BasicExpression, name?: string, options?: any) => BaseIndex<TKey>;
+/**
+ * Index resolver can be either a class constructor or async loader
+ */
+export type IndexResolver<TKey extends string | number = string | number> = IndexConstructor<TKey> | (() => Promise<IndexConstructor<TKey>>);

package/dist/esm/indexes/base-index.js

@@ -0,0 +1,46 @@
+import { compileSingleRowExpression } from "../query/compiler/evaluators.js";
+import { comparisonFunctions } from "../query/builder/functions.js";
+const IndexOperation = comparisonFunctions;
+class BaseIndex {
+  constructor(id, expression, name, options) {
+    this.lookupCount = 0;
+    this.totalLookupTime = 0;
+    this.lastUpdated = /* @__PURE__ */ new Date();
+    this.id = id;
+    this.expression = expression;
+    this.name = name;
+    this.initialize(options);
+  }
+  // Common methods
+  supports(operation) {
+    return this.supportedOperations.has(operation);
+  }
+  matchesField(fieldPath) {
+    return this.expression.type === `ref` && this.expression.path.length === fieldPath.length && this.expression.path.every((part, i) => part === fieldPath[i]);
+  }
+  getStats() {
+    return {
+      entryCount: this.keyCount,
+      lookupCount: this.lookupCount,
+      averageLookupTime: this.lookupCount > 0 ? this.totalLookupTime / this.lookupCount : 0,
+      lastUpdated: this.lastUpdated
+    };
+  }
+  evaluateIndexExpression(item) {
+    const evaluator = compileSingleRowExpression(this.expression);
+    return evaluator(item);
+  }
+  trackLookup(startTime) {
+    const duration = performance.now() - startTime;
+    this.lookupCount++;
+    this.totalLookupTime += duration;
+  }
+  updateTimestamp() {
+    this.lastUpdated = /* @__PURE__ */ new Date();
+  }
+}
+export {
+  BaseIndex,
+  IndexOperation
+};
+//# sourceMappingURL=base-index.js.map

package/dist/esm/indexes/base-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-index.js","sources":["../../../src/indexes/base-index.ts"],"sourcesContent":["import { compileSingleRowExpression } from \"../query/compiler/evaluators.js\"\nimport { comparisonFunctions } from \"../query/builder/functions.js\"\nimport type { BasicExpression } from \"../query/ir.js\"\n\n/**\n * Operations that indexes can support, imported from available comparison functions\n */\nexport const IndexOperation = comparisonFunctions\n\n/**\n * Type for index operation values\n */\nexport type IndexOperation = (typeof comparisonFunctions)[number]\n\n/**\n * Statistics about index usage and performance\n */\nexport interface IndexStats {\n  readonly entryCount: number\n  readonly lookupCount: number\n  readonly averageLookupTime: number\n  readonly lastUpdated: Date\n}\n\n/**\n * Base abstract class that all index types extend\n */\nexport abstract class BaseIndex<\n  TKey extends string | number = string | number,\n> {\n  public readonly id: number\n  public readonly name?: string\n  public readonly expression: BasicExpression\n  public abstract readonly supportedOperations: Set<IndexOperation>\n\n  protected lookupCount = 0\n  protected totalLookupTime = 0\n  protected lastUpdated = new Date()\n\n  constructor(\n    id: number,\n    expression: BasicExpression,\n    name?: string,\n    options?: any\n  ) {\n    this.id = id\n    this.expression = expression\n    this.name = name\n    this.initialize(options)\n  }\n\n  // Abstract methods that each index type must implement\n  abstract add(key: TKey, item: any): void\n  abstract remove(key: TKey, item: any): void\n  abstract update(key: TKey, oldItem: any, newItem: any): void\n  abstract build(entries: Iterable<[TKey, any]>): void\n  abstract clear(): void\n  abstract lookup(operation: IndexOperation, value: any): Set<TKey>\n  abstract get keyCount(): number\n\n  // Common methods\n  supports(operation: IndexOperation): boolean {\n    return this.supportedOperations.has(operation)\n  }\n\n  matchesField(fieldPath: Array<string>): boolean {\n    return (\n      this.expression.type === `ref` &&\n      this.expression.path.length === fieldPath.length &&\n      this.expression.path.every((part, i) => part === fieldPath[i])\n    )\n  }\n\n  getStats(): IndexStats {\n    return {\n      entryCount: this.keyCount,\n      lookupCount: this.lookupCount,\n      averageLookupTime:\n        this.lookupCount > 0 ? this.totalLookupTime / this.lookupCount : 0,\n      lastUpdated: this.lastUpdated,\n    }\n  }\n\n  // Protected methods for subclasses\n  protected abstract initialize(options?: any): void\n\n  protected evaluateIndexExpression(item: any): any {\n    const evaluator = compileSingleRowExpression(this.expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n\n  protected trackLookup(startTime: number): void {\n    const duration = performance.now() - startTime\n    this.lookupCount++\n    this.totalLookupTime += duration\n  }\n\n  protected updateTimestamp(): void {\n    this.lastUpdated = new Date()\n  }\n}\n\n/**\n * Type for index constructor\n */\nexport type IndexConstructor<TKey extends string | number = string | number> =\n  new (\n    id: number,\n    expression: BasicExpression,\n    name?: string,\n    options?: any\n  ) => BaseIndex<TKey>\n\n/**\n * Index resolver can be either a class constructor or async loader\n */\nexport type IndexResolver<TKey extends string | number = string | number> =\n  | IndexConstructor<TKey>\n  | (() => Promise<IndexConstructor<TKey>>)\n"],"names":[],"mappings":";;AAOO,MAAM,iBAAiB;AAoBvB,MAAe,UAEpB;AAAA,EAUA,YACE,IACA,YACA,MACA,SACA;AATF,SAAU,cAAc;AACxB,SAAU,kBAAkB;AAC5B,SAAU,kCAAkB,KAAA;AAQ1B,SAAK,KAAK;AACV,SAAK,aAAa;AAClB,SAAK,OAAO;AACZ,SAAK,WAAW,OAAO;AAAA,EACzB;AAAA;AAAA,EAYA,SAAS,WAAoC;AAC3C,WAAO,KAAK,oBAAoB,IAAI,SAAS;AAAA,EAC/C;AAAA,EAEA,aAAa,WAAmC;AAC9C,WACE,KAAK,WAAW,SAAS,SACzB,KAAK,WAAW,KAAK,WAAW,UAAU,UAC1C,KAAK,WAAW,KAAK,MAAM,CAAC,MAAM,MAAM,SAAS,UAAU,CAAC,CAAC;AAAA,EAEjE;AAAA,EAEA,WAAuB;AACrB,WAAO;AAAA,MACL,YAAY,KAAK;AAAA,MACjB,aAAa,KAAK;AAAA,MAClB,mBACE,KAAK,cAAc,IAAI,KAAK,kBAAkB,KAAK,cAAc;AAAA,MACnE,aAAa,KAAK;AAAA,IAAA;AAAA,EAEtB;AAAA,EAKU,wBAAwB,MAAgB;AAChD,UAAM,YAAY,2BAA2B,KAAK,UAAU;AAC5D,WAAO,UAAU,IAA+B;AAAA,EAClD;AAAA,EAEU,YAAY,WAAyB;AAC7C,UAAM,WAAW,YAAY,IAAA,IAAQ;AACrC,SAAK;AACL,SAAK,mBAAmB;AAAA,EAC1B;AAAA,EAEU,kBAAwB;AAChC,SAAK,kCAAkB,KAAA;AAAA,EACzB;AACF;"}

package/dist/esm/indexes/btree-index.d.ts

@@ -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/esm/indexes/btree-index.js

@@ -0,0 +1,191 @@
+import { ascComparator } from "../utils/comparison.js";
+import { BTree } from "../utils/btree.js";
+import { BaseIndex } from "./base-index.js";
+class BTreeIndex extends 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 = ascComparator;
+    this.compareFn = (options == null ? void 0 : options.compareFn) ?? ascComparator;
+    this.orderedEntries = new 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;
+  }
+}
+export {
+  BTreeIndex
+};
+//# sourceMappingURL=btree-index.js.map

package/dist/esm/indexes/btree-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"btree-index.js","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":[],"mappings":"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"}

package/dist/esm/indexes/index-options.d.ts

@@ -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/esm/indexes/lazy-index.d.ts

@@ -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>;
+}