Contributing

Setup

Code
pnpm install
pnpm build        # tsc → dist/ (prebuild also refreshes docs artifacts)
pnpm test         # vitest — battle-test matrix incl. live-PG golden values
pnpm typecheck    # tsc --noEmit

Conventions

• Functional API only — add(a, b), never a.add(b). Ops accept DecimalInput and return Decimal.
• Immutability — Decimal instances are frozen value objects.
• PG parity — div default scale follows PostgreSQL select_div_scale; HALF_UP is the default rounding (= PG round()).
• No runtime dependencies, no Primebrick deps — this is the leaf of the dependency graph.
• Docs — English; TSDoc on every public function (not the class). The rendered api-reference.mdx is regenerated mechanically — never edit it.

Adding an operation

1. Implement in src/ops.ts (or a new src/ module) — pure bigint math, no Math.* on the value.
2. Export from src/index.ts.
3. Extend the matrix tables in test/decimal.test.ts — include negative, zero, scale-mismatched, and boundary cases.
4. pnpm build regenerates docs/dev-guide/api-reference.mdx — commit it with the change.

Docs pipeline

pnpm extract-docs runs TypeDoc → docs/dev-guide/_extracted/api.json, then scripts/render-api-reference.mjs → api-reference.mdx. prebuild runs the chain on every build, so artifacts stay fresh — commit them with your diff. The institutional site syncs this repo's docs/dev-guide/ from main (scheduled docs-release workflow in primebrick-v3-docs). There is no docs/user-guide/ on purpose — decimal is dev-documentation only and must never enter the product KB.

GitFlow & releases

Work on feature/* from develop. Releases: release/X.Y.Z (minor) or hotfix/X.Y.Z (patch) → merge to main → tag X.Y.Z → CI publishes to npm via OIDC trusted publishing → merge main back to develop.