@tanstack/db 0.5.33 → 0.6.0

package/dist/esm/collection/cleanup-queue.js

@@ -0,0 +1,89 @@
+const _CleanupQueue = class _CleanupQueue {
+  constructor() {
+    this.tasks = /* @__PURE__ */ new Map();
+    this.timeoutId = null;
+    this.microtaskScheduled = false;
+  }
+  static getInstance() {
+    if (!_CleanupQueue.instance) {
+      _CleanupQueue.instance = new _CleanupQueue();
+    }
+    return _CleanupQueue.instance;
+  }
+  /**
+   * Queues a cleanup task and defers timeout selection to a microtask so
+   * multiple synchronous registrations can share one root timer.
+   */
+  schedule(key, gcTime, callback) {
+    const executeAt = Date.now() + gcTime;
+    this.tasks.set(key, { executeAt, callback });
+    if (!this.microtaskScheduled) {
+      this.microtaskScheduled = true;
+      Promise.resolve().then(() => {
+        this.microtaskScheduled = false;
+        this.updateTimeout();
+      });
+    }
+  }
+  cancel(key) {
+    this.tasks.delete(key);
+  }
+  /**
+   * Keeps only one active timeout: whichever task is due next.
+   */
+  updateTimeout() {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+    if (this.tasks.size === 0) {
+      return;
+    }
+    let earliestTime = Infinity;
+    for (const task of this.tasks.values()) {
+      if (task.executeAt < earliestTime) {
+        earliestTime = task.executeAt;
+      }
+    }
+    const delay = Math.max(0, earliestTime - Date.now());
+    this.timeoutId = setTimeout(() => this.process(), delay);
+  }
+  /**
+   * Runs every task whose deadline has passed, then schedules the next wakeup
+   * if there is still pending work.
+   */
+  process() {
+    this.timeoutId = null;
+    const now = Date.now();
+    for (const [key, task] of this.tasks.entries()) {
+      if (now >= task.executeAt) {
+        this.tasks.delete(key);
+        try {
+          task.callback();
+        } catch (error) {
+          console.error("Error in CleanupQueue task:", error);
+        }
+      }
+    }
+    if (this.tasks.size > 0) {
+      this.updateTimeout();
+    }
+  }
+  /**
+   * Resets the singleton instance for tests.
+   */
+  static resetInstance() {
+    if (_CleanupQueue.instance) {
+      if (_CleanupQueue.instance.timeoutId !== null) {
+        clearTimeout(_CleanupQueue.instance.timeoutId);
+      }
+      _CleanupQueue.instance = null;
+    }
+  }
+};
+_CleanupQueue.instance = null;
+let CleanupQueue = _CleanupQueue;
+export {
+  CleanupQueue
+};
+//# sourceMappingURL=cleanup-queue.js.map

package/dist/esm/collection/cleanup-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-queue.js","sources":["../../../src/collection/cleanup-queue.ts"],"sourcesContent":["type CleanupTask = {\n  executeAt: number\n  callback: () => void\n}\n\n/**\n * Batches many GC registrations behind a single shared timeout.\n */\nexport class CleanupQueue {\n  private static instance: CleanupQueue | null = null\n\n  private tasks: Map<unknown, CleanupTask> = new Map()\n\n  private timeoutId: ReturnType<typeof setTimeout> | null = null\n  private microtaskScheduled = false\n\n  private constructor() {}\n\n  public static getInstance(): CleanupQueue {\n    if (!CleanupQueue.instance) {\n      CleanupQueue.instance = new CleanupQueue()\n    }\n    return CleanupQueue.instance\n  }\n\n  /**\n   * Queues a cleanup task and defers timeout selection to a microtask so\n   * multiple synchronous registrations can share one root timer.\n   */\n  public schedule(key: unknown, gcTime: number, callback: () => void): void {\n    const executeAt = Date.now() + gcTime\n    this.tasks.set(key, { executeAt, callback })\n\n    if (!this.microtaskScheduled) {\n      this.microtaskScheduled = true\n      Promise.resolve().then(() => {\n        this.microtaskScheduled = false\n        this.updateTimeout()\n      })\n    }\n  }\n\n  public cancel(key: unknown): void {\n    this.tasks.delete(key)\n  }\n\n  /**\n   * Keeps only one active timeout: whichever task is due next.\n   */\n  private updateTimeout(): void {\n    if (this.timeoutId !== null) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = null\n    }\n\n    if (this.tasks.size === 0) {\n      return\n    }\n\n    let earliestTime = Infinity\n    for (const task of this.tasks.values()) {\n      if (task.executeAt < earliestTime) {\n        earliestTime = task.executeAt\n      }\n    }\n\n    const delay = Math.max(0, earliestTime - Date.now())\n    this.timeoutId = setTimeout(() => this.process(), delay)\n  }\n\n  /**\n   * Runs every task whose deadline has passed, then schedules the next wakeup\n   * if there is still pending work.\n   */\n  private process(): void {\n    this.timeoutId = null\n    const now = Date.now()\n    for (const [key, task] of this.tasks.entries()) {\n      if (now >= task.executeAt) {\n        this.tasks.delete(key)\n        try {\n          task.callback()\n        } catch (error) {\n          console.error('Error in CleanupQueue task:', error)\n        }\n      }\n    }\n\n    if (this.tasks.size > 0) {\n      this.updateTimeout()\n    }\n  }\n\n  /**\n   * Resets the singleton instance for tests.\n   */\n  public static resetInstance(): void {\n    if (CleanupQueue.instance) {\n      if (CleanupQueue.instance.timeoutId !== null) {\n        clearTimeout(CleanupQueue.instance.timeoutId)\n      }\n      CleanupQueue.instance = null\n    }\n  }\n}\n"],"names":[],"mappings":"AAQO,MAAM,gBAAN,MAAM,cAAa;AAAA,EAQhB,cAAc;AALtB,SAAQ,4BAAuC,IAAA;AAE/C,SAAQ,YAAkD;AAC1D,SAAQ,qBAAqB;AAAA,EAEN;AAAA,EAEvB,OAAc,cAA4B;AACxC,QAAI,CAAC,cAAa,UAAU;AAC1B,oBAAa,WAAW,IAAI,cAAA;AAAA,IAC9B;AACA,WAAO,cAAa;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,SAAS,KAAc,QAAgB,UAA4B;AACxE,UAAM,YAAY,KAAK,IAAA,IAAQ;AAC/B,SAAK,MAAM,IAAI,KAAK,EAAE,WAAW,UAAU;AAE3C,QAAI,CAAC,KAAK,oBAAoB;AAC5B,WAAK,qBAAqB;AAC1B,cAAQ,UAAU,KAAK,MAAM;AAC3B,aAAK,qBAAqB;AAC1B,aAAK,cAAA;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEO,OAAO,KAAoB;AAChC,SAAK,MAAM,OAAO,GAAG;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKQ,gBAAsB;AAC5B,QAAI,KAAK,cAAc,MAAM;AAC3B,mBAAa,KAAK,SAAS;AAC3B,WAAK,YAAY;AAAA,IACnB;AAEA,QAAI,KAAK,MAAM,SAAS,GAAG;AACzB;AAAA,IACF;AAEA,QAAI,eAAe;AACnB,eAAW,QAAQ,KAAK,MAAM,OAAA,GAAU;AACtC,UAAI,KAAK,YAAY,cAAc;AACjC,uBAAe,KAAK;AAAA,MACtB;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,IAAI,GAAG,eAAe,KAAK,KAAK;AACnD,SAAK,YAAY,WAAW,MAAM,KAAK,QAAA,GAAW,KAAK;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,UAAgB;AACtB,SAAK,YAAY;AACjB,UAAM,MAAM,KAAK,IAAA;AACjB,eAAW,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM,WAAW;AAC9C,UAAI,OAAO,KAAK,WAAW;AACzB,aAAK,MAAM,OAAO,GAAG;AACrB,YAAI;AACF,eAAK,SAAA;AAAA,QACP,SAAS,OAAO;AACd,kBAAQ,MAAM,+BAA+B,KAAK;AAAA,QACpD;AAAA,MACF;AAAA,IACF;AAEA,QAAI,KAAK,MAAM,OAAO,GAAG;AACvB,WAAK,cAAA;AAAA,IACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAc,gBAAsB;AAClC,QAAI,cAAa,UAAU;AACzB,UAAI,cAAa,SAAS,cAAc,MAAM;AAC5C,qBAAa,cAAa,SAAS,SAAS;AAAA,MAC9C;AACA,oBAAa,WAAW;AAAA,IAC1B;AAAA,EACF;AACF;AA/FE,cAAe,WAAgC;AAD1C,IAAM,eAAN;"}

package/dist/esm/collection/events.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from '../event-emitter.js';
 import { Collection } from './index.js';
 import { CollectionStatus } from '../types.js';
+import { BasicExpression } from '../query/ir.js';
 /**
  * Event emitted when the collection status changes
  */
@@ -45,15 +46,50 @@ export interface CollectionTruncateEvent {
     type: `truncate`;
     collection: Collection<any, any, any, any, any>;
 }
+export type CollectionIndexSerializableValue = string | number | boolean | null | Array<CollectionIndexSerializableValue> | {
+    [key: string]: CollectionIndexSerializableValue;
+};
+export interface CollectionIndexResolverMetadata {
+    kind: `constructor` | `async`;
+    name?: string;
+}
+export interface CollectionIndexMetadata {
+    /**
+     * Version for the signature serialization contract.
+     */
+    signatureVersion: 1;
+    /**
+     * Stable signature derived from expression + serializable options.
+     * Non-serializable option fields are intentionally omitted.
+     */
+    signature: string;
+    indexId: number;
+    name?: string;
+    expression: BasicExpression;
+    resolver: CollectionIndexResolverMetadata;
+    options?: CollectionIndexSerializableValue;
+}
+export interface CollectionIndexAddedEvent {
+    type: `index:added`;
+    collection: Collection<any, any, any, any, any>;
+    index: CollectionIndexMetadata;
+}
+export interface CollectionIndexRemovedEvent {
+    type: `index:removed`;
+    collection: Collection<any, any, any, any, any>;
+    index: CollectionIndexMetadata;
+}
 export type AllCollectionEvents = {
     'status:change': CollectionStatusChangeEvent;
     'subscribers:change': CollectionSubscribersChangeEvent;
     'loadingSubset:change': CollectionLoadingSubsetChangeEvent;
     truncate: CollectionTruncateEvent;
+    'index:added': CollectionIndexAddedEvent;
+    'index:removed': CollectionIndexRemovedEvent;
 } & {
     [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
 };
-export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent | CollectionTruncateEvent;
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent | CollectionTruncateEvent | CollectionIndexAddedEvent | CollectionIndexRemovedEvent;
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
 export declare class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
     private collection;
@@ -68,5 +104,7 @@ export declare class CollectionEventsManager extends EventEmitter<AllCollectionE
     emit<T extends keyof AllCollectionEvents>(event: T, eventPayload: AllCollectionEvents[T]): void;
     emitStatusChange<T extends CollectionStatus>(status: T, previousStatus: CollectionStatus): void;
     emitSubscribersChange(subscriberCount: number, previousSubscriberCount: number): void;
+    emitIndexAdded(index: CollectionIndexMetadata): void;
+    emitIndexRemoved(index: CollectionIndexMetadata): void;
     cleanup(): void;
 }

package/dist/esm/collection/events.js

@@ -36,6 +36,20 @@ class CollectionEventsManager extends EventEmitter {
       subscriberCount
     });
   }
+  emitIndexAdded(index) {
+    this.emit(`index:added`, {
+      type: `index:added`,
+      collection: this.collection,
+      index
+    });
+  }
+  emitIndexRemoved(index) {
+    this.emit(`index:removed`, {
+      type: `index:removed`,
+      collection: this.collection,
+      index
+    });
+  }
   cleanup() {
     this.clearListeners();
   }

package/dist/esm/collection/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sources":["../../../src/collection/events.ts"],"sourcesContent":["import { EventEmitter } from '../event-emitter.js'\nimport type { Collection } from './index.js'\nimport type { CollectionStatus } from '../types.js'\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\n/**\n * Event emitted when the collection's loading more state changes\n */\nexport interface CollectionLoadingSubsetChangeEvent {\n  type: `loadingSubset:change`\n  collection: Collection<any, any, any, any, any>\n  isLoadingSubset: boolean\n  previousIsLoadingSubset: boolean\n  loadingSubsetTransition: `start` | `end`\n}\n\n/**\n * Event emitted when the collection is truncated (all data cleared)\n */\nexport interface CollectionTruncateEvent {\n  type: `truncate`\n  collection: Collection<any, any, any, any, any>\n}\n\nexport type AllCollectionEvents = {\n  'status:change': CollectionStatusChangeEvent\n  'subscribers:change': CollectionSubscribersChangeEvent\n  'loadingSubset:change': CollectionLoadingSubsetChangeEvent\n  truncate: CollectionTruncateEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n  | CollectionLoadingSubsetChangeEvent\n  | CollectionTruncateEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T],\n) => void\n\nexport class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {\n  private collection!: Collection<any, any, any, any, any>\n\n  constructor() {\n    super()\n  }\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an event to all listeners\n   * Public API for emitting collection events\n   */\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T],\n  ): void {\n    this.emitInner(event, eventPayload)\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus,\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number,\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  cleanup() {\n    this.clearListeners()\n  }\n}\n"],"names":[],"mappings":";AAyEO,MAAM,gCAAgC,aAAkC;AAAA,EAG7E,cAAc;AACZ,UAAA;AAAA,EACF;AAAA,EAEA,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KACE,OACA,cACM;AACN,SAAK,UAAU,OAAO,YAAY;AAAA,EACpC;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,eAAA;AAAA,EACP;AACF;"}
+{"version":3,"file":"events.js","sources":["../../../src/collection/events.ts"],"sourcesContent":["import { EventEmitter } from '../event-emitter.js'\nimport type { Collection } from './index.js'\nimport type { CollectionStatus } from '../types.js'\nimport type { BasicExpression } from '../query/ir.js'\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\n/**\n * Event emitted when the collection's loading more state changes\n */\nexport interface CollectionLoadingSubsetChangeEvent {\n  type: `loadingSubset:change`\n  collection: Collection<any, any, any, any, any>\n  isLoadingSubset: boolean\n  previousIsLoadingSubset: boolean\n  loadingSubsetTransition: `start` | `end`\n}\n\n/**\n * Event emitted when the collection is truncated (all data cleared)\n */\nexport interface CollectionTruncateEvent {\n  type: `truncate`\n  collection: Collection<any, any, any, any, any>\n}\n\nexport type CollectionIndexSerializableValue =\n  | string\n  | number\n  | boolean\n  | null\n  | Array<CollectionIndexSerializableValue>\n  | {\n      [key: string]: CollectionIndexSerializableValue\n    }\n\nexport interface CollectionIndexResolverMetadata {\n  kind: `constructor` | `async`\n  name?: string\n}\n\nexport interface CollectionIndexMetadata {\n  /**\n   * Version for the signature serialization contract.\n   */\n  signatureVersion: 1\n  /**\n   * Stable signature derived from expression + serializable options.\n   * Non-serializable option fields are intentionally omitted.\n   */\n  signature: string\n  indexId: number\n  name?: string\n  expression: BasicExpression\n  resolver: CollectionIndexResolverMetadata\n  options?: CollectionIndexSerializableValue\n}\n\nexport interface CollectionIndexAddedEvent {\n  type: `index:added`\n  collection: Collection<any, any, any, any, any>\n  index: CollectionIndexMetadata\n}\n\nexport interface CollectionIndexRemovedEvent {\n  type: `index:removed`\n  collection: Collection<any, any, any, any, any>\n  index: CollectionIndexMetadata\n}\n\nexport type AllCollectionEvents = {\n  'status:change': CollectionStatusChangeEvent\n  'subscribers:change': CollectionSubscribersChangeEvent\n  'loadingSubset:change': CollectionLoadingSubsetChangeEvent\n  truncate: CollectionTruncateEvent\n  'index:added': CollectionIndexAddedEvent\n  'index:removed': CollectionIndexRemovedEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n  | CollectionLoadingSubsetChangeEvent\n  | CollectionTruncateEvent\n  | CollectionIndexAddedEvent\n  | CollectionIndexRemovedEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T],\n) => void\n\nexport class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {\n  private collection!: Collection<any, any, any, any, any>\n\n  constructor() {\n    super()\n  }\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an event to all listeners\n   * Public API for emitting collection events\n   */\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T],\n  ): void {\n    this.emitInner(event, eventPayload)\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus,\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number,\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  emitIndexAdded(index: CollectionIndexMetadata) {\n    this.emit(`index:added`, {\n      type: `index:added`,\n      collection: this.collection,\n      index,\n    })\n  }\n\n  emitIndexRemoved(index: CollectionIndexMetadata) {\n    this.emit(`index:removed`, {\n      type: `index:removed`,\n      collection: this.collection,\n      index,\n    })\n  }\n\n  cleanup() {\n    this.clearListeners()\n  }\n}\n"],"names":[],"mappings":";AA0HO,MAAM,gCAAgC,aAAkC;AAAA,EAG7E,cAAc;AACZ,UAAA;AAAA,EACF;AAAA,EAEA,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KACE,OACA,cACM;AACN,SAAK,UAAU,OAAO,YAAY;AAAA,EACpC;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,eAAe,OAAgC;AAC7C,SAAK,KAAK,eAAe;AAAA,MACvB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,iBAAiB,OAAgC;AAC/C,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,eAAA;AAAA,EACP;AACF;"}

package/dist/esm/collection/index.d.ts

@@ -2,14 +2,14 @@ import { CollectionStateManager } from './state.js';
 import { CollectionLifecycleManager } from './lifecycle.js';
 import { CollectionSyncManager } from './sync.js';
 import { CollectionSubscription } from './subscription.js';
-import { AllCollectionEvents, CollectionEventHandler } from './events.js';
-import { BaseIndex, IndexResolver } from '../indexes/base-index.js';
+import { AllCollectionEvents, CollectionEventHandler, CollectionIndexMetadata } from './events.js';
+import { BaseIndex, IndexConstructor } from '../indexes/base-index.js';
 import { IndexOptions } from '../indexes/index-options.js';
 import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, NonSingleResult, OperationConfig, SingleResult, StringCollationConfig, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { BTreeIndex } from '../indexes/btree-index.js';
-import { IndexProxy } from '../indexes/lazy-index.js';
+import { WithVirtualProps } from '../virtual-props.js';
+export type { CollectionIndexMetadata } from './events.js';
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
  * @template T - The type of items in the collection
@@ -130,6 +130,12 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     private _indexes;
     private _mutations;
     _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
+    /**
+     * When set, collection consumers should defer processing incoming data
+     * refreshes until this promise resolves. This prevents stale data from
+     * overwriting optimistic state while pending writes are being applied.
+     */
+    deferDataRefresh: Promise<void> | null;
     private comparisonOpts;
     /**
      * Creates a new Collection instance
@@ -188,7 +194,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     /**
      * Get the current value for a key (virtual derived state)
      */
-    get(key: TKey): TOutput | undefined;
+    get(key: TKey): WithVirtualProps<TOutput, TKey> | undefined;
     /**
      * Check if a key exists in the collection (virtual derived state)
      */
@@ -204,58 +210,65 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     /**
      * Get all values (virtual derived state)
      */
-    values(): IterableIterator<TOutput>;
+    values(): IterableIterator<WithVirtualProps<TOutput, TKey>>;
     /**
      * Get all entries (virtual derived state)
      */
-    entries(): IterableIterator<[TKey, TOutput]>;
+    entries(): IterableIterator<[TKey, WithVirtualProps<TOutput, TKey>]>;
     /**
      * Get all entries (virtual derived state)
      */
-    [Symbol.iterator](): IterableIterator<[TKey, TOutput]>;
+    [Symbol.iterator](): IterableIterator<[
+        TKey,
+        WithVirtualProps<TOutput, TKey>
+    ]>;
     /**
      * Execute a callback for each entry in the collection
      */
-    forEach(callbackfn: (value: TOutput, key: TKey, index: number) => void): void;
+    forEach(callbackfn: (value: WithVirtualProps<TOutput, TKey>, key: TKey, index: number) => void): void;
     /**
      * Create a new array with the results of calling a function for each entry in the collection
      */
-    map<U>(callbackfn: (value: TOutput, key: TKey, index: number) => U): Array<U>;
+    map<U>(callbackfn: (value: WithVirtualProps<TOutput, TKey>, key: TKey, index: number) => U): Array<U>;
     getKeyFromItem(item: TOutput): TKey;
     /**
      * Creates an index on a collection for faster queries.
      * Indexes significantly improve query performance by allowing constant time lookups
      * and logarithmic time range queries instead of full scans.
      *
-     * @template TResolver - The type of the index resolver (constructor or async loader)
      * @param indexCallback - Function that extracts the indexed value from each item
      * @param config - Configuration including index type and type-specific options
-     * @returns An index proxy that provides access to the index when ready
+     * @returns The created index
      *
      * @example
-     * // Create a default B+ tree index
-     * const ageIndex = collection.createIndex((row) => row.age)
+     * ```ts
+     * import { BasicIndex } from '@tanstack/db'
      *
-     * // Create a ordered index with custom options
+     * // Create an index with explicit type
      * const ageIndex = collection.createIndex((row) => row.age, {
-     *   indexType: BTreeIndex,
-     *   options: {
-     *     compareFn: customComparator,
-     *     compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }
-     *   },
-     *   name: 'age_btree'
+     *   indexType: BasicIndex
      * })
      *
-     * // Create an async-loaded index
-     * const textIndex = collection.createIndex((row) => row.content, {
-     *   indexType: async () => {
-     *     const { FullTextIndex } = await import('./indexes/fulltext.js')
-     *     return FullTextIndex
-     *   },
-     *   options: { language: 'en' }
-     * })
+     * // Create an index with collection's default type
+     * const nameIndex = collection.createIndex((row) => row.name)
+     * ```
+     */
+    createIndex<TIndexType extends IndexConstructor<TKey>>(indexCallback: (row: SingleRowRefProxy<TOutput>) => any, config?: IndexOptions<TIndexType>): BaseIndex<TKey>;
+    /**
+     * Removes an index created with createIndex.
+     * Returns true when an index existed and was removed.
+     *
+     * Best-effort semantics: removing an index guarantees it is detached from
+     * collection query planning. Existing index proxy references should be treated
+     * as invalid after removal.
+     */
+    removeIndex(indexOrId: BaseIndex<TKey> | number): boolean;
+    /**
+     * Returns a snapshot of current index metadata sorted by indexId.
+     * Persistence wrappers can use this to bootstrap index state if indexes were
+     * created before event listeners were attached.
      */
-    createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(indexCallback: (row: SingleRowRefProxy<TOutput>) => any, config?: IndexOptions<TResolver>): IndexProxy<TKey>;
+    getIndexMetadata(): Array<CollectionIndexMetadata>;
     /**
      * Get resolved indexes for query optimization
      */
@@ -392,27 +405,27 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   console.log("Todo 1 exists:", itemsMap.get("todo-1"))
      * }
      */
-    get state(): Map<TKey, TOutput>;
+    get state(): Map<TKey, WithVirtualProps<TOutput, TKey>>;
     /**
      * Gets the current state of the collection as a Map, but only resolves when data is available
      * Waits for the first sync commit to complete before resolving
      *
      * @returns Promise that resolves to a Map containing all items in the collection
      */
-    stateWhenReady(): Promise<Map<TKey, TOutput>>;
+    stateWhenReady(): Promise<Map<TKey, WithVirtualProps<TOutput, TKey>>>;
     /**
      * Gets the current state of the collection as an Array
      *
      * @returns An Array containing all items in the collection
      */
-    get toArray(): TOutput[];
+    get toArray(): WithVirtualProps<TOutput, TKey>[];
     /**
      * Gets the current state of the collection as an Array, but only resolves when data is available
      * Waits for the first sync commit to complete before resolving
      *
      * @returns Promise that resolves to an Array containing all items in the collection
      */
-    toArrayWhenReady(): Promise<Array<TOutput>>;
+    toArrayWhenReady(): Promise<Array<WithVirtualProps<TOutput, TKey>>>;
     /**
      * Returns the current state of the collection as an array of changes
      * @param options - Options including optional where filter
@@ -431,7 +444,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   whereExpression: eq(row.status, 'active')
      * })
      */
-    currentStateAsChanges(options?: CurrentStateAsChangesOptions): Array<ChangeMessage<TOutput>> | void;
+    currentStateAsChanges(options?: CurrentStateAsChangesOptions): Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>> | void;
     /**
      * Subscribe to changes in the collection
      * @param callback - Function called when items change
@@ -474,7 +487,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   where: (row) => and(eq(row.status, "active"), gt(row.priority, 5))
      * })
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions<TOutput>): CollectionSubscription;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>) => void, options?: SubscribeChangesOptions<TOutput, TKey>): CollectionSubscription;
     /**
      * Subscribe to a collection event
      */

package/dist/esm/collection/index.js

@@ -1,4 +1,4 @@
-import { CollectionRequiresConfigError, CollectionRequiresSyncConfigError } from "../errors.js";
+import { CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionConfigurationError } from "../errors.js";
 import { currentStateAsChanges } from "./change-events.js";
 import { CollectionStateManager } from "./state.js";
 import { CollectionChangesManager } from "./changes.js";
@@ -27,6 +27,7 @@ class CollectionImpl {
    */
   constructor(config) {
     this.utils = {};
+    this.deferDataRefresh = null;
     this.insert = (data, config2) => {
       return this._mutations.insert(data, config2);
     };
@@ -46,8 +47,15 @@ class CollectionImpl {
     }
     this.config = {
       ...config,
-      autoIndex: config.autoIndex ?? `eager`
+      autoIndex: config.autoIndex ?? `off`
     };
+    if (this.config.autoIndex === `eager` && !config.defaultIndexType) {
+      throw new CollectionConfigurationError(
+        `autoIndex: 'eager' requires defaultIndexType to be set. Import an index type and set it:
+  import { BasicIndex } from '@tanstack/db'
+  createCollection({ defaultIndexType: BasicIndex, autoIndex: 'eager', ... })`
+      );
+    }
     this._changes = new CollectionChangesManager();
     this._events = new CollectionEventsManager();
     this._indexes = new CollectionIndexesManager();
@@ -61,7 +69,9 @@ class CollectionImpl {
       // Required for passing to CollectionSubscription
       lifecycle: this._lifecycle,
       sync: this._sync,
-      events: this._events
+      events: this._events,
+      state: this._state
+      // Required for enriching changes with virtual properties
     });
     this._events.setDeps({
       collection: this
@@ -69,7 +79,9 @@ class CollectionImpl {
     });
     this._indexes.setDeps({
       state: this._state,
-      lifecycle: this._lifecycle
+      lifecycle: this._lifecycle,
+      defaultIndexType: config.defaultIndexType,
+      events: this._events
     });
     this._lifecycle.setDeps({
       changes: this._changes,
@@ -168,7 +180,7 @@ class CollectionImpl {
    * Get the current value for a key (virtual derived state)
    */
   get(key) {
-    return this._state.get(key);
+    return this._state.getWithVirtualProps(key);
   }
   /**
    * Check if a key exists in the collection (virtual derived state)
@@ -192,31 +204,49 @@ class CollectionImpl {
    * Get all values (virtual derived state)
    */
   *values() {
-    yield* this._state.values();
+    for (const key of this._state.keys()) {
+      const value = this.get(key);
+      if (value !== void 0) {
+        yield value;
+      }
+    }
   }
   /**
    * Get all entries (virtual derived state)
    */
   *entries() {
-    yield* this._state.entries();
+    for (const key of this._state.keys()) {
+      const value = this.get(key);
+      if (value !== void 0) {
+        yield [key, value];
+      }
+    }
   }
   /**
    * Get all entries (virtual derived state)
    */
   *[Symbol.iterator]() {
-    yield* this._state[Symbol.iterator]();
+    yield* this.entries();
   }
   /**
    * Execute a callback for each entry in the collection
    */
   forEach(callbackfn) {
-    return this._state.forEach(callbackfn);
+    let index = 0;
+    for (const [key, value] of this.entries()) {
+      callbackfn(value, key, index++);
+    }
   }
   /**
    * Create a new array with the results of calling a function for each entry in the collection
    */
   map(callbackfn) {
-    return this._state.map(callbackfn);
+    const result = [];
+    let index = 0;
+    for (const [key, value] of this.entries()) {
+      result.push(callbackfn(value, key, index++));
+    }
+    return result;
   }
   getKeyFromItem(item) {
     return this.config.getKey(item);
@@ -226,37 +256,45 @@ class CollectionImpl {
    * Indexes significantly improve query performance by allowing constant time lookups
    * and logarithmic time range queries instead of full scans.
    *
-   * @template TResolver - The type of the index resolver (constructor or async loader)
    * @param indexCallback - Function that extracts the indexed value from each item
    * @param config - Configuration including index type and type-specific options
-   * @returns An index proxy that provides access to the index when ready
+   * @returns The created index
    *
    * @example
-   * // Create a default B+ tree index
-   * const ageIndex = collection.createIndex((row) => row.age)
+   * ```ts
+   * import { BasicIndex } from '@tanstack/db'
    *
-   * // Create a ordered index with custom options
+   * // Create an index with explicit type
    * const ageIndex = collection.createIndex((row) => row.age, {
-   *   indexType: BTreeIndex,
-   *   options: {
-   *     compareFn: customComparator,
-   *     compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }
-   *   },
-   *   name: 'age_btree'
+   *   indexType: BasicIndex
    * })
    *
-   * // Create an async-loaded index
-   * const textIndex = collection.createIndex((row) => row.content, {
-   *   indexType: async () => {
-   *     const { FullTextIndex } = await import('./indexes/fulltext.js')
-   *     return FullTextIndex
-   *   },
-   *   options: { language: 'en' }
-   * })
+   * // Create an index with collection's default type
+   * const nameIndex = collection.createIndex((row) => row.name)
+   * ```
    */
   createIndex(indexCallback, config = {}) {
     return this._indexes.createIndex(indexCallback, config);
   }
+  /**
+   * Removes an index created with createIndex.
+   * Returns true when an index existed and was removed.
+   *
+   * Best-effort semantics: removing an index guarantees it is detached from
+   * collection query planning. Existing index proxy references should be treated
+   * as invalid after removal.
+   */
+  removeIndex(indexOrId) {
+    return this._indexes.removeIndex(indexOrId);
+  }
+  /**
+   * Returns a snapshot of current index metadata sorted by indexId.
+   * Persistence wrappers can use this to bootstrap index state if indexes were
+   * created before event listeners were attached.
+   */
+  getIndexMetadata() {
+    return this._indexes.getIndexMetadataSnapshot();
+  }
   /**
    * Get resolved indexes for query optimization
    */