@tanstack/db 0.0.11 → 0.0.13

package/dist/esm/SortedMap.js

@@ -21,6 +21,33 @@ class SortedMap {
     if (a > b) return 1;
     return 0;
   }
+  /**
+   * Finds the index where a key-value pair should be inserted to maintain sort order.
+   * Uses binary search to find the correct position based on the value.
+   * Hence, it is in O(log n) time.
+   *
+   * @param key - The key to find position for
+   * @param value - The value to compare against
+   * @returns The index where the key should be inserted
+   */
+  indexOf(value) {
+    let left = 0;
+    let right = this.sortedKeys.length;
+    while (left < right) {
+      const mid = Math.floor((left + right) / 2);
+      const midKey = this.sortedKeys[mid];
+      const midValue = this.map.get(midKey);
+      const comparison = this.comparator(value, midValue);
+      if (comparison < 0) {
+        right = mid;
+      } else if (comparison > 0) {
+        left = mid + 1;
+      } else {
+        return mid;
+      }
+    }
+    return left;
+  }
   /**
    * Sets a key-value pair in the map and maintains sort order
    *
@@ -29,15 +56,14 @@ class SortedMap {
    * @returns This SortedMap instance for chaining
    */
   set(key, value) {
-    this.map.set(key, value);
-    if (!this.sortedKeys.includes(key)) {
-      this.sortedKeys.push(key);
+    if (this.map.has(key)) {
+      const oldValue = this.map.get(key);
+      const oldIndex = this.indexOf(oldValue);
+      this.sortedKeys.splice(oldIndex, 1);
     }
-    this.sortedKeys.sort((a, b) => {
-      const valueA = this.map.get(a);
-      const valueB = this.map.get(b);
-      return this.comparator(valueA, valueB);
-    });
+    const index = this.indexOf(value);
+    this.sortedKeys.splice(index, 0, key);
+    this.map.set(key, value);
     return this;
   }
   /**
@@ -56,10 +82,11 @@ class SortedMap {
    * @returns True if the key was found and removed, false otherwise
    */
   delete(key) {
-    if (this.map.delete(key)) {
-      const index = this.sortedKeys.indexOf(key);
+    if (this.map.has(key)) {
+      const oldValue = this.map.get(key);
+      const index = this.indexOf(oldValue);
       this.sortedKeys.splice(index, 1);
-      return true;
+      return this.map.delete(key);
     }
     return false;
   }

package/dist/esm/SortedMap.js.map

@@ -1 +1 @@
-{"version":3,"file":"SortedMap.js","sources":["../../src/SortedMap.ts"],"sourcesContent":["/**\n * A Map implementation that keeps its entries sorted based on a comparator function\n * @template TKey - The type of keys in the map\n * @template TValue - The type of values in the map\n */\nexport class SortedMap<TKey, TValue> {\n  private map: Map<TKey, TValue>\n  private sortedKeys: Array<TKey>\n  private comparator: (a: TValue, b: TValue) => number\n\n  /**\n   * Creates a new SortedMap instance\n   *\n   * @param comparator - Optional function to compare values for sorting\n   */\n  constructor(comparator?: (a: TValue, b: TValue) => number) {\n    this.map = new Map<TKey, TValue>()\n    this.sortedKeys = []\n    this.comparator = comparator || this.defaultComparator\n  }\n\n  /**\n   * Default comparator function used when none is provided\n   *\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns -1 if a < b, 1 if a > b, 0 if equal\n   */\n  private defaultComparator(a: TValue, b: TValue): number {\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n\n  /**\n   * Sets a key-value pair in the map and maintains sort order\n   *\n   * @param key - The key to set\n   * @param value - The value to associate with the key\n   * @returns This SortedMap instance for chaining\n   */\n  set(key: TKey, value: TValue): this {\n    this.map.set(key, value)\n\n    if (!this.sortedKeys.includes(key)) {\n      this.sortedKeys.push(key)\n    }\n\n    // Re-sort keys based on values\n    this.sortedKeys.sort((a, b) => {\n      const valueA = this.map.get(a)!\n      const valueB = this.map.get(b)!\n      return this.comparator(valueA, valueB)\n    })\n\n    return this\n  }\n\n  /**\n   * Gets a value by its key\n   *\n   * @param key - The key to look up\n   * @returns The value associated with the key, or undefined if not found\n   */\n  get(key: TKey): TValue | undefined {\n    return this.map.get(key)\n  }\n\n  /**\n   * Removes a key-value pair from the map\n   *\n   * @param key - The key to remove\n   * @returns True if the key was found and removed, false otherwise\n   */\n  delete(key: TKey): boolean {\n    if (this.map.delete(key)) {\n      const index = this.sortedKeys.indexOf(key)\n      this.sortedKeys.splice(index, 1)\n      return true\n    }\n    return false\n  }\n\n  /**\n   * Checks if a key exists in the map\n   *\n   * @param key - The key to check\n   * @returns True if the key exists, false otherwise\n   */\n  has(key: TKey): boolean {\n    return this.map.has(key)\n  }\n\n  /**\n   * Removes all key-value pairs from the map\n   */\n  clear(): void {\n    this.map.clear()\n    this.sortedKeys = []\n  }\n\n  /**\n   * Gets the number of key-value pairs in the map\n   */\n  get size(): number {\n    return this.map.size\n  }\n\n  /**\n   * Default iterator that returns entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  *[Symbol.iterator](): IterableIterator<[TKey, TValue]> {\n    for (const key of this.sortedKeys) {\n      yield [key, this.map.get(key)!] as [TKey, TValue]\n    }\n  }\n\n  /**\n   * Returns an iterator for the map's entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  entries(): IterableIterator<[TKey, TValue]> {\n    return this[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's keys in sorted order\n   *\n   * @returns An iterator for the map's keys\n   */\n  keys(): IterableIterator<TKey> {\n    return this.sortedKeys[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's values in sorted order\n   *\n   * @returns An iterator for the map's values\n   */\n  values(): IterableIterator<TValue> {\n    return function* (this: SortedMap<TKey, TValue>) {\n      for (const key of this.sortedKeys) {\n        yield this.map.get(key)!\n      }\n    }.call(this)\n  }\n\n  /**\n   * Executes a callback function for each key-value pair in the map in sorted order\n   *\n   * @param callbackfn - Function to execute for each entry\n   */\n  forEach(\n    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void\n  ): void {\n    for (const key of this.sortedKeys) {\n      callbackfn(this.map.get(key)!, key, this.map)\n    }\n  }\n}\n"],"names":[],"mappings":"AAKO,MAAM,UAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUnC,YAAY,YAA+C;AACpD,SAAA,0BAAU,IAAkB;AACjC,SAAK,aAAa,CAAC;AACd,SAAA,aAAa,cAAc,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAU/B,kBAAkB,GAAW,GAAmB;AAClD,QAAA,IAAI,EAAU,QAAA;AACd,QAAA,IAAI,EAAU,QAAA;AACX,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUT,IAAI,KAAW,OAAqB;AAC7B,SAAA,IAAI,IAAI,KAAK,KAAK;AAEvB,QAAI,CAAC,KAAK,WAAW,SAAS,GAAG,GAAG;AAC7B,WAAA,WAAW,KAAK,GAAG;AAAA,IAAA;AAI1B,SAAK,WAAW,KAAK,CAAC,GAAG,MAAM;AAC7B,YAAM,SAAS,KAAK,IAAI,IAAI,CAAC;AAC7B,YAAM,SAAS,KAAK,IAAI,IAAI,CAAC;AACtB,aAAA,KAAK,WAAW,QAAQ,MAAM;AAAA,IAAA,CACtC;AAEM,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,IAAI,KAA+B;AAC1B,WAAA,KAAK,IAAI,IAAI,GAAG;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASzB,OAAO,KAAoB;AACzB,QAAI,KAAK,IAAI,OAAO,GAAG,GAAG;AACxB,YAAM,QAAQ,KAAK,WAAW,QAAQ,GAAG;AACpC,WAAA,WAAW,OAAO,OAAO,CAAC;AACxB,aAAA;AAAA,IAAA;AAEF,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,IAAI,KAAoB;AACf,WAAA,KAAK,IAAI,IAAI,GAAG;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMzB,QAAc;AACZ,SAAK,IAAI,MAAM;AACf,SAAK,aAAa,CAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMrB,IAAI,OAAe;AACjB,WAAO,KAAK,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQlB,EAAE,OAAO,QAAQ,IAAsC;AAC1C,eAAA,OAAO,KAAK,YAAY;AACjC,YAAM,CAAC,KAAK,KAAK,IAAI,IAAI,GAAG,CAAE;AAAA,IAAA;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQF,UAA4C;AACnC,WAAA,KAAK,OAAO,QAAQ,EAAE;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ/B,OAA+B;AAC7B,WAAO,KAAK,WAAW,OAAO,QAAQ,EAAE;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ1C,SAAmC;AACjC,YAAO,aAA0C;AACpC,iBAAA,OAAO,KAAK,YAAY;AAC3B,cAAA,KAAK,IAAI,IAAI,GAAG;AAAA,MAAA;AAAA,IACxB,GACA,KAAK,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQb,QACE,YACM;AACK,eAAA,OAAO,KAAK,YAAY;AACjC,iBAAW,KAAK,IAAI,IAAI,GAAG,GAAI,KAAK,KAAK,GAAG;AAAA,IAAA;AAAA,EAC9C;AAEJ;"}
+{"version":3,"file":"SortedMap.js","sources":["../../src/SortedMap.ts"],"sourcesContent":["/**\n * A Map implementation that keeps its entries sorted based on a comparator function\n * @template TKey - The type of keys in the map\n * @template TValue - The type of values in the map\n */\nexport class SortedMap<TKey, TValue> {\n  private map: Map<TKey, TValue>\n  private sortedKeys: Array<TKey>\n  private comparator: (a: TValue, b: TValue) => number\n\n  /**\n   * Creates a new SortedMap instance\n   *\n   * @param comparator - Optional function to compare values for sorting\n   */\n  constructor(comparator?: (a: TValue, b: TValue) => number) {\n    this.map = new Map<TKey, TValue>()\n    this.sortedKeys = []\n    this.comparator = comparator || this.defaultComparator\n  }\n\n  /**\n   * Default comparator function used when none is provided\n   *\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns -1 if a < b, 1 if a > b, 0 if equal\n   */\n  private defaultComparator(a: TValue, b: TValue): number {\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n\n  /**\n   * Finds the index where a key-value pair should be inserted to maintain sort order.\n   * Uses binary search to find the correct position based on the value.\n   * Hence, it is in O(log n) time.\n   *\n   * @param key - The key to find position for\n   * @param value - The value to compare against\n   * @returns The index where the key should be inserted\n   */\n  private indexOf(value: TValue): number {\n    let left = 0\n    let right = this.sortedKeys.length\n\n    while (left < right) {\n      const mid = Math.floor((left + right) / 2)\n      const midKey = this.sortedKeys[mid]!\n      const midValue = this.map.get(midKey)!\n      const comparison = this.comparator(value, midValue)\n\n      if (comparison < 0) {\n        right = mid\n      } else if (comparison > 0) {\n        left = mid + 1\n      } else {\n        return mid\n      }\n    }\n\n    return left\n  }\n\n  /**\n   * Sets a key-value pair in the map and maintains sort order\n   *\n   * @param key - The key to set\n   * @param value - The value to associate with the key\n   * @returns This SortedMap instance for chaining\n   */\n  set(key: TKey, value: TValue): this {\n    if (this.map.has(key)) {\n      // Need to remove the old key from the sorted keys array\n      const oldValue = this.map.get(key)!\n      const oldIndex = this.indexOf(oldValue)\n      this.sortedKeys.splice(oldIndex, 1)\n    }\n\n    // Insert the new key at the correct position\n    const index = this.indexOf(value)\n    this.sortedKeys.splice(index, 0, key)\n\n    this.map.set(key, value)\n\n    return this\n  }\n\n  /**\n   * Gets a value by its key\n   *\n   * @param key - The key to look up\n   * @returns The value associated with the key, or undefined if not found\n   */\n  get(key: TKey): TValue | undefined {\n    return this.map.get(key)\n  }\n\n  /**\n   * Removes a key-value pair from the map\n   *\n   * @param key - The key to remove\n   * @returns True if the key was found and removed, false otherwise\n   */\n  delete(key: TKey): boolean {\n    if (this.map.has(key)) {\n      const oldValue = this.map.get(key)\n      const index = this.indexOf(oldValue!)\n      this.sortedKeys.splice(index, 1)\n      return this.map.delete(key)\n    }\n\n    return false\n  }\n\n  /**\n   * Checks if a key exists in the map\n   *\n   * @param key - The key to check\n   * @returns True if the key exists, false otherwise\n   */\n  has(key: TKey): boolean {\n    return this.map.has(key)\n  }\n\n  /**\n   * Removes all key-value pairs from the map\n   */\n  clear(): void {\n    this.map.clear()\n    this.sortedKeys = []\n  }\n\n  /**\n   * Gets the number of key-value pairs in the map\n   */\n  get size(): number {\n    return this.map.size\n  }\n\n  /**\n   * Default iterator that returns entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  *[Symbol.iterator](): IterableIterator<[TKey, TValue]> {\n    for (const key of this.sortedKeys) {\n      yield [key, this.map.get(key)!] as [TKey, TValue]\n    }\n  }\n\n  /**\n   * Returns an iterator for the map's entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  entries(): IterableIterator<[TKey, TValue]> {\n    return this[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's keys in sorted order\n   *\n   * @returns An iterator for the map's keys\n   */\n  keys(): IterableIterator<TKey> {\n    return this.sortedKeys[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's values in sorted order\n   *\n   * @returns An iterator for the map's values\n   */\n  values(): IterableIterator<TValue> {\n    return function* (this: SortedMap<TKey, TValue>) {\n      for (const key of this.sortedKeys) {\n        yield this.map.get(key)!\n      }\n    }.call(this)\n  }\n\n  /**\n   * Executes a callback function for each key-value pair in the map in sorted order\n   *\n   * @param callbackfn - Function to execute for each entry\n   */\n  forEach(\n    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void\n  ): void {\n    for (const key of this.sortedKeys) {\n      callbackfn(this.map.get(key)!, key, this.map)\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/collection.d.ts

@@ -1,11 +1,17 @@
 import { Store } from '@tanstack/store';
 import { Transaction } from './transactions.js';
 import { SortedMap } from './SortedMap.js';
-import { ChangeListener, ChangeMessage, CollectionConfig, Fn, InsertConfig, OperationConfig, Transaction as TransactionType, UtilsRecord } from './types.js';
+import { ChangeListener, ChangeMessage, CollectionConfig, CollectionStatus, Fn, InsertConfig, OperationConfig, OptimisticChangeMessage, ResolveType, Transaction as TransactionType, UtilsRecord } from './types.js';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 export declare const collectionsStore: Map<string, CollectionImpl<any, any>>;
+interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
+    committed: boolean;
+    operations: Array<OptimisticChangeMessage<T>>;
+}
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
  * @template T - The type of items in the collection
+ * @template TKey - The type of the key for the collection
  * @template TUtils - The utilities record type
  */
 export interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}> extends CollectionImpl<T, TKey> {
@@ -14,42 +20,39 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
 /**
  * Creates a new Collection instance with the given configuration
  *
- * @template T - The type of items in the collection
+ * @template TExplicit - The explicit type of items in the collection (highest priority)
  * @template TKey - The type of the key for the collection
  * @template TUtils - The utilities record type
+ * @template TSchema - The schema type for validation and type inference (second priority)
+ * @template TFallback - The fallback type if no explicit or schema type is provided
  * @param options - Collection options with optional utilities
  * @returns A new Collection with utilities exposed both at top level and under .utils
- */
-export declare function createCollection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<T, TKey> & {
-    utils?: TUtils;
-}): Collection<T, TKey, TUtils>;
-/**
- * Preloads a collection with the given configuration
- * Returns a promise that resolves once the sync tool has done its first commit (initial sync is finished)
- * If the collection has already loaded, it resolves immediately
- *
- * This function is useful in route loaders or similar pre-rendering scenarios where you want
- * to ensure data is available before a route transition completes. It uses the same shared collection
- * instance that will be used by useCollection, ensuring data consistency.
  *
  * @example
- * ```typescript
- * // In a route loader
- * async function loader({ params }) {
- *   await preloadCollection({
- *     id: `users-${params.userId}`,
- *     sync: { ... },
- *   });
+ * // Using explicit type
+ * const todos = createCollection<Todo>({
+ *   getKey: (todo) => todo.id,
+ *   sync: { sync: () => {} }
+ * })
  *
- *   return null;
- * }
- * ```
+ * // Using schema for type inference (preferred as it also gives you client side validation)
+ * const todoSchema = z.object({
+ *   id: z.string(),
+ *   title: z.string(),
+ *   completed: z.boolean()
+ * })
  *
- * @template T - The type of items in the collection
- * @param config - Configuration for the collection, including id and sync
- * @returns Promise that resolves when the initial sync is finished
+ * const todos = createCollection({
+ *   schema: todoSchema,
+ *   getKey: (todo) => todo.id,
+ *   sync: { sync: () => {} }
+ * })
+ *
+ * // Note: You must provide either an explicit type or a schema, but not both
  */
-export declare function preloadCollection<T extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: CollectionConfig<T, TKey>): Promise<CollectionImpl<T, TKey>>;
+export declare function createCollection<TExplicit = unknown, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey, TSchema> & {
+    utils?: TUtils;
+}): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils>;
 /**
  * Custom error class for schema validation errors
  */
@@ -65,8 +68,10 @@ export declare class SchemaValidationError extends Error {
     }>, message?: string);
 }
 export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    config: CollectionConfig<T, TKey, any>;
     transactions: SortedMap<string, Transaction<any>>;
-    syncedData: Map<TKey, T>;
+    pendingSyncedTransactions: Array<PendingSyncedTransaction<T>>;
+    syncedData: Map<TKey, T> | SortedMap<TKey, T>;
     syncedMetadata: Map<TKey, unknown>;
     derivedUpserts: Map<TKey, T>;
     derivedDeletes: Set<TKey>;
@@ -74,11 +79,17 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     private changeListeners;
     private changeKeyListeners;
     utils: Record<string, Fn>;
-    private pendingSyncedTransactions;
     private syncedKeys;
-    config: CollectionConfig<T, TKey>;
+    private preSyncVisibleState;
+    private recentlySyncedKeys;
     private hasReceivedFirstCommit;
+    private isCommittingSyncTransactions;
     private onFirstCommitCallbacks;
+    private _status;
+    private activeSubscribersCount;
+    private gcTimeoutId;
+    private preloadPromise;
+    private syncCleanupFn;
     /**
      * Register a callback to be executed on the next commit
      * Useful for preloading collections
@@ -86,13 +97,70 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      */
     onFirstCommit(callback: () => void): void;
     id: string;
+    /**
+     * Gets the current status of the collection
+     */
+    get status(): CollectionStatus;
+    /**
+     * Validates that the collection is in a usable state for data operations
+     * @private
+     */
+    private validateCollectionUsable;
+    /**
+     * Validates state transitions to prevent invalid status changes
+     * @private
+     */
+    private validateStatusTransition;
+    /**
+     * Safely update the collection status with validation
+     * @private
+     */
+    private setStatus;
     /**
      * Creates a new Collection instance
      *
      * @param config - Configuration object for the collection
      * @throws Error if sync config is missing
      */
-    constructor(config: CollectionConfig<T, TKey>);
+    constructor(config: CollectionConfig<T, TKey, any>);
+    /**
+     * Start sync immediately - internal method for compiled queries
+     * This bypasses lazy loading for special cases like live query results
+     */
+    startSyncImmediate(): void;
+    /**
+     * Start the sync process for this collection
+     * This is called when the collection is first accessed or preloaded
+     */
+    private startSync;
+    /**
+     * Preload the collection data by starting sync if not already started
+     * Multiple concurrent calls will share the same promise
+     */
+    preload(): Promise<void>;
+    /**
+     * Clean up the collection by stopping sync and clearing data
+     * This can be called manually or automatically by garbage collection
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Start the garbage collection timer
+     * Called when the collection becomes inactive (no subscribers)
+     */
+    private startGCTimer;
+    /**
+     * Cancel the garbage collection timer
+     * Called when the collection becomes active again
+     */
+    private cancelGCTimer;
+    /**
+     * 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;
     /**
      * Recompute optimistic state from active transactions
      */
@@ -145,6 +213,7 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     private ensureStandardSchema;
     getKeyFromItem(item: T): TKey;
     generateGlobalKey(key: any, item: any): string;
+    private deepEqual;
     private validateData;
     /**
      * Inserts one or more items into the collection
@@ -269,6 +338,11 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     subscribeChangesKey(key: TKey, listener: ChangeListener<T, TKey>, { includeInitialState }?: {
         includeInitialState?: boolean;
     }): () => void;
+    /**
+     * Capture visible state for keys that will be affected by pending sync operations
+     * This must be called BEFORE onTransactionStateChange clears optimistic state
+     */
+    private capturePreSyncVisibleState;
     /**
      * Trigger a recomputation when transactions change
      * This method should be called by the Transaction class when state changes
@@ -291,3 +365,4 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      */
     asStoreArray(): Store<Array<T>>;
 }
+export {};