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

package/node/esm/r21pRf-kqnnAD611.mjs

@@ -0,0 +1,32 @@
+/**
+* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.2
+*
+* (C) 2026-present SheetXL Inc. & Michael T. Ford
+* License: The license can be found at https://www.sheetxl.com/license.
+*/
+var e = {
+	FVSCHEDULE: {
+		s: "Returns the future value of an initial principal after applying a series of compound interest rates.",
+		p: {
+			principal: { d: "is the present value." },
+			schedule: { d: "is an array of interest rates to apply." }
+		}
+	},
+	RRI: {
+		s: "Returns an equivalent interest rate for the growth of an investment.",
+		p: {
+			nper: { d: "is the total number of payment periods." },
+			pv: { d: "is the present value of the investment." },
+			fv: { d: "is the future value of the investment." }
+		}
+	},
+	PDURATION: {
+		s: "Returns the number of periods required by an investment to reach a specified value.",
+		p: {
+			rate: { d: "is the interest rate." },
+			pv: { d: "is the present value of the investment." },
+			fv: { d: "is the desired future value of the investment." }
+		}
+	}
+};
+export { e as default };

package/node/esm/{LAkTk93odAfpvx50.mjs → sXWR_bAqmw8b4bT6.mjs}

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.1
+* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.2
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.

package/{browser/esm/BRwwvGaJ6HvkxjFC.mjs → node/esm/v2vXc6oQz1MG0L1T.mjs}

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.1
+* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.2
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.

package/{browser/esm/Bma3CN4_Nec6_4n7.mjs → node/esm/vMGzN0Xt0WnzZiH5.mjs}

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.1
+* @license @sheetxl/formulas-extended - Formulas Enterprise - TypeScript formulas compatible with Excel built-ins. - v0.8.0-beta.2
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -17,10 +17,10 @@ var e = {
 	COUPDAYS: {
 		s: "Returns the number of days in the coupon period containing the settlement date.",
 		p: {
-			settlement: { d: "Settlement date number number." },
-			maturity: { d: "Maturity date number number." },
-			frequency: { d: "Coupons per year: 1, 2, or 4." },
-			basis: { d: "Day-count basis (0–4). Default 0." }
+			settlement: { d: "is the security's settlement date, expressed as a serial date number." },
+			maturity: { d: "is the security's maturity date, expressed as a serial date number." },
+			frequency: { d: "is the number of coupon payments per year." },
+			basis: { d: "is the type of day count basis to use." }
 		}
 	},
 	COUPDAYSNC: {
@@ -33,7 +33,7 @@ var e = {
 		}
 	},
 	COUPNCD: {
-		s: "Returns the number of days from the beginning of the coupon period to the settlement date.",
+		s: "Returns the next coupon date after the settlement date.",
 		p: {
 			settlement: { d: "is the security's settlement date, expressed as a serial date number." },
 			maturity: { d: "is the security's maturity date, expressed as a serial date number." },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/formulas-extended",
   "description": "Formulas Enterprise - TypeScript formulas compatible with Excel built-ins.",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.2",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -37,7 +37,7 @@
     "formulas"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.1",
-    "@sheetxl/scripting": "^0.8.0-beta.1"
+    "@sheetxl/primitives": "^0.8.0-beta.2",
+    "@sheetxl/scripting": "^0.8.0-beta.2"
   }
 }

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

@@ -0,0 +1,5 @@
+import { MinifiedDeclarations, MinifiedEnums } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export declare const enums: MinifiedEnums;
+export default declarations;
+//# sourceMappingURL=Annuity.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial.decl.d.ts → Cashflow.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial.decl.d.ts.map
+//# sourceMappingURL=Cashflow.decl.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Convert.decl.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Coupon.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial2.decl.d.ts → Depreciation.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial2.decl.d.ts.map
+//# sourceMappingURL=Depreciation.decl.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Growth.decl.d.ts.map

package/types/src/.generated/decl/financial/{ODD.decl.d.ts → Odd.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=ODD.decl.d.ts.map
+//# sourceMappingURL=Odd.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial3.decl.d.ts → STOCKHISTORY.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial3.decl.d.ts.map
+//# sourceMappingURL=STOCKHISTORY.decl.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Security.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial4.decl.d.ts → SecurityMaturity.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial4.decl.d.ts.map
+//# sourceMappingURL=SecurityMaturity.decl.d.ts.map

package/types/src/.generated/decl/{statistical/TTEST.decl.d.ts → financial/TBill.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=TTEST.decl.d.ts.map
+//# sourceMappingURL=TBill.decl.d.ts.map

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

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=ETS.decl.d.ts.map
+//# sourceMappingURL=Ets.decl.d.ts.map

package/types/src/.generated/decl/statistical/TTest.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=TTest.decl.d.ts.map

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

@@ -0,0 +1,5 @@
+import { MinifiedDescriptors, MinifiedEnumDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export declare const enums: MinifiedEnumDescriptors;
+export default descriptors;
+//# sourceMappingURL=Annuity.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial.desc.d.ts → Cashflow.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial.desc.d.ts.map
+//# sourceMappingURL=Cashflow.desc.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Convert.desc.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Coupon.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial2.desc.d.ts → Depreciation.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial2.desc.d.ts.map
+//# sourceMappingURL=Depreciation.desc.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Growth.desc.d.ts.map

package/types/src/.generated/desc/financial/{ODD.desc.d.ts → Odd.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=ODD.desc.d.ts.map
+//# sourceMappingURL=Odd.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial3.desc.d.ts → STOCKHISTORY.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial3.desc.d.ts.map
+//# sourceMappingURL=STOCKHISTORY.desc.d.ts.map

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

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Security.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial4.desc.d.ts → SecurityMaturity.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial4.desc.d.ts.map
+//# sourceMappingURL=SecurityMaturity.desc.d.ts.map

package/types/src/.generated/desc/{statistical/TTEST.desc.d.ts → financial/TBill.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=TTEST.desc.d.ts.map
+//# sourceMappingURL=TBill.desc.d.ts.map

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

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=ETS.desc.d.ts.map
+//# sourceMappingURL=Ets.desc.d.ts.map

package/types/src/.generated/desc/statistical/TTest.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=TTest.desc.d.ts.map

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

@@ -1,4 +1,4 @@
-import { Scalar } from '@sheetxl/primitives';
+import { Scalar, Omittable } from '@sheetxl/primitives';
 /**
  * Readers for arguments Excel declares `any` rather than `number`.
  *
@@ -23,10 +23,17 @@ import { Scalar } from '@sheetxl/primitives';
  * `parseAsSerialDate` supplies the refusal — `#VALUE!` for a boolean, whether it arrived as a
  * literal or as a cell, and an incoming error rethrown with its own identity.
  *
- * A blank CELL is serial 0. Excel answers `#N/A` for a genuinely empty SLOT (`EOMONTH(,0)`),
- * which we cannot yet distinguish — both reach the body as `null` (CALC-ISSUES item 43).
+ * A blank CELL is serial 0. A genuinely empty SLOT is `#N/A` in Excel (`EOMONTH(,0)`,
+ * `YEARFRAC(,39814)` — fn-battery financial/YEARFRAC, 2026-08-28); a parameter declared
+ * `Omittable<Scalar>` sees that slot as `undefined` and reads it through {@link anyDateRequired}.
  */
 export declare function anyDate(value: Scalar): number;
+/**
+ * A REQUIRED date parameter Excel declares `any` (`Omittable<Scalar>` on the declaration): an
+ * argument supplied EMPTY is a missing argument (#N/A); everything else reads through
+ * {@link anyDate}, so a blank CELL is still serial 0.
+ */
+export declare function anyDateRequired(value: Omittable<Scalar>): number;
 /**
  * Reads a plain NUMERIC argument declared `any` — the `months`/`basis` slots.
  *
@@ -35,4 +42,11 @@ export declare function anyDate(value: Scalar): number;
  * text parsed, boolean refused, error identity preserved.
  */
 export declare function anyNumber(value: Scalar): number;
+/**
+ * A REQUIRED parameter Excel declares `any` (`Omittable<Scalar>` on the declaration): an argument
+ * supplied EMPTY is a missing argument (#N/A) rather than a zero, and everything else reads
+ * through `anyNumber`. The `undefined` check must come first — `anyNumber` reads a blank cell's
+ * `null` as 0, which is what a blank CELL is measured to be.
+ */
+export declare function anyRequired(value: Omittable<Scalar>): number;
 //# sourceMappingURL=AnyArgs.d.ts.map

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

@@ -1,4 +1,34 @@
 type IterFn = (x: number) => number;
+/**
+ * The approximate yield a bond-yield iteration starts from: the annual coupon plus the pull to par
+ * spread over `years`, against a denominator that is the mid-point of par and the price less a
+ * `years`-scaled share of the same pull. At par it returns the coupon rate exactly, which is why
+ * a bond priced at 100 answers in one step.
+ *
+ * `years` is {@link getYearsToMaturity}, never the coupon count over the frequency. Measured on
+ * 1,154 rows of fn-battery financial/adhoc-yield-start, -n, -n2 and -n3 — bonds whose redemption
+ * dwarfs the price, where a hundred Newton steps carry the start out to a number that inverts.
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function approximateYield(rate: number, pr: number, years: number): number;
+/**
+ * Excel's bond-yield iteration: Newton on the price with its ANALYTIC slope, at most a hundred
+ * steps from {@link approximateYield}, stopping the first time a step moves the yield by less than
+ * `1e-5` and answering the iterate the step just produced — so the answer is a PARTIALLY converged
+ * one, ~1e-10 from the root on an ordinary bond, and on a bond that cannot converge it is simply
+ * where the walk stood after a hundred steps.
+ *
+ * A slope that overflows to infinity, or a step that lands where the price cannot be evaluated
+ * (a `1 + y/f` at or below zero), is `NaN` — the caller's #NUM!.
+ *
+ * Measured on YIELD's 1,134-row battery and fn-battery financial/adhoc-yield-fingerprint,
+ * -start, -n, -n2, -n3, -domain (2026-09-09).
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function solveYieldByNewton(start: number, priceFn: IterFn, slopeFn: IterFn): number;
+export {};
 /**
  * Solve `iterFn(x) = 0` numerically, starting from `guess`.
  *
@@ -14,6 +44,13 @@ type IterFn = (x: number) => number;
  *
  * Used by: YIELD, ODDFYIELD, ODDLYIELD.
  */
-export declare function solveByNewton(guess: number, iterFn: IterFn): number;
-export {};
+/**
+ * Bisection fallback when Newton-Raphson fails to converge.
+ *
+ * Phase 1: Expand a small bracket around guess until the function changes sign
+ *   (guarantees a root is bracketed, or gives up with NaN).
+ * Phase 2: Standard bisection to isolate the root.
+ *
+ * Returns NaN if no bracket is found within the iteration budget.
+ */
 //# sourceMappingURL=FinanaceSolver.d.ts.map

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

@@ -0,0 +1,23 @@
+import { Scalar, Omittable } from '@sheetxl/primitives';
+/** The arguments of AMORLINC/AMORDEGRC once read and validated. */
+export interface AmorArgs {
+    cost: number;
+    salvage: number;
+    /** The period as Excel indexes it: under 1 is period 1, above 1 truncates. */
+    periodIndex: number;
+    rate: number;
+    /** The stub period's day count (`getAmorDayCount`); its year fraction is `days / yearDays`. */
+    days: number;
+    yearDays: number;
+}
+/**
+ * The seven arguments of AMORLINC/AMORDEGRC — measured against Excel 16.0 (fn-battery
+ * financial/AMORLINC, /AMORDEGRC, 2026-08-28). Every one is Excel-declared `any`, so they are
+ * read here in declaration order, with the basis read AFTER the dates are validated (a reversed
+ * date pair beats a text basis: `…, DATE(2008,12,31), DATE(2008,8,19), …, "x")` is #NUM!). The
+ * serials truncate; the shared domain is `cost > 0`, `0 ≤ salvage ≤ cost`, `period ≥ 0`,
+ * `rate > 0`, both dates in the calendar and in order, and a truncated basis of 0, 1, 3 or 4.
+ * Returns `null` for #NUM!.
+ */
+export declare function amorArgs(cost: Omittable<Scalar>, datePurchased: Omittable<Scalar>, firstPeriod: Omittable<Scalar>, salvage: Omittable<Scalar>, period: Omittable<Scalar>, rate: Omittable<Scalar>, basis: Omittable<Scalar>): AmorArgs | null;
+//# sourceMappingURL=FinanceAmor.d.ts.map

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

@@ -0,0 +1,42 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The dated cash-flow operands of XNPV and XIRR, read the way Excel reads them (measured against
+ * Excel 16.0, fn-battery financial/XNPV, 2026-08-29).
+ *
+ * @remarks
+ * Both functions take two operands that are read TOGETHER, member by member, by flattened
+ * row-major ordinal — a 3x1 pairs fully with a 1x3 and a 2x2 pairs with a 4x1
+ * (DESIGN-RANGE-PAIRING). That makes the reading order a pair scan rather than a slot order, and
+ * it is one pass that stops at the first fault: a bad ordinal 2 is answered before ordinal 3's
+ * error is looked at.
+ *
+ * Ordinal 0 is not like the rest. Its DATE is read before its value (an error there wins over an
+ * error in the first flow) and range-checked before either, and a member of EITHER operand that
+ * is not a number is `#VALUE!` there where the same member at any later ordinal is `#NUM!` —
+ * so a whole operand of numeric text, or of blanks, answers `#VALUE!` while one number among
+ * them answers `#NUM!`.
+ */
+export interface DatedFlows {
+    /** The flow at each ordinal. */
+    values: number[];
+    /** Days from the first date, every serial truncated first. */
+    days: number[];
+}
+/**
+ * `(values, dates)` as XNPV and XIRR read them. `valuesSlot` is the argument index of the values
+ * operand (the dates operand is the next one), which is what tells a one-cell operand from a list
+ * of one; `dialect` picks between the two functions' member rules.
+ *
+ * The pair scan is common to both: a count mismatch is `#NUM!` before anything else, and then, per
+ * ordinal, an error in the values operand, an error in the dates operand, and only then the kinds
+ * and the date's own domain.
+ *
+ * What differs is what a member may BE. XNPV's list members must already be numbers — a text, a
+ * boolean, an empty string or a blank is `#VALUE!` at ordinal 0 and `#NUM!` after it — and its
+ * serials run `[1, MAX_SERIAL_DATE]` with every date at or after the first. XIRR COERCES its
+ * members instead (numeric text and date text parse, a boolean or a true text is `#VALUE!`
+ * wherever it sits), drops a pair whose VALUE is blank, answers `#NUM!` for a blank DATE beside a
+ * present value, admits serial 0, and does not order the dates at all.
+ */
+export declare function readDatedFlows(values: IRange, dates: IRange, valuesSlot: number, dialect?: 'xnpv' | 'xirr'): DatedFlows;
+//# sourceMappingURL=FinanceCashflow.d.ts.map