Money

export interface Money {
  readonly minor: number;
  readonly currency: string;
  /** Decimal places `minor` counts, when they are not the currency's own. */
  readonly scale?: number;
}

Integer minor units + a three-letter uppercase code — the ISO-4217 rows the framework ships (53, As of 2026-08 — Currency exponents), plus whatever the app registers. Never a float, never a number in a column, never a currency-less amount.

The ceiling: 9,007,199,254,740,991 minor units

minor is a JavaScript number, so the largest amount a Money can carry is Number.MAX_SAFE_INTEGER — 9,007,199,254,740,991 minor units. In USD cents that is roughly $90 trillion; in JPY, ¥9 quadrillion.

Past it, refused. Never truncated, never widened, never rounded into the row. fromMinor(2 ** 53, 'USD') throws X_MONEY_NOT_INTEGER, and t.money fails the same value at the HTTP boundary with the field path attached — the same refusal twice, so a body that would have failed at the row write fails at the door instead.

That is deliberate. minor is not a bigint because money is projected onto every wire this framework generates: JSON.stringify refuses a bigint, and t.money is the OpenAPI contract. A silently-widened amount that crashes the response three layers away is worse than a loud refusal at the boundary. Migrating an app with amount columns that might exceed it: Migrating an existing app carries the audit query.

scale — sub-minor precision, without a second money type

scale names the decimal places minor counts, when they are not the currency's own. Absent — the shape every value and every row already had — means the currency's natural minor unit: 2 for USD, 0 for JPY, 3 for KWD.

fromMinor(1999, 'USD');            // $19.99      — no scale key, the currency's own minor unit
fromMinor(2, 'USD', 6);            // $0.000002   — minor counts millionths
toDecimalString(fromMinor(2, 'USD', 6));   // '0.000002'

fromDecimal('12.9999', 'USD', { scale: 4 }) keeps every digit. Without the scale, more fraction digits than the currency has is X_MONEY_NOT_INTEGER, and its fix: offers the exact scale that would keep them.

One declaration, three names. @ultimat3/schema's MoneyValue is the type; @ultimat3/money's Money and @ultimat3/entity's MoneyValue are aliases of it, not restatements of its shape. It lives at tier 0 because that is the only tier every package may import. A row a money() column decodes therefore is a Money — pass it to add(), formatMoney() or <Money> with no conversion and no cast.

The column is still bigint, wider than the value it holds — see the range rule under Storage.

{ minor: 1999, currency: 'USD' } is $19.99. { minor: 1999, currency: 'JPY' } is ¥1999. The exponent comes from the currency table, never from an assumed / 100.

Why not a float

An integer count of minor units is exact, and the currency travels with it so a mismatch is catchable.

Storage

Three columns per amount. No JSON blob, no numeric amount, no float.

Entities declare a money field once and the generated migration emits all three columns plus the checks. See Entities and migrations.

A table this framework did not create names its own columns. money({ columns: … }) maps the three onto what is already there, merged per part over the <name>_minor / <name>_currency / <name>_scale defaults — so a legacy amount_cents beside a currency is two words, not three:

total: money({ columns: { minor: 'amount_cents', currency: 'currency', scale: null } }),

scale: null says the table has no scale column at all. What that costs is that every amount is then at the currency's own minor unit — which is exactly what an absent scale already meant, so it costs no correctness. Adopting a live schema: Migrating an existing app.

An amount column with no currency column beside it is not adoptable as money(), and should not be. A Money is an amount and a currency by construction; a single implied currency is the bug the type exists to prevent, and a framework that guessed one would guess on every row. Declare such a column as decimal({ precision, scale }) and carry the currency in your own column.

<name>_scale is not addressable as a predicate or a sort key. A scale says which units minor counts, so ordering or filtering by it compares two different questions.

The column is wider than the value, and the gap is a refusal. bigint holds more than a JS number does, so a <name>_minor past ±2^53 — written by a psql session, a backfill, another service, never by this framework — is refused when it is read (X_INVARIANT_VIOLATED, naming the value). It is never rounded into the row, and never carried as a bigint that would crash the response three layers later. @ultimat3/realtime refuses the identical value for the identical reason, so the two readers of one column agree.

A writer may still hand a bigint — MoneyInput is { minor: bigint | number; currency: string }, so a minor unit read straight off a bigint column reaches an insert with no conversion at the call site. Both drivers narrow it to the value type before storing, so what a row holds never depends on which one you built.

Operations

Allowed, total, and typed. As of 2026-08 the package ships the currency table, the rounding modes, the error codes, and the arithmetic surface below.

Rejected

Total across a currency boundary requires a conversion first. Silent coercion is how a marketplace bills in the wrong currency for a quarter.

Rounding modes

DEFAULT_ROUNDING is 'half-up'. Four modes, ROUNDING_MODES in declaration order:

roundToInteger(value, mode) rounds fractional minor units; roundToDigits(value, digits, mode) is used when a decimal string is more precise than the currency's minor unit; roundRatio(numerator, denominator, mode) rounds an exact bigint fraction, which is what multiply, divide, convert and fromDecimal all use. A float product can only judge a value IEEE-754 has already moved — 100 * 1.005 is 100.49999999999999, so half-up would answer 100 where the exact 100.5 owes 101, charging a 0.5% fee on €1.00 as nothing.

-0 is never produced: an amount rounding to nothing stays 0, because JSON.stringify writes -0 as 0 while Object.is and any keyed Map see a different value.

Changing rounding mode shifts every tie by one minor unit

A tie — an exact .5 fractional minor unit — is where the modes disagree, and they disagree by exactly one minor unit every time. Under half-up the shift is systematic (always away from zero); under half-even it is balanced (half the ties go each way). That is why the two diverge with row count instead of cancelling, and why a migrating app that silently changes mode moves a reconciled ledger.

import { fromMinor, multiply } from '@ultimat3/money';

const one = fromMinor(100, 'USD');                  // $1.00

multiply(one, 0.125);                           // { minor: 13, currency: 'USD' } — the default, half-up
multiply(one, 0.125, 'half-up');                // { minor: 13, … }   $0.13
multiply(one, 0.125, 'half-even');              // { minor: 12, … }   $0.12  — 12 is even
multiply(one, 0.125, 'down');                   // { minor: 12, … }
multiply(one, 0.125, 'up');                     // { minor: 13, … }

12.5 minor units, four answers. One cent per tie, in one direction, over however many rows tie.

What other stacks default to

As of 2026-08, and each is configurable — check what your app actually set, not what its ecosystem defaults to.

Migrating, do this in order:

A shift of ±1 minor unit is invisible on one invoice and is a reconciliation failure across millions of rows.

Currency exponents

The exponent table is data, not an assumption. As of 2026-08 it ships 53 ISO-4217 rows (packages/money/src/currency.ts:21).

exponentOf(currency) and scaleOf(currency) derive from the table. A hardcoded / 100 is wrong in nine of the codes above.

Registering a currency

As of 2026-08 the table is open, and it is opened by a call — not by config, not by a fork. 53 of roughly 180 ISO codes is a convention, and axiom 8 says an app encodes its own by calling a function.

import { fromMinor, registerCurrency, toDecimalString } from '@ultimat3/money';

// Once at boot, before any XBT amount is built.
registerCurrency({ code: 'XBT', exponent: 8, name: 'Bitcoin' });

const dust = fromMinor(1, 'XBT');
toDecimalString(dust); // '0.00000001'

A local currency, a scrip, a loyalty point, a token — anything the shipped rows do not carry.

Why the table opened

Three layers already treated the currency set as open, and only arithmetic disagreed. All three now read one declaration — CURRENCY_CODE_PATTERN = '^[A-Z]{3}$' in packages/schema/src/money-value.ts.

So an app could already take GHS over HTTP, validate it, write it to Postgres and read it back — and add() was the only thing that refused it. The set was never closed; one package disagreed with the boundary, the storage layer and the contract it publishes. CurrencyCode is string, not a union, and the table had zero consumers outside packages/money/ — nothing depended on it being total.

The pattern stays inside the syntax ECMAScript, JSON Schema and POSIX ERE spell identically. A \d, a lookahead or a non-greedy quantifier would make the Postgres CHECK stop meaning what isCurrencyCode means, and a real server is the first thing that would say so.

Formatting

Edge only — a route or a component. Never in a service, repo, or job.

import { formatMoney } from '@ultimat3/money';

toDecimal is for machine consumers (CSV, API payloads, accounting exports). formatMoney is for humans. They are not interchangeable.

An amount a person typed — parseAmount

As of 2026-11-06. parseAmount(text, { currency, locale }) reads the separators and digits of the person's locale off Intl.NumberFormat, then hands the digits to fromDecimal as a string: no float, ever.

The locale's currency symbol and the currency code are ignored, a sign is - or the locale's minus. Every refusal is X_MONEY_INPUT_INVALID (422), whose cause names the character: re-prompt the person, never round or guess.

Where money appears in the framework

export const summarize = llm({
  model: 'claude-sonnet-5-5',
  input:  t.object({ postId: t.uuid }),
  output: t.object({ summary: t.string, tags: t.string.array() }),
  prompt: summarizePrompt,                       // versioned artifact
  cache:  { semantic: { threshold: 0.97, ttl: '7d' } },
  budget: { tokensIn: 8000, costPerCall: { minor: 5, currency: 'USD' } },
  policy: can('post:read'),
});

See MCP and AI.

Errors

Full list: Error codes.

Rules

• Money = { readonly minor: number; readonly currency: string }. No other money type exists — MoneyValue in @ultimat3/schema and in @ultimat3/entity is the same declaration under another name.
• Never a float. Never a bare number for an amount. Never a bigint on a row.
• Two columns: integer minor + char(3) currency. A stored minor unit past ±2^53 is refused on read, never rounded.
• Same currency or throw. No implicit conversion, ever.
• A non-integer multiplier requires an explicit rounding mode.
• allocate distributes the remainder; the parts always sum to the whole.
• Exponents come from the currency table, never from 100.
• A currency the shipped rows lack is registerCurrency({ code, exponent, name }) at boot, never a fork of the table.
• Format at the edge with an explicit locale and currency → I18n.