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

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

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