moneyfunx 0.0.2

package/.circleci/config.yml

@@ -0,0 +1,24 @@
+# This config is equivalent to both the ".circleci/extended/orb-free.yml" and the base ".circleci/config.yml"
+version: 2.1
+
+# Orbs are reusable packages of CircleCI configuration that you may share across projects, enabling you to create encapsulated, parameterized commands, jobs, and executors that can be used across multiple projects.
+# See: https://circleci.com/docs/2.0/orb-intro/
+orbs:
+  node: circleci/node@4.7
+
+# Invoke jobs via workflows
+# See: https://circleci.com/docs/2.0/configuration-reference/#workflows
+workflows:
+  test_lib: # This is the name of the workflow, feel free to change it to better match your workflow.
+    # Inside the workflow, you define the jobs you want to run.
+    jobs:
+      - node/test:
+          # This is the node version to use for the `cimg/node` tag
+          # Relevant tags can be found on the CircleCI Developer Hub
+          # https://circleci.com/developer/images/image/cimg/node
+          version: "17.5"
+          # If you are using yarn, change the line below from "npm" to "yarn"
+          pkg-manager: npm
+          filters:
+            tags:
+              only: /d+/.\d+/.\d+/

package/.eslintignore

@@ -0,0 +1 @@
+**/scratch.js

package/.eslintrc.json

@@ -0,0 +1,35 @@
+{
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:vue/essential"
+    ],
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "plugins": [
+        "vue"
+    ],
+    "rules": {
+        "indent": [
+            "error",
+            4
+        ],
+        "linebreak-style": [
+            "error",
+            "unix"
+        ],
+        "quotes": [
+            "error",
+            "double"
+        ],
+        "semi": [
+            "error",
+            "always"
+        ]
+    }
+}

package/.github/workflows/release-package.yml

@@ -0,0 +1,23 @@
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+
+  publish-gpr:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 17
+          registry-url: https://npm.pkg.github.com/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Kyle Pekosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# MoneyFunx
+[![CircleCI](https://circleci.com/gh/Kylep342/moneyfunx/tree/main.svg?style=svg)](https://circleci.com/gh/Kylep342/moneyfunx/tree/main)
+
+MoneyFunx is a small library of functions for financial computations, with a focus on personal finance
+
+## TODO
+- Fix interest calculation/accrual for the `lifetimeInterest` attribute from the `payLoans` function
+- Add tests
+- Figure out how imports/exports work in JavaScript

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "moneyfunx",
+  "type": "module",
+  "version": "0.0.2",
+  "description": "MoneyFunx is a small library of functions for financial computations, with a focus on personal finance",
+  "main": "index.js",
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "lint": "eslint"
+  },
+  "author": "Kyle Pekosh",
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^8.11.0",
+    "eslint-plugin-vue": "^8.5.0",
+    "jest": "^27.5.1"
+  },
+  "publishConfig": {
+   "@Kylep342:registry": "https://npm.pkg.github.com"
+ }
+}

package/src/lib/loan.js

@@ -0,0 +1,122 @@
+/*
+
+*****************
+*** MoneyFunx ***
+*****************
+
+mek it funx up
+
+This library contains functions used to in personal financial analysis
+
+*/
+
+export function calculateMinPayment (principal, periodicRate, periods) {
+    return periodicRate > 0 ?
+        principal * (
+            (
+                periodicRate * (1 + periodicRate) ** periods
+            ) / (
+                (1 + periodicRate) ** periods - 1
+            )
+        ) :
+        principal / periods;
+}
+
+export function principalRemaining (principal, payment, periodicRate, periods) {
+    return Math.max(
+        (principal * (1 + periodicRate) ** periods) - (
+            payment * (
+                ((1 + periodicRate) ** periods - 1) / (periodicRate)
+            )
+        ),
+        0
+    );
+}
+
+export function numPaymentsToZero (principal, payment, periodicRate) {
+    return Math.ceil(
+        Math.log(
+            (payment / (payment - principal * periodicRate))
+        ) / Math.log(periodicRate + 1)
+    );
+}
+
+//
+export class Loan {
+    constructor (principal, annualRate, periodsPerYear, termInYears) {
+        this.id = String(Math.floor(Math.random() * Date.now()));
+        this.principal = principal;
+        this.annualRate = annualRate;
+        this.periodsPerYear = periodsPerYear;
+        this.termInYears = termInYears;
+        this.periodicRate = this.annualRate / this.periodsPerYear;
+        this.periods = this.periodsPerYear * this.termInYears;
+        this.minPayment = this.calculateMinPayment();
+        this.totalInterest = (this.minPayment * (this.periods)) - this.principal;
+    }
+
+    validatePayment(payment=this.minPayment) {
+        if (payment < this.minPayment) {
+            throw `payment of ${payment} cannot be less than ${this.minPayment}`;
+        } else {
+            return payment;
+        }
+    }
+
+    calculateMinPayment() {
+        return calculateMinPayment(this.principal, this.periodicRate, this.periods);
+    }
+
+    accrueInterest(balance=this.principal) {
+        // TODO: figure out if this is valid
+        // UPDATE: 24-3-2022 this is valid AF
+        return balance * this.periodicRate;
+    }
+
+    numPaymentsToZero(payment=this.minPayment, balance=this.principal) {
+        payment = this.validatePayment(payment);
+        return numPaymentsToZero(
+            balance,
+            payment,
+            this.periodicRate
+        );
+    }
+
+    principalRemaining(periods, payment=this.minPayment, balance=this.principal) {
+        payment = this.validatePayment(payment);
+        return periods < this.numPaymentsToZero(payment, balance) ?
+            principalRemaining(
+                balance,
+                payment,
+                this.periodicRate,
+                periods
+            ) :
+            0;
+    }
+
+    interestPaid(periods, payment=this.minPayment, balance=this.principal) {
+        // TODO: Fix this
+        // 18-3-2022: Need to compute interest for the final payment and add it to the ternary
+        payment = this.validatePayment(payment);
+        return periods < this.numPaymentsToZero(payment, balance) ?
+            (payment * periods) - (balance - this.principalRemaining(periods, payment, balance)) :
+            Math.max(
+                payment * (this.numPaymentsToZero(payment, balance) - 1) - (
+                    balance - this.principalRemaining(
+                        this.numPaymentsToZero(payment) - 1,
+                        payment,
+                        balance
+                    )
+                ) + (
+                    this.accrueInterest(
+                        this.principalRemaining(
+                            this.numPaymentsToZero(payment) - 1,
+                            payment,
+                            balance
+                        )
+                    )
+                ),
+                0
+            );
+    }
+}

package/src/lib/payments.js

@@ -0,0 +1,107 @@
+/*
+
+*/
+import * as loanLib from "./loan.js";
+
+//
+export function determineExtraPayment (loans, payment) {
+    const totalMinPayment = loans.reduce(
+        (previousValue, currentValue) => previousValue + currentValue.minPayment,
+        0
+    );
+    if (totalMinPayment > payment) {
+        throw `Payment amount of ${payment} must be greater than ${totalMinPayment}`;
+    }
+    return payment - totalMinPayment;
+}
+
+//
+export function amortizePayments (loan, payment, numPayments, startPeriod) {
+    payment = loan.validatePayment(payment);
+    let amortizationSchedule = [];
+    for (
+        let period=0;
+        period<numPayments;
+        period++
+    ) {
+        let interestThisPeriod = loan.accrueInterest(
+            loan.principalRemaining(
+                period,
+                payment,
+                loan.principalRemaining(startPeriod)
+            )
+        );
+        let principalThisPeriod = Math.min(
+            payment - interestThisPeriod,
+            loan.principalRemaining(
+                period,
+                payment,
+                loan.principalRemaining(startPeriod)
+            )
+        );
+        amortizationSchedule.push(
+            {
+                period: startPeriod + period + 1,
+                principal: principalThisPeriod,
+                interest: interestThisPeriod,
+                principalRemaining: loan.principalRemaining(
+                    period + 1,
+                    payment,
+                    loan.principalRemaining(startPeriod)
+                )
+            }
+        );
+    }
+    return amortizationSchedule;
+}
+
+//
+export function payLoans (loans, payment) {
+    let loanInterestTotals = {};
+    loans.map(
+        (loan) => {
+            loanInterestTotals[loan.id] = {lifetimeInterest: 0, amortizationSchedule: []};
+        }
+    );
+
+    let periodsElapsed = 0;
+    let paidLoans = 0;
+
+    while (paidLoans < loans.length) {
+        let extraPaymentAmount = determineExtraPayment(loans.slice(paidLoans), payment);
+        let firstLoan = loans.slice(paidLoans)[0];
+        let firstLoanPayment = firstLoan.minPayment + extraPaymentAmount;
+        let periodsToPay = loanLib.numPaymentsToZero(
+            firstLoan.principalRemaining(
+                periodsElapsed,
+                firstLoan.minPayment
+            ),
+            firstLoanPayment,
+            firstLoan.periodicRate
+        );
+        let firstLoanInterestPaid = firstLoan.interestPaid(
+            periodsToPay,
+            firstLoanPayment,
+            firstLoan.principalRemaining(periodsElapsed)
+        );
+        loanInterestTotals[firstLoan.id].lifetimeInterest += firstLoanInterestPaid;
+        loanInterestTotals[firstLoan.id].amortizationSchedule = [
+            ...loanInterestTotals[firstLoan.id].amortizationSchedule,
+            ...amortizePayments(firstLoan, firstLoanPayment, periodsToPay, periodsElapsed)
+        ];
+        paidLoans += 1;
+        loans.slice(paidLoans).map((loan) => {
+            loanInterestTotals[loan.id].lifetimeInterest += loan.interestPaid(
+                periodsToPay,
+                loan.minPayment,
+                loan.principalRemaining(periodsElapsed)
+            );
+            loanInterestTotals[loan.id].amortizationSchedule = [
+                ...loanInterestTotals[loan.id].amortizationSchedule,
+                ...amortizePayments(loan, loan.minPayment, periodsToPay, periodsElapsed)
+            ];
+        });
+        periodsElapsed += periodsToPay;
+    }
+    return loanInterestTotals;
+}

package/src/lib/sorting.js

@@ -0,0 +1,26 @@
+/*
+
+NOTE: When sorting by avalanche, sort by snowball first for optimal interest minimization
+
+*/
+
+/*
+Sorts loans descending by interest rate
+*/
+export function snowball(loan1, loan2) {
+    return loan2.annualRate - loan1.annualRate;
+}
+
+/*
+Sorts loans ascending by principal
+*/
+export function avalanche(loan1, loan2) {
+    return loan1.principal - loan2.principal;
+}
+
+/*
+Sorts an array of loans using the provided sortFunc
+*/
+export function sortLoans(loans, sortFunc) {
+    return loans.sort(sortFunc);
+}

package/tests/loan.test.js

@@ -0,0 +1,35 @@
+import { test, expect } from "@jest/globals";
+import * as loan from "../src/lib/loan.js";
+
+test(
+    "Loan with principal=7500, interest=0.068, periods/year=12, years=10 has proper attributes",
+    () => {
+        const loan1 = new loan.Loan(7500, 0.068, 12, 10);
+
+        expect(loan1.periodicRate).toBe(0.005666666666666667);
+        expect(loan1.periods).toBe(120);
+        expect(loan1.minPayment).toBe(86.31024763658397);
+        expect(loan1.totalInterest).toBe(2857.2297163900766);
+
+        expect(loan1.numPaymentsToZero()).toBe(120);
+        expect(loan1.numPaymentsToZero(300)).toBe(28);
+        expect(() => {loan1.numPaymentsToZero(30);}).toThrow("payment of 30 cannot be less than 86.31024763658397");
+
+        expect(loan1.validatePayment(100)).toBe(100);
+        expect(loan1.validatePayment()).toBe(86.31024763658397);
+        expect(() => {loan1.validatePayment(20);}).toThrow("payment of 20 cannot be less than 86.31024763658397");
+        expect(() => {loan1.validatePayment(-160);}).toThrow("payment of -160 cannot be less than 86.31024763658397");
+
+        expect(loan1.principalRemaining(33)).toBe(5915.168870573016);
+        expect(loan1.principalRemaining(0)).toBe(7500);
+        expect(loan1.principalRemaining(40, 500)).toBe(0);
+        expect(loan1.principalRemaining(3, 200, 3000)).toBe(2447.8831236666597);
+        expect(() => {loan1.principalRemaining(21, 40, 9000);}).toThrow("payment of 40 cannot be less than 86.31024763658397");
+
+        expect(loan1.interestPaid(0)).toBe(0);
+        expect(loan1.interestPaid(22)).toBe(875.4263974363766);
+        expect(loan1.interestPaid(50, 300)).toBe(610.3609925683494);
+        expect(loan1.interestPaid(120)).toBe(loan1.totalInterest);
+        expect(() => {loan1.interestPaid(30, 10, 20000);}).toThrow("payment of 10 cannot be less than 86.31024763658397");
+    }
+);

package/tests/payments.test.js

@@ -0,0 +1,37 @@
+import { expect, test } from "@jest/globals";
+import * as loan from "../src/lib/loan.js";
+import * as sorting from "../src/lib/sorting.js";
+import * as payments from "../src/lib/payments.js";
+
+
+test(
+    "Payments are good",
+    () => {
+        const loan1 = new loan.Loan(7500, .068, 12, 10);
+        const loan2 = new loan.Loan(7500, .0368, 12, 10);
+        const loan3 = new loan.Loan(4500, .0429, 12, 10);
+
+        const loans = sorting.sortLoans(
+            [loan2, loan3, loan1],
+            sorting.snowball
+        );
+
+        const loan2AmortizationSchedule = payments.amortizePayments(loan2, loan2.minPayment, 120, 0);
+
+        expect(loan2AmortizationSchedule.length).toBe(120);
+        expect(loan2AmortizationSchedule[3].period).toBe(4);
+        expect(loan2AmortizationSchedule[3].principal).toBe(52.27646756701894);
+        expect(loan2AmortizationSchedule[3].interest).toBe(22.5219912775614);
+        expect(loan2AmortizationSchedule[3].principalRemaining).toBe(7291.851122942134);
+
+        expect(payments.determineExtraPayment(loans, 400)).toBe(192.70819668183697);
+        expect(() => {payments.determineExtraPayment(loans, 0);}).toThrow("Payment amount of 0 must be greater than 207.29180331816303");
+
+        const loanPaymentTotals1 = payments.payLoans(loans, 400);
+
+        expect(Object.keys(loanPaymentTotals1).length).toBe(3);
+        expect(loanPaymentTotals1[loan1.id].lifetimeInterest).toBe(659.9318259100721);
+        expect(loanPaymentTotals1[loan2.id].lifetimeInterest).toBe(841.5352714723776);
+        expect(loanPaymentTotals1[loan3.id].lifetimeInterest).toBe(462.70985781957734);
+    }
+);

package/tests/sorting.test.js

@@ -0,0 +1,42 @@
+import { expect, test } from "@jest/globals";
+import * as loan from "../src/lib/loan.js";
+import * as sorting from "../src/lib/sorting.js";
+
+test(
+    "Loans sort well",
+    () => {
+        const loan1 = new loan.Loan(7500, .068, 12, 10);
+        const loan2 = new loan.Loan(7500, .0368, 12, 10);
+        const loan3 = new loan.Loan(4500, .0429, 12, 10);
+
+        const loans = [loan2, loan3, loan1];
+
+        expect(sorting.snowball(loan1, loan2)).toBe(-0.031200000000000006);
+        expect(sorting.snowball(loan3, loan2)).toBe(-0.006100000000000001);
+
+        expect(sorting.avalanche(loan1, loan3)).toBe(3000);
+        expect(sorting.avalanche(loan1, loan2)).toBe(0);
+
+        expect(
+            sorting.sortLoans(
+                loans,
+                sorting.snowball
+            )
+        ).toStrictEqual([loan1, loan3, loan2]);
+        expect(
+            sorting.sortLoans(
+                loans,
+                sorting.avalanche
+            )
+        ).toStrictEqual([loan3, loan1, loan2]);
+        expect(
+            sorting.sortLoans(
+                sorting.sortLoans(
+                    loans,
+                    sorting.snowball
+                ),
+                sorting.avalanche
+            )
+        ).toStrictEqual([loan3, loan1, loan2]);
+    }
+);