feat(ts): branded Cents/Dollars money types — first TS conversion (T2)
Converted client/lib/money.js -> money.ts with branded types:
type Cents = number & { __unit: 'cents' }
type Dollars = number & { __unit: 'dollars' }
plus asCents/asDollars/centsToDollars/dollarsToCents. The formatters now require
the correct branded unit (a bare number won't do), so a typed caller physically
cannot format cents as dollars (the 100×-too-big bug) or vice-versa. Existing
.jsx callers are unaffected (checkJs off) — gradual adoption.
money.type-test.ts is a compile-time guard (never imported/bundled): its
@ts-expect-error lines assert each unit mixup is a real error, so typecheck
fails loudly if the branding ever regresses. Verified: removing a guard makes
tsc error 'Argument of type 1234 is not assignable to DollarsInput'.
typecheck + build (with React Compiler) + 48 client tests all green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
null
parent
907a407399
commit
255036afc2
|
|
@ -1,77 +0,0 @@
|
||||||
// Currency formatting for the client, mirroring the server's utils/money.js.
|
|
||||||
//
|
|
||||||
// The API sends money in two units: bill / summary values are serialized as
|
|
||||||
// DOLLARS (the server calls fromCents before responding), while raw bank
|
|
||||||
// transaction amounts arrive as integer CENTS. So there are two entry points —
|
|
||||||
// formatUSD(dollars) and formatCentsUSD(cents) — matching the server's
|
|
||||||
// formatUSD / formatCentsUSD split. USD / en-US throughout (the app is USD-only,
|
|
||||||
// and this matches the server). Inputs are coerced defensively so null, '',
|
|
||||||
// undefined, or NaN never render as "$NaN".
|
|
||||||
|
|
||||||
const DASH = '—';
|
|
||||||
|
|
||||||
function toNumber(value) {
|
|
||||||
const n = Number(value);
|
|
||||||
if (!Number.isFinite(n)) return 0;
|
|
||||||
return n === 0 ? 0 : n; // normalize -0 → +0 so it never renders as "-$0.00"
|
|
||||||
}
|
|
||||||
|
|
||||||
function isBlank(value) {
|
|
||||||
return value === null || value === undefined || value === '';
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Format a DOLLAR amount → "$1,234.56".
|
|
||||||
* @param {number|string|null} dollars
|
|
||||||
* @param {{ whole?: boolean, dash?: boolean }} [opts]
|
|
||||||
* whole — drop the cents ("$1,235"); dash — render blank input as "—" not "$0.00".
|
|
||||||
*/
|
|
||||||
export function formatUSD(dollars, { whole = false, dash = false } = {}) {
|
|
||||||
if (dash && isBlank(dollars)) return DASH;
|
|
||||||
return toNumber(dollars).toLocaleString('en-US', {
|
|
||||||
style: 'currency',
|
|
||||||
currency: 'USD',
|
|
||||||
minimumFractionDigits: whole ? 0 : 2,
|
|
||||||
maximumFractionDigits: whole ? 0 : 2,
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Whole-dollar convenience → "$1,235". */
|
|
||||||
export function formatUSDWhole(dollars, opts = {}) {
|
|
||||||
return formatUSD(dollars, { ...opts, whole: true });
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Format an integer-CENTS amount (e.g. a bank transaction) → "$12.34".
|
|
||||||
* @param {number|string|null} cents
|
|
||||||
* @param {{ signed?: boolean, dash?: boolean, currency?: string }} [opts]
|
|
||||||
* signed — prefix "+"/"-" (income vs expense); dash — blank input → "—";
|
|
||||||
* currency — ISO code (defaults USD).
|
|
||||||
*/
|
|
||||||
export function formatCentsUSD(cents, { signed = false, dash = false, currency = 'USD' } = {}) {
|
|
||||||
if (dash && isBlank(cents)) return DASH;
|
|
||||||
const c = toNumber(cents);
|
|
||||||
const body = (Math.abs(c) / 100).toLocaleString('en-US', {
|
|
||||||
style: 'currency',
|
|
||||||
currency: currency || 'USD',
|
|
||||||
minimumFractionDigits: 2,
|
|
||||||
maximumFractionDigits: 2,
|
|
||||||
});
|
|
||||||
if (signed) return (c < 0 ? '-' : '+') + body;
|
|
||||||
return (c < 0 ? '-' : '') + body;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Shared form validator for a non-negative money field (dollars). Blank is
|
|
||||||
* allowed (returns ''); otherwise the value must parse to a number ≥ 0. Returns
|
|
||||||
* '' when valid, or an error string labelled for the field. Zero is allowed —
|
|
||||||
* these are non-negative, not strictly-positive, amounts.
|
|
||||||
* @param {number|string|null} val
|
|
||||||
* @param {string} [label] — field name for the message (e.g. "Amount", "Balance")
|
|
||||||
*/
|
|
||||||
export function validateNonNegativeMoney(val, label = 'Amount') {
|
|
||||||
if (val === '' || val === null || val === undefined) return '';
|
|
||||||
const num = parseFloat(val);
|
|
||||||
if (isNaN(num) || num < 0) return `${label} must be a non-negative number`;
|
|
||||||
return '';
|
|
||||||
}
|
|
||||||
|
|
@ -0,0 +1,108 @@
|
||||||
|
// Currency formatting for the client, mirroring the server's utils/money.js.
|
||||||
|
//
|
||||||
|
// The API sends money in two units: bill / summary values are serialized as
|
||||||
|
// DOLLARS (the server calls fromCents before responding), while raw bank
|
||||||
|
// transaction amounts arrive as integer CENTS. So there are two entry points —
|
||||||
|
// formatUSD(dollars) and formatCentsUSD(cents) — matching the server's
|
||||||
|
// formatUSD / formatCentsUSD split. USD / en-US throughout. Inputs are coerced
|
||||||
|
// defensively so null, '', undefined, or NaN never render as "$NaN".
|
||||||
|
//
|
||||||
|
// The two units are *branded* below: a Dollars value can't be passed where Cents
|
||||||
|
// is expected (or vice-versa) without an explicit conversion, so the cents↔dollars
|
||||||
|
// mixups that have caused real money bugs (e.g. displaying cents as dollars →
|
||||||
|
// 100× wrong) become compile errors in typed code.
|
||||||
|
|
||||||
|
/** Integer cents, e.g. a raw bank transaction amount (1234 = $12.34). */
|
||||||
|
export type Cents = number & { readonly __unit: 'cents' };
|
||||||
|
/** Dollars, e.g. an API-serialized bill amount (12.34 = $12.34). */
|
||||||
|
export type Dollars = number & { readonly __unit: 'dollars' };
|
||||||
|
|
||||||
|
/** Brand a raw number as cents (the sanctioned way to enter the typed world). */
|
||||||
|
export const asCents = (n: number): Cents => n as Cents;
|
||||||
|
/** Brand a raw number as dollars. */
|
||||||
|
export const asDollars = (n: number): Dollars => n as Dollars;
|
||||||
|
/** Convert cents → dollars (the only way to cross the unit boundary). */
|
||||||
|
export const centsToDollars = (c: Cents): Dollars => (c / 100) as Dollars;
|
||||||
|
/** Convert dollars → cents, rounding to the nearest cent. */
|
||||||
|
export const dollarsToCents = (d: Dollars): Cents => Math.round(d * 100) as Cents;
|
||||||
|
|
||||||
|
// A money value as it may still arrive untyped from a form field or legacy code:
|
||||||
|
// the branded unit, or a numeric string, or blank. Note bare `number` is NOT
|
||||||
|
// included — that's deliberate, so typed callers must brand (asDollars/asCents)
|
||||||
|
// and can't accidentally hand cents to a dollars formatter.
|
||||||
|
type DollarsInput = Dollars | string | null | undefined;
|
||||||
|
type CentsInput = Cents | string | null | undefined;
|
||||||
|
|
||||||
|
const DASH = '—';
|
||||||
|
|
||||||
|
function toNumber(value: unknown): number {
|
||||||
|
const n = Number(value);
|
||||||
|
if (!Number.isFinite(n)) return 0;
|
||||||
|
return n === 0 ? 0 : n; // normalize -0 → +0 so it never renders as "-$0.00"
|
||||||
|
}
|
||||||
|
|
||||||
|
function isBlank(value: unknown): value is null | undefined | '' {
|
||||||
|
return value === null || value === undefined || value === '';
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Format a DOLLAR amount → "$1,234.56".
|
||||||
|
* `whole` drops the cents ("$1,235"); `dash` renders blank input as "—".
|
||||||
|
*/
|
||||||
|
export function formatUSD(
|
||||||
|
dollars: DollarsInput,
|
||||||
|
{ whole = false, dash = false }: { whole?: boolean; dash?: boolean } = {},
|
||||||
|
): string {
|
||||||
|
if (dash && isBlank(dollars)) return DASH;
|
||||||
|
return toNumber(dollars).toLocaleString('en-US', {
|
||||||
|
style: 'currency',
|
||||||
|
currency: 'USD',
|
||||||
|
minimumFractionDigits: whole ? 0 : 2,
|
||||||
|
maximumFractionDigits: whole ? 0 : 2,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Whole-dollar convenience → "$1,235". */
|
||||||
|
export function formatUSDWhole(
|
||||||
|
dollars: DollarsInput,
|
||||||
|
opts: { dash?: boolean } = {},
|
||||||
|
): string {
|
||||||
|
return formatUSD(dollars, { ...opts, whole: true });
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Format an integer-CENTS amount (e.g. a bank transaction) → "$12.34".
|
||||||
|
* `signed` prefixes "+"/"-" (income vs expense); `dash` renders blank → "—";
|
||||||
|
* `currency` is an ISO code (defaults USD).
|
||||||
|
*/
|
||||||
|
export function formatCentsUSD(
|
||||||
|
cents: CentsInput,
|
||||||
|
{ signed = false, dash = false, currency = 'USD' }: { signed?: boolean; dash?: boolean; currency?: string } = {},
|
||||||
|
): string {
|
||||||
|
if (dash && isBlank(cents)) return DASH;
|
||||||
|
const c = toNumber(cents);
|
||||||
|
const body = (Math.abs(c) / 100).toLocaleString('en-US', {
|
||||||
|
style: 'currency',
|
||||||
|
currency: currency || 'USD',
|
||||||
|
minimumFractionDigits: 2,
|
||||||
|
maximumFractionDigits: 2,
|
||||||
|
});
|
||||||
|
if (signed) return (c < 0 ? '-' : '+') + body;
|
||||||
|
return (c < 0 ? '-' : '') + body;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Shared form validator for a non-negative money field (dollars). Blank is
|
||||||
|
* allowed (returns ''); otherwise the value must parse to a number ≥ 0. Returns
|
||||||
|
* '' when valid, or an error string labelled for the field. Zero is allowed —
|
||||||
|
* these are non-negative, not strictly-positive, amounts.
|
||||||
|
*/
|
||||||
|
export function validateNonNegativeMoney(
|
||||||
|
val: string | number | null | undefined,
|
||||||
|
label = 'Amount',
|
||||||
|
): string {
|
||||||
|
if (val === '' || val === null || val === undefined) return '';
|
||||||
|
const num = parseFloat(String(val));
|
||||||
|
if (isNaN(num) || num < 0) return `${label} must be a non-negative number`;
|
||||||
|
return '';
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
// Compile-time guard for the branded money types. Not imported anywhere (so it
|
||||||
|
// never ships in a bundle); `npm run typecheck` type-checks it via the tsconfig
|
||||||
|
// include, and each `@ts-expect-error` asserts the following line IS a genuine
|
||||||
|
// type error. If the cents/dollars branding ever regresses, one of these lines
|
||||||
|
// stops erroring and typecheck fails loudly ("unused @ts-expect-error").
|
||||||
|
import { formatUSD, formatCentsUSD, asCents, asDollars, centsToDollars } from './money';
|
||||||
|
|
||||||
|
const cents = asCents(1234); // $12.34 as integer cents
|
||||||
|
const dollars = asDollars(12.34); // $12.34 as dollars
|
||||||
|
|
||||||
|
// ✅ Correct unit → compiles fine.
|
||||||
|
formatUSD(dollars);
|
||||||
|
formatCentsUSD(cents);
|
||||||
|
formatUSD(centsToDollars(cents)); // cross the boundary explicitly
|
||||||
|
|
||||||
|
// ❌ Unit mixups → compile errors (the class of bug we keep fixing).
|
||||||
|
// @ts-expect-error cents can't be formatted as dollars (would render 100× too big)
|
||||||
|
formatUSD(cents);
|
||||||
|
// @ts-expect-error dollars can't be formatted as cents
|
||||||
|
formatCentsUSD(dollars);
|
||||||
|
// @ts-expect-error a raw number must be branded (asDollars/asCents) first
|
||||||
|
formatUSD(1234);
|
||||||
Loading…
Reference in New Issue