AmortizationCalculation

Overview

This module details an amortization calculation system that defines constants for various periodic intervals and events, as well as methods for managing loans, payments, rate changes, and schedule calculations. ## Constants

The module includes constants representing various time periods, such as annual, bi-annual, monthly, and weekly intervals, as well as unique identifiers like NUMBER_UNLIMITED for unlimited occurrences and STARTDAY_NORMAL for consistent start-day tracking. These constants simplify configuring amortization schedules with precise periodicity and event behaviors.

Methods

Key methods facilitate:

• Loan and Payment Management: Functions like addLoan and addPayment support different configurations, including start and end dates, periodic intervals, and repetitions.

• Rate Changes and Period Adjustments: addRateChange and addCompoundPeriodChange enable dynamic updates to interest rates and compounding periods.

• Amortization Schedule Handling: Methods like calculateAmortizationSchedule and getAmortizationSchedule compute and retrieve detailed schedules, while getRestBalance and solveForUnknown provide insights into financial balances and unknown variables.

Features

• Utilities like isValidPeriod and roundMoney ensure input validity and precision.

• Event management and sorting (sortEvents, getEvents) organize financial activities over time.

This module streamlines the creation and management of customized amortization schedules with precision and adaptability.

Constants Summarized

Type	Name	Summary
Number	NUMBER_UNLIMITED	The numeric constant used to identify an unlimited number of repeated events.
Number	PERIOD_ANNUALY	The numeric constant used to identify an annual period.
Number	PERIOD_BI_ANNUALLY	The numeric constant used to identify a bi-annual period (twice every year).
Number	PERIOD_BI_MONTHLY	The numeric constant used to identify a bi-monthly period (twice every month).
Number	PERIOD_DAILY	The numeric constant used to identify a daily period.
Number	PERIOD_FOUR_MONTHLY	The numeric constant used to identify a four-monthly period (once every four months).
Number	PERIOD_FOUR_WEEKLY	The numeric constant used to identify a four-weekly period (once every four weeks).
Number	PERIOD_MONTHLY	The numeric constant used to identify a monthly period.
Number	PERIOD_NONE	The numeric constant used to identify that there is no period.
Number	PERIOD_QUARTERLY	The numeric constant used to identify a quarterly period (once every three months).
Number	PERIOD_TWO_MONTHLY	The numeric constant used to identify a two-monthly period (once every two months).
Number	PERIOD_TWO_WEEKLY	The numeric constant used to identify a two-weekly period (once every two weeks).
Number	PERIOD_WEEKLY	The numeric constant used to identify a weekly period.
Number	STARTDAY_NORMAL	The numeric constant used to identify that the same start day should be used as the day of the month of the starting date of the event.

Methods Summarized

Type	Name	Summary
Boolean	addCompoundPeriodChange(newPeriod, date)	Adds a compound period change.
Boolean	addLoan(amount, date)	Adds a loan.
Boolean	addLoan(amount, firstDate, lastDate, period)	Adds a loan.
Boolean	addLoan(amount, firstDate, lastDate, period, number)	Adds a loan.
Boolean	addLoan(amount, firstDate, lastDate, period, number, startday)	Adds a loan.
Boolean	addPayment(amount, date)	Adds a payment.
Boolean	addPayment(amount, firstDate, lastDate, period)	Adds a payment.
Boolean	addPayment(amount, firstDate, lastDate, period, number)	Adds a payment.
Boolean	addPayment(amount, firstDate, lastDate, period, number, startday)	Adds a payment.
Boolean	addRateChange(newRate, date)	Sets a new interest rate.
Boolean	calculateAmortizationSchedule()	Calculates the amortization schedule.
JSDataSet	getAmortizationSchedule()	Gets the amortization schedule as a JSDataSet.
Number	getError()	Returns the error that remains when solving for the unknown.
JSDataSet	getEvents()	Returns all the amortization events - such as rate changes, loan events, payment events, compounding period changes.
Number	getRestBalance()	Gets the rest balance after the amortization schedule.
Number	getUnknown()	Returns the solveForUnknown value.
Boolean	isValidPeriod(period)	Returns true if the period is valid, or false if the period is not valid.
Number	roundMoney(amount)	Rounds a number up to the nearest cents.
Boolean	solveForUnknown()	Returns true if successful or false if the call failed.
void	sortEvents()	Sorts the amortization events ascending by date.

Constants Detailed

NUMBER_UNLIMITED

The numeric constant used to identify an unlimited number of repeated events.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_ANNUALY

The numeric constant used to identify an annual period.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_BI_ANNUALLY

The numeric constant used to identify a bi-annual period (twice every year).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_BI_MONTHLY

The numeric constant used to identify a bi-monthly period (twice every month). TODO: this period is not supported yet.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_DAILY

The numeric constant used to identify a daily period.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_FOUR_MONTHLY

The numeric constant used to identify a four-monthly period (once every four months).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_FOUR_WEEKLY

The numeric constant used to identify a four-weekly period (once every four weeks).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_MONTHLY

The numeric constant used to identify a monthly period.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_NONE

The numeric constant used to identify that there is no period.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_QUARTERLY

The numeric constant used to identify a quarterly period (once every three months).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_TWO_MONTHLY

The numeric constant used to identify a two-monthly period (once every two months).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_TWO_WEEKLY

The numeric constant used to identify a two-weekly period (once every two weeks).

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

PERIOD_WEEKLY

The numeric constant used to identify a weekly period.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

STARTDAY_NORMAL

The numeric constant used to identify that the same start day should be used as the day of the month of the starting date of the event.

Type Number

Sample

var c = plugins.amortization.newCalculation();
c.addPayment(500, new Date(2005, 1, 28), null,
			plugins.amortization.AmortizationCalculation.PERIOD_DAILY, 5,
			plugins.amortization.AmortizationCalculation.STARTDAY_NORMAL);

var c2 = plugins.amortization.newCalculation();
c2.addPayment(300, new Date(2006, 11, 24), new Date(2006, 12, 24),
			plugins.amortization.AmortizationCalculation.PERIOD_BI_MONTHLY,
			plugins.amortization.AmortizationCalculation.NUMBER_UNLIMITED, 30);

Methods Detailed

addCompoundPeriodChange(newPeriod, date)

Adds a compound period change.

Parameters

• Number newPeriod ;

• Date date ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addLoan(amount, date)

Adds a loan.

Parameters

• Number amount ;

• Date date ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addLoan(amount, firstDate, lastDate, period)

Adds a loan.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addLoan(amount, firstDate, lastDate, period, number)

Adds a loan.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

• Number number ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addLoan(amount, firstDate, lastDate, period, number, startday)

Adds a loan.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

• Number number ;

• Number startday ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addPayment(amount, date)

Adds a payment.

Parameters

• Number amount ;

• Date date ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addPayment(amount, firstDate, lastDate, period)

Adds a payment.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addPayment(amount, firstDate, lastDate, period, number)

Adds a payment.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

• Number number ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addPayment(amount, firstDate, lastDate, period, number, startday)

Adds a payment.

Parameters

• Number amount ;

• Date firstDate ;

• Date lastDate ;

• Number period ;

• Number number ;

• Number startday ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

addRateChange(newRate, date)

Sets a new interest rate.

Parameters

• Number newRate ;

• Date date ;

Returns: Boolean

Sample

var c = plugins.amortization.newCalculation();
c.addRateChange(r, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
c.addPayment(500, new Date(2005, 1, 28), null, 12, 5, 31);

calculateAmortizationSchedule()

Calculates the amortization schedule.

Returns: Boolean

Sample

plugins.amortization.calculateAmortizationSchedule();

getAmortizationSchedule()

Gets the amortization schedule as a JSDataSet.

Returns: JSDataSet

Sample

plugins.amortization.getAmortizationSchedule();

getError()

Returns the error that remains when solving for the unknown. Please note that the error should be less or equal to 1E-8 - otherwise, the solveForUnknown value is incorrect.

Returns: Number

Sample

var c = plugins.amortization.newCalculation();
// sets the rate to -1 for unknown.
c.addRateChange(-1, new Date(2005, 0, 1));
c.addCompoundPeriodChange(12, new Date(2005, 0, 1));
c.addLoan(2000, new Date(2005, 0, 1));
var lastDate = null;
var period = 12;
var number_count = 5;
var startday = 31;
c.addPayment(500, new Date(2005, 1, 28), lastDate, period,number_count, startday);
// solves for the interest rate.
c.solveForUnknown();
// gets the interest rate and the error in the calculation.
// which should be small (otherwise the calculation did
// not converge for some reason.
var r = c.getUnknown();
var e = c.getError();

getEvents()

Returns all the amortization events - such as rate changes, loan events, payment events, compounding period changes.

Returns: JSDataSet

Sample

plugins.amortization.getEvents();

getRestBalance()

Gets the rest balance after the amortization schedule.

Returns: Number

Sample

var rb = plugins.amortization.getRestBalance();

getUnknown()

Returns the solveForUnknown value.

Returns: Number

Sample

plugins.amortization.getUnknown();

isValidPeriod(period)

Returns true if the period is valid, or false if the period is not valid.

Parameters

• Number period ;

Returns: Boolean

Sample

var v_period = plugins.amortization.isValidPeriod(12);

roundMoney(amount)

Rounds a number up to the nearest cents.

Parameters

• Number amount ;

Returns: Number

Sample

//rounds the number up to 34.35
var rm = plugins.amortization.roundMoney(34.349384);

solveForUnknown()

Returns true if successful or false if the call failed.

Returns: Boolean

Sample

plugins.amortization.solveForUnknown();

sortEvents()

Sorts the amortization events ascending by date.

Returns: void

Sample

plugins.amortization.sortEvents();

---