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

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

@@ -0,0 +1,205 @@
+import { FormulaError, IFormulaContext, IFunction, IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * One aggregate column: a function applied to one value column.
+ */
+export interface Measure {
+    readonly fn: IFunction;
+    /** The value column it reads. */
+    readonly column: number;
+    /** Called with `(x, y)` rather than `(x)` — see {@link aggregate}. */
+    readonly twoArgs: boolean;
+    /** What the function-name row shows. */
+    readonly label: string;
+}
+/**
+ * The function argument, resolved.
+ */
+export interface Functions {
+    /** One per output column (or, when `vertical`, one per output row of each group). */
+    readonly measures: Measure[];
+    /** The functions were a column (`VSTACK(SUM,COUNT)`): each group gets one row per function. */
+    readonly vertical: boolean;
+    /** More than one function — a row or column names them. */
+    readonly named: boolean;
+}
+/**
+ * Resolves the function argument against the value columns, or answers the whole call's error.
+ *
+ * @remarks
+ * A row of functions is one column per function, a column of them one row per function (a13, a14),
+ * and a 2-D block is refused (a15). Functions pair with value columns one to many, many to one, or
+ * one to one (a37, a38, a42). A function that cannot take one argument, or needs more than two, is
+ * refused up front (a23, a24, a43) — the call shape is decided before any group runs.
+ */
+export declare const resolveFunctions: (fn: any, valueColumns: number) => Functions | FormulaError.Known;
+/**
+ * Applies a measure to a group's members.
+ *
+ * @remarks
+ * `y` is every kept value of the column, and only a function that REQUIRES two arguments gets it
+ * (`PERCENTOF`, `LAMBDA(x,y,…)`; a20–a22). An array result, a 1×1 included, is `#VALUE!` for that
+ * cell (a25, r05, r06); a single-cell reference reads as its value, and an error — returned or
+ * thrown — is just the cell's value.
+ */
+export declare const aggregate: (measure: Measure, x: IRange, y: () => IRange) => Scalar;
+/**
+ * How the first row is read — see {@link resolveHeaders}.
+ */
+export interface Headers {
+    /** The first row is a header, not data. */
+    readonly hasHeader: boolean;
+    /** A header row is output (the data's own, or generated). */
+    readonly show: boolean;
+}
+/**
+ * The `field_headers` argument, resolved; omitted, it is guessed from the values.
+ *
+ * @remarks
+ * 0: data; 1: header, hidden; 2: no header, generate one; 3: header, shown. Anything else is
+ * `#VALUE!` (b10, b11, b16).
+ *
+ * The guess is the one sort uses: a header when the first two rows hold values of different types
+ * in some value column (b01 has `"Sales"` over `10`, b08 has `"Product"` over `"Apple"`). Excel's
+ * own rule is not fully measured yet.
+ */
+export declare const resolveHeaders: (fieldHeaders: number | undefined, values: IRange) => Headers | FormulaError.Known;
+/**
+ * Validates a `total_depth` against the number of key fields.
+ *
+ * @remarks
+ * An integer no deeper than the fields (c04, c16, c20, c21); the sign puts totals first.
+ */
+export declare const isValidDepth: (depth: number, fieldCount: number) => boolean;
+/**
+ * One axis's sort: a direction per key level, or a sort by an aggregate.
+ */
+export interface SortSpec {
+    /** Per key level, 1 ascending or -1 descending. */
+    readonly keyDirections: number[];
+    /** Sort by an aggregate column: the measure's index and its direction. */
+    readonly byValue: {
+        readonly measure: number;
+        readonly direction: number;
+    } | null;
+}
+/**
+ * Parses a `sort_order` argument.
+ *
+ * @param valueColumns How many aggregate columns follow the keys; an index past the keys picks one.
+ *
+ * @remarks
+ * `±k` sorts key level `k`, or, past the keys, an aggregate column (d02, d05). Several indices must
+ * be distinct key levels, no more than there are (d09, d11, r12–r15). Zero, out of range, text, a
+ * fraction and a logical are `#VALUE!` (d07, d08, d16, d17, r24).
+ */
+export declare const resolveSort: (sortOrder: IRange | undefined, fieldCount: number, valueColumns: number) => SortSpec | FormulaError.Known;
+/**
+ * Whether `values` is one blank CELL — refused for the whole call (g16, g19).
+ *
+ * @remarks
+ * The rule `ARRAYTOTEXT` has for a lone blank: a reference to one empty cell is `#VALUE!`, while a
+ * blank KEY (g21), two blank cells (g18) or a blank array member are ordinary values.
+ */
+export declare const isLoneBlankCell: (values: IRange) => boolean;
+/**
+ * Validates a `filter_array` against the record count.
+ *
+ * @remarks
+ * One column as tall as the data, holding logicals and numbers only: an error or text anywhere is
+ * `#VALUE!` for the whole call (f06, f08), as is a shape mismatch (f03, f09, f11).
+ */
+export declare const isValidFilter: (filter: IRange, recordCount: number) => boolean;
+/**
+ * A group at one key level of an axis.
+ */
+export interface AxisNode {
+    /** The key level, 0 for the outermost field. */
+    readonly level: number;
+    /** The group within that level's grouping. */
+    readonly group: number;
+    /** The keys down to this level, as spelled by the group's first record. */
+    readonly keys: readonly Scalar[];
+    /** The group one level up, `null` at the outermost level. */
+    readonly parent: AxisNode | null;
+    readonly children: AxisNode[];
+}
+/**
+ * One output line of an axis: a group at the innermost level, a subtotal, or the grand total.
+ */
+export interface AxisLine {
+    readonly kind: 'group' | 'subtotal' | 'total';
+    /** `null` for the grand total. */
+    readonly node: AxisNode | null;
+}
+/**
+ * One axis of groups — `GROUPBY`'s rows, or either side of `PIVOTBY`.
+ *
+ * @remarks
+ * Each key level has its own grouping, over the key columns down to it, so a subtotal's members are
+ * one group of that grouping rather than a union of its children's. A level's parent is read
+ * through its first record (`getFirstRecord`/`getGroup`).
+ */
+export declare class PivotAxis {
+    readonly fieldCount: number;
+    /** Per key level, the grouping over the key columns down to it. */
+    readonly groupings: IFormulaContext.Grouping[];
+    /** Per key level, the key columns down to it. */
+    readonly prefixes: IRange[];
+    readonly roots: AxisNode[];
+    constructor(keys: IRange, filter: IRange | undefined);
+    /** The number of records kept. */
+    getRecordCount(): number;
+    /** A node's members of one value column. */
+    getMembers(values: IRange, node: AxisNode | null): IRange;
+    /**
+     * Orders the groups at every level.
+     *
+     * @param valueOf A node's aggregate, for a sort by value.
+     * @param table Field relationship 1: one flat order over the innermost groups (d18).
+     *
+     * @remarks
+     * Keys sort by the comparison operators' order — numbers, text, `FALSE`, `TRUE`, errors — with
+     * a blank key last in either direction (e01, e02). A sort by value orders each level by its own
+     * aggregate, parents by their subtotal (d05); ties keep key order (e06), and an error aggregate
+     * sorts last.
+     */
+    sort(spec: SortSpec, valueOf: (node: AxisNode) => Scalar, table: boolean): AxisNode[];
+    /**
+     * The output lines in order, with subtotals and the grand total placed per `depth`.
+     *
+     * @remarks
+     * `|depth|` 1 is the grand total alone; each step deeper adds subtotals for one more level from
+     * the top (c03, c13, c14). A negative depth puts every total before what it totals (c06, c15).
+     */
+    lines(roots: AxisNode[], depth: number): AxisLine[];
+    /**
+     * The key cells of a line: its keys, `""` past its level, and the total's label.
+     *
+     * @remarks
+     * A blank key shows as `0`, as Excel spills it (a01); padding is `""` (b09, c03). The grand total
+     * is `Grand Total` once subtotals show, `Total` otherwise (c02, c03).
+     */
+    keyCells(line: AxisLine, depth: number): Scalar[];
+}
+/**
+ * The generated header of key field `index` (0-based), for `field_headers` 2 (b04).
+ */
+export declare const generatedFieldLabel: (index: number) => string;
+/**
+ * The generated header of `PIVOTBY` column field `index` (0-based), for `field_headers` 2 (p43).
+ */
+export declare const generatedColumnFieldLabel: (index: number) => string;
+/**
+ * The generated header of value column `index` (0-based), for `field_headers` 2 (b04).
+ */
+export declare const generatedValueLabel: (index: number) => string;
+/**
+ * The columns of a range, one slice each — the same object every time it is asked for, which is
+ * what lets a grouping reuse its work on a value column.
+ */
+export declare const columnsOf: (range: IRange) => IRange[];
+/**
+ * A range without its first row — the data under a header.
+ */
+export declare const withoutFirstRow: (range: IRange) => IRange;
+//# sourceMappingURL=Pivot.d.ts.map

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

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

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

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

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

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

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

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

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