installment-plan

Installment and disbursement plan calculator for JavaScript/Node.js.

This package provides 3 main functions:

• CalculateInstallmentPlan: build an installment schedule from a single principal amount
• CalculateInstallmentPlan_DE: convenience wrapper for a default date setup
• CalculateDisbursementPlan: build a schedule from multiple disbursements

Install

npm install installment-plan

Runtime Notes

• This package is published as ESM ("type": "module")
• Use import syntax in Node.js or bundlers that support ESM

Quick Start

import {
  CalculateInstallmentPlan,
  CalculateInstallmentPlan_DE,
  CalculateDisbursementPlan,
} from "installment-plan";

API

1) CalculateInstallmentPlan

CalculateInstallmentPlan(
  DISBURSEMENTDATE,
  PAYMENTFIRSTDATE,
  PAYMENTDUEDAY,
  Principal,
  PaymentAmount,
  TopupAmt = 0,
  TopupStart = 1,
  countInstallment = 0,
)

Parameters:

• DISBURSEMENTDATE (Date): disbursement date
• PAYMENTFIRSTDATE (Date): first payment date
• PAYMENTDUEDAY (number): due day of month (for following installments)
• Principal (number): initial principal
• PaymentAmount (Array<{ from, to, installment, IntRate }>): tiered payment/rate rules
• TopupAmt (number, optional): top-up added to payment amount
• TopupStart (number, optional): installment index where top-up starts (1-based)
• countInstallment (number, optional): internal/advanced usage

Returns:

• Array<object> schedule rows, or
• Array<string> with an error message when date constraints are invalid

Date constraints:

• returns an error if days from disbursement date to first payment date is >= 45
• returns an error if that day difference is < 0

Example:

import { CalculateInstallmentPlan } from "installment-plan";

const DISBURSEMENTDATE = new Date(2023, 9, 25);
const PAYMENTFIRSTDATE = new Date(2023, 10, 24);
const PAYMENTDUEDAY = 24;
const Principal = 500000;

const PaymentAmount = [
  { from: 1, to: 12, installment: 2300, IntRate: 0.0239 },
  { from: 13, to: 24, installment: 2300, IntRate: 0.0414 },
  { from: 25, to: 36, installment: 2300, IntRate: 0.0414 },
  { from: 37, to: 120, installment: 2300, IntRate: 0.0594 },
];

const plan = CalculateInstallmentPlan(
  DISBURSEMENTDATE,
  PAYMENTFIRSTDATE,
  PAYMENTDUEDAY,
  Principal,
  PaymentAmount,
);

console.log(plan[0]);

2) CalculateInstallmentPlan_DE

CalculateInstallmentPlan_DE(Principal, PaymentAmount)

Parameters:

• Principal (number)
• PaymentAmount (Array<{ from, to, installment, IntRate }>)

Behavior:

• Uses current month dates internally:
  • disbursement date = first day of current month
  • first payment date = last day of current month
  • payment due day = 25

Returns:

• same output shape as CalculateInstallmentPlan

Example:

import { CalculateInstallmentPlan_DE } from "installment-plan";

const plan = CalculateInstallmentPlan_DE(100000, [
  { from: 1, to: 12, installment: 9000, IntRate: 0.08 },
]);

console.log(plan.length);

3) CalculateDisbursementPlan

CalculateDisbursementPlan(DISB, PA, PAYMENTFIRSTDATE, PAYMENTDUEDAY)

Parameters:

• DISB (Array<{ date: Date, amount: number }>): disbursements
• PA (Array<{ from, to, installment, IntRate }>): payment/rate tiers
• PAYMENTFIRSTDATE (Date)
• PAYMENTDUEDAY (number)

Behavior:

• Groups disbursements by date
• Calculates first installment interest per disbursement, then continues schedule via installment logic

Returns:

• Array<object> schedule rows, or
• Array<string> with an error message for invalid day-difference constraints

Example:

import { CalculateDisbursementPlan } from "installment-plan";

const PAYMENTFIRSTDATE = new Date(2025, 4, 6);
const PAYMENTDUEDAY = 6;

const PA = [
  { from: 1, to: 3, installment: 11040, IntRate: 0.0888 },
  { from: 3, to: 60, installment: 11040, IntRate: 0.1199 },
];

const DISB = [
  { date: new Date(2025, 3, 25), amount: 230000 },
  { date: new Date(2025, 3, 25), amount: 160000 },
  { date: new Date(2025, 3, 28), amount: 100000 },
  { date: new Date(2025, 3, 28), amount: 10000 },
];

const plan = CalculateDisbursementPlan(
  DISB,
  PA,
  PAYMENTFIRSTDATE,
  PAYMENTDUEDAY,
);

console.log(plan[0]);

Output Fields

Each row in the resulting schedule contains:

• c: installment number
• prevmonthpaymentdate: previous payment date (string | null)
• thismonthpaymentdate: current payment date (string)
• DD: day difference used in interest calculation
• PA: payment amount
• IDA: interest due amount
• DP: deducted principal
• DI: deducted interests
• RP: remaining principal
• AI: accrued interest
• AILP: accrued interest from last payment
• ITP: interest this payment

Development

Install dependencies:

npm install

Run tests:

npm test

Run coverage:

npm run cv

License

MIT