@tanstack/db 0.0.7 → 0.0.9

package/dist/esm/collection.d.ts

@@ -1,27 +1,28 @@
-import { Derived, Store } from '@tanstack/store';
+import { Store } from '@tanstack/store';
 import { Transaction } from './transactions.js';
 import { SortedMap } from './SortedMap.js';
-import { ChangeMessage, CollectionConfig, Fn, InsertConfig, OperationConfig, OptimisticChangeMessage, Transaction as TransactionType, UtilsRecord } from './types.js';
-export declare const collectionsStore: Store<Map<string, CollectionImpl<any>>, (cb: Map<string, CollectionImpl<any>>) => Map<string, CollectionImpl<any>>>;
+import { ChangeListener, ChangeMessage, CollectionConfig, Fn, InsertConfig, OperationConfig, Transaction as TransactionType, UtilsRecord } from './types.js';
+export declare const collectionsStore: Map<string, CollectionImpl<any, any>>;
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
  * @template T - The type of items in the collection
  * @template TUtils - The utilities record type
  */
-export interface Collection<T extends object = Record<string, unknown>, TUtils extends UtilsRecord = {}> extends CollectionImpl<T> {
+export interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}> extends CollectionImpl<T, TKey> {
     readonly utils: TUtils;
 }
 /**
  * Creates a new Collection instance with the given configuration
  *
  * @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
  * @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>, TUtils extends UtilsRecord = {}>(options: CollectionConfig<T> & {
+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, 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)
@@ -48,7 +49,7 @@ export declare function createCollection<T extends object = Record<string, unkno
  * @param config - Configuration for the collection, including id and sync
  * @returns Promise that resolves when the initial sync is finished
  */
-export declare function preloadCollection<T extends object = Record<string, unknown>>(config: CollectionConfig<T>): Promise<CollectionImpl<T>>;
+export declare function preloadCollection<T extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: CollectionConfig<T, TKey>): Promise<CollectionImpl<T, TKey>>;
 /**
  * Custom error class for schema validation errors
  */
@@ -63,22 +64,19 @@ export declare class SchemaValidationError extends Error {
         path?: ReadonlyArray<string | number | symbol>;
     }>, message?: string);
 }
-export declare class CollectionImpl<T extends object = Record<string, unknown>> {
-    /**
-     * Utilities namespace
-     * This is populated by createCollection
-     */
+export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    transactions: SortedMap<string, Transaction<any>>;
+    syncedData: Map<TKey, T>;
+    syncedMetadata: Map<TKey, unknown>;
+    derivedUpserts: Map<TKey, T>;
+    derivedDeletes: Set<TKey>;
+    private _size;
+    private changeListeners;
+    private changeKeyListeners;
     utils: Record<string, Fn>;
-    transactions: Store<SortedMap<string, TransactionType>>;
-    optimisticOperations: Derived<Array<OptimisticChangeMessage<T>>>;
-    derivedState: Derived<Map<string, T>>;
-    derivedArray: Derived<Array<T>>;
-    derivedChanges: Derived<Array<ChangeMessage<T>>>;
-    syncedData: Store<Map<string, T>, (cb: Map<string, T>) => Map<string, T>>;
-    syncedMetadata: Store<Map<string, unknown>, (cb: Map<string, unknown>) => Map<string, unknown>>;
     private pendingSyncedTransactions;
     private syncedKeys;
-    config: CollectionConfig<T>;
+    config: CollectionConfig<T, TKey>;
     private hasReceivedFirstCommit;
     private onFirstCommitCallbacks;
     /**
@@ -94,15 +92,59 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>>
      * @param config - Configuration object for the collection
      * @throws Error if sync config is missing
      */
-    constructor(config: CollectionConfig<T>);
+    constructor(config: CollectionConfig<T, TKey>);
+    /**
+     * 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 multiple events at once to all listeners
+     */
+    private emitEvents;
+    /**
+     * Get the current value for a key (virtual derived state)
+     */
+    get(key: TKey): T | undefined;
+    /**
+     * Check if a key exists in the collection (virtual derived state)
+     */
+    has(key: TKey): boolean;
+    /**
+     * Get the current size of the collection (cached)
+     */
+    get size(): number;
+    /**
+     * Get all keys (virtual derived state)
+     */
+    keys(): IterableIterator<TKey>;
+    /**
+     * Get all values (virtual derived state)
+     */
+    values(): IterableIterator<T>;
+    /**
+     * Get all entries (virtual derived state)
+     */
+    entries(): IterableIterator<[TKey, T]>;
     /**
      * 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;
     private ensureStandardSchema;
-    private getKeyFromId;
-    generateObjectKey(id: any, item: any): string;
+    getKeyFromItem(item: T): TKey;
+    generateGlobalKey(key: any, item: any): string;
     private validateData;
     /**
      * Inserts one or more items into the collection
@@ -123,7 +165,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;
+    insert: (data: T | Array<T>, config?: InsertConfig) => Transaction<Record<string, unknown>>;
     /**
      * Updates one or more items in the collection using a callback function
      * @param items - Single item/key or array of items/keys to update
@@ -162,8 +204,10 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>>
      * // Update with metadata
      * update("todo-1", { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
      */
-    update<TItem extends object = T>(id: unknown, configOrCallback: ((draft: TItem) => void) | OperationConfig, maybeCallback?: (draft: TItem) => void): TransactionType;
-    update<TItem extends object = T>(ids: Array<unknown>, configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig, maybeCallback?: (draft: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(key: Array<TKey | unknown>, callback: (drafts: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(keys: Array<TKey | unknown>, config: OperationConfig, callback: (drafts: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(id: TKey | unknown, callback: (draft: TItem) => void): TransactionType;
+    update<TItem extends object = T>(id: TKey | unknown, config: OperationConfig, callback: (draft: TItem) => void): TransactionType;
     /**
      * Deletes one or more items from the collection
      * @param ids - Single ID or array of IDs to delete
@@ -179,20 +223,20 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>>
      * // Delete with metadata
      * delete("todo-1", { metadata: { reason: "completed" } })
      */
-    delete: (ids: Array<string> | string, config?: OperationConfig) => TransactionType;
+    delete: (keys: Array<TKey> | TKey, config?: OperationConfig) => TransactionType<any>;
     /**
      * Gets the current state of the collection as a Map
      *
      * @returns A Map containing all items in the collection, with keys as identifiers
      */
-    get state(): Map<string, T>;
+    get state(): Map<TKey, T>;
     /**
      * 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<string, T>>;
+    stateWhenReady(): Promise<Map<TKey, T>>;
     /**
      * Gets the current state of the collection as an Array
      *
@@ -216,5 +260,34 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>>
      * @param callback - A function that will be called with the changes in the collection
      * @returns A function that can be called to unsubscribe from the changes
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void): () => void;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void, { includeInitialState }?: {
+        includeInitialState?: boolean;
+    }): () => void;
+    /**
+     * Subscribe to changes for a specific key
+     */
+    subscribeChangesKey(key: TKey, listener: ChangeListener<T, TKey>, { includeInitialState }?: {
+        includeInitialState?: boolean;
+    }): () => void;
+    /**
+     * Trigger a recomputation when transactions change
+     * This method should be called by the Transaction class when state changes
+     */
+    onTransactionStateChange(): void;
+    private _storeMap;
+    /**
+     * Returns a Tanstack Store Map that is updated when the collection changes
+     * This is a temporary solution to enable the existing framework hooks to work
+     * with the new internals of Collection until they are rewritten.
+     * TODO: Remove this once the framework hooks are rewritten.
+     */
+    asStoreMap(): Store<Map<TKey, T>>;
+    private _storeArray;
+    /**
+     * Returns a Tanstack Store Array that is updated when the collection changes
+     * This is a temporary solution to enable the existing framework hooks to work
+     * with the new internals of Collection until they are rewritten.
+     * TODO: Remove this once the framework hooks are rewritten.
+     */
+    asStoreArray(): Store<Array<T>>;
 }