@syncfusion/ej2-calculate 35.1.37

package/src/base/calculate.d.ts

@@ -0,0 +1,1105 @@
+import { INotifyPropertyChanged, EmitType, Base } from '@syncfusion/ej2-base';
+import { CalculateModel } from './calculate-model';
+import { IFormulaCollection, FailureEventArgs, StoredCellInfo, ICalculateHost, CalculateSheetInfo, CalculateDateParseResult } from '../common/interface';
+import { Parser } from './parser';
+/**
+ * Excel-compatible formula calculation engine.
+ *
+ * Register sheets, named ranges, and cell values, then evaluate formulas with
+ * {@link Calculate.computeFormula} or refresh dependent cells after edits.
+ *
+ * Built-in library functions are registered by {@link BasicFormulas} (math, text,
+ * logical, lookup, financial, statistical, engineering, and ECMA-376 extensions).
+ *
+ * @remarks
+ * Integrate with a workbook by passing an {@link ICalculateHost} to the constructor,
+ * or use standalone key/value storage via {@link Calculate.setKeyValue}.
+ *
+ * @example
+ * ```ts
+ * import { Calculate } from '@syncfusion/ej2-calculate';
+ *
+ * const engine = new Calculate();
+ * engine.setKeyValue('A1', '10');
+ * engine.setKeyValue('A2', '20');
+ * const sum = engine.computeFormula('=SUM(A1:A2)'); // '30'
+ * engine.destroy();
+ * ```
+ */
+export declare class Calculate extends Base<HTMLElement> implements INotifyPropertyChanged {
+    private lFormulas;
+    /**
+     * Registered library formula collection (name → handler metadata).
+     *
+     * Prefer {@link getLibraryFormulas} for read access. The setter accepts a single
+     * formula registration payload used during built-in and custom registration.
+     *
+     * @hidden
+     * @returns {any} - Registered library formula collection.
+     */
+    libraryFormulas: any;
+    /** @hidden */
+    storedData: Map<string, FormulaInfo>;
+    /** @hidden */
+    actCell: string;
+    private keyToRowsMap;
+    private rowsToKeyMap;
+    /** @hidden */
+    rightBracket: string;
+    /** @hidden */
+    leftBracket: string;
+    /** @hidden */
+    sheetToken: string;
+    /**
+     * Active cell reference currently being evaluated (may include a sheet token).
+     *
+     * @hidden
+     */
+    cell: string;
+    private cellPrefix;
+    private treatEmptyStringAsZero;
+    /** @hidden */
+    parentObject: Object | Calculate;
+    /** @hidden */
+    tic: string;
+    /** @hidden */
+    singleTic: string;
+    /** @hidden */
+    trueValue: string;
+    /** @hidden */
+    falseValue: string;
+    private parseDecimalSeparator;
+    /** @hidden */
+    spreadSheetUsedRange: number[];
+    /** @hidden */
+    arithMarker: string;
+    /** @hidden */
+    arithMarker2: string;
+    private dependentCells;
+    private dependentFormulaCells;
+    /**
+     * Minimum numeric bound used by library formulas that clamp results.
+     *
+     * @hidden
+     */
+    minValue: number;
+    /**
+     * Maximum numeric bound used by library formulas that clamp results.
+     *
+     * @hidden
+     */
+    maxValue: number;
+    /**
+     * Formula category labels used by Insert Function UI integrations.
+     * The `'All'` entry is localized via Syncfusion {@link L10n} (key `CategoryAll`).
+     *
+     * @hidden
+     */
+    categoryCollection: string[];
+    /**
+     * Nesting depth counter used while walking formula dependencies.
+     *
+     * @hidden
+     */
+    dependencyLevel: number;
+    /**
+     * Syncfusion L10n instance for localizable calculate prose (not Excel tokens).
+     *
+     * @hidden
+     */
+    private l10n;
+    /** @hidden */
+    randomValues: Map<string, string>;
+    /** @hidden */
+    isRandomVal: boolean;
+    /** @hidden */
+    randCollection: string[];
+    /** @hidden */
+    dependencyCollection: string[];
+    /** @hidden */
+    uniqueRange: string[];
+    private uniqueCells;
+    /** @hidden */
+    sortRange: string[];
+    private sortCells;
+    /**
+     * Parser and engine failure messages indexed by {@link FormulasErrorsStrings}.
+     *
+     * Prose entries are localized via {@link L10n} / {@link setLocale}. Excel error
+     * tokens in this array (`#NAME?`, `#CIRCULARREF!`, `#SPILL!`, `#DIV/0!`) stay
+     * English for workbook compatibility.
+     *
+     * @hidden
+     */
+    formulaErrorStrings: string[];
+    private errorStrings;
+    /** @hidden */
+    grid: Object | Calculate;
+    /** @hidden */
+    parser: Parser;
+    private parseArgumentSeparator;
+    private dateTime1900;
+    private isParseDecimalSeparatorChanged;
+    private isArgumentSeparatorChanged;
+    private sheetFamilyID;
+    private defaultFamilyItem;
+    private sheetFamiliesList;
+    private modelToSheetID;
+    /** @hidden */
+    tokenCount: number;
+    private sortedSheetNames;
+    private tempSheetPlaceHolder;
+    /** @hidden */
+    namedRanges: Map<string, string>;
+    private formulaInfoTable;
+    private millisecondsOfaDay;
+    private parseDateTimeSeparator;
+    /** Keys currently being evaluated via {@link getKeyValue} (guards row-map recursion). */
+    private evaluatingKeys;
+    /**
+     * Fired when formula parsing or evaluation fails.
+     *
+     * @event onFailure
+     */
+    onFailure: EmitType<FailureEventArgs>;
+    /**
+     * Creates a Calculate engine and registers built-in formulas.
+     *
+     * @param {Object} parent - Optional host implementing {@link ICalculateHost} (for example a workbook),
+     * or omit for a standalone engine that stores values with {@link setKeyValue}.
+     */
+    constructor(parent?: Object | ICalculateHost);
+    /**
+     * Applies culture-specific prose for parser/engine messages and category labels.
+     *
+     * Excel error tokens (`#VALUE!`, …), `TRUE`/`FALSE`, and English function names
+     * are not localized.
+     *
+     * @hidden
+     * @param {string} locale - Culture id (for example `"fr-FR"`). Defaults to host `locale` or `"en-US"`.
+     * @returns {void}
+     */
+    setLocale(locale?: string): void;
+    /**
+     * Rebuilds {@link formulaErrorStrings} and {@link categoryCollection} from L10n.
+     *
+     * @hidden
+     * @returns {void}
+     */
+    private refreshLocalizedStrings;
+    /**
+     * Returns sheet metadata from the calculate host when available.
+     *
+     * @returns {Object} - Sheet info entries from {@link ICalculateHost.getSheetInfo}, or an empty array.
+     * @hidden
+     */
+    getHostSheetInfo(): CalculateSheetInfo[];
+    /**
+     * Parses a date/time string via the host when {@link ICalculateHost.parseDate} is implemented.
+     *
+     * @param {string | number | boolean | Object} value - Date or time text to parse.
+     * @returns {Object} - Host parse result, or an empty object when no host parser is available.
+     * @hidden
+     */
+    hostParseDate(value: string): CalculateDateParseResult;
+    /**
+     * Gets the culture-aware separator used to split formula arguments (typically `,` or `;`).
+     *
+     * @hidden
+     * @returns {string} - Argument separator string.
+     */
+    getParseArgumentSeparator(): string;
+    /**
+     * Sets the separator used to split formula arguments.
+     *
+     * @param {string | number | boolean | Object} value - Argument separator for the current culture (for example `,` or `;`).
+     * @returns {void}
+     */
+    setParseArgumentSeparator(value: string): void;
+    /**
+     * Gets the date/time component separator used when parsing date literals.
+     *
+     * @hidden
+     * @returns {Date | Object} - Date/time separator string (default `/`).
+     */
+    getParseDateTimeSeparator(): string;
+    /**
+     * Controls whether empty string cell values are treated as numeric zero in calculations.
+     *
+     * @param {string | number | boolean | Object} value - When `true`, empty strings coerce to `0`.
+     * @returns {void}
+     */
+    setTreatEmptyStringAsZero(value: boolean): void;
+    /**
+     * Returns whether empty string values are treated as numeric zero.
+     *
+     * @hidden
+     * @returns {string | number} - `true` when empty strings coerce to `0`.
+     */
+    getTreatEmptyStringAsZero(): boolean;
+    /**
+     * Sets the date/time component separator used when parsing date literals.
+     *
+     * @hidden
+     * @param {string | number | boolean | Object} value - Separator character or string (for example `/` or `-`).
+     * @returns {void}
+     */
+    setParseDateTimeSeparator(value: string): void;
+    /**
+     * Syncfusion property-change hook (no-op for Calculate; required by {@link INotifyPropertyChanged}).
+     *
+     * @param {Object} newProp - Updated model properties.
+     * @param {Object} oldProp - Previous model properties.
+     * @returns {void}
+     */
+    onPropertyChanged(newProp: CalculateModel, oldProp: CalculateModel): void;
+    /**
+     * Gets the module name of the Calculate engine.
+     *
+     * @returns {string} - Returns "calculate" as the component module name.
+     */
+    getModuleName(): string;
+    /**
+     * Returns the leading character that marks a formula expression (always `=`).
+     *
+     * @returns {string} - Formula prefix character.
+     * @hidden
+     */
+    getFormulaCharacter(): string;
+    /**
+     * Returns whether the first character of `text` is an uppercase A–Z letter.
+     *
+     * @param {string} text - Text to inspect.
+     * @returns {string} - `true` when the first character is uppercase ASCII A-Z.
+     * @hidden
+     */
+    isUpperChar(text: string): boolean;
+    private resetKeys;
+    /**
+     * Records a dependency from the active formula cell to `cellRef` and detects circular references.
+     *
+     * @param {string} cellRef - Dependent cell reference (may include a sheet token).
+     * @throws When a circular reference is detected.
+     * @hidden
+     * @returns {void}
+     */
+    updateDependentCell(cellRef: string): void;
+    /**
+     * Returns the map of cell references to cells that depend on them.
+     *
+     * @returns {Object} - Dependency map keyed by referenced cell.
+     * @hidden
+     */
+    getDependentCells(): Map<string, string[]>;
+    /**
+     * Returns the map of formula cells to the references they depend on.
+     *
+     * @returns {Object} - Nested map of formula cell → referenced cells.
+     * @hidden
+     */
+    getDependentFormulaCells(): Map<string, Map<string, string>>;
+    /**
+     * Returns the map of registered library formula names to their handlers and metadata.
+     *
+     * @hidden
+     * @returns {Object} - Map keyed by uppercase Excel function name (for example `"SUM"`, `"XLOOKUP"`).
+     */
+    getLibraryFormulas(): Map<string, IFormulaCollection>;
+    /**
+     * Returns the handler function for a registered library formula.
+     *
+     * @hidden
+     * @param {string} libFormula - Excel function name (case-insensitive), for example `"SUM"`.
+     * @returns {Function | null} - Bound `Compute*` handler, or `null` when the name is not registered.
+     *
+     * @example
+     * ```ts
+     * const sum = engine.getFunction('SUM');
+     * ```
+     */
+    getFunction(libFormula: string): Function;
+    /**
+     * Converts an Excel serial date value to a JavaScript `Date`.
+     *
+     * @param {string | number} val - Excel serial number as a string.
+     * @returns {Date | Object} - Corresponding `Date` (accounts for the Excel 1900 leap-year quirk).
+     * @hidden
+     */
+    intToDate(val: string): Date;
+    /**
+     * Returns the formula info table for the active sheet family (or the standalone engine table).
+     *
+     * @hidden
+     * @returns {Object} - Map of cell token → {@link FormulaInfo}.
+     */
+    getFormulaInfoTable(): Map<string, FormulaInfo>;
+    /**
+     * Gets the decimal separator used when parsing numeric literals.
+     *
+     * @hidden
+     * @returns {string} - Decimal separator string (default `.`).
+     */
+    getParseDecimalSeparator(): string;
+    /**
+     * Sets the decimal separator used when parsing numeric literals.
+     *
+     * @param {string | number | boolean | Object} value - Decimal separator for the current culture (for example `.` or `,`).
+     * @returns {void}
+     */
+    setParseDecimalSeparator(value: string): void;
+    /**
+     * Extracts the sheet token prefix from a cell reference when present.
+     *
+     * @param {string} cellRef - Cell or range reference that may begin with a sheet token.
+     * @returns {string} - Sheet token substring including delimiters, or an empty string.
+     * @hidden
+     */
+    getSheetToken(cellRef: string): string;
+    /**
+     * Resolves the sheet family id for a grid/parent object.
+     *
+     * @param {Object} grd - Grid or parent object registered with the engine.
+     * @returns {string | number} - Sheet id, or `-1` when not registered.
+     * @hidden
+     */
+    getSheetID(grd: Object): number;
+    /**
+     * Parses a numeric string using the configured decimal separator.
+     *
+     * @hidden
+     * @param {string | number | boolean | Object} value - Numeric text or number.
+     * @returns {number} - Parsed number, or `NaN` when parsing fails.
+     */
+    parseFloat(value: string | number): number;
+    /**
+     * Returns the 1-based row index from a cell reference string.
+     *
+     * @hidden
+     * @param {string} cell - Cell reference (optional sheet token allowed).
+     * @returns {number} - Row number, or `-1` when invalid.
+     */
+    rowIndex(cell: string): number;
+    /**
+     * Returns the 1-based column index from a cell reference string.
+     *
+     * @param {string} cell - Cell reference (optional sheet token allowed).
+     * @returns {number} - Column number, or `-1` when invalid.
+     * @hidden
+     */
+    colIndex(cell: string): number;
+    /**
+     * Returns the Excel-compatible error tokens used by the engine (`#N/A`, `#VALUE!`, …).
+     *
+     * @returns {string[]} - Error string list indexed by {@link CommonErrors}.
+     * @hidden
+     */
+    getErrorStrings(): string[];
+    /**
+     * Returns a substring with Excel-style optional length (defaults to remainder of `text`).
+     *
+     * @param {string} text - Source string.
+     * @param {number} startIndex - Zero-based start index.
+     * @param {number} length - Optional length; when omitted, returns through the end of `text`.
+     * @returns {string} - Substring.
+     * @hidden
+     */
+    substring(text: string, startIndex: number, length?: number): string;
+    /**
+     * Returns whether `c` is an alphabetic character (A–Z or a–z).
+     *
+     * @param {number} c - Single character or string whose first character is tested.
+     * @returns {string | number} - `true` when alphabetic.
+     * @hidden
+     */
+    isChar(c: string): boolean;
+    /**
+     * Returns the {@link CalcSheetFamilyItem} for a model/grid, creating family storage as needed.
+     *
+     * @param {Object} model - Parent grid or sheet model.
+     * @param {string | number | Object} calcId - Optional explicit family id.
+     * @returns {string | number} - Sheet family item for the model.
+     * @hidden
+     */
+    getSheetFamilyItem(model: Object, calcId?: number): CalcSheetFamilyItem;
+    /**
+     * Stores a standalone key/value (or formula) for evaluation without a workbook host.
+     *
+     * When `value` starts with `=`, it is treated as a formula and evaluated by {@link getKeyValue}.
+     *
+     * @param {string} key - Cell-like key (for example `"A1"`).
+     * @param {string | number | boolean | Object} value - Literal value or formula text.
+     *
+     * @example
+     * ```ts
+     * engine.setKeyValue('A1', '10');
+     * engine.setKeyValue('B1', '=A1*2');
+     * ```
+     * @returns {void}
+     */
+    setKeyValue(key: string, value: string | number): void;
+    /**
+     * Clears dependency graph entries for a formula cell.
+     *
+     * @param {string} cell - Formula cell token whose dependencies should be removed.
+     * @hidden
+     * @returns {void}
+     */
+    clearFormulaDependentCells(cell: string): void;
+    /**
+     * Clears all stored key-value pairs from memory in standalone mode.
+     *
+     * @returns {void}
+     */
+    clearKeys(): void;
+    private arrayRemove;
+    /**
+     * Returns the stored or computed value for a standalone key registered with {@link setKeyValue}.
+     *
+     * @param {string} key - Cell-like key (case-insensitive).
+     * @returns {string} - Computed formula result or stored literal; empty string when missing.
+     *
+     * @example
+     * ```ts
+     * engine.setKeyValue('A1', '=1+2');
+     * engine.getKeyValue('A1'); // '3'
+     * ```
+     */
+    getKeyValue(key: string): string | number;
+    /**
+     * Returns the named range map (name → range address).
+     *
+     * @hidden
+     * @returns {Object} - Mutable map of named ranges.
+     */
+    getNamedRanges(): Map<string, string>;
+    /**
+     * Adds or replaces a named range.
+     *
+     * @param {string} name - Range name (optionally `Sheet!Name` scoped).
+     * @param {string} range - Address or formula text associated with the name.
+     * @returns {string} - `true` when the name was registered; `false` when sheet scope could not be resolved.
+     */
+    addNamedRange(name: string, range: string): boolean;
+    /**
+     * Rewrites named-range keys after a sheet rename.
+     *
+     * @param {string} pName - Previous sheet name segment.
+     * @param {string} name - New sheet name segment.
+     * @hidden
+     * @returns {void}
+     */
+    updateNamedRange(pName: string, name: string): void;
+    /**
+     * Removes a named range by name.
+     *
+     * @param {string} name - Named range to remove (case-insensitive).
+     * @returns {string} - `true` when the name existed and was removed.
+     */
+    removeNamedRange(name: string): boolean;
+    /**
+     * Converts a 1-based column number to Excel column letters (`1` → `"A"`, `27` → `"AA"`).
+     *
+     * @param {number} col - 1-based column index.
+     * @returns {string | number} - Column letters.
+     * @hidden
+     */
+    convertAlpha(col: number): string;
+    /**
+     * Expands a cell or range reference into an array of individual cell addresses.
+     *
+     * @param {string} cellRange - Single cell or `A1:B2`-style range (sheet token allowed).
+     * @returns {string} - Cell address array, or the original string when not expandable.
+     * @hidden
+     */
+    getCellCollection(cellRange: string): string[] | string;
+    /**
+     * Parses (when needed) and evaluates a formula expression.
+     *
+     * @hidden
+     * @param {string} formulaText - Formula text (with or without leading `=`) or a pre-parsed token string.
+     * @param {boolean} isFromComputeExpression - Internal flag when invoked from {@link computeExpression}.
+     * @returns {string} - Computed value, or an Excel error token string on failure.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=SUM(1,2,3)'); // '6'
+     * ```
+     */
+    computeFormula(formulaText: string, isFromComputeExpression?: boolean): string | number;
+    private calculateFormula;
+    /**
+     * Shared implementation for SUMIF / AVERAGEIF range evaluation.
+     *
+     * @param {string} range - Argument tokens for the conditional aggregate.
+     * @param {boolean} isAvgIf - When `true`, computes AVERAGEIF semantics; otherwise SUMIF.
+     * @returns {string} - Partial aggregate values or an error string.
+     * @hidden
+     */
+    computeSumIfAndAvgIf(range: string[], isAvgIf: boolean): number[] | string;
+    /**
+     * Shared LOOKUP evaluation helper used by library formula handlers.
+     *
+     * @param {string} range - LOOKUP argument tokens.
+     * @returns {string} - Matched value or an error token.
+     * @hidden
+     */
+    computeLookup(range: string[]): string;
+    /**
+     * Shared VLOOKUP / HLOOKUP evaluation helper.
+     *
+     * @param {string} range - Lookup argument tokens.
+     * @param {boolean} isVlookup - When `true` (default), uses VLOOKUP orientation; otherwise HLOOKUP.
+     * @returns {string} - Matched value or an error token.
+     * @hidden
+     */
+    computeVHLookup(range: string[], isVlookup?: boolean): string;
+    private findClosestMatch;
+    private compareStrings;
+    /**
+     * Applies Excel-style wildcard matching (`*`, `?`, `~`) between criteria and a cell value.
+     *
+     * @param {string | number | Object} lookVal - Criteria pattern.
+     * @param {string} cellValue - Candidate cell text.
+     * @returns {string | number} - Match marker or original values used by lookup/criteria helpers.
+     * @hidden
+     */
+    findWildCardValue(lookVal: string, cellValue: string): string;
+    /**
+     * Evaluates criteria against a criteria range and aggregates matching sum-range values.
+     *
+     * @param {string} criteriaRange - Criteria cells.
+     * @param {string} sumRange - Values to aggregate for matches.
+     * @param {string} criteria - Criteria expression.
+     * @returns {string | number} - Aggregate result details used by SUMIF-family formulas.
+     * @hidden
+     */
+    getComputeSumIfValue(criteriaRange: string[] | string, sumRange: string[] | string, criteria: string, checkCriteria: number, op: string, isAsterisk: boolean, isQuestionMark: boolean): number[];
+    private getValueFromRange;
+    /**
+     * Evaluates AND / OR / NOT over argument tokens.
+     *
+     * @param {string[]} args - Logical argument tokens.
+     * @param {string} op - Operation name (`"and"`, `"or"`, or `"not"`).
+     * @returns {string} - `"TRUE"`, `"FALSE"`, or an error token.
+     * @hidden
+     */
+    computeAndOrNot(args: string[], op: string): string;
+    /**
+     * @hidden
+     * @param {string} text - specify the text
+     * @returns {string} - to strip out the tic from the formula arguments.
+     */
+    /**
+     * Strips surrounding formula string quotes (`"...`) when present.
+     *
+     * @param {string} text - Possibly quoted text.
+     * @returns {string} - Unquoted text.
+     * @hidden
+     */
+    removeTics(text: string): string;
+    /**
+     * Returns the top-left cell address from a range string.
+     *
+     * @param {string} range - Range such as `A1:B2`.
+     * @returns {string | number} - Starting cell address.
+     * @hidden
+     */
+    getCellFrom(range: string): string;
+    private computeValue;
+    private getValArithmetic;
+    /**
+     * Applies a comparison operator to values on the evaluation stack.
+     *
+     * @param {string | number | Object} stack - Value stack.
+     * @param {string | number | Object} operator - Comparison / logical operator token.
+     * @param {string | number | Object} emptyStack - Optional alternate stack for empty handling.
+     * @returns {string} - `"TRUE"`, `"FALSE"`, or an error token.
+     * @hidden
+     */
+    processLogical(stack: string[], operator: string, emptyStack?: string[]): string;
+    /**
+     * Stores and expands cells for multi-criteria IFS formulas.
+     *
+     * @param {string} sCell - Stored cell info payload.
+     * @returns {string | number} - Expanded stored cell list.
+     * @hidden
+     */
+    computeStoreCells(sCell: StoredCellInfo): string[];
+    /**
+     * Shared SUMIFS / AVERAGEIFS evaluation entry point.
+     *
+     * @param {string} range - Argument tokens for the IFS aggregate.
+     * @param {boolean} isCountIfs - COUNTIFS marker when applicable.
+     * @param {string} isAvgIfs - AVERAGEIFS marker when applicable.
+     * @returns {string} - Aggregate result or error token.
+     * @hidden
+     */
+    computeIfsFormulas(range: string[], isCountIfs?: string, isAvgIfs?: string): string | number;
+    /**
+     * Shared COUNTIFS evaluation entry point.
+     *
+     * @param {string} range - COUNTIFS argument tokens.
+     * @returns {string} - Count result or error token.
+     * @hidden
+     */
+    computeCountIfsFormulas(range: string[]): string | number;
+    private getOperatorAndCriteria;
+    private processNestedFormula;
+    /**
+     * Returns whether `value` is `NaN` after numeric coercion.
+     *
+     * @hidden
+     * @param {string | number | boolean | Object} value - Value to test.
+     * @returns {number} - `true` when not a number.
+     */
+    isNaN(value: string | number): boolean;
+    /**
+     * Returns whether `val` is numeric (including numeric strings).
+     *
+     * @hidden
+     * @param {string | number} val - Value to test.
+     * @returns {number} - `true` when numeric.
+     */
+    isNumber(val: string | number): boolean;
+    /**
+     * Converts an OLE Automation (Excel) serial date to a JavaScript `Date`.
+     *
+     * @hidden
+     * @param {string | number | Object} doubleNumber - Excel serial date/time.
+     * @returns {Date | Object} - JavaScript `Date`.
+     */
+    fromOADate(doubleNumber: number): Date;
+    /**
+     * Builds an Excel serial date from year, month, and day components.
+     *
+     * @hidden
+     * @param {number} year - Full year.
+     * @param {number} month - Month number (1–12; Excel-style overflow allowed).
+     * @param {number} day - Day of month (Excel-style overflow allowed).
+     * @returns {number} - Excel serial date number.
+     */
+    getSerialDateFromDate(year: number, month: number, day: number): number;
+    /**
+     * Converts a serial time fraction (or time string) to a `Date`.
+     *
+     * @param {string | number | boolean | Object} value - Time serial or text.
+     * @returns {Date | Object} - `Date` representing the time of day.
+     * @hidden
+     */
+    intToTime(value: string | number): Date;
+    /**
+     * Converts a JavaScript `Date` to an Excel OLE Automation serial number.
+     *
+     * @hidden
+     * @param {string | number | Object} dateTime - Date/time to convert.
+     * @param {boolean} isTime - When `true`, includes the time fraction.
+     * @param {boolean} isTimeOnly - When `true`, treats the value as time without a date component.
+     * @returns {number} - Excel serial number.
+     */
+    toOADate(dateTime: Date, isTime?: boolean, isTimeOnly?: boolean): number;
+    /**
+     * Normalizes a date string for calculation.
+     *
+     * @param {number | string} date - Date text.
+     * @returns {string} - Normalized date string.
+     * @hidden
+     */
+    calculateDate(date: string): string;
+    /**
+     * Returns whether `s` is `null`, `undefined`, or an empty string.
+     *
+     * @hidden
+     * @param {number | string} s - Text to test.
+     * @returns {string | number} - `true` when empty.
+     */
+    isTextEmpty(s: string): boolean;
+    /**
+     * Returns whether `text` consists only of digit characters `0`–`9`.
+     *
+     * @hidden
+     * @param {string} text - Text to test.
+     * @returns {string | number} - `true` when all characters are digits.
+     */
+    isDigit(text: string): boolean;
+    /**
+     * Evaluates a single AND condition token to `"TRUE"` / `"FALSE"`.
+     *
+     * @param {boolean | string | number} condition - Condition expression or cell token.
+     * @returns {string} - Logical result string.
+     * @hidden
+     */
+    getANDComputedValue(condition: string): string;
+    private findLastIndexOfq;
+    /**
+     * Resolves a formula argument token to its computed display/value string.
+     *
+     * Handles cell references, nested formulas, literals, and named ranges.
+     *
+     * @hidden
+     * @param {string | number} val - Argument token from the parser.
+     * @param {boolean} isUnique - UNIQUE formula context.
+     * @param {boolean} isIfError - IFERROR/IFNA context.
+     * @param {boolean} isSubtotal - SUBTOTAL context.
+     * @param {boolean} isIFFormula - IF formula context.
+     * @returns {string} - Resolved value string.
+     */
+    getValueFromArg(val: string, isUnique?: boolean, isIfError?: boolean, isSubtotal?: boolean, isIFFormula?: boolean): string;
+    /**
+     * Attempts to interpret `date` as a JavaScript `Date`.
+     *
+     * @hidden
+     * @param {number | string} date - Date instance, serial, or valid text.
+     * @returns {Date | Object} - `Date` when recognized; otherwise a false result used by callers.
+     */
+    isDate(date: any): Date;
+    /**
+     * Parses a date-like value into a `Date` or intermediate representation.
+     *
+     * @param {number | string} date - Value to parse.
+     * @returns {string | number} - Parsed date information.
+     * @hidden
+     */
+    parseDate(date: any): any;
+    /**
+     * Validates and parses a date string using engine/host date rules.
+     *
+     * @param {number | string} date - Date text.
+     * @param {string | number | Object} pvtParse - Private parse mode.
+     * @param {string | number | Object} fromIsDate - When called from {@link isDate}.
+     * @returns {Date | Object} - Parsed `Date` when valid.
+     * @hidden
+     */
+    checkDateFormat(date: string, pvtParse?: boolean, fromIsDate?: boolean): Date;
+    /**
+     * Returns whether `args` looks like a valid cell or range reference.
+     *
+     * @hidden
+     * @param {string[]} args - Text to test.
+     * @returns {string} - `true` when the text is a cell/range reference.
+     */
+    isCellReference(args: string): boolean;
+    /**
+     * Rewrites sheet names in formula text to internal sheet tokens.
+     *
+     * @param {string} text - Formula text containing sheet names.
+     * @returns {string} - Text with sheet tokens substituted.
+     * @hidden
+     */
+    setTokensForSheets(text: string): string;
+    private getParentObjectCellValue;
+    /**
+     * Returns a function that reads a cell value for the active grid context.
+     *
+     * @param {Object} grid - Grid / parent object providing cell values.
+     * @param {string} actCell - Active cell reference for dependency tracking.
+     * @param {string | number | Object} sheetId - Sheet id for the grid.
+     * @param {string} updateDependentCell - When `true`, records dependents while reading.
+     * @param {string | number | Object} refresh - Whether to refresh computed values while reading.
+     * @param {boolean} isUnique - UNIQUE formula context.
+     * @param {boolean} isSubtotal - SUBTOTAL formula context.
+     * @returns {string} - Cell value getter `(row, col, curCell) => string`.
+     * @hidden
+     */
+    getCellValueFn(grid: Object, actCell: string, sheetId: number, updateDependentCell?: boolean, refresh?: boolean, isUnique?: boolean, isSubtotal?: boolean): (row: number, col: number, curCell: string) => string;
+    private isValidCell;
+    /**
+     * Returns the numeric sheet id for a registered grid object.
+     *
+     * @param {Object} grd - Grid / parent object.
+     * @returns {string | number} - Sheet id.
+     * @hidden
+     */
+    getSheetId(grd: Object): number;
+    /**
+     * Getting the formula result.
+     *
+     * @param {Object} grid - Specifies the parent object.
+     * @param {number} row - Row index of the parent object or key.
+     * @param {number} col - Column index of the parent object.
+     * @returns {string} - Getting the formula result.
+     */
+    /**
+     * Reads a cell value from a grid at 1-based row/column indexes.
+     *
+     * @param {Object} grid - Grid / parent object.
+     * @param {number} row - 1-based row index.
+     * @param {number} col - 1-based column index.
+     * @returns {string} - Cell value as a string.
+     */
+    getValueRowCol(grid: Object, row: number, col: number): string;
+    /**
+     * Registers a custom formula in the library.
+     *
+     * @param {string} formulaName - Excel-facing function name to register.
+     * @param {string} functionName - Handler function, or a global function name string.
+     * @param {string | number | Object} formulaDescription - Description shown in Insert Function UI.
+     * @param {string} category - Category label for Insert Function UI.
+     *
+     * @example
+     * ```ts
+     * engine.defineFunction('DOUBLE', (x) => Number(x) * 2, 'Doubles a number', 'Custom');
+     * ```
+     * @returns {void}
+     */
+    defineFunction(formulaName: string, functionName: string | Function, formulaDescription: string, category: string): void;
+    /**
+     * Notifies the engine that a cell value or formula changed and optionally recalculates dependents.
+     *
+     * @hidden
+     * @param {Object} grid - Parent object / sheet reference name.
+     * @param {string[]} changeArgs - Changed cell coordinates and formula/value.
+     * @param {boolean} isCalculate - When `true`, recalculates the changed formula.
+     * @param {string | number | Object} usedRangeCol - Used-range bounds for the sheet.
+     * @param {string | number | Object} refresh - Whether to refresh computed values.
+     * @param {string} sheetName - Visible sheet name for `actCell` tracking.
+     * @param {boolean} isRandomFormula - Whether the change involves volatile random formulas.
+     * @param {string} randomFormulaRefreshing - Whether random formulas are being refreshed.
+     * @param {boolean} isDelete - Whether the change originates from a delete operation.
+     * @param {string} deletedRange - Deleted range indexes when `isDelete` is `true`.
+     * @param {string | number | Object} refreshDependentCells - Forces dependent refresh regardless of calculation mode.
+     * @param {string | number | Object} action - Optional calculation action label (for example `"calculate"`).
+     */
+    valueChanged(grid: string, changeArgs: ValueChangedArgs, isCalculate?: boolean, usedRangeCol?: number[], refresh?: boolean, sheetName?: string, isRandomFormula?: boolean, randomFormulaRefreshing?: boolean, isDelete?: boolean, deletedRange?: number[], refreshDependentCells?: boolean, action?: string): void;
+    /**
+     * @hidden
+     * @param {number} value - specify the value
+     * @param {string | number} formulaValue -  specify the formula value.
+     * @param {number} row - specify the row
+     * @param {number} col - specify the col.
+     * @returns {void} - to set value row and column.
+     */
+    /**
+     * Writes a computed value into standalone storage for the given sheet/row/column.
+     *
+     * @param {string | number | boolean | Object} value - Sheet id used to build the storage key.
+     * @param {string | number | Object} formulaValue - Value to store.
+     * @param {number} row - 1-based row index.
+     * @param {number} col - 1-based column index.
+     * @returns {void}
+     */
+    setValueRowCol(value: number, formulaValue: string | number, row: number, col: number): void;
+    private getSortedSheetNames;
+    /**
+     * Extracts an error line/label from an exception message when present.
+     *
+     * @param {string} error - Error object or message.
+     * @returns {string} - Error line text, or an empty string.
+     * @hidden
+     */
+    getErrorLine(error: string): string;
+    /**
+     * Allocates a new sheet family id for registering grids as sheets.
+     *
+     * @returns {string | number} - New family id.
+     * @hidden
+     */
+    createSheetFamilyID(): number;
+    /**
+     * Shared MIN / MAX evaluation over argument tokens.
+     *
+     * @param {string[]} args - Numeric argument tokens.
+     * @param {string | number | Object} operation - `"min"` or `"max"`.
+     * @returns {string} - Aggregate result string or error token.
+     * @hidden
+     */
+    computeMinMax(args: string[], operation: string): string;
+    /**
+     * Shared AVERAGE evaluation over argument tokens.
+     *
+     * @param {string[]} args - Numeric argument tokens.
+     * @param {boolean} isSubtotalFormula - When `true`, applies SUBTOTAL visibility rules.
+     * @returns {string} - Average as a string, or an error token.
+     * @hidden
+     */
+    calculateAvg(args: string[], isSubtotalFormula?: boolean): string;
+    /**
+     * Registers a grid/model as a named sheet within a sheet family.
+     *
+     * @param {string} refName - Sheet reference name.
+     * @param {Object} model - Grid / model object (or id string).
+     * @param {string | number | Object} sheetFamilyID - Family id from {@link createSheetFamilyID}.
+     * @returns {string} - Sheet token assigned to the model.
+     */
+    registerGridAsSheet(refName: string, model: Object | string, sheetFamilyID: number): string;
+    /**
+     * Unregisters a sheet name (or all sheets) from a sheet family.
+     *
+     * @param {string} refName - Sheet reference name to remove.
+     * @param {Object} model - Grid / model object associated with the sheet.
+     * @param {Object} unRegisterAll - When `true`, removes all registered sheets for the model.
+     * @returns {void}
+     */
+    unregisterGridAsSheet(refName: string, model: string | Object, unRegisterAll?: boolean): void;
+    /**
+     * Parses and evaluates a formula expression in one call (always re-parses).
+     *
+     * @param {string} formula - Formula text to evaluate.
+     * @param {boolean} isFromComputeExpression - Internal flag passed through to {@link computeFormula}.
+     * @returns {string} - Computed value or error token.
+     *
+     * @example
+     * ```ts
+     * engine.computeExpression('=AVERAGE(1,2,3)'); // '2'
+     * ```
+     */
+    computeExpression(formula: string, isFromComputeExpression?: boolean): string | number;
+    private isSheetMember;
+    /**
+     * Releases engine state (stored values, named ranges, dependency graphs, sheet
+     * families, volatile tracking, and library formulas).
+     *
+     * Call when the engine instance is no longer needed.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Recomputes volatile random formula cells tracked by the engine.
+     *
+     * @param {string} cellRef - Cell reference that triggered the refresh (removed from the random set when present).
+     * @hidden
+     * @returns {void}
+     */
+    refreshRandValues(cellRef: string): void;
+    /**
+     * Recalculates cells that depend on `cellRef` according to calculation mode and options.
+     *
+     * @hidden
+     * @param {string} cellRef - Changed cell reference.
+     * @param {string} uniqueCell - Optional UNIQUE spill context cell to skip.
+     * @param {string} dependentCell - Accumulator of already-refreshed dependents (used for recursion).
+     * @param {boolean} isRandomFormula - Whether refresh is for volatile random formulas.
+     * @param {boolean} isDelete - Whether refresh follows a delete.
+     * @param {string} deletedRange - Deleted range indexes.
+     * @param {string | number | Object} refreshDependentCells - Forces dependent updates.
+     * @param {string | number | Object} action - Optional action label (for example `"calculate"`).
+     */
+    refreshDependentCells(cellRef: string, uniqueCell?: string, dependentCell?: string[], isRandomFormula?: boolean, isDelete?: boolean, deletedRange?: number[], refreshDependentCells?: boolean, action?: string): void;
+}
+/**
+ * Formula parse/evaluation error raised by the Calculate engine.
+ *
+ * @hidden
+ */
+export declare class FormulaError {
+    /** Human-readable error message. */
+    message: string;
+    /** When `true`, the parser suggests an auto-corrected formula. */
+    formulaCorrection: boolean;
+    /**
+     * @param {string | number | Object} errorMessage - Error description.
+     * @param {string} formulaAutoCorrection - Whether formula auto-correction is available.
+     */
+    constructor(errorMessage: string, formulaAutoCorrection?: boolean);
+}
+/**
+ * Cached formula text, parsed form, and computed value for a cell.
+ *
+ * @hidden
+ */
+export declare class FormulaInfo {
+    /** Calculation generation id for cache invalidation. */
+    calcID: number;
+    /** Original formula text (including leading `=` when present). */
+    formulaText: string;
+    private formulaValue;
+    private parsedFormula;
+    private calcID1;
+    /**
+     * Returns the stored formula text for this cell.
+     *
+     * @returns {string} - Formula text, or `undefined` when unset.
+     */
+    getFormulaText(): string;
+    /**
+     * Sets the formula text for this cell.
+     *
+     * @param {string | number | boolean | Object} value - Formula text (typically including leading `=`).
+     * @returns {void}
+     */
+    setFormulaText(value: string): void;
+    /**
+     * Returns the last computed value for this cell.
+     *
+     * @returns {string} - Computed value or error token.
+     */
+    getFormulaValue(): string | number;
+    /**
+     * Sets the computed value for this cell.
+     *
+     * @param {string | number | boolean | Object} value - Computed result.
+     * @returns {void}
+     */
+    setFormulaValue(value: string | number): void;
+    /**
+     * Returns the parser token string for this cell's formula.
+     *
+     * @returns {string | number} - Parsed formula tokens.
+     */
+    getParsedFormula(): string;
+    /**
+     * Sets the parser token string for this cell's formula.
+     *
+     * @param {string | number | boolean | Object} value - Parsed formula tokens from {@link Parser.parseFormula}.
+     * @returns {void}
+     */
+    setParsedFormula(value: string): void;
+}
+/**
+ * Per-family sheet registration and dependency tables used when multiple grids share an engine.
+ *
+ * @hidden
+ */
+export declare class CalcSheetFamilyItem {
+    /** Whether this family participates in multi-sheet evaluation. */
+    isSheetMember: boolean;
+    /** Maps parent grid objects to their sheet tokens. */
+    parentObjectToToken: Map<Object, string>;
+    /** Formula dependency map scoped to this sheet family. */
+    sheetDependentFormulaCells: Map<string, Map<string, string>>;
+    /** Maps sheet names to parent grid objects. */
+    sheetNameToParentObject: Map<string, Object>;
+    /** Maps sheet names to sheet tokens. */
+    sheetNameToToken: Map<string, string>;
+    /** Maps sheet tokens to parent grid objects. */
+    tokenToParentObject: Map<string, Object>;
+    /** Formula info table scoped to this sheet family. */
+    sheetFormulaInfotable: Map<string, FormulaInfo>;
+}
+/**
+ * Converts a 1-based column index to Excel column letters.
+ *
+ * @param {number} col - 1-based column index.
+ * @returns {string | number} - Column letters (for example `1` → `"A"`).
+ * @hidden
+ */
+export declare function getAlphalabel(col: number): string;
+/**
+ * Arguments describing a cell value/formula change for {@link Calculate.valueChanged}.
+ *
+ * @hidden
+ */
+export declare class ValueChangedArgs {
+    /** 1-based row index of the changed cell. */
+    row: number;
+    /** 1-based column index of the changed cell. */
+    col: number;
+    /** New formula text or literal value. */
+    value: number | string;
+    /** Returns the 1-based row index. */
+    getRowIndex: Function;
+    /** Updates the 1-based row index. */
+    setRowIndex: Function;
+    /** Returns the 1-based column index. */
+    getColIndex: Function;
+    /** Updates the 1-based column index. */
+    setColIndex: Function;
+    /** Returns the formula/value associated with this change. */
+    getFormulaValue: Function;
+    /**
+     * @param {number} row - 1-based row index.
+     * @param {number} col - 1-based column index.
+     * @param {string | number | boolean | Object} value - Formula text or literal value.
+     */
+    constructor(row: number, col: number, value: number | string);
+}