moneyfunx 2.2.0 → 3.0.1

package/build/src/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MoneyFunx
+ * * mek it funx up
+ */
+export { MAX_DURATION_YEARS, TOTALS, } from '@/lib/constants';
+export { ILoan, Loan } from '@/lib/debt/loan';
+export { determineExtraPayment, amortizePayments, payLoans, } from '@/lib/debt/payments';
+export { PaymentRecord, LoansPaymentSchedule, LoanPrincipals, PaymentSchedule, } from '@/lib/debt/paymentTypes';
+export { NegativeContributionError, PaymentTooLowError, NegativeWithdrawalError } from '@/lib/errors';
+export { amortizeContributions, contributeInstruments, determineExtraContribution, } from '@/lib/investment/contributions';
+export { ContributionRecord, ContributionSchedule, InstrumentsContributionSchedule, } from '@/lib/investment/contributionTypes';
+export { IInstrument, Instrument } from '@/lib/investment/instrument';
+export { calculateAmortizedWithdrawal, drawdownInstruments, } from '@/lib/investment/withdrawals';
+export { WithdrawalRecord, WithdrawalSchedule, InstrumentsWithdrawalSchedule, } from '@/lib/investment/withdrawalTypes';
+export { calculatePeriodicAmount, calculateBalanceRemaining, calculatePeriodsToZero, calculateInterestOverPeriods, } from '@/lib/shared/primitives';
+export { HasRateAndBalance, snowball, avalanche, sortWith } from '@/lib/shared/sorting';
+//# sourceMappingURL=index.d.ts.map

package/build/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,kBAAkB,EAClB,MAAM,GACP,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,QAAQ,GACT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEtG,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,GAChC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,GAC9B,MAAM,kCAAkC,CAAC;AAM1C,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}

package/build/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * MoneyFunx
+ * * mek it funx up
+ */
+export { MAX_DURATION_YEARS, TOTALS, } from '@/lib/constants';
+export { Loan } from '@/lib/debt/loan';
+export { determineExtraPayment, amortizePayments, payLoans, } from '@/lib/debt/payments';
+export { NegativeContributionError, PaymentTooLowError, NegativeWithdrawalError } from '@/lib/errors';
+export { amortizeContributions, contributeInstruments, determineExtraContribution, } from '@/lib/investment/contributions';
+export { Instrument } from '@/lib/investment/instrument';
+export { calculateAmortizedWithdrawal, drawdownInstruments, } from '@/lib/investment/withdrawals';
+// export {
+//   performWaterfallDrawdown,
+// } from '@/lib/investment/strategies';
+export { calculatePeriodicAmount, calculateBalanceRemaining, calculatePeriodsToZero, calculateInterestOverPeriods, } from '@/lib/shared/primitives';
+export { snowball, avalanche, sortWith } from '@/lib/shared/sorting';

package/build/{lib → src/lib}/constants.d.ts

@@ -3,3 +3,4 @@ export declare const MAX_DURATION_YEARS = 110;
 export declare const MAX_YIELD_FACTOR = 1.4;
 export declare const MIN_GROWTH_FACTOR = 1;
 export declare const MIN_YIELD_FACTOR = 0.45;
+//# sourceMappingURL=constants.d.ts.map

package/build/src/lib/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/lib/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,MAAM,WAAW,CAAC;AAG/B,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,gBAAgB,OAAO,CAAC"}

package/build/src/lib/debt/loan.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Represents a financial loan and provides methods for amortization and
+ * interest calculations.
+ */
+import { HasRateAndBalance } from '@/lib/shared/sorting';
+export interface ILoan extends HasRateAndBalance {
+    id: string;
+    name: string;
+    principal: number;
+    annualRate: number;
+    periodsPerYear: number;
+    termInYears: number;
+    periodicRate: number;
+    periods: number;
+    minPayment: number;
+    currentBalance: number;
+    fees: number;
+}
+export declare class Loan implements ILoan {
+    id: string;
+    name: string;
+    principal: number;
+    annualRate: number;
+    periodsPerYear: number;
+    termInYears: number;
+    periodicRate: number;
+    periods: number;
+    minPayment: number;
+    currentBalance: number;
+    fees: number;
+    /**
+     * @constructor
+     * @param {number} principal - The initial amount borrowed.
+     * @param {number} annualRate - The yearly interest rate (decimal).
+     * @param {number} periodsPerYear - Frequency of interest accrual per year.
+     * @param {number} termInYears - Total lifespan of the loan in years.
+     * @param {string} name - Identifying name for the loan.
+     * @param {number} [currentBalance] - The current outstanding balance.
+     * @param {number} [fees] - Any applicable loan fees.
+     */
+    constructor(principal: number, annualRate: number, periodsPerYear: number, termInYears: number, name: string, currentBalance?: number, fees?: number);
+    /**
+     * Validates that a payment amount meets the minimum requirement.
+     *
+     * @param {number} paymentAmount - The amount intended to be paid.
+     * @throws {errors.PaymentTooLowError} If the payment is less than the minimum.
+     * @returns {number} The validated payment amount.
+     */
+    validatePayment(paymentAmount?: number): number;
+    /**
+     * Calculates the minimum payment required to amortize the loan over its term.
+     * * @returns {number} The minimum periodic payment.
+     */
+    calculateMinPayment(): number;
+    /**
+     * Calculates interest accrued on a specific balance for one period.
+     *
+     * @param {number} [targetBalance=this.currentBalance] - The balance to accrue interest on.
+     * @returns {number} The interest accrued.
+     */
+    accrueInterest(targetBalance?: number): number;
+    /**
+     * Determines the number of periods remaining until the loan reaches a zero balance.
+     *
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Balance to calculate against.
+     * @returns {number} Number of periods to zero.
+     */
+    numPaymentsToZero(paymentAmount?: number, targetBalance?: number): number;
+    /**
+     * Calculates the balance remaining after a set number of periods.
+     *
+     * @param {number} periodsElapsed - Number of periods that have passed.
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Starting balance.
+     * @returns {number} The remaining principal balance.
+     */
+    principalRemaining(periodsElapsed: number, paymentAmount?: number, targetBalance?: number): number;
+    /**
+     * Calculates the total interest paid over a specified number of periods.
+     *
+     * @param {number} periodsElapsed - Number of periods paid.
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Starting balance.
+     * @returns {number} Total interest paid.
+     */
+    interestPaid(periodsElapsed: number, paymentAmount?: number, targetBalance?: number): number;
+}
+//# sourceMappingURL=loan.d.ts.map

package/build/src/lib/debt/loan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loan.d.ts","sourceRoot":"","sources":["../../../../src/lib/debt/loan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,KAAM,SAAQ,iBAAiB;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,IAAK,YAAW,KAAK;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;OASG;gBAED,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,MAAM,EACvB,IAAI,CAAC,EAAE,MAAM;IAef;;;;;;OAMG;IACH,eAAe,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM;IAYhE;;;OAGG;IACH,mBAAmB,IAAI,MAAM;IAQ7B;;;;;OAKG;IACH,cAAc,CAAC,aAAa,GAAE,MAA4B,GAAG,MAAM;IAInE;;;;;;OAMG;IACH,iBAAiB,CACf,aAAa,GAAE,MAAwB,EACvC,aAAa,GAAE,MAA4B,GAC1C,MAAM;IAST;;;;;;;OAOG;IACH,kBAAkB,CAChB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAwB,EACvC,aAAa,GAAE,MAA4B,GAC1C,MAAM;IAcT;;;;;;;OAOG;IACH,YAAY,CACV,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAwB,EACvC,aAAa,GAAE,MAA4B,GAC1C,MAAM;CAyBV"}

package/build/src/lib/debt/loan.js

@@ -0,0 +1,106 @@
+/**
+ * Represents a financial loan and provides methods for amortization and
+ * interest calculations.
+ */
+import * as errors from '@/lib/errors';
+import * as primitives from '@/lib/shared/primitives';
+export class Loan {
+    /**
+     * @constructor
+     * @param {number} principal - The initial amount borrowed.
+     * @param {number} annualRate - The yearly interest rate (decimal).
+     * @param {number} periodsPerYear - Frequency of interest accrual per year.
+     * @param {number} termInYears - Total lifespan of the loan in years.
+     * @param {string} name - Identifying name for the loan.
+     * @param {number} [currentBalance] - The current outstanding balance.
+     * @param {number} [fees] - Any applicable loan fees.
+     */
+    constructor(principal, annualRate, periodsPerYear, termInYears, name, currentBalance, fees) {
+        this.id = String(Math.floor(Math.random() * Date.now()));
+        this.name = name;
+        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.currentBalance = currentBalance !== undefined ? currentBalance : principal;
+        this.fees = fees || 0;
+    }
+    /**
+     * Validates that a payment amount meets the minimum requirement.
+     *
+     * @param {number} paymentAmount - The amount intended to be paid.
+     * @throws {errors.PaymentTooLowError} If the payment is less than the minimum.
+     * @returns {number} The validated payment amount.
+     */
+    validatePayment(paymentAmount = this.minPayment) {
+        const normalizedMinimum = parseInt((100 * this.minPayment).toFixed());
+        const normalizedPayment = parseInt((100 * paymentAmount).toFixed());
+        if (normalizedMinimum > normalizedPayment) {
+            throw new errors.PaymentTooLowError(`payment of ${paymentAmount} cannot be less than ${this.minPayment}`);
+        }
+        return paymentAmount;
+    }
+    /**
+     * Calculates the minimum payment required to amortize the loan over its term.
+     * * @returns {number} The minimum periodic payment.
+     */
+    calculateMinPayment() {
+        return primitives.calculatePeriodicAmount(this.principal, this.periodicRate, this.periods);
+    }
+    /**
+     * Calculates interest accrued on a specific balance for one period.
+     *
+     * @param {number} [targetBalance=this.currentBalance] - The balance to accrue interest on.
+     * @returns {number} The interest accrued.
+     */
+    accrueInterest(targetBalance = this.currentBalance) {
+        return targetBalance * this.periodicRate;
+    }
+    /**
+     * Determines the number of periods remaining until the loan reaches a zero balance.
+     *
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Balance to calculate against.
+     * @returns {number} Number of periods to zero.
+     */
+    numPaymentsToZero(paymentAmount = this.minPayment, targetBalance = this.currentBalance) {
+        this.validatePayment(paymentAmount);
+        return primitives.calculatePeriodsToZero(targetBalance, paymentAmount, this.periodicRate);
+    }
+    /**
+     * Calculates the balance remaining after a set number of periods.
+     *
+     * @param {number} periodsElapsed - Number of periods that have passed.
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Starting balance.
+     * @returns {number} The remaining principal balance.
+     */
+    principalRemaining(periodsElapsed, paymentAmount = this.minPayment, targetBalance = this.currentBalance) {
+        this.validatePayment(paymentAmount);
+        const periodsToZero = this.numPaymentsToZero(paymentAmount, targetBalance);
+        return periodsElapsed < periodsToZero
+            ? primitives.calculateBalanceRemaining(targetBalance, paymentAmount, this.periodicRate, periodsElapsed)
+            : 0;
+    }
+    /**
+     * Calculates the total interest paid over a specified number of periods.
+     *
+     * @param {number} periodsElapsed - Number of periods paid.
+     * @param {number} [paymentAmount=this.minPayment] - Periodic payment amount.
+     * @param {number} [targetBalance=this.currentBalance] - Starting balance.
+     * @returns {number} Total interest paid.
+     */
+    interestPaid(periodsElapsed, paymentAmount = this.minPayment, targetBalance = this.currentBalance) {
+        this.validatePayment(paymentAmount);
+        const totalPeriodsToZero = this.numPaymentsToZero(paymentAmount, targetBalance);
+        if (periodsElapsed < totalPeriodsToZero) {
+            return primitives.calculateInterestOverPeriods(targetBalance, paymentAmount, this.periodicRate, periodsElapsed);
+        }
+        const lastFullPeriod = totalPeriodsToZero - 1;
+        const finalInterestAccrual = this.accrueInterest(this.principalRemaining(lastFullPeriod, paymentAmount, targetBalance));
+        return primitives.calculateInterestOverPeriods(targetBalance, paymentAmount, this.periodicRate, lastFullPeriod) + finalInterestAccrual;
+    }
+}

package/build/{lib → src/lib}/debt/paymentTypes.d.ts

@@ -11,3 +11,4 @@ export type PaymentSchedule = {
 };
 export type LoansPaymentSchedule = Record<string, PaymentSchedule>;
 export type LoanPrincipals = Record<string, number>;
+//# sourceMappingURL=paymentTypes.d.ts.map

package/build/src/lib/debt/paymentTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paymentTypes.d.ts","sourceRoot":"","sources":["../../../../src/lib/debt/paymentTypes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,aAAa,EAAE,CAAC;CACvC,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEnE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/build/{lib → src/lib}/debt/payments.d.ts

@@ -3,8 +3,8 @@
  * This file contains functions for computing detailed information on paying loans
  *
  */
-import type { ILoan, Loan } from './loan';
-import type { PaymentRecord, LoansPaymentSchedule } from './paymentTypes';
+import type { ILoan, Loan } from '@/lib/debt/loan';
+import type { PaymentRecord, LoansPaymentSchedule } from '@/lib/debt/paymentTypes';
 /**
  *
  * Calculates the extra amount in a payment after all loans' minimum payments are met
@@ -50,3 +50,4 @@ export declare function amortizePayments(loan: Loan, principal: number, payment:
  *
  */
 export declare function payLoans(loans: Loan[], payment: number, reduceMinimum?: boolean): LoansPaymentSchedule;
+//# sourceMappingURL=payments.d.ts.map

package/build/src/lib/debt/payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.d.ts","sourceRoot":"","sources":["../../../../src/lib/debt/payments.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EACV,aAAa,EAEb,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EAAE,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAYR;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,OAAO,GACrB,MAAM,CAOR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAC,IAAI,EACpB,WAAW,EAAE,MAAM,GAAC,IAAI,EACxB,WAAW,GAAE,MAAU,EACvB,SAAS,GAAE,MAAU,GACpB,aAAa,EAAE,CA+BjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,OAAe,GAC7B,oBAAoB,CAqItB"}

package/build/{lib → src/lib}/debt/payments.js

@@ -3,7 +3,7 @@
  * This file contains functions for computing detailed information on paying loans
  *
  */
-import * as errors from '../errors';
+import * as errors from '@/lib/errors';
 /**
  *
  * Calculates the extra amount in a payment after all loans' minimum payments are met
@@ -105,8 +105,8 @@ export function payLoans(loans, payment, reduceMinimum = false) {
     let totalAmortizationSchedule = [];
     while (paidLoans < loans.length) {
         const firstLoan = loans.slice(paidLoans)[0];
-        const firstLoanPayment = firstLoan.minPayment +
-            determineExtraPayment(loans.slice(paidLoans), monthlyPayment);
+        const firstLoanPayment = (firstLoan.minPayment +
+            determineExtraPayment(loans.slice(paidLoans), monthlyPayment));
         const firstLoanPrincipalRemaining = loanPrincipalsRemaining[firstLoan.id];
         const periodsToPay = firstLoan.numPaymentsToZero(firstLoanPayment, firstLoanPrincipalRemaining);
         const firstLoanAmortizedPayments = amortizePayments(firstLoan, firstLoanPrincipalRemaining, firstLoanPayment, periodsToPay, periodsElapsed);

package/build/{lib → src/lib}/errors.d.ts

@@ -4,3 +4,7 @@ export declare class PaymentTooLowError extends Error {
 export declare class NegativeContributionError extends Error {
     constructor(message: string);
 }
+export declare class NegativeWithdrawalError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/src/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAK5B;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAK5B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAK5B"}

package/build/{lib → src/lib}/errors.js

@@ -12,3 +12,10 @@ export class NegativeContributionError extends Error {
         this.name = 'NegativeContributionError';
     }
 }
+export class NegativeWithdrawalError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, NegativeWithdrawalError.prototype);
+        this.name = 'NegativeWithdrawalError';
+    }
+}

package/build/{lib → src/lib}/investment/contributionTypes.d.ts

@@ -31,3 +31,4 @@ export type ContributionSchedule = {
 export type InstrumentsContributionSchedule = Record<string, ContributionSchedule>;
 export type InstrumentBalances = Record<string, number>;
 export type InstrumentYTDs = Record<string, number>;
+//# sourceMappingURL=contributionTypes.d.ts.map

package/build/src/lib/investment/contributionTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributionTypes.d.ts","sourceRoot":"","sources":["../../../../src/lib/investment/contributionTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/build/{lib → src/lib}/investment/contributions.d.ts

@@ -3,8 +3,8 @@
  * This file containts functions for computing detailed information on contributing to investments
  *
  */
-import type { Instrument } from './instrument';
-import { ContributionRecord, InstrumentsContributionSchedule } from './contributionTypes';
+import type { Instrument } from '@/lib/investment/instrument';
+import { ContributionRecord, InstrumentsContributionSchedule } from '@/lib/investment/contributionTypes';
 /**
  *
  * @param {IInstrument[]} instruments The instruments to allocate maximum contributions
@@ -50,3 +50,4 @@ export declare function amortizeContributions(instrument: Instrument, initialBal
  * @returns {InstrumentsContributionSchedule} The amortized contributions for all instruments
  */
 export declare function contributeInstruments(instruments: Instrument[], contribution: number, numContributions: number, accrueBeforeContribution?: boolean): InstrumentsContributionSchedule;
+//# sourceMappingURL=contributions.d.ts.map

package/build/src/lib/investment/contributions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributions.d.ts","sourceRoot":"","sources":["../../../../src/lib/investment/contributions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAGhC,MAAM,oCAAoC,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,UAAU,EAAE,EACzB,YAAY,EAAE,MAAM,GACnB,MAAM,CAMR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,WAAW,GAAE,MAAU,EACvB,wBAAwB,GAAE,OAAc,GACvC,kBAAkB,CAgBpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,WAAW,GAAE,MAAU,EACvB,wBAAwB,GAAE,OAAc,GACvC,kBAAkB,EAAE,CAkBtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,UAAU,EAAE,EACzB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,wBAAwB,GAAE,OAAc,GACvC,+BAA+B,CA6FjC"}

package/build/{lib → src/lib}/investment/contributions.js

@@ -13,6 +13,7 @@ export function determineExtraContribution(instruments, contribution) {
     const totalMaxPayment = instruments.reduce((accumulator, instrument) => accumulator + instrument.periodicContribution(), 0);
     return Math.max(contribution - totalMaxPayment, 0);
 }
+;
 /**
  *
  * @param {Instrument} instrument The Instrument to contribute to
@@ -42,6 +43,7 @@ export function amortizeContribution(instrument, currentBalance, contribution, s
         currentBalance,
     };
 }
+;
 /**
  *
  * Calculates the amortization schedule for an instrument with a contribution
@@ -81,6 +83,7 @@ export function amortizeContributions(instrument, initialBalance, contribution,
  * @returns {InstrumentsContributionSchedule} The amortized contributions for all instruments
  */
 export function contributeInstruments(instruments, contribution, numContributions, accrueBeforeContribution = true) {
+    // state setup
     const contributionSchedules = {};
     const instrumentBalances = {};
     const instrumentYTDs = {};
@@ -96,11 +99,11 @@ export function contributeInstruments(instruments, contribution, numContribution
         instrumentBalances[instrument.id] = instrument.currentBalance;
         instrumentYTDs[instrument.id] = 0;
     });
-    // algorithm
+    // algorithm to build contributionSchedules
     for (let period = 0; period < numContributions; period++) {
         let periodicContribution = contribution;
         for (const instrument of instruments) {
-            if (period % 12 == 1) {
+            if (period % instrument.periodsPerYear == 1) {
                 instrumentYTDs[instrument.id] = 0;
             }
             const validContribution = instrument.validateContribution(Math.min(periodicContribution, instrument.periodicContribution()), instrumentYTDs[instrument.id]);
@@ -145,3 +148,4 @@ export function contributeInstruments(instruments, contribution, numContribution
     };
     return contributionSchedules;
 }
+;

package/build/src/lib/investment/instrument.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Represents a financial instrument for investments and drawdowns.
+ */
+import { HasRateAndBalance } from '@/lib/shared/sorting';
+export interface IInstrument extends HasRateAndBalance {
+    id: string;
+    name: string;
+    currentBalance: number;
+    annualRate: number;
+    periodsPerYear: number;
+    periodicRate: number;
+    annualLimit: number;
+}
+export declare class Instrument implements IInstrument {
+    id: string;
+    name: string;
+    currentBalance: number;
+    annualRate: number;
+    periodsPerYear: number;
+    periodicRate: number;
+    annualLimit: number;
+    /**
+     * @constructor
+     * @param {number} currentBalance - Initial balance of the instrument.
+     * @param {number} annualRate - The yearly expected return or interest rate.
+     * @param {number} periodsPerYear - Number of accrual periods per year.
+     * @param {string} name - Name of the investment instrument.
+     * @param {number} [annualLimit=0] - Maximum allowable contribution per year.
+     */
+    constructor(currentBalance: number, annualRate: number, periodsPerYear: number, name: string, annualLimit?: number);
+    /**
+     * Validates a contribution against limits and negative values.
+     *
+     * @param {number} contribution - Amount to contribute.
+     * @param {number} yearToDateContribution - Current contributions for the calendar year.
+     * @throws {errors.NegativeContributionError} If contribution is less than zero.
+     * @returns {number} The allowed contribution amount.
+     */
+    validateContribution(contribution: number, yearToDateContribution: number): number;
+    /**
+     * Determines the number of periods remaining until the balance reaches zero during drawdown.
+     *
+     * @param {number} periodicWithdrawalAmount - The amount withdrawn each period.
+     * @param {number} [targetBalance=this.currentBalance] - The balance to draw from.
+     * @returns {number} Number of periods to depletion.
+     */
+    numWithdrawalsToZero(periodicWithdrawalAmount: number, targetBalance?: number): number;
+    /**
+     * Calculates the maximum sustainable periodic withdrawal for a set duration.
+     *
+     * @param {number} totalDurationInPeriods - The number of periods the balance must last.
+     * @param {number} [targetBalance=this.currentBalance] - The starting balance.
+     * @returns {number} The calculated periodic withdrawal amount.
+     */
+    calculateMaxWithdrawal(totalDurationInPeriods: number, targetBalance?: number): number;
+    /**
+     * Helper to calculate the maximum periodic contribution allowed by the annual limit.
+     *
+     * @returns {number} The amortized periodic limit.
+     */
+    periodicContribution(): number;
+    /**
+     * Calculates the growth/interest accrued in one period.
+     *
+     * @param {number} [targetBalance=this.currentBalance] - The balance to calculate growth on.
+     * @returns {number} The growth amount.
+     */
+    accrueInterest(targetBalance?: number): number;
+}
+//# sourceMappingURL=instrument.d.ts.map

package/build/src/lib/investment/instrument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../../../src/lib/investment/instrument.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,UAAW,YAAW,WAAW;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;gBAED,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,MAAU;IAWzB;;;;;;;OAOG;IACH,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,GAAG,MAAM;IAmBlF;;;;;;OAMG;IACH,oBAAoB,CAClB,wBAAwB,EAAE,MAAM,EAChC,aAAa,GAAE,MAA4B,GAC1C,MAAM;IAQT;;;;;;OAMG;IACH,sBAAsB,CACpB,sBAAsB,EAAE,MAAM,EAC9B,aAAa,GAAE,MAA4B,GAC1C,MAAM;IAQT;;;;OAIG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;;;;OAKG;IACH,cAAc,CAAC,aAAa,GAAE,MAA4B,GAAG,MAAM;CAGpE"}

package/build/src/lib/investment/instrument.js

@@ -0,0 +1,79 @@
+/**
+ * Represents a financial instrument for investments and drawdowns.
+ */
+import * as errors from '@/lib/errors';
+import * as primitives from '@/lib/shared/primitives';
+export class Instrument {
+    /**
+     * @constructor
+     * @param {number} currentBalance - Initial balance of the instrument.
+     * @param {number} annualRate - The yearly expected return or interest rate.
+     * @param {number} periodsPerYear - Number of accrual periods per year.
+     * @param {string} name - Name of the investment instrument.
+     * @param {number} [annualLimit=0] - Maximum allowable contribution per year.
+     */
+    constructor(currentBalance, annualRate, periodsPerYear, name, annualLimit = 0) {
+        this.id = String(Math.floor(Math.random() * Date.now()));
+        this.name = name;
+        this.currentBalance = currentBalance;
+        this.annualRate = annualRate;
+        this.periodsPerYear = periodsPerYear;
+        this.periodicRate = this.annualRate / this.periodsPerYear;
+        this.annualLimit = annualLimit;
+    }
+    /**
+     * Validates a contribution against limits and negative values.
+     *
+     * @param {number} contribution - Amount to contribute.
+     * @param {number} yearToDateContribution - Current contributions for the calendar year.
+     * @throws {errors.NegativeContributionError} If contribution is less than zero.
+     * @returns {number} The allowed contribution amount.
+     */
+    validateContribution(contribution, yearToDateContribution) {
+        if (contribution < 0) {
+            throw new errors.NegativeContributionError(`contribution of ${contribution} must be greater than/equal to zero`);
+        }
+        if (this.annualLimit > 0) {
+            const remainingAnnualCapacity = Math.max(this.annualLimit - yearToDateContribution, 0);
+            return Math.min(remainingAnnualCapacity, contribution, this.periodicContribution());
+        }
+        return contribution;
+    }
+    /**
+     * Determines the number of periods remaining until the balance reaches zero during drawdown.
+     *
+     * @param {number} periodicWithdrawalAmount - The amount withdrawn each period.
+     * @param {number} [targetBalance=this.currentBalance] - The balance to draw from.
+     * @returns {number} Number of periods to depletion.
+     */
+    numWithdrawalsToZero(periodicWithdrawalAmount, targetBalance = this.currentBalance) {
+        return primitives.calculatePeriodsToZero(targetBalance, periodicWithdrawalAmount, this.periodicRate);
+    }
+    /**
+     * Calculates the maximum sustainable periodic withdrawal for a set duration.
+     *
+     * @param {number} totalDurationInPeriods - The number of periods the balance must last.
+     * @param {number} [targetBalance=this.currentBalance] - The starting balance.
+     * @returns {number} The calculated periodic withdrawal amount.
+     */
+    calculateMaxWithdrawal(totalDurationInPeriods, targetBalance = this.currentBalance) {
+        return primitives.calculatePeriodicAmount(targetBalance, this.periodicRate, totalDurationInPeriods);
+    }
+    /**
+     * Helper to calculate the maximum periodic contribution allowed by the annual limit.
+     *
+     * @returns {number} The amortized periodic limit.
+     */
+    periodicContribution() {
+        return this.annualLimit > 0 ? this.annualLimit / this.periodsPerYear : 0;
+    }
+    /**
+     * Calculates the growth/interest accrued in one period.
+     *
+     * @param {number} [targetBalance=this.currentBalance] - The balance to calculate growth on.
+     * @returns {number} The growth amount.
+     */
+    accrueInterest(targetBalance = this.currentBalance) {
+        return targetBalance * this.periodicRate;
+    }
+}

package/build/src/lib/investment/strategies.d.ts

@@ -0,0 +1,19 @@
+/**
+ * This file contains high-level drawdown strategies for investment portfolios.
+ */
+import { Instrument } from '@/lib/investment/instrument';
+import { InstrumentsWithdrawalSchedule } from '@/lib/investment/withdrawalTypes';
+/**
+ * Executes a 'Waterfall' drawdown strategy.
+ * Funds are pulled from instruments in the order they appear in the array.
+ * The next instrument is only touched if the previous one cannot fulfill the
+ * remaining target net income.
+ *
+ * @param {Instrument[]} financialInstruments - Ordered list of accounts (e.g., Taxable -> Tax-Deferred).
+ * @param {number} targetNetPeriodicIncome - The take-home cash required for the period.
+ * @param {number} totalPeriodsToSimulate - Duration of the simulation.
+ * @param {number} [effectiveTaxRate=0] - The tax rate used to gross up withdrawals.
+ * @returns {InstrumentsWithdrawalSchedule} The full simulation results.
+ */
+export declare function performWaterfallDrawdown(financialInstruments: Instrument[], targetNetPeriodicIncome: number, totalPeriodsToSimulate: number, effectiveTaxRate?: number): InstrumentsWithdrawalSchedule;
+//# sourceMappingURL=strategies.d.ts.map

package/build/src/lib/investment/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../../src/lib/investment/strategies.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,OAAO,EACL,6BAA6B,EAE9B,MAAM,kCAAkC,CAAC;AAG1C;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,oBAAoB,EAAE,UAAU,EAAE,EAClC,uBAAuB,EAAE,MAAM,EAC/B,sBAAsB,EAAE,MAAM,EAC9B,gBAAgB,GAAE,MAAU,GAC3B,6BAA6B,CAsE/B"}