Skip to content

Commit

Permalink
🏦 Add portfolio documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
mxbaylee committed Jul 29, 2023
1 parent 523cab6 commit 38ee992
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 19 deletions.
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"repository": {
"type": "git",
"url": "git+ssh://[email protected]/mxbaylee/tax-planning.js.git"
"url": "git+ssh://[email protected]/mxbaylee/taxPlanning.js.git"
},
"engines": {
"node": ">=19.4",
Expand Down
64 changes: 47 additions & 17 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ This toolchain is designed to assist individuals with long-term tax planning
strategies, such as a Roth conversion ladder and predicting tax liability over
their lifetime.

The API's are intentionally compatible with [Google Sheets App Scripts][gsas].

## 🌺 Table of Contents

* [🧪 Examples](#-examples)
* [🧪 Examples](#-portfolio-examples)
* [🏦 Portfolio Examples](#-portfolio-examples)
* [🏛️ Tax Examples](#-tax-examples)
* [🚀 Use Cases](#-use-cases)
* [⌨️ Local Development](#%EF%B8%8F--local-development)

Expand All @@ -17,12 +18,41 @@ The API's are intentionally compatible with [Google Sheets App Scripts][gsas].
A comprehensive example of Federal and State tax bracket combinations exist
inside of `./test/fullTaxYearAmount.js`.

### 🏦 Tax Amount
### 🏦 Portfolio Examples

Given a list of individual purchases (called Stonks) you can emulate tax
planning strategies on a specific portfolio.

```js
const { Portfolio } = require('taxPlanning.js')

const portfolio = new Portfolio([
new Stonk({ value: 10, gains: 0, shares: 10 }),
new Stonk({ value: 10, gains: 8, shares: 10 }),
new Stonk({ value: 10, gains: -10, shares: 10 }),
])

// we want to withdraw $20 and tax-loss harvest as much as possible
// more specific ratios can be picked to control taxes loss/gains in withdraws
const withdraw = portfolio.withdraw(20, -1.0)

// withdraw includes 2 full stonks
console.log(withdraw.value) // 20

// withdraw includes the lowest gains
console.log(withdraw.gains) // -10
```

### 🏛️ Tax Examples

The API's are intentionally compatible with [Google Sheets App Scripts][gsas].

#### 🏦 Tax Amount

Calculate the tax amount based on a value and a range of tax brackets.

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const simpleTaxBracket = [
[ 0, 10_000, 0.00],
[10_000, 25_000, 0.10],
Expand All @@ -34,12 +64,12 @@ console.log(
// => 2_500.00
```

### 🚕 Tax Basis
#### 🚕 Tax Basis

Given an amount, it'll return the basis that would result in `amount` if you included tax.

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const simpleTaxBracket = [
[ 0, 10_000, 0.00],
[10_000, 25_000, 0.10],
Expand All @@ -51,12 +81,12 @@ console.log(
// => 14_545.45
```

### 🛋️ Append Deduction to Bracket
#### 🛋️ Append Deduction to Bracket

Instead of subtracting your standard deduction, craft a new tax bracket set with a standard deduction built in.

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const simpleTaxBracket = [
[ 0, 10_000, 0.00],
[10_000, 25_000, 0.10],
Expand All @@ -74,12 +104,12 @@ console.log(
*/
```

### 🧲 Merge Tax Brackets
#### 🧲 Merge Tax Brackets

Merge two tax brackets into one bracket.

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const simpleFederal = [
[ 0, 10_000, 0.00],
[10_000, 25_000, 0.10],
Expand All @@ -105,13 +135,13 @@ console.log(
*/
```

### 🧱 Stack Tax Brackets
#### 🧱 Stack Tax Brackets

Stack two tax brackets on a pivot. It's common to pivot on ordinary income,
while stack capital gains income on top.

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const ordinaryIncome = 25_000
const simpleIncome = [
[ 0, 15_000, 0.01],
Expand Down Expand Up @@ -140,10 +170,10 @@ console.log(
*/
```

### 📏 Amount By Rate
#### 📏 Amount By Rate

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')
const goalEffectiveTaxRate = 0.20
const taxBracket = [
[ 0, 10_275, 0.10],
Expand All @@ -161,7 +191,7 @@ console.log(toWithdraw) // 154_099.75
console.log(tp.taxRate(toWithdraw, taxBracket)) // 0.20
```

#### 📐 Complex Amount By Rate
##### 📐 Complex Amount By Rate

```js
const goalEffectiveTaxRate = 0.14
Expand Down Expand Up @@ -206,7 +236,7 @@ which you can use to generate the tax amount for various scenarios.
[💡 View the full Example][example]

```js
const tp = require('tax-planning.js')
const tp = require('taxPlanning.js')

// snippet from `./test/fullYearTaxAmount.js`
const federalTaxBracket = tp.stackTaxBrackets(
Expand Down Expand Up @@ -257,7 +287,7 @@ const actualAmount = tp.taxAmount(
Requires node v19.4 or greater.

```
git clone [email protected]:mxbaylee/tax-planning.js.git
git clone [email protected]:mxbaylee/taxPlanning.js.git
npm install
npm test
```
Expand Down

0 comments on commit 38ee992

Please sign in to comment.