Finance

Collection of financial functions.

Methods

annuity

annuity(rate: number, periods: number) 

Calculates the annuity for a given number of periods and interest rate for a capital of 1.

Parameters

rate number

The decimal interest rate. 1 = 100%

periods number

The number of periods.

Return type

number

Examples

// Calculates annuity over a period of 30 years with an interest rate of 6%:
Finance.annuity(0.06, 30) // => 0.07264891149004721 (Calculates annuity over a period of 30 years with an interest rate of 6%)

An

An(rate: number, periods: number) 

Calculates the present value for a lumpsum, based on a given number of periods and interest rate for a capital of 1.

Parameters

rate number

The decimal interest rate. 1 = 100%

periods number

The number of periods.

Return type

number

Examples

// Calculates present value over a period of 30 years with an interest rate of 6%:
Finance.An(0.06, 30) // => 0.1741101309106343 (Calculates present value of a lumpsum of 1 over a period of 30 years with an interest rate of 6%)

Sn

Sn(rate: number, periods: number) 

Calculates the future value for a lumpsum, based on a given number of periods and interest rate for a capital of 1.

Parameters

rate number

The decimal interest rate. 1 = 100%

periods number

The number of periods.

Return type

number

Examples

// Calculates future value of a lumpsum of 1 over a period of 30 years with an interest rate of 6%:
Finance.Sn(0.06, 30) // => 5.7434911729132585 (Calculates future value of a lumpsum of 1 over a period of 30 years with an interest rate of 6%)

annuityDuration

annuityDuration(rate: number, annuity: number) 

Calculates the duration for a given annuity and interest rate for a capital of 1.

Parameters

rate number

The decimal interest rate. 1 = 100%

annuity number

The annuity.

Return type

number

Examples

// Calculates the duration of a annuity over a period of 30 years with an annuity of 0.07264891149004721 and an interest rate of 6%:
Finance.annuityDuration(0.06, 0.07264891149004721) // => 30 (Calculates annuity over a period of 30 years with an interest rate of 6%)

effect

effect(rate: number, periods: number) 

Equivalent to the Excel function with the same name. Returns the effective annual interest rate, given the nominal annual interest rate and the number of compounding periods per year.

Parameters

rate number

The nominal interest rate.

periods number

The number of compounding periods per year.

Return type

number

Examples

// Calculates the effective rate of a nominal interest rate of 5,25% and 4 periods in a year:
Finance.effect(0.0525, 4) // => 0.0535427

nominal

nominal(rate: number, periods: number) 

Equivalent to the Excel function with the same name. Returns the nominal annual interest rate, given the effective annual interest rate and the number of compounding periods per year.

Parameters

rate number

The effective interest rate.

periods number

The number of compounding periods per year.

Return type

number

Examples

// Calculates the nominal rate of a effective interest rate of 5,35427% and 4 periods in a year:
Finance.nominal(0.0535427, 4) // => 0.0525

pv

pv(rate: number, nper: number, pmt: number, fv?: number, moment?: number, decimals?: number) 

Equivalent to the Excel function with the same name. Calculates the present value of a loan or an investment, based on a constant interest rate. You can use PV with either periodic, constant payments (such as a mortgage or other loan), or a future value that's your investment goal.

Parameters

rate number

The interest rate per period. For example, if you obtain an automobile loan at a 10 percent annual interest rate and make monthly payments, your interest rate per month is 10%/12, or 0.83%. You would enter 10%/12, or 0.83%, or 0.0083, into the formula as the rate.

nper number

The total number of payment periods in an annuity. For example, if you get a four-year car loan and make monthly payments, your loan has 4*12 (or 48) periods. You would enter 48 into the formula for nper.

pmt number

The payment made each period and cannot change over the life of the annuity. Typically, pmt includes principal and interest but no other fees or taxes. For example, the monthly payments on a $10,000, four-year car loan at 12 percent are $263.33. You would enter -263.33 into the formula as the pmt. If pmt is omitted, you must include the fv argument.

fv number

(optional) The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0). For example, if you want to save $50,000 to pay for a special project in 18 years, then $50,000 is the future value. You could then make a conservative guess at an interest rate and determine how much you must save each month. If fv is omitted, you must include the pmt argument.

moment number

(optional) The number 0 or 1 and indicates when payments are due. 0 or omitted: At the end of the period; 1: At the beginning of the period

decimals number

(optional) The number of decimals to round up to, defaults to 2.

Return type

number

Examples

// Calculates the present value needed for a payment of 100 (negative because it is a payout) over a period of 30 years with an interest rate of 6%:
Finance.pv(0.06, 30, -100) // 1.376,48 
// Calculates the present value needed to reach 50.000 after 30 years with a yearly premium and an interest rate of 6%:
Finance.pv(0.06, 30, 120, -50000, 1) // 6.954,62

fv

fv(rate: number, nper: number, pmt: number, pv?: number, moment?: number, decimals?: number) 

Equivalent to the Excel function with the same name. Calculates the future value of an investment based on a constant interest rate. You can use FV with either periodic, constant payments, or a single lump sum payment.

Parameters

rate number

The interest rate per period. For example, if you are saving at a 10 percent annual interest rate and make monthly payments, your interest rate per month is 10%/12, or 0.83%. You would enter 10%/12, or 0.83%, or 0.0083, into the formula as the rate.

nper number

The total number of payment periods in an annuity.

pmt number

The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes. If pmt is omitted, you must include the pv argument.

pv number

(optional) The present value, or the lump-sum amount that a series of future payments is worth right now. If pv is omitted, it is assumed to be 0 (zero), and you must include the pmt argument.

moment number

(optional) The number 0 or 1 and indicates when payments are due. 0 or omitted: At the end of the period; 1: At the beginning of the period

decimals number

(optional) The number of decimals to round up to, defaults to 2.

Return type

number

Examples

// Calculates the future value for a premium of 100 (positive because it is an investment) over a period of 30 years with an interest rate of 6%:
Finance.fv(0.06, 30, 100) // -7.905,82

pmt

pmt(rate: number, nper?: number, pv?: number, fv?: number, moment?: number, decimals?: number) 

Equivalent to the Excel function with the same name. Calculates the payment for a loan based on constant payments and a constant interest rate.

Parameters

rate number

The interest rate for the loan.

nper number

(optional) The total number of payment periods in the annuity.

pv number

(optional) The present value, or the total amount that a series of future payments is worth now; also known as the principal.

fv number

(optional) The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

moment number

(optional) The number 0 or 1 and indicates when payments are due. 0 or omitted: At the end of the period; 1: At the beginning of the period.

decimals number

(optional) The number of decimals to round up to, defaults to 2.

Return type

number

Examples

// Calculates the payment for a loan of 10.000 over a period of 10 months with an monthly interest rate of 8%/12:
Finance.pmt(0.08/12, 10, 10000) // -1.037.03

nper

nper(rate: number, pmt: number, pv: number, fv?: number, moment?: number, decimals?: number) 

Equivalent to the Excel function with the same name. Calculates the number of periods for a loan or investment.

Parameters

rate number

The interest rate for the loan.

pmt number

The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes. If pmt is omitted, you must include the pv argument.

pv number

The present value, or the total amount that a series of future payments is worth now; also known as the principal.

fv number

(optional) The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

moment number

(optional) The number 0 or 1 and indicates when payments are due. 0 or omitted: At the end of the period 1: At the beginning of the period.

decimals number

(optional) The number of decimals to round up to, defaults to 2.

Return type

number

Examples

// Calculates the period for a loan of 10.000 with a monthly payment of 1037.03 and an a rate of 8%/12:
Finance.nper(0.08/12, 1037.03, -10000) // 10

rate

rate(nper: number, pmt: number, pv: number, fv?: number, moment?: number, decimals?: number) 

Equivalent to the Excel function with the same name. Calculates the interest rate per period of an annuity.

Parameters

nper number

The total number of payment periods in the annuity.

pmt number

The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes. If pmt is omitted, you must include the pv argument.

pv number

The present value, or the total amount that a series of future payments is worth now; also known as the principal.

fv number

(optional) The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

moment number

(optional) The number 0 or 1 and indicates when payments are due. 0 or omitted: At the end of the period 1: At the beginning of the period.

decimals number

(optional) The number of decimals to round up to, defaults to 2.

Return type

number

Examples

// Calculates the rate for a loan of 10.000 with a monthly payment of 1037.03 and an a period of 10:
Finance.rate(10, -1037.22, 10000) * 12 // 0.08