@sheetxl/formulas-extended 0.8.0-beta.1 → 0.8.0-beta.3

package/types/src/_utils/FinanceDayCount.d.ts

@@ -77,4 +77,50 @@ export declare function getDayCount(startSerial: number, endSerial: number, basi
  *
  */
 export declare function getDays360US(startSerial: number, endSerial: number): number;
+/** The last serial of the 1900 calendar (9999-12-31). */
+export declare const MAX_SERIAL_DATE = 2958465;
+/**
+ * Excel's date-slot domain for the day-count family, measured on DAYS360, YEARFRAC, DATEDIF
+ * and the six coupon functions (fn-battery financial/*, 2026-08-28): the RAW value must not be
+ * negative (`-1E-9` is #NUM!) and the truncated serial must not pass 9999-12-31 (`2958465.9` is
+ * a legal 9999-12-31). The fraction is otherwise discarded by every function in the family.
+ */
+export declare function isSerialDateInRange(serial: number): boolean;
+/**
+ * `YEARFRAC` — measured against Excel 16.0 (fn-battery financial/YEARFRAC, 2026-08-28). Both
+ * serials are truncated first, the earlier date becomes the start, and basis 0 is then the
+ * SIGNED NASD count: Excel orders the dates but never takes a magnitude, so
+ * `YEARFRAC(59,60,0)` — 1900-02-28, a real month end, against the phantom 1900-02-29 that is
+ * not — is `-1/360`. The other bases cannot go negative once ordered. The caller has validated
+ * the serials and the basis.
+ */
+export declare function getYearFrac(startSerial: number, endSerial: number, basis: number): number;
+/**
+ * The years to maturity a bond-yield ITERATION starts from — not `YEARFRAC`, and not the coupon
+ * count over the frequency. Whole years are stepped off the settlement (the day clamped to each
+ * destination month) and the remainder is the basis's own day count over the basis's year: the
+ * 30/360 counts over 360 at bases 0 and 4, real days over 360 at basis 2 and over 365 at basis 3,
+ * and real days over the MATURITY'S OWN year at basis 1 — 366 out of a leap year, whatever the
+ * remainder itself covers. Basis 0's February here is the LEGACY calendar's: a Feb 29 start is a
+ * month end and a Feb 28 is not, which is neither `getDayCount`'s rule (the real calendar's month
+ * end, so Feb 28 counts too) nor `getDays360US`'s (which also lets the conversion steer the end).
+ *
+ * Measured on 1,154 rows where the answer depends on nothing else (fn-battery
+ * financial/adhoc-yield-n, -n2, -n3), 2026-09-09.
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function getYearsToMaturity(settlement: number, maturity: number, basis: number): number;
+/**
+ * The stub-period day count of AMORLINC/AMORDEGRC (the year fraction is `days / yearDays`, and
+ * the caller groups that as Excel does) — measured against Excel 16.0 (fn-battery
+ * financial/AMORLINC, /AMORDEGRC, 2026-08-28), and NOT YEARFRAC's: serials are truncated, the
+ * 30/360 bases count days as `getDayCount` does over 360, basis 3 is actual days over 365, and
+ * basis 1 is actual days over the length of the PURCHASE year (366 only when that year is a
+ * Gregorian leap year — 1900 is not — whatever the span crosses; 2007-12-31 → 2008-12-31 is
+ * 366/365), and in both actual bases a real Feb 29 counts as the 28th (`_feb29AsFeb28`). A zero-day stub is a whole period (`purchase = first period`, or Dec 30 → Dec 31
+ * at basis 0), and a stub longer than a year is not capped. Basis 2 is not accepted by either
+ * function; the caller has refused it before this is called.
+ */
+export declare function getAmorDayCount(purchased: number, firstPeriod: number, basis: number): DayCount;
 //# sourceMappingURL=FinanceDayCount.d.ts.map

package/types/src/_utils/FinanceOdd.d.ts

@@ -0,0 +1,93 @@
+import { Omittable, Scalar } from '@sheetxl/primitives';
+/**
+ * The odd-coupon securities' shared machinery — the quasi-coupon chain of an irregular period
+ * and the day-count sums the price and yield forms are built from, measured against Excel 16.0
+ * (fn-battery financial/ODDLPRICE + /ODDLYIELD + /ODDFPRICE and the `adhoc-oddl-*` /
+ * `adhoc-oddf-*` probes, 2026-08-28/29).
+ */
+/**
+ * `(settlement, maturity, …dates, …numbers, frequency, [basis])` as the four ODD functions read
+ * it: every slot is Excel-declared `any` (a boolean is #VALUE!, an empty argument #N/A, a blank
+ * cell 0, a multi-cell reference does not broadcast — `NoLift<>` on every slot), and the order is
+ * coupon six's, not PRICE's. Each DATE is coerced and range-checked as it is read, so a negative
+ * `last_interest` is #NUM! over a text frequency; then the numbers are coerced; then the
+ * frequency is validated (1, 2 or 4 after truncation); then the BASIS, last. Only after all of
+ * that do the date ORDER and the signs decide — a text frequency beats a settlement that is
+ * after its maturity. Serials come back truncated.
+ */
+export declare function readOddArgs(dates: Omittable<Scalar>[], numbers: Omittable<Scalar>[], frequency: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    dates: number[];
+    numbers: number[];
+    frequency: number;
+    basis: number;
+};
+/**
+ * The three day-count sums of the odd LAST period `[lastInterest, maturity]`, in coupon-period
+ * units — the numbers ODDLPRICE and ODDLYIELD are built from. Measured on 1,780
+ * (shape, frequency, basis) triples, each sum exact (`fn-battery/financial/fit-oddl.mjs`).
+ *
+ * It takes TWO chains, as COUPDAYS' basis 1 did (batch 3): the DECAYING chain anchored at
+ * `lastInterest` gives the period ends and their lengths, while the STICKY chain decides only
+ * which period the maturity lands in — so an Aug 31 maturity against a decayed Aug 28 boundary
+ * is still inside the period that ENDS there and overhangs it by three days.
+ *
+ * Over the periods `[B₀ = lastInterest, B₁] … [B_{J−1}, B_J]`:
+ *
+ * - `A` and `DSC` walk their span (`lastInterest → settlement`, `settlement → maturity`) period
+ *   by period, no period contributing more than itself — a 31st period end counted raw runs one
+ *   day past its own length.
+ * - `DC` counts every period 1 except the last, which is measured BACKWARD from its end,
+ *   `(NL − count(maturity, B_J)) / NL`. That is what makes `DC ≠ A + DSC` at basis 0.
+ *
+ * A chain that leaves the calendar is #NUM!: past its end going forward, and — stepping BACK
+ * from the MATURITY to the first date at or below `lastInterest` — below serial 1 going back
+ * (measured: a ladder landing on serial 1 computes, one landing on serial 0 is #NUM!).
+ */
+export declare function oddLastSums(settlement: number, maturity: number, lastInterest: number, frequency: number, basis: number): {
+    A: number;
+    DC: number;
+    DSC: number;
+};
+/**
+ * The numbers ODDFPRICE's form is built from — `N` regular coupons after `firstCoupon`, the
+ * accrued sum `A` and the first coupon's sum `DC` (both in coupon-period units), and `u`, the
+ * fractional exponent every cash flow after the settlement is discounted by. Measured on 1,125
+ * (shape, frequency, basis) triples, the four sums solved out of Excel by linearity
+ * (`fn-battery/financial/oddf-model.mjs`, `verify-oddf.mjs`, `adhoc-oddf-*`, 2026-08-29).
+ *
+ * The maturity must sit on `firstCoupon`'s grid — `COUPPCD(firstCoupon, maturity) = firstCoupon`
+ * — and the doc's two branches are real, on DIFFERENT date machinery. `E` is the regular period
+ * around the settlement on that grid, PRICE's {@link couponPeriod} (`COUPDAYBS + COUPDAYSNC` at
+ * basis 1); `DFC` the basis's count issue → firstCoupon:
+ *
+ * - `DFC = E` is #NUM! — an odd period that is exactly a regular one.
+ * - SHORT (`DFC < E`): one period, every count over `E` — `A = issue→settlement`, `DC = DFC`,
+ *   `u = settlement→firstCoupon`, the last straight from the settlement (the NASD advance
+ *   included). `N` is `COUPNUM(settlement, maturity) − 1`, which counts a grid date between the
+ *   settlement and the first coupon when there is one (a settlement in the gap between a
+ *   decayed boundary and its sticky twin).
+ * - LONG (`DFC > E`): `COUPNUM(issue, firstCoupon)` quasi periods on the STICKY grid, their
+ *   boundaries walked DECAYED back from `firstCoupon` (each step subtracts `12/f` months from
+ *   the previous date and clamps: an Aug 31 anchor semiannual is Feb 28, then Aug 28) — so the
+ *   earliest period can end at or before the issue and count nothing. `NL` is each period's
+ *   own actual span at basis 1, `360/f` or `365/f` elsewhere; `A` walks issue → settlement as
+ *   days over `NL`; `DC` is the issue's period as days over `NL` and every later period exactly
+ *   1 (the doc's DCᵢ — visible at bases 2 and 3). The exponent `u = Nq + DSC/E` is on the
+ *   sticky grid instead: `DSC = E − COUPDAYBS` at bases 0/1/4 and the actual days to the next
+ *   grid date at 2/3, and `Nq` is `COUPNUM(settlement, firstCoupon) − 1` PLUS ONE on a
+ *   month-end first coupon — Excel discounts every cash flow one period too far — unless the
+ *   settlement is itself a month end or its month holds an earlier quasi-coupon date
+ *   (`adhoc-oddf-nq`, 957 settlements swept day by day).
+ *
+ * A chain that walks below the calendar is #NUM! in either branch (a settlement in the first
+ * days of 1900 has quasi dates in 1899).
+ */
+export declare function oddFirstSums(settlement: number, maturity: number, issue: number, firstCoupon: number, frequency: number, basis: number): {
+    N: number;
+    A: number;
+    DC: number;
+    u: number;
+};
+/** The ATP arithmetic of the family: a product that overflowed is 0 (batch 4's `overflowIsZero`). */
+export declare const zeroIfOverflow: (value: number) => number;
+//# sourceMappingURL=FinanceOdd.d.ts.map

package/types/src/_utils/FinanceSecurity.d.ts

@@ -0,0 +1,84 @@
+import { Omittable, Scalar } from '@sheetxl/primitives';
+/**
+ * Argument readers for the securities functions — every slot Excel-declared `any`, read in the
+ * order Excel reads them (measured against Excel 16.0, fn-battery financial/*, 2026-08-28).
+ *
+ * Two orders exist in the family. The discount securities (DISC PRICEDISC YIELDDISC INTRATE
+ * RECEIVED) CONVERT from the last slot to the first and only then look for errors in slot
+ * order; ACCRINTM, ACCRINT and the coupon functions convert and validate each slot from the
+ * first. Each function names its own.
+ */
+/** The basis slot: omitted or blank is 0, text parses, a boolean is #VALUE!, out of 0–4 after truncation is #NUM!. */
+export declare function readBasis(basis: Omittable<Scalar>): number;
+/** The two dates of a security, truncated, both in the calendar and the settlement strictly first — else #NUM!. */
+export declare function checkDateOrder(settlement: number, maturity: number): {
+    settlement: number;
+    maturity: number;
+};
+/**
+ * `(settlement, maturity, x, y, [basis])` as DISC, PRICEDISC, YIELDDISC, INTRATE and RECEIVED
+ * read it: the basis FIRST — coerced and range-checked, so a text basis is #VALUE!, a basis of 5
+ * is #NUM! and an error there is the answer whatever an earlier slot holds — then the four
+ * slots from the first, each coerced (its error or a text answered) before the next is read;
+ * then the domain: serials in the calendar, `settlement < maturity` once truncated, `x > 0`,
+ * `y > 0`. An omitted required slot is #N/A, a blank cell 0.
+ */
+export declare function readDiscountArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, x: Omittable<Scalar>, y: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    settlement: number;
+    maturity: number;
+    x: number;
+    y: number;
+    basis: number;
+};
+/**
+ * `(settlement, maturity, x)` as TBILLEQ, TBILLPRICE and TBILLYIELD read it: each slot coerced
+ * from the first (an error or a text is answered before the next slot is read, so a text `x`
+ * beats swapped dates), then the domain: both serials in the calendar, `settlement < maturity`
+ * once truncated, the maturity at most one calendar year out ({@link _anniversary}), `x > 0`.
+ * `days` is the actual span of the truncated serials.
+ */
+export declare function readTbillArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, x: Omittable<Scalar>): {
+    settlement: number;
+    maturity: number;
+    x: number;
+    days: number;
+};
+/**
+ * `(settlement, maturity, issue, rate, x, [basis])` as PRICEMAT and YIELDMAT read it: the basis
+ * first (coerced and range-checked, so a text basis is #VALUE! and a basis of 5 #NUM! whatever
+ * the other slots hold, and an error there wins), then the five slots from the first, each
+ * coerced before the next is read; then the domain — every serial in the calendar,
+ * `issue < settlement < maturity` once truncated, and the signs the caller checks. The three
+ * day counts come back with `DSM` as `DIM − A`, which is how Excel has it: at basis 0 a Feb 28
+ * settlement against a Mar 31 maturity counts 32 days inside a Jan 31 issue (60 − 28), where
+ * the NASD count of the pair alone is 31. `B` is the year length of the issue→settlement pair.
+ */
+export declare function readMatArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, issue: Omittable<Scalar>, rate: Omittable<Scalar>, x: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    rate: number;
+    x: number;
+    DIM: number;
+    DSM: number;
+    A: number;
+    B: number;
+};
+/**
+ * `(settlement, maturity, …numbers, frequency, [basis])` as PRICE, YIELD, DURATION and
+ * MDURATION read it (measured on all four, fn-battery 2026-08-28). PRICE and YIELD read the
+ * basis FIRST — coerced and range-checked, so a text basis is #VALUE! and a 5 is #NUM! whatever
+ * else is wrong, and an error there wins over an error in the settlement; DURATION and
+ * MDURATION read it LAST (`basisLast`), the coupon functions' way. In between, the settlement
+ * and the maturity are each coerced and checked against the calendar before the next slot is
+ * read (a negative settlement is #NUM! over a text frequency), then the numeric slots are
+ * coerced, then the frequency is coerced and validated (1, 2 or 4 after truncation); the date
+ * order (`settlement < maturity` once truncated) and the signs of the numbers come last.
+ */
+export declare function readBondArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, numbers: Omittable<Scalar>[], frequency: Omittable<Scalar>, basis: Omittable<Scalar>, basisLast?: boolean): {
+    settlement: number;
+    maturity: number;
+    numbers: number[];
+    frequency: number;
+    basis: number;
+};
+/** Excel's Analysis-ToolPak arithmetic answers 0 for a product that overflowed (measured on ACCRINTM, TBILLEQ, TBILLPRICE, PRICEMAT). */
+export declare const overflowIsZero: (value: number) => number;
+//# sourceMappingURL=FinanceSecurity.d.ts.map

package/types/src/_utils/FinanceUtils.d.ts

@@ -1,4 +1,25 @@
 import { IRuntime } from '@sheetxl/primitives';
+/**
+ * The secant step cap shared by RATE and IRR — Excel gives up after 200, not the documented 20
+ * (measured on one 24-period loan: a path of 200 steps converges, one of 203 is #NUM!). IRR runs
+ * the same iteration on the discount factor rather than the rate, so the cap is one fact.
+ */
+export declare const RATE_MAX_ITERATIONS = 200;
+/**
+ * The currency format Excel gives a financial result cell, in the runtime's locale.
+ *
+ * @remarks
+ * Which functions auto-format is a per-function fact and was MEASURED across the category
+ * (2026-08-29, `Range.NumberFormat` read after a `Formula2` entry into a General cell): the
+ * legacy core formats by result kind — money through this helper (NPV PMT IPMT PPMT FV PV SLN
+ * SYD DB DDB VDB) and a rate as `0%` (IRR MIRR RATE) — while everything ATP-era or added later
+ * sets nothing at all (XIRR XNPV NPER ISPMT RRI PDURATION EFFECT NOMINAL FVSCHEDULE CUMIPMT
+ * CUMPRINC and every security, COUPNCD and COUPPCD included).
+ *
+ * Excel applies it at ENTRY, before it knows the answer, so a `#NUM!`, `#VALUE!` or `#DIV/0!`
+ * cell carries the format too. That is why every `formatResults` call in this category LEADS its
+ * body instead of following the domain guards.
+ */
 export declare const defaultCurrencyFormat: (runtime: IRuntime) => string;
 /**
  * `base ^ exponent` as Excel evaluates it (the `^` operator, POWER, and the powers inside the
@@ -17,4 +38,17 @@ export declare const defaultCurrencyFormat: (runtime: IRuntime) => string;
  * A zero base follows the `^` operator: `0^0` is #NUM! and `0^negative` is #DIV/0!.
  */
 export declare const excelPow: (base: number, exponent: number) => number;
+/**
+ * Excel's C `(int)` cast of an argument: truncation toward zero, and INT_MIN for anything out of
+ * the 32-bit range (the x64 `cvttsd2si` convention), NaN included. Measured on DB (fn-battery,
+ * 2026-08-28): `DB(…,3E9,2E9)` is #NUM! because only `life` overflows to INT_MIN while
+ * `DB(…,1E10,5E9)` is 0 because both do.
+ */
+export declare const excelInt32: (value: number) => number;
+/**
+ * Round to `digits` decimals as Excel's ROUND does: ties away from zero, decided on the value's
+ * 15-significant-digit decimal form rather than its binary one — `550 · 0.45` is
+ * 247.49999999999997 in double and Excel rounds it to 248 (AMORDEGRC, measured 2026-08-28).
+ */
+export declare const excelRound: (value: number, digits?: number) => number;
 //# sourceMappingURL=FinanceUtils.d.ts.map

package/types/src/_utils/LeastSquares.d.ts

@@ -1,4 +1,4 @@
-import { FormulaError, IRange } from '@sheetxl/primitives';
+import { FormulaError, IRange, IReferenceRange, Scalar } from '@sheetxl/primitives';
 /**
  * How Excel reads `known_y` / `known_x` into (observations x predictors).
  *
@@ -33,15 +33,22 @@ export interface RegressionData {
 /**
  * Reads `known_y` / `known_x` the way the whole LINEST family does.
  *
- * STRICT membership: any non-numeric member of either range — text, boolean, or BLANK — is
- * `#VALUE!`. There is no skipping and no coercion here (`LINEST({2;TRUE;5;4}, …)` and
- * `LINEST({2;"3";5;4}, …)` are both `#VALUE!`), which is the opposite of the paired statistics
- * (CORREL/SLOPE/…) where a non-numeric member drops its pair. Dropping a member here would shift
- * every later observation against its x and silently return a different fit.
+ * The SHAPES are judged first — a mismatch is #REF! whatever the members hold — and then the
+ * members, in order. Membership is STRICT: any non-numeric member of either range — text,
+ * boolean, or BLANK — is `#VALUE!`. There is no skipping and no coercion here
+ * (`LINEST({2;TRUE;5;4}, …)` and `LINEST({2;"3";5;4}, …)` are both `#VALUE!`), which is the
+ * opposite of the paired statistics (CORREL/SLOPE/…) where a non-numeric member drops its pair.
+ * Dropping a member here would shift every later observation against its x and silently return a
+ * different fit.
  *
- * @throws #VALUE! on a non-numeric member, #REF! on a dimension mismatch.
+ * `log` is the LOGEST/GROWTH read: each y is checked as it is met, so a y at or below zero is
+ * #NUM! even when a text member sits later in the range, and the ys come back as their logarithms.
+ *
+ * @throws #VALUE! on a non-numeric member, #REF! on a dimension mismatch, #NUM! on a y without a
+ * logarithm.
  */
-export declare const readRegressionData: (knownYs: IRange, knownXs: IRange | undefined) => RegressionData;
+export declare const readRegressionData: (knownYs: IRange, knownXs: IRange | undefined, log?: boolean) => RegressionData;
+export declare const overLogical: (value: boolean | IReferenceRange | IReferenceRange[] | null | undefined, absent: boolean, compute: (value: boolean) => Scalar[][]) => Scalar[][];
 /**
  * Reads a `new_x` range into (observations x k), and reports the shape its predictions spill into.
  *
@@ -57,15 +64,6 @@ export declare const readNewX: (newXs: IRange, data: RegressionData) => {
     rows: number;
     cols: number;
 };
-/**
- * `ln(y)` for the log-space members of the family (LOGEST / GROWTH).
- *
- * A y at or below zero has no logarithm, and Excel reports that as #NUM! — a distinct outcome from
- * the #VALUE! a non-numeric member gets, so the two checks stay separate.
- *
- * @throws #NUM! when any y is <= 0.
- */
-export declare const toLogYs: (ys: number[]) => number[];
 /**
  * Evaluates a fit over `new_x`, in the shape Excel spills.
  *
@@ -73,7 +71,7 @@ export declare const toLogYs: (ys: number[]) => number[];
  * the fitted values, so a 6x2 `known_y` spills 6x2. Otherwise the shape comes from `new_x`
  * ({@link readNewX} decides whether that is element-wise or one row/column per observation).
  */
-export declare const predictInShape: (data: RegressionData, newXs: IRange | undefined, predict: (x: number[]) => number) => number[][];
+export declare const predictInShape: (data: RegressionData, newXs: IRange | undefined, predict: (x: number[]) => Scalar) => Scalar[][];
 /** A fitted model — coefficients in Excel's slot order plus everything the stats grid needs. */
 export interface RegressionFit {
     /**
@@ -81,11 +79,11 @@ export interface RegressionFit {
      * belongs to the LAST column of `known_x`.
      */
     coefficients: number[];
-    /** Standard errors in the same slot order. `se[k]` is meaningless when `!useConst` (Excel: #N/A). */
+    /** Standard errors in the same slot order. `se[k]` is meaningless when `!constant` (Excel: #N/A). */
     standardErrors: number[];
     /** Number of predictors actually used — a column dropped for rank deficiency does not count. */
     kEffective: number;
-    /** `n - kEffective - (useConst ? 1 : 0)`. */
+    /** `n - kEffective - (constant ? 1 : 0)`. */
     df: number;
     /** Standard error of the y estimate. 0 when `df <= 0`, which is what Excel returns. */
     sey: number;
@@ -111,7 +109,7 @@ export interface RegressionFit {
  * The same path covers "not enough observations": with n = 2 and 2 predictors the second column
  * has no residual left and is dropped, which is exactly what Excel returns.
  */
-export declare const fitLeastSquares: (ys: number[], xs: number[][], useConst: boolean) => RegressionFit;
+export declare const fitLeastSquares: (ys: number[], xs: number[][], constant: boolean) => RegressionFit;
 /**
  * The `stats = TRUE` grid: 5 rows x (k + 1) columns.
  *
@@ -127,5 +125,5 @@ export declare const fitLeastSquares: (ys: number[], xs: number[][], useConst: b
  * `se(b)` when the intercept was not fitted — the b slot itself still carries a value (0 for
  * LINEST, 1 for LOGEST), it is only its error that is #N/A.
  */
-export declare const buildStatsGrid: (fit: RegressionFit, coefficients: number[], useConst: boolean) => (number | FormulaError.Known)[][];
+export declare const buildStatsGrid: (fit: RegressionFit, coefficients: (number | FormulaError.Known)[], constant: boolean) => (number | FormulaError.Known)[][];
 //# sourceMappingURL=LeastSquares.d.ts.map

package/types/src/_utils/RegexCompile.d.ts

@@ -0,0 +1,33 @@
+import { FormulaError } from '@sheetxl/primitives';
+/** A compiled Excel pattern: the regex, and how many capture groups it has. */
+export interface CompiledPattern {
+    regex: RegExp;
+    groups: number;
+}
+/**
+ * Compiles one of Excel's patterns, or `#VALUE!` when neither reading of it will compile.
+ *
+ * The translated form is tried first, under `u`. A pattern that will not compile that way is
+ * retried EXACTLY AS WRITTEN and without `u` — that is the pre-translation reading, and it keeps
+ * the patterns that only `u`'s stricter escaping would have broken (`\-` outside a class) working.
+ */
+export declare const compilePattern: (pattern: string, caseInsensitive: boolean, extraFlags?: string) => CompiledPattern | FormulaError.Known;
+/**
+ * Excel's replacement text, as JavaScript's.
+ *
+ * The two languages nearly agree — `$1`, `$&`, `` $` `` and `$'` mean the same in both — and
+ * differ in three places: Excel's `$0` is the whole match (JavaScript spells that `$&`), its
+ * `${1}` and `${name}` are references where JavaScript reads them literally, and a reference to a
+ * group that does not exist is `#VALUE!` rather than literal text. That last one is why this
+ * returns an error instead of a string: `REGEXREPLACE("ab","(a)(b)","$3")` is refused by Excel,
+ * and so is a lone `$`.
+ */
+export declare const translateReplacement: (replacement: string, groups: number) => string | FormulaError.Known;
+/**
+ * Excel's 0-or-1 enum slots (`caseSensitivity`, and `returnMode`'s three values).
+ *
+ * Truncated first — 1.5 is 1 — and anything outside the list is `#VALUE!`, including a huge value
+ * and non-numeric text.
+ */
+export declare const readMode: (value: number, max: number) => number | FormulaError.Known;
+//# sourceMappingURL=RegexCompile.d.ts.map

package/types/src/cube/Cube.d.ts

@@ -1,6 +1,6 @@
 /**
+ * Returns a key performance indicator (KPI) property and displays the KPI name in the cell.
  * @hidden Unimplemented Cube
- * @summary Returns a key performance indicator (KPI) property and displays the KPI name in the cell.
  * @param connection is the name of a connection to an OLAP cube.
  * @param kpiName is the KPI name.
  * @param kpiProperty is the KPI property.
@@ -9,24 +9,24 @@
 export declare function CUBEKPIMEMBER(connection: string, kpiName: string, kpiProperty: number, // option 1-6
 caption?: string): Promise<string>;
 /**
+ * Returns a member or tuple from the cube.
  * @hidden Unimplemented Cube
- * @summary Returns a member or tuple from the cube.
  * @param connection is the name of a connection to an OLAP cube.
  * @param memberExpression is the expression representing the name of a member or tuple in the OLAP cube.
  * @param caption is the caption to be displayed in the cell.
  */
 export declare function CUBEMEMBER(connection: string, memberExpression: string, caption?: string): Promise<string>;
 /**
+ * Returns the value of a member property from the cube.
  * @hidden Unimplemented Cube
- * @summary Returns the value of a member property from the cube.
  * @param connection is the name of a connection to an OLAP cube.
  * @param memberExpression is the expression representing the name of a member in the OLAP cube.
  * @param kpiProperty is the property name.
  */
 export declare function CUBEMEMBERPROPERTY(connection: string, memberExpression: string, kpiProperty: number): Promise<string>;
 /**
+ * Returns the nth, or ranked, member in a set.
  * @hidden Unimplemented Cube
- * @summary Returns the nth, or ranked, member in a set.
  * @param connection is the name of a connection to an OLAP cube.
  * @param setExpression is the set from which the element is to be retrieved.
  * @param rank is the rank of the element to be retrieved.
@@ -35,8 +35,8 @@ export declare function CUBEMEMBERPROPERTY(connection: string, memberExpression:
 export declare function CUBERANKEDMEMBER(connection: string, setExpression: string, rank: number, // 1 - 5
 caption?: string): Promise<string>;
 /**
+ * Defines a calculated set of members or tuples by sending a set expression to the cube on the server, which creates the set, and then returns that set to Microsoft Excel.
  * @hidden Unimplemented Cube
- * @summary Defines a calculated set of members or tuples by sending a set expression to the cube on the server, which creates the set, and then returns that set to Microsoft Excel.
  * @param connection is the name of a connection to an OLAP cube.
  * @param setExpression is the expression for the set.
  * @param caption is the caption to be displayed in the cell.
@@ -49,14 +49,14 @@ caption?: string): Promise<string>;
 export declare function CUBESET(connection: string, setExpression: string, caption?: string, sortOrder?: number, // 1 - 6
 sortBy?: string): Promise<string>;
 /**
+ * Returns the number of items in a set.
  * @hidden Unimplemented Cube
- * @summary Returns the number of items in a set.
  * @param set is the set whose elements are to be counted.
  */
 export declare function CUBESETCOUNT(set: string): Promise<number>;
 /**
+ * Returns an aggregated value from the cube.
  * @hidden Unimplemented Cube
- * @summary Returns an aggregated value from the cube.
  * @param connection is the name of a connection to an OLAP cube.
  * @param memberExpression is a slicer that determines the portion of the OLAP cube for which the aggregation value is to be retrieved.
  */

package/types/src/financial/ACCRINT.d.ts

@@ -1,5 +1,6 @@
+import { AcceptError, Omittable, Scalar, NoLift } from '@sheetxl/primitives';
 /**
- * @summary Returns the accrued interest for a security that pays periodic interest.
+ * Returns the accrued interest for a security that pays periodic interest.
  * @param issue is the security's issue date, expressed as a serial date number.
  * @param firstInterest is the security's first interest date, expressed as a serial date number.
  * @param settlement is the security's settlement date, expressed as a serial date number.
@@ -10,10 +11,36 @@
  * @param calcMethod is a logical value: to accrued interest from issue date = TRUE; to calculate from last coupon payment date = FALSE.
  *
  * @remarks
- * {@link https://support.microsoft.com/en-us/office/accrint-function-fe45d089-6722-4fb3-9379-e1f911d8dc74|Docs}
+ * `par · rate/frequency · Σ(Aᵢ/NLᵢ)` over the quasi-coupon periods anchored at `first_interest`,
+ * as Excel 16.0 composes it (fn-battery financial/ACCRINT and adhoc-accrint-clamped, 1,796 rows,
+ * 2026-08-28 / 2026-09-09) — see {@link accruedPeriods}.
+ * The seven leading slots are Excel-declared `any` (a boolean is #VALUE!, an empty slot #N/A —
+ * except `par`, which is 1000 when omitted — a blank cell 0); `calc_method` is a logical read
+ * FIRST: any number is accepted (nonzero is TRUE), text — `"TRUE"` included — is #VALUE!. Then
+ * the slots are read from the first, each coerced and validated before the next (a negative
+ * issue is #NUM! over a text frequency, a frequency of 3 over a text basis): every date in the
+ * calendar, the frequency 1/2/4 and the basis 0–4 after truncation; then `issue < settlement`,
+ * `rate > 0`, `par > 0`, and a quasi-coupon date the walk needs below serial 1 or past the
+ * calendar's end is #NUM!. A product that overflows is 0.
  */
-export declare function ACCRINT(issue: number, // date
-firstInterest: number, //date
-settlement: number, //date
-rate: number, par: number, frequency: number, basis?: number, calcMethod?: boolean): number;
+export declare function ACCRINT(issue: NoLift<Omittable<AcceptError<Scalar>>>, firstInterest: NoLift<Omittable<AcceptError<Scalar>>>, settlement: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, par: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>, calcMethod?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the accrued interest for a security that pays interest at maturity.
+ * @param issue is the security's issue date, expressed as a serial date number.
+ * @param settlement is the security's maturity date, expressed as a serial date number.
+ * @param rate is the security's annual coupon rate.
+ * @param par is the security's par value.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `par · rate · yearfrac(issue, settlement)` with YEARFRAC's year fraction (the signed NASD
+ * count at basis 0), measured against Excel 16.0 (fn-battery financial/ACCRINTM, 2026-08-28).
+ * There is no quasi-coupon walk here — a security paying at maturity has one period — so the
+ * two share their reading and nothing else. The slots read from the first: each date is coerced
+ * and checked against the calendar before the next slot is looked at, then the rate, the par and
+ * the basis are coerced, and only then the date order (`issue ≤ settlement` once truncated —
+ * equal is 0) and the signs of the rate and the par. An OMITTED par is 1000 (a blank cell is 0,
+ * and #NUM!). A product that overflows is 0.
+ */
+export declare function ACCRINTM(issue: NoLift<Omittable<AcceptError<Scalar>>>, settlement: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, par: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
 //# sourceMappingURL=ACCRINT.d.ts.map

package/types/src/financial/AMORDEGRC.d.ts

@@ -1,6 +1,6 @@
+import { Scalar, Omittable, NoLift } from '@sheetxl/primitives';
 /**
- * @summary Returns the depreciation for each accounting period using a
- * depreciation coefficient (French degressive / accelerated depreciation).
+ * Returns the depreciation for each accounting period using a depreciation coefficient (French degressive / accelerated depreciation).
  * @param cost is the cost of the asset.
  * @param datePurchased is the date the asset is purchased.
  * @param firstPeriod is the date of the end of the first period.
@@ -10,44 +10,26 @@
  * @param basis is the type of day count basis to use.
  *
  * @remarks
- * AMORDEGRC is the accelerated counterpart to AMORLINC. The depreciation
- * rate is multiplied by a coefficient that depends on the asset's useful life
- * (computed as `1 / rate`):
+ * Measured against Excel 16.0 (fn-battery financial/AMORDEGRC, 2026-08-28), where it differs from
+ * the documentation in most places:
  *
- *   life (1/rate)  │ coefficient
- *   ───────────────┼────────────
- *   < 3 years      │ 1.5 (special algorithm — see below)
- *   3–4 years      │ 1.5
- *   5–6 years      │ 2.0
- *   > 6 years      │ 2.5
- *
- * The accelerated rate = rate × coefficient.
- *
- * Normal algorithm (life >= 3, per Excel spec):
- *   Period 0: FLOOR(cost × rateAccel × (days / 365))   [basis=1 always uses 365]
- *             bv carry-forward uses actual yearDays (366 for leap years)
- *   Period N: FLOOR(max(DDB, SL)) where:
- *               DDB = bv × rateAccel
- *               SL  = bv / (ceil(1/rate) − period)   [no salvage subtraction]
- *             No clamping to (bv − salvage) — Excel deprecates past salvage.
- *             Returns 0 when bv ≤ salvage at start of period.
- *
- * Special algorithm (life < 3):
- *   Period 0: FLOOR(cost × rateAccel × (days / actualYearDays))
- *   Period N: CEIL(bv / (ceil(1/rate) − 1))  — same value for all remaining periods
- *   Returns 0 once all remaining periods are exhausted.
- *
- * Excel-verified behaviors:
- *   - basis=2 and basis=4 return #NUM! (unlike AMORLINC which rejects basis=2
- *     only; AMORDEGRC rejects both)
- *   - life < 3 does NOT return #NUM! despite documentation — Excel computes
- *     using coeff=1.5 with the simplified equal-split algorithm above
- *   - period 0 for basis=1 with life >= 3: return value uses yearDays=365,
- *     but the bv carried into period 1 uses the actual yearDays (366 for leap).
- *     This means total depreciation across all periods can exceed cost by 1
- *     for the life < 3 case — this matches Excel's behavior exactly.
+ * - The life is `1/rate`. A life of 2 or less is #NUM!; the coefficient is 1.5 up to a life of 4,
+ *   2 up to 6, 2.5 beyond (the documented "1 to 2 years" and "4 to 5 years" bands do not exist).
+ * - Period 0 is `cost · rate · coefficient · stub fraction` (the AMORLINC stub, see
+ *   `getAmorDayCount`), capped at `cost − salvage`, ROUNDED — half away from zero, not
+ *   floored — and carried into the balance rounded.
+ * - Each later period is the declining charge `balance · rate · coefficient`, except the LAST
+ *   TWO periods of `ceil(life)`, which split the balance in two and then take the rest. There is
+ *   no other straight-line switch (a 10-year asset stays on the declining charge in period 7
+ *   although straight line is larger). Every returned charge is rounded, but the balance carries
+ *   the UNROUNDED charge.
+ * - A balance already below salvage at the start of a period returns 0; one equal to salvage is
+ *   still depreciated (`AMORDEGRC(2400,…,2399,1,0.15,1)` is 900).
+ * - A period under 1 is period 1 and above 1 truncates — except that Excel answers other
+ *   periods' values for some fractions below 1 (0.1 and 1E-300 answer period 5, 0.5 answers 0);
+ *   those rows are accepted differences.
+ * - Every argument is Excel-declared `any`: a boolean is refused, an empty argument is missing, a
+ *   multi-cell reference does not broadcast. Basis truncates and 2 is refused; 4 is accepted.
  */
-export declare function AMORDEGRC(cost: number, datePurchased: number, // date serial
-firstPeriod: number, // date serial
-salvage: number, period: number, rate: number, basis?: number): number;
+export declare function AMORDEGRC(cost: NoLift<Omittable<Scalar>>, datePurchased: NoLift<Omittable<Scalar>>, firstPeriod: NoLift<Omittable<Scalar>>, salvage: NoLift<Omittable<Scalar>>, period: NoLift<Omittable<Scalar>>, rate: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
 //# sourceMappingURL=AMORDEGRC.d.ts.map