/** * Official Type definitions for JSS Formula Premium * https://jspreadsheet.com/products/formulas */ /** * Error instance returned by the engine when a formula fails. * The message is the Excel error text, e.g. "#VALUE!". */ declare class FormulasError extends Error { readonly formulaError: true; } /** * Object form accepted by the main function. Used by Jspreadsheet v12+ * to evaluate a cell in place: the expression is evaluated against the * worksheet and the record is used as the caching key of the cell. */ interface FormulaRequest { /** Formula without the leading "=" */ expression: string; /** External variables, e.g. { A1: 1000, A2: 2000 }. When present the expression is sanitised before evaluation. */ variables?: object; /** Column index of the cell being evaluated */ x?: number; /** Row index of the cell being evaluated */ y?: number; /** Worksheet instance */ worksheet?: object; /** Cell record returned by worksheet.getCellObject(x, y) */ record?: object; } /** * Scope (this) received by custom formulas registered with setFormula */ interface CustomFormulaScope { /** Column index of the cell being evaluated */ x: number | undefined; /** Row index of the cell being evaluated */ y: number | undefined; /** Worksheet instance */ worksheet: object | undefined; /** Alias of worksheet */ instance: object | undefined; } type CustomFormula = (this: CustomFormulaScope, ...args: any[]) => any; /** * Evaluate a formula. * @param expression - Formula without the leading "=", e.g. SUM(A1,B2) * @param variables - External variables, e.g. { A1: 1000, A2: 2000 } * @param x - Cell column index * @param y - Cell row index * @param instance - Worksheet instance */ declare function formula(expression: string, variables?: object, x?: number, y?: number, instance?: object): any declare function formula(request: FormulaRequest): any declare namespace formula { /** * Define custom formulas. Use dotted keys for namespaced names, e.g. { 'MY.FUNC': fn }. * Set a key to null to remove a previously defined formula. * Arguments arrive already resolved (references become values); the return value is * treated like the result of a built-in function, so arrays spill. */ function setFormula(formulas: Record) : void; function license(value: string | { clientId?: string; licenseKey: string }) : void; /** * @deprecated Use Jspreadsheet defined names instead. */ function define() : void; /** * @deprecated */ function reset() : void; /** * Round the final result of a formula to remove floating-point noise. Default: false */ let adjustPrecision: boolean; /** * Apply the precision adjustment to every intermediate operation and function result, * not only to the final result. Default: false */ let adjustPrecisionGranular: boolean; /** * Character that separates function arguments. Default: "," */ let divisor: string; /** * Character that separates columns inside an array literal, e.g. {1,2;3,4}. Default: "," */ let horizontalArraySeparator: string; /** * Log evaluation errors to the console. Default: false */ let debug: boolean; /** * Locale of the worksheet being evaluated, taken from the Jspreadsheet * international configuration. Set by the engine, read-only for consumers. */ let locale: string | undefined; /** * Error instances returned by the engine. Compare by identity, e.g. * result === formula.errors.na */ const errors: { /** #NULL! */ nil: FormulasError; /** #DIV/0! */ div0: FormulasError; /** #VALUE! */ value: FormulasError; /** #REF! */ ref: FormulasError; /** #NAME? */ name: FormulasError; /** #NUM! */ num: FormulasError; /** #N/A */ na: FormulasError; /** #ERROR! */ error: FormulasError; /** #GETTING_DATA */ data: FormulasError; /** #CALC! */ calc: FormulasError; /** #SPILL! */ spill: FormulasError; /** #BLOCKED! */ blocked: FormulasError; }; /** * Error returned when a circular reference is detected (#LOOP!) */ const loopError: Error; /** * Transform a formula before executed. * @param {string} expression * Example: * formula.onbeforeformula = (expression) => expression.replace(/\./g, '').replace(/\,/g, '.') */ function onbeforeformula(expression: string) : string /** * Intercept formula errors. * @param {Error} error * @param {string} expression - SUM(A1,B2) * @param {object | undefined} variables - { A1: 1000, A2: 2000 } * @param {number | undefined} x - Cell column index * @param {number | undefined} y - Cell row index * @param {object | undefined} worksheet - Worksheet instance */ function onerror(error: Error, expression: string, variables: object | undefined, x: number | undefined, y: number | undefined, worksheet: object | undefined) : void } export default formula;