@ricsam/formula-engine 0.2.13 → 0.2.15

package/dist/types/core/engine-snapshot.d.ts

@@ -16,6 +16,18 @@ export type StyleManagerSnapshot = {
 };
 export type RangeMetadataManagerSnapshot = RangeMetadata[];
 export type ReferenceManagerSnapshot = Map<string, TrackedReference>;
+export type EngineHistorySnapshotManagers = {
+    workbook: WorkbookManagerSnapshot;
+    namedExpression: NamedExpressionManagerSnapshot;
+    table: TableManagerSnapshot;
+    style: StyleManagerSnapshot;
+    rangeMetadata: RangeMetadataManagerSnapshot;
+    reference: ReferenceManagerSnapshot;
+};
+export type EngineHistorySnapshot = {
+    version: typeof ENGINE_SNAPSHOT_VERSION;
+    managers: EngineHistorySnapshotManagers;
+};
 export type SerializedValueEvaluationResultSnapshot = {
     type: "value";
     result: CellValue;
@@ -120,13 +132,7 @@ export type CacheManagerSnapshot = {
         scc: SerializedSCCSnapshot;
     }>;
 };
-type EngineSnapshotManagers = {
-    workbook: WorkbookManagerSnapshot;
-    namedExpression: NamedExpressionManagerSnapshot;
-    table: TableManagerSnapshot;
-    style: StyleManagerSnapshot;
-    rangeMetadata: RangeMetadataManagerSnapshot;
-    reference: ReferenceManagerSnapshot;
+type EngineSnapshotManagers = EngineHistorySnapshotManagers & {
     dependency: DependencyManagerSnapshot;
     cache: CacheManagerSnapshot;
 };

package/dist/types/core/engine.d.ts

@@ -2,7 +2,7 @@
  * Main FormulaEngine class
  * Core API implementation for spreadsheet calculations
  */
-import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type NamedExpression, type RangeAddress, type RangeMetadata, type RangeMetadataInput, type ReplaceChange, type ReplaceTarget, type SearchMatch, type SearchOptions, type SerializedCellValue, type Sheet, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
+import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type FormulaEngineOptions, type NamedExpression, type RangeAddress, type RangeMetadata, type RangeMetadataInput, type ReplaceChange, type ReplaceTarget, type SearchMatch, type SearchOptions, type SerializedCellValue, type Sheet, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition, type UndoRedoState } from "./types";
 import type { FillDirection } from "@ricsam/selection-manager";
 import { AutoFill } from "./autofill-utils";
 import { WorkbookManager } from "./managers/workbook-manager";
@@ -36,6 +36,8 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
     private rangeMetadataManager;
     private copyManager;
     private referenceManager;
+    private undoRedoManager;
+    private historyCheckpointDepth;
     /**
      * Public access to the store manager for testing
      */
@@ -48,14 +50,22 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
     _dependencyManager: DependencyManager;
     _styleManager: StyleManager;
     _rangeMetadataManager: RangeMetadataManager<MetadataType<TMetadata, "range">>;
-    constructor();
+    constructor(options?: FormulaEngineOptions);
     /**
      * Static factory method to build an empty engine
      * @template TMetadata - Consumer-defined metadata shape with optional cell, sheet, and workbook entries.
      */
-    static buildEmpty<TMetadata extends Metadata = Metadata>(): FormulaEngine<TMetadata>;
+    static buildEmpty<TMetadata extends Metadata = Metadata>(options?: FormulaEngineOptions): FormulaEngine<TMetadata>;
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getUndoRedoState(): UndoRedoState;
+    clearUndoRedoHistory(): void;
+    transact<T>(callback: () => T): T;
     private emitMutation;
     private emitUpdate;
+    private withUndoRedoCheckpoint;
     private getExistingSheetContent;
     private getWorkbookResourceKeys;
     private getSheetResourceKeys;
@@ -522,8 +532,13 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
     };
     onUpdate(listener: () => void): () => void;
     private buildSerializedSnapshot;
+    private buildHistorySnapshot;
+    private serializeHistorySnapshot;
     private buildNamedExpressionSnapshot;
     serializeEngine(): string;
+    private assertSupportedSnapshot;
+    private restoreDataManagersFromSnapshot;
+    private restoreHistorySnapshot;
     resetToSerializedEngine(data: string): void;
 }
 export {};

package/dist/types/core/managers/undo-redo-manager.d.ts

@@ -0,0 +1,16 @@
+import type { UndoRedoOptions, UndoRedoState } from "../types";
+export declare class UndoRedoManager {
+    private undoStack;
+    private redoStack;
+    readonly maxDepth: number;
+    constructor(options: UndoRedoOptions | undefined);
+    canUndo(): boolean;
+    canRedo(): boolean;
+    recordMutation(before: string, after: string): void;
+    popUndo(): string | undefined;
+    popRedo(): string | undefined;
+    pushUndo(snapshot: string): void;
+    pushRedo(snapshot: string): void;
+    clear(): void;
+    getState(): UndoRedoState;
+}

package/dist/types/core/managers/workbook-manager.d.ts

@@ -99,6 +99,8 @@ export declare class WorkbookManager {
     private resolveSearchScope;
     private getStringContentKind;
     private findMatchesInString;
+    private normalizeSearchMaxResults;
+    private iterateStringCellsInSearchOrder;
     private buildSearchMatchesInScope;
     search(query: string, options?: SearchOptions): SearchMatch[];
     private buildReplacedContent;

package/dist/types/core/types.d.ts

@@ -7,6 +7,27 @@ import type { FormulaEvaluator } from "../evaluator/formula-evaluator";
 import type { FunctionNode } from "../parser/ast";
 import type { DependencyNode } from "./managers/dependency-node";
 import type { LookupOrder } from "./managers/range-eval-order-builder";
+export interface UndoRedoOptions {
+    /**
+     * Maximum number of undo entries retained by the engine.
+     * @default 100
+     */
+    maxDepth?: number;
+}
+export interface FormulaEngineOptions {
+    /**
+     * Configure engine-level undo/redo history. History is always enabled.
+     */
+    undoRedo?: UndoRedoOptions;
+}
+export interface UndoRedoState {
+    enabled: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoDepth: number;
+    redoDepth: number;
+    maxDepth: number;
+}
 export interface CellAddress {
     sheetName: string;
     workbookName: string;
@@ -80,10 +101,18 @@ export type CellValue = CellNumber | CellString | CellBoolean | CellInfinity;
  * any empty values are deleted from the sheet content
  */
 export type SerializedCellValue = string | number | boolean | undefined;
+export declare const DEFAULT_SEARCH_MAX_RESULTS = 1000;
 export interface SearchOptions {
     workbookName?: string;
     sheetName?: string;
     caseSensitive?: boolean;
+    /**
+     * Maximum number of matches returned by search(). Defaults to
+     * DEFAULT_SEARCH_MAX_RESULTS to keep interactive UIs from materializing
+     * enormous result sets. Pass Number.POSITIVE_INFINITY for an unbounded search.
+     * replaceAll() ignores this option and always replaces all matches in scope.
+     */
+    maxResults?: number;
 }
 export interface SearchMatch {
     workbookName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/formula-engine",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "module": "./dist/mjs/lib.mjs",
   "scripts": {
     "test": "bun test",