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

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

@@ -0,0 +1,22 @@
+import { Scalar, Omittable, IRange, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the future value of an initial principal after applying a series of compound interest rates.
+ * @param principal is the present value.
+ * @param schedule is an array of interest rates to apply.
+ */
+export declare function FVSCHEDULE(principal: NoLift<Omittable<Scalar>>, schedule: Omittable<IRange>): number;
+/**
+ * Returns an equivalent interest rate for the growth of an investment.
+ * @param nper is the total number of payment periods.
+ * @param pv is the present value of the investment.
+ * @param fv is the future value of the investment.
+ */
+export declare function RRI(nper: number, pv: number, fv: number): number;
+/**
+ * Returns the number of periods required by an investment to reach a specified value.
+ * @param rate is the interest rate.
+ * @param pv is the present value of the investment.
+ * @param fv is the desired future value of the investment.
+ */
+export declare function PDURATION(rate: number, pv: number, fv: number): number;
+//# sourceMappingURL=Growth.d.ts.map

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

@@ -0,0 +1,82 @@
+import { AcceptError, Omittable, Scalar, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the price per $100 face value of a security with an odd first period.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param issue is the security's issue date, expressed as a serial date number.
+ * @param firstCoupon is the security's first coupon date, expressed as a serial date number.
+ * @param rate is the security's interest rate.
+ * @param yld is the security's annual yield.
+ * @param redemption is the security's redemption value per $100 face value.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * The odd FIRST period `[issue, firstCoupon]` is short (a stub of one regular period) or long
+ * (several quasi-coupon periods); which, and the day-count sums of either, are
+ * {@link oddFirstSums} — measured against Excel 16.0 on 1,125 (shape, frequency, basis) triples
+ * and every row of its battery (fn-battery financial/ODDFPRICE, 2026-08-29), Excel's own
+ * month-end exponent quirk included. Reading and validation are {@link readOddArgs}'s, then
+ * `issue < settlement < firstCoupon < maturity` once truncated, the first coupon on the
+ * maturity's coupon grid, `rate ≥ 0`, `yld ≥ 0`, `redemption > 0`; an odd period exactly one
+ * regular period long is #NUM!.
+ */
+export declare function ODDFPRICE(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, issue: NoLift<Omittable<AcceptError<Scalar>>>, firstCoupon: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the yield of a security with an odd first period.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param issue is the security's issue date, expressed as a serial date number.
+ * @param firstCoupon is the security's first coupon date, expressed as a serial date number.
+ * @param rate is the security's interest rate.
+ * @param pr is the security's price.
+ * @param redemption is the security's redemption value per $100 face value.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * The root of ODDFPRICE in the yield — a power form, so an iterate (Newton with a numerical
+ * derivative, bisection when that fails), not a closed form. Reads and validates as ODDFPRICE
+ * does, with `pr > 0` in place of the yield's sign.
+ */
+export declare function ODDFYIELD(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, issue: NoLift<Omittable<AcceptError<Scalar>>>, firstCoupon: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the price per $100 face value of a security with an odd last period.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param lastInterest is the security's last coupon date, expressed as a serial date number.
+ * @param rate is the interest rate.
+ * @param yld is the security's annual yield.
+ * @param redemption is the amount to be received at maturity.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `(redemption + C·ΣDCᵢ/NLᵢ) / (1 + yld/frequency · ΣDSCᵢ/NLᵢ) − C·ΣAᵢ/NLᵢ` with
+ * `C = 100·rate/frequency` — linear in the yield, since the whole bond is the one irregular
+ * period. The three sums are {@link oddLastSums}; a product that overflows is 0. Measured
+ * bit-for-bit on Excel 16.0 (fn-battery financial/ODDLPRICE, 556 numeric rows, 2026-08-28).
+ * Reading and validation are {@link readOddArgs}'s: `lastInterest < settlement < maturity` once
+ * truncated, `rate ≥ 0`, `yld ≥ 0`, `redemption > 0`.
+ */
+export declare function ODDLPRICE(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, lastInterest: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the yield of a security with an odd last period.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param lastInterest is the security's last coupon date, expressed as a serial date number.
+ * @param rate is the interest rate.
+ * @param pr is the security's price.
+ * @param redemption is the amount to be received at maturity.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * ODDLPRICE inverted — a closed form, not an iterate, because the price is linear in the yield.
+ * The grouping is measured rather than derived: `(N − D)/D · (frequency/ΣDSC)` over
+ * `N = redemption + C·ΣDC`, `D = pr + C·ΣA` is bit-exact on all 560 numeric rows of the battery
+ * where `frequency·(N/D − 1)/ΣDSC` holds only 14.3 digits. Reads and validates as ODDLPRICE
+ * does, with `pr > 0` in place of the yield's sign.
+ */
+export declare function ODDLYIELD(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, lastInterest: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+//# sourceMappingURL=Odd.d.ts.map

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

@@ -0,0 +1,17 @@
+import { IRange, Flatten } from '@sheetxl/primitives';
+/**
+ * Returns an array of historical quote data for a symbol and date range you specify..
+ * @hidden Unimplemented RichData
+ * @param stock Symbol of financial instrument to be considered or a Stock data type.
+ * @param startDate First date to return data from.
+ * @param endDate Last date to return data from.
+ * @param interval A number indicating the granularity of the data; 0 - Daily, 1 - Weekly, 2 - Monthly.
+ * @param headers A logical value to add column header data; 0 - No column header, 1 - Show column header, 2 - Show instrument identifier and column header.
+ * @param properties A number indicating which column of data to return; 0 through 5.
+ */
+export declare function STOCKHISTORY(stock: string, startDate: number, // date
+endDate?: number, // date
+interval?: number, // 0=day, 1=week, 2=month
+headers?: number, // 0=none, 1=field names, 2=field names and row numbers
+properties?: Flatten<number>): Promise<IRange>;
+//# sourceMappingURL=STOCKHISTORY.d.ts.map

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

@@ -0,0 +1,68 @@
+import { AcceptError, Omittable, Scalar, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the price per $100 face value of a security that pays periodic interest.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param rate is the interest rate.
+ * @param yld is the security's annual yield.
+ * @param redemption is the amount to be received at maturity.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * The doc's closed form over `calculatePrice`'s coupon-period numbers; a negative rate or
+ * yield, a redemption at or below zero, and a previous coupon date below the calendar are
+ * #NUM!.
+ */
+export declare function PRICE(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the annual duration of a security with periodic interest payments.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param coupon is the security's annual coupon rate.
+ * @param yld is the security's annual yield.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * The Macaulay duration — the present-value-weighted mean time to each cash flow, in coupon
+ * periods offset by the fraction of the current period already elapsed, over the frequency. A
+ * negative coupon or yield is #NUM!; a settlement in the first days of 1900 computes. Unlike
+ * PRICE, the slots read from the first and the basis last (`readBondArgs`).
+ */
+export declare function DURATION(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, coupon: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the Macauley modified duration for a security with an assumed par value of $100.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param coupon is the security's annual coupon rate.
+ * @param yld is the security's annual yield.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * DURATION divided by `1 + yld/frequency`; the same reading and validation as DURATION.
+ */
+export declare function MDURATION(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, coupon: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the yield on a security that pays periodic interest.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param rate is the security's annual coupon rate.
+ * @param pr is the security's price per $100 face value.
+ * @param redemption is the security's redemption value per $100 face value.
+ * @param frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * PRICE inverted: the yield `y` with `PRICE(…, y, …) = pr`. With one coupon left the doc's closed
+ * form is used, over a coupon period that is the real span from the previous coupon to the
+ * maturity (so at bases 2 and 3 the single-coupon yield does not invert PRICE's 360/f or 365/f
+ * period). With more than one it is `solveYieldByNewton` on `calculatePrice` from
+ * `approximateYield` — an iteration that STOPS SHORT of the root, so the answer sits ~1e-10 away
+ * from it, and on a bond it cannot converge on (a redemption that dwarfs the price) it is simply
+ * where the walk stood after a hundred steps. Measured, fn-battery financial/YIELD and
+ * /adhoc-yield-* (2026-08-28, iteration 2026-09-09).
+ */
+export declare function YIELD(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, frequency: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+//# sourceMappingURL=Security.d.ts.map

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

@@ -0,0 +1,107 @@
+import { AcceptError, Scalar, Omittable, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the discount rate for a security.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param pr is the security's price per $100 face value.
+ * @param redemption is the security's redemption value per $100 face value.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `(1 − pr/redemption)` over YEARFRAC's year fraction of the two dates — the signed NASD count
+ * at basis 0, the 365/366 rules at basis 1 — measured against Excel 16.0 (fn-battery
+ * financial/DISC, 2026-08-28); a price above the redemption is a negative rate, and a
+ * zero-day 30/360 span (Mar 30 → Mar 31) is #NUM!. The arguments read as
+ * {@link readDiscountArgs} describes.
+ */
+export declare function DISC(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the price per $100 face value of a discounted security.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param discount is the security's discount rate.
+ * @param redemption is the amount to be received at maturity.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `redemption − discount · redemption · yearfrac` with YEARFRAC's year fraction, measured
+ * against Excel 16.0 (fn-battery financial/PRICEDISC, 2026-08-28): a discount that exhausts
+ * the redemption gives a negative price, and the product overflowing is #NUM!. The arguments
+ * read as {@link readDiscountArgs} describes.
+ */
+export declare function PRICEDISC(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, discount: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the annual yield for a discounted security. For example, a treasury bill.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param pr is the security's price per $100 face value.
+ * @param redemption is the security's redemption value per $100 face value.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `(redemption − pr)/pr` over YEARFRAC's year fraction, measured against Excel 16.0 (fn-battery
+ * financial/YIELDDISC, 2026-08-28); a price above the redemption is a negative yield. The
+ * arguments read as {@link readDiscountArgs} describes.
+ */
+export declare function YIELDDISC(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the interest rate for a fully invested security.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param investment is the amount invested in the security.
+ * @param redemption is the amount to be received at maturity.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `(redemption − investment)/investment` over YEARFRAC's year fraction, measured against Excel 16.0
+ * (fn-battery financial/INTRATE, 2026-08-28); a redemption below the investment is a negative
+ * rate. The arguments read as {@link readDiscountArgs} describes.
+ */
+export declare function INTRATE(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, investment: NoLift<Omittable<AcceptError<Scalar>>>, redemption: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the amount received at maturity for a fully invested security.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param investment is the amount invested in the security.
+ * @param discount is the security's discount rate.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * `investment / (1 − discount · yearfrac)` with YEARFRAC's year fraction, measured against
+ * Excel 16.0 (fn-battery financial/RECEIVED, 2026-08-28); a denominator at or below zero (a
+ * discount of 4 over a 90/360 quarter) is #NUM!. The arguments read as
+ * {@link readDiscountArgs} describes.
+ */
+export declare function RECEIVED(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, investment: NoLift<Omittable<AcceptError<Scalar>>>, discount: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the price per $100 face value of a security that pays interest at maturity.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param issue is the security's issue date, expressed as a serial date number.
+ * @param rate is the interest rate.
+ * @param yld is the security's annual yield.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * The doc's `(100 + DIM/B·rate·100) / (1 + DSM/B·yld) − A/B·rate·100`, measured against Excel
+ * 16.0 (fn-battery financial/PRICEMAT, 2026-08-28) with the counts {@link readMatArgs}
+ * describes (DSM is `DIM − A`); a coupon term that overflows is 0, so a rate of 1E307 prices
+ * the redemption alone.
+ */
+export declare function PRICEMAT(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, issue: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, yld: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the annual yield of a security that pays interest at maturity.
+ * @param settlement is the security's settlement date, expressed as a serial date number.
+ * @param maturity is the security's maturity date, expressed as a serial date number.
+ * @param issue is the security's issue date, expressed as a serial date number.
+ * @param rate is the interest rate.
+ * @param pr is the security's price per $100 face value.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * PRICEMAT inverted in closed form, `((1 + DIM/B·rate) / (pr/100 + A/B·rate) − 1) / (DSM/B)`,
+ * measured against Excel 16.0 (fn-battery financial/YIELDMAT, 2026-08-28) with the counts
+ * {@link readMatArgs} describes.
+ */
+export declare function YIELDMAT(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, issue: NoLift<Omittable<AcceptError<Scalar>>>, rate: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<AcceptError<Scalar>>>): number;
+//# sourceMappingURL=SecurityMaturity.d.ts.map

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

@@ -0,0 +1,40 @@
+import { AcceptError, Scalar, Omittable, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the price per $100 face value for a treasury bill.
+ * @param settlement is the Treasury bill's settlement date, expressed as a serial date number.
+ * @param maturity is the Treasury bill's maturity date, expressed as a serial date number.
+ * @param discount is the Treasury bill's discount rate.
+ *
+ * @remarks
+ * `100·(1 − discount·days/360)`, measured against Excel 16.0 (fn-battery financial/TBILLPRICE,
+ * 2026-08-28): a negative price is #NUM!, and a `discount·days` that overflows is 0 (a price of
+ * 100). The arguments read as {@link readTbillArgs} describes.
+ */
+export declare function TBILLPRICE(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, discount: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the yield for a treasury bill.
+ * @param settlement is the Treasury bill's settlement date, expressed as a serial date number.
+ * @param maturity is the Treasury bill's maturity date, expressed as a serial date number.
+ * @param pr is the Treasury Bill's price per $100 face value.
+ *
+ * @remarks
+ * `(100 − pr)/pr · 360/days`, measured against Excel 16.0 (fn-battery financial/TBILLYIELD,
+ * 2026-08-28); a price above 100 is a negative yield. The arguments read as
+ * {@link readTbillArgs} describes.
+ */
+export declare function TBILLYIELD(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, pr: NoLift<Omittable<AcceptError<Scalar>>>): number;
+/**
+ * Returns the bond-equivalent yield for a treasury bill.
+ * @param settlement is the Treasury bill's settlement date, expressed as a serial date number.
+ * @param maturity is the Treasury bill's maturity date, expressed as a serial date number.
+ * @param discount is the Treasury bill's discount rate.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/TBILLEQ, 2026-08-28). Through 182 days the
+ * doc's `365·discount / (360 − discount·days)`; from 183 days the Treasury's bond-equivalent
+ * quadratic on the discounted price, over a 365-day year — 366 for a 366-day span. A
+ * denominator at or below zero is #NUM!; a product that overflows is 0. The arguments read as
+ * {@link readTbillArgs} describes.
+ */
+export declare function TBILLEQ(settlement: NoLift<Omittable<AcceptError<Scalar>>>, maturity: NoLift<Omittable<AcceptError<Scalar>>>, discount: NoLift<Omittable<AcceptError<Scalar>>>): number;
+//# sourceMappingURL=TBill.d.ts.map

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

@@ -1,5 +1,5 @@
 /**
- * @summary Returns the depreciation of an asset for any period you specify, including partial periods, using the double-declining balance method or some other method you specify.
+ * Returns the depreciation of an asset for any period you specify, including partial periods, using the double-declining balance method or some other method you specify.
  * @param cost is the initial cost of the asset.
  * @param salvage is the salvage value at the end of the life of the asset.
  * @param life is the number of periods over which the asset is being depreciated (sometimes called the useful life of the asset).
@@ -9,19 +9,21 @@
  * @param noSwitch switch to straight-line depreciation when depreciation is greater than the declining balance = FALSE; do not switch = TRUE.
  *
  * @remarks
- * including partial periods, using the double-declining balance method or
- * some other method you specify.
+ * Measured against Excel 16.0 (fn-battery financial/VDB and `adhoc-vdb-clamp`, 2026-08-28).
  *
- * VDB = Variable Declining Balance.  It generalises DDB by:
- *   • accepting fractional start/end periods
- *   • supporting any factor (not just 2)
- *   • optionally switching to straight-line when SL > DDB (noSwitch=FALSE)
+ * `no_switch = TRUE` is DDB period by period from the original cost, the first and last periods
+ * pro-rated by the fraction of them inside the window.
  *
- * The `noSwitch` flag controls the switch-to-SL behavior:
- *   FALSE (default) — switch to straight-line when it yields more depreciation
- *   TRUE            — pure declining-balance, never switch
+ * With the switch, Excel runs two passes. The first walks from 0 to `start` to find the balance
+ * there — the FRACTIONAL part of `start` first (a partial period charged as `raw·fraction`,
+ * clamped at salvage and never negative), then whole periods with the straight-line switch, each
+ * period's straight line measured against the life remaining at that point (so a start of 2.5
+ * or 6.5 switches on the same `[1.5, 2.5]` period). The second pass depreciates that balance over
+ * `end − start` periods with a remaining life of `life − start`, each period's declining-balance
+ * charge clamped at salvage (then pro-rated if partial), switching to straight-line when that is
+ * larger. The second pass is NOT floored at zero: an asset already below salvage is written UP
+ * to it in its first period (VDB(300,2400,10,0,1) is −2100), which is also why a whole-period
+ * start on such an asset is 0 — the first pass has already moved the balance to salvage.
  */
-export declare function VDB(cost: number, salvage: number, life: number, startPeriod: number, // date
-endPeriod: number, // date
-factor?: number, noSwitch?: boolean): number;
+export declare function VDB(cost: number, salvage: number, life: number, startPeriod: number, endPeriod: number, factor?: number, noSwitch?: boolean): number;
 //# sourceMappingURL=VDB.d.ts.map

package/types/src/lookupReference/GroupBy.d.ts

@@ -0,0 +1,14 @@
+import { AcceptError, IRange, Omittable } from '@sheetxl/primitives';
+/**
+ * Aggregate values by row fields.
+ * @param rowFields The range or array containing the row fields.
+ * @param values The range or array containing the values to aggregate.
+ * @param fn The function used to do the aggregations: a LAMBDA, a function name such as SUM, or an array of them.
+ * @param fieldHeaders A number between 0 and 3 that specifies whether the field data has headers and whether field headers should be returned in the results.
+ * @param totalDepth Show totals for the row fields. 0 for none, 1 for grand totals, 2 for grand total and first level subtotals, etc. A negative number shows them at the top.
+ * @param sortOrder The column index to sort the row fields on. A negative index will sort in reverse order.
+ * @param filterArray An array of boolean where TRUE represents a row to retain.
+ * @param fieldRelationship The relationship of fields when multiple columns are supplied to the rowFields argument. 0 for hierarchy, 1 for table.
+ */
+export declare function GROUPBY(rowFields: IRange, values: IRange, fn: AcceptError<any>, fieldHeaders?: Omittable<number>, totalDepth?: Omittable<number>, sortOrder?: Omittable<IRange>, filterArray?: Omittable<IRange>, fieldRelationship?: Omittable<number>): IRange;
+//# sourceMappingURL=GroupBy.d.ts.map

package/types/src/lookupReference/PivotBy.d.ts

@@ -0,0 +1,17 @@
+import { IRange, AcceptError, Omittable } from '@sheetxl/primitives';
+/**
+ * Aggregate values by rows and columns.
+ * @param rowFields The range or array containing the row fields.
+ * @param colFields The range or array containing the column fields.
+ * @param values The range or array containing the value fields.
+ * @param fn The function used to do the aggregations: a LAMBDA, a function name such as SUM, or an array of them.
+ * @param fieldHeaders A number between 0 and 3 that specifies whether the field data has headers and whether field headers should be return in the results.
+ * @param rowTotalDepth Show totals for the row fields. 0 for none, 1 for grand totals, 2 for grand totals and first level subtotals, etc. A negative number shows them at the top.
+ * @param rowSortOrder The column index to sort the row fields on. A negative index will sort in reverse order.
+ * @param colTotalDepth Show totals for the column fields. 0 for none, 1 for grand totals, 2 for grand totals and first level subtotals, etc. A negative number shows them at the left.
+ * @param colSortOrder The column index to sort the column fields on. A negative index will sort in reverse order.
+ * @param filterArray An array of boolean where TRUE represents a row to retain.
+ * @param relativeTo Defines what PERCENTOF is calculated relative to. 0 for column totals, 1 for row totals, 2 for the grand total, 3 for parent column totals, 4 for parent row totals.
+ */
+export declare function PIVOTBY(rowFields: Omittable<IRange>, colFields: Omittable<IRange>, values: IRange, fn: AcceptError<any>, fieldHeaders?: Omittable<number>, rowTotalDepth?: Omittable<number>, rowSortOrder?: Omittable<IRange>, colTotalDepth?: Omittable<number>, colSortOrder?: Omittable<IRange>, filterArray?: Omittable<IRange>, relativeTo?: Omittable<number>): IRange;
+//# sourceMappingURL=PivotBy.d.ts.map

package/types/src/statistical/{ETS.d.ts → Ets.d.ts}

@@ -1,45 +1,45 @@
-import { IRange, Scalar } from '@sheetxl/primitives';
+import { IRange, Scalar, Omittable } from '@sheetxl/primitives';
 /**
+ * Returns the forecasted value for a specific future target date using exponential smoothing method.
  * @name FORECAST.ETS
- * @summary Returns the forecasted value for a specific future target date using exponential smoothing method.
  * @param targetDate is the data point for which you want to predict a value. It should carry on the pattern of values in the timeline.
  * @param values is the array or range of numeric data you're predicting.
  * @param timeline is the independent array or range of numeric data. The dates in the timeline must have a consistent step between them and can't be zero.
  * @param seasonality [1] 0 = no seasonality; 1 = auto-detect; any integer > 1 = explicit seasonal period.
  * @param dataCompletion [1] 1 = interpolate missing values; 0 = fill with zeros.
- * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=Max, 4=Median, 5=Min, 6=Sum, 7=None (#NUM! if duplicates exist).
+ * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=CountA, 4=Max, 5=Median, 6=Min, 7=Sum.
  */
-export declare function FORECAST_ETS(targetDate: number, values: IRange, timeline: IRange, seasonality?: number, dataCompletion?: number, aggregation?: number): Scalar;
+export declare function FORECAST_ETS(targetDate: number, values: IRange, timeline: IRange, seasonality?: Omittable<number>, dataCompletion?: Omittable<number>, aggregation?: Omittable<number>): Scalar;
 /**
+ * Returns a confidence interval for the forecasted value at the specified target date.
  * @name FORECAST.ETS.CONFINT
- * @summary Returns a confidence interval for the forecasted value at the specified target date.
  * @param targetDate is the data point for which you want to predict a value. It should carry on the pattern of values in the timeline.
  * @param values is the array or range of numeric data you're predicting.
  * @param timeline is the independent array or range of numeric data. The dates in the timeline must have a consistent step between them and can't be zero.
  * @param confidenceLevel [0.95] Confidence probability, must be strictly between 0 and 1.
  * @param seasonality [1] 0 = no seasonality; 1 = auto-detect; any integer > 1 = explicit seasonal period.
  * @param dataCompletion [1] 1 = interpolate missing values; 0 = fill with zeros.
- * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=Max, 4=Median, 5=Min, 6=Sum, 7=None.
+ * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=CountA, 4=Max, 5=Median, 6=Min, 7=Sum.
  */
-export declare function FORECAST_ETS_CONFINT(targetDate: number, values: IRange, timeline: IRange, confidenceLevel?: number, seasonality?: number, dataCompletion?: number, aggregation?: number): Scalar;
+export declare function FORECAST_ETS_CONFINT(targetDate: number, values: IRange, timeline: IRange, confidenceLevel?: Omittable<number>, seasonality?: Omittable<number>, dataCompletion?: Omittable<number>, aggregation?: Omittable<number>): Scalar;
 /**
+ * Returns the length of the repetitive pattern in the data for the specific time series.
  * @name FORECAST.ETS.SEASONALITY
- * @summary Returns the length of the repetitive pattern in the data for the specific time series.
  * @param values is the array or range of numeric data you're predicting.
  * @param timeline is the independent array or range of numeric data. The dates in the timeline must have a consistent step between them and can't be zero.
  * @param dataCompletion [1] 1 = interpolate missing values; 0 = fill with zeros.
- * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=Max, 4=Median, 5=Min, 6=Sum, 7=None.
+ * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=CountA, 4=Max, 5=Median, 6=Min, 7=Sum.
  */
-export declare function FORECAST_ETS_SEASONALITY(values: IRange, timeline: IRange, dataCompletion?: number, aggregation?: number): Scalar;
+export declare function FORECAST_ETS_SEASONALITY(values: IRange, timeline: IRange, dataCompletion?: Omittable<number>, aggregation?: Omittable<number>): Scalar;
 /**
+ * Returns a requested statistic for the ETS forecast model.
  * @name FORECAST.ETS.STAT
- * @summary Returns a requested statistic for the ETS forecast model.
  * @param values is the array or range of numeric data you're predicting.
  * @param timeline is the independent array or range of numeric data.
  * @param statisticType 1=Alpha, 2=Beta (trend smoothing), 3=Gamma (seasonal smoothing), 4=MASE, 5=SMAPE, 6=MAE, 7=RMSE, 8=Step size.
  * @param seasonality [1] 0 = no seasonality; 1 = auto-detect; any integer > 1 = explicit seasonal period.
  * @param dataCompletion [1] 1 = interpolate missing values; 0 = fill with zeros.
- * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=Max, 4=Median, 5=Min, 6=Sum, 7=None.
+ * @param aggregation [1] Aggregation method for duplicate timestamps: 1=Average, 2=Count, 3=CountA, 4=Max, 5=Median, 6=Min, 7=Sum.
  */
-export declare function FORECAST_ETS_STAT(values: IRange, timeline: IRange, statisticType: number, seasonality?: number, dataCompletion?: number, aggregation?: number): Scalar;
-//# sourceMappingURL=ETS.d.ts.map
+export declare function FORECAST_ETS_STAT(values: IRange, timeline: IRange, statisticType: number, seasonality?: Omittable<number>, dataCompletion?: Omittable<number>, aggregation?: Omittable<number>): Scalar;
+//# sourceMappingURL=Ets.d.ts.map

package/types/src/statistical/Regression.d.ts

@@ -1,13 +1,7 @@
-import { FormulaError, Scalar, IRange, Omittable } from '@sheetxl/primitives';
+import { Scalar, IRange, Omittable, ReportType, NoLift } from '@sheetxl/primitives';
+import { RegressionData } from '../_utils/LeastSquares';
 /**
- * The least-squares regression family: LINEST / LOGEST report the fitted model, TREND / GROWTH
- * evaluate it at new x-values, and LOGEST / GROWTH are the linear pair run on `ln(y)`.
- *
- * All four share `_utils/LeastSquares.ts` — the known_y/known_x/new_x shape rules, the
- * rank-deficient QR solve, and the `stats` grid.
- */
-/**
- * @summary Returns statistics that describe a linear trend matching known data points, by fitting a straight line using the least squares method.
+ * Returns statistics that describe a linear trend matching known data points, by fitting a straight line using the least squares method.
  * @param knownYs is the set of y-values you already know in the relationship y = mx + b.
  * @param knownXs is an optional set of x-values that you may already know in the relationship y = mx + b.
  * @param constant is a logical value: the constant b is calculated normally if Const = TRUE; b is set equal to 0 if Const = FALSE.
@@ -15,9 +9,9 @@ import { FormulaError, Scalar, IRange, Omittable } from '@sheetxl/primitives';
  *
  * @remarks {@link https://support.microsoft.com/en-us/office/linest-function-84d7d0d9-6e50-4101-977a-fa7abf772b6d|Docs}
  */
-export declare function LINEST(knownYs: IRange, knownXs?: Omittable<IRange>, constant?: Omittable<boolean>, stats?: boolean): (number | FormulaError.Known)[][];
+export declare function LINEST(knownYs: IRange, knownXs?: ReportType<Omittable<IRange>>, constant?: Omittable<ReportType<NoLift<boolean>>>, stats?: Omittable<ReportType<NoLift<boolean>>>): Scalar[][];
 /**
- * @summary Returns statistics that describe an exponential curve matching known data points.
+ * Returns statistics that describe an exponential curve matching known data points.
  * @param knownYs is the set of y-values you already know in the relationship y = b*m^x.
  * @param knownXs is an optional set of x-values that you may already know in the relationship y = b*m^x.
  * @param constant is a logical value: the constant b is calculated normally if Const = TRUE; b is set equal to 1 if Const = FALSE.
@@ -25,25 +19,26 @@ export declare function LINEST(knownYs: IRange, knownXs?: Omittable<IRange>, con
  *
  * @remarks {@link https://support.microsoft.com/en-us/office/logest-function-f27462d8-3657-4030-866b-a272c1d18b4b|Docs}
  */
-export declare function LOGEST(knownYs: IRange, knownXs?: Omittable<IRange>, constant?: Omittable<boolean>, stats?: boolean): (number | FormulaError.Known)[][];
+export declare function LOGEST(knownYs: IRange, knownXs?: ReportType<Omittable<IRange>>, constant?: Omittable<ReportType<NoLift<boolean>>>, stats?: Omittable<ReportType<NoLift<boolean>>>): Scalar[][];
 /**
- * @summary Returns values along a linear trend fitted to known data points.
+ * Returns values along a linear trend fitted to known data points.
  * @param knownYs The known y-values in the relationship y = mx + b.
  * @param knownXs Optional x-values. Defaults to {1,2,3,...,n}.
  * @param newXs The x-values for which to predict y. Defaults to knownX.
- * @param useConst If FALSE, forces the constant b to zero. Defaults to TRUE.
+ * @param constant If FALSE, forces the constant b to zero. Defaults to TRUE.
  *
  * @remarks {@link https://support.microsoft.com/en-us/office/trend-function-e2f135f0-8827-4096-9873-9a7cf7b51ef1|Docs}
  */
-export declare function TREND(knownYs: IRange, knownXs?: Omittable<IRange>, newXs?: Omittable<IRange>, useConst?: Omittable<boolean>): Scalar[][];
+export declare function TREND(knownYs: IRange, knownXs?: ReportType<Omittable<IRange>>, newXs?: Omittable<IRange>, constant?: Omittable<ReportType<NoLift<boolean>>>): Scalar[][];
 /**
- * @summary Returns numbers in an exponential growth trend matching known data points.
+ * Returns numbers in an exponential growth trend matching known data points.
  * @param knownYs is the set of y-values you already know in the relationship y = b*m^x, an array or range of positive numbers.
  * @param knownXs is an optional set of x-values that you may already know in the relationship y = b*m^x, an array or range the same size as Known_y's.
  * @param newXs  are new x-values for which you want GROWTH to return corresponding y-values.
- * @param useConst is a logical value: the constant b is calculated normally if Const = TRUE; b is set equal to 1 if Const = FALSE.
+ * @param constant is a logical value: the constant b is calculated normally if Const = TRUE; b is set equal to 1 if Const = FALSE.
  *
  * @remarks {@link https://support.microsoft.com/en-us/office/growth-function-541a91dc-3d5e-437d-b156-21324e68b80d|Docs}
  */
-export declare function GROWTH(knownYs: IRange, knownXs?: Omittable<IRange>, newXs?: Omittable<IRange>, useConst?: Omittable<boolean>): number[][];
+export declare function GROWTH(knownYs: IRange, knownXs?: ReportType<Omittable<IRange>>, newXs?: Omittable<IRange>, constant?: Omittable<ReportType<NoLift<boolean>>>): Scalar[][];
+export type { RegressionData };
 //# sourceMappingURL=Regression.d.ts.map

package/types/src/statistical/{TTEST.d.ts → TTest.d.ts}

@@ -1,6 +1,6 @@
 import { IRange } from '@sheetxl/primitives';
 /**
- * @summary Returns the probability associated with a Student's t-Test.
+ * Returns the probability associated with a Student's t-Test.
  * @param array1 is the first data set.
  * @param array2 is the second data set.
  * @param tails specifies the number of distribution tails to return: one-tailed distribution = 1; two-tailed distribution = 2.
@@ -10,10 +10,10 @@ import { IRange } from '@sheetxl/primitives';
  * @remarks
  * {@link https://support.microsoft.com/en-us/office/t-test-function-d4e08ec3-c545-485f-962e-276f7cbed055|Docs}
  */
-export declare function TTEST(array1: IRange<number>, array2: IRange<number>, tails: number, type: number): number;
+export declare function TTEST(array1: IRange, array2: IRange, tails: number, type: number): number;
 /**
+ * Returns the probability associated with a Student's t-Test.
  * @name T.TEST
- * @summary Returns the probability associated with a Student's t-Test.
  * @param array1 is the first data set.
  * @param array2 is the second data set.
  * @param tails specifies the number of distribution tails to return: one-tailed distribution = 1; two-tailed distribution = 2.
@@ -23,5 +23,5 @@ export declare function TTEST(array1: IRange<number>, array2: IRange<number>, ta
  * @remarks
  * {@link https://support.microsoft.com/en-us/office/t-test-function-d4e08ec3-c545-485f-962e-276f7cbed055|Docs}
  */
-export declare function T_TEST(array1: IRange<number>, array2: IRange<number>, tails: number, type: number): number;
-//# sourceMappingURL=TTEST.d.ts.map
+export declare function T_TEST(array1: IRange, array2: IRange, tails: number, type: number): number;
+//# sourceMappingURL=TTest.d.ts.map