@tanstack/db 0.0.12 → 0.0.14

package/dist/esm/collection.d.ts

@@ -1,9 +1,13 @@
 import { Store } from '@tanstack/store';
 import { Transaction } from './transactions.js';
 import { SortedMap } from './SortedMap.js';
-import { ChangeListener, ChangeMessage, CollectionConfig, Fn, InsertConfig, OperationConfig, ResolveType, 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
@@ -64,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>;
@@ -73,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, any>;
+    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
@@ -85,6 +97,25 @@ 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
      *
@@ -92,6 +123,44 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      * @throws Error if sync config is missing
      */
     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
      */
@@ -144,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
@@ -164,7 +234,7 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      * // Insert with custom key
      * insert({ text: "Buy groceries" }, { key: "grocery-task" })
      */
-    insert: (data: T | Array<T>, config?: InsertConfig) => Transaction<Record<string, unknown>>;
+    insert: (data: T | Array<T>, config?: InsertConfig) => Transaction<Record<string, unknown>, import('./types.js').OperationType>;
     /**
      * Updates one or more items in the collection using a callback function
      * @param items - Single item/key or array of items/keys to update
@@ -268,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
@@ -290,3 +365,4 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      */
     asStoreArray(): Store<Array<T>>;
 }
+export {};