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

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

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

@@ -0,0 +1,118 @@
+import { Scalar, Omittable, NoLift, ReportType } from '@sheetxl/primitives';
+/**
+ * When payments are due in each period.
+ *
+ * @remarks
+ * Declared `ReportType`, as every numeric built-in enum is: Excel reads any nonzero value as 1
+ * (`2`, `-1` and `0.5` all mean "beginning", measured), which an enum's gate does not, so the
+ * bodies keep the verdict. CUMIPMT and CUMPRINC declare it as `PaymentType | Scalar`: their bodies
+ * read the raw argument themselves, and answer #NUM! for anything but 0 or 1.
+ */
+declare enum PaymentType {
+    /**
+     * Payments are due at the end of each period.
+     * @name At the end of the period
+     */
+    End = 0,
+    /**
+     * Payments are due at the beginning of each period.
+     * @name At the beginning of the period
+     */
+    Beginning = 1
+}
+/**
+ * Returns the future value of an investment based on periodic, constant payments and a constant interest rate.
+ * @param rate is the interest rate.
+ * @param nper is the total number of payment periods.
+ * @param pmt is the payment made each period; it cannot change over the life of the investment.
+ * @param pv is the present value of the investment.
+ * @param type Indicates when payments are due: at the end of the period = 0, at the beginning of the period = 1.
+ */
+export declare function FV(rate: number, nper: number, pmt: number, pv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Returns the present value of an investment: the total amount that a series of future payments is worth now.
+ * @param rate is the interest rate.
+ * @param nper is the total number of payment periods in an investment.
+ * @param pmt is the payment made each period and cannot change over the life of the investment.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value: payment at the beginning of the period = 1; payment at the end of the period = 0.
+ */
+export declare function PV(rate: number, nper: number, pmt: number, fv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Calculates the payment for a loan based on constant payments and a constant interest rate.
+ * @param rate is the interest rate.
+ * @param nper is the total number of payment periods.
+ * @param pv is the present value of the investment.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value: payment at the beginning of the period = 1; payment at the end of the period = 0.
+ */
+export declare function PMT(rate: number, nper: number, pv: number, fv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Returns the number of periods for an investment based on periodic, constant payments and a constant interest rate.
+ * @param rate is the interest rate per period. For example, use 6%/4 for quarterly payments at 6% APR.
+ * @param pmt is the payment made each period; it cannot change over the life of the investment.
+ * @param pv is the present value, or the lump-sum amount that a series of future payments is worth now.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value: payment at the beginning of the period = 1; payment at the end of the period = 0.
+ */
+export declare function NPER(rate: number, pmt: number, pv: number, fv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Returns the interest rate per period of a loan or an investment. For example, use 6%/4 for quarterly payments at 6% APR.
+ * @param nper is the total number of payment periods.
+ * @param pmt is the payment made each period and cannot change over the life of the loan or investment.
+ * @param pv is the present value: the total amount that a series of future payments is worth now.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value: payment at the beginning of the period = 1; payment at the end of the period = 0.
+ * @param guess is your guess for what the rate will be.
+ */
+export declare function RATE(nper: number, pmt: number, pv: number, fv?: number, type?: ReportType<PaymentType>, guess?: number): number;
+/**
+ * Returns the interest payment for a given period for an investment, based on periodic, constant payments and a constant interest rate.
+ * @param rate is the interest rate.
+ * @param per is the period for which you want to find the interest and must be in the range 1 to Nper.
+ * @param nper is the total number of payment periods.
+ * @param pv is the present value of the investment.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value representing the timing of payment: at the end of the period = 0, at the beginning of the period = 1.
+ */
+export declare function IPMT(rate: number, per: number, nper: number, pv: number, fv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Returns the payment on the principal for a given investment based on periodic, constant payments and a constant payments and a constant interest rate.
+ * @param rate is the interest rate per period.
+ * @param per is the period for which you want to find the principal payment and must be in the range 1 to Nper.
+ * @param nper is the total number of payment periods in the investment.
+ * @param pv is the present value of the investment.
+ * @param fv is the future value, or a cash balance you want to attain after the last payment is made.
+ * @param type is a logical value: payment at the beginning of the period = 1; payment at the end of the period = 0.
+ */
+export declare function PPMT(rate: number, per: number, nper: number, pv: number, fv?: number, type?: ReportType<PaymentType>): number;
+/**
+ * Returns the cumulative interest paid between two periods.
+ * @param rate is the interest rate.
+ * @param nper is the total number of payment periods.
+ * @param pv is the present value of the investment.
+ * @param startPeriod is the first period in the calculation.
+ * @param endPeriod is the last period in the calculation.
+ * @param type is the timing of the payment.
+ */
+export declare function CUMIPMT(rate: NoLift<Omittable<Scalar>>, nper: NoLift<Omittable<Scalar>>, pv: NoLift<Omittable<Scalar>>, startPeriod: NoLift<Omittable<Scalar>>, endPeriod: NoLift<Omittable<Scalar>>, type: NoLift<Omittable<PaymentType | Scalar>>): number;
+/**
+ * Returns the cumulative principal paid on a loan between two periods.
+ * @param rate is the interest rate.
+ * @param nper is the total number of payment periods.
+ * @param pv is the present value of the investment.
+ * @param startPeriod is the first period in the calculation.
+ * @param endPeriod is the last period in the calculation.
+ * @param type is the timing of the payment.
+ */
+export declare function CUMPRINC(rate: NoLift<Omittable<Scalar>>, nper: NoLift<Omittable<Scalar>>, pv: NoLift<Omittable<Scalar>>, startPeriod: NoLift<Omittable<Scalar>>, endPeriod: NoLift<Omittable<Scalar>>, type: NoLift<Omittable<PaymentType | Scalar>>): number;
+/**
+ * Returns the interest paid during a specific period of an investment.
+ * @param rate is the interest rate.
+ * @param per period for which you want to find the interest.
+ * @param nper number of payment periods in an investment.
+ * @param pv lump sum amount that a series of future payments is right now.
+ */
+export declare function ISPMT(rate: number, per: number, nper: number, pv: number): number;
+export {};
+//# sourceMappingURL=Annuity.d.ts.map

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

@@ -0,0 +1,84 @@
+import { Scalar, Omittable, AcceptError, IRange, Flatten, NoLift } from '@sheetxl/primitives';
+/**
+ * Returns the net present value of an investment based on a discount rate and a series of future payments (negative values) and income (positive values).
+ * @param rate is the rate of discount over the length of one period.
+ * @param value are 1 to 254 payments and income, equally spaced in time and occurring at the end of each period.
+ */
+export declare function NPV(rate: number, value: IRange<number>[]): number;
+/**
+ * Returns the internal rate of return for a series of cash flows.
+ * @param values is an array or a reference to cells that contain numbers for which you want to calculate the internal rate of return.
+ * @param guess is a number that you guess is close to the result of IRR.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/IRR plus `adhoc-irr-iterates` and
+ * `adhoc-irr-guess`, 2026-08-29). The member rule is NPV's — a text, boolean, blank or
+ * empty-string member is SKIPPED and the periods close up behind it, so `{-100,TRUE,110}` is the
+ * two-flow 10% — while an error member is `#VALUE!` whatever its own identity was. An error handed
+ * as the whole argument is not a member and keeps its identity (`IRR(NA())` is `#N/A`). `guess` is
+ * declared `number` (a boolean coerces, a text is `#VALUE!`), an ABSENT argument is 0.1 where an
+ * EMPTY slot and a blank cell are 0, and the domain is the one RATE has at both ends:
+ * `guess <= -1` is `#VALUE!`, and so is a guess so large that `1 + guess` is `guess` again
+ * (the turn is at 2^53 — `IRR(…,9.007E15)` answers and `IRR(…,9.008E15)` does not).
+ */
+export declare function IRR(values: Omittable<Flatten<AcceptError<Scalar>>>, guess?: number): number;
+/**
+ * Returns the modified internal rate of return for a series of periodic cash flows.
+ * @param values An array of cash flows; must contain at least one positive and one negative value.
+ * @param financeRate The interest rate paid on negative cash flows (cost of capital).
+ * @param reinvestRate The interest rate received on positive cash flows (reinvestment rate).
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/MIRR, 2026-08-29). The member rule is IRR's —
+ * a text, boolean, blank or empty-string member is SKIPPED and the periods close up, so it also
+ * shortens the `n` the exponent counts — but an error member keeps its own identity here where
+ * IRR flattens every one to `#VALUE!`. The two rates are declared `number` (a boolean coerces, an
+ * empty slot and a blank cell are 0) and are read before the members, so a text rate beats an
+ * `#N/A` in the schedule.
+ *
+ * The form is the documented one, and each side DIVIDES by its own compounding — which is where
+ * `#DIV/0!` comes from at a rate of −1 (a flow at period 0 divides by `(1+r)^0` and survives one:
+ * `MIRR({-100,110},-1,0)` is 10% while `MIRR({-100,110},0,-1)` is not). Fewer than two flows, or
+ * no outflow at all, divides by zero as well.
+ */
+export declare function MIRR(values: Omittable<Flatten<AcceptError<Scalar>>>, financeRate: number, reinvestRate: number): number;
+/**
+ * Returns the net present value for a schedule of cash flows.
+ * @param rate is the discount rate to apply to the cash flows.
+ * @param values is a series of cash flows that correspond to a schedule of payments in dates.
+ * @param dates is a schedule of payment dates that corresponds to the cash flow payments.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/XNPV, 2026-08-29). Each flow is discounted
+ * over ACTUAL days from the FIRST date on a 365-day year — `(trunc(dᵢ) − trunc(d₀))/365`, each
+ * serial truncated on its own, so a fractional date changes nothing. The dates need not be
+ * sorted; they need only fall at or after `d₀`, and a date before it is #NUM!. The rate is
+ * strictly positive (0 and below are #NUM!, 1E-300 is an answer), and a discount factor or a
+ * sum that overflows is #NUM!. The operands read as {@link readDatedFlows} describes.
+ */
+export declare function XNPV(rate: NoLift<Omittable<Scalar>>, values: Omittable<IRange>, dates: Omittable<IRange>): number;
+/**
+ * Returns the internal rate of return for a schedule of cash flows.
+ * @param values is a series of cash flows that correspond to a schedule of payments in dates.
+ * @param dates is a schedule of payment dates that corresponds to the cash flow payments.
+ * @param guess is a number that you guess is close to the result of XIRR.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (fn-battery financial/XIRR, 2026-08-29). XIRR is XNPV's equation
+ * solved for the rate — the same `(trunc(dᵢ) − trunc(d₀))/365` day count — but neither its
+ * operands nor its answer are XNPV's. The members are COERCED rather than refused (numeric text
+ * and date text parse; a boolean or a true text is `#VALUE!`), a pair whose VALUE is blank is
+ * DROPPED, serial 0 is legal, and the dates need not be ordered at all: a flow before `d₀` is
+ * discounted by a negative exponent. Fewer than two surviving pairs is `#N/A`; two of the same
+ * sign is `#NUM!`. `guess` is ATP `any` — a boolean is `#VALUE!`, an EMPTY slot is the 0.1
+ * default where a blank cell is 0, and a reference does not lift.
+ *
+ * Excel's own answer is only accurate to about eight digits and moves with the guess in the
+ * ninth, so the fixture's numeric rows carry a `precision` (CALC-ISSUES 26): its
+ * iteration is unidentified, as YIELD's and ODDFYIELD's are. What IS reproduced is the search's
+ * one directional rule — from a NEGATIVE guess Excel never reaches a positive root
+ * (`XIRR({-100,110},…,-0.5)` is `#NUM!` while the same call at guess 0 answers 10%), though a
+ * non-negative guess reaches a negative root freely.
+ */
+export declare function XIRR(values: Omittable<IRange>, dates: Omittable<IRange>, guess?: NoLift<Omittable<Scalar>>): number;
+//# sourceMappingURL=Cashflow.d.ts.map

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