Options
All
• Public
• Public/Protected
• All

# Module "financial"

## Functions

### Private _gDivGp

• _gDivGp(r: number, n: number, p: number, x: number, y: number, when: PaymentDueTime): number
• Evaluates g(r_n)/g'(r_n), where:

g = fv + pv * (1+rate) ** nper + pmt * (1+rate * when)/rate * ((1+rate) ** nper - 1)

### Private _irrResult

• _irrResult(values: number[], dates: number[], rate: number): number
• Calculates the resulting amount.

### Private _irrResultDeriv

• _irrResultDeriv(values: number[], dates: number[], rate: number): number
• Calculates the first derivation

### Private _rbl

• _rbl(rate: number, per: number, pmt: number, pv: number, when: PaymentDueTime): number
• This function is here to simply have a different name for the 'fv' function to not interfere with the 'fv' keyword argument within the 'ipmt' function. It is the 'remaining balance on loan' which might be useful as it's own function, but is easily calculated with the 'fv' function.

### fv

• fv(rate: number, nper: number, pmt: number, pv: number, when?: PaymentDueTime): number
• Compute the future value.

since

v0.0.12

## Examples

What is the future value after 10 years of saving $100 now, with an additional monthly savings of$100. Assume the interest rate is 5% (annually) compounded monthly?

import { fv } from 'financial'

fv(0.05 / 12, 10 * 12, -100, -100) // 15692.928894335748

By convention, the negative sign represents cash flow out (i.e. money not available today). Thus, saving $100 a month at 5% annual interest leads to$15,692.93 available to spend in 10 years.

The future value is computed by solving the equation:

fv + pv * (1+rate) ** nper + pmt * (1 + rate * when) / rate * ((1 + rate) ** nper - 1) == 0

or, when rate == 0:

fv + pv + pmt * nper == 0

#### Parameters

• ##### rate: number

Rate of interest as decimal (not per cent) per period

• ##### nper: number

Number of compounding periods

• ##### pmt: number

A fixed payment, paid either at the beginning or ar the end (specified by when)

• ##### pv: number

Present value

#### Returns number

The value at the end of the nper periods

### ipmt

• ipmt(rate: number, per: number, nper: number, pv: number, fv?: number, when?: PaymentDueTime): number
• Compute the interest portion of a payment.

since

v0.0.12

## Examples

What is the amortization schedule for a 1 year loan of $2500 at 8.24% interest per year compounded monthly? const principal = 2500 const periods = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] const ipmts = periods.map((per) => f.ipmt(0.0824 / 12, per, 1 * 12, principal)) expect(ipmts).toEqual([ -17.166666666666668, -15.789337457350777, -14.402550587464257, -13.006241114404524, -11.600343649629737, -10.18479235559687, -8.759520942678298, -7.324462666057678, -5.879550322604295, -4.424716247725826, -2.9598923121998877, -1.4850099189833388 ]) const interestpd = ipmts.reduce((a, b) => a + b, 0) expect(interestpd).toBeCloseTo(-112.98308424136215, 6) The periods variable represents the periods of the loan. Remember that financial equations start the period count at 1! ## Notes The total payment is made up of payment against principal plus interest. pmt = ppmt + ipmt #### Parameters • ##### rate: number Rate of interest as decimal (not per cent) per period • ##### per: number Interest paid against the loan changes during the life or the loan. The per is the payment period to calculate the interest amount • ##### nper: number Number of compounding periods • ##### pv: number Present value • ##### Default value fv: number = 0 Future value • ##### Default value when: PaymentDueTime = PaymentDueTime.End When payments are due #### Returns number Interest portion of payment ### irr • irr(values: number[], guess?: number, tol?: number, maxIter?: number): number • Return the Internal Rate of Return (IRR). This is the "average" periodically compounded rate of return that gives a net present value of 0.0; for a more complete explanation, see Notes below. since v0.0.17 ## Notes The IRR is perhaps best understood through an example (illustrated using irr in the Examples section below). Suppose one invests 100 units and then makes the following withdrawals at regular (fixed) intervals: 39, 59, 55, 20. Assuming the ending value is 0, one's 100 unit investment yields 173 units; however, due to the combination of compounding and the periodic withdrawals, the "average" rate of return is neither simply 0.73/4 nor (1.73)^0.25-1. Rather, it is the solution (for r) of the equation: -100 + 39/(1+r) + 59/((1+r)^2) + 55/((1+r)^3) + 20/((1+r)^4) = 0 In general, for values = [0, 1, ... M], irr is the solution of the equation: \\sum_{t=0}^M{\\frac{v_t}{(1+irr)^{t}}} = 0 ## Example import { irr } from 'financial' irr([-100, 39, 59, 55, 20]) // 0.28095 irr([-100, 0, 0, 74]) // -0.0955 irr([-100, 100, 0, -7]) // -0.0833 irr([-100, 100, 0, 7]) // 0.06206 irr([-5, 10.5, 1, -8, 1]) // 0.0886 ## References • L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed., Addison-Wesley, 2003, pg. 348. #### Parameters • ##### values: number[] Input cash flows per time period. By convention, net "deposits" are negative and net "withdrawals" are positive. Thus, for example, at least the first element of values, which represents the initial investment, will typically be negative. • ##### Default value guess: number = 0.1 Starting guess for solving the Internal Rate of Return • ##### Default value tol: number = 0.000001 Required tolerance for the solution • ##### Default value maxIter: number = 100 Maximum iterations in finding the solution #### Returns number Internal Rate of Return for periodic input values ### mirr • mirr(values: number[], financeRate: number, reinvestRate: number): number • Calculates the Modified Internal Rate of Return. since v0.1.0 #### Parameters • ##### values: number[] Cash flows (must contain at least one positive and one negative value) or nan is returned. The first value is considered a sunk cost at time zero. • ##### financeRate: number Interest rate paid on the cash flows • ##### reinvestRate: number Interest rate received on the cash flows upon reinvestment #### Returns number Modified internal rate of return ### nper • nper(rate: number, pmt: number, pv: number, fv?: number, when?: PaymentDueTime): number • Compute the number of periodic payments. since v0.0.12 ## Examples If you only had$150/month to pay towards the loan, how long would it take to pay-off a loan of $8,000 at 7% annual interest? import { nper } from 'financial' Math.round(nper(0.07/12, -150, 8000), 5) // 64.07335 So, over 64 months would be required to pay off the loan. ## Notes The number of periods nper is computed by solving the equation: fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper-1) = 0 but if rate = 0 then: fv + pv + pmt * nper = 0 #### Parameters • ##### rate: number Rate of interest (per period) • ##### pmt: number Payment • ##### pv: number Present value • ##### Default value fv: number = 0 Future value • ##### Default value when: PaymentDueTime = PaymentDueTime.End When payments are due #### Returns number The number of periodic payments ### npv • npv(rate: number, values: number[]): number • Returns the NPV (Net Present Value) of a cash flow series. since v0.0.18 ## Warnings npv considers a series of cashflows starting in the present (t = 0). NPV can also be defined with a series of future cashflows, paid at the end, rather than the start, of each period. If future cashflows are used, the first cashflowvalues must be zeroed and added to the net present value of the future cashflows. This is demonstrated in the examples. ## Notes Returns the result of: \\sum_{t=0}^{M-1}{\\frac{values_t}{(1+rate)^{t}}} ## Examples Consider a potential project with an initial investment of$40 000 and projected cashflows of $5 000,$8 000, $12 000 and$30 000 at the end of each period discounted at a rate of 8% per period. To find the project's net present value:

import {npv} from 'financial'

const rate = 0.08
const cashflows = [-40_000, 5000, 8000, 12000, 30000]
npv(rate, cashflows) // 3065.2226681795255

It may be preferable to split the projected cashflow into an initial investment and expected future cashflows. In this case, the value of the initial cashflow is zero and the initial investment is later added to the future cashflows net present value:

const initialCashflow = cashflows
cashflows = 0

npv(rate, cashflows) + initialCashflow // 3065.2226681795255

## References

L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed., Addison-Wesley, 2003, pg. 346.

#### Parameters

• ##### rate: number

The discount rate

• ##### values: number[]

The values of the time series of cash flows. The (fixed) time interval between cash flow "events" must be the same as that for which rate is given (i.e., if rate is per year, then precisely a year is understood to elapse between each cash flow event). By convention, investments or "deposits" are negative, income or "withdrawals" are positive; values must begin with the initial investment, thus values will typically be negative.

#### Returns number

The NPV of the input cash flow series values at the discount rate.

### pmt

• pmt(rate: number, nper: number, pv: number, fv?: number, when?: PaymentDueTime): number
• Compute the payment against loan principal plus interest.

since

v0.0.12

## Notes

The present value is computed by solving the equation:

fv + pv * (1 + rate) ** nper + pmt * (1 + rate * when) / rate * ((1 + rate) ** nper - 1) = 0

or, when rate = 0:

fv + pv + pmt * nper = 0

for pv, which is then returned.

## References

#### Parameters

• ##### rate: number

Rate of interest (per period)

• ##### nper: number

Number of compounding periods

Payment

• ##### Default value fv: number = 0

Future value

• ##### Default value when: PaymentDueTime = PaymentDueTime.End

When payments are due

#### Returns number

the present value of a payment or investment

### rate

• rate(nper: number, pmt: number, pv: number, fv: number, when?: PaymentDueTime, guess?: number, tol?: number, maxIter?: number): number
• Compute the rate of interest per period

since

v0.0.16

## Notes

Use Newton's iteration until the change is less than 1e-6 for all values or a maximum of 100 iterations is reached. Newton's rule is:

r_{n+1} = r_{n} - g(r_n)/g'(r_n)

where:

• g(r) is the formula
• g'(r) is the derivative with respect to r.

The rate of interest is computed by iteratively solving the (non-linear) equation:

fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper - 1) = 0

for rate.

## References

#### Parameters

• ##### nper: number

Number of compounding periods

Payment

• ##### pv: number

Present value

• ##### fv: number

Future value

• ##### Default value when: PaymentDueTime = PaymentDueTime.End

When payments are due ('begin' or 'end')

• ##### Default value guess: number = 0.1

Starting guess for solving the rate of interest

• ##### Default value tol: number = 0.000001

Required tolerance for the solution

• ##### Default value maxIter: number = 100

Maximum iterations in finding the solution

#### Returns number

the rate of interest per period (or NaN if it could not be computed within the number of iterations provided)

Generated using TypeDoc