@tanstack/db 0.3.1 → 0.4.0

package/dist/cjs/{change-events.cjs → collection/change-events.cjs}

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const refProxy = require("./query/builder/ref-proxy.cjs");
-const evaluators = require("./query/compiler/evaluators.cjs");
-const indexOptimization = require("./utils/index-optimization.cjs");
+const evaluators = require("../query/compiler/evaluators.cjs");
+const indexOptimization = require("../utils/index-optimization.cjs");
 function currentStateAsChanges(collection, options = {}) {
   const collectFilteredResults = (filterFn) => {
     const result = [];
@@ -17,20 +16,11 @@ function currentStateAsChanges(collection, options = {}) {
     }
     return result;
   };
-  if (!options.where && !options.whereExpression) {
+  if (!options.where) {
     return collectFilteredResults();
   }
   try {
-    let expression;
-    if (options.whereExpression) {
-      expression = options.whereExpression;
-    } else if (options.where) {
-      const singleRowRefProxy = refProxy.createSingleRowRefProxy();
-      const whereExpression = options.where(singleRowRefProxy);
-      expression = refProxy.toExpression(whereExpression);
-    } else {
-      return [];
-    }
+    const expression = options.where;
     const optimizationResult = indexOptimization.optimizeExpressionWithIndexes(
       expression,
       collection.indexes
@@ -49,7 +39,10 @@ function currentStateAsChanges(collection, options = {}) {
       }
       return result;
     } else {
-      const filterFn = options.where ? createFilterFunction(options.where) : createFilterFunctionFromExpression(expression);
+      if (options.optimizedOnly) {
+        return;
+      }
+      const filterFn = createFilterFunctionFromExpression(expression);
       return collectFilteredResults(filterFn);
     }
   } catch (error) {
@@ -57,34 +50,13 @@ function currentStateAsChanges(collection, options = {}) {
       `Error processing where clause, falling back to full scan:`,
       error
     );
-    const filterFn = options.where ? createFilterFunction(options.where) : createFilterFunctionFromExpression(options.whereExpression);
+    const filterFn = createFilterFunctionFromExpression(options.where);
+    if (options.optimizedOnly) {
+      return;
+    }
     return collectFilteredResults(filterFn);
   }
 }
-function createFilterFunction(whereCallback) {
-  return (item) => {
-    try {
-      const singleRowRefProxy = refProxy.createSingleRowRefProxy();
-      const whereExpression = whereCallback(singleRowRefProxy);
-      const expression = refProxy.toExpression(whereExpression);
-      const evaluator = evaluators.compileSingleRowExpression(expression);
-      const result = evaluator(item);
-      return result;
-    } catch {
-      try {
-        const simpleProxy = new Proxy(item, {
-          get(target, prop) {
-            return target[prop];
-          }
-        });
-        const result = whereCallback(simpleProxy);
-        return result;
-      } catch {
-        return false;
-      }
-    }
-  };
-}
 function createFilterFunctionFromExpression(expression) {
   return (item) => {
     try {
@@ -97,7 +69,7 @@ function createFilterFunctionFromExpression(expression) {
   };
 }
 function createFilteredCallback(originalCallback, options) {
-  const filterFn = options.whereExpression ? createFilterFunctionFromExpression(options.whereExpression) : createFilterFunction(options.where);
+  const filterFn = createFilterFunctionFromExpression(options.whereExpression);
   return (changes) => {
     const filteredChanges = [];
     for (const change of changes) {
@@ -134,7 +106,6 @@ function createFilteredCallback(originalCallback, options) {
     }
   };
 }
-exports.createFilterFunction = createFilterFunction;
 exports.createFilterFunctionFromExpression = createFilterFunctionFromExpression;
 exports.createFilteredCallback = createFilteredCallback;
 exports.currentStateAsChanges = currentStateAsChanges;

package/dist/cjs/collection/change-events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-events.cjs","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from \"../query/builder/ref-proxy\"\nimport { compileSingleRowExpression } from \"../query/compiler/evaluators.js\"\nimport { optimizeExpressionWithIndexes } from \"../utils/index-optimization.js\"\nimport type {\n  ChangeMessage,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from \"../types\"\nimport type { Collection } from \"./index.js\"\nimport type { SingleRowRefProxy } from \"../query/builder/ref-proxy\"\nimport type { BasicExpression } from \"../query/ir.js\"\n\n/**\n * Interface for a collection-like object that provides the necessary methods\n * for the change events system to work\n */\nexport interface CollectionLike<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n> extends Pick<Collection<T, TKey>, `get` | `has` | `entries` | `indexes`> {}\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   whereExpression: eq(row.status, 'active')\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<T, TKey>,\n  options: CurrentStateAsChangesOptions = {}\n): Array<ChangeMessage<T>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: T) => boolean\n  ): Array<ChangeMessage<T>> => {\n    const result: Array<ChangeMessage<T>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // TODO: handle orderBy and limit options\n  //       by calling optimizeOrderedLimit\n\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection.indexes\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<T>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `Error processing where clause, falling back to full scan:`,\n      error\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return result\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return result\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      return Boolean(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<T extends object>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n"],"names":["optimizeExpressionWithIndexes","compileSingleRowExpression"],"mappings":";;;;AA2CO,SAAS,sBAId,YACA,UAAwC,IACR;AAEhC,QAAM,yBAAyB,CAC7B,aAC4B;AAC5B,UAAM,SAAkC,CAAA;AACxC,eAAW,CAAC,KAAK,KAAK,KAAK,WAAW,WAAW;AAE/C,WAAI,qCAAW,WAAU,MAAM;AAC7B,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAKA,MAAI,CAAC,QAAQ,OAAO;AAElB,WAAO,uBAAA;AAAA,EACT;AAGA,MAAI;AACF,UAAM,aAAuC,QAAQ;AAGrD,UAAM,qBAAqBA,kBAAAA;AAAAA,MACzB;AAAA,MACA,WAAW;AAAA,IAAA;AAGb,QAAI,mBAAmB,aAAa;AAElC,YAAM,SAAkC,CAAA;AACxC,iBAAW,OAAO,mBAAmB,cAAc;AACjD,cAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,YAAI,UAAU,QAAW;AACvB,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN;AAAA,YACA;AAAA,UAAA,CACD;AAAA,QACH;AAAA,MACF;AACA,aAAO;AAAA,IACT,OAAO;AACL,UAAI,QAAQ,eAAe;AACzB;AAAA,MACF;AAEA,YAAM,WAAW,mCAAmC,UAAU;AAC9D,aAAO,uBAAuB,QAAQ;AAAA,IACxC;AAAA,EACF,SAAS,OAAO;AAEd,YAAQ;AAAA,MACN;AAAA,MACA;AAAA,IAAA;AAGF,UAAM,WAAW,mCAAmC,QAAQ,KAAK;AAEjE,QAAI,QAAQ,eAAe;AACzB;AAAA,IACF;AAEA,WAAO,uBAAuB,QAAQ;AAAA,EACxC;AACF;AA6CO,SAAS,mCACd,YACsB;AACtB,SAAO,CAAC,SAAqB;AAC3B,QAAI;AACF,YAAM,YAAYC,WAAAA,2BAA2B,UAAU;AACvD,YAAM,SAAS,UAAU,IAA+B;AACxD,aAAO,QAAQ,MAAM;AAAA,IACvB,QAAQ;AAEN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAQO,SAAS,uBACd,kBACA,SAC4C;AAC5C,QAAM,WAAW,mCAAmC,QAAQ,eAAgB;AAE5E,SAAO,CAAC,YAAqC;AAC3C,UAAM,kBAA2C,CAAA;AAEjD,eAAW,UAAU,SAAS;AAC5B,UAAI,OAAO,SAAS,UAAU;AAE5B,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF,WAAW,OAAO,SAAS,UAAU;AAEnC,cAAM,kBAAkB,SAAS,OAAO,KAAK;AAC7C,cAAM,kBAAkB,OAAO,gBAC3B,SAAS,OAAO,aAAa,IAC7B;AAEJ,YAAI,mBAAmB,iBAAiB;AAEtC,0BAAgB,KAAK,MAAM;AAAA,QAC7B,WAAW,mBAAmB,CAAC,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,UAAA,CACP;AAAA,QACH,WAAW,CAAC,mBAAmB,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,YACN,OAAO,OAAO;AAAA;AAAA,UAAA,CACf;AAAA,QACH;AAAA,MAEF,OAAO;AAGL,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF;AAAA,IACF;AAIA,QAAI,gBAAgB,SAAS,KAAK,QAAQ,WAAW,GAAG;AACtD,uBAAiB,eAAe;AAAA,IAClC;AAAA,EACF;AACF;;;;"}

package/dist/{esm/change-events.d.ts → cjs/collection/change-events.d.cts}

@@ -1,7 +1,7 @@
-import { ChangeMessage, CurrentStateAsChangesOptions, SubscribeChangesOptions } from './types.js';
-import { Collection } from './collection.js';
-import { SingleRowRefProxy } from './query/builder/ref-proxy.js';
-import { BasicExpression } from './query/ir.js';
+import { ChangeMessage, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.cjs';
+import { Collection } from './index.js';
+import { SingleRowRefProxy } from '../query/builder/ref-proxy.cjs';
+import { BasicExpression } from '../query/ir.js';
 /**
  * Interface for a collection-like object that provides the necessary methods
  * for the change events system to work
@@ -27,7 +27,7 @@ export interface CollectionLike<T extends object = Record<string, unknown>, TKey
  *   whereExpression: eq(row.status, 'active')
  * })
  */
-export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<T, TKey>, options?: CurrentStateAsChangesOptions<T>): Array<ChangeMessage<T>>;
+export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<T, TKey>, options?: CurrentStateAsChangesOptions): Array<ChangeMessage<T>> | void;
 /**
  * Creates a filter function from a where callback
  * @param whereCallback - The callback function that defines the filter condition
@@ -46,4 +46,4 @@ export declare function createFilterFunctionFromExpression<T extends object>(exp
  * @param options - The subscription options containing the where clause
  * @returns A filtered callback function
  */
-export declare function createFilteredCallback<T extends object>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions<T>): (changes: Array<ChangeMessage<T>>) => void;
+export declare function createFilteredCallback<T extends object>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions): (changes: Array<ChangeMessage<T>>) => void;

package/dist/cjs/collection/changes.cjs

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const errors = require("../errors.cjs");
+const subscription = require("./subscription.cjs");
+class CollectionChangesManager {
+  /**
+   * Creates a new CollectionChangesManager instance
+   */
+  constructor() {
+    this.activeSubscribersCount = 0;
+    this.changeSubscriptions = /* @__PURE__ */ new Set();
+    this.batchedEvents = [];
+    this.shouldBatchEvents = false;
+  }
+  setDeps(deps) {
+    this.lifecycle = deps.lifecycle;
+    this.sync = deps.sync;
+    this.events = deps.events;
+    this.collection = deps.collection;
+  }
+  /**
+   * Emit an empty ready event to notify subscribers that the collection is ready
+   * This bypasses the normal empty array check in emitEvents
+   */
+  emitEmptyReadyEvent() {
+    for (const subscription2 of this.changeSubscriptions) {
+      subscription2.emitEvents([]);
+    }
+  }
+  /**
+   * Emit events either immediately or batch them for later emission
+   */
+  emitEvents(changes, forceEmit = false) {
+    if (this.shouldBatchEvents && !forceEmit) {
+      this.batchedEvents.push(...changes);
+      return;
+    }
+    let eventsToEmit = changes;
+    if (this.batchedEvents.length > 0 && forceEmit) {
+      eventsToEmit = [...this.batchedEvents, ...changes];
+      this.batchedEvents = [];
+      this.shouldBatchEvents = false;
+    }
+    if (eventsToEmit.length === 0) return;
+    for (const subscription2 of this.changeSubscriptions) {
+      subscription2.emitEvents(eventsToEmit);
+    }
+  }
+  /**
+   * Subscribe to changes in the collection
+   */
+  subscribeChanges(callback, options = {}) {
+    this.addSubscriber();
+    const subscription$1 = new subscription.CollectionSubscription(this.collection, callback, {
+      ...options,
+      onUnsubscribe: () => {
+        this.removeSubscriber();
+        this.changeSubscriptions.delete(subscription$1);
+      }
+    });
+    if (options.includeInitialState) {
+      subscription$1.requestSnapshot();
+    }
+    this.changeSubscriptions.add(subscription$1);
+    return subscription$1;
+  }
+  /**
+   * Increment the active subscribers count and start sync if needed
+   */
+  addSubscriber() {
+    const previousSubscriberCount = this.activeSubscribersCount;
+    this.activeSubscribersCount++;
+    this.lifecycle.cancelGCTimer();
+    if (this.lifecycle.status === `cleaned-up` || this.lifecycle.status === `idle`) {
+      this.sync.startSync();
+    }
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    );
+  }
+  /**
+   * Decrement the active subscribers count and start GC timer if needed
+   */
+  removeSubscriber() {
+    const previousSubscriberCount = this.activeSubscribersCount;
+    this.activeSubscribersCount--;
+    if (this.activeSubscribersCount === 0) {
+      this.lifecycle.startGCTimer();
+    } else if (this.activeSubscribersCount < 0) {
+      throw new errors.NegativeActiveSubscribersError();
+    }
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    );
+  }
+  /**
+   * Clean up the collection by stopping sync and clearing data
+   * This can be called manually or automatically by garbage collection
+   */
+  cleanup() {
+    this.batchedEvents = [];
+    this.shouldBatchEvents = false;
+  }
+}
+exports.CollectionChangesManager = CollectionChangesManager;
+//# sourceMappingURL=changes.cjs.map

package/dist/cjs/collection/changes.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.cjs","sources":["../../../src/collection/changes.ts"],"sourcesContent":["import { NegativeActiveSubscribersError } from \"../errors\"\nimport { CollectionSubscription } from \"./subscription.js\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { ChangeMessage, SubscribeChangesOptions } from \"../types\"\nimport type { CollectionLifecycleManager } from \"./lifecycle.js\"\nimport type { CollectionSyncManager } from \"./sync.js\"\nimport type { CollectionEventsManager } from \"./events.js\"\nimport type { CollectionImpl } from \"./index.js\"\n\nexport class CollectionChangesManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n\n  public activeSubscribersCount = 0\n  public changeSubscriptions = new Set<CollectionSubscription>()\n  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []\n  public shouldBatchEvents = false\n\n  /**\n   * Creates a new CollectionChangesManager instance\n   */\n  constructor() {}\n\n  public setDeps(deps: {\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  }) {\n    this.lifecycle = deps.lifecycle\n    this.sync = deps.sync\n    this.events = deps.events\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an empty ready event to notify subscribers that the collection is ready\n   * This bypasses the normal empty array check in emitEvents\n   */\n  public emitEmptyReadyEvent(): void {\n    // Emit empty array directly to all subscribers\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents([])\n    }\n  }\n\n  /**\n   * Emit events either immediately or batch them for later emission\n   */\n  public emitEvents(\n    changes: Array<ChangeMessage<TOutput, TKey>>,\n    forceEmit = false\n  ): void {\n    // Skip batching for user actions (forceEmit=true) to keep UI responsive\n    if (this.shouldBatchEvents && !forceEmit) {\n      // Add events to the batch\n      this.batchedEvents.push(...changes)\n      return\n    }\n\n    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)\n    let eventsToEmit = changes\n\n    // If we have batched events and this is a forced emit, combine them\n    if (this.batchedEvents.length > 0 && forceEmit) {\n      eventsToEmit = [...this.batchedEvents, ...changes]\n      this.batchedEvents = []\n      this.shouldBatchEvents = false\n    }\n\n    if (eventsToEmit.length === 0) return\n\n    // Emit to all listeners\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents(eventsToEmit)\n    }\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   */\n  public subscribeChanges(\n    callback: (changes: Array<ChangeMessage<TOutput>>) => void,\n    options: SubscribeChangesOptions = {}\n  ): CollectionSubscription {\n    // Start sync and track subscriber\n    this.addSubscriber()\n\n    const subscription = new CollectionSubscription(this.collection, callback, {\n      ...options,\n      onUnsubscribe: () => {\n        this.removeSubscriber()\n        this.changeSubscriptions.delete(subscription)\n      },\n    })\n\n    if (options.includeInitialState) {\n      subscription.requestSnapshot()\n    }\n\n    // Add to batched listeners\n    this.changeSubscriptions.add(subscription)\n\n    return subscription\n  }\n\n  /**\n   * Increment the active subscribers count and start sync if needed\n   */\n  private addSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount++\n    this.lifecycle.cancelGCTimer()\n\n    // Start sync if collection was cleaned up\n    if (\n      this.lifecycle.status === `cleaned-up` ||\n      this.lifecycle.status === `idle`\n    ) {\n      this.sync.startSync()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount\n    )\n  }\n\n  /**\n   * Decrement the active subscribers count and start GC timer if needed\n   */\n  private removeSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount--\n\n    if (this.activeSubscribersCount === 0) {\n      this.lifecycle.startGCTimer()\n    } else if (this.activeSubscribersCount < 0) {\n      throw new NegativeActiveSubscribersError()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount\n    )\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public cleanup(): void {\n    this.batchedEvents = []\n    this.shouldBatchEvents = false\n  }\n}\n"],"names":["subscription","CollectionSubscription","NegativeActiveSubscribersError"],"mappings":";;;;AASO,MAAM,yBAKX;AAAA;AAAA;AAAA;AAAA,EAcA,cAAc;AARd,SAAO,yBAAyB;AAChC,SAAO,0CAA0B,IAAA;AACjC,SAAO,gBAAqD,CAAA;AAC5D,SAAO,oBAAoB;AAAA,EAKZ;AAAA,EAER,QAAQ,MAKZ;AACD,SAAK,YAAY,KAAK;AACtB,SAAK,OAAO,KAAK;AACjB,SAAK,SAAS,KAAK;AACnB,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,sBAA4B;AAEjC,eAAWA,iBAAgB,KAAK,qBAAqB;AACnD,MAAAA,cAAa,WAAW,EAAE;AAAA,IAC5B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,WACL,SACA,YAAY,OACN;AAEN,QAAI,KAAK,qBAAqB,CAAC,WAAW;AAExC,WAAK,cAAc,KAAK,GAAG,OAAO;AAClC;AAAA,IACF;AAGA,QAAI,eAAe;AAGnB,QAAI,KAAK,cAAc,SAAS,KAAK,WAAW;AAC9C,qBAAe,CAAC,GAAG,KAAK,eAAe,GAAG,OAAO;AACjD,WAAK,gBAAgB,CAAA;AACrB,WAAK,oBAAoB;AAAA,IAC3B;AAEA,QAAI,aAAa,WAAW,EAAG;AAG/B,eAAWA,iBAAgB,KAAK,qBAAqB;AACnD,MAAAA,cAAa,WAAW,YAAY;AAAA,IACtC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,iBACL,UACA,UAAmC,IACX;AAExB,SAAK,cAAA;AAEL,UAAMA,iBAAe,IAAIC,aAAAA,uBAAuB,KAAK,YAAY,UAAU;AAAA,MACzE,GAAG;AAAA,MACH,eAAe,MAAM;AACnB,aAAK,iBAAA;AACL,aAAK,oBAAoB,OAAOD,cAAY;AAAA,MAC9C;AAAA,IAAA,CACD;AAED,QAAI,QAAQ,qBAAqB;AAC/BA,qBAAa,gBAAA;AAAA,IACf;AAGA,SAAK,oBAAoB,IAAIA,cAAY;AAEzC,WAAOA;AAAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKQ,gBAAsB;AAC5B,UAAM,0BAA0B,KAAK;AACrC,SAAK;AACL,SAAK,UAAU,cAAA;AAGf,QACE,KAAK,UAAU,WAAW,gBAC1B,KAAK,UAAU,WAAW,QAC1B;AACA,WAAK,KAAK,UAAA;AAAA,IACZ;AAEA,SAAK,OAAO;AAAA,MACV,KAAK;AAAA,MACL;AAAA,IAAA;AAAA,EAEJ;AAAA;AAAA;AAAA;AAAA,EAKQ,mBAAyB;AAC/B,UAAM,0BAA0B,KAAK;AACrC,SAAK;AAEL,QAAI,KAAK,2BAA2B,GAAG;AACrC,WAAK,UAAU,aAAA;AAAA,IACjB,WAAW,KAAK,yBAAyB,GAAG;AAC1C,YAAM,IAAIE,OAAAA,+BAAA;AAAA,IACZ;AAEA,SAAK,OAAO;AAAA,MACV,KAAK;AAAA,MACL;AAAA,IAAA;AAAA,EAEJ;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,UAAgB;AACrB,SAAK,gBAAgB,CAAA;AACrB,SAAK,oBAAoB;AAAA,EAC3B;AACF;;"}

package/dist/cjs/collection/changes.d.cts

@@ -0,0 +1,53 @@
+import { CollectionSubscription } from './subscription.js';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { ChangeMessage, SubscribeChangesOptions } from '../types.cjs';
+import { CollectionLifecycleManager } from './lifecycle.js';
+import { CollectionSyncManager } from './sync.js';
+import { CollectionEventsManager } from './events.js';
+import { CollectionImpl } from './index.js';
+export declare class CollectionChangesManager<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
+    private lifecycle;
+    private sync;
+    private events;
+    private collection;
+    activeSubscribersCount: number;
+    changeSubscriptions: Set<CollectionSubscription>;
+    batchedEvents: Array<ChangeMessage<TOutput, TKey>>;
+    shouldBatchEvents: boolean;
+    /**
+     * Creates a new CollectionChangesManager instance
+     */
+    constructor();
+    setDeps(deps: {
+        lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;
+        sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;
+        events: CollectionEventsManager;
+        collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
+    }): void;
+    /**
+     * Emit an empty ready event to notify subscribers that the collection is ready
+     * This bypasses the normal empty array check in emitEvents
+     */
+    emitEmptyReadyEvent(): void;
+    /**
+     * Emit events either immediately or batch them for later emission
+     */
+    emitEvents(changes: Array<ChangeMessage<TOutput, TKey>>, forceEmit?: boolean): void;
+    /**
+     * Subscribe to changes in the collection
+     */
+    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions): CollectionSubscription;
+    /**
+     * Increment the active subscribers count and start sync if needed
+     */
+    private addSubscriber;
+    /**
+     * Decrement the active subscribers count and start GC timer if needed
+     */
+    private removeSubscriber;
+    /**
+     * Clean up the collection by stopping sync and clearing data
+     * This can be called manually or automatically by garbage collection
+     */
+    cleanup(): void;
+}

package/dist/cjs/collection/events.cjs

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class CollectionEventsManager {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  setDeps(deps) {
+    this.collection = deps.collection;
+  }
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      this.listeners.get(event).delete(callback);
+    };
+  }
+  once(event, callback) {
+    const unsubscribe = this.on(event, (eventPayload) => {
+      callback(eventPayload);
+      unsubscribe();
+    });
+    return unsubscribe;
+  }
+  off(event, callback) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.delete(callback);
+  }
+  waitFor(event, timeout) {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      const unsubscribe = this.on(event, (eventPayload) => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = void 0;
+        }
+        resolve(eventPayload);
+        unsubscribe();
+      });
+      if (timeout) {
+        timeoutId = setTimeout(() => {
+          timeoutId = void 0;
+          unsubscribe();
+          reject(new Error(`Timeout waiting for event ${event}`));
+        }, timeout);
+      }
+    });
+  }
+  emit(event, eventPayload) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.forEach((listener) => {
+      try {
+        listener(eventPayload);
+      } catch (error) {
+        queueMicrotask(() => {
+          throw error;
+        });
+      }
+    });
+  }
+  emitStatusChange(status, previousStatus) {
+    this.emit(`status:change`, {
+      type: `status:change`,
+      collection: this.collection,
+      previousStatus,
+      status
+    });
+    const eventKey = `status:${status}`;
+    this.emit(eventKey, {
+      type: eventKey,
+      collection: this.collection,
+      previousStatus,
+      status
+    });
+  }
+  emitSubscribersChange(subscriberCount, previousSubscriberCount) {
+    this.emit(`subscribers:change`, {
+      type: `subscribers:change`,
+      collection: this.collection,
+      previousSubscriberCount,
+      subscriberCount
+    });
+  }
+  cleanup() {
+    this.listeners.clear();
+  }
+}
+exports.CollectionEventsManager = CollectionEventsManager;
+//# sourceMappingURL=events.cjs.map

package/dist/cjs/collection/events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.cjs","sources":["../../../src/collection/events.ts"],"sourcesContent":["import 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\nexport type AllCollectionEvents = {\n  \"status:change\": CollectionStatusChangeEvent\n  \"subscribers:change\": CollectionSubscribersChangeEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T]\n) => void\n\nexport class CollectionEventsManager {\n  private collection!: Collection<any, any, any, any, any>\n  private listeners = new Map<\n    keyof AllCollectionEvents,\n    Set<CollectionEventHandler<any>>\n  >()\n\n  constructor() {}\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  on<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set())\n    }\n    this.listeners.get(event)!.add(callback)\n\n    return () => {\n      this.listeners.get(event)!.delete(callback)\n    }\n  }\n\n  once<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    const unsubscribe = this.on(event, (eventPayload) => {\n      callback(eventPayload)\n      unsubscribe()\n    })\n    return unsubscribe\n  }\n\n  off<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    this.listeners.get(event)?.delete(callback)\n  }\n\n  waitFor<T extends keyof AllCollectionEvents>(\n    event: T,\n    timeout?: number\n  ): Promise<AllCollectionEvents[T]> {\n    return new Promise((resolve, reject) => {\n      let timeoutId: NodeJS.Timeout | undefined\n      const unsubscribe = this.on(event, (eventPayload) => {\n        if (timeoutId) {\n          clearTimeout(timeoutId)\n          timeoutId = undefined\n        }\n        resolve(eventPayload)\n        unsubscribe()\n      })\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          timeoutId = undefined\n          unsubscribe()\n          reject(new Error(`Timeout waiting for event ${event}`))\n        }, timeout)\n      }\n    })\n  }\n\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T]\n  ) {\n    this.listeners.get(event)?.forEach((listener) => {\n      try {\n        listener(eventPayload)\n      } catch (error) {\n        // Re-throw in a microtask to surface the error\n        queueMicrotask(() => {\n          throw error\n        })\n      }\n    })\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.listeners.clear()\n  }\n}\n"],"names":[],"mappings":";;AAiDO,MAAM,wBAAwB;AAAA,EAOnC,cAAc;AALd,SAAQ,gCAAgB,IAAA;AAAA,EAKT;AAAA,EAEf,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA,EAEA,GACE,OACA,UACA;AACA,QAAI,CAAC,KAAK,UAAU,IAAI,KAAK,GAAG;AAC9B,WAAK,UAAU,IAAI,OAAO,oBAAI,KAAK;AAAA,IACrC;AACA,SAAK,UAAU,IAAI,KAAK,EAAG,IAAI,QAAQ;AAEvC,WAAO,MAAM;AACX,WAAK,UAAU,IAAI,KAAK,EAAG,OAAO,QAAQ;AAAA,IAC5C;AAAA,EACF;AAAA,EAEA,KACE,OACA,UACA;AACA,UAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,eAAS,YAAY;AACrB,kBAAA;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,IACE,OACA,UACA;;AACA,eAAK,UAAU,IAAI,KAAK,MAAxB,mBAA2B,OAAO;AAAA,EACpC;AAAA,EAEA,QACE,OACA,SACiC;AACjC,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAI;AACJ,YAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,YAAI,WAAW;AACb,uBAAa,SAAS;AACtB,sBAAY;AAAA,QACd;AACA,gBAAQ,YAAY;AACpB,oBAAA;AAAA,MACF,CAAC;AACD,UAAI,SAAS;AACX,oBAAY,WAAW,MAAM;AAC3B,sBAAY;AACZ,sBAAA;AACA,iBAAO,IAAI,MAAM,6BAA6B,KAAK,EAAE,CAAC;AAAA,QACxD,GAAG,OAAO;AAAA,MACZ;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,KACE,OACA,cACA;;AACA,eAAK,UAAU,IAAI,KAAK,MAAxB,mBAA2B,QAAQ,CAAC,aAAa;AAC/C,UAAI;AACF,iBAAS,YAAY;AAAA,MACvB,SAAS,OAAO;AAEd,uBAAe,MAAM;AACnB,gBAAM;AAAA,QACR,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;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,UAAU,MAAA;AAAA,EACjB;AACF;;"}

package/dist/cjs/collection/events.d.cts

@@ -0,0 +1,53 @@
+import { Collection } from './index.js';
+import { CollectionStatus } from '../types.js';
+/**
+ * Event emitted when the collection status changes
+ */
+export interface CollectionStatusChangeEvent {
+    type: `status:change`;
+    collection: Collection;
+    previousStatus: CollectionStatus;
+    status: CollectionStatus;
+}
+/**
+ * Event emitted when the collection status changes to a specific status
+ */
+export interface CollectionStatusEvent<T extends CollectionStatus> {
+    type: `status:${T}`;
+    collection: Collection;
+    previousStatus: CollectionStatus;
+    status: T;
+}
+/**
+ * Event emitted when the number of subscribers to the collection changes
+ */
+export interface CollectionSubscribersChangeEvent {
+    type: `subscribers:change`;
+    collection: Collection;
+    previousSubscriberCount: number;
+    subscriberCount: number;
+}
+export type AllCollectionEvents = {
+    "status:change": CollectionStatusChangeEvent;
+    "subscribers:change": CollectionSubscribersChangeEvent;
+} & {
+    [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
+};
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent;
+export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
+export declare class CollectionEventsManager {
+    private collection;
+    private listeners;
+    constructor();
+    setDeps(deps: {
+        collection: Collection<any, any, any, any, any>;
+    }): void;
+    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
+    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
+    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;
+    cleanup(): void;
+}