@ricsam/formula-engine 0.0.1

package/dist/mjs/core/sheet-renamer.mjs

@@ -0,0 +1,59 @@
+// src/core/sheet-renamer.ts
+import { parseFormula } from "../parser/parser.mjs";
+import { astToString } from "../parser/formatter.mjs";
+import { transformAST } from "./ast-traverser.mjs";
+function renameSheetInFormula(options) {
+  const { formula, oldSheetName, newSheetName } = options;
+  try {
+    const ast = parseFormula(formula);
+    const updatedAst = transformAST(ast, (node) => {
+      if (node.type === "reference" && node.sheetName === oldSheetName) {
+        return {
+          ...node,
+          sheetName: newSheetName
+        };
+      }
+      if (node.type === "range" && node.sheetName === oldSheetName) {
+        return {
+          ...node,
+          sheetName: newSheetName
+        };
+      }
+      return node;
+    });
+    return astToString(updatedAst);
+  } catch (error) {
+    return formula;
+  }
+}
+function formulaReferencesSheet(formula, sheetName) {
+  try {
+    const ast = parseFormula(formula);
+    const referencedSheets = getReferencedSheetNames(formula);
+    return referencedSheets.includes(sheetName);
+  } catch (error) {
+    return false;
+  }
+}
+function getReferencedSheetNames(formula) {
+  try {
+    const ast = parseFormula(formula);
+    const sheetNames = new Set;
+    transformAST(ast, (node) => {
+      if ((node.type === "reference" || node.type === "range") && node.sheetName) {
+        sheetNames.add(node.sheetName);
+      }
+      return node;
+    });
+    return Array.from(sheetNames);
+  } catch (error) {
+    return [];
+  }
+}
+export {
+  renameSheetInFormula,
+  getReferencedSheetNames,
+  formulaReferencesSheet
+};
+
+//# debugId=0B6036BCDD11B7B564756E2164756E21

package/dist/mjs/core/sheet-renamer.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/sheet-renamer.ts"],
+  "sourcesContent": [
+    "/**\n * Sheet renamer utility for updating cross-sheet references in formulas\n */\n\nimport { parseFormula } from \"../parser/parser.mjs\";\nimport { astToString } from \"../parser/formatter.mjs\";\nimport { transformAST } from \"./ast-traverser.mjs\";\nimport type { ASTNode } from \"../parser/ast.mjs\";\n\n/**\n * Renames sheet references in a formula string\n * @param formula The formula string (without the leading =)\n * @param oldSheetName The old sheet name to replace\n * @param newSheetName The new sheet name to use\n * @returns The updated formula string\n */\nexport function renameSheetInFormula(options: {\n  formula: string,\n  oldSheetName: string;\n  newSheetName: string;\n}): string {\n  const { formula, oldSheetName, newSheetName } = options;\n  try {\n    const ast = parseFormula(formula);\n    \n    const updatedAst = transformAST(ast, (node) => {\n      // Handle regular cross-sheet references (e.g., Sheet1!A1)\n      if (node.type === \"reference\" && node.sheetName === oldSheetName) {\n        return {\n          ...node,\n          sheetName: newSheetName,\n        };\n      }\n      \n      // Handle range references with sheet names (e.g., Sheet1!A1:B2)\n      if (node.type === \"range\" && node.sheetName === oldSheetName) {\n        return {\n          ...node,\n          sheetName: newSheetName,\n        };\n      }\n      \n      return node;\n    });\n    \n    return astToString(updatedAst);\n  } catch (error) {\n    // If parsing fails, return the original formula\n    return formula;\n  }\n}\n\n/**\n * Checks if a formula references a specific sheet\n * @param formula The formula string (without the leading =)\n * @param sheetName The sheet name to check for\n * @returns True if the formula references the sheet\n */\nexport function formulaReferencesSheet(formula: string, sheetName: string): boolean {\n  try {\n    const ast = parseFormula(formula);\n    const referencedSheets = getReferencedSheetNames(formula);\n    return referencedSheets.includes(sheetName);\n  } catch (error) {\n    // If parsing fails, assume no reference\n    return false;\n  }\n}\n\n/**\n * Gets all sheet names referenced in a formula\n * @param formula The formula string (without the leading =)\n * @returns Array of unique sheet names referenced in the formula\n */\nexport function getReferencedSheetNames(formula: string): string[] {\n  try {\n    const ast = parseFormula(formula);\n    const sheetNames = new Set<string>();\n\n    transformAST(ast, (node) => {\n      // Handle cross-sheet references\n      if ((node.type === \"reference\" || node.type === \"range\") && node.sheetName) {\n        sheetNames.add(node.sheetName);\n      }\n      \n      return node;\n    });\n\n    return Array.from(sheetNames);\n  } catch (error) {\n    // If parsing fails, return empty array\n    return [];\n  }\n}\n\n"
+  ],
+  "mappings": ";AAIA;AACA;AACA;AAUO,SAAS,oBAAoB,CAAC,SAI1B;AAAA,EACT,QAAQ,SAAS,cAAc,iBAAiB;AAAA,EAChD,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAEhC,MAAM,aAAa,aAAa,KAAK,CAAC,SAAS;AAAA,MAE7C,IAAI,KAAK,SAAS,eAAe,KAAK,cAAc,cAAc;AAAA,QAChE,OAAO;AAAA,aACF;AAAA,UACH,WAAW;AAAA,QACb;AAAA,MACF;AAAA,MAGA,IAAI,KAAK,SAAS,WAAW,KAAK,cAAc,cAAc;AAAA,QAC5D,OAAO;AAAA,aACF;AAAA,UACH,WAAW;AAAA,QACb;AAAA,MACF;AAAA,MAEA,OAAO;AAAA,KACR;AAAA,IAED,OAAO,YAAY,UAAU;AAAA,IAC7B,OAAO,OAAO;AAAA,IAEd,OAAO;AAAA;AAAA;AAUJ,SAAS,sBAAsB,CAAC,SAAiB,WAA4B;AAAA,EAClF,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAChC,MAAM,mBAAmB,wBAAwB,OAAO;AAAA,IACxD,OAAO,iBAAiB,SAAS,SAAS;AAAA,IAC1C,OAAO,OAAO;AAAA,IAEd,OAAO;AAAA;AAAA;AASJ,SAAS,uBAAuB,CAAC,SAA2B;AAAA,EACjE,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAChC,MAAM,aAAa,IAAI;AAAA,IAEvB,aAAa,KAAK,CAAC,SAAS;AAAA,MAE1B,KAAK,KAAK,SAAS,eAAe,KAAK,SAAS,YAAY,KAAK,WAAW;AAAA,QAC1E,WAAW,IAAI,KAAK,SAAS;AAAA,MAC/B;AAAA,MAEA,OAAO;AAAA,KACR;AAAA,IAED,OAAO,MAAM,KAAK,UAAU;AAAA,IAC5B,OAAO,OAAO;AAAA,IAEd,OAAO,CAAC;AAAA;AAAA;",
+  "debugId": "0B6036BCDD11B7B564756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/sheet-utils.mjs

@@ -0,0 +1,8 @@
+// src/core/sheet-utils.ts
+class SheetUtils {
+}
+export {
+  SheetUtils
+};
+
+//# debugId=B68229AE11460E9B64756E2164756E21

package/dist/mjs/core/sheet-utils.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/sheet-utils.ts"],
+  "sourcesContent": [
+    "export class SheetUtils {\n    \n}"
+  ],
+  "mappings": ";AAAO,MAAM,WAAW;AAExB;",
+  "debugId": "B68229AE11460E9B64756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/table-renamer.mjs

@@ -0,0 +1,58 @@
+// src/core/table-renamer.ts
+import { parseFormula } from "../parser/parser.mjs";
+import { astToString } from "../parser/formatter.mjs";
+import { transformAST } from "./ast-traverser.mjs";
+function renameTableInFormula(formula, oldTableName, newTableName) {
+  try {
+    const ast = parseFormula(formula);
+    const transformedAST = transformAST(ast, (node) => {
+      if (node.type === "structured-reference" && node.tableName === oldTableName) {
+        return {
+          ...node,
+          tableName: newTableName
+        };
+      }
+      return node;
+    });
+    return astToString(transformedAST);
+  } catch (error) {
+    return formula;
+  }
+}
+function formulaReferencesTable(formula, tableName) {
+  try {
+    const ast = parseFormula(formula);
+    let hasReference = false;
+    transformAST(ast, (node) => {
+      if (node.type === "structured-reference" && node.tableName === tableName) {
+        hasReference = true;
+      }
+      return node;
+    });
+    return hasReference;
+  } catch (error) {
+    return false;
+  }
+}
+function getReferencedTableNames(formula) {
+  try {
+    const ast = parseFormula(formula);
+    const tableNames = new Set;
+    transformAST(ast, (node) => {
+      if (node.type === "structured-reference" && node.tableName) {
+        tableNames.add(node.tableName);
+      }
+      return node;
+    });
+    return Array.from(tableNames);
+  } catch (error) {
+    return [];
+  }
+}
+export {
+  renameTableInFormula,
+  getReferencedTableNames,
+  formulaReferencesTable
+};
+
+//# debugId=282767C4AEBEE9EC64756E2164756E21

package/dist/mjs/core/table-renamer.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/table-renamer.ts"],
+  "sourcesContent": [
+    "import { parseFormula } from \"../parser/parser.mjs\";\nimport { astToString } from \"../parser/formatter.mjs\";\nimport { transformAST } from \"./ast-traverser.mjs\";\n\n/**\n * Renames table references in a formula string\n * @param formula - The formula string (without the leading =)\n * @param oldTableName - The current table name to replace\n * @param newTableName - The new table name\n * @returns The updated formula string, or the original if no changes were made\n */\nexport function renameTableInFormula(\n  formula: string,\n  oldTableName: string,\n  newTableName: string\n): string {\n  try {\n    const ast = parseFormula(formula);\n    \n    const transformedAST = transformAST(ast, (node) => {\n      if (node.type === \"structured-reference\" && node.tableName === oldTableName) {\n        return {\n          ...node,\n          tableName: newTableName\n        };\n      }\n      return node;\n    });\n\n    return astToString(transformedAST);\n  } catch (error) {\n    // If parsing fails, return the original formula\n    return formula;\n  }\n}\n\n/**\n * Checks if a formula contains references to a specific table\n * @param formula - The formula string (without the leading =)\n * @param tableName - The table name to search for\n * @returns True if the formula contains references to the table\n */\nexport function formulaReferencesTable(formula: string, tableName: string): boolean {\n  try {\n    const ast = parseFormula(formula);\n    let hasReference = false;\n\n    transformAST(ast, (node) => {\n      if (node.type === \"structured-reference\" && node.tableName === tableName) {\n        hasReference = true;\n      }\n      return node;\n    });\n\n    return hasReference;\n  } catch (error) {\n    // If parsing fails, assume no reference\n    return false;\n  }\n}\n\n/**\n * Gets all table names referenced in a formula\n * @param formula - The formula string (without the leading =)\n * @returns Array of unique table names referenced in the formula\n */\nexport function getReferencedTableNames(formula: string): string[] {\n  try {\n    const ast = parseFormula(formula);\n    const tableNames = new Set<string>();\n\n    transformAST(ast, (node) => {\n      if (node.type === \"structured-reference\" && node.tableName) {\n        tableNames.add(node.tableName);\n      }\n      return node;\n    });\n\n    return Array.from(tableNames);\n  } catch (error) {\n    // If parsing fails, return empty array\n    return [];\n  }\n}\n"
+  ],
+  "mappings": ";AAAA;AACA;AACA;AASO,SAAS,oBAAoB,CAClC,SACA,cACA,cACQ;AAAA,EACR,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAEhC,MAAM,iBAAiB,aAAa,KAAK,CAAC,SAAS;AAAA,MACjD,IAAI,KAAK,SAAS,0BAA0B,KAAK,cAAc,cAAc;AAAA,QAC3E,OAAO;AAAA,aACF;AAAA,UACH,WAAW;AAAA,QACb;AAAA,MACF;AAAA,MACA,OAAO;AAAA,KACR;AAAA,IAED,OAAO,YAAY,cAAc;AAAA,IACjC,OAAO,OAAO;AAAA,IAEd,OAAO;AAAA;AAAA;AAUJ,SAAS,sBAAsB,CAAC,SAAiB,WAA4B;AAAA,EAClF,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAChC,IAAI,eAAe;AAAA,IAEnB,aAAa,KAAK,CAAC,SAAS;AAAA,MAC1B,IAAI,KAAK,SAAS,0BAA0B,KAAK,cAAc,WAAW;AAAA,QACxE,eAAe;AAAA,MACjB;AAAA,MACA,OAAO;AAAA,KACR;AAAA,IAED,OAAO;AAAA,IACP,OAAO,OAAO;AAAA,IAEd,OAAO;AAAA;AAAA;AASJ,SAAS,uBAAuB,CAAC,SAA2B;AAAA,EACjE,IAAI;AAAA,IACF,MAAM,MAAM,aAAa,OAAO;AAAA,IAChC,MAAM,aAAa,IAAI;AAAA,IAEvB,aAAa,KAAK,CAAC,SAAS;AAAA,MAC1B,IAAI,KAAK,SAAS,0BAA0B,KAAK,WAAW;AAAA,QAC1D,WAAW,IAAI,KAAK,SAAS;AAAA,MAC/B;AAAA,MACA,OAAO;AAAA,KACR;AAAA,IAED,OAAO,MAAM,KAAK,UAAU;AAAA,IAC5B,OAAO,OAAO;AAAA,IAEd,OAAO,CAAC;AAAA;AAAA;",
+  "debugId": "282767C4AEBEE9EC64756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/types.mjs

@@ -0,0 +1,18 @@
+// src/core/types.ts
+var FormulaError;
+((FormulaError2) => {
+  FormulaError2["DIV0"] = "#DIV/0!";
+  FormulaError2["NA"] = "#N/A";
+  FormulaError2["NAME"] = "#NAME?";
+  FormulaError2["NUM"] = "#NUM!";
+  FormulaError2["REF"] = "#REF!";
+  FormulaError2["VALUE"] = "#VALUE!";
+  FormulaError2["CYCLE"] = "#CYCLE!";
+  FormulaError2["ERROR"] = "#ERROR!";
+  FormulaError2["SPILL"] = "#SPILL!";
+})(FormulaError ||= {});
+export {
+  FormulaError
+};
+
+//# debugId=0E7C5AF634572D3964756E2164756E21

package/dist/mjs/core/types.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/types.ts"],
+  "sourcesContent": [
+    "/**\n * Core type definitions for FormulaEngine\n * This file contains all fundamental types used throughout the engine\n */\n\nimport type { ASTNode, FunctionNode } from \"src/parser/ast\";\nimport type { FormulaEngine } from \"./engine.mjs\";\nimport type { FormulaEvaluator } from \"src/evaluator/formula-evaluator\";\nimport type { EvaluationContext } from \"src/evaluator/evaluation-context\";\nimport type { CellValueNode } from \"src/evaluator/dependency-nodes/cell-value-node\";\nimport type { EmptyCellEvaluationNode } from \"src/evaluator/dependency-nodes/empty-cell-evaluation-node\";\nimport type { RangeEvaluationNode } from \"src/evaluator/range-evaluation-node\";\nimport type { DependencyNode } from \"./managers/dependency-node.mjs\";\nimport type { LookupOrder } from \"./managers/range-eval-order-builder.mjs\";\n\n// Cell addressing types\nexport interface CellAddress {\n  sheetName: string;\n  workbookName: string;\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport interface RangeAddress {\n  sheetName: string;\n  workbookName: string;\n  range: SpreadsheetRange;\n}\n\nexport interface LocalCellAddress {\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport type ArethmeticEvaluator = (\n  left: CellValue,\n  right: CellValue,\n  context: EvaluationContext\n) => CellValue | ErrorEvaluationResult;\n\nexport type PositiveInfinity = {\n  type: \"infinity\";\n  sign: \"positive\";\n};\n\nexport type CellInfinity = {\n  type: \"infinity\";\n  sign: \"positive\" | \"negative\";\n};\n\nexport type CellNumber = {\n  type: \"number\";\n  value: number;\n};\n\nexport type SpreadsheetRangeEnd = CellNumber | PositiveInfinity;\n\nexport type SpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: SpreadsheetRangeEnd;\n    row: SpreadsheetRangeEnd;\n  };\n};\n\nexport type RelativeRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  width: SpreadsheetRangeEnd;\n  height: SpreadsheetRangeEnd;\n};\n\nexport type FiniteSpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: number;\n    row: number;\n  };\n};\n\nexport type CellString = {\n  type: \"string\";\n  value: string;\n};\n\nexport type CellBoolean = {\n  type: \"boolean\";\n  value: boolean;\n};\n\n// Cell value types\nexport type CellValue = CellNumber | CellString | CellBoolean | CellInfinity;\n/**\n * undefined and \"\" are considered empty values\n * undefineds are converted to \"\" in the engine\n *\n * any empty values are deleted from the sheet content\n */\nexport type SerializedCellValue = string | number | boolean | undefined;\n\n// Named expressions\nexport interface NamedExpression {\n  name: string;\n  expression: string;\n}\n\nexport interface TableDefinition {\n  name: string;\n  start: {\n    rowIndex: number;\n    colIndex: number;\n  };\n  headers: Map<string, { name: string; index: number }>;\n  endRow: SpreadsheetRangeEnd;\n  sheetName: string;\n  workbookName: string;\n}\n\n// Formula errors\nexport enum FormulaError {\n  DIV0 = \"#DIV/0!\",\n  NA = \"#N/A\",\n  NAME = \"#NAME?\",\n  NUM = \"#NUM!\",\n  REF = \"#REF!\",\n  VALUE = \"#VALUE!\",\n  CYCLE = \"#CYCLE!\",\n  ERROR = \"#ERROR!\",\n  SPILL = \"#SPILL!\",\n}\n\n// Sheet structure\nexport interface Sheet {\n  name: string;\n  index: number; // 0-based index of the sheet\n  content: Map<string, SerializedCellValue>;\n}\n\nexport interface Workbook {\n  name: string;\n  sheets: Map<string, Sheet>;\n}\n\nexport type ValueEvaluationResult = {\n  type: \"value\";\n  result: CellValue;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type AwaitingEvaluationResult = {\n  type: \"awaiting-evaluation\";\n  waitingFor: DependencyNode;\n  errAddress: DependencyNode;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type DoesNotSpillResult = {\n  type: \"does-not-spill\";\n};\n\nexport type ErrorEvaluationResult =\n  | {\n      type: \"error\";\n      err: FormulaError;\n      errAddress: DependencyNode;\n      message: string;\n      /**\n       * If the terminating evaluation result is a reference (see evaluateReference)\n       * then we store information about the source cell for context dependent functions like CELL\n       */\n      sourceCell?: CellAddress;\n    }\n  | AwaitingEvaluationResult;\n\nexport type SingleEvaluationResult =\n  | ValueEvaluationResult\n  | ErrorEvaluationResult;\n\nexport type SpilledValuesEvaluator = (\n  spillOffset: { x: number; y: number },\n  context: EvaluationContext\n) => SingleEvaluationResult;\n\nexport type SpilledValuesEvaluationResult = {\n  type: \"spilled-values\";\n\n  /**\n   * When a raw range is evaluated, we will add it to the sourceRange so it can be used e.g. for context dependent functions\n   */\n  sourceRange?: RangeAddress;\n\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   * sourceCell will only be defined on a spilledValue when a single value is looked up,\n   */\n  sourceCell?: CellAddress;\n\n  spillArea: (origin: CellAddress) => SpreadsheetRange;\n  /**\n   * for debugging we add a source string to denote where the spilled values were created\n   */\n  source: string;\n  evaluate: SpilledValuesEvaluator;\n  /**\n   * evaluateAllCells evaluates all non-empty cells in the spilled range.\n   * Because a spilled range can be open-ended, we need to have logic for which cells we should evaluate.\n   * e.g. when evaluating a range such as D:D only the cells in the current sheet residing in\n   * column D should be evaluated and cells producing spilled values that spill onto D:D.\n   *\n   * In order to evaluate spilled cells in D:D the range evaluateAllCells need to get all cells in the\n   * the intersection of the spilled range and D:D, for that reason evaluateAllCells gets an intersection parameter,\n   * where the intersection is relative to the origin.\n   *\n   * #### Producers:\n   * In e.g. SEQUENCE and evaluateRange we have logic for which cells in a spilled range we should evaluate,\n   *\n   * #### Nesting:\n   * e.g. evaluation of scalar operators where we want to nest e.g. `5 * right.evaluate()`\n   * can be implemented by calling\n   * ```ts\n   * const vals = child.evaluateAllCells.call(this, options);\n   * return vals.map(val => ({ ...val, result: 5 * val.result }));\n   * ```\n   *\n   * #### Consumers:\n   * Only functions that need access to all spilled values in a range end up calling evaluateAllCells, e.g.\n   * SUM, MIN, MAX, MATCH. Other types of functions like INDEX doesn't need to evaluate all cells in a range,\n   * but does a lookup into a spilled range using the evaluate method.\n   *\n   */\n  evaluateAllCells: (\n    this: FormulaEvaluator,\n    options: {\n      /**\n       * an intersection relative to the origin\n       */\n      intersection?: SpreadsheetRange;\n      evaluate: SpilledValuesEvaluator;\n      context: EvaluationContext;\n      /**\n       * origin is the cell address that the spilled range is spilled from\n       * e.g. in A3=B2:B4 the origin is A3\n       */\n      origin: CellAddress;\n\n      lookupOrder: LookupOrder;\n    }\n  ) => EvaluateAllCellsResult;\n};\n\nexport type EvaluateAllCellsResult =\n  | ErrorEvaluationResult\n  | {\n      type: \"values\";\n      values: CellInRangeResult[];\n    };\n\nexport type CellInRangeResult = {\n  result: SingleEvaluationResult;\n  relativePos: { x: number; y: number };\n};\n\nexport type FunctionEvaluationResult =\n  | SingleEvaluationResult\n  | SpilledValuesEvaluationResult;\n\nexport type SpilledValue = {\n  /**\n   * spillOnto is the range that the spilled value is spilled onto\n   */\n  spillOnto: SpreadsheetRange;\n  /**\n   * origin is the cell address that the spilled value is spilled from\n   */\n  origin: CellAddress;\n};\n\n/**\n * Function definition\n */\nexport interface FunctionDefinition {\n  name: string;\n  evaluate: (\n    this: FormulaEvaluator,\n    node: FunctionNode,\n    context: EvaluationContext\n  ) => FunctionEvaluationResult;\n  aliases?: string[];\n}\n\n/**\n * Evaluation result\n */\nexport type EvaluationResult = {\n  dependencies: Set<string>;\n} & FunctionEvaluationResult;\n\nexport type SCC = {\n  id: number;\n  nodes: Set<DependencyNode>; // All nodes considering soft + hard edges\n  evaluationOrder: DependencyNode[]; // Flat topologically ordered list\n  resolved: boolean;\n  hardEdgeSCCs: Set<DependencyNode>[]; // SCCs formed by only hard edges (regular dependencies)\n};\n\nexport type SCCDAG = {\n  sccList: SCC[];\n  sccGraph: Map<number, Set<number>>; // Adjacency list of SCC dependencies\n};\n\nexport type EvaluationOrder = {\n  evaluationOrder: Set<DependencyNode>;\n  hasCycle: boolean;\n  cycleNodes?: Set<DependencyNode>;\n  hash: string;\n  sccDAG?: SCCDAG;\n};\n"
+  ],
+  "mappings": ";AA+HO,IAAK;AAAA,CAAL,CAAK,kBAAL;AAAA,EACL,wBAAO;AAAA,EACP,sBAAK;AAAA,EACL,wBAAO;AAAA,EACP,uBAAM;AAAA,EACN,uBAAM;AAAA,EACN,yBAAQ;AAAA,EACR,yBAAQ;AAAA,EACR,yBAAQ;AAAA,EACR,yBAAQ;AAAA,GATE;",
+  "debugId": "0E7C5AF634572D3964756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/utils/range-serializer.mjs

@@ -0,0 +1,35 @@
+// src/core/utils/range-serializer.ts
+import { indexToColumn, getRowNumber } from "../utils.mjs";
+function serializeRange(range) {
+  const startCell = `${indexToColumn(range.start.col)}${getRowNumber(range.start.row)}`;
+  const endRowIsInfinity = range.end.row.type === "infinity";
+  const endColIsInfinity = range.end.col.type === "infinity";
+  let rangeEnd;
+  if (endRowIsInfinity && endColIsInfinity) {
+    rangeEnd = "INFINITY";
+  } else if (endRowIsInfinity && range.end.col.type === "number") {
+    rangeEnd = indexToColumn(range.end.col.value);
+  } else if (range.end.row.type === "number" && endColIsInfinity) {
+    rangeEnd = getRowNumber(range.end.row.value).toString();
+  } else if (range.end.row.type === "number" && range.end.col.type === "number") {
+    rangeEnd = `${indexToColumn(range.end.col.value)}${getRowNumber(range.end.row.value)}`;
+  } else {
+    throw new Error("Invalid range end configuration");
+  }
+  return `${startCell}:${rangeEnd}`;
+}
+function serializeRangeWithSheet(range, sheetName) {
+  const rangeStr = serializeRange(range);
+  if (sheetName) {
+    const needsQuotes = /[^A-Za-z0-9_]/.test(sheetName);
+    const quotedSheetName = needsQuotes ? `'${sheetName}'` : sheetName;
+    return `${quotedSheetName}!${rangeStr}`;
+  }
+  return rangeStr;
+}
+export {
+  serializeRangeWithSheet,
+  serializeRange
+};
+
+//# debugId=EAB81BB82F22743064756E2164756E21

package/dist/mjs/core/utils/range-serializer.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/utils/range-serializer.ts"],
+  "sourcesContent": [
+    "import type { SpreadsheetRange } from \"../types.mjs\";\nimport { indexToColumn, getRowNumber } from \"../utils.mjs\";\n\n/**\n * Serializes a SpreadsheetRange into a human-readable range string following canonical format.\n * \n * Examples:\n * - Finite range: A2:B10\n * - Column-infinite range: A2:B (row infinite, column bounded)\n * - Row-infinite range: A2:10 (column infinite, row bounded)\n * - Fully infinite range: A2:INFINITY (both infinite)\n * \n * @param range The SpreadsheetRange to serialize\n * @returns A human-readable range string in canonical format\n */\nexport function serializeRange(range: SpreadsheetRange): string {\n  // Format start cell\n  const startCell = `${indexToColumn(range.start.col)}${getRowNumber(range.start.row)}`;\n  \n  // Determine end format based on infinity types\n  const endRowIsInfinity = range.end.row.type === \"infinity\";\n  const endColIsInfinity = range.end.col.type === \"infinity\";\n  \n  let rangeEnd: string;\n  \n  if (endRowIsInfinity && endColIsInfinity) {\n    // Both infinite: A2:INFINITY\n    rangeEnd = \"INFINITY\";\n  } else if (endRowIsInfinity && range.end.col.type === \"number\") {\n    // Row infinite, col finite: A2:B (column only)\n    rangeEnd = indexToColumn(range.end.col.value);\n  } else if (range.end.row.type === \"number\" && endColIsInfinity) {\n    // Row finite, col infinite: A2:10 (row only)\n    rangeEnd = getRowNumber(range.end.row.value).toString();\n  } else if (range.end.row.type === \"number\" && range.end.col.type === \"number\") {\n    // Both finite: A2:B10\n    rangeEnd = `${indexToColumn(range.end.col.value)}${getRowNumber(range.end.row.value)}`;\n  } else {\n    throw new Error(\"Invalid range end configuration\");\n  }\n  \n  return `${startCell}:${rangeEnd}`;\n}\n\n/**\n * Serializes a SpreadsheetRange with an optional sheet name prefix.\n * \n * @param range The SpreadsheetRange to serialize\n * @param sheetName Optional sheet name to prefix the range\n * @returns A human-readable range string, optionally prefixed with sheet name\n */\nexport function serializeRangeWithSheet(range: SpreadsheetRange, sheetName?: string): string {\n  const rangeStr = serializeRange(range);\n  \n  if (sheetName) {\n    // Handle sheet names that need quoting (contain spaces or special characters)\n    const needsQuotes = /[^A-Za-z0-9_]/.test(sheetName);\n    const quotedSheetName = needsQuotes ? `'${sheetName}'` : sheetName;\n    return `${quotedSheetName}!${rangeStr}`;\n  }\n  \n  return rangeStr;\n}\n"
+  ],
+  "mappings": ";AACA;AAcO,SAAS,cAAc,CAAC,OAAiC;AAAA,EAE9D,MAAM,YAAY,GAAG,cAAc,MAAM,MAAM,GAAG,IAAI,aAAa,MAAM,MAAM,GAAG;AAAA,EAGlF,MAAM,mBAAmB,MAAM,IAAI,IAAI,SAAS;AAAA,EAChD,MAAM,mBAAmB,MAAM,IAAI,IAAI,SAAS;AAAA,EAEhD,IAAI;AAAA,EAEJ,IAAI,oBAAoB,kBAAkB;AAAA,IAExC,WAAW;AAAA,EACb,EAAO,SAAI,oBAAoB,MAAM,IAAI,IAAI,SAAS,UAAU;AAAA,IAE9D,WAAW,cAAc,MAAM,IAAI,IAAI,KAAK;AAAA,EAC9C,EAAO,SAAI,MAAM,IAAI,IAAI,SAAS,YAAY,kBAAkB;AAAA,IAE9D,WAAW,aAAa,MAAM,IAAI,IAAI,KAAK,EAAE,SAAS;AAAA,EACxD,EAAO,SAAI,MAAM,IAAI,IAAI,SAAS,YAAY,MAAM,IAAI,IAAI,SAAS,UAAU;AAAA,IAE7E,WAAW,GAAG,cAAc,MAAM,IAAI,IAAI,KAAK,IAAI,aAAa,MAAM,IAAI,IAAI,KAAK;AAAA,EACrF,EAAO;AAAA,IACL,MAAM,IAAI,MAAM,iCAAiC;AAAA;AAAA,EAGnD,OAAO,GAAG,aAAa;AAAA;AAUlB,SAAS,uBAAuB,CAAC,OAAyB,WAA4B;AAAA,EAC3F,MAAM,WAAW,eAAe,KAAK;AAAA,EAErC,IAAI,WAAW;AAAA,IAEb,MAAM,cAAc,gBAAgB,KAAK,SAAS;AAAA,IAClD,MAAM,kBAAkB,cAAc,IAAI,eAAe;AAAA,IACzD,OAAO,GAAG,mBAAmB;AAAA,EAC/B;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "EAB81BB82F22743064756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/utils/spreadsheet-visualizer.mjs

@@ -0,0 +1,112 @@
+// src/core/utils/spreadsheet-visualizer.ts
+function visualizeSpreadsheet(engine, options) {
+  const {
+    workbookName,
+    numRows,
+    numCols,
+    startRow = 1,
+    startCol = 0,
+    sheetName,
+    emptyCellChar = ".",
+    minColWidth = 3,
+    maxColWidth = 20,
+    showColumnHeaders = true,
+    showRowNumbers = true,
+    snapshot = false
+  } = options;
+  const targetSheetName = sheetName || (() => {
+    const sheets = engine.getSheets(workbookName);
+    const sheetNames = Array.from(sheets.keys());
+    return sheetNames.length > 0 ? sheetNames[0] : null;
+  })();
+  const cellValues = [];
+  const columnWidths = new Array(numCols).fill(minColWidth);
+  if (showColumnHeaders) {
+    const headerRow = [];
+    for (let col = 0;col < numCols; col++) {
+      const colLetter = String.fromCharCode(65 + startCol + col);
+      headerRow.push(colLetter);
+      columnWidths[col] = Math.max(columnWidths[col], colLetter.length);
+    }
+    cellValues.push(headerRow);
+  }
+  for (let row = startRow;row < startRow + numRows; row++) {
+    const rowValues = [];
+    for (let col = 0;col < numCols; col++) {
+      let value;
+      if (targetSheetName) {
+        const cellValue = engine.getCellValue({
+          sheetName: targetSheetName,
+          workbookName,
+          rowIndex: row - 1,
+          colIndex: startCol + col
+        });
+        value = cellValue === "" || cellValue == null ? emptyCellChar : String(cellValue);
+      } else {
+        value = emptyCellChar;
+      }
+      rowValues.push(value);
+      columnWidths[col] = Math.max(columnWidths[col], Math.min(value.length, maxColWidth));
+    }
+    cellValues.push(rowValues);
+  }
+  let totalRowWidth = 0;
+  if (showRowNumbers) {
+    totalRowWidth += 3;
+  }
+  for (let col = 0;col < numCols; col++) {
+    totalRowWidth += columnWidths[col];
+  }
+  if (numCols > 0) {
+    totalRowWidth += (numCols - 1) * 3;
+    if (showRowNumbers) {
+      totalRowWidth += 3;
+    }
+  }
+  let result = "";
+  for (let i = 0;i < cellValues.length; i++) {
+    const rowValues = cellValues[i];
+    const formattedCells = [];
+    if (showRowNumbers) {
+      if (i === 0 && showColumnHeaders) {
+        formattedCells.push("   ");
+      } else {
+        const rowNum = showColumnHeaders ? startRow + i - 1 : startRow + i;
+        formattedCells.push(rowNum.toString().padStart(3));
+      }
+    }
+    for (let col = 0;col < rowValues.length; col++) {
+      let cellValue = rowValues[col];
+      if (cellValue.length > maxColWidth) {
+        cellValue = cellValue.substring(0, maxColWidth - 3) + "...";
+      }
+      formattedCells.push(cellValue.padEnd(columnWidths[col]));
+    }
+    let rowContent = formattedCells.join(" | ");
+    rowContent = rowContent.padEnd(totalRowWidth);
+    if (snapshot && i > 0) {
+      rowContent = " " + rowContent;
+    }
+    result += rowContent + `
+`;
+    if (i === 0 && showColumnHeaders) {
+      const separatorParts = [];
+      if (showRowNumbers) {
+        separatorParts.push(snapshot ? "----" : "---");
+      }
+      for (let col = 0;col < numCols; col++) {
+        separatorParts.push("-".repeat(columnWidths[col]));
+      }
+      let separatorLine = separatorParts.join("-+-");
+      separatorLine = separatorLine.padEnd(totalRowWidth);
+      result += separatorLine + `
+`;
+    }
+  }
+  return result;
+}
+export {
+  visualizeSpreadsheet
+};
+
+//# debugId=13EB020C0050D77364756E2164756E21

package/dist/mjs/core/utils/spreadsheet-visualizer.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/utils/spreadsheet-visualizer.ts"],
+  "sourcesContent": [
+    "import { FormulaEngine } from \"../engine.mjs\";\n\nexport interface SpreadsheetVisualizerOptions {\n  workbookName: string;\n  /** Number of rows to display (1-based) */\n  numRows: number;\n  /** Number of columns to display (0-based, so 11 = A-K) */\n  numCols: number;\n  /** Starting row (1-based, default: 1) */\n  startRow?: number;\n  /** Starting column (0-based, default: 0 = A) */\n  startCol?: number;\n  /** Sheet name to visualize (default: uses engine's current sheet) */\n  sheetName?: string;\n  /** Character to use for empty cells (default: \".\") */\n  emptyCellChar?: string;\n  /** Minimum column width (default: 3) */\n  minColWidth?: number;\n  /** Maximum column width (default: 20) */\n  maxColWidth?: number;\n  /** Whether to show column headers (A, B, C...) */\n  showColumnHeaders?: boolean;\n  /** Whether to show row numbers */\n  showRowNumbers?: boolean;\n  /** If output is used for snapshotting */\n  snapshot?: boolean;\n}\n\n/**\n * Generates a visual ASCII representation of a spreadsheet region\n */\nexport function visualizeSpreadsheet(\n  engine: FormulaEngine,\n  options: SpreadsheetVisualizerOptions\n): string {\n  const {\n    workbookName,\n    numRows,\n    numCols,\n    startRow = 1,\n    startCol = 0,\n    sheetName,\n    emptyCellChar = \".\",\n    minColWidth = 3,\n    maxColWidth = 20,\n    showColumnHeaders = true,\n    showRowNumbers = true,\n    snapshot = false,\n  } = options;\n\n  // Determine the sheet name to use upfront\n  const targetSheetName =\n    sheetName ||\n    (() => {\n      const sheets = engine.getSheets(workbookName);\n      const sheetNames = Array.from(sheets.keys());\n      return sheetNames.length > 0 ? sheetNames[0]! : null;\n    })();\n\n  // First pass: collect all cell values and calculate column widths\n  const cellValues: string[][] = [];\n  const columnWidths: number[] = new Array(numCols).fill(minColWidth);\n\n  // Collect column headers if needed\n  if (showColumnHeaders) {\n    const headerRow: string[] = [];\n    for (let col = 0; col < numCols; col++) {\n      const colLetter = String.fromCharCode(65 + startCol + col);\n      headerRow.push(colLetter);\n      columnWidths[col] = Math.max(columnWidths[col]!, colLetter.length);\n    }\n    cellValues.push(headerRow);\n  }\n\n  // Collect all cell data\n  for (let row = startRow; row < startRow + numRows; row++) {\n    const rowValues: string[] = [];\n    for (let col = 0; col < numCols; col++) {\n      let value: string;\n      if (targetSheetName) {\n        const cellValue = engine.getCellValue({\n          sheetName: targetSheetName,\n          workbookName,\n          rowIndex: row - 1,\n          colIndex: startCol + col,\n        });\n        value =\n          cellValue === \"\" || cellValue == null\n            ? emptyCellChar\n            : String(cellValue);\n      } else {\n        // No sheets available\n        value = emptyCellChar;\n      }\n\n      rowValues.push(value);\n      // Update column width, respecting max width\n      columnWidths[col] = Math.max(\n        columnWidths[col]!,\n        Math.min(value.length, maxColWidth)\n      );\n    }\n    cellValues.push(rowValues);\n  }\n\n  // Calculate total row width for consistent formatting\n  let totalRowWidth = 0;\n  if (showRowNumbers) {\n    totalRowWidth += 3; // Row number width\n  }\n  for (let col = 0; col < numCols; col++) {\n    totalRowWidth += columnWidths[col]!;\n  }\n  // Add separator characters: \" | \" between columns (3 chars each, but last column doesn't have trailing separator)\n  if (numCols > 0) {\n    totalRowWidth += (numCols - 1) * 3; // \" | \" between columns\n    if (showRowNumbers) {\n      totalRowWidth += 3; // \" | \" after row number\n    }\n  }\n\n  // Second pass: format the output with proper column widths\n  let result = \"\";\n\n  for (let i = 0; i < cellValues.length; i++) {\n    const rowValues = cellValues[i]!;\n    const formattedCells: string[] = [];\n\n    // Add row number if requested\n    if (showRowNumbers) {\n      if (i === 0 && showColumnHeaders) {\n        formattedCells.push(\"   \"); // Empty space for header row\n      } else {\n        const rowNum = showColumnHeaders ? startRow + i - 1 : startRow + i;\n        formattedCells.push(rowNum.toString().padStart(3));\n      }\n    }\n\n    // Format each cell with proper width\n    for (let col = 0; col < rowValues.length; col++) {\n      let cellValue = rowValues[col]!;\n\n      // Truncate if too long\n      if (cellValue.length > maxColWidth) {\n        cellValue = cellValue.substring(0, maxColWidth - 3) + \"...\";\n      }\n\n      // Pad to column width\n      formattedCells.push(cellValue.padEnd(columnWidths[col]!));\n    }\n\n    // Join with consistent separators and ensure exact row width\n    let rowContent = formattedCells.join(\" | \");\n    // Pad the entire row to ensure consistent width\n    rowContent = rowContent.padEnd(totalRowWidth);\n    if (snapshot && i > 0) {\n      rowContent = \" \" + rowContent;\n    }\n    result += rowContent + \"\\n\";\n\n    // Add separator line after header\n    if (i === 0 && showColumnHeaders) {\n      const separatorParts: string[] = [];\n\n      if (showRowNumbers) {\n        separatorParts.push(snapshot ? \"----\" : \"---\");\n      }\n\n      for (let col = 0; col < numCols; col++) {\n        separatorParts.push(\"-\".repeat(columnWidths[col]!));\n      }\n\n      // Create separator line with same width as data rows\n      let separatorLine = separatorParts.join(\"-+-\");\n      separatorLine = separatorLine.padEnd(totalRowWidth);\n      result += separatorLine + \"\\n\";\n    }\n  }\n\n  return result;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "13EB020C0050D77364756E2164756E21",
+  "names": []
+}