@tanstack/db/dist/esm/collection/state.d.ts

A reactive client store for building super fast apps on sync

import { SortedMap } from '../SortedMap.js';
import { DuplicateKeySyncError } from '../errors.js';
import { VirtualOrigin, VirtualRowProps, WithVirtualProps } from '../virtual-props.js';
import { Transaction } from '../transactions.js';
import { StandardSchemaV1 } from '@standard-schema/spec';
import { ChangeMessage, CollectionConfig, OperationType, OptimisticChangeMessage, PendingMutation } from '../types.js';
import { CollectionImpl } from './index.js';
import { CollectionLifecycleManager } from './lifecycle.js';
import { CollectionChangesManager } from './changes.js';
import { CollectionIndexesManager } from './indexes.js';
import { CollectionEventsManager } from './events.js';
import { Deferred } from '../deferred.js';
type PendingSyncOperation<T extends object, TKey extends string | number> = OptimisticChangeMessage<T, TKey> & {
    /** Preserve adapter intent when queue changes require reclassification. */
    originalSyncType?: `insert`;
};
type PendingInsertDisposition = `insert` | `update` | `duplicate`;
interface PendingSyncedTransaction<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
    committed: boolean;
    applicationStarted: boolean;
    layoutChanged: boolean;
    operations: Array<PendingSyncOperation<T, TKey>>;
    truncate?: boolean;
    rowMetadataWrites: Map<TKey, PendingMetadataWrite>;
    explicitRowMetadataWriteKeys?: Set<TKey>;
    collectionMetadataWrites: Map<string, PendingMetadataWrite>;
    /** Resolves after application and rejects if canceled before application. */
    applied: Deferred<void>;
    preserveHydrationSeedKeys?: boolean;
    /** Builds the error for an open transaction whose insert a replay invalidates. */
    duplicateKeyError?: (key: TKey) => DuplicateKeySyncError;
    /**
     * Set when a replay invalidates an open transaction, which happens when a
     * later transaction begun inside it commits first. Its commit rejects.
     */
    invalidationError?: Error;
}
type PendingMetadataWrite = {
    type: `set`;
    value: unknown;
} | {
    type: `delete`;
};
/** The row metadata a sync operation writes unless the adapter set it explicitly. */
export declare function automaticRowMetadataWrite(operation: Pick<OptimisticChangeMessage<object>, `type` | `metadata`>): PendingMetadataWrite | undefined;
export declare class CollectionStateManager<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
    config: CollectionConfig<TOutput, TKey, TSchema, any>;
    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;
    changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>;
    indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>;
    private _events;
    transactions: SortedMap<string, Transaction<any>>;
    pendingSyncedTransactions: Array<PendingSyncedTransaction<TOutput, TKey>>;
    private pendingSyncedProjection;
    syncedData: SortedMap<TKey, TOutput>;
    syncedMetadata: Map<TKey, unknown>;
    syncedCollectionMetadata: Map<string, unknown>;
    hydrationSeedKeys: Set<TKey>;
    hydratedKeys: Set<TKey>;
    private appliedAdapterDeletedKeys?;
    private hasAppliedAdapterTruncate;
    optimisticUpserts: Map<TKey, TOutput>;
    optimisticDeletes: Set<TKey>;
    heldOptimisticRows: Map<TKey, {
        owner: Transaction<any>;
        row?: TOutput;
    }>;
    /**
     * Tracks the origin of confirmed changes for each row.
     * 'local' = change originated from this client
     * 'remote' = change was received via sync
     *
     * This is used for the $origin virtual property.
     * Note: This only tracks *confirmed* changes, not optimistic ones.
     * Optimistic changes are always considered 'local' for $origin.
     */
    rowOrigins: Map<TKey, VirtualOrigin>;
    /**
     * Tracks keys that have pending local changes.
     * Used to determine whether sync-confirmed data should have 'local' or 'remote' origin.
     * When sync confirms data for a key with pending local changes, it keeps 'local' origin.
     */
    pendingLocalChanges: Set<TKey>;
    pendingLocalOrigins: Set<TKey>;
    private virtualPropsCache;
    size: number;
    preSyncVisibleState: Map<TKey, TOutput | undefined>;
    preSyncVirtualState: Map<TKey, VirtualRowProps<TKey>>;
    recentlySyncedKeys: Set<TKey>;
    hasReceivedFirstCommit: boolean;
    isCommittingSyncTransactions: boolean;
    private isDrainingSyncTransactions;
    private syncRunGeneration;
    isLocalOnly: boolean;
    /**
     * Set by a local-only Collection for operation types without a user handler.
     * Their direct mutations can be written as synced rows at once.
     */
    localOnlyDirectWrite: {
        types: ReadonlySet<OperationType>;
        write: (mutations: Array<PendingMutation<TOutput>>) => void;
    } | undefined;
    /**
     * Creates a new CollectionState manager
     */
    constructor(config: CollectionConfig<TOutput, TKey, TSchema, any>);
    setDeps(deps: {
        collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
        lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;
        changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>;
        indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>;
        events: CollectionEventsManager;
    }): void;
    /**
     * Checks whether this row currently has no pending local optimistic writes.
     *
     * This is local mutation status, not backend confirmation: `true` means the
     * row is not currently affected by an optimistic transaction in this
     * collection's visible state.
     *
     * Used to compute the $synced virtual property.
     */
    isRowSynced(key: TKey): boolean;
    /**
     * Gets the origin of the last confirmed change to a row.
     * Returns 'local' if the row has optimistic mutations (optimistic changes are local).
     * Used to compute the $origin virtual property.
     */
    getRowOrigin(key: TKey): VirtualOrigin;
    private createVirtualPropsSnapshot;
    private getVirtualPropsSnapshotForState;
    private snapshotRowOriginsForKeys;
    private enrichWithVirtualPropsSnapshot;
    private clearOriginTrackingState;
    /**
     * Enriches a row with virtual properties using the "add-if-missing" pattern.
     * If the row already has virtual properties (from an upstream collection),
     * they are preserved. Otherwise, new values are computed.
     */
    enrichWithVirtualProps(row: TOutput, key: TKey): WithVirtualProps<TOutput, TKey>;
    /**
     * Visible entries whose stored row passes `prefilter`, enriched with virtual
     * properties. Rows that fail are never enriched.
     */
    entriesPassing(prefilter: (row: object) => boolean): IterableIterator<[TKey, WithVirtualProps<TOutput, TKey>]>;
    /**
     * Creates a change message with virtual properties.
     * Uses the "add-if-missing" pattern so that pass-through from upstream
     * collections works correctly.
     */
    enrichChangeMessage(change: ChangeMessage<TOutput, TKey>): ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey>;
    /**
     * Get the current value for a key enriched with virtual properties.
     */
    getWithVirtualProps(key: TKey): WithVirtualProps<TOutput, TKey> | undefined;
    /**
     * Get the current value for a key (virtual derived state)
     */
    get(key: TKey): TOutput | undefined;
    /**
     * Check if a key exists in the collection (virtual derived state)
     */
    has(key: TKey): boolean;
    /**
     * Get all keys (virtual derived state)
     */
    keys(): IterableIterator<TKey>;
    /**
     * Get all values (virtual derived state)
     */
    values(): IterableIterator<TOutput>;
    /**
     * Get all entries (virtual derived state)
     */
    entries(): IterableIterator<[TKey, TOutput]>;
    /**
     * Get all entries (virtual derived state)
     */
    [Symbol.iterator](): IterableIterator<[TKey, TOutput]>;
    /**
     * Execute a callback for each entry in the collection
     */
    forEach(callbackfn: (value: TOutput, key: TKey, index: number) => void): void;
    /**
     * 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>;
    /**
     * Check if the given collection is this collection
     * @param collection The collection to check
     * @returns True if the given collection is this collection, false otherwise
     */
    private isThisCollection;
    /**
     * Recompute optimistic state from active transactions
     */
    recomputeOptimisticState(triggeredByUserAction?: boolean): void;
    /**
     * Overlay still-active optimistic mutations on the current layers and
     * record their keys as pending local changes for $origin tracking.
     */
    private overlayActiveTransactions;
    /**
     * Calculate the current size based on synced data and optimistic changes
     */
    private calculateSize;
    /**
     * Collect events for optimistic changes
     */
    private collectOptimisticChanges;
    /** Build once per output flush; queued membership excludes optimistic edits. */
    createSyncedKeyLookup(): (key: TKey) => boolean;
    enableHydrationAuthorityTracking(): void;
    /** A late hydration seed cannot supersede committed adapter work. */
    createAdapterAuthorityLookup(): (key: TKey) => boolean;
    private getProjectedSyncedKeyState;
    /**
     * The synced row once every accepted sync transaction applies. A queued
     * transaction is accepted before it is visible, so a direct write must
     * read this rather than `syncedData`.
     */
    getAcceptedSyncedRow(key: TKey): TOutput | undefined;
    /**
     * Accept a committed seed transaction, such as a DbClient hydration chunk,
     * ahead of any still-open source transaction, so that source's `commit()`
     * still targets its own writes.
     */
    acceptSeedTransaction(transaction: PendingSyncedTransaction<TOutput, TKey>): void;
    /** Every synced row once every accepted sync transaction applies. */
    acceptedSyncedEntries(): IterableIterator<[TKey, TOutput]>;
    private classifyProjectedInsert;
    /** Classify an adapter insert against retained and queued source state. */
    classifyPendingSyncedInsert(key: TKey, value: TOutput): PendingInsertDisposition;
    private applyPendingSyncOperation;
    /** Extend the queued projection after admitting one sync operation. */
    stagePendingSyncOperation(operation: PendingSyncOperation<TOutput, TKey>): void;
    /**
     * Get the previous value for a key given previous optimistic state
     */
    private getPreviousValue;
    private rebuildAutomaticRowMetadataWrites;
    /**
     * Rebuild the queued projection after truncate, application, or an
     * accepted seed changes queue history. An open transaction can become
     * invalid when a later transaction begun inside it commits first; it then
     * holds an invalidation error that its commit returns. Only the open last
     * transaction can be canceled, so a replay that invalidates a committed
     * transaction is an invariant failure.
     */
    private rebuildPendingSyncedProjection;
    /** Rebuild after truncate, application, or an accepted seed. */
    refreshPendingSyncedProjection(): void;
    /**
     * 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;
    hasPersistingTransaction(): boolean;
    private commitNextPendingTransactionBatch;
    /**
     * Abandons the open last sync transaction before acceptance. Only
     * `commit(signal)` with an aborted signal reaches this, so no other
     * transaction can depend on the one canceled.
     */
    cancelPendingSyncedTransaction(transaction: PendingSyncedTransaction<TOutput, TKey>, reason?: Error): void;
    /**
     * Schedule cleanup of a transaction when it completes
     */
    scheduleTransactionCleanup(transaction: Transaction<any>): void;
    /**
     * Capture visible state for keys that will be affected by pending sync operations
     * This must be called BEFORE onTransactionStateChange clears optimistic state
     */
    capturePreSyncVisibleState(): void;
    /**
     * Trigger a recomputation when transactions change
     * This method should be called by the Transaction class when state changes
     */
    onTransactionStateChange(): void;
    /**
     * Clean up the collection by stopping sync and clearing data
     * This can be called manually or automatically by garbage collection
     */
    cleanup(): void;
}
export {};