diff --git a/src/portfolio.js b/src/portfolio.js index abeb4bb..d1d484c 100644 --- a/src/portfolio.js +++ b/src/portfolio.js @@ -154,6 +154,30 @@ class Portfolio { /** * Withdraws an amount from the portfolio. * + * The naive approach, which works most of the time, would be to sort the + * stonks by the absolute distance between the desired ratio and stonk ratio. + * + * The correct approach would be to split the stonks by less than and greater + * than the desired ratio, then sort them by absolute distance. Each + * iteration, you'd want one from either list based on which brings you closer + * to your desired ratio. + * + * For example if you were targeting a 0.0 ratio and sorted these shares were + * sorted by distance alone, you'd end up with 1.5 in gains by adding the + * first two stonks together. But the first and third stonk get you closer to + * the 0.0 ratio. + * + * ``` + * const portfolio = new Portfolio([ + * new Stonk({ value: 10, gains: 0.5, shares: 10 }), // 0.05 + * new Stonk({ value: 10, gains: 1, shares: 10 }), // 0.1 + * new Stonk({ value: 10, gains: -1.5, shares: 10 }), // -0.15 + * ]) + * const withdraw = portfolio.withdraw(20, 0) + * assert.equal(withdraw.value, 20) + * assert.equal(withdraw.gains, -1) + * ``` + * * @param {number} withdrawAmount The amount to withdraw. * @param {number} [desiredRatio=0.0] * The desired ratio of gains to withdraw. Can be `-1.0` to `1.0` for