@tanstack/db 0.3.1 → 0.4.0

package/dist/{cjs/collection.d.cts → esm/collection/index.d.ts}

@@ -1,18 +1,13 @@
-import { SortedMap } from './SortedMap.cjs';
-import { BTreeIndex } from './indexes/btree-index.js';
-import { IndexProxy } from './indexes/lazy-index.js';
-import { Transaction } from './transactions.cjs';
+import { CollectionStateManager } from './state.js';
+import { CollectionSubscription } from './subscription.js';
+import { AllCollectionEvents, CollectionEventHandler } from './events.js';
+import { BaseIndex, IndexResolver } from '../indexes/base-index.js';
+import { IndexOptions } from '../indexes/index-options.js';
+import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, OperationConfig, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
+import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { SingleRowRefProxy } from './query/builder/ref-proxy.cjs';
-import { ChangeListener, ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, OperationConfig, OptimisticChangeMessage, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from './types.cjs';
-import { IndexOptions } from './indexes/index-options.js';
-import { BaseIndex, IndexResolver } from './indexes/base-index.js';
-interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
-    committed: boolean;
-    operations: Array<OptimisticChangeMessage<T>>;
-    truncate?: boolean;
-    deletedKeys: Set<string | number>;
-}
+import { BTreeIndex } from '../indexes/btree-index.js';
+import { IndexProxy } from '../indexes/lazy-index.js';
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
  * @template T - The type of items in the collection
@@ -102,35 +97,31 @@ export declare function createCollection<T extends object, TKey extends string |
     utils?: TUtils;
 }): Collection<T, TKey, TUtils, never, T>;
 export declare class CollectionImpl<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
+    id: string;
     config: CollectionConfig<TOutput, TKey, TSchema>;
-    transactions: SortedMap<string, Transaction<any>>;
-    pendingSyncedTransactions: Array<PendingSyncedTransaction<TOutput>>;
-    syncedData: Map<TKey, TOutput> | SortedMap<TKey, TOutput>;
-    syncedMetadata: Map<TKey, unknown>;
-    optimisticUpserts: Map<TKey, TOutput>;
-    optimisticDeletes: Set<TKey>;
-    private _size;
-    private lazyIndexes;
-    private resolvedIndexes;
-    private isIndexesResolved;
-    private indexCounter;
-    private changeListeners;
-    private changeKeyListeners;
     utils: Record<string, Fn>;
-    private syncedKeys;
-    private preSyncVisibleState;
-    private recentlySyncedKeys;
-    private hasReceivedFirstCommit;
-    private isCommittingSyncTransactions;
-    private onFirstReadyCallbacks;
-    private hasBeenReady;
-    private batchedEvents;
-    private shouldBatchEvents;
-    private _status;
-    private activeSubscribersCount;
-    private gcTimeoutId;
-    private preloadPromise;
-    private syncCleanupFn;
+    private _events;
+    private _changes;
+    private _lifecycle;
+    private _sync;
+    private _indexes;
+    private _mutations;
+    _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
+    /**
+     * Creates a new Collection instance
+     *
+     * @param config - Configuration object for the collection
+     * @throws Error if sync config is missing
+     */
+    constructor(config: CollectionConfig<TOutput, TKey, TSchema>);
+    /**
+     * Gets the current status of the collection
+     */
+    get status(): CollectionStatus;
+    /**
+     * Get the number of subscribers to the collection
+     */
+    get subscriberCount(): number;
     /**
      * Register a callback to be executed when the collection first becomes ready
      * Useful for preloading collections
@@ -155,103 +146,16 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * }
      */
     isReady(): boolean;
-    /**
-     * Mark the collection as ready for use
-     * This is called by sync implementations to explicitly signal that the collection is ready,
-     * providing a more intuitive alternative to using commits for readiness signaling
-     * @private - Should only be called by sync implementations
-     */
-    private markReady;
-    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<TOutput, TKey, TSchema>);
     /**
      * 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
-     */
-    private recomputeOptimisticState;
-    /**
-     * Calculate the current size based on synced data and optimistic changes
-     */
-    private calculateSize;
-    /**
-     * Collect events for optimistic changes
-     */
-    private collectOptimisticChanges;
-    /**
-     * Get the previous value for a key given previous optimistic state
-     */
-    private getPreviousValue;
-    /**
-     * Emit an empty ready event to notify subscribers that the collection is ready
-     * This bypasses the normal empty array check in emitEvents
-     */
-    private emitEmptyReadyEvent;
-    /**
-     * Emit events either immediately or batch them for later emission
-     */
-    private emitEvents;
     /**
      * Get the current value for a key (virtual derived state)
      */
@@ -288,19 +192,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * 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>;
-    /**
-     * Attempts to commit pending synced transactions if there are no active transactions
-     * This method processes operations from pending transactions and applies them to the synced data
-     */
-    commitPendingTransactions: () => void;
-    /**
-     * Schedule cleanup of a transaction when it completes
-     * @private
-     */
-    private scheduleTransactionCleanup;
-    private ensureStandardSchema;
     getKeyFromItem(item: TOutput): TKey;
-    generateGlobalKey(key: any, item: any): string;
     /**
      * Creates an index on a collection for faster queries.
      * Indexes significantly improve query performance by allowing constant time lookups
@@ -332,25 +224,13 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * })
      */
     createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(indexCallback: (row: SingleRowRefProxy<TOutput>) => any, config?: IndexOptions<TResolver>): IndexProxy<TKey>;
-    /**
-     * Resolve all lazy indexes (called when collection first syncs)
-     * @private
-     */
-    private resolveAllIndexes;
-    /**
-     * Resolve a single index immediately
-     * @private
-     */
-    private resolveSingleIndex;
     /**
      * Get resolved indexes for query optimization
      */
     get indexes(): Map<number, BaseIndex<TKey>>;
     /**
-     * Updates all indexes when the collection changes
-     * @private
+     * Validates the data against the schema
      */
-    private updateIndexes;
     validateData(data: unknown, type: `insert` | `update`, key?: TKey): TOutput | never;
     /**
      * Inserts one or more items into the collection
@@ -388,7 +268,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   console.log('Insert failed:', error)
      * }
      */
-    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => Transaction<Record<string, unknown>> | Transaction<TOutput>;
+    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => TransactionType<Record<string, unknown>> | TransactionType<TOutput>;
     /**
      * Updates one or more items in the collection using a callback function
      * @param keys - Single key or array of keys to update
@@ -518,7 +398,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   whereExpression: eq(row.status, 'active')
      * })
      */
-    currentStateAsChanges(options?: CurrentStateAsChangesOptions<TOutput>): Array<ChangeMessage<TOutput>>;
+    currentStateAsChanges(options?: CurrentStateAsChangesOptions): Array<ChangeMessage<TOutput>> | void;
     /**
      * Subscribe to changes in the collection
      * @param callback - Function called when items change
@@ -526,23 +406,23 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * @returns Unsubscribe function - Call this to stop listening for changes
      * @example
      * // Basic subscription
-     * const unsubscribe = collection.subscribeChanges((changes) => {
+     * const subscription = collection.subscribeChanges((changes) => {
      *   changes.forEach(change => {
      *     console.log(`${change.type}: ${change.key}`, change.value)
      *   })
      * })
      *
-     * // Later: unsubscribe()
+     * // Later: subscription.unsubscribe()
      *
      * @example
      * // Include current state immediately
-     * const unsubscribe = collection.subscribeChanges((changes) => {
+     * const subscription = collection.subscribeChanges((changes) => {
      *   updateUI(changes)
      * }, { includeInitialState: true })
      *
      * @example
      * // Subscribe only to changes matching a condition
-     * const unsubscribe = collection.subscribeChanges((changes) => {
+     * const subscription = collection.subscribeChanges((changes) => {
      *   updateUI(changes)
      * }, {
      *   includeInitialState: true,
@@ -551,29 +431,33 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *
      * @example
      * // Subscribe using a pre-compiled expression
-     * const unsubscribe = collection.subscribeChanges((changes) => {
+     * const subscription = collection.subscribeChanges((changes) => {
      *   updateUI(changes)
      * }, {
      *   includeInitialState: true,
      *   whereExpression: eq(row.status, 'active')
      * })
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions<TOutput>): () => void;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions): CollectionSubscription;
     /**
-     * Subscribe to changes for a specific key
+     * Subscribe to a collection event
      */
-    subscribeChangesKey(key: TKey, listener: ChangeListener<TOutput, TKey>, { includeInitialState }?: {
-        includeInitialState?: boolean;
-    }): () => void;
+    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
     /**
-     * Capture visible state for keys that will be affected by pending sync operations
-     * This must be called BEFORE onTransactionStateChange clears optimistic state
+     * Subscribe to a collection event once
      */
-    private capturePreSyncVisibleState;
+    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
     /**
-     * Trigger a recomputation when transactions change
-     * This method should be called by the Transaction class when state changes
+     * Unsubscribe from a collection event
      */
-    onTransactionStateChange(): void;
+    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
+    /**
+     * Wait for a collection event
+     */
+    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
+    /**
+     * Clean up the collection by stopping sync and clearing data
+     * This can be called manually or automatically by garbage collection
+     */
+    cleanup(): Promise<void>;
 }
-export {};