@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/functions/financial.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Financial Functions — Native RuntimeValue implementation.
+ */
+import type { RuntimeValue } from "../runtime/values.js";
+type NativeFn = (args: RuntimeValue[]) => RuntimeValue;
+export declare const fnPMT: NativeFn;
+export declare const fnFV: NativeFn;
+export declare const fnPV: NativeFn;
+export declare const fnNPV: NativeFn;
+export declare const fnIRR: NativeFn;
+export declare const fnNPER: NativeFn;
+export declare const fnRATE: NativeFn;
+export declare const fnSLN: NativeFn;
+/**
+ * SYD — Sum-of-years'-digits depreciation.
+ *
+ *   SYD(cost, salvage, life, per)
+ *
+ * The depreciation assigned to period `per` by the sum-of-years'-digits
+ * method: `(cost - salvage) * (life - per + 1) * 2 / (life * (life + 1))`.
+ * Excel rejects `life = 0` and period outside [1, life] with #NUM!.
+ */
+export declare const fnSYD: NativeFn;
+/**
+ * VDB — Variable Declining Balance depreciation.
+ *
+ *   VDB(cost, salvage, life, start_period, end_period, [factor], [no_switch])
+ *
+ * Applies declining-balance depreciation (with a default factor of 2
+ * for double-declining) between two fractional periods. By default
+ * (`no_switch = FALSE`) the method silently switches to straight-line
+ * when that yields a larger deduction, matching Excel's documented
+ * behaviour. `no_switch = TRUE` forces declining-balance for all
+ * periods.
+ */
+export declare const fnVDB: NativeFn;
+export declare const fnDB: NativeFn;
+export declare const fnDDB: NativeFn;
+export declare const fnIPMT: NativeFn;
+export declare const fnPPMT: NativeFn;
+/**
+ * FVSCHEDULE — future value with a schedule of varying rates.
+ *
+ *   FVSCHEDULE(principal, schedule)
+ *
+ * Compounds `principal` through each rate in `schedule`:
+ *   FV = principal · ∏(1 + rᵢ)
+ *
+ * Excel treats blanks in the schedule as zero (no-op compounding) and
+ * propagates any error it encounters. Text values produce #VALUE!.
+ */
+export declare const fnFVSCHEDULE: NativeFn;
+/**
+ * PDURATION — number of periods required for an investment to reach a
+ * specified value.
+ *
+ *   PDURATION(rate, pv, fv) = (log fv − log pv) / log(1 + rate)
+ *
+ * Excel requires `rate > 0` and `pv, fv > 0`.
+ */
+export declare const fnPDURATION: NativeFn;
+/**
+ * RRI — equivalent interest rate for the growth of an investment.
+ *
+ *   RRI(nper, pv, fv) = (fv / pv)^(1/nper) − 1
+ *
+ * Excel requires `nper > 0`, `pv > 0`, `fv >= 0`.
+ */
+export declare const fnRRI: NativeFn;
+export declare const fnEFFECT: NativeFn;
+export declare const fnNOMINAL: NativeFn;
+export declare const fnXNPV: NativeFn;
+export declare const fnXIRR: NativeFn;
+export declare const fnMIRR: NativeFn;
+export declare const fnISPMT: NativeFn;
+export declare const fnCUMPRINC: NativeFn;
+export declare const fnCUMIPMT: NativeFn;
+export declare const fnDOLLARDE: NativeFn;
+export declare const fnDOLLARFR: NativeFn;
+export declare const fnDISC: NativeFn;
+export declare const fnPRICEDISC: NativeFn;
+export declare const fnYIELDDISC: NativeFn;
+export declare const fnRECEIVED: NativeFn;
+export declare const fnINTRATE: NativeFn;
+/**
+ * PRICE(settlement, maturity, rate, yield, redemption, frequency, [basis])
+ *
+ * Price per $100 face value of a security that pays periodic interest.
+ * Excel formula (standard case, more than one coupon period remaining):
+ *
+ *   P = [redemption / (1 + y/f)^(N - 1 + DSC/E)]
+ *     + Σ_{k=1..N} [100 * r / f / (1 + y/f)^(k - 1 + DSC/E)]
+ *     - 100 * r / f * A/E
+ *
+ * Where:
+ *   f  = frequency
+ *   N  = number of coupons from settlement to maturity
+ *   DSC = days from settlement to next coupon
+ *   E   = days in coupon period containing settlement
+ *   A   = days from beginning of coupon period to settlement
+ */
+export declare const fnPRICE: NativeFn;
+/**
+ * YIELD(settlement, maturity, rate, pr, redemption, frequency, [basis])
+ *
+ * Inverse of PRICE: solve numerically for yield such that PRICE(...y) = pr.
+ * Uses bracketed bisection in [0, 1] (100% yield upper bound covers all
+ * realistic bond scenarios) followed by a light Newton polish.
+ */
+export declare const fnYIELD: NativeFn;
+/**
+ * DURATION(settlement, maturity, coupon, yield, frequency, [basis])
+ *
+ * Macaulay duration of a bond: the weighted average time to cash flows,
+ * weighted by present value. Expressed in years.
+ */
+export declare const fnDURATION: NativeFn;
+/**
+ * MDURATION — modified duration = DURATION / (1 + yield/frequency).
+ */
+export declare const fnMDURATION: NativeFn;
+/**
+ * ACCRINT(issue, first_interest, settlement, rate, par, frequency, [basis], [calc_method])
+ *
+ * Accrued interest for a security that pays periodic interest.
+ * The simplified implementation (calc_method TRUE, the default) treats
+ * accrued interest from issue to settlement as par * rate * dcf(issue, settlement, basis).
+ */
+export declare const fnACCRINT: NativeFn;
+/**
+ * ACCRINTM(issue, settlement, rate, par, [basis]) — accrued interest
+ * for a security that pays interest at maturity.
+ *   result = par × rate × dayCountFraction(issue, settlement, basis)
+ */
+export declare const fnACCRINTM: NativeFn;
+/**
+ * TBILLPRICE(settlement, maturity, discount) — price per $100 face value.
+ *   price = 100 × (1 - discount × DSM / 360)
+ * where DSM is days from settlement to maturity.
+ */
+export declare const fnTBILLPRICE: NativeFn;
+/**
+ * TBILLYIELD(settlement, maturity, pr) — bond-equivalent yield.
+ *   yield = (100 - pr) / pr × (360 / DSM)
+ */
+export declare const fnTBILLYIELD: NativeFn;
+/**
+ * TBILLEQ(settlement, maturity, discount) — bond equivalent yield.
+ *   TBILLEQ = (365 × discount) / (360 - discount × DSM)
+ */
+export declare const fnTBILLEQ: NativeFn;
+/**
+ * PRICEMAT(settlement, maturity, issue, rate, yld, [basis]) —
+ * price per $100 face value for a security that pays interest at maturity.
+ *
+ *   A = DCF(issue, settlement, basis)
+ *   DSM = DCF(settlement, maturity, basis)
+ *   DIM = DCF(issue, maturity, basis)
+ *   price = (100 + DIM × rate × 100) / (1 + DSM × yld) - A × rate × 100
+ */
+export declare const fnPRICEMAT: NativeFn;
+/**
+ * YIELDMAT(settlement, maturity, issue, rate, pr, [basis]) —
+ * annual yield for a security that pays interest at maturity.
+ *
+ *   A = DCF(issue, settlement, basis)
+ *   DSM = DCF(settlement, maturity, basis)
+ *   DIM = DCF(issue, maturity, basis)
+ *   yield = ((1 + DIM × rate) / (pr/100 + A × rate) - 1) / DSM
+ */
+export declare const fnYIELDMAT: NativeFn;
+/**
+ * COUPNCD(settlement, maturity, frequency, [basis]) — next coupon date
+ * after settlement, as an Excel serial.
+ */
+export declare const fnCOUPNCD: NativeFn;
+/**
+ * COUPPCD(settlement, maturity, frequency, [basis]) — previous coupon
+ * date on or before settlement, as an Excel serial.
+ */
+export declare const fnCOUPPCD: NativeFn;
+/**
+ * COUPNUM(settlement, maturity, frequency, [basis]) — number of
+ * coupons payable between settlement and maturity, rounded up.
+ */
+export declare const fnCOUPNUM: NativeFn;
+/**
+ * COUPDAYSNC(settlement, maturity, frequency, [basis]) — days from
+ * settlement to the next coupon date.
+ */
+export declare const fnCOUPDAYSNC: NativeFn;
+/**
+ * COUPDAYBS(settlement, maturity, frequency, [basis]) — days from the
+ * beginning of the coupon period to settlement.
+ */
+export declare const fnCOUPDAYBS: NativeFn;
+/**
+ * COUPDAYS(settlement, maturity, frequency, [basis]) — days in the
+ * coupon period that contains settlement.
+ */
+export declare const fnCOUPDAYS: NativeFn;
+export {};