@tanstack/db 0.0.27 → 0.0.29

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 { OrderedIndex } from "./ordered-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: OrderedIndex
+      });
+    } 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 { OrderedIndex } from \"./ordered-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: OrderedIndex,\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/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>;
+}

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

@@ -0,0 +1,193 @@
+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;
+  }
+}
+export {
+  IndexProxy,
+  LazyIndexWrapper
+};
+//# sourceMappingURL=lazy-index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-index.js","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":"AAUA,SAAS,cACP,UACoC;AAEpC,SACE,OAAO,aAAa,cACpB,SAAS,cAAc,UACvB,SAAS,UAAU,gBAAgB;AAEvC;AAKA,eAAe,wBACb,UACiC;AACjC,MAAI,cAAc,QAAQ,GAAG;AAC3B,WAAO;AAAA,EACT,OAAO;AAEL,WAAO,MAAM,SAAA;AAAA,EACf;AACF;AAKO,MAAM,iBAAiE;AAAA,EAI5E,YACU,IACA,YACA,MACA,UACA,SACA,mBACR;AANQ,SAAA,KAAA;AACA,SAAA,aAAA;AACA,SAAA,OAAA;AACA,SAAA,WAAA;AACA,SAAA,UAAA;AACA,SAAA,oBAAA;AATV,SAAQ,eAAgD;AACxD,SAAQ,gBAAwC;AAW9C,QAAI,cAAc,KAAK,QAAQ,GAAG;AAChC,WAAK,gBAAgB,IAAI,KAAK;AAAA,QAC5B,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MAAA;AAGP,UAAI,KAAK,mBAAmB;AAC1B,aAAK,cAAc,MAAM,KAAK,iBAAiB;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,UAAoC;AACxC,QAAI,KAAK,eAAe;AACtB,aAAO,KAAK;AAAA,IACd;AAEA,QAAI,CAAC,KAAK,cAAc;AACtB,WAAK,eAAe,KAAK,YAAA;AAAA,IAC3B;AAEA,SAAK,gBAAgB,MAAM,KAAK;AAChC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,aAAsB;AACpB,WAAO,KAAK,kBAAkB;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA,EAKA,cAA+B;AAC7B,QAAI,CAAC,KAAK,eAAe;AACvB,YAAM,IAAI;AAAA,QACR,SAAS,KAAK,EAAE;AAAA,MAAA;AAAA,IAEpB;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,QAAgB;AACd,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,UAA8B;AAC5B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,gBAAiC;AAC/B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,cAAwC;AACpD,UAAM,aAAa,MAAM,wBAAwB,KAAK,QAAQ;AAC9D,WAAO,IAAI,WAAW,KAAK,IAAI,KAAK,YAAY,KAAK,MAAM,KAAK,OAAO;AAAA,EACzE;AACF;AAKO,MAAM,WAA2D;AAAA,EACtE,YACU,SACA,WACR;AAFQ,SAAA,UAAA;AACA,SAAA,YAAA;AAAA,EACP;AAAA;AAAA;AAAA;AAAA,EAKH,IAAI,QAAyB;AAC3B,WAAO,KAAK,UAAU,YAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,UAAmB;AACrB,WAAO,KAAK,UAAU,WAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,YAAsC;AAC1C,WAAO,MAAM,KAAK,UAAU,QAAA;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,KAAa;AACf,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAA2B;AAC7B,QAAI,KAAK,SAAS;AAChB,aAAO,KAAK,MAAM;AAAA,IACpB;AACA,WAAO,KAAK,UAAU,QAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,aAA8B;AAChC,WAAO,KAAK,UAAU,cAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,SAAS,WAAyB;AAChC,WAAO,KAAK,MAAM,SAAS,SAAS;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW;AACT,WAAO,KAAK,MAAM,SAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAKA,aAAa,WAAmC;AAC9C,UAAM,OAAO,KAAK;AAClB,WACE,KAAK,SAAS,SACd,KAAK,KAAK,WAAW,UAAU,UAC/B,KAAK,KAAK,MAAM,CAAC,MAAM,MAAM,SAAS,UAAU,CAAC,CAAC;AAAA,EAEtD;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,WAAmB;AACrB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA;AAAA,EAGA,IAAI,iBAA4B;AAC9B,UAAM,WAAW,KAAK;AACtB,WAAO,SAAS;AAAA,EAClB;AAAA,EAEA,IAAI,sBAA+C;AACjD,UAAM,WAAW,KAAK;AACtB,WAAO,SAAS;AAAA,EAClB;AAAA,EAEA,IAAI,eAAoC;AACtC,UAAM,WAAW,KAAK;AACtB,WAAO,SAAS;AAAA,EAClB;AAAA;AAAA,EAGA,eAAe,OAAuB;AA7NxC;AA8NI,UAAM,WAAW,KAAK;AACtB,aAAO,cAAS,mBAAT,kCAA0B,+BAAc,IAAA;AAAA,EACjD;AAAA,EAEA,WAAW,SAAyB;AAlOtC;AAmOI,UAAM,WAAW,KAAK;AACtB,aAAO,cAAS,eAAT,kCAAsB,iCAAgB,IAAA;AAAA,EAC/C;AAAA,EAEA,cAAc,QAA+B;AAvO/C;AAwOI,UAAM,WAAW,KAAK;AACtB,aAAO,cAAS,kBAAT,kCAAyB,gCAAe,IAAA;AAAA,EACjD;AAAA;AAAA,EAGA,kBAA0C;AACxC,WAAO,KAAK;AAAA,EACd;AACF;"}

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

@@ -0,0 +1,72 @@
+import { BaseIndex, IndexOperation } from './base-index.js';
+/**
+ * Options for Ordered index
+ */
+export interface OrderedIndexOptions {
+    compareFn?: (a: any, b: any) => number;
+}
+/**
+ * Options for range queries
+ */
+export interface RangeQueryOptions {
+    from?: any;
+    to?: any;
+    fromInclusive?: boolean;
+    toInclusive?: boolean;
+}
+/**
+ * Ordered index for sorted data with range queries
+ * This maintains items in sorted order and provides efficient range operations
+ */
+export declare class OrderedIndex<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;
+    protected initialize(options?: OrderedIndexOptions): 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>>;
+}