@gridengine/angular-datagrid-enterprise 0.2.0 → 0.4.0

package/types/gridengine-angular-datagrid-enterprise.d.ts

@@ -276,5 +276,227 @@ declare class UndoRedoManager {
     private _notifyChange;
 }
 
-export { ClipboardEngine, DataGridPro, FillHandleEngine, GridLicenseWatermark, LicenseManager, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
-export type { CellEditCommand, CellRange, ClipboardEngineOptions, DeleteCommand, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, PasteCommand, RangeSelectionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };
+/**
+ * FormulaEngine — evaluates Excel-like formula strings against row data.
+ * Formulas start with '=' and reference other columns by field name.
+ *
+ * Functions: SUM, AVG, MIN, MAX, COUNT, IF, CONCAT, ROUND, ABS, FLOOR, CEIL,
+ * LEN, UPPER, LOWER. Bare identifiers that aren't function names are treated as
+ * field lookups on the current row.
+ *
+ * Error values: '#ERROR!', '#DIV/0!', '#REF!', '#CIRCULAR!', '#NAME?'.
+ * A formula that directly/transitively references its own cell yields
+ * '#CIRCULAR!'.
+ */
+type Row = Record<string, unknown>;
+interface FormulaEngineOptions {
+    /**
+     * Fields that contain formula definitions. Key = field name, value = formula
+     * string (e.g. '=SUM(price, tax)'). The row's field value is replaced by the
+     * evaluation result.
+     */
+    formulaFields: Record<string, string>;
+}
+declare class FormulaEngine {
+    private readonly _formulaFields;
+    constructor(options: FormulaEngineOptions);
+    /** Evaluate all formula fields for a row, returning a new (unmutated) row. */
+    evaluateRow(row: Row): Row;
+    /** Evaluate a single formula string against a row. */
+    evaluateFormula(formula: string, row: Row, selfField?: string): unknown;
+    /** Whether a formula string is parseable (no evaluation). */
+    isValidFormula(formula: string): boolean;
+}
+
+/** A grid row — an arbitrary keyed record. Alias used across the Pro engines. */
+type GridRow = Record<string, unknown>;
+
+/**
+ * SSRMEngine — Server-Side Row Model: a block-based LRU cache for server-driven
+ * datasets of arbitrary size. Pure logic; the caller supplies a datasource with
+ * a single async `getRows()` method. Filter/sort/group models are forwarded to
+ * the server. Failed fetches retry up to 3 times with exponential backoff.
+ */
+
+interface SSRMGetRowsParams {
+    startRow: number;
+    endRow: number;
+    filterModel: Record<string, unknown>;
+    sortModel: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    groupKeys: string[];
+}
+interface SSRMGetRowsResult {
+    rows: GridRow[];
+    totalCount: number;
+}
+interface SSRMDataSource {
+    getRows(params: SSRMGetRowsParams): Promise<SSRMGetRowsResult>;
+}
+type BlockState = 'idle' | 'loading' | 'loaded' | 'error';
+interface Block {
+    /** Zero-based block index (index * blockSize = startRow). */
+    index: number;
+    state: BlockState;
+    rows: GridRow[];
+    error?: Error;
+    /** Monotonically increasing access counter — higher = more recently used. */
+    lastAccessed: number;
+}
+interface SSRMEngineOptions {
+    dataSource: SSRMDataSource;
+    /** Rows per block. Default: 100 */
+    blockSize?: number;
+    /** Maximum blocks to keep in memory (LRU eviction). Default: 10 */
+    maxBlocksInCache?: number;
+}
+declare class SSRMEngine {
+    private readonly _dataSource;
+    readonly blockSize: number;
+    readonly maxBlocksInCache: number;
+    private readonly _blocks;
+    private _accessClock;
+    private _totalCount;
+    private _filterModel;
+    private _sortModel;
+    private _groupKeys;
+    private _onChange?;
+    constructor(options: SSRMEngineOptions);
+    subscribe(listener: () => void): () => void;
+    setFilterModel(model: Record<string, unknown>): void;
+    setSortModel(model: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[]): void;
+    setGroupKeys(keys: string[]): void;
+    /** Total row count from the last server response (null = not yet known). */
+    getTotalCount(): number | null;
+    /**
+     * Get the row at an absolute zero-based index, fetching the containing block
+     * if needed. Returns null while the block is loading.
+     */
+    getRow(rowIndex: number): GridRow | null;
+    /** Rows for the viewport [startRow, endRow); missing slots are null. */
+    getRowSlice(startRow: number, endRow: number): (GridRow | null)[];
+    getBlockState(blockIndex: number): BlockState;
+    getBlocks(): ReadonlyMap<number, Block>;
+    /** Evict all cached blocks and reset total count. */
+    invalidateAll(): void;
+    /** Evict a specific block (e.g. after a row mutation on that page). */
+    invalidateBlock(blockIndex: number): void;
+    private _getOrCreateBlock;
+    private _fetchBlock;
+    private _evictOldest;
+    private _invalidateAll;
+    private _notify;
+}
+
+/**
+ * TransactionEngine — stages add / update / remove operations against a row set
+ * without mutating the original array. Changes are held until commit (fires
+ * `onTransactionCommit` with the delta) or rollback (discards them). Row
+ * identity comes from `rowIdField` (default 'id').
+ */
+
+interface TransactionDelta {
+    added: GridRow[];
+    updated: GridRow[];
+    removedIds: (string | number)[];
+}
+interface TransactionEngineOptions {
+    /** Initial rows loaded from the grid. */
+    initialRows: GridRow[];
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    onTransactionCommit?: (delta: TransactionDelta) => void;
+    onTransactionRollback?: () => void;
+}
+declare class TransactionEngine {
+    private readonly _rowIdField;
+    private readonly _onCommit?;
+    private readonly _onRollback?;
+    private _baseRows;
+    private readonly _dirty;
+    constructor(opts: TransactionEngineOptions);
+    /** Stage new rows; an existing ID is treated as an update instead. */
+    addRows(rows: GridRow[]): void;
+    /** Stage updates for existing rows; unknown IDs are ignored with a warning. */
+    updateRows(rows: GridRow[]): void;
+    /** Stage rows for removal by ID; a still-staged add is simply cancelled. */
+    removeRows(ids: (string | number)[]): void;
+    commitTransaction(): void;
+    rollbackTransaction(): void;
+    /** True if there are any staged (uncommitted) changes. */
+    isDirty(): boolean;
+    /** All current staged changes, grouped by kind. */
+    getDirtyRows(): {
+        added: GridRow[];
+        updated: GridRow[];
+        removed: GridRow[];
+    };
+    /** The merged row list: base rows with staged changes applied. */
+    getDisplayRows(): GridRow[];
+    /** Replace the base rows (e.g. after a refresh); staged changes are kept. */
+    resetRows(rows: GridRow[]): void;
+    private _rowId;
+    private _findBase;
+    private _stageUpdate;
+    private _buildDelta;
+}
+
+/**
+ * MasterDetailEngine — manages expand/collapse state and lazy-loaded, cached
+ * detail data for master rows. Pure logic. Detail data is fetched once per row
+ * ID on first expand; subsequent expands reuse the cache.
+ */
+
+type DetailLoadState = 'idle' | 'loading' | 'loaded' | 'error';
+interface DetailEntry {
+    state: DetailLoadState;
+    data: GridRow[];
+    error?: Error;
+}
+interface MasterDetailEngineOptions {
+    /** Loads detail rows for a master row; called at most once per row ID. */
+    getDetailRowData: (masterRow: GridRow) => Promise<GridRow[]>;
+    /** Called when a row's expanded state changes. */
+    onExpand?: (masterRow: GridRow, expanded: boolean) => void;
+    /** Field used as the row ID. Default: 'id' */
+    rowIdField?: string;
+}
+declare class MasterDetailEngine {
+    private readonly _getDetailRowData;
+    private readonly _onExpand?;
+    private readonly _rowIdField;
+    private readonly _expanded;
+    private readonly _cache;
+    private _onChange?;
+    constructor(options: MasterDetailEngineOptions);
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    isExpanded(rowId: string | number): boolean;
+    getLoadState(rowId: string | number): DetailLoadState;
+    /** Cached detail rows, or an empty array if not yet loaded. */
+    getDetailData(rowId: string | number): GridRow[];
+    /** Expand a master row, triggering a load if not already cached. */
+    expand(masterRow: GridRow): void;
+    /** Collapse a master row; cached data is retained for re-expansion. */
+    collapse(masterRow: GridRow): void;
+    toggle(masterRow: GridRow): void;
+    /** Pre-fetch detail data without expanding (e.g. hover prefetch). */
+    prefetch(masterRow: GridRow): void;
+    /** Invalidate one row's cache, or the entire cache when rowId is omitted. */
+    invalidateCache(rowId?: string | number): void;
+    /** Collapse all expanded rows. Cache is preserved. */
+    collapseAll(): void;
+    /** A read-only snapshot of currently expanded row IDs. */
+    getExpandedIds(): ReadonlySet<string | number>;
+    private _rowId;
+    private _ensureLoaded;
+    private _notify;
+}
+
+export { ClipboardEngine, DataGridPro, FillHandleEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, SSRMEngine, TransactionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
+export type { Block, BlockState, CellEditCommand, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FormulaEngineOptions, GridRow, MasterDetailEngineOptions, PasteCommand, RangeSelectionEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };