@gridengine/angular-datagrid-enterprise 0.3.0 → 0.5.0

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

@@ -308,5 +308,345 @@ declare class FormulaEngine {
     isValidFormula(formula: string): boolean;
 }
 
-export { ClipboardEngine, DataGridPro, FillHandleEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
-export type { CellEditCommand, CellRange, ClipboardEngineOptions, DeleteCommand, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FormulaEngineOptions, PasteCommand, RangeSelectionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };
+/** 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;
+}
+
+/**
+ * CellPermissionEngine — enforces per-cell read/edit permissions from a
+ * caller-supplied policy. Unreadable cells are masked ('●●●') everywhere
+ * (display, export, clipboard); non-editable cells can't be edited regardless
+ * of the column's `editable`. Results are cached per (rowId, field). Pure logic.
+ */
+
+interface CellPermission {
+    canRead: boolean;
+    canEdit: boolean;
+}
+/** Default mask string used for unreadable cells. */
+declare const DEFAULT_MASK = "\u25CF\u25CF\u25CF";
+interface CellPermissionEngineOptions {
+    /** Policy returning permissions for a cell; called once per (rowId, field). */
+    policy: (row: GridRow, field: string) => CellPermission;
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    /** String shown in place of unreadable cell values. Default: '●●●' */
+    maskValue?: string;
+}
+declare class CellPermissionEngine {
+    private readonly _policy;
+    private readonly _rowIdField;
+    private readonly _maskValue;
+    private readonly _cache;
+    constructor(options: CellPermissionEngineOptions);
+    /** The resolved permission for a cell (cached). */
+    getPermission(row: GridRow, field: string): CellPermission;
+    canRead(row: GridRow, field: string): boolean;
+    canEdit(row: GridRow, field: string): boolean;
+    /** The display value for a cell, masked when not readable. */
+    getDisplayValue(row: GridRow, field: string): unknown;
+    /** The value for copy/export; unreadable cells return '' so data never leaks. */
+    getExportValue(row: GridRow, field: string): unknown;
+    /** True if the given value is the mask placeholder. */
+    isMasked(value: unknown): boolean;
+    get maskValue(): string;
+    /** Clear one row's cached permissions, or the whole cache when omitted. */
+    clearCache(rowId?: string | number): void;
+    private _key;
+}
+
+/**
+ * AuditTrailEngine — records an immutable log of every cell edit (who/what/when
+ * + prev/next values) in a bounded in-memory ring buffer, emitting each entry
+ * via `onEntry` for persistence. Pure logic.
+ */
+interface AuditEntry {
+    timestamp: number;
+    userId: string | undefined;
+    rowId: string | number;
+    field: string;
+    prevValue: unknown;
+    nextValue: unknown;
+}
+interface AuditTrailEngineOptions {
+    /** User identifier stamped on every entry. */
+    userId?: string;
+    /** Called for every new entry — persist to a server here. */
+    onEntry?: (entry: AuditEntry) => void;
+    /** Maximum entries retained in memory (oldest evicted first). Default: 1000 */
+    maxEntries?: number;
+    /** Injectable clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}
+declare class AuditTrailEngine {
+    private readonly _userId?;
+    private readonly _onEntry?;
+    private readonly _maxEntries;
+    private readonly _now;
+    private _entries;
+    private _onChange?;
+    constructor(options?: AuditTrailEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Record a cell edit; no-op edits (prev === next) return null. */
+    record(rowId: string | number, field: string, prevValue: unknown, nextValue: unknown): AuditEntry | null;
+    /** All entries, oldest first (read-only snapshot). */
+    getEntries(): readonly AuditEntry[];
+    /** Entries for a specific row, oldest first. */
+    getEntriesForRow(rowId: string | number): AuditEntry[];
+    /** Entries for a specific cell (row + field), oldest first. */
+    getEntriesForCell(rowId: string | number, field: string): AuditEntry[];
+    get size(): number;
+    /** Discard all entries. */
+    clear(): void;
+    private _notify;
+}
+
+/**
+ * RowLockEngine — tracks which rows are locked (by other users) so the grid can
+ * show a lock indicator and block edits. Supports an async source of locks
+ * (e.g. polled from a collaboration server) plus optimistic local lock/unlock.
+ * Pure logic.
+ */
+
+interface LockedRow {
+    rowId: string | number;
+    lockedByUserId: string;
+    lockedByDisplayName?: string;
+    lockedAt: number;
+}
+interface RowLockEngineOptions {
+    /** The current user's ID. Locks held by this user do not block editing. */
+    currentUserId?: string;
+    /** Async source of currently locked rows (server state). */
+    getLockedRows?: () => Promise<LockedRow[]>;
+    /** Called when the current user attempts to edit a row locked by someone else. */
+    onLockConflict?: (row: GridRow, lockedBy: string) => void;
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    /** Injectable clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}
+declare class RowLockEngine {
+    private readonly _currentUserId?;
+    private readonly _getLockedRows?;
+    private readonly _onLockConflict?;
+    private readonly _rowIdField;
+    private readonly _now;
+    private _locks;
+    private _onChange?;
+    constructor(options?: RowLockEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Load locks from the async source and replace local state. */
+    refresh(): Promise<void>;
+    /** Optimistically lock a row for a user. */
+    lockRow(rowId: string | number, userId: string, displayName?: string): void;
+    /** Remove a lock. */
+    unlockRow(rowId: string | number): void;
+    /** Remove all locks. */
+    clear(): void;
+    /** The lock for a row, or undefined if unlocked. */
+    getLock(rowId: string | number): LockedRow | undefined;
+    /** True if the row is locked by anyone. */
+    isLocked(rowId: string | number): boolean;
+    /** True if the row is locked by someone OTHER than the current user. */
+    isLockedByOther(rowId: string | number): boolean;
+    /** All current locks. */
+    getLocks(): LockedRow[];
+    get size(): number;
+    /**
+     * Whether the row may be edited by the current user. If it's locked by
+     * another user, fires `onLockConflict` and returns false.
+     */
+    canEditRow(row: GridRow): boolean;
+    private _rowId;
+    private _notify;
+}
+
+export { AuditTrailEngine, CellPermissionEngine, ClipboardEngine, DEFAULT_MASK, DataGridPro, FillHandleEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, RowLockEngine, SSRMEngine, TransactionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
+export type { AuditEntry, AuditTrailEngineOptions, Block, BlockState, CellEditCommand, CellPermission, CellPermissionEngineOptions, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FormulaEngineOptions, GridRow, LockedRow, MasterDetailEngineOptions, PasteCommand, RangeSelectionEngineOptions, RowLockEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };