@aman050807/cashflow-lens 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +29 -0
- package/LICENSE +21 -0
- package/README.md +186 -2
- package/package.json +43 -4
- package/src/index.d.ts +213 -0
- package/src/index.js +144 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Changes follow semantic versioning. Dates are actual release dates.
|
|
4
|
+
|
|
5
|
+
## 0.2.0 - 2026-11-19
|
|
6
|
+
|
|
7
|
+
Backward-compatible additions; all calculations are unchanged.
|
|
8
|
+
|
|
9
|
+
- `formatMoney` and `formatRate` display helpers built on `Intl.NumberFormat`,
|
|
10
|
+
including Indian locale grouping (`en-IN`). Display only: calculations stay
|
|
11
|
+
unrounded IEEE-754 numbers.
|
|
12
|
+
- Marked the package as side-effect free (`"sideEffects": false`) so bundlers
|
|
13
|
+
can drop unimported functions.
|
|
14
|
+
- Expanded editor hover documentation: full JSDoc with examples in the
|
|
15
|
+
TypeScript declarations.
|
|
16
|
+
- CI, npm version, bundle size and license badges in the README.
|
|
17
|
+
- Browser playground added to the companion demo repository.
|
|
18
|
+
|
|
19
|
+
## 0.1.0 - 2026-11-16
|
|
20
|
+
|
|
21
|
+
Initial development release.
|
|
22
|
+
|
|
23
|
+
- Cash yield, cumulative total return and capital-only CAGR functions.
|
|
24
|
+
- Constant-income scenario projection with compound asset growth and exit fees.
|
|
25
|
+
- Stable, non-mutating scenario ranking with unique identifiers.
|
|
26
|
+
- Runtime validation, TypeScript declarations and CommonJS/ESM support.
|
|
27
|
+
- Unit tests and Node.js 20/22/24 CI workflow.
|
|
28
|
+
|
|
29
|
+
The model is educational. It does not calculate IRR, taxes, debt or investment risk.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 V M Aman Sharma
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,187 @@
|
|
|
1
|
-
#
|
|
1
|
+
# cashflow-lens
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/aman050807/cashflow-lens/actions/workflows/test.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/@aman050807/cashflow-lens)
|
|
5
|
+
[](https://bundlephobia.com/package/@aman050807/cashflow-lens)
|
|
6
|
+
[](https://github.com/aman050807/cashflow-lens/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Compare cashflow scenarios without mixing rental income with capital growth.
|
|
9
|
+
A dependency-free JavaScript/Node.js library with CommonJS, ESM named imports,
|
|
10
|
+
TypeScript declarations and strict runtime validation.
|
|
11
|
+
|
|
12
|
+
Useful for comparison tables, educational investment calculators and scenario
|
|
13
|
+
analysis. All examples are fictional, not investment advice or expected returns.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install @aman050807/cashflow-lens
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires Node.js 20+. No runtime dependencies, network calls, build step or side effects.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
const { projectScenario } = require('@aman050807/cashflow-lens');
|
|
27
|
+
// ESM: import { projectScenario } from '@aman050807/cashflow-lens';
|
|
28
|
+
|
|
29
|
+
const result = projectScenario({
|
|
30
|
+
initialInvestment: 10000,
|
|
31
|
+
annualIncome: 800,
|
|
32
|
+
annualExpenses: 200,
|
|
33
|
+
annualGrowthRate: 0.05, // 5%, not 5
|
|
34
|
+
years: 2,
|
|
35
|
+
exitFeeRate: 0.02 // 2% of ending asset value
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
console.log(result.netProfit); // 2004.5
|
|
39
|
+
console.log(result.cashYieldRate); // 0.06 = 6%
|
|
40
|
+
console.log(result.totalReturnRate); // 0.20045 = 20.045% over two years
|
|
41
|
+
console.log(result.capitalCagrRate); // about 0.039447 = 3.9447% per year
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Compare scenarios
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
const { compareScenarios } = require('@aman050807/cashflow-lens');
|
|
48
|
+
|
|
49
|
+
const ranked = compareScenarios([
|
|
50
|
+
{ id: 'income-first', initialInvestment: 10000, annualIncome: 800, years: 3 },
|
|
51
|
+
{ id: 'growth-first', initialInvestment: 10000, annualIncome: 400,
|
|
52
|
+
annualGrowthRate: 0.05, years: 3 }
|
|
53
|
+
]);
|
|
54
|
+
|
|
55
|
+
console.log(ranked.map(row => row.id)); // ['growth-first', 'income-first']
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Results are sorted by **total return rate**, highest first. Equal rates retain
|
|
59
|
+
input order. No input array or object is changed. Empty input returns `[]`.
|
|
60
|
+
Each scenario needs a unique non-empty string `id`; results contain that `id`
|
|
61
|
+
and the projection fields below, not arbitrary input metadata.
|
|
62
|
+
|
|
63
|
+
**Only compare like-for-like horizons and currency assumptions.** A higher total
|
|
64
|
+
return over ten years is not automatically better than a smaller return over one.
|
|
65
|
+
This function ranks one metric, not risk, liquidity, suitability or investment quality.
|
|
66
|
+
|
|
67
|
+
## API
|
|
68
|
+
|
|
69
|
+
All money arguments must use the same currency/unit. Rates are decimal fractions:
|
|
70
|
+
`0.08` means 8%. Results are unrounded JavaScript numbers. Round for display only.
|
|
71
|
+
|
|
72
|
+
### `cashYield(initialInvestment, annualIncome, annualExpenses = 0)`
|
|
73
|
+
|
|
74
|
+
Returns `(annualIncome - annualExpenses) / initialInvestment`.
|
|
75
|
+
Income and expenses must be non-negative; a net loss is allowed.
|
|
76
|
+
|
|
77
|
+
### `totalReturn(initialInvestment, terminalProceeds, accumulatedIncome = 0)`
|
|
78
|
+
|
|
79
|
+
Returns `(terminalProceeds + accumulatedIncome - initialInvestment) / initialInvestment`.
|
|
80
|
+
Terminal proceeds must be non-negative. Accumulated income may be negative to
|
|
81
|
+
represent operating losses. This is a **cumulative**, not annualized, return.
|
|
82
|
+
|
|
83
|
+
### `cagr(initialValue, finalValue, years)`
|
|
84
|
+
|
|
85
|
+
Returns `(finalValue / initialValue) ** (1 / years) - 1`.
|
|
86
|
+
Final value must be non-negative. A zero final value returns `-1` (100% loss).
|
|
87
|
+
This is a **capital-only** measure. It is not IRR/XIRR and does not account for
|
|
88
|
+
interim cashflow timing. Do not add this rate to cash yield to invent a total CAGR.
|
|
89
|
+
|
|
90
|
+
### `projectScenario(options)`
|
|
91
|
+
|
|
92
|
+
| Option | Required | Meaning |
|
|
93
|
+
| --- | --- | --- |
|
|
94
|
+
| `initialInvestment` | yes | Positive initial asset value / capital invested |
|
|
95
|
+
| `annualIncome` | yes | Non-negative gross income per year |
|
|
96
|
+
| `years` | yes | Positive holding period; fractional years allowed |
|
|
97
|
+
| `annualExpenses` | no, `0` | Non-negative fixed annual expenses |
|
|
98
|
+
| `annualGrowthRate` | no, `0` | Annual compound asset growth, at least `-1` |
|
|
99
|
+
| `exitFeeRate` | no, `0` | Fraction of ending asset value, between `0` and `1` |
|
|
100
|
+
|
|
101
|
+
Returned fields:
|
|
102
|
+
|
|
103
|
+
| Field | Formula |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| `netAnnualIncome` | annualIncome - annualExpenses |
|
|
106
|
+
| `accumulatedIncome` | netAnnualIncome * years |
|
|
107
|
+
| `endingAssetValue` | initialInvestment * (1 + annualGrowthRate) ** years |
|
|
108
|
+
| `exitFee` | endingAssetValue * exitFeeRate |
|
|
109
|
+
| `terminalProceeds` | endingAssetValue - exitFee |
|
|
110
|
+
| `netProfit` | terminalProceeds + accumulatedIncome - initialInvestment |
|
|
111
|
+
| `cashYieldRate` | netAnnualIncome / initialInvestment |
|
|
112
|
+
| `totalReturnRate` | netProfit / initialInvestment |
|
|
113
|
+
| `capitalCagrRate` | cagr(initialInvestment, terminalProceeds, years) |
|
|
114
|
+
|
|
115
|
+
### `compareScenarios(scenarios)`
|
|
116
|
+
|
|
117
|
+
Accepts an array of the options above plus a unique `id`. Returns ranked projection
|
|
118
|
+
objects. Duplicate ids throw `RangeError`; missing/blank/non-string ids throw `TypeError`.
|
|
119
|
+
|
|
120
|
+
### `formatMoney(amount, options)`
|
|
121
|
+
|
|
122
|
+
Formats a money amount for display with `Intl.NumberFormat`. `options.currency`
|
|
123
|
+
is required (3-letter ISO 4217 code); `options.locale` defaults to `en-US`.
|
|
124
|
+
Use `en-IN` for Indian digit grouping.
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
formatMoney(100000, { locale: 'en-IN', currency: 'INR' }); // "₹1,00,000.00"
|
|
128
|
+
formatMoney(1000, { locale: 'en-US', currency: 'USD' }); // "$1,000.00"
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### `formatRate(rate, options)`
|
|
132
|
+
|
|
133
|
+
Formats a decimal rate as a percentage. `options.maximumFractionDigits`
|
|
134
|
+
defaults to `2` (integer 0-20); `options.locale` defaults to `en-US`.
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
formatRate(0.06); // "6%"
|
|
138
|
+
formatRate(0.03945); // "3.95%"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Both helpers are **display only**. They format output for humans; every
|
|
142
|
+
calculation stays an unrounded IEEE-754 number exactly as documented above.
|
|
143
|
+
They change nothing about financial accuracy and are never used internally.
|
|
144
|
+
|
|
145
|
+
## Browser playground
|
|
146
|
+
|
|
147
|
+
A zero-build playground that ranks scenarios against the published package
|
|
148
|
+
lives in the demo repo: [cashflow-lens-demo/playground](https://github.com/aman050807/cashflow-lens-demo/tree/main/playground).
|
|
149
|
+
|
|
150
|
+
## Model assumptions and limits
|
|
151
|
+
|
|
152
|
+
- Initial investment equals initial asset value. Acquisition costs are not modeled.
|
|
153
|
+
- Income and expenses stay constant and are **not reinvested**. Fractional years
|
|
154
|
+
prorate these flows linearly; asset growth compounds over the fractional exponent.
|
|
155
|
+
- No taxes, inflation, debt, currency conversion, vacancies, changing fees or risk model.
|
|
156
|
+
Model an expected vacancy allowance within annual income, not as a guaranteed outcome.
|
|
157
|
+
- Exit fee applies to ending asset value, not profit. Net cashflow may be negative.
|
|
158
|
+
- Annual growth cannot be below -100%; exit fees can reach 100%.
|
|
159
|
+
- Unknown option fields are ignored. Sparse comparison arrays are invalid.
|
|
160
|
+
- Uses IEEE-754 numbers, not decimal accounting arithmetic. Do not use for payment
|
|
161
|
+
settlement, ledger reconciliation or exact money storage. Very large inputs may overflow.
|
|
162
|
+
- Inputs must be finite numbers, not numeric strings. Initial capital and years must
|
|
163
|
+
be greater than zero. Invalid types throw `TypeError`, invalid ranges and non-finite
|
|
164
|
+
calculated results throw `RangeError`. Very tiny values can underflow to zero.
|
|
165
|
+
|
|
166
|
+
## Development and verification
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
npm ci
|
|
170
|
+
npm test
|
|
171
|
+
npm run test:coverage
|
|
172
|
+
npm pack --dry-run
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Tests cover hand-calculated examples, losses, zero final values, fractional years,
|
|
176
|
+
invalid input, overflow, stable sorting, scale invariance, non-mutation, display
|
|
177
|
+
formatting and both module loading styles. CI runs on Node.js 20, 22 and 24.
|
|
178
|
+
|
|
179
|
+
## Versioning
|
|
180
|
+
|
|
181
|
+
Semantic versioning. The first stable release is `1.0.0`. Patch versions fix bugs;
|
|
182
|
+
minor versions add backward-compatible features; major versions change existing
|
|
183
|
+
contracts. See [CHANGELOG.md](CHANGELOG.md).
|
|
184
|
+
|
|
185
|
+
## License
|
|
186
|
+
|
|
187
|
+
MIT. See [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,45 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aman050807/cashflow-lens",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Pure, dependency-free cashflow and investment scenario calculations with explicit assumptions.",
|
|
5
|
+
"main": "./src/index.js",
|
|
6
|
+
"types": "./src/index.d.ts",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"types": "./src/index.d.ts",
|
|
10
|
+
"default": "./src/index.js"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"files": [
|
|
15
|
+
"src",
|
|
16
|
+
"README.md",
|
|
17
|
+
"LICENSE",
|
|
18
|
+
"CHANGELOG.md"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"test": "node --test",
|
|
22
|
+
"test:coverage": "node --test --experimental-test-coverage",
|
|
23
|
+
"prepublishOnly": "npm test"
|
|
24
|
+
},
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=20"
|
|
27
|
+
},
|
|
28
|
+
"keywords": [
|
|
29
|
+
"cashflow",
|
|
30
|
+
"roi",
|
|
31
|
+
"cagr",
|
|
32
|
+
"investment",
|
|
33
|
+
"comparison"
|
|
34
|
+
],
|
|
35
|
+
"author": "V M Aman Sharma",
|
|
36
|
+
"license": "MIT",
|
|
37
|
+
"repository": {
|
|
38
|
+
"type": "git",
|
|
39
|
+
"url": "git+https://github.com/aman050807/cashflow-lens.git"
|
|
40
|
+
},
|
|
41
|
+
"homepage": "https://github.com/aman050807/cashflow-lens#readme",
|
|
42
|
+
"bugs": {
|
|
43
|
+
"url": "https://github.com/aman050807/cashflow-lens/issues"
|
|
44
|
+
}
|
|
45
|
+
}
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* cashflow-lens: compare cashflow scenarios without mixing rental income
|
|
3
|
+
* with capital growth.
|
|
4
|
+
*
|
|
5
|
+
* All money arguments must use one consistent currency/unit. Rates are
|
|
6
|
+
* decimal fractions: `0.08` means 8%. Results are unrounded JavaScript
|
|
7
|
+
* numbers (IEEE-754, not decimal accounting); round for display only.
|
|
8
|
+
* All examples are fictional, not investment advice.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A scenario to project. Rates are decimals (`0.05` = 5%); money uses one
|
|
13
|
+
* consistent currency.
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* const flat = {
|
|
17
|
+
* initialInvestment: 5000000, // ₹50 lakh
|
|
18
|
+
* annualIncome: 300000, // rent
|
|
19
|
+
* annualExpenses: 60000, // maintenance, tax
|
|
20
|
+
* annualGrowthRate: 0.04,
|
|
21
|
+
* years: 5,
|
|
22
|
+
* exitFeeRate: 0.02
|
|
23
|
+
* };
|
|
24
|
+
*/
|
|
25
|
+
export interface Scenario {
|
|
26
|
+
/** Initial asset value / capital invested. Must be greater than zero. */
|
|
27
|
+
initialInvestment: number;
|
|
28
|
+
/** Gross income per year. Must be non-negative. */
|
|
29
|
+
annualIncome: number;
|
|
30
|
+
/** Fixed annual expenses. Default `0`. Must be non-negative. */
|
|
31
|
+
annualExpenses?: number;
|
|
32
|
+
/** Annual compound asset growth as a decimal. Default `0`. At least `-1`. */
|
|
33
|
+
annualGrowthRate?: number;
|
|
34
|
+
/** Holding period in years; fractional years allowed. Must be greater than zero. */
|
|
35
|
+
years: number;
|
|
36
|
+
/** Fraction of ending asset value charged at exit. Default `0`. Between `0` and `1`. */
|
|
37
|
+
exitFeeRate?: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The projection returned by {@link projectScenario}. All rates are decimal
|
|
42
|
+
* fractions; all money fields use the input's currency.
|
|
43
|
+
*/
|
|
44
|
+
export interface Projection {
|
|
45
|
+
/** `annualIncome - annualExpenses` */
|
|
46
|
+
netAnnualIncome: number;
|
|
47
|
+
/** `netAnnualIncome * years` (income is not reinvested) */
|
|
48
|
+
accumulatedIncome: number;
|
|
49
|
+
/** `initialInvestment * (1 + annualGrowthRate) ** years` */
|
|
50
|
+
endingAssetValue: number;
|
|
51
|
+
/** `endingAssetValue * exitFeeRate` */
|
|
52
|
+
exitFee: number;
|
|
53
|
+
/** `endingAssetValue - exitFee` */
|
|
54
|
+
terminalProceeds: number;
|
|
55
|
+
/** `terminalProceeds + accumulatedIncome - initialInvestment` */
|
|
56
|
+
netProfit: number;
|
|
57
|
+
/** `netAnnualIncome / initialInvestment` */
|
|
58
|
+
cashYieldRate: number;
|
|
59
|
+
/** `netProfit / initialInvestment` (cumulative, not annualized) */
|
|
60
|
+
totalReturnRate: number;
|
|
61
|
+
/** Capital-only CAGR after exit fees. Excludes interim income; do not add it to cash yield. */
|
|
62
|
+
capitalCagrRate: number;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** A {@link Scenario} plus a unique non-empty string `id`. */
|
|
66
|
+
export interface IdentifiedScenario extends Scenario { id: string; }
|
|
67
|
+
|
|
68
|
+
/** A {@link Projection} plus the `id` of the scenario it came from. */
|
|
69
|
+
export interface RankedProjection extends Projection { id: string; }
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Annual net income divided by initial investment. Returns a decimal rate.
|
|
73
|
+
*
|
|
74
|
+
* @param initialInvestment Positive initial capital.
|
|
75
|
+
* @param annualIncome Non-negative gross annual income.
|
|
76
|
+
* @param annualExpenses Non-negative annual expenses. Default `0`.
|
|
77
|
+
* @returns `(annualIncome - annualExpenses) / initialInvestment`
|
|
78
|
+
* @throws {TypeError} Non-finite or wrongly typed arguments.
|
|
79
|
+
* @throws {RangeError} Negative income/expenses or non-positive investment.
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* cashYield(10000, 800, 200); // 0.06, i.e. 6%
|
|
83
|
+
*/
|
|
84
|
+
export declare function cashYield(initialInvestment: number, annualIncome: number, annualExpenses?: number): number;
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Cumulative total return: income and terminal proceeds versus initial
|
|
88
|
+
* investment. Not annualized.
|
|
89
|
+
*
|
|
90
|
+
* @param initialInvestment Positive initial capital.
|
|
91
|
+
* @param terminalProceeds Non-negative proceeds at exit.
|
|
92
|
+
* @param accumulatedIncome Income over the holding period; may be negative. Default `0`.
|
|
93
|
+
* @returns `(terminalProceeds + accumulatedIncome - initialInvestment) / initialInvestment`
|
|
94
|
+
* @throws {TypeError} Non-finite or wrongly typed arguments.
|
|
95
|
+
* @throws {RangeError} Negative terminal proceeds or non-positive investment.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* totalReturn(10000, 10804.5, 1200); // 0.20045, i.e. 20.045% over the period
|
|
99
|
+
*/
|
|
100
|
+
export declare function totalReturn(initialInvestment: number, terminalProceeds: number, accumulatedIncome?: number): number;
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Capital-only compound annual growth rate. Not IRR/XIRR: ignores interim
|
|
104
|
+
* income and its timing. A zero final value returns `-1` (100% loss).
|
|
105
|
+
*
|
|
106
|
+
* @param initialValue Positive starting value.
|
|
107
|
+
* @param finalValue Non-negative ending value.
|
|
108
|
+
* @param years Positive period; fractional years allowed.
|
|
109
|
+
* @returns `(finalValue / initialValue) ** (1 / years) - 1`
|
|
110
|
+
* @throws {TypeError} Non-finite or wrongly typed arguments.
|
|
111
|
+
* @throws {RangeError} Negative final value, or non-positive initial value or years.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* cagr(100, 121, 2); // 0.1, i.e. 10% per year
|
|
115
|
+
*/
|
|
116
|
+
export declare function cagr(initialValue: number, finalValue: number, years: number): number;
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Project one scenario: fixed annual net income (not reinvested) plus
|
|
120
|
+
* constant compound asset growth, minus an exit fee on the ending value.
|
|
121
|
+
*
|
|
122
|
+
* Model limits: no taxes, inflation, debt, vacancies or reinvestment.
|
|
123
|
+
* Unknown option fields are ignored.
|
|
124
|
+
*
|
|
125
|
+
* @param scenario The scenario to project.
|
|
126
|
+
* @returns The {@link Projection}. Throws `RangeError` if any result overflows to a non-finite number.
|
|
127
|
+
* @throws {TypeError} Missing/invalid fields or a non-object argument.
|
|
128
|
+
* @throws {RangeError} Out-of-range fields (see {@link Scenario}).
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* const p = projectScenario({
|
|
132
|
+
* initialInvestment: 10000, annualIncome: 800, annualExpenses: 200,
|
|
133
|
+
* annualGrowthRate: 0.05, years: 2, exitFeeRate: 0.02
|
|
134
|
+
* });
|
|
135
|
+
* p.netProfit; // 2004.5
|
|
136
|
+
* p.cashYieldRate; // 0.06
|
|
137
|
+
* p.totalReturnRate; // 0.20045
|
|
138
|
+
* p.capitalCagrRate; // about 0.0394
|
|
139
|
+
*/
|
|
140
|
+
export declare function projectScenario(scenario: Scenario): Projection;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Rank scenarios by total return rate, highest first. Equal rates retain
|
|
144
|
+
* input order. Inputs are never mutated; empty input returns `[]`.
|
|
145
|
+
*
|
|
146
|
+
* Only compare like-for-like horizons and currency assumptions: this ranks
|
|
147
|
+
* one metric, not risk, liquidity, suitability or investment quality.
|
|
148
|
+
*
|
|
149
|
+
* @param scenarios Scenarios with unique non-empty string `id`s.
|
|
150
|
+
* @returns Ranked projections carrying each scenario's `id`.
|
|
151
|
+
* @throws {TypeError} Non-array input, or a missing/blank/non-string `id`.
|
|
152
|
+
* @throws {RangeError} Duplicate `id`s.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* const ranked = compareScenarios([
|
|
156
|
+
* { id: 'income-first', initialInvestment: 10000, annualIncome: 800, years: 3 },
|
|
157
|
+
* { id: 'growth-first', initialInvestment: 10000, annualIncome: 400, annualGrowthRate: 0.05, years: 3 }
|
|
158
|
+
* ]);
|
|
159
|
+
* ranked.map(row => row.id); // ['growth-first', 'income-first']
|
|
160
|
+
*/
|
|
161
|
+
export declare function compareScenarios(scenarios: readonly IdentifiedScenario[]): RankedProjection[];
|
|
162
|
+
|
|
163
|
+
/** Options for {@link formatMoney}. */
|
|
164
|
+
export interface FormatMoneyOptions {
|
|
165
|
+
/**
|
|
166
|
+
* BCP 47 locale controlling digit grouping and symbol placement.
|
|
167
|
+
* Default `'en-US'`. Use `'en-IN'` for Indian grouping (`1,00,000`).
|
|
168
|
+
*/
|
|
169
|
+
locale?: string;
|
|
170
|
+
/** 3-letter ISO 4217 currency code, e.g. `'INR'`, `'USD'`, `'EUR'`. Required. */
|
|
171
|
+
currency: string;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** Options for {@link formatRate}. */
|
|
175
|
+
export interface FormatRateOptions {
|
|
176
|
+
/** BCP 47 locale. Default `'en-US'`. */
|
|
177
|
+
locale?: string;
|
|
178
|
+
/** Fraction digits shown after the decimal point, integer 0-20. Default `2`. */
|
|
179
|
+
maximumFractionDigits?: number;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Format a money amount for display, using the runtime's `Intl.NumberFormat`
|
|
184
|
+
* data. Display only: the returned string is for humans and never feeds the
|
|
185
|
+
* library's calculations, which stay unrounded IEEE-754 numbers.
|
|
186
|
+
*
|
|
187
|
+
* @param amount Finite number in the given currency.
|
|
188
|
+
* @param options See {@link FormatMoneyOptions}. `currency` is required.
|
|
189
|
+
* @returns A localized currency string.
|
|
190
|
+
* @throws {TypeError} Non-finite amount, missing/non-string currency, or non-object options.
|
|
191
|
+
* @throws {RangeError} Currency that is not a 3-letter ISO 4217 code.
|
|
192
|
+
*
|
|
193
|
+
* @example
|
|
194
|
+
* formatMoney(100000, { locale: 'en-IN', currency: 'INR' }); // "₹1,00,000.00"
|
|
195
|
+
* formatMoney(1000, { locale: 'en-US', currency: 'USD' }); // "$1,000.00"
|
|
196
|
+
*/
|
|
197
|
+
export declare function formatMoney(amount: number, options: FormatMoneyOptions): string;
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Format a decimal rate as a percentage for display. Display only: rounding
|
|
201
|
+
* applies to the string, not to stored values.
|
|
202
|
+
*
|
|
203
|
+
* @param rate Finite decimal rate (`0.06` = 6%).
|
|
204
|
+
* @param options See {@link FormatRateOptions}.
|
|
205
|
+
* @returns A localized percent string.
|
|
206
|
+
* @throws {TypeError} Non-finite rate, non-integer digits, or non-object options.
|
|
207
|
+
* @throws {RangeError} `maximumFractionDigits` outside 0-20.
|
|
208
|
+
*
|
|
209
|
+
* @example
|
|
210
|
+
* formatRate(0.06); // "6%"
|
|
211
|
+
* formatRate(0.0394, { maximumFractionDigits: 1 }); // "3.9%"
|
|
212
|
+
*/
|
|
213
|
+
export declare function formatRate(rate: number, options?: FormatRateOptions): string;
|
package/src/index.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
function finite(value, name) {
|
|
4
|
+
if (typeof value !== 'number' || !Number.isFinite(value)) {
|
|
5
|
+
throw new TypeError(`${name} must be a finite number`);
|
|
6
|
+
}
|
|
7
|
+
return value;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
function positive(value, name) {
|
|
11
|
+
finite(value, name);
|
|
12
|
+
if (value <= 0) throw new RangeError(`${name} must be greater than zero`);
|
|
13
|
+
return value;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function nonnegative(value, name) {
|
|
17
|
+
finite(value, name);
|
|
18
|
+
if (value < 0) throw new RangeError(`${name} must not be negative`);
|
|
19
|
+
return value;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function result(value) {
|
|
23
|
+
if (!Number.isFinite(value)) throw new RangeError('calculation exceeds the finite number range');
|
|
24
|
+
return value;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Annual net income divided by initial investment. Returns a decimal rate. */
|
|
28
|
+
function cashYield(initialInvestment, annualIncome, annualExpenses = 0) {
|
|
29
|
+
positive(initialInvestment, 'initialInvestment');
|
|
30
|
+
nonnegative(annualIncome, 'annualIncome');
|
|
31
|
+
nonnegative(annualExpenses, 'annualExpenses');
|
|
32
|
+
return result((annualIncome - annualExpenses) / initialInvestment);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** (Terminal proceeds + accumulated income - initial investment) / initial investment. */
|
|
36
|
+
function totalReturn(initialInvestment, terminalProceeds, accumulatedIncome = 0) {
|
|
37
|
+
positive(initialInvestment, 'initialInvestment');
|
|
38
|
+
nonnegative(terminalProceeds, 'terminalProceeds');
|
|
39
|
+
finite(accumulatedIncome, 'accumulatedIncome');
|
|
40
|
+
return result((terminalProceeds + accumulatedIncome - initialInvestment) / initialInvestment);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Capital-only CAGR. Does not account for interim income or its timing. */
|
|
44
|
+
function cagr(initialValue, finalValue, years) {
|
|
45
|
+
positive(initialValue, 'initialValue');
|
|
46
|
+
nonnegative(finalValue, 'finalValue');
|
|
47
|
+
positive(years, 'years');
|
|
48
|
+
return result(Math.pow(finalValue / initialValue, 1 / years) - 1);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Fixed annual net income, no reinvestment, constant annual asset growth. */
|
|
52
|
+
function projectScenario(options) {
|
|
53
|
+
if (options === null || typeof options !== 'object' || Array.isArray(options)) {
|
|
54
|
+
throw new TypeError('scenario must be an object');
|
|
55
|
+
}
|
|
56
|
+
const { initialInvestment, annualIncome, annualExpenses = 0,
|
|
57
|
+
annualGrowthRate = 0, years, exitFeeRate = 0 } = options;
|
|
58
|
+
positive(initialInvestment, 'initialInvestment');
|
|
59
|
+
nonnegative(annualIncome, 'annualIncome');
|
|
60
|
+
nonnegative(annualExpenses, 'annualExpenses');
|
|
61
|
+
positive(years, 'years');
|
|
62
|
+
finite(annualGrowthRate, 'annualGrowthRate');
|
|
63
|
+
if (annualGrowthRate < -1) throw new RangeError('annualGrowthRate must be at least -1');
|
|
64
|
+
finite(exitFeeRate, 'exitFeeRate');
|
|
65
|
+
if (exitFeeRate < 0 || exitFeeRate > 1) throw new RangeError('exitFeeRate must be between 0 and 1');
|
|
66
|
+
const netAnnualIncome = result(annualIncome - annualExpenses);
|
|
67
|
+
const accumulatedIncome = result(netAnnualIncome * years);
|
|
68
|
+
const endingAssetValue = result(initialInvestment * Math.pow(1 + annualGrowthRate, years));
|
|
69
|
+
const exitFee = result(endingAssetValue * exitFeeRate);
|
|
70
|
+
const terminalProceeds = result(endingAssetValue - exitFee);
|
|
71
|
+
const netProfit = result(terminalProceeds + accumulatedIncome - initialInvestment);
|
|
72
|
+
return {
|
|
73
|
+
netAnnualIncome, accumulatedIncome, endingAssetValue, exitFee, terminalProceeds, netProfit,
|
|
74
|
+
cashYieldRate: cashYield(initialInvestment, annualIncome, annualExpenses),
|
|
75
|
+
totalReturnRate: totalReturn(initialInvestment, terminalProceeds, accumulatedIncome),
|
|
76
|
+
capitalCagrRate: cagr(initialInvestment, terminalProceeds, years)
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Rank scenarios by total return rate, descending. Input order breaks ties. */
|
|
81
|
+
function compareScenarios(scenarios) {
|
|
82
|
+
if (!Array.isArray(scenarios)) throw new TypeError('scenarios must be an array');
|
|
83
|
+
const ids = new Set();
|
|
84
|
+
return Array.from(scenarios, (scenario) => {
|
|
85
|
+
if (!scenario || typeof scenario.id !== 'string' || scenario.id.trim() === '') {
|
|
86
|
+
throw new TypeError('each scenario must have a non-empty string id');
|
|
87
|
+
}
|
|
88
|
+
if (ids.has(scenario.id)) throw new RangeError(`duplicate scenario id: ${scenario.id}`);
|
|
89
|
+
ids.add(scenario.id);
|
|
90
|
+
return { id: scenario.id, ...projectScenario(scenario) };
|
|
91
|
+
}).sort((a, b) => b.totalReturnRate - a.totalReturnRate);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function localeOf(value) {
|
|
95
|
+
if (value === undefined) return 'en-US';
|
|
96
|
+
if (typeof value !== 'string' || value.trim() === '') {
|
|
97
|
+
throw new TypeError('locale must be a non-empty BCP 47 string, e.g. "en-IN"');
|
|
98
|
+
}
|
|
99
|
+
return value;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Format a money amount for display, e.g. "\u20B91,00,000.00" in en-IN/INR.
|
|
104
|
+
* Display only: the result is a string for humans and never feeds calculations.
|
|
105
|
+
*/
|
|
106
|
+
function formatMoney(amount, options = {}) {
|
|
107
|
+
finite(amount, 'amount');
|
|
108
|
+
if (options === null || typeof options !== 'object' || Array.isArray(options)) {
|
|
109
|
+
throw new TypeError('options must be an object');
|
|
110
|
+
}
|
|
111
|
+
if (options.currency === undefined) throw new TypeError('options.currency is required');
|
|
112
|
+
if (typeof options.currency !== 'string') throw new TypeError('currency must be a string');
|
|
113
|
+
if (!/^[A-Za-z]{3}$/.test(options.currency)) {
|
|
114
|
+
throw new RangeError('currency must be a 3-letter ISO 4217 code, e.g. "INR"');
|
|
115
|
+
}
|
|
116
|
+
return new Intl.NumberFormat(localeOf(options.locale),
|
|
117
|
+
{ style: 'currency', currency: options.currency.toUpperCase() }).format(amount);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Format a decimal rate as a percentage for display, e.g. 0.06 -> "6%".
|
|
122
|
+
* Display only: rounding applies to the string, not to stored values.
|
|
123
|
+
*/
|
|
124
|
+
function formatRate(rate, options = {}) {
|
|
125
|
+
finite(rate, 'rate');
|
|
126
|
+
if (options === null || typeof options !== 'object' || Array.isArray(options)) {
|
|
127
|
+
throw new TypeError('options must be an object');
|
|
128
|
+
}
|
|
129
|
+
const digits = options.maximumFractionDigits === undefined ? 2 : options.maximumFractionDigits;
|
|
130
|
+
if (typeof digits !== 'number' || !Number.isInteger(digits)) {
|
|
131
|
+
throw new TypeError('maximumFractionDigits must be an integer');
|
|
132
|
+
}
|
|
133
|
+
if (digits < 0 || digits > 20) throw new RangeError('maximumFractionDigits must be between 0 and 20');
|
|
134
|
+
return new Intl.NumberFormat(localeOf(options.locale),
|
|
135
|
+
{ style: 'percent', maximumFractionDigits: digits }).format(rate);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
exports.cashYield = cashYield;
|
|
139
|
+
exports.totalReturn = totalReturn;
|
|
140
|
+
exports.cagr = cagr;
|
|
141
|
+
exports.projectScenario = projectScenario;
|
|
142
|
+
exports.compareScenarios = compareScenarios;
|
|
143
|
+
exports.formatMoney = formatMoney;
|
|
144
|
+
exports.formatRate = formatRate;
|