@ricsam/formula-engine 0.2.8 → 0.2.10

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

@@ -1,119 +0,0 @@
-/**
- * Table Commands - Commands that modify table definitions
- *
- * These commands all require re-evaluation after execution.
- */
-import type { TableManager } from "../managers/table-manager";
-import type { NamedExpressionManager } from "../managers/named-expression-manager";
-import type { WorkbookManager } from "../managers/workbook-manager";
-import type { SchemaManager } from "../managers/schema-manager";
-import type { CellAddress, SerializedCellValue, SpreadsheetRangeEnd, TableDefinition } from "../types";
-import type { EngineCommand, EngineAction, MutationInvalidation } from "./types";
-/**
- * Dependencies needed for table commands.
- */
-export interface TableCommandDeps {
-    tableManager: TableManager;
-    namedExpressionManager: NamedExpressionManager;
-    workbookManager: WorkbookManager;
-    apiSchemaManager: SchemaManager;
-    getCellValue: (cellAddress: CellAddress) => SerializedCellValue;
-    renameTableInFormula: (formula: string, oldName: string, newName: string) => string;
-}
-/**
- * Command to add a table.
- */
-export declare class AddTableCommand implements EngineCommand {
-    private deps;
-    private props;
-    readonly requiresReevaluation = true;
-    private executeFootprint;
-    private undoFootprint;
-    constructor(deps: TableCommandDeps, props: {
-        tableName: string;
-        sheetName: string;
-        workbookName: string;
-        start: string;
-        numRows: SpreadsheetRangeEnd;
-        numCols: number;
-    });
-    execute(): void;
-    undo(): void;
-    getInvalidationFootprint(phase: "execute" | "undo"): MutationInvalidation;
-    toAction(): EngineAction;
-}
-/**
- * Command to remove a table.
- */
-export declare class RemoveTableCommand implements EngineCommand {
-    private deps;
-    private opts;
-    readonly requiresReevaluation = true;
-    private removedTable;
-    private executeFootprint;
-    private undoFootprint;
-    constructor(deps: TableCommandDeps, opts: {
-        tableName: string;
-        workbookName: string;
-    });
-    execute(): void;
-    undo(): void;
-    getInvalidationFootprint(phase: "execute" | "undo"): MutationInvalidation;
-    toAction(): EngineAction;
-}
-/**
- * Command to rename a table.
- */
-export declare class RenameTableCommand implements EngineCommand {
-    private deps;
-    private workbookName;
-    private oldName;
-    private newName;
-    readonly requiresReevaluation = true;
-    private executeFootprint;
-    private undoFootprint;
-    constructor(deps: TableCommandDeps, workbookName: string, oldName: string, newName: string);
-    execute(): void;
-    undo(): void;
-    getInvalidationFootprint(phase: "execute" | "undo"): MutationInvalidation;
-    toAction(): EngineAction;
-}
-/**
- * Command to update a table.
- */
-export declare class UpdateTableCommand implements EngineCommand {
-    private deps;
-    private opts;
-    readonly requiresReevaluation = true;
-    private previousTable;
-    private executeFootprint;
-    private undoFootprint;
-    constructor(deps: TableCommandDeps, opts: {
-        tableName: string;
-        sheetName?: string;
-        start?: string;
-        numRows?: SpreadsheetRangeEnd;
-        numCols?: number;
-        workbookName: string;
-    });
-    execute(): void;
-    undo(): void;
-    getInvalidationFootprint(phase: "execute" | "undo"): MutationInvalidation;
-    toAction(): EngineAction;
-}
-/**
- * Command to reset all tables.
- */
-export declare class ResetTablesCommand implements EngineCommand {
-    private deps;
-    private newTables;
-    readonly requiresReevaluation = true;
-    private previousTables;
-    private executeFootprint;
-    private undoFootprint;
-    constructor(deps: TableCommandDeps, newTables: Map<string, Map<string, TableDefinition>>);
-    execute(): void;
-    undo(): void;
-    getInvalidationFootprint(phase: "execute" | "undo"): MutationInvalidation;
-    toAction(): EngineAction;
-}

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

@@ -1,143 +0,0 @@
-/**
- * Command Pattern Types for FormulaEngine
- *
- * Commands encapsulate all mutating operations on the engine,
- * enabling undo/redo, schema validation with rollback, and action serialization.
- */
-import type { CellAddress, SerializedCellValue } from "../types";
-export type CellContentKind = "empty" | "scalar" | "formula";
-export type RemovedScope = {
-    type: "workbook";
-    workbookName: string;
-} | {
-    type: "sheet";
-    workbookName: string;
-    sheetName: string;
-};
-export type MutationInvalidation = {
-    touchedCells: Array<{
-        address: CellAddress;
-        beforeKind: CellContentKind;
-        afterKind: CellContentKind;
-    }>;
-    /**
-     * Cells whose table membership or implicit current-row table context changed
-     * without necessarily changing their formula text.
-     */
-    tableContextChangedCells?: CellAddress[];
-    resourceKeys: string[];
-    removedScopes?: RemovedScope[];
-};
-export declare function getSerializedCellValueKind(value: SerializedCellValue | undefined): CellContentKind;
-export declare function emptyMutationInvalidation(): MutationInvalidation;
-/**
- * Serializable action representation of a command.
- * Used for persistence, collaboration, and changelog functionality.
- */
-export interface EngineAction {
-    type: string;
-    payload: unknown;
-    timestamp?: number;
-}
-/**
- * Base interface for all engine commands.
- */
-export interface EngineCommand {
-    /**
-     * Whether this command affects cell values/formulas and requires re-evaluation.
-     * Commands that only affect metadata or styles don't need re-evaluation.
-     */
-    readonly requiresReevaluation: boolean;
-    /**
-     * Returns the exact mutation footprint for the last execute/undo pass.
-     */
-    getInvalidationFootprint?(phase: "execute" | "undo"): MutationInvalidation;
-    /**
-     * Execute the command (forward operation).
-     */
-    execute(): void;
-    /**
-     * Undo the command (reverse operation).
-     */
-    undo(): void;
-    /**
-     * Convert the command to a serializable action for persistence/collaboration.
-     */
-    toAction(): EngineAction;
-}
-/**
- * Options for command execution.
- */
-export interface ExecuteOptions {
-    /**
-     * Whether to validate schema constraints after execution.
-     * Only applies to commands that require re-evaluation.
-     */
-    validate?: boolean;
-    /**
-     * Whether to skip adding to undo stack (for internal use).
-     */
-    skipUndoStack?: boolean;
-    /**
-     * Whether to skip emitting update events.
-     */
-    skipEmitUpdate?: boolean;
-}
-/**
- * Result of schema validation.
- */
-export interface SchemaValidationResult {
-    valid: boolean;
-    errors: SchemaValidationErrorInfo[];
-}
-/**
- * Information about a schema validation error.
- */
-export interface SchemaValidationErrorInfo {
-    message: string;
-    cellAddress?: CellAddress;
-    schemaNamespace?: string;
-    columnName?: string;
-    originalError?: Error;
-}
-/**
- * Action types for all commands.
- * Used for serialization and deserialization.
- */
-export declare const ActionTypes: {
-    readonly SET_CELL_CONTENT: "SET_CELL_CONTENT";
-    readonly SET_SHEET_CONTENT: "SET_SHEET_CONTENT";
-    readonly CLEAR_RANGE: "CLEAR_RANGE";
-    readonly PASTE_CELLS: "PASTE_CELLS";
-    readonly FILL_AREAS: "FILL_AREAS";
-    readonly MOVE_CELL: "MOVE_CELL";
-    readonly MOVE_RANGE: "MOVE_RANGE";
-    readonly AUTO_FILL: "AUTO_FILL";
-    readonly ADD_WORKBOOK: "ADD_WORKBOOK";
-    readonly REMOVE_WORKBOOK: "REMOVE_WORKBOOK";
-    readonly RENAME_WORKBOOK: "RENAME_WORKBOOK";
-    readonly CLONE_WORKBOOK: "CLONE_WORKBOOK";
-    readonly ADD_SHEET: "ADD_SHEET";
-    readonly REMOVE_SHEET: "REMOVE_SHEET";
-    readonly RENAME_SHEET: "RENAME_SHEET";
-    readonly ADD_TABLE: "ADD_TABLE";
-    readonly REMOVE_TABLE: "REMOVE_TABLE";
-    readonly RENAME_TABLE: "RENAME_TABLE";
-    readonly UPDATE_TABLE: "UPDATE_TABLE";
-    readonly RESET_TABLES: "RESET_TABLES";
-    readonly ADD_NAMED_EXPRESSION: "ADD_NAMED_EXPRESSION";
-    readonly REMOVE_NAMED_EXPRESSION: "REMOVE_NAMED_EXPRESSION";
-    readonly UPDATE_NAMED_EXPRESSION: "UPDATE_NAMED_EXPRESSION";
-    readonly RENAME_NAMED_EXPRESSION: "RENAME_NAMED_EXPRESSION";
-    readonly SET_NAMED_EXPRESSIONS: "SET_NAMED_EXPRESSIONS";
-    readonly SET_CELL_METADATA: "SET_CELL_METADATA";
-    readonly SET_SHEET_METADATA: "SET_SHEET_METADATA";
-    readonly SET_WORKBOOK_METADATA: "SET_WORKBOOK_METADATA";
-    readonly ADD_CONDITIONAL_STYLE: "ADD_CONDITIONAL_STYLE";
-    readonly REMOVE_CONDITIONAL_STYLE: "REMOVE_CONDITIONAL_STYLE";
-    readonly ADD_CELL_STYLE: "ADD_CELL_STYLE";
-    readonly REMOVE_CELL_STYLE: "REMOVE_CELL_STYLE";
-    readonly CLEAR_CELL_STYLES: "CLEAR_CELL_STYLES";
-    readonly RESET_TO_SERIALIZED: "RESET_TO_SERIALIZED";
-};
-export type ActionType = (typeof ActionTypes)[keyof typeof ActionTypes];

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

@@ -1,142 +0,0 @@
-/**
- * SchemaManager - Manages schema definitions and validation
- *
- * Tracks registered schemas and provides validation for cell writes,
- * spill operations, and copy/paste operations.
- */
-import type { CellAddress, FiniteSpreadsheetRange, SerializedCellValue, SpreadsheetRange, TableDefinition } from "../types";
-import type { TableManager } from "./table-manager";
-export type ParseFunction<TCellMetadata = unknown> = (value: SerializedCellValue, metadata: TCellMetadata) => unknown;
-export type WriteFunction<TCellMetadata = unknown> = (value: any) => {
-    value: SerializedCellValue;
-    metadata?: TCellMetadata;
-};
-export type TableSchemaHeaders<TCellMetadata = unknown> = Record<string, {
-    parse: ParseFunction<TCellMetadata>;
-    write: WriteFunction<TCellMetadata>;
-    index: number;
-}>;
-export interface RegisteredTableSchema {
-    type: "table";
-    namespace: string;
-    workbookName: string;
-    tableName: string;
-    headers: TableSchemaHeaders;
-}
-export interface RegisteredCellSchema {
-    type: "cell";
-    namespace: string;
-    cellAddress: CellAddress;
-    parse: ParseFunction;
-}
-export interface RegisteredGridSchema {
-    type: "grid";
-    namespace: string;
-    workbookName: string;
-    sheetName: string;
-    range: FiniteSpreadsheetRange;
-    parse: ParseFunction;
-}
-export type RegisteredSchema = RegisteredTableSchema | RegisteredCellSchema | RegisteredGridSchema;
-export interface ValidationResult {
-    valid: boolean;
-    error?: string;
-    originalError?: Error;
-}
-export declare class SchemaValidationError extends Error {
-    cellAddress?: CellAddress | undefined;
-    originalError?: Error | undefined;
-    constructor(message: string, cellAddress?: CellAddress | undefined, originalError?: Error | undefined);
-}
-export declare class SchemaManager {
-    private tableManager;
-    private schemas;
-    constructor(tableManager: TableManager);
-    /**
-     * Register a table schema
-     */
-    registerTableSchema(namespace: string, workbookName: string, tableName: string, headers: TableSchemaHeaders): void;
-    /**
-     * Register a cell schema
-     */
-    registerCellSchema(namespace: string, cellAddress: CellAddress, parse: ParseFunction): void;
-    /**
-     * Register a grid schema
-     */
-    registerGridSchema(namespace: string, workbookName: string, sheetName: string, range: FiniteSpreadsheetRange, parse: ParseFunction): void;
-    /**
-     * Get a schema by namespace
-     */
-    getSchema(namespace: string): RegisteredSchema | undefined;
-    /**
-     * Remove a schema
-     */
-    removeSchema(namespace: string): boolean;
-    /**
-     * Check if any schemas are registered
-     */
-    hasSchemas(): boolean;
-    /**
-     * Check if a cell is protected by a schema
-     * Returns the schema info if protected, null otherwise
-     */
-    isCellProtected(cell: CellAddress): {
-        schema: RegisteredSchema;
-        columnName?: string;
-    } | null;
-    /**
-     * Check if a cell is within a table's data range (excluding header row)
-     */
-    private isCellInTableDataRange;
-    /**
-     * Get column name by index from headers
-     */
-    private getColumnNameByIndex;
-    /**
-     * Validate a cell write against schemas
-     */
-    validateCellWrite(cell: CellAddress, value: SerializedCellValue, metadata?: unknown): ValidationResult;
-    /**
-     * Validate a spill area against schemas
-     * Returns validation result - if invalid, spill should produce #SPILL! error
-     */
-    validateSpillArea(origin: CellAddress, spillArea: SpreadsheetRange, getSpillValue: (row: number, col: number) => SerializedCellValue, getMetadata?: (cell: CellAddress) => unknown): ValidationResult;
-    /**
-     * Update schemas when a table is renamed
-     */
-    updateForTableRename(workbookName: string, oldTableName: string, newTableName: string): void;
-    /**
-     * Update schemas when a sheet is renamed
-     */
-    updateForSheetRename(workbookName: string, oldSheetName: string, newSheetName: string): void;
-    /**
-     * Update schemas when a workbook is renamed
-     */
-    updateForWorkbookRename(oldWorkbookName: string, newWorkbookName: string): void;
-    /**
-     * Get all schemas (for debugging/testing)
-     */
-    getAllSchemas(): Map<string, RegisteredSchema>;
-    /**
-     * Validate all schema constraints using evaluated cell values.
-     *
-     * This is the key method for schema validation with rollback:
-     * - It validates EVALUATED values, not raw content
-     * - A cell with "=123+123" validates as number (246), not string
-     * - Called after re-evaluation to check all schema-constrained cells
-     *
-     * @param getCellValue - Function to get the evaluated value of a cell
-     * @param getCellMetadata - Optional function to get cell metadata
-     * @returns Validation result with all errors found
-     */
-    validateAllSchemaConstraints(getCellValue: (cell: CellAddress) => SerializedCellValue, getCellMetadata?: (cell: CellAddress) => unknown, getTableDataCells?: (table: TableDefinition) => CellAddress[]): {
-        valid: boolean;
-        errors: Array<{
-            message: string;
-            cellAddress?: CellAddress;
-            schemaNamespace?: string;
-            columnName?: string;
-            originalError?: Error;
-        }>;
-    };
-}

package/dist/types/core/schema/cell-orm.d.ts

@@ -1,33 +0,0 @@
-/**
- * CellOrm - Object-Relational Mapping for single cell data
- *
- * Provides read/write operations for a single cell with type-safe access.
- * Used as the `this` context for custom cell API methods.
- */
-import type { CellAddress, SerializedCellValue } from "../types";
-import type { FormulaEngine } from "../engine";
-export type CellParseFunction<TCellMetadata, TValue> = (value: unknown, metadata: TCellMetadata) => TValue;
-export type CellWriteFunction<TCellMetadata, TValue> = (value: TValue) => {
-    value: SerializedCellValue;
-    metadata?: TCellMetadata;
-};
-export declare class CellOrm<TValue, TCellMetadata = unknown> {
-    private engine;
-    private cellAddress;
-    private parser;
-    private writer;
-    private namespace;
-    constructor(engine: FormulaEngine<any, any>, cellAddress: CellAddress, parser: CellParseFunction<TCellMetadata, TValue>, writer: CellWriteFunction<TCellMetadata, TValue>, namespace: string);
-    /**
-     * Read the cell value and parse it using the schema's parse function
-     */
-    read(): TValue;
-    /**
-     * Write a value to the cell using the schema's write function
-     */
-    write(value: TValue): void;
-    /**
-     * Get the cell address
-     */
-    getAddress(): CellAddress;
-}

package/dist/types/core/schema/grid-orm.d.ts

@@ -1,63 +0,0 @@
-/**
- * GridOrm - Object-Relational Mapping for grid/range data
- *
- * Provides read/write operations for a 2D range of cells with type-safe access.
- * Supports both column-major and row-major array access patterns.
- */
-import type { FiniteSpreadsheetRange, SerializedCellValue } from "../types";
-import type { FormulaEngine } from "../engine";
-export type GridParseFunction<TCellMetadata, TValue> = (value: unknown, metadata: TCellMetadata) => TValue;
-export type GridWriteFunction<TCellMetadata, TValue> = (value: TValue) => {
-    value: SerializedCellValue;
-    metadata?: TCellMetadata;
-};
-export declare class GridOrm<TValue, TCellMetadata = unknown> {
-    private engine;
-    private workbookName;
-    private sheetName;
-    private range;
-    private parser;
-    private writer;
-    private namespace;
-    private numCols;
-    private numRows;
-    constructor(engine: FormulaEngine<any, any>, workbookName: string, sheetName: string, range: FiniteSpreadsheetRange, parser: GridParseFunction<TCellMetadata, TValue>, writer: GridWriteFunction<TCellMetadata, TValue>, namespace: string);
-    /**
-     * Get the cell address for a given column and row index within the grid
-     */
-    private getCellAddress;
-    /**
-     * Read a single cell and parse it
-     */
-    private readCell;
-    /**
-     * Write a single cell using the write function
-     */
-    private writeCell;
-    /**
-     * Get all cells as a column-major 2D array (readonly)
-     * columns[colIndex][rowIndex]
-     */
-    get columns(): readonly (readonly TValue[])[];
-    /**
-     * Get all cells as a row-major 2D array (readonly)
-     * rows[rowIndex][colIndex]
-     */
-    get rows(): readonly (readonly TValue[])[];
-    /**
-     * Set a single value at the specified position
-     * Position is relative to the grid (0-indexed)
-     */
-    setValue(value: TValue, position: {
-        col: number;
-        row: number;
-    }): void;
-    /**
-     * Get a single value at the specified position
-     * Position is relative to the grid (0-indexed)
-     */
-    getValue(position: {
-        col: number;
-        row: number;
-    }): TValue;
-}

package/dist/types/core/schema/schema-builder.d.ts

@@ -1,16 +0,0 @@
-/**
- * Schema Builder - Constructs the working schema from declarations
- *
- * This module is responsible for creating the actual working schema
- * from the schema declarations when attached to a FormulaEngine.
- */
-import type { FormulaEngine } from "../engine";
-import type { SchemaDeclaration, Schema } from "./schema";
-import type { SchemaManager } from "../managers/schema-manager";
-/**
- * Build the working schema surface from declarations
- *
- * This creates TableOrm, CellOrm, and GridOrm instances for each declared schema
- * and returns them directly.
- */
-export declare function buildSchemaFromDeclaration(engine: FormulaEngine<any, any>, declaration: SchemaDeclaration, schemaManager: SchemaManager): Schema;

package/dist/types/core/schema/schema-helpers.d.ts

@@ -1,49 +0,0 @@
-/**
- * Schema Helper utilities for row/object conversion and filtering
- */
-import type { CellAddress, SerializedCellValue, TableDefinition } from "../types";
-import type { FormulaEngine } from "../engine";
-export type ParseFunction<TCellMetadata = unknown> = (value: SerializedCellValue, metadata: TCellMetadata) => unknown;
-export type WriteFunction<TCellMetadata = unknown> = (value: unknown) => {
-    value: SerializedCellValue;
-    metadata?: TCellMetadata;
-};
-export type TableSchemaHeaders<TCellMetadata = unknown> = Record<string, {
-    parse: ParseFunction<TCellMetadata>;
-    write: WriteFunction<TCellMetadata>;
-    index: number;
-}>;
-/**
- * Convert a spreadsheet row to a typed object using header parsers
- */
-export declare function rowToObject<TItem extends Record<string, unknown>>(engine: FormulaEngine<any, any>, table: TableDefinition, rowIndex: number, headers: TableSchemaHeaders, getCellMetadata?: (cell: CellAddress) => unknown): TItem;
-/**
- * Result from objectToRowValues including both values and optional metadata
- */
-export type RowValuesResult<TCellMetadata = unknown> = {
-    values: Map<number, SerializedCellValue>;
-    metadata: Map<number, TCellMetadata>;
-};
-/**
- * Convert a typed object to cell values based on headers using write functions
- */
-export declare function objectToRowValues<TItem extends Record<string, unknown>, TCellMetadata = unknown>(obj: TItem, headers: TableSchemaHeaders<TCellMetadata>): RowValuesResult<TCellMetadata>;
-/**
- * Check if an object matches a filter predicate
- */
-export declare function matchesFilter<TItem extends Record<string, unknown>>(item: TItem, filter: Partial<TItem>): boolean;
-/**
- * Get the number of data rows in a table (excluding header)
- */
-export declare function getTableRowCount(engine: FormulaEngine<any, any>, table: TableDefinition): number;
-/**
- * Get the next empty row index for appending data
- */
-export declare function getNextEmptyRow(engine: FormulaEngine<any, any>, table: TableDefinition): number;
-/**
- * Iterate over all data rows in a table
- */
-export declare function iterateTableRows(engine: FormulaEngine<any, any>, table: TableDefinition): Generator<{
-    rowIndex: number;
-    isEmpty: boolean;
-}>;