@cubedelement.com/realty-investor-timeline 5.5.1 → 5.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.6.0](https://github.com/kvernon/realty-investor-timeline/compare/v5.5.1...v5.6.0) (2026-01-13)
+
+
+### Features
+
+* quarterly cash flow ([#74](https://github.com/kvernon/realty-investor-timeline/issues/74)) ([8700a3c](https://github.com/kvernon/realty-investor-timeline/commit/8700a3c889d865cc6f31a61c4a230b046606602c))
+
 ## [5.5.1](https://github.com/kvernon/realty-investor-timeline/compare/v5.5.0...v5.5.1) (2026-01-02)
 
 

package/dist/src/account/i-user-goal.d.ts

@@ -8,4 +8,9 @@ export interface IUserGoal {
      * @param today
      */
     metMonthlyGoal(today: Date): boolean;
+    /**
+     * takes data from a quarterly average cash flow and compares it to the monthly goal. The reason on quarterly is that apartments do distributions quarterly, so you have to spread those out monthly
+     * @param today
+     */
+    metAverageQuarterlyGoal(today: Date): boolean;
 }

package/dist/src/account/user.d.ts

@@ -14,10 +14,15 @@ export interface IUser extends IUserInvestorCheck {
      */
     monthlySavedAmount: number;
     /**
-     * method used to help determine if you have met your expenses
+     * returns your passive income for the year + month date supplied
      * @param today
      */
     getCashFlowMonth(today: Date): number;
+    /**
+     * returns the cash flow by a quarter. This is ideal when evaluating your distributions that are not monthly.
+     * @param today
+     */
+    getCashFlowQuarter(today: Date): number;
     clone(): IUser;
 }
 export declare class User implements IUser {
@@ -38,6 +43,20 @@ export declare class User implements IUser {
      * @param today
      */
     metMonthlyGoal(today: Date): boolean;
+    /**
+     * takes data from a quarterly average cash flow and compares it to the monthly goal. The reason on quarterly is that apartments do distributions quarterly, so you have to spread those out monthly
+     * @param today
+     */
+    metAverageQuarterlyGoal(today: Date): boolean;
+    /**
+     * returns the cash flow by a quarter. This is ideal when evaluating your distributions that are not monthly.
+     * @param today
+     */
+    getCashFlowQuarter(today: Date): number;
+    /**
+     * returns your passive income for the year + month date supplied
+     * @param today
+     */
     getCashFlowMonth(today: Date): number;
     /**
      * an amount which the user can save per month after expenses, like, after my pay check I could put this amount into savings

package/dist/src/account/user.js

@@ -28,6 +28,27 @@ class User {
     metMonthlyGoal(today) {
         return this.getCashFlowMonth(today) >= this.monthlyIncomeAmountGoal;
     }
+    /**
+     * takes data from a quarterly average cash flow and compares it to the monthly goal. The reason on quarterly is that apartments do distributions quarterly, so you have to spread those out monthly
+     * @param today
+     */
+    metAverageQuarterlyGoal(today) {
+        return this.getCashFlowQuarter(today) >= this.monthlyIncomeAmountGoal;
+    }
+    /**
+     * returns the cash flow by a quarter. This is ideal when evaluating your distributions that are not monthly.
+     * @param today
+     */
+    getCashFlowQuarter(today) {
+        if (!this.ledgerCollection) {
+            return 0;
+        }
+        return (0, currency_1.default)(this.ledgerCollection.getAverageCashFlowMonthByQuarter(today));
+    }
+    /**
+     * returns your passive income for the year + month date supplied
+     * @param today
+     */
     getCashFlowMonth(today) {
         if (!this.ledgerCollection) {
             return 0;

package/dist/src/ledger/ledger-collection.d.ts

@@ -11,6 +11,8 @@ export interface ILedgerCollection {
     filter(pred?: LedgerItemPredicate): LedgerItem[];
     add(item: LedgerItem | Iterable<LedgerItem>): void;
     getCashFlowMonth(date?: Date): number;
+    getAverageCashFlowMonthByQuarter(date?: Date): number;
+    getCashFlowQuarter(date?: Date): number;
     /**
      * This method gets the total of savings needed for all properties by x amount of months.
      * @example
@@ -103,6 +105,8 @@ export declare class LedgerCollection implements ILedgerCollection {
      */
     getCashFlowYearAverage(date?: Date): number;
     getCashFlowMonth(date?: Date): number;
+    getAverageCashFlowMonthByQuarter(date?: Date): number;
+    getCashFlowQuarter(date?: Date): number;
     getSummaryMonth(date: Date): ILedgerSummary;
     getSummaryAnnual(year?: number): ILedgerSummary;
     getSummariesAnnual(year?: number): ILedgerSummary[];

package/dist/src/ledger/ledger-collection.js

@@ -10,6 +10,7 @@ const properties_1 = require("../properties");
 const currency_1 = __importDefault(require("../formatters/currency"));
 const data_clone_date_1 = require("../utils/data-clone-date");
 const date_fns_1 = require("date-fns");
+const get_date_quarter_1 = require("../utils/get-date-quarter");
 class LedgerCollection {
     collection;
     getSummaryByType(collection, type) {
@@ -124,6 +125,48 @@ class LedgerCollection {
         }
         return this.getSummaryByType(boundary, ledger_item_type_1.LedgerItemType.CashFlow);
     }
+    getAverageCashFlowMonthByQuarter(date) {
+        if (this.isEmpty()) {
+            return 0;
+        }
+        if (!date) {
+            date = this.collection.last().created;
+        }
+        const quarter = Math.floor(date.getUTCMonth() / 3);
+        const year = date.getUTCFullYear();
+        const boundary = this.filter((li) => {
+            return li.dateMatchesYearAndQuarter(year, quarter);
+        });
+        if (boundary.length === 0) {
+            return 0;
+        }
+        const cashFlowItems = boundary.filter((x) => x.typeMatches(ledger_item_type_1.LedgerItemType.CashFlow));
+        if (cashFlowItems.length === 0) {
+            return 0;
+        }
+        if (cashFlowItems.length === 0) {
+            return 0;
+        }
+        const firstMonth = cashFlowItems[0].created.getUTCMonth();
+        const lastMonth = cashFlowItems[cashFlowItems.length - 1].created.getUTCMonth();
+        const monthsWithData = lastMonth - firstMonth + 1;
+        const totalCashFlow = this.getCashFlowQuarter(date);
+        return totalCashFlow / monthsWithData;
+    }
+    getCashFlowQuarter(date) {
+        if (this.isEmpty()) {
+            return 0;
+        }
+        if (!date) {
+            date = this.collection.last().created;
+        }
+        const quarter = (0, get_date_quarter_1.getDateQuarter)(date);
+        const year = date.getUTCFullYear();
+        const boundary = this.filter((li) => {
+            return li.dateMatchesYearAndQuarter(year, quarter);
+        });
+        return this.getSummaryByType(boundary, ledger_item_type_1.LedgerItemType.CashFlow);
+    }
     getSummaryMonth(date) {
         if (!date) {
             throw new Error('no date supplied');

package/dist/src/ledger/ledger-item.d.ts

@@ -9,11 +9,16 @@ export declare class LedgerItem {
     note?: string;
     constructor(amount?: number, type?: LedgerItemType, created?: Date, note?: string);
     getMonth(): number;
+    /**
+     * if one is found, a zero based quarter number, otherwise you'll get -1
+     */
+    getQuarter(): number;
     isAmountGreaterThanZero(): boolean;
     dateMatchesYearAndMonth(today: Date): boolean;
     dateLessThanOrEqualTo(today: Date): boolean;
     dateNotGreaterThan(today: Date): boolean;
     dateMatchesYear(year: number): boolean;
+    dateMatchesYearAndQuarter(year: number, quarter: number): boolean;
     typeMatches(itemType: LedgerItemType): boolean;
     getYear(): number;
     clone(): LedgerItem;

package/dist/src/ledger/ledger-item.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LedgerItem = void 0;
 const ledger_item_type_1 = require("./ledger-item-type");
 const data_compare_date_1 = __importDefault(require("../utils/data-compare-date"));
+const get_date_quarter_1 = require("../utils/get-date-quarter");
 /**
  * this is an entry into the account. Think of it as a checking account, and it's simply a transaction line.
  */
@@ -30,6 +31,15 @@ class LedgerItem {
         }
         return this.created.getUTCMonth();
     }
+    /**
+     * if one is found, a zero based quarter number, otherwise you'll get -1
+     */
+    getQuarter() {
+        if (!this.created) {
+            return -1;
+        }
+        return (0, get_date_quarter_1.getDateQuarter)(this.created);
+    }
     isAmountGreaterThanZero() {
         return this.amount > 0;
     }
@@ -60,6 +70,15 @@ class LedgerItem {
         }
         return year === this.created.getUTCFullYear();
     }
+    dateMatchesYearAndQuarter(year, quarter) {
+        if (!this.created) {
+            return false;
+        }
+        if (!this.dateMatchesYear(year)) {
+            return false;
+        }
+        return this.getQuarter() === quarter;
+    }
     typeMatches(itemType) {
         return this.type === itemType;
     }

package/dist/src/time/default-has-met-goal-or-max-time.js

@@ -14,7 +14,7 @@ const defaultHasMetGoalOrMaxTime = (start, today, user, maxYears) => {
     if ((0, date_fns_1.isEqual)(start, today) && !user) {
         return false;
     }
-    if (user && user.metMonthlyGoal(today)) {
+    if (user && user.metAverageQuarterlyGoal(today)) {
         return true;
     }
     const maxDate = (0, data_clone_date_1.cloneDateUtc)(start, (date) => {

package/dist/src/time/looper.js

@@ -42,7 +42,7 @@ const looper = (options, timeline) => {
             }
         }
     }
-    if (result.user.metMonthlyGoal(result.endDate)) {
+    if (result.user.metAverageQuarterlyGoal(result.endDate)) {
         return result;
     }
     //step 3: sell properties

package/dist/src/utils/get-date-quarter.d.ts

@@ -0,0 +1 @@
+export declare const getDateQuarter: (date: Date) => number;

package/dist/src/utils/get-date-quarter.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDateQuarter = void 0;
+const getDateQuarter = (date) => Math.floor(date.getUTCMonth() / 3);
+exports.getDateQuarter = getDateQuarter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubedelement.com/realty-investor-timeline",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "description": "A way to determine if and when your expenses would be covered",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",

package/.github/dependabot.yml

@@ -1,10 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    pull-request-branch-name:
-      separator: "-"
-      prefix: "feature/"
-    version: "patch"

package/docs/_media/badge.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="116" height="20" role="img" aria-label="Coverage: 89.34%"><title>Coverage: 89.34%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="116" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="63" height="20" fill="#555"/><rect x="63" width="53" height="20" fill="#dfb317"/><rect width="116" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="325" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="530">Coverage</text><text x="325" y="140" transform="scale(.1)" fill="#fff" textLength="530">Coverage</text><text aria-hidden="true" x="885" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">89.34%</text><text x="885" y="140" transform="scale(.1)" fill="#fff" textLength="430">89.34%</text></g></svg>

package/docs/account/i-user-goal/index.md

@@ -1,11 +0,0 @@
-[**@cubedelement.com/realty-investor-timeline**](../../index.md)
-
----
-
-[@cubedelement.com/realty-investor-timeline](../../modules.md) / account/i-user-goal
-
-# account/i-user-goal
-
-## Interfaces
-
-- [IUserGoal](interfaces/IUserGoal.md)

package/docs/account/i-user-goal/interfaces/IUserGoal.md

@@ -1,47 +0,0 @@
-[**@cubedelement.com/realty-investor-timeline**](../../../index.md)
-
----
-
-[@cubedelement.com/realty-investor-timeline](../../../modules.md) / [account/i-user-goal](../index.md) / IUserGoal
-
-# Interface: IUserGoal
-
-Defined in: [account/i-user-goal.ts:3](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-goal.ts#L3)
-
-## Extended by
-
-- [`IUserInvestorCheck`](../../i-user-investor-check/interfaces/IUserInvestorCheck.md)
-
-## Properties
-
-### monthlyIncomeAmountGoal
-
-> **monthlyIncomeAmountGoal**: `number`
-
-Defined in: [account/i-user-goal.ts:7](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-goal.ts#L7)
-
-used to determine how much you need want for monthly expenses
-
-## Methods
-
-### metMonthlyGoal()
-
-> **metMonthlyGoal**(`today`, `properties`): `boolean`
-
-Defined in: [account/i-user-goal.ts:14](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-goal.ts#L14)
-
-method used to help determine if you have met your expenses
-
-#### Parameters
-
-##### today
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-#### Returns
-
-`boolean`

package/docs/account/i-user-investor-check/index.md

@@ -1,11 +0,0 @@
-[**@cubedelement.com/realty-investor-timeline**](../../index.md)
-
----
-
-[@cubedelement.com/realty-investor-timeline](../../modules.md) / account/i-user-investor-check
-
-# account/i-user-investor-check
-
-## Interfaces
-
-- [IUserInvestorCheck](interfaces/IUserInvestorCheck.md)

package/docs/account/i-user-investor-check/interfaces/IUserInvestorCheck.md

@@ -1,206 +0,0 @@
-[**@cubedelement.com/realty-investor-timeline**](../../../index.md)
-
----
-
-[@cubedelement.com/realty-investor-timeline](../../../modules.md) / [account/i-user-investor-check](../index.md) / IUserInvestorCheck
-
-# Interface: IUserInvestorCheck
-
-Defined in: [account/i-user-investor-check.ts:9](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L9)
-
-## Extends
-
-- [`IUserGoal`](../../i-user-goal/interfaces/IUserGoal.md)
-
-## Extended by
-
-- [`IUser`](../../user/interfaces/IUser.md)
-
-## Properties
-
-### holdRules
-
-> **holdRules**: [`IRuleEvaluation`](../../../rules/rule-evaluation/interfaces/IRuleEvaluation.md)\<[`HoldRuleTypes`](../../../rules/hold-rule-types/enumerations/HoldRuleTypes.md)\>[]
-
-Defined in: [account/i-user-investor-check.ts:23](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L23)
-
-a system to determine how to hold onto the properties the longest. This scenario says as long as it meets 1 rule
-
----
-
-### ledgerCollection
-
-> `readonly` **ledgerCollection**: [`ILedgerCollection`](../../../ledger/ledger-collection/interfaces/ILedgerCollection.md)
-
-Defined in: [account/i-user-investor-check.ts:13](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L13)
-
-the collection which is used to keep a balance sheet.
-
----
-
-### loanSettings
-
-> **loanSettings**: [`ILoanSetting`](../../../loans/i-loan-settings/interfaces/ILoanSetting.md)[]
-
-Defined in: [account/i-user-investor-check.ts:18](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L18)
-
-a collection of loan settings for how to get a loan for single family or some other kind of property
-
----
-
-### monthlyIncomeAmountGoal
-
-> **monthlyIncomeAmountGoal**: `number`
-
-Defined in: [account/i-user-goal.ts:7](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-goal.ts#L7)
-
-used to determine how much you need want for monthly expenses
-
-#### Inherited from
-
-[`IUserGoal`](../../i-user-goal/interfaces/IUserGoal.md).[`monthlyIncomeAmountGoal`](../../i-user-goal/interfaces/IUserGoal.md#monthlyincomeamountgoal)
-
----
-
-### purchaseRules
-
-> **purchaseRules**: [`IRuleEvaluation`](../../../rules/rule-evaluation/interfaces/IRuleEvaluation.md)\<[`PurchaseRuleTypes`](../../../rules/purchase-rule-types/enumerations/PurchaseRuleTypes.md)\>[]
-
-Defined in: [account/i-user-investor-check.ts:60](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L60)
-
-a system to weed out the properties you don't want. This scenario says as long as it meets 1 rule
-
-## Methods
-
-### getAvailableSavings()
-
-> **getAvailableSavings**(`date`, `properties`): `number`
-
-Defined in: [account/i-user-investor-check.ts:55](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L55)
-
-should be the total balance - savings, using [getMinimumSavings](IUserInvestorCheck.md#getminimumsavings), for determining monthly cash to save for single family properties
-
-#### Parameters
-
-##### date
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-#### Returns
-
-`number`
-
----
-
-### getMinimumSavings()
-
-> **getMinimumSavings**(`date`, `properties`): `number`
-
-Defined in: [account/i-user-investor-check.ts:48](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L48)
-
-used to retrieve the amount required to keep in savings
-
-#### Parameters
-
-##### date
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-#### Returns
-
-`number`
-
----
-
-### hasMinimumSavings()
-
-> **hasMinimumSavings**(`date`, `properties`): `boolean`
-
-Defined in: [account/i-user-investor-check.ts:41](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L41)
-
-a way to determine if the user has enough money. This is different because with
-single family homes, you would have to save a certain amount of monthly mortgage
-
-#### Parameters
-
-##### date
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-#### Returns
-
-`boolean`
-
----
-
-### hasMoneyToInvest()
-
-> **hasMoneyToInvest**(`date`, `properties`, `contribution`?): `boolean`
-
-Defined in: [account/i-user-investor-check.ts:33](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-investor-check.ts#L33)
-
-based upon [getMinimumSavings](IUserInvestorCheck.md#getminimumsavings), it checks to see if there is an amount remaining that can be used along with the [contribution](IUserInvestorCheck.md#contribution).
-
-#### Parameters
-
-##### date
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-##### contribution?
-
-`number`
-
-#### Returns
-
-`boolean`
-
-#### Example
-
-```ts
-availableSavings - contribution >= 0;
-```
-
----
-
-### metMonthlyGoal()
-
-> **metMonthlyGoal**(`today`, `properties`): `boolean`
-
-Defined in: [account/i-user-goal.ts:14](https://github.com/kvernon/realty-investor-timeline/blob/c7446a8a5576468ac5874a2dd8323180fa97a55b/src/account/i-user-goal.ts#L14)
-
-method used to help determine if you have met your expenses
-
-#### Parameters
-
-##### today
-
-`Date`
-
-##### properties
-
-[`IRentalPropertyEntity`](../../../properties/i-rental-property-entity/interfaces/IRentalPropertyEntity.md)[]
-
-#### Returns
-
-`boolean`
-
-#### Inherited from
-
-[`IUserGoal`](../../i-user-goal/interfaces/IUserGoal.md).[`metMonthlyGoal`](../../i-user-goal/interfaces/IUserGoal.md#metmonthlygoal)

package/docs/account/index.md

@@ -1,31 +0,0 @@
-[**@cubedelement.com/realty-investor-timeline**](../index.md)
-
----
-
-[@cubedelement.com/realty-investor-timeline](../modules.md) / account
-
-# account
-
-## References
-
-### IUser
-
-Re-exports [IUser](user/interfaces/IUser.md)
-
----
-
-### IUserGoal
-
-Re-exports [IUserGoal](i-user-goal/interfaces/IUserGoal.md)
-
----
-
-### IUserInvestorCheck
-
-Re-exports [IUserInvestorCheck](i-user-investor-check/interfaces/IUserInvestorCheck.md)
-
----
-
-### User
-
-Re-exports [User](user/classes/User.md)