@carlo-finance/tax-engine

Tax calculation engine for personal financial planning.

Built with Effect — a TypeScript framework for composable, type-safe programs.

Status

Pre-release. Do not depend on this package yet.

How it's shaped

ARCHITECTURE.md — the three-layer chain (model → accounting → engine), the engine's internal subsystem map, the public API contract, and pointers into the specs.

docs/MODULE-AUTHORING.md — the recipe for adding a rule module with metadata, parameter bindings, diagnostics, provenance, tests, fixtures, ADRs, and changesets.

Install

pnpm add @carlo-finance/tax-engine

Runtime Entry Points

The package root and browser subpath are filesystem-free and can be bundled for browser or other non-Node runtimes:

import { TaxEngine } from "@carlo-finance/tax-engine"
import { TaxEngine as BrowserTaxEngine } from "@carlo-finance/tax-engine/browser"

Both create engines from the embedded runtime parameter index. Node-only source-directory loading lives behind the explicit Node subpath:

import { createTaxEngineFromSourcesDir } from "@carlo-finance/tax-engine/node"

Develop

pnpm install
pnpm test          # vitest, watch mode
pnpm check         # typecheck (no emit)
pnpm lint          # eslint
pnpm build         # ESM + CJS to ./dist

Run a TypeScript file directly via tsx:

pnpm tsx ./path/to/file.ts

Releasing

Versioning and publishing are managed by Changesets.

1. After a code change, run pnpm changeset and answer the prompts to record a changelog entry + bump type.
2. Commit the generated .changeset/*.md file alongside your change.
3. Merging to main triggers .github/workflows/release.yml, which either opens a "Version Packages" PR or — once that PR is merged — publishes to npm.

License

MIT