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

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

@@ -0,0 +1,26 @@
+import { Scalar, Omittable, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the effective annual interest rate.
+ * @param nominalRate is the nominal interest rate.
+ * @param npery is the number of compounding periods per year.
+ */
+export declare function EFFECT(nominalRate: NoLift<Omittable<Scalar>>, npery: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the annual nominal interest rate.
+ * @param effectiveRate is the effective interest rate.
+ * @param npery is the number of compounding periods per year.
+ */
+export declare function NOMINAL(effectiveRate: NoLift<Omittable<Scalar>>, npery: NoLift<Omittable<Scalar>>): number;
+/**
+ * Converts a dollar price, expressed as a fraction, into a dollar price, expressed as a decimal number.
+ * @param fractionalDollar is a number expressed as a fraction.
+ * @param fraction is the integer to use in the denominator of the fraction.
+ */
+export declare function DOLLARDE(fractionalDollar: NoLift<Omittable<Scalar>>, fraction: NoLift<Omittable<Scalar>>): number;
+/**
+ * Converts a dollar price, expressed as a decimal number, into a dollar price, expressed as a fraction.
+ * @param decimalDollar is a decimal number.
+ * @param fraction is the integer to use in the denominator of the fraction.
+ */
+export declare function DOLLARFR(decimalDollar: NoLift<Omittable<Scalar>>, fraction: NoLift<Omittable<Scalar>>): number;
+//# sourceMappingURL=Convert.d.ts.map

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

@@ -0,0 +1,72 @@
+import { Omittable, Scalar, NoLift } from '@sheetxl/primitives';
+/**
+ * Coupon date and day-count functions.
+ *
+ * The six share one argument reader, `readCouponArgs` — every slot is Excel-declared `any`,
+ * the dates and frequency validate before the basis is read — and one coupon chain,
+ * `FinanceCoupon`'s, both measured against Excel 16.0 (fn-battery financial/COUP*,
+ * 2026-08-28). COUPNCD and COUPPCD return date serials, not day counts.
+ */
+/**
+ * Returns the number of days from the beginning of the coupon period to the settlement date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ */
+export declare function COUPDAYBS(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the number of days in the coupon period containing the settlement date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ */
+export declare function COUPDAYS(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the number of days from the settlement date to the next coupon date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ */
+export declare function COUPDAYSNC(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the next coupon date after the settlement date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * Returns a date serial and leaves the cell's format alone — Excel does not hint one here, on a
+ * serial argument, on `DATE(...)` or on a date-formatted reference (measured 2026-08-29). No
+ * ATP-era date function does; `DATE` and `TODAY` do, and an operator such as `B1+1` propagates
+ * its operand's.
+ */
+export declare function COUPNCD(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the previous coupon date before the settlement date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * Returns a date serial and leaves the cell's format alone, as COUPNCD does. A previous coupon
+ * date below the calendar (a settlement in the first days of 1900) answers 0, as Excel does.
+ */
+export declare function COUPPCD(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+/**
+ * Returns the number of coupons payable between the settlement date and maturity date.
+ * @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 frequency is the number of coupon payments per year.
+ * @param basis is the type of day count basis to use.
+ *
+ * @remarks
+ * A previous coupon date at or below the calendar's serial 0 is #NUM!, where COUPPCD itself
+ * still answers 0 (measured).
+ */
+export declare function COUPNUM(settlement: NoLift<Omittable<Scalar>>, maturity: NoLift<Omittable<Scalar>>, frequency: NoLift<Omittable<Scalar>>, basis?: NoLift<Omittable<Scalar>>): number;
+//# sourceMappingURL=Coupon.d.ts.map

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

@@ -1,27 +1,56 @@
-import { Scalar } from '@sheetxl/primitives';
+import { AcceptError, Scalar, Omittable, NoLift } from '@sheetxl/primitives';
 /**
+ * Returns the number of days between two dates.
  * @hidden Legacy
- * @summary Returns the number of days between two dates.
  * @param startDate is a serial date number that represents the start date.
  * @param endDate is a serial date number that represents the end date.
  * @param unit is a string that specifies the unit of time to use.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/DATEDIF, 2026-08-28). Both serials are
+ * truncated before anything is compared (`DATEDIF(37179.6,37179.5,"d")` is 0); a serial outside
+ * the calendar is #NUM!, as is a start after the end, and so is a unit that is not exactly one
+ * of Y M D MD YM YD in either case — nothing is trimmed, and a number or a boolean arrives as
+ * text and is refused the same way. `"MD"` re-anchors the start's day into the end's month
+ * (the documented negative answers are Excel's own: Jan 31 → Mar 1 is −2). `"YD"` is the
+ * `"YM"` months and `"MD"` days walked forward from the start, so it counts on the START year's
+ * calendar — Jan 1 2004 → Mar 1 2005 is 60 where Jan 1 2003 → Mar 1 2004 is 59 (the documented
+ * leap-year quirk), and Feb 29 2004 → Mar 1 2005 is 0.
  */
 export declare function DATEDIF(startDate: number, // Date
 endDate: number, // Date
 unit: string): number;
 /**
- * @summary Returns the year fraction representing the number of whole days between start_date and end_date.
+ * Returns the year fraction representing the number of whole days between start_date and end_date.
  * @param startDate is a serial date number that represents the start date.
  * @param endDate is a serial date number that represents the end date.
  * @param basis is the type of day count basis to use.
  * @category Date & Time
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/YEARFRAC, 2026-08-28). Excel declares all
+ * three arguments `any`: a boolean is #VALUE!, an empty argument is #N/A where a blank cell is
+ * serial 0, and a multi-cell reference does not broadcast while an array constant does. The
+ * basis is read and validated FIRST — truncated, #NUM! below 0 or above 4, so
+ * `YEARFRAC("x",39814,5)` is #NUM! and `YEARFRAC(NA(),39814,"x")` is #VALUE! (the dates
+ * accept an error so that the body, not the marshaller, decides which is seen first) — then
+ * the start, then the end, each coerced and range-checked in turn (`YEARFRAC(-1,"x",0)` is
+ * #NUM!). The day counts are `getYearFrac`'s: serials truncated, dates ordered, basis 0
+ * signed.
  */
-export declare function YEARFRAC(startDate: Scalar, endDate: Scalar, basis?: Scalar): number;
+export declare function YEARFRAC(startDate: NoLift<Omittable<AcceptError<Scalar>>>, endDate: NoLift<Omittable<AcceptError<Scalar>>>, basis?: NoLift<Omittable<Scalar>>): number;
 /**
- * @summary Returns the number of days between two dates based on a 360-day year (twelve 30-day months).
+ * Returns the number of days between two dates based on a 360-day year (twelve 30-day months).
  * @param endDate startDate and endDate are the two dates between which you want to know the number of days.
  * @param startDate startDate and endDate are the two dates between which you want to know the number of days.
  * @param method is a logical value specifying the calculation method: U.S. (NASD) = FALSE; European = TRUE.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/DAYS360, 2026-08-28). Excel declares the
+ * dates `number` and the method `logical`, so the engine's coercion applies: a boolean date is
+ * its serial, a number is a method, `"TRUE"` is one while `"1"` is #VALUE!. A serial outside
+ * the calendar is #NUM! at either slot and the fraction is discarded. The US rules are
+ * `getDays360US`'s, applied to (start, end) as given.
  */
 export declare function DAYS360(startDate: number, // date
 endDate: number, // date

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

@@ -0,0 +1,58 @@
+import { Scalar, Omittable, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the straight-line depreciation of an asset for one period.
+ * @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).
+ */
+export declare function SLN(cost: number, salvage: number, life: number): number;
+/**
+ * Returns the sum-of-years' digits depreciation of an asset for a specified period.
+ * @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).
+ * @param per is the period and must use the same units as Life.
+ */
+export declare function SYD(cost: number, salvage: number, life: number, per: number): number;
+/**
+ * Returns the depreciation of an asset for a specified period using the fixed-declining balance method.
+ * @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).
+ * @param period is the period for which you want to calculate the depreciation. Period must use the same units as Life.
+ * @param month is the number of months in the first year.
+ */
+export declare function DB(cost: number, salvage: number, life: number, period: number, month?: number): number;
+/**
+ * Returns the depreciation of an asset for a specified period 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).
+ * @param period is the period for which you want to calculate the depreciation. Period must use the same units as Life.
+ * @param factor is the rate at which the balance declines.
+ *
+ * @remarks
+ * Double declining balance (DDB) depreciation method.
+ */
+export declare function DDB(cost: number, salvage: number, life: number, period: number, factor?: number): number;
+/**
+ * Returns the prorated linear depreciation of an asset for each accounting period.
+ * @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.
+ * @param salvage is the salvage value at the end of life of the asset.
+ * @param period is the period.
+ * @param rate is the rate of depreciation.
+ * @param basis year basis : 0 for year of 360 days, 1 for actual, 3 for year of 365 days.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/AMORLINC, 2026-08-28). Period 0 is the
+ * stub from purchase to the end of the first period, pro-rated by `getAmorDayCount` (a
+ * zero-day stub is a whole period; a stub longer than a year is not capped) and capped at
+ * `cost − salvage`; every following period is `cost·rate` until the one that takes what is
+ * left, and 0 beyond. A period under 1 is period 1, above it truncates. Basis truncates and 2 is
+ * refused. Every argument is Excel-declared `any`: a boolean is refused, an empty argument is
+ * missing, a multi-cell reference does not broadcast.
+ */
+export declare function AMORLINC(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=Depreciation.d.ts.map

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