feat: get year avg cash flow (#59)

Author: kvernon

src/ledger/ledger-collection.ts

@@ -44,6 +44,12 @@ export interface ILedgerCollection {
    */
   hasMinimumSavings(properties: IRentalPropertyEntity[], date: Date, minMonthsRequired?: number): boolean;
 
+  /**
+   * used to get the average cash flow for the year.
+   * @param date
+   */
+  getCashFlowYearAverage(date?: Date): number;
+
   getSummaryMonth(date: Date): ILedgerSummary;
 
   getSummaryAnnual(year?: number): ILedgerSummary;
@@ -161,12 +167,42 @@ export class LedgerCollection implements ILedgerCollection {
     return this.getBalance(date) >= this.getMinimumSavings(properties, date, minMonthsRequired);
   }
 
+  getAverageByType(collection: LedgerItem[], type: LedgerItemType): number {
+    return this.getSummaryByType(collection, type) / collection.filter((x) => x.typeMatches(type)).length;
+  }
+
+  /**
+   * used to get the average cash flow for the year.
+   * @param date
+   */
+  getCashFlowYearAverage(date?: Date): number {
+    if (this.isEmpty()) {
+      return 0;
+    }
+
+    if (!date) {
+      date = this.collection.last().created;
+    }
+
+    const boundary = this.filter((li) => li.dateMatchesYear(date.getUTCFullYear()));
+
+    if (boundary.length === 0) {
+      return 0;
+    }
+
+    return this.getAverageByType(boundary, LedgerItemType.CashFlow);
+  }
+
   getCashFlowMonth(date?: Date): number {
     if (this.isEmpty()) {
       return 0;
     }
 
-    const boundary = this.filter((li) => li.dateMatchesYearAndMonth(date ?? this.collection.last().created));
+    if (!date) {
+      date = this.collection.last().created;
+    }
+
+    const boundary = this.filter((li) => li.dateMatchesYearAndMonth(date));
 
     if (boundary.length === 0) {
       return 0;

tests/accounts/user.spec.ts

@@ -17,6 +17,7 @@ describe('User unit tests', () => {
       getAvailableSavings: jest.fn(),
       filter: jest.fn(),
       add: jest.fn(),
+      getCashFlowYearAverage: jest.fn(),
       getBalance: jest.fn(),
       getCashFlowMonth: jest.fn(),
       getMinimumSavings: jest.fn(),

tests/ledger/ledger-collection.spec.ts

@@ -236,6 +236,82 @@ describe('LedgerCollection unit tests', () => {
       });
     });
   });
+  describe('and getCashFlowYearAverage', () => {
+    describe('and no date', () => {
+      test('should return 0', () => {
+        expect(instance.getCashFlowYearAverage(null)).toEqual(0);
+      });
+    });
+    describe('and no ledgerItem', () => {
+      test('should return empty data', () => {
+        expect(instance.getCashFlowYearAverage(dateUtc)).toEqual(0);
+      });
+    });
+    describe('and ledgerItems', () => {
+      describe('with matches', () => {
+        let createdDate: Date;
+        let cashFlow: LedgerItem;
+        let cashFlowTwo: LedgerItem;
+
+        beforeEach(() => {
+          createdDate = new Date(Date.UTC(dateUtc.getUTCFullYear() + 1, dateUtc.getUTCMonth(), 1));
+
+          cashFlow = new LedgerItem();
+          cashFlow.created = createdDate;
+          cashFlow.amount = 1;
+          cashFlow.type = LedgerItemType.CashFlow;
+
+          cashFlowTwo = new LedgerItem();
+          cashFlowTwo.created = createdDate;
+          cashFlowTwo.amount = 3;
+          cashFlowTwo.type = LedgerItemType.CashFlow;
+
+          const cashFlowOut = new LedgerItem();
+          cashFlowOut.created = new Date(Date.UTC(dateUtc.getUTCFullYear(), dateUtc.getUTCMonth(), 1));
+          cashFlowOut.created.setUTCMonth(cashFlowOut.created.getUTCMonth() + 2);
+          cashFlowOut.amount = 111111;
+          cashFlowOut.type = LedgerItemType.CashFlow;
+
+          const equity = new LedgerItem();
+          equity.created = createdDate;
+          equity.amount = 2;
+          equity.type = LedgerItemType.Equity;
+
+          const purchase = new LedgerItem();
+          purchase.created = createdDate;
+          purchase.amount = -3;
+          purchase.type = LedgerItemType.Purchase;
+
+          const salary = new LedgerItem();
+          salary.created = createdDate;
+          salary.amount = 4;
+          salary.type = LedgerItemType.Salary;
+
+          instance.add([cashFlow, cashFlowTwo, cashFlowOut, equity, purchase, salary]);
+        });
+
+        describe('with date', () => {
+          test('should return average result', () => {
+            expect(instance.getCashFlowYearAverage()).toEqual((cashFlow.amount + cashFlowTwo.amount) / 2);
+          });
+        });
+      });
+
+      test('and no matching dates', () => {
+        const createdDate = new Date(Date.UTC(dateUtc.getUTCFullYear() + 1, dateUtc.getUTCMonth(), 1));
+
+        const cashFlowOut = new LedgerItem();
+        cashFlowOut.created = new Date(Date.UTC(dateUtc.getUTCFullYear(), dateUtc.getUTCMonth(), 1));
+        cashFlowOut.created.setUTCMonth(cashFlowOut.created.getUTCMonth() + 2);
+        cashFlowOut.amount = 111111;
+        cashFlowOut.type = LedgerItemType.CashFlow;
+
+        instance.add([cashFlowOut]);
+
+        expect(instance.getCashFlowYearAverage(createdDate)).toEqual(0);
+      });
+    });
+  });
   describe('and getSummariesAnnual', () => {
     describe('and no date', () => {
       test('should throw error', () => {

tests/time/looper.spec.ts

@@ -59,6 +59,7 @@ describe('looper unit tests', () => {
     user = {
       ledgerCollection: {
         add: jest.fn(),
+        getCashFlowYearAverage: jest.fn(),
         getBalance: jest.fn(),
         getMinimumSavings: jest.fn(),
         clone: jest.fn().mockReturnThis(),