<!-- AUTO-GENERATED:reference -->
---
title: API Reference
description: Complete API reference for @primebrick/decimal — every exported symbol.
---

# API Reference

Every exported symbol from `@primebrick/decimal`, rendered mechanically from the
TypeDoc extraction. This page is regenerated from `docs/dev-guide/_extracted/api.json`
on every `pnpm extract-docs` run — do not edit by hand.

## Classes

### `Decimal`

| Property | Type | Description |
|----------|------|-------------|
| v | `bigint` | Unscaled integer: `value = v × 10^-scale`. |
| scale | `number` | Number of base-10 digits after the decimal point. Always `>= 0`. |
| periodic | `boolean` | Provenance flag: the producing operation truncated a non-terminating expansion. |

#### `Decimal(v, scale, periodic)`

Internal constructor — prefer `dec()`, `fromPG()`, `fromNumber()`, `fromBigInt()`.

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `bigint` |  |
| scale | `number` |  |
| periodic | `boolean` |  |

#### `Decimal.toString(): string`

Canonical plain decimal string, e.g. `-12.3400` (scale preserved).

#### `Decimal.toJSON(): string`

Wire form for ext-json / JSON.stringify: `"12.34d"` — a self-describing
string so the value survives naive `JSON.parse` visibly typed and can be
revived by schema-aware hydration (`fromWire`).

#### `Decimal.toNumber(): number`

Lossy coercion — may round. Use only for display hints, never for math.

### `DecimalError`

Errors raised by @primebrick/decimal.

| Property | Type | Description |
|----------|------|-------------|
| code | `"INVALID_INPUT" \| "NON_FINITE" \| "DIVISION_BY_ZERO" \| "INVALID_SCALE" \| "INVALID_ROUNDING"` |  |

#### `DecimalError(code, message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| code | `"INVALID_INPUT" \| "NON_FINITE" \| "DIVISION_BY_ZERO" \| "INVALID_SCALE" \| "INVALID_ROUNDING"` |  |
| message | `string` |  |

## Types & Enums

### `DecimalInput`

Anything coercion functions accept: Decimal, native number, bigint, or a decimal string.

**Type:** `Decimal \| number \| bigint \| string`

### `RoundingMode`

**Type:** `"UP" \| "DOWN" \| "CEILING" \| "FLOOR" \| "HALF_UP" \| "HALF_DOWN" \| "HALF_EVEN"`

## Constants

### `fromPG`

Alias of `dec()` — parse a PostgreSQL `numeric`/`decimal` text value.

**Type:** `(input: DecimalInput) => Decimal`

### `fromString`

**Type:** `(input: DecimalInput) => Decimal`

### `fromWire`

Alias of `dec()` — tolerates the `"…d"` wire suffix.

**Type:** `(input: DecimalInput) => Decimal`

### `NUMERIC_MIN_SIG_DIGITS`

Minimum significant digits preserved by automatic `div` scale — mirrors
PostgreSQL `NUMERIC_MIN_SIG_DIGITS` (16). See `pgDivScale`.

**Type:** `16`

### `ONE`

**Type:** `Decimal`

### `TEN`

**Type:** `Decimal`

### `ZERO`

**Type:** `Decimal`

## Functions

### `abs(d): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `add(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `ceil(d): Decimal`

Smallest integer `>= d`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `cmp(a, b): -1 \| 0 \| 1`

Numeric comparison ignoring scale: `cmp(1.0, 1.00) === 0`. Returns -1 | 0 | 1.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `dec(input): Decimal`

`Decimal` — pass-through. `string` — parsed (PG text form or `"…d"` wire form). `number` — via shortest round-trip `toString` so `0.1` stays `"0.1"`. `bigint` — scale 0.

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `DecimalInput` |  |

### `div(a, b, opts): Decimal`

`a / b`. Without `scale`, the result uses the PostgreSQL `numeric`
division rule (`pgDivScale` — e.g. `1/3` → scale 20, `10/4` → 16), so
Decimal↔DB computations compare equal digit-for-digit. Rounding defaults
to `HALF_UP`. When the true quotient does not terminate at the target
scale the result is flagged `periodic` (`isPeriodic(d)` → true).

  div(1, 3)            // 0.33333333333333333333 — periodic
  div(10, 4)           // 2.5000000000000000
  div(1, 3, 2)         // 0.33
  div(a, b, &#123; scale: 6, rounding: "HALF_EVEN" &#125;)

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |
| opts | `number \| { scale: number; rounding: RoundingMode }` |  |

### `eq(a, b): boolean`

Numeric equality ignoring scale — `eq(1.0, 1.00)` is `true`.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `floor(d): Decimal`

Largest integer `<= d`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `fromBigInt(v, scale): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `bigint` |  |
| scale | `number` |  |

### `fromNumber(n): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| n | `number` |  |

### `isDecimal(v): v is Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `unknown` |  |

### `isPeriodic(d): boolean`

`true` when the value was produced by a truncated non-terminating division.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `max(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `min(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `mod(a, b): Decimal`

`a mod b` — remainder of truncated division at the common scale.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `mul(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `neg(d): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `normalize(d): Decimal`

Strip trailing fractional zeros — `1.230` → `1.23`, `12.000` → `12`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `parseDecimal(input): Decimal`

Parse a decimal string into unscaled form.
Accepts: `"12"`, `"-0.5"`, `".5"`, `"5."`, `"1.5e3"`, `"1E-3"`, `"+4"`.
Rejects: `NaN`, `Infinity`, empty strings, hex, non-numeric garbage.
Scale is preserved as written (`"1.230"` → scale 3).

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `string` |  |

### `pgDivScale(a, b): number`

PostgreSQL-faithful result scale for `x / y` (mirrors `select_div_scale`):
`max(16 - 4·qweight, x.scale, y.scale)` — 16 significant digits minimum.
Verified live: `1/3`→20, `10/4`→16, `1.00/8`→20, `2/1`→16, `100/3`→16.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `pow10(n): bigint`

| Parameter | Type | Description |
|-----------|------|-------------|
| n | `number` |  |

### `rescale(d, newScale, mode): Decimal`

Re-express `d` at `newScale`. Growing is exact; shrinking applies `mode`
(default `HALF_UP`, matching PostgreSQL `round()`).

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |
| newScale | `number` |  |
| mode | `RoundingMode` |  |

### `round(d, scale, mode): Decimal`

Round to `scale` fractional digits (default `HALF_UP`).

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |
| scale | `number` |  |
| mode | `RoundingMode` |  |

### `signum(d): -1 \| 0 \| 1`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `strictEq(a, b): boolean`

Exact structural equality — value AND scale must match (`strictEq(1.0, 1.00)` is `false`).

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `sub(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `toPG(d): string`

PostgreSQL parameter form — plain canonical decimal string, no `d` suffix.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `toWire(d): string`

Wire form — `"…d"` suffixed string.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `trunc(d): Decimal`

Integer part, toward zero.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

<!-- END -->