ag-charts-community

import { DataChangeDescription } from './dataChangeDescription'; import { DataSetSelection } from './dataSetSelection'; export { DataChangeDescription } from './dataChangeDescription'; export { DataSetSelection } from './dataSetSelection'; type DataIdValue = string | number | undefined; /** * Encapsulates a single transaction to be applied to a DataSet. * Supports both the AG Grid-compatible API (add/addIndex) and the internal format (prepend/append/insertions). */ export interface DataSetTransaction<T> { /** Items to add at the specified index (AG Grid-compatible API). */ add?: T[]; /** Zero-based index for add operation. If undefined or >= length, items are appended. */ addIndex?: number; /** Items to prepend to the beginning (internal format, converted from add with addIndex=0). */ prepend?: T[]; /** Items to append to the end (internal format, converted from add with no addIndex). */ append?: T[]; /** Items to remove. Matched by referential equality, or by `dataIdKey` when set on the DataSet. */ remove?: T[]; /** Items to update. Matched by referential equality, or by `dataIdKey` when set on the DataSet. When matched by ID, the item replaces the existing datum. */ update?: T[]; /** Arbitrary insertions at specific indices (internal format, converted from add with 0 < addIndex < length). */ insertions?: Array<{ index: number; items: T[]; }>; } interface TrackedInsertion<T> { virtualIndex: number; items: T[]; } interface UpdateIndexTracking { updatedPrependsIndices: number[]; updatedAppendsIndices: number[]; updatedInsertionsIndices: number[]; } export interface TransactionCollectionState<T> { prependsList: T[][]; appendsList: T[][]; insertionsList: T[][]; trackedInsertions: TrackedInsertion<T>[]; removedOriginalIndices: Set<number>; updatedOriginalIndices: Set<number>; virtualLength: number; updateTracking?: UpdateIndexTracking; pendingReplacements?: Map<string | number, T>; } /** * Manages transactional updates to an array of data with optimized batch processing. * Transactions are queued and can be applied in batch for efficient data transformations. */ export declare class DataSet<T = unknown> { data: T[]; readonly dataIdKey?: string | undefined; private pendingTransactions; private cachedChangeDescription; private cachedPendingReplacements; private itemToIndexCache; protected idToIndexCache: Map<string | number, number> | undefined; protected idArrayCache: DataIdValue[] | undefined; /** Per-series selection state. Keyed by `seriesId`. */ readonly selections: Map<string, DataSetSelection>; constructor(data: T[], dataIdKey?: string | undefined); /** * Creates an empty DataSet. */ static empty(dataIdKey?: string): DataSet; /** * Wraps existing data in a DataSet. */ static wrap(data: U[], dataIdKey?: string): DataSet; netSize(): number; /** * Queues a transaction (applied on commit). * Normalizes AG Grid-compatible format (add/addIndex) to internal format (prepend/append). */ addTransaction(transaction: DataSetTransaction<T>): void; /** * @returns A deep clone of the DataSet. Selection state is preserved only when * `dataIdKey` is set (transferred via key mapping). Without `dataIdKey`, selections * are dropped because index-based transfer cannot guarantee correctness after the * clone's data is independently mutated. */ deepClone(): DataSet<T>; /** * Create a new DataSet, transferring persistent state from a predecessor. * For subclasses that take additional constructor args (e.g. HierarchyDataSet), * use the two-phase pattern: construct, then call `transferFrom()` explicitly. */ static replaceWith(predecessor: DataSet | undefined, data: U[], dataIdKey?: string): DataSet; /** Lazy-create a per-series selection backed by a Uint8Array of `data.length`. */ enableSelection(seriesId: string): DataSetSelection; /** * Lazy index→key array mirroring `getIdToIndexMap()`. Built on first access * when `dataIdKey` is set; invalidated on data mutation and rebuilt on demand. */ getIdArray(): DataIdValue[] | undefined; getItemIdFromIndex(datumIndex: number): string | number; getIndexFromItemId(itemId: string | number): number | undefined; /** * Transfer persistent state (selections) from a predecessor DataSet. * Uses `idArray` + `idToIndexMap` to map selected keys from old to new index space. * Without `dataIdKey`, selections cannot be transferred and are dropped. */ transferFrom(predecessor: DataSet<T>): void; /** * Converts AG Grid-compatible transaction format to internal format. * Maps `add` + `addIndex` to prepend, append, or arbitrary insertion based on the index. */ private normalizeTransaction; hasPendingTransactions(): boolean; getPendingTransactionCount(): number; /** Applies all pending transactions to the data array. */ commitPendingTransactions(): boolean; /** Updates item→index cache incrementally, or invalidates for complex changes. */ private updateItemToIndexCache; /** Updates id→index cache incrementally, or invalidates for complex changes. */ private updateIdToIndexCache; clearPendingTransactions(): number; getPendingTransactions(): DataSetTransaction<T>[]; /** Custom JSON serialization (avoids snapshot bloat). */ toJSON(): T[]; /** Builds a DataChangeDescription from pending transactions. */ getChangeDescription(): DataChangeDescription | undefined; /** * Helper method to remove items from a list of groups. * Mutates the groups in-place and removes found items from toRemove set. * @param groups List of groups to search and remove from * @param toRemove Set of items to remove (modified in-place) */ private removeFromGroups; /** * Builds the index transformation map by sequentially applying all pending transactions. * Optimized to: * - Track operation boundaries instead of individual items * - Only scan for values that are actually being removed * - Stop scanning early when all removed values are found * - Support arbitrary insertions at any index * - Track updated items by referential equality */ private buildIndexMap; private getSortedRemovedIndices; private collectTransactionEffects; private applyPrepends; private applyInsertions; private applyAppends; private applyRemovals; private applyRemovalsByRef; protected applyRemovalsById(remove: T[], state: TransactionCollectionState<T>): void; private applyUpdates; private applyUpdatesByRef; private applyUpdatesById; private collectUpdatedIndicesFromGroups; /** Lazy item→index map for O(1) lookups. */ private getItemToIndexMap; /** Extracts the ID value from a datum; returns `undefined` if missing or not a string/number. */ protected getIdValue(item: T): DataIdValue; /** Lazy ID→index map for O(1) lookups when `dataIdKey` is set. */ protected getIdToIndexMap(): Map<string | number, number>; /** Removes items from groups by matching their ID values against a set of IDs. */ private removeFromGroupsById; /** Collects updated indices from groups by matching their ID values against a map of IDs to new datums. */ private collectUpdatedIndicesFromGroupsById; /** Collects updated original indices by ID, storing replacements (keyed by ID) in state for commit. */ protected collectUpdatedOriginalIndicesById(toUpdate: Map<string | number, T>, state: TransactionCollectionState<T>): void; private collectUpdatedOriginalIndices; private removeFromTrackedInsertions; protected removeFromTrackedInsertionsById(removeValues: T[], state: TransactionCollectionState<T>): void; private adjustLaterInsertionsAfterRemoval; private buildSpliceOperations; private countRemovalsBeforeIndex; private resolveUpdatedIndices; }