Audit History

Module Extensions

HTMLRevoGridElement (Extended from @revolist/revogrid)

interface HTMLRevoGridElement {
  auditHistory?: AuditHistoryConfig
}

---

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  /**
       * @deprecated Use the direct `grid.auditHistory` property instead.
       */
      auditHistory?: AuditHistoryConfig
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  auditrecord: AuditRecord;
  auditrecordsloaded: AuditRecord[];
  auditerror: AuditHistoryError;
  beforeauditrestore: AuditRestoreEvent;
  auditrestore: AuditRestoreEvent
}

Plugin API

AuditHistoryPlugin

Dependencies

• Required EventManagerPlugin: Requires EventManagerPlugin to receive normalized edit and paste events.
• Event integration HistoryPlugin: Integrates with HistoryPlugin undo and redo events when present.

class AuditHistoryPlugin {
  getRecords(filter?: AuditHistoryFilter): AuditRecord[];

  getCellHistory(rowId: string | number, column: ColumnProp): AuditRecord[];

  getRowHistory(rowId: string | number): AuditRecord[];

  getRecord(id: string): AuditRecord | undefined;

  getTransaction(transactionId: string): AuditRecord[];

  getLastChange(rowId: string | number, column?: ColumnProp): AuditChange | undefined;

  getStats(filter?: AuditHistoryFilter): AuditHistoryStats;

  getRowIdentity(row: DataType | undefined, rowIndex: number, rowType: DimensionRows): string | undefined;

  clear(): boolean;

  replaceRecords(records: AuditRecord[], options:;

  async refreshRecords(options:;

  exportRecords(options: AuditHistoryExportOptions =;

  canRestoreRecord(context: AuditHistoryRestoreContext): boolean;

  restoreCell(change: AuditChange): boolean;

  restoreRow(recordOrRowId: AuditRecord | string | number): boolean;

  restoreTransaction(transactionId: string): boolean;
}

---

AuditUser

export type AuditUser = {
  id: string;
  name?: string;
  email?: string;
};

---

AuditActionType

export type AuditActionType =
  | 'cell-change'
  | 'bulk-paste'
  | 'row-added'
  | 'row-deleted'
  | 'row-restored'
  | 'undo'
  | 'redo'
  | 'restore-cell'
  | 'restore-row'
  | 'restore-transaction';

---

AuditChange

export type AuditChange = {
  id: string;
  rowId?: string;
  rowIndex?: number;
  rowType: DimensionRows;
  column?: ColumnProp;
  oldValue?: unknown;
  newValue?: unknown;
  oldRow?: DataType;
  newRow?: DataType;
  metadata?: Record<string, unknown>;
};

---

AuditRecord

export type AuditRecord = {
  id: string;
  transactionId: string;
  type: AuditActionType;
  changedAt: string;
  changedBy: AuditUser;
  changes: AuditChange[];
  metadata?: Record<string, unknown>;
};

---

AuditHistoryFilter

export type AuditHistoryFilter = {
  rowId?: string | number;
  column?: ColumnProp;
  userId?: string;
  userEmail?: string;
  actionType?: AuditActionType;
  transactionId?: string;
  dateFrom?: string | Date;
  dateTo?: string | Date;
};

---

AuditHistoryStorageAdapter

export type AuditHistoryStorageAdapter = {
  load?: () => AuditRecord[] | Promise<AuditRecord[]>;
  save?: (records: AuditRecord[]) => void | Promise<void>;
  append?: (record: AuditRecord, records: AuditRecord[]) => void | Promise<void>;
  clear?: () => void | Promise<void>;
};

---

AuditHistoryError

export type AuditHistoryError = {
  phase:
    | 'get-current-user'
    | 'metadata'
    | 'sanitize'
    | 'storage-load'
    | 'storage-save'
    | 'storage-append'
    | 'storage-clear'
    | 'on-record'
    | 'restore'
    | 'export'
    | 'replace-records';
  error: unknown;
  record?: AuditRecord;
};

---

AuditHistoryRestoreContext

export type AuditHistoryRestoreContext = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};

---

AuditHistoryStats

export type AuditHistoryStats = {
  totalRecords: number;
  totalChanges: number;
  firstChangedAt?: string;
  lastChangedAt?: string;
  byType: Partial<Record<AuditActionType, number>>;
  byUser: Record<string, number>;
};

---

AuditHistoryExportFormat

export type AuditHistoryExportFormat = 'json' | 'csv';

---

AuditHistoryExportOptions

export type AuditHistoryExportOptions = {
  format?: AuditHistoryExportFormat;
  filter?: AuditHistoryFilter;
  includeMetadata?: boolean;
};

---

AuditHistoryConfig

export type AuditHistoryConfig = {
  getCurrentUser?: () => AuditUser;
  getMetadata?: (context: { type: AuditActionType; changes: AuditChange[] }) => Record<string, unknown> | undefined;
  rowIdProp?: string;
  getRowId?: (
    row: DataType,
    context: { rowIndex: number; rowType: DimensionRows },
  ) => string | number | undefined;
  sanitizeValue?: (
    value: unknown,
    context: {
      rowId?: string;
      rowIndex?: number;
      rowType: DimensionRows;
      column?: ColumnProp;
      direction: 'old' | 'new';
    },
  ) => unknown;
  shouldTrackChange?: (
    change: Omit<AuditChange, 'id'>,
    context: { type: AuditActionType },
  ) => boolean;
  ignoredColumns?: ColumnProp[] | ((context: { column?: ColumnProp; rowType: DimensionRows; rowId?: string }) => boolean);
  captureSourceUpdates?: boolean;
  immutable?: boolean;
  canRestore?: (context: AuditHistoryRestoreContext) => boolean;
  storage?: 'memory' | 'localStorage' | 'custom';
  storageKey?: string;
  storageAdapter?: AuditHistoryStorageAdapter;
  records?: AuditRecord[];
  maxRecords?: number;
  disabled?: boolean;
  onAuditRecord?: (record: AuditRecord) => void | Promise<void>;
  onAuditError?: (error: AuditHistoryError) => void;
  onRecordsLoaded?: (records: AuditRecord[]) => void;
};

---

AuditRestoreType

export type AuditRestoreType = 'cell' | 'row' | 'transaction';

---

AuditRestoreEvent

export type AuditRestoreEvent = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};

---

defineAuditHistoryPanel

Renders the Audit History panel into el for the given RevoGrid element.

The grid must have AuditHistoryPlugin installed.

export function defineAuditHistoryPanel(el: HTMLElement, grid: HTMLRevoGridElement, options?: AuditHistoryPanelOptions): void;

---

AuditHistoryPanelOptions

export type AuditHistoryPanelOptions = {
  pageSize?: number;
  allowExport?: boolean;
};

---

cloneValue

export function cloneValue<T>(value: T): T;

---

cloneChange

export function cloneChange(change: AuditChange): AuditChange;

---

cloneRecord

export function cloneRecord(record: AuditRecord): AuditRecord;

---

normalizeRowId

export function normalizeRowId(rowId: string | number | undefined): string | undefined;

---

toTime

export function toTime(value: string | Date | undefined, fallback: number);

---

shouldIncludeRecord

export function shouldIncludeRecord(record: AuditRecord, filter?: AuditHistoryFilter);

---

trimRecords

export function trimRecords(records: AuditRecord[], maxRecords: number): AuditRecord[];

---

mergeRecords

export function mergeRecords(current: AuditRecord[], next: AuditRecord[]): AuditRecord[];

---

createAuditStats

export function createAuditStats(records: AuditRecord[], filter?: AuditHistoryFilter): AuditHistoryStats;

---

stringifyExportValue

export function stringifyExportValue(value: unknown): string;

---

exportAuditRecords

export function exportAuditRecords(records: AuditRecord[], options: AuditHistoryExportOptions =;