feat: implemented holdrules

Author: kvernon

README.md

@@ -90,8 +90,7 @@ Once a feature's PR is merged, the pipeline will run checks and publish.
 ## Missing features
 
 1. delay 1st mortgage payment
-2. implement hold rules
-3. apartments (passive investor)
+2. apartments (passive investor)
 
 ## Future
 
@@ -107,6 +106,7 @@ import {
   ISimulateOptions,
   LedgerCollection,
   LoanSettings,
+  HoldRuleTypes,
   PropertyType,
   RentalGenerator,
   RentalSingleFamily,
@@ -121,6 +121,13 @@ const options: ISimulateOptions = {
   amountInSavings: 100000,
   monthlyIncomeAmountGoal: 10000,
   monthlySavedAmount: 10000,
+  holdRules: [
+    {
+      value: 5,
+      type: HoldRuleTypes.minSellIfHighEquityPercent,
+      propertyType: PropertyType.SingleFamily,
+    },
+  ],
   purchaseRules: [
     { value: 30000, type: PurchaseRuleTypes.maxEstimatedOutOfPocket },
     { value: 7000, type: PurchaseRuleTypes.minEstimatedCapitalGains },

src/account/user.ts

@@ -8,6 +8,7 @@ import { PurchaseRuleTypes } from '../rules/purchase-rule-types';
 import { IRuleEvaluation } from '../rules/rule-evaluation';
 import cloneDeep from 'lodash.clonedeep';
 import { ILedgerSummary } from '../ledger/i-ledger-summary';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 /**
  * It's the user... as an interface!
@@ -53,6 +54,11 @@ export interface IUser extends IUserInvestorCheck {
    */
   getSummariesAnnual(year: number): ILedgerSummary[];
 
+  /**
+   * a system to determine how to hold onto the properties the longest. This scenario says as long as it meets 1 rule
+   */
+  holdRules: IRuleEvaluation<HoldRuleTypes>[];
+
   /**
    * a system to weed out the properties you don't want. This scenario says as long as it meets 1 rule
    */
@@ -94,6 +100,11 @@ export class User implements IUser {
     this.ledgerCollection = ledgerCollection;
   }
 
+  /**
+   * a system to determine how to hold onto the properties the longest. This scenario says as long as it meets 1 rule
+   */
+  holdRules: IRuleEvaluation<HoldRuleTypes>[];
+
   /**
    * a system to weed out the properties you don't want. This scenario says as long as it meets 1 rule
    */

src/calculations/can-invest-by-user.ts

@@ -69,7 +69,7 @@ export function canInvestByUser(
   }
 
   // 1. need to map to rule to property, eg: PurchaseRuleTypes.minEstimatedCashFlowPerMonth > this.monthlyCashFlow;
-  const reasons = getInvestmentReasons<IRentalPropertyEntity>(rental).filter(
+  const reasons = getInvestmentReasons<IRentalPropertyEntity, PurchaseRuleTypes>(rental).filter(
     (r) => r.ruleType !== PurchaseRuleTypes.none
   );
 

src/investments/investment-reasons-decorator.ts

@@ -3,12 +3,13 @@ import 'reflect-metadata';
 import { IRentalPropertyEntity } from '../properties/i-rental-property-entity';
 import { InvestmentReasons } from './investment-reasons';
 import { PurchaseRuleTypes } from '../rules/purchase-rule-types';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 export type PropertyDecoratorType<T extends IRentalPropertyEntity> = (target: T, propertyKey: keyof T & string) => any;
 
-export interface IReasonToRule<T extends IRentalPropertyEntity> {
+export interface IReasonToRule<T extends IRentalPropertyEntity, TR extends PurchaseRuleTypes | HoldRuleTypes> {
   investmentReason: InvestmentReasons;
-  ruleType: PurchaseRuleTypes;
+  ruleType: TR;
   propertyKey: keyof T & string;
   value: T[keyof T] & number;
 }
@@ -17,14 +18,14 @@ export interface IReasonToRule<T extends IRentalPropertyEntity> {
  * used to set up properties to help map results to InvestmentReasons
  * @constructor
  * @param investmentReason
- * @param [ruleType=PurchaseRuleTypes.none]
+ * @param ruleType
  */
 export function InvestmentReason(
   investmentReason: InvestmentReasons,
-  ruleType: PurchaseRuleTypes = PurchaseRuleTypes.none
+  ruleType: PurchaseRuleTypes | HoldRuleTypes
 ): PropertyDecoratorType<IRentalPropertyEntity> {
   return (target: IRentalPropertyEntity, propertyKey: keyof IRentalPropertyEntity & string): any => {
-    const saveItem: IReasonToRule<IRentalPropertyEntity> = {
+    const saveItem: IReasonToRule<IRentalPropertyEntity, PurchaseRuleTypes | HoldRuleTypes> = {
       investmentReason,
       ruleType,
       propertyKey,
@@ -56,7 +57,10 @@ export function InvestmentReason(
  * @param target
  * @constructor
  */
-export function getInvestmentReasons<T extends IRentalPropertyEntity & object>(target: T): IReasonToRule<T>[] {
+export function getInvestmentReasons<
+  T extends IRentalPropertyEntity & object,
+  TR extends PurchaseRuleTypes | HoldRuleTypes
+>(target: T): IReasonToRule<T, TR>[] {
   const keys = Reflect.getMetadata('design:type', target) as string[];
 
   return keys.map((k) => {

src/properties/property-sort.ts

@@ -2,24 +2,25 @@ import { IRentalPropertyEntity } from './i-rental-property-entity';
 import { PurchaseRuleTypes } from '../rules/purchase-rule-types';
 import { getInvestmentReasons, InvestmentReasons } from '../investments';
 import { IRuleEvaluation } from '../rules/rule-evaluation';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 /**
  * property sort based on rules order and property value
  * @param propertyA
  * @param propertyB
- * @param purchaseRules
+ * @param rule
  */
-export default function propertySort(
+export default function propertySort<T extends PurchaseRuleTypes | HoldRuleTypes>(
   propertyA: IRentalPropertyEntity,
   propertyB: IRentalPropertyEntity,
-  purchaseRules: IRuleEvaluation<PurchaseRuleTypes>[]
+  rule: IRuleEvaluation<T>[]
 ): number {
-  if (!purchaseRules || purchaseRules.length === 0) {
+  if (!rule || rule.length === 0) {
     return -1;
   }
 
-  const reasonsA = getInvestmentReasons<IRentalPropertyEntity>(propertyA);
-  const reasonsB = getInvestmentReasons<IRentalPropertyEntity>(propertyB);
+  const reasonsA = getInvestmentReasons<IRentalPropertyEntity, T>(propertyA);
+  const reasonsB = getInvestmentReasons<IRentalPropertyEntity, T>(propertyB);
 
   if (reasonsA.length > 0 && reasonsB.length === 0) {
     return -1;
@@ -29,8 +30,8 @@ export default function propertySort(
     return 1;
   }
 
-  for (let i = 0; i < purchaseRules.length; i++) {
-    const r = purchaseRules[i];
+  for (let i = 0; i < rule.length; i++) {
+    const r = rule[i];
     const reasonsItemA = reasonsA.find((s) => s.ruleType === r.type) || {
       ruleType: PurchaseRuleTypes.none,
       descriptor: { value: 0 },
@@ -42,6 +43,7 @@ export default function propertySort(
       ruleType: PurchaseRuleTypes.none,
       descriptor: { value: 0 },
       propertyKey: '',
+      value: -1,
       investmentReason: InvestmentReasons.Unknown,
     };
 

src/properties/rental-single-family.ts

@@ -13,6 +13,7 @@ import { getCashDown, getSellPriceEstimate } from '../calculations/get-monthly-m
 import { cloneDateUtc } from '../utils/data-clone-date';
 import areSameDate from '../utils/data-are-same-date';
 import compareDates from '../utils/data-compare-date';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 export class RentalSingleFamily implements IEntityExistence, IRentalSavings, IRentalPropertyEntity {
   /**
@@ -227,5 +228,6 @@ export class RentalSingleFamily implements IEntityExistence, IRentalSavings, IRe
   }
 
   @InvestmentReason(InvestmentReasons.DoesNotMeetUserRuleCashOnCash, PurchaseRuleTypes.minEstimatedCashFlowPerMonth)
+  @InvestmentReason(InvestmentReasons.DoesNotMeetUserRuleCashOnCash, HoldRuleTypes.minSellIfLowCashFlowPercent)
   monthlyCashFlow: number;
 }

src/rules/hold-rule-types.ts

@@ -4,7 +4,7 @@ export enum HoldRuleTypes {
    */
   none = 'none',
   /**
-   * this rule is states that if you have a low cash flow %, then you'd like to sell it
+   * this rule states that if you have a low cash flow %, then you'd like to sell it
    */
   minSellIfLowCashFlowPercent = 'minSellIfLowCashFlowPercent',
 

src/time/movement.ts

@@ -13,6 +13,7 @@ import { ILoanSetting } from '../account/i-loan-settings';
 import { PropertyType } from '../account/property-type';
 import { IRuleEvaluation } from '../rules/rule-evaluation';
 import { PurchaseRuleTypes } from '../rules/purchase-rule-types';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 export interface ILoopOptions {
   /**
@@ -62,6 +63,10 @@ export function loop(options: ILoopOptions, user: IUser): ITimeline {
     predicate: (item) => item.propertyType === PropertyType.SingleFamily,
     message: 'no single family purchase rules for user: purchaseRules',
   });
+  ensureArray<IRuleEvaluation<HoldRuleTypes>>(user.holdRules, {
+    predicate: (item) => item.propertyType === PropertyType.SingleFamily,
+    message: 'no single family purchase rules for user: holdRules',
+  });
 
   let today = cloneDateUtc(options.startDate);
 
@@ -120,6 +125,7 @@ export function loop(options: ILoopOptions, user: IUser): ITimeline {
     //step 3: sell properties
     result.rentals
       .filter((r) => r.property.canSell(today))
+      .sort((a, b) => propertySort<HoldRuleTypes>(a.property, b.property, user.holdRules))
       .forEach((pr) => {
         pr.property.soldDate = cloneDateUtc(today);
 
@@ -161,7 +167,7 @@ export function loop(options: ILoopOptions, user: IUser): ITimeline {
       })
       .filter((r) => r.validator.canInvest)
       .map((r) => r.historical)
-      .sort((a, b) => propertySort(a.property, b.property, user.purchaseRules))
+      .sort((a, b) => propertySort<PurchaseRuleTypes>(a.property, b.property, user.purchaseRules))
       .forEach((pr) => {
         // check cash
         if (user.hasMoneyToInvest(today)) {

src/time/simulate.ts

@@ -13,6 +13,7 @@ import { LedgerCollection, LedgerItem, LedgerItemType } from '../ledger';
 import { ValueCache } from '../caching/value-cache';
 import { loop } from './movement';
 import { cloneDateUtc } from '../utils/data-clone-date';
+import { HoldRuleTypes } from '../rules/hold-rule-types';
 
 export interface ISimulateOptions extends IPropertyEntityOptions {
   /**
@@ -35,6 +36,11 @@ export interface ISimulateOptions extends IPropertyEntityOptions {
    */
   loanSettings: ILoanSetting[];
 
+  /**
+   * a system to determine how to hold onto the properties the longest. This scenario says as long as it meets 1 rule
+   */
+  holdRules: IRule<HoldRuleTypes>[];
+
   /**
    * This is how to prioritize the properties that come up. Use one, or use all rules! The order you put them in here, is the order it evaluates them as. {@link PurchaseRuleTypes} for possible rules
    */
@@ -88,6 +94,7 @@ export function simulate(options: ISimulateOptions): ITimeline {
   user.monthlySavedAmount = options.monthlySavedAmount;
   user.monthlyIncomeAmountGoal = options.monthlyIncomeAmountGoal;
   user.loanSettings = options.loanSettings;
+  user.holdRules = (options.holdRules || []).map((r) => new RuleEvaluation(r.value, r.type, r.propertyType));
   user.purchaseRules = (options.purchaseRules || []).map((r) => new RuleEvaluation(r.value, r.type, r.propertyType));
 
   return loop(

tests/calculations/can-invest-by-user.spec.ts

@@ -69,6 +69,7 @@ describe('and canInvestByUser', () => {
       expect(canInvestByUser(instance, user, null, null)).toMatchObject(expected);
     });
   });
+
   describe('and ledger.hasMinimumSavings is true', () => {
     test('and no rules', () => {
       const user: IUserInvestorCheck = {