README.md

   1 # ustaxlib
   2
   3 This project provides modules for modeling the US tax system for individuals. The `ustaxlib/core`
   4 module provides a generic framework for defining tax return forms. And peer modules like
   5 `ustaxlib/fed2019` provide forms for specific revisions/years of tax returns.
   6
   7 There is a peer project [ustaxviewer](https://github.com/rsesek/ustaxviewer) that can render a tax
   8 return as HTML.
   9
  10 ## Core
  11
  12 The `ustaxlib/core` module provides a very simple data model for tax returns:
  13
  14 - `TaxReturn`: An abstract class that is the root of the object graph. It holds at least one
  15     `Person` and several `Form`s.
  16 - `Person`: A person for whom the `TaxReturn` is being computed.
  17 - `Form`: An abstract class that represents a single form in the tax system. Holds one or more
  18     `Line`s. `Form`s optionally take an input object, the values of which are typically exposed
  19     by an `InputLine`.
  20 - `Line`: An abstract class, with several concrete subclasses provided by core, that corresponds to
  21     a single line on a tax system form. A `Line`'s parametrized type corresponds to the type of
  22     value that is computed by it. Examples are:
  23    - `ComputedLine`: Uses a function to produce a value.
  24    - `ReferenceLine`: Returns the value of a specific line of a `Form`.
  25    - `InputLine`: Returns the value of a `Form`'s input.
  26    - `AccumulatorLine`: Some `Form`s can have multiple instances in a `TaxReturn`, and this line
  27        sums a specific line for all instances of that form type.
  28
  29 The core module provides what is effectively a specialized spreadsheet. Rather than sheets and rows,
  30 there are forms and lines. A `TaxReturn` provides a way to find forms by their type, and a `Form`
  31 provides access to the values computed by `Line`s.
  32
  33 ## Models
  34
  35 Currently ustaxlib supports the following models:
  36
  37 - [**fed2019**](src/fed2019/README.md)
  38
  39 ## Getting Started
  40
  41 To start using the software, create a new, private NPM project, and install the necessary
  42 dependencies. This will also install the HTML viewer. Then copy an example file and run the viewer
  43 with it.
  44
  45     npm init
  46     # answer questions
  47     npm i ts-node typescript ustaxlib ustaxviewer
  48     cp node_modules/ustaxlib/examples/fed2019.ts .
  49     npx ustaxviewer-ts fed2019.ts
  50
  51 ## Contributing
  52
  53 Contributions to address bugs and not-supported forms or situations are welcome. Only forms for
  54 individuals are accepted (no estates, trusts, businesses, etc.). Please include tests with your
  55 contribution and keep your commit history clean.
  56
  57 Issues should be filed on [GitHub](https://github.com/rsesek/ustaxlib).
  58
  59 ## Anticipated Answers
  60
  61 ### Why?
  62
  63 This project can be used to check the values produced by other tax software, to model expected tax
  64 liability throughout the year, or to learn about the US tax system.
  65
  66 ### Should I use this to file my own tax returns?
  67
  68 Please, heck no. There are guaranteed to be bugs in this software. The models do not support every
  69 and situation. This software is provided with no warranty.
  70
  71 ### How well does it work?
  72
  73 I have run my personal income tax information through the fed2019 model and received identical
  74 results to the commercial tax prep software I'm using to actually file my tax returns. My situation
  75 is moderately complex, and it exercises most of the forms in the fed2019 module. Your results may
  76 vary.