Cash-Flow Timelines and Net Present Value
Install and import#
npm install fintech-algorithmsimport { cashFlowTimelinesAndNetPresentValue } from "fintech-algorithms/foundations/financial-arithmetic-time-value-and-returns/cashflow-npv";Signature#
cashFlowTimelinesAndNetPresentValue(input)Discounts a dated series of cash flows back to today at a single rate and sums them into a net present value.
Parameters#
| Name | Type | Notes |
|---|---|---|
input | D00Input | A plain object. Every F02 topic first reads principal, rate and periods and validates them before any per-topic branch runs. This topic then reads cashFlows, a non-empty array of finite numbers whose position in the array is the period the flow lands in, counted from 0. principal and periods are validated but not used. |
Returns#
{ npv: number; presentValues: number[] }
presentValues holds each flow divided by (1 + rate) raised to its zero-based position, so the first flow is undiscounted. npv is their sum.
Errors#
- When input is not a plain object — throws TypeError
- When principal is negative, periods is negative, or rate is at or below -1 — throws RangeError
- When cashFlows is missing, empty, not an array, or contains a non-finite number — throws RangeError
Complexity: time O(n),
space O(n).
Worked example#
verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.
Input#
{
"principal": 1000,
"rate": 0.05,
"periods": 3,
"compoundsPerPeriod": 12,
"futureValue": 1200,
"cashFlows": [-1000, 400, 400, 400],
"startValue": 100,
"endValue": 110,
"returns": [0.1, -0.05, 0.08],
"frequency": 12,
"periodicReturn": 0.01
}Call#
cashFlowTimelinesAndNetPresentValue(input)Returns#
object with 2 fields: npv, presentValues
{
"npv": 89.29921174819128,
"presentValues": [-1000, 380.95238095238096, 362.81179138321994, 345.5350394125904]
}Diagrams#
Calculation flow#
Cash-Flow Timelines and Net Present Value — four-part map
flowchart LR
A["Name the input"] --> B["Apply: NPV = CF0 + CF1/(1+r)^1 + CF2/(1+r)^2 + ..."]
B --> C["Check units and boundary"]
C --> D["Explain the output"]
How it works#
This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.
References#
- CFA_TVM - Time Value of Money in Finance — CFA Institute
- CFA_QM - CFA Institute Quantitative Methods Study Session — CFA Institute
- Author-derived and synthetic boundary