# 7.0.0

## Breaking Changes

- **Jspreadsheet Compatibility**: Requires Jspreadsheet v13 or later. Cells are now read through the v13 record accessors (`getCellObject`, `getCellRowObject`)
- **Legacy Update Module Removed**: The v11 spill bookkeeping path, the `Update` module and the `UpdateLoop` export were removed
- **Debug Default**: `formula.debug` now defaults to `false`. Set it to `true` to keep logging evaluation errors to the console
- **Argument Count Validation**: Every function declares its accepted argument count. A wrong number of arguments returns `#N/A`, and variadic functions are capped at 255 arguments
- **Direct JavaScript Calls**: When calling functions directly from JavaScript, matrix arguments must be two-dimensional. One-dimensional arrays are no longer accepted
- **IMAGE Result Type**: `IMAGE` returns an image entity instead of a string. `ISTEXT` is FALSE, `TYPE` is 128, and text operations on it return `#VALUE!`. `String(value)` still yields the source URL
- **REGEXEXTRACT and REGEXREPLACE**: Switched from the Google Sheets signature to the Excel signature (`occurrence`, `return_mode`, `case_sensitivity`). `REGEXMATCH` keeps the Sheets behavior

## New Syntax

- **Spill Range Operator**: `=A1#` resolves the whole spill range of an anchor cell and composes with `:` and arithmetic
- **Union References**: `=SUM((A1:B2,D6))` combines areas. `AREAS` counts them and overlapping cells are counted twice, like Excel
- **3D References**: `=SUM(Sheet1:Sheet3!A1)` spans every sheet between the two endpoints in tab order (Jspreadsheet mode only)
- **Intersection Operator**: `=A1:B5 B3:C6` returns the cells common to both references. The meaningful space is preserved before Jspreadsheet strips whitespace
- **Trim References**: `A1.:E10`, `A1:.E10` and `A1.:.E10` trim leading, trailing or both blank rows and columns, equivalent to `TRIMRANGE`
- **Functions as Values**: Bare function names can be passed to `BYROW`, `BYCOL`, `MAP`, `REDUCE`, `SCAN`, `MAKEARRAY`, `GROUPBY` and `PIVOTBY`, e.g. `=BYROW(A1:B2,SUM)`. Defined names and tables take precedence over function names
- **Callable Results**: A function returned by another expression can be called in place, e.g. `=CHOOSE(2,LAMBDA(1),LAMBDA(X,X*3))(5)`. Lambdas capture their lexical scope, so `=LAMBDA(X,LAMBDA(Y,X+Y))(1)(2)` returns 3

## Functions Added

- **Dynamic Arrays**: TAKE, VSTACK, TOCOL, TOROW, WRAPROWS, WRAPCOLS, TRIMRANGE, GROUPBY, PIVOTBY, IMAGE
- **Text**: REGEXTEST, ASC, BAHTTEXT, DBCS, JIS, PHONETIC, FINDB, LEFTB, LENB, MIDB, REPLACEB, RIGHTB, SEARCHB
- **Financial**: VDB, ACCRINTM, DURATION, MDURATION, RECEIVED, ODDFPRICE, ODDFYIELD, ODDLPRICE, ODDLYIELD
- **Statistical**: FORECAST.ETS, FORECAST.ETS.CONFINT, FORECAST.ETS.SEASONALITY, FORECAST.ETS.STAT
- **Web**: WEBSERVICE, FILTERXML
- **Logical**: REDUCE
- **Math**: PERCENTOF
- **Compatibility**: PERCENTRANK, WEIBULL

No functions were removed.

## API Additions

- **`formula.loopError`**: The `#LOOP!` error instance returned on circular references
- **`formula.errors.blocked`**: New `#BLOCKED!` error, returned by IMAGE when a source cannot be loaded
- **`formula.locale`**: Set by the engine from the worksheet international configuration. Drives locale-aware date parsing and byte semantics in the DBCS functions
- **Async Functions**: WEBSERVICE resolves through the Jspreadsheet cell cache. The anchor cell shows the value once the request completes. Without a worksheet it returns a Promise
- **Type Definitions**: `index.d.ts` now covers the object-form call, the scope custom functions receive, `adjustPrecisionGranular`, `horizontalArraySeparator`, `errors`, `loopError` and `locale`
- **Function Catalog**: `formulas.json` ships with the package and lists every function with its description, syntax, parameters, examples and category

## Behavior Changes

- **Error Precedence**: When several arguments are invalid, the first problematic cell in argument order decides the error, e.g. `=DEVSQ(HSTACK(1/0,SUM))` returns `#DIV/0!`
- **Per-Cell Errors**: A lambda or invalid value inside a computed array no longer fails the whole formula. Only the offending cells return an error. Ranges keep the scalar `#VALUE!`
- **Union and 3D as Values**: A union used as a cell value returns `#VALUE!`. A direct 3D reference used as a value returns `#REF!`
- **Function Values in Arrays**: Function values inside spilled arrays render as `#CALC!`
- **COUNT, AGGREGATE(2), SUBTOTAL(2/102)**: Error values are skipped instead of propagated
- **MAX, MIN, MAXA, MINA**: Booleans and numeric text in referenced cells are ignored. Omitted arguments count as zero
- **SORT, SORTBY**: Empty inputs return 0 instead of `#N/A`
- **Legacy Distribution Functions**: BETADIST, CHIDIST, HYPGEOMDIST, LOGNORMDIST, NEGBINOMDIST, NORMSDIST, TTEST, FTEST and ZTEST use their original signatures instead of aliasing the dotted functions, so results may change
- **TEXTJOIN**: Matrices are flattened cell by cell, `{"a","b";"c","d"}` joins as `a-b-c-d`. Empty cells render as empty text
- **ARRAYTOTEXT, VALUETOTEXT**: Strict mode always uses `;` as row separator. The format argument must be exactly 0 or 1
- **EXACT, SEARCH, PROPER**: Lambda arguments return `#CALC!` or `#VALUE!` instead of silently comparing the lambda source text
- **FILTER, MATCH, INDIRECT, HYPERLINK**: `=FILTER(A1:C1,A2)` returns `#VALUE!`. `=INDIRECT("B3#")` resolves the spill range. One-argument HYPERLINK displays the location
- **1900 Date Serials**: WEEKDAY, ISOWEEKNUM and NETWORKDAYS handle serials in the 1900 range like Excel
- **Empty vs Omitted**: An omitted argument counts as 0. An empty referenced cell is skipped
- **Text Length Limits**: The 32767-character limit is applied per function as in Excel. TEXTJOIN and CONCAT return `#CALC!`, CONCATENATE truncates
- **Type Coercion**: Scalar arguments go through shared number, boolean and text parsers, so numeric strings, percentages and booleans convert consistently across functions

## Known Limitations

- LINEST, LOGEST, TREND and GROWTH do not support multi-variable regression
- Chained comparisons are right-associative, `=1<2<3` returns TRUE where Excel returns FALSE
- Scientific notation and trailing-dot number literals are not parsed, `=1E2+1` returns `#ERROR!`
- LAMBDA optional parameters `[y]` are not supported
- INDEX accepts `area_num` but the full reference form over multi-area references is limited
- WEBSERVICE does not accept array or range arguments
- Spaces in table column names are not supported
- Cube, RTD, GETPIVOTDATA, STOCKHISTORY, EUROCONVERT, CALL and REGISTER.ID are documented in the catalog but not implemented
- Excel formula limits (8192 characters, 64 nesting levels) are not enforced

# 6.0.0

## Breaking Changes

- **JSpreadsheet Compatibility**: Requires JSpreadsheet v12 or later
- **Caching Option Removed**: Caching is now always enabled
- **Custom Functions Format**: Changed from `{ MY: { FUNC: fn } }` to `{ 'MY.FUNC': fn }`
- **Unary Plus Operator**: Using "+" with a reference now returns the value instead of the reference (e.g., `=COLUMN(+A1)` returns #N/A error instead of 1)

## New Features

- **Enhanced Reference Returns**: Functions like INDIRECT and DROP can now return references (similar to OFFSET)
- **Range Operator**: Added ":" operator for range references
- **String Scientific Notation**: Strings with scientific notation are now converted in operations and functions
- **Leading Decimal**: Expressions like `.5` are now parsed as `0.5`
- **Maximum References**: Column ZZZ and row 1048576

## Functions Added

- **RANK**: Alias for RANK.EQ

## Functions Removed

- TABLE
- VAL
- THISROWCELL
- NULL

## Improvements

- Improved performance for cell and range value access
- Better error handling and validation
- Reference errors like "SHEET1!#REF!" are now properly detected

## Behavior Changes

- **Comparison Operators**: `>`, `>=`, `<`, `<=` now perform case-insensitive text comparisons
- **Percentage Strings**: Strings like "5%" are now converted in function arguments (not just operations)
- **Date/Time Strings**: Converted to serial numbers in arithmetic operations
- **Date Format**: Only accepts `yyyy-mm-dd hh:mm:ss` or locale-specific format
- **FALSE/TRUE Functions**: `=FALSE(5)` now returns #N/A error (was ERROR)

# 5.10.0

- Added event, triggered when a formula evaluation fails: `onerror(error: object, expression: object, variables: object, x: number, y: number, worksheet: object) => void`

# 5.9.0

- Fixed CEILING function bug.
- Added argument validation for FORECAST.
- Added argument validation for INTERCEPT.
- Reviewed and added argument validation for LINEST.
- Reviewed and added argument validation for LOGEST.
- Reviewed and added argument validation for TREND.
- Implemented operations to handle omitted arguments and accept boolean types.
- Updated ^ and & operations to properly handle numeric values and return correct errors.


# 5.4.3

- Cleaned up *formula names* that are not present in *Excel* or *Google Sheets*;
- Updated `REGEXEXTRACT`, `REGEXREPLACE`, and `REGEXMATCH` functions;
- Improved `ISERR` and `ISERROR` to catch errors caused by incorrect *function names*;
- The adjust precision feature has been improved;

# 5.4.0

- REVIEW MATCH and other database functions
- ISBLANK & OFFSET
- REFERENCE SY TYPE

# 5.3.1
- DAYS360 fix

# 5.3.0
- VLOOKUP updates
- Caching adjustments
- TEXT

# 5.1.0
- VLOOKUP: performance updates;
- OFFSET: create dynamic chains;

# 5.0.3
- AVERAGEIF: fix