@ricsam/formula-engine 0.0.16 → 0.0.18

package/dist/types/core/api/table-orm.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TableOrm - Object-Relational Mapping for table data
+ *
+ * Provides CRUD operations for table data with type-safe access.
+ * Used as the `this` context for custom table API methods.
+ */
+import type { FormulaEngine } from "../engine";
+import { type TableSchemaHeaders } from "./api-helpers";
+export declare class TableOrm<TItem extends Record<string, unknown>> {
+    private engine;
+    private workbookName;
+    private tableName;
+    private headers;
+    private namespace;
+    constructor(engine: FormulaEngine<any, any>, workbookName: string, tableName: string, headers: TableSchemaHeaders, namespace: string);
+    /**
+     * Get the table definition from the engine
+     */
+    private getTable;
+    /**
+     * Find the first row matching the filter
+     */
+    findWhere(filter: Partial<TItem>): TItem | undefined;
+    /**
+     * Find all rows matching the filter
+     */
+    findAllWhere(filter: Partial<TItem>): TItem[];
+    /**
+     * Append a new row to the table
+     */
+    append(item: TItem): TItem;
+    /**
+     * Update all rows matching the filter
+     * Returns the number of rows updated
+     */
+    updateWhere(filter: Partial<TItem>, update: Partial<TItem>): number;
+    /**
+     * Remove all rows matching the filter
+     * Returns the number of rows removed
+     */
+    removeWhere(filter: Partial<TItem>): number;
+    /**
+     * Get the count of data rows in the table
+     */
+    count(): number;
+}

package/dist/types/core/autofill-utils.d.ts

@@ -1,21 +1,14 @@
 /**
  * AutoFill class for handling spreadsheet autofill functionality
  */
-import type { CellAddress, SerializedCellValue, SpreadsheetRange } from "./types";
+import type { SpreadsheetRange } from "./types";
 import type { FillDirection } from "@ricsam/selection-manager";
 import type { WorkbookManager } from "./managers/workbook-manager";
 import type { StyleManager } from "./managers/style-manager";
 export declare class AutoFill {
     private workbookManager;
     private styleManager;
-    private engine;
-    constructor(workbookManager: WorkbookManager, styleManager: StyleManager, engine: {
-        setCellContent: (address: CellAddress, content: SerializedCellValue) => void;
-        setSheetContent: (opts: {
-            sheetName: string;
-            workbookName: string;
-        }, content: Map<string, SerializedCellValue>) => void;
-    });
+    constructor(workbookManager: WorkbookManager, styleManager: StyleManager);
     /**
      * Converts a SpreadsheetRange to FiniteSpreadsheetRange, throwing an error if infinite
      */
@@ -40,4 +33,8 @@ export declare class AutoFill {
      * Clears existing cell styles in fill range first (Excel behavior)
      */
     private fillStyles;
+    /**
+     * Copy metadata from seed range to fill range with pattern repetition
+     */
+    private fillMetadata;
 }

package/dist/types/core/cell-mover.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Information about cells being moved
+ */
+export interface MovedCellsInfo {
+    /**
+     * Set of cell keys in format "workbookName:sheetName:colIndex:rowIndex"
+     * for fast O(1) lookup
+     */
+    cellsSet: Set<string>;
+    /**
+     * Workbook name of the source cells (all moved cells must be in same workbook/sheet)
+     */
+    workbookName: string;
+    /**
+     * Sheet name of the source cells
+     */
+    sheetName: string;
+    /**
+     * Row offset for the move (targetRow - sourceRow)
+     */
+    rowOffset: number;
+    /**
+     * Column offset for the move (targetCol - sourceCol)
+     */
+    colOffset: number;
+}
+/**
+ * Updates cell and range references in a formula when cells are moved
+ *
+ * @param formula - The formula string (without the leading =)
+ * @param movedCells - Information about which cells were moved
+ * @returns The updated formula string, or the original if no changes were made
+ *
+ * @example
+ * // Moving A1 to D5 (offset: col+3, row+4)
+ * updateReferencesForMovedCells("A1+B1", {...}) // "D5+B1" (only A1 updated)
+ * updateReferencesForMovedCells("SUM(A1:D5)", {...}) // "SUM(E4:H9)" (if entire range moved)
+ */
+export declare function updateReferencesForMovedCells(formula: string, movedCells: MovedCellsInfo): string;
+/**
+ * Checks if a formula contains a reference to a specific cell
+ *
+ * @param formula - The formula string (without the leading =)
+ * @param workbookName - The workbook name
+ * @param sheetName - The sheet name
+ * @param colIndex - The column index
+ * @param rowIndex - The row index
+ * @returns True if the formula references the cell
+ */
+export declare function formulaReferencesCell(formula: string, workbookName: string, sheetName: string, colIndex: number, rowIndex: number): boolean;
+/**
+ * Checks if a formula contains a reference to a specific range
+ *
+ * @param formula - The formula string (without the leading =)
+ * @param workbookName - The workbook name
+ * @param sheetName - The sheet name
+ * @param startCol - Range start column
+ * @param startRow - Range start row
+ * @param endCol - Range end column
+ * @param endRow - Range end row
+ * @returns True if the formula references the range
+ */
+export declare function formulaReferencesRange(formula: string, workbookName: string, sheetName: string, startCol: number, startRow: number, endCol: number, endRow: number): boolean;

package/dist/types/core/commands/command-executor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * CommandExecutor - Executes commands with undo/redo support and schema validation
+ *
+ * Handles:
+ * - Command execution with optional re-evaluation
+ * - Schema validation after re-evaluation
+ * - Automatic rollback on validation failure
+ * - Undo/redo stacks
+ * - Action serialization for persistence
+ */
+import type { Declaration } from "../api/api";
+import type { EvaluationManager } from "../managers/evaluation-manager";
+import type { EventManager } from "../managers/event-manager";
+import type { EngineCommand, EngineAction, ExecuteOptions, SchemaValidationResult, SchemaValidationErrorInfo } from "./types";
+/**
+ * Error thrown when schema integrity validation fails.
+ * Contains all validation errors that occurred.
+ */
+export declare class SchemaIntegrityError extends Error {
+    errors: SchemaValidationErrorInfo[];
+    constructor(errors: SchemaValidationErrorInfo[]);
+}
+/**
+ * CommandExecutor manages command execution with validation and undo/redo support.
+ */
+export declare class CommandExecutor {
+    private apiDeclaration;
+    private evaluationManager;
+    private eventManager;
+    private validateAllSchemas;
+    private undoStack;
+    private redoStack;
+    private actionLog;
+    constructor(apiDeclaration: Declaration | undefined, evaluationManager: EvaluationManager, eventManager: EventManager, validateAllSchemas: () => SchemaValidationResult);
+    /**
+     * Execute a command with optional schema validation.
+     *
+     * @param command - The command to execute
+     * @param options - Execution options
+     * @throws SchemaIntegrityError if validation fails
+     */
+    execute(command: EngineCommand, options?: ExecuteOptions): void;
+    /**
+     * Undo the last command.
+     *
+     * @returns true if undo was performed, false if nothing to undo
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone command.
+     *
+     * @returns true if redo was performed, false if nothing to redo
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Get the action log for persistence/collaboration.
+     */
+    getActionLog(): EngineAction[];
+    /**
+     * Clear the action log.
+     */
+    clearActionLog(): void;
+    /**
+     * Clear undo/redo stacks.
+     */
+    clearHistory(): void;
+    /**
+     * Get the number of commands in the undo stack.
+     */
+    getUndoStackSize(): number;
+    /**
+     * Get the number of commands in the redo stack.
+     */
+    getRedoStackSize(): number;
+}

package/dist/types/core/commands/content-commands.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Content Commands - Commands that modify cell/sheet content
+ *
+ * These commands all require re-evaluation after execution.
+ */
+import type { WorkbookManager } from "../managers/workbook-manager";
+import type { CopyManager } from "../managers/copy-manager";
+import type { CellAddress, CopyCellsOptions, RangeAddress, SerializedCellValue } from "../types";
+import type { EngineCommand, EngineAction } from "./types";
+/**
+ * Command to set a single cell's content.
+ */
+export declare class SetCellContentCommand implements EngineCommand {
+    private workbookManager;
+    private address;
+    private newContent;
+    readonly requiresReevaluation = true;
+    private previousValue;
+    private hadPreviousValue;
+    constructor(workbookManager: WorkbookManager, address: CellAddress, newContent: SerializedCellValue);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to set an entire sheet's content.
+ */
+export declare class SetSheetContentCommand implements EngineCommand {
+    private workbookManager;
+    private opts;
+    private newContent;
+    readonly requiresReevaluation = true;
+    private previousContent;
+    constructor(workbookManager: WorkbookManager, opts: {
+        workbookName: string;
+        sheetName: string;
+    }, newContent: Map<string, SerializedCellValue>);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to clear a range of cells.
+ */
+export declare class ClearRangeCommand implements EngineCommand {
+    private workbookManager;
+    private address;
+    readonly requiresReevaluation = true;
+    private clearedCells;
+    constructor(workbookManager: WorkbookManager, address: RangeAddress);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to paste cells.
+ */
+export declare class PasteCellsCommand implements EngineCommand {
+    private workbookManager;
+    private copyManager;
+    private source;
+    private target;
+    private options;
+    readonly requiresReevaluation = true;
+    private targetSnapshots;
+    private sourceSnapshots;
+    constructor(workbookManager: WorkbookManager, copyManager: CopyManager, source: CellAddress[], target: CellAddress, options: CopyCellsOptions);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to fill areas with a seed range.
+ */
+export declare class FillAreasCommand implements EngineCommand {
+    private workbookManager;
+    private copyManager;
+    private seedRange;
+    private targetRanges;
+    private options;
+    readonly requiresReevaluation = true;
+    private targetSnapshots;
+    constructor(workbookManager: WorkbookManager, copyManager: CopyManager, seedRange: RangeAddress, targetRanges: RangeAddress[], options: CopyCellsOptions);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to move a single cell.
+ */
+export declare class MoveCellCommand implements EngineCommand {
+    private workbookManager;
+    private copyManager;
+    private source;
+    private target;
+    readonly requiresReevaluation = true;
+    private sourceSnapshot;
+    private targetSnapshot;
+    constructor(workbookManager: WorkbookManager, copyManager: CopyManager, source: CellAddress, target: CellAddress);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to move a range of cells.
+ */
+export declare class MoveRangeCommand implements EngineCommand {
+    private workbookManager;
+    private copyManager;
+    private sourceRange;
+    private target;
+    readonly requiresReevaluation = true;
+    private sourceSnapshots;
+    private targetSnapshots;
+    constructor(workbookManager: WorkbookManager, copyManager: CopyManager, sourceRange: RangeAddress, target: CellAddress);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to auto-fill ranges based on a seed pattern.
+ * Captures the entire affected area for undo.
+ */
+export declare class AutoFillCommand implements EngineCommand {
+    private workbookManager;
+    private styleManager;
+    private autoFillManager;
+    private opts;
+    private seedRange;
+    private fillRanges;
+    private direction;
+    readonly requiresReevaluation = true;
+    private previousContent;
+    private previousMetadata;
+    constructor(workbookManager: WorkbookManager, styleManager: import("../managers/style-manager").StyleManager, autoFillManager: import("../autofill-utils").AutoFill, opts: {
+        sheetName: string;
+        workbookName: string;
+    }, seedRange: import("../types").SpreadsheetRange, fillRanges: import("../types").SpreadsheetRange[], direction: import("@ricsam/selection-manager").FillDirection);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Commands Module - Command Pattern implementation for FormulaEngine
+ *
+ * This module provides:
+ * - EngineCommand interface for all commands
+ * - CommandExecutor for execution with undo/redo and schema validation
+ * - All command implementations organized by category
+ */
+export * from "./types";
+export { CommandExecutor, SchemaIntegrityError } from "./command-executor";
+export { SetCellContentCommand, SetSheetContentCommand, ClearRangeCommand, PasteCellsCommand, FillAreasCommand, MoveCellCommand, MoveRangeCommand, AutoFillCommand, } from "./content-commands";
+export { AddWorkbookCommand, RemoveWorkbookCommand, RenameWorkbookCommand, CloneWorkbookCommand, AddSheetCommand, RemoveSheetCommand, RenameSheetCommand, type StructureCommandDeps, } from "./structure-commands";
+export { AddTableCommand, RemoveTableCommand, RenameTableCommand, UpdateTableCommand, ResetTablesCommand, type TableCommandDeps, } from "./table-commands";
+export { AddNamedExpressionCommand, RemoveNamedExpressionCommand, UpdateNamedExpressionCommand, RenameNamedExpressionCommand, SetNamedExpressionsCommand, type NamedExpressionCommandDeps, } from "./named-expression-commands";
+export { SetCellMetadataCommand, SetSheetMetadataCommand, SetWorkbookMetadataCommand, } from "./metadata-commands";
+export { AddConditionalStyleCommand, RemoveConditionalStyleCommand, AddCellStyleCommand, RemoveCellStyleCommand, ClearCellStylesCommand, } from "./style-commands";

package/dist/types/core/commands/metadata-commands.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Metadata Commands - Commands that modify cell/sheet/workbook metadata
+ *
+ * These commands do NOT require re-evaluation after execution.
+ * They only affect metadata, not cell values or formulas.
+ */
+import type { WorkbookManager } from "../managers/workbook-manager";
+import type { CellAddress } from "../types";
+import type { EngineCommand, EngineAction } from "./types";
+/**
+ * Command to set cell metadata.
+ */
+export declare class SetCellMetadataCommand<TMetadata = unknown> implements EngineCommand {
+    private workbookManager;
+    private address;
+    private newMetadata;
+    readonly requiresReevaluation = false;
+    private previousMetadata;
+    private hadPreviousMetadata;
+    constructor(workbookManager: WorkbookManager, address: CellAddress, newMetadata: TMetadata | undefined);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to set sheet metadata.
+ */
+export declare class SetSheetMetadataCommand<TMetadata = unknown> implements EngineCommand {
+    private workbookManager;
+    private opts;
+    private newMetadata;
+    readonly requiresReevaluation = false;
+    private previousMetadata;
+    constructor(workbookManager: WorkbookManager, opts: {
+        workbookName: string;
+        sheetName: string;
+    }, newMetadata: TMetadata);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to set workbook metadata.
+ */
+export declare class SetWorkbookMetadataCommand<TMetadata = unknown> implements EngineCommand {
+    private workbookManager;
+    private workbookName;
+    private newMetadata;
+    readonly requiresReevaluation = false;
+    private previousMetadata;
+    constructor(workbookManager: WorkbookManager, workbookName: string, newMetadata: TMetadata);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}

package/dist/types/core/commands/named-expression-commands.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Named Expression Commands - Commands that modify named expressions
+ *
+ * These commands all require re-evaluation after execution.
+ */
+import type { NamedExpressionManager } from "../managers/named-expression-manager";
+import type { WorkbookManager } from "../managers/workbook-manager";
+import type { NamedExpression } from "../types";
+import type { EngineCommand, EngineAction } from "./types";
+/**
+ * Dependencies needed for named expression commands.
+ */
+export interface NamedExpressionCommandDeps {
+    namedExpressionManager: NamedExpressionManager;
+    workbookManager: WorkbookManager;
+    renameNamedExpressionInFormula: (formula: string, oldName: string, newName: string) => string;
+}
+/**
+ * Command to add a named expression.
+ */
+export declare class AddNamedExpressionCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    constructor(deps: NamedExpressionCommandDeps, opts: {
+        expression: string;
+        expressionName: string;
+        sheetName?: string;
+        workbookName?: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to remove a named expression.
+ */
+export declare class RemoveNamedExpressionCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    private removedExpression;
+    constructor(deps: NamedExpressionCommandDeps, opts: {
+        expressionName: string;
+        sheetName?: string;
+        workbookName?: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to update a named expression.
+ */
+export declare class UpdateNamedExpressionCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    private previousExpression;
+    constructor(deps: NamedExpressionCommandDeps, opts: {
+        expression: string;
+        expressionName: string;
+        sheetName?: string;
+        workbookName?: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to rename a named expression.
+ */
+export declare class RenameNamedExpressionCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    constructor(deps: NamedExpressionCommandDeps, opts: {
+        expressionName: string;
+        sheetName?: string;
+        workbookName?: string;
+        newName: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Options for setNamedExpressions command.
+ */
+type SetNamedExpressionsOpts = ({
+    type: "global";
+} | {
+    type: "sheet";
+    sheetName: string;
+    workbookName: string;
+} | {
+    type: "workbook";
+    workbookName: string;
+}) & {
+    expressions: Map<string, NamedExpression>;
+};
+/**
+ * Command to set named expressions (replace all at a scope).
+ */
+export declare class SetNamedExpressionsCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    private previousExpressions;
+    constructor(deps: NamedExpressionCommandDeps, opts: SetNamedExpressionsOpts);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+export {};

package/dist/types/core/commands/structure-commands.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Structure Commands - Commands that modify workbook/sheet structure
+ *
+ * These commands all require re-evaluation after execution.
+ */
+import type { ApiSchemaManager } from "../managers/api-schema-manager";
+import type { NamedExpressionManager } from "../managers/named-expression-manager";
+import type { ReferenceManager } from "../managers/reference-manager";
+import type { StyleManager } from "../managers/style-manager";
+import type { TableManager } from "../managers/table-manager";
+import type { WorkbookManager } from "../managers/workbook-manager";
+import type { EngineAction, EngineCommand } from "./types";
+/**
+ * Dependencies needed for structure commands.
+ */
+export interface StructureCommandDeps {
+    workbookManager: WorkbookManager;
+    namedExpressionManager: NamedExpressionManager;
+    tableManager: TableManager;
+    styleManager: StyleManager;
+    referenceManager: ReferenceManager;
+    apiSchemaManager: ApiSchemaManager;
+    renameSheetInFormula: (opts: {
+        formula: string;
+        oldSheetName: string;
+        newSheetName: string;
+    }) => string;
+    renameWorkbookInFormula: (opts: {
+        formula: string;
+        oldWorkbookName: string;
+        newWorkbookName: string;
+    }) => string;
+}
+/**
+ * Command to add a workbook.
+ */
+export declare class AddWorkbookCommand implements EngineCommand {
+    private deps;
+    private workbookName;
+    readonly requiresReevaluation = true;
+    constructor(deps: StructureCommandDeps, workbookName: string);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to remove a workbook.
+ */
+export declare class RemoveWorkbookCommand implements EngineCommand {
+    private deps;
+    private workbookName;
+    readonly requiresReevaluation = true;
+    private snapshot;
+    constructor(deps: StructureCommandDeps, workbookName: string);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to rename a workbook.
+ */
+export declare class RenameWorkbookCommand implements EngineCommand {
+    private deps;
+    private workbookName;
+    private newWorkbookName;
+    readonly requiresReevaluation = true;
+    constructor(deps: StructureCommandDeps, workbookName: string, newWorkbookName: string);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to clone a workbook.
+ * Undo simply removes the cloned workbook.
+ */
+export declare class CloneWorkbookCommand implements EngineCommand {
+    private deps;
+    private fromWorkbookName;
+    private toWorkbookName;
+    readonly requiresReevaluation = true;
+    constructor(deps: StructureCommandDeps, fromWorkbookName: string, toWorkbookName: string);
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to add a sheet.
+ */
+export declare class AddSheetCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    constructor(deps: StructureCommandDeps, opts: {
+        workbookName: string;
+        sheetName: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to remove a sheet.
+ */
+export declare class RemoveSheetCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    private snapshot;
+    constructor(deps: StructureCommandDeps, opts: {
+        workbookName: string;
+        sheetName: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}
+/**
+ * Command to rename a sheet.
+ */
+export declare class RenameSheetCommand implements EngineCommand {
+    private deps;
+    private opts;
+    readonly requiresReevaluation = true;
+    constructor(deps: StructureCommandDeps, opts: {
+        workbookName: string;
+        sheetName: string;
+        newSheetName: string;
+    });
+    execute(): void;
+    undo(): void;
+    toAction(): EngineAction;
+}