@stll/money 0.1.0 → 0.2.2

package/dist/index.d.ts

@@ -1,23 +1,10 @@
-//#region src/index.d.ts
+//#region src/cents.d.ts
 /**
- * Branded monetary amounts and minor-unit billing arithmetic.
- *
- * Money in this codebase is stored and computed in minor units
- * ("cents" for USD/EUR, halere for CZK, etc.). The `CentsAmount`
- * brand prevents the canonical 100x bug where a major-unit value
- * (12.50 dollars) is silently mixed with minor-unit math (1250 cents).
+ * The minor-unit brand and its constructors.
  *
- * The brand lives here, in a shared package, so it threads end to end:
- * the same `CentsAmount` flows from a Drizzle column declared with
- * `.$type<CentsAmount>()`, across the API boundary (Eden infers the
- * brand from the handler's return type), into browser previews and back.
- * A plain `number` is not assignable to `CentsAmount`; mint one with
- * `cents()` after validating minor-unit input, or `unsafeCents()` at a
- * documented boundary.
- *
- * Currency-agnostic: the currency code lives alongside the amount in the
- * schema (e.g. invoices.currency); pairing them is the call site's
- * responsibility.
+ * Separate from `index.ts` because `format.ts` mints amounts too: the
+ * conversion helpers there return a `CentsAmount`, and a module the package
+ * entry re-exports cannot import back from that entry without a cycle.
  */
 declare const __cents: unique symbol;
 type CentsAmount = number & {
@@ -26,30 +13,108 @@ type CentsAmount = number & {
 /**
  * Construct a CentsAmount from a value already known to be in minor
  * units. Use at boundaries where the input is validated as an integer
- * minor-unit value (e.g. after Elysia `t.Integer({ minimum: 0 })` or
- * after parsing user input that has been multiplied by 100).
+ * minor-unit value (e.g. after Elysia `tMinorUnitAmount(...)` or after
+ * scaling a typed major-unit amount by the currency's exponent).
  *
- * Throws on non-integer input — money math at the minor-unit level must
- * be exact.
+ * SAFE integer, not merely integer: `Number.isInteger` is true for 2^53 and
+ * everything above it, where the spacing between representable doubles is
+ * larger than one minor unit, so `x + 1 === x` and a total silently stops
+ * moving. An amount that far out is a caller defect rather than a runtime
+ * condition, like a fractional one, so it panics the same way.
  */
-declare const cents: (value: number) => CentsAmount;
+export declare const cents: (value: number) => CentsAmount;
 /**
  * Escape hatch for code paths that genuinely need to attach the brand
  * without a runtime check (test fixtures, generated code). Prefer
  * `cents()` everywhere else; reach for this only with a `// SAFETY:`
  * comment naming why the value is already a valid minor-unit integer.
  */
-declare const unsafeCents: (value: number) => CentsAmount;
-type ProrateHourlyCentsInput = {
+export declare const unsafeCents: (value: number) => CentsAmount;
+//#endregion
+//#region src/format.d.ts
+/**
+ * How many minor units make a major one, for this currency: 100 for CZK, 1 for
+ * JPY, 1000 for KWD. It is a property of the currency and not of the reader, so
+ * the lookup is deliberately locale-independent.
+ *
+ * A malformed code makes the `Intl.NumberFormat` constructor throw, before any
+ * `?? 2` on its result could help, so the fallback has to wrap the call.
+ */
+export declare const currencyMinorUnitDigits: (currency: string) => number;
+type ToMinorUnitsParams = {
+  /**
+   * The amount in major units: the decimal text a form holds, or a number.
+   * Text is preferred where the caller has it, because it is what the person
+   * typed rather than the nearest double to it.
+   */
+  amount: number | string;
+  currency: string;
+};
+/**
+ * A typed major-unit amount as the minor units the currency actually counts:
+ * 12.5 USD is 1250, 1500 JPY is 1500, 12.5 KWD is 12500.
+ *
+ * The scaling is decimal, not a float multiply. `1.005 * 100` is
+ * 100.49999999999999 in binary floating point, so `Math.round` of it is 100
+ * and a $1.005 line item silently loses a cent; the same shortfall appears at
+ * a different decimal for every currency. Splitting the text on the point and
+ * moving the digits instead keeps the amount the person typed: the kept
+ * fraction digits are appended to the whole part, and the first digit dropped
+ * decides a half-up carry on the magnitude.
+ *
+ * Rounding is still the point -- a typed amount carries more places than the
+ * currency has -- and it happens on digits, exactly. Text this cannot parse,
+ * and a result outside the safe integer range, are caller defects: gate the
+ * text with `isDecimalAmount` first.
+ */
+export declare const toMinorUnits: (params: ToMinorUnitsParams) => CentsAmount;
+/**
+ * The same conversion for text nobody has vouched for yet: null when the text
+ * is not a decimal amount, and null when the scaled value would leave the safe
+ * integer range, where a total silently stops adding up.
+ *
+ * A form holds whatever was typed and has to be able to decline it. Everything
+ * past that gate calls `toMinorUnits`, which panics, because by then the
+ * decision has been made.
+ */
+export declare const tryToMinorUnits: ({ amount, currency }: ToMinorUnitsParams) => CentsAmount | null;
+type ToMajorUnitsParams = {
+  amountCents: number;
+  currency: string;
+};
+/** The inverse: a stored amount as the major-unit number a person reads. */
+export declare const toMajorUnits: ({ amountCents, currency }: ToMajorUnitsParams) => number;
+type FormatMoneyCentsParams = {
+  amountCents: number;
+  currency: string;
+  locale: string;
+  /**
+   * Digits to show, minimum and maximum alike. Defaults to the currency's own
+   * exponent; pass 0 for a rounded summary that has no room for decimals.
+   */
+  fractionDigits?: number;
+};
+/**
+ * Money is stored in minor units, and how many of them make a major one is a
+ * property of the currency. Ask the currency rather than assuming a hundred.
+ *
+ * A code `Intl` rejects falls back to the amount beside the raw code: a column
+ * showing "15.00 A1C" is wrong-looking data, which is the truth, where a thrown
+ * RangeError would take the whole board down with it.
+ */
+export declare const formatMoneyCents: ({ amountCents, currency, locale, fractionDigits }: FormatMoneyCentsParams) => string;
+//#endregion
+//#region src/index.d.ts
+export type ProrateHourlyCentsInput = {
   billedMinutes: number;
   hourlyRateCents: CentsAmount;
 };
-declare const prorateHourlyCents: ({ billedMinutes, hourlyRateCents }: ProrateHourlyCentsInput) => CentsAmount;
-type ApplyMarkupCentsInput = {
+export declare const prorateHourlyCents: ({ billedMinutes, hourlyRateCents }: ProrateHourlyCentsInput) => CentsAmount;
+export type ApplyMarkupCentsInput = {
   amountCents: CentsAmount;
   markupPercent: number;
 };
-declare const applyMarkupCents: ({ amountCents, markupPercent }: ApplyMarkupCentsInput) => CentsAmount;
+export declare const applyMarkupCents: ({ amountCents, markupPercent }: ApplyMarkupCentsInput) => CentsAmount;
 declare const __currency: unique symbol;
 /**
  * A `CentsAmount` additionally branded with its ISO 4217-ish currency code
@@ -63,7 +128,7 @@ declare const __currency: unique symbol;
  * currency code is a plain string carried alongside it, so there is no
  * boundary that needs to skip it.
  */
-type CurrencyCents<C extends string = string> = CentsAmount & {
+export type CurrencyCents<C extends string = string> = CentsAmount & {
   readonly [__currency]: C;
 };
 /**
@@ -72,7 +137,7 @@ type CurrencyCents<C extends string = string> = CentsAmount & {
  * from the literal `currency` argument (e.g. `currencyCents("USD", 100)`
  * infers `CurrencyCents<"USD">`).
  */
-declare const currencyCents: <C extends string>(currency: C, amount: number) => CurrencyCents<C>;
+export declare const currencyCents: <C extends string>(currency: C, amount: number) => CurrencyCents<C>;
 type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 type IsSingletonCurrency<C extends string> = string extends C ? never : [C] extends [UnionToIntersection<C>] ? C : never;
 /**
@@ -96,7 +161,7 @@ type IsSingletonCurrency<C extends string> = string extends C ? never : [C] exte
  * instead, which buckets by currency at runtime and is the runtime-correct
  * tool for that case.
  */
-declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurrency<A> extends never ? never : CurrencyCents<A>, b: IsSingletonCurrency<B> extends never ? never : CurrencyCents<B>) => CurrencyCents<A>;
+export declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurrency<A> extends never ? never : CurrencyCents<A>, b: IsSingletonCurrency<B> extends never ? never : CurrencyCents<B>) => CurrencyCents<A>;
 /**
  * Per-currency accumulator for aggregating money across rows that may carry
  * different currencies (e.g. time entries across matters, expenses across
@@ -117,11 +182,11 @@ declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurren
  * the same "never sum across currencies" invariant at runtime via the
  * per-currency `Map`.
  */
-type MoneyTotalsEntry = {
+export type MoneyTotalsEntry = {
   currency: string;
   amountCents: CentsAmount;
 };
-declare class MoneyTotals {
+export declare class MoneyTotals {
   #private;
   /** Add `amountCents` to the running total for `currency`. */
   add(currency: string, amountCents: CentsAmount): void;
@@ -134,4 +199,4 @@ declare class MoneyTotals {
   entries(): MoneyTotalsEntry[];
 }
 //#endregion
-export { ApplyMarkupCentsInput, CentsAmount, CurrencyCents, MoneyTotals, MoneyTotalsEntry, ProrateHourlyCentsInput, addCents, applyMarkupCents, cents, currencyCents, prorateHourlyCents, unsafeCents };
+export type { CentsAmount, FormatMoneyCentsParams, ToMajorUnitsParams, ToMinorUnitsParams };

package/dist/index.js

@@ -1,15 +1,28 @@
-//#region src/index.ts
+import { Result, panic } from "better-result";
+//#region src/cents.ts
+/**
+* The minor-unit brand and its constructors.
+*
+* Separate from `index.ts` because `format.ts` mints amounts too: the
+* conversion helpers there return a `CentsAmount`, and a module the package
+* entry re-exports cannot import back from that entry without a cycle.
+*/
+/** The brand is nominal: every safe integer is a valid minor-unit amount. */
+const isMinorUnitAmount = (value) => Number.isSafeInteger(value);
 /**
 * Construct a CentsAmount from a value already known to be in minor
 * units. Use at boundaries where the input is validated as an integer
-* minor-unit value (e.g. after Elysia `t.Integer({ minimum: 0 })` or
-* after parsing user input that has been multiplied by 100).
+* minor-unit value (e.g. after Elysia `tMinorUnitAmount(...)` or after
+* scaling a typed major-unit amount by the currency's exponent).
 *
-* Throws on non-integer input — money math at the minor-unit level must
-* be exact.
+* SAFE integer, not merely integer: `Number.isInteger` is true for 2^53 and
+* everything above it, where the spacing between representable doubles is
+* larger than one minor unit, so `x + 1 === x` and a total silently stops
+* moving. An amount that far out is a caller defect rather than a runtime
+* condition, like a fractional one, so it panics the same way.
 */
 const cents = (value) => {
-	if (!Number.isInteger(value)) throw new TypeError(`cents(${value}): money values must be integer minor units`);
+	if (!isMinorUnitAmount(value)) return panic(`cents(${value}): money values must be safe integer minor units`);
 	return value;
 };
 /**
@@ -19,6 +32,180 @@ const cents = (value) => {
 * comment naming why the value is already a valid minor-unit integer.
 */
 const unsafeCents = (value) => value;
+//#endregion
+//#region src/format.ts
+/**
+* Moving between a stored minor-unit amount and the major-unit number a
+* person types, and rendering either as text.
+*
+* The brand keeps the arithmetic honest; this keeps the scale honest. Both
+* live here because "how many minor units make a major one" is a property of
+* the currency, and every surface that touches money has to answer it the
+* same way — a workspace column header, a billing form, an invoice line, an
+* export row.
+*
+* The locale is always a parameter. A package cannot read the reader's
+* formatting locale, and one that guessed would render a number differently
+* from the app around it.
+*/
+/**
+* Two, the ISO 4217 default, used when a stored code is one `Intl` will not
+* accept. Validation at the API boundary keeps those out, but a row written
+* before that constraint existed must still render rather than throw.
+*/
+const DEFAULT_MINOR_UNIT_DIGITS = 2;
+/**
+* How many minor units make a major one, for this currency: 100 for CZK, 1 for
+* JPY, 1000 for KWD. It is a property of the currency and not of the reader, so
+* the lookup is deliberately locale-independent.
+*
+* A malformed code makes the `Intl.NumberFormat` constructor throw, before any
+* `?? 2` on its result could help, so the fallback has to wrap the call.
+*/
+const currencyMinorUnitDigits = (currency) => {
+	const resolved = Result.try(() => new Intl.NumberFormat("en", {
+		style: "currency",
+		currency
+	}).resolvedOptions().maximumFractionDigits);
+	if (resolved.isErr()) return DEFAULT_MINOR_UNIT_DIGITS;
+	return resolved.value ?? DEFAULT_MINOR_UNIT_DIGITS;
+};
+/** A decimal amount in major units: an optional sign, digits, an optional point. */
+const DECIMAL_AMOUNT = /^(?<sign>[+-]?)(?<whole>\d*)(?:\.(?<fraction>\d*))?$/u;
+/** Scientific notation, which `String(1e21)` and `String(1e-7)` both produce. */
+const EXPONENT_AMOUNT = /^(?<sign>[+-]?)(?<whole>\d+)(?:\.(?<fraction>\d+))?[eE](?<exponent>[+-]?\d+)$/u;
+/**
+* The widest exponent a finite double prints with (`5e-324`, `1.8e308`).
+* Text past it names no amount any currency stores, and expanding it would
+* mean materialising that many zeros.
+*/
+const MAX_EXPONENT_MAGNITUDE = 324;
+const expandExponent = (text) => {
+	const groups = EXPONENT_AMOUNT.exec(text)?.groups;
+	if (!groups) return null;
+	const exponent = Number(groups["exponent"]);
+	if (Math.abs(exponent) > MAX_EXPONENT_MAGNITUDE) return null;
+	const sign = groups["sign"] ?? "";
+	const digits = `${groups["whole"] ?? ""}${groups["fraction"] ?? ""}`;
+	const point = (groups["whole"] ?? "").length + exponent;
+	if (point <= 0) return `${sign}0.${"0".repeat(-point)}${digits}`;
+	if (point >= digits.length) return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+	return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+};
+/**
+* The amount as decimal text, or null when it is not a decimal amount.
+*
+* A number is rendered by `String`, which produces the SHORTEST text that
+* round-trips back to the same double. That is what makes the number path
+* exact: the double nearest 1.005 prints as "1.005", which is the amount the
+* person typed, where multiplying that double by 100 yields 100.49999999999999.
+*/
+const decimalText = (amount) => {
+	if (typeof amount === "number") {
+		if (!Number.isFinite(amount)) return null;
+		const rendered = String(amount);
+		return rendered.includes("e") ? expandExponent(rendered) : rendered;
+	}
+	const trimmed = amount.trim();
+	return /[eE]/u.test(trimmed) ? expandExponent(trimmed) : trimmed;
+};
+/** The digits of a decimal amount, or null when the text is not one. */
+const amountDigits = (amount) => {
+	const text = decimalText(amount);
+	const groups = text === null ? void 0 : DECIMAL_AMOUNT.exec(text)?.groups;
+	if (groups === void 0) return null;
+	const whole = groups["whole"] ?? "";
+	const fraction = groups["fraction"] ?? "";
+	if (`${whole}${fraction}`.length === 0) return null;
+	return {
+		sign: groups["sign"] ?? "",
+		whole,
+		fraction
+	};
+};
+/**
+* A typed major-unit amount as the minor units the currency actually counts:
+* 12.5 USD is 1250, 1500 JPY is 1500, 12.5 KWD is 12500.
+*
+* The scaling is decimal, not a float multiply. `1.005 * 100` is
+* 100.49999999999999 in binary floating point, so `Math.round` of it is 100
+* and a $1.005 line item silently loses a cent; the same shortfall appears at
+* a different decimal for every currency. Splitting the text on the point and
+* moving the digits instead keeps the amount the person typed: the kept
+* fraction digits are appended to the whole part, and the first digit dropped
+* decides a half-up carry on the magnitude.
+*
+* Rounding is still the point -- a typed amount carries more places than the
+* currency has -- and it happens on digits, exactly. Text this cannot parse,
+* and a result outside the safe integer range, are caller defects: gate the
+* text with `isDecimalAmount` first.
+*/
+const toMinorUnits = (params) => tryToMinorUnits(params) ?? panic(`toMinorUnits(${JSON.stringify(params.amount)}): not an amount ${params.currency} can store`);
+/**
+* The same conversion for text nobody has vouched for yet: null when the text
+* is not a decimal amount, and null when the scaled value would leave the safe
+* integer range, where a total silently stops adding up.
+*
+* A form holds whatever was typed and has to be able to decline it. Everything
+* past that gate calls `toMinorUnits`, which panics, because by then the
+* decision has been made.
+*/
+const tryToMinorUnits = ({ amount, currency }) => {
+	const parsed = amountDigits(amount);
+	if (parsed === null) return null;
+	const digits = currencyMinorUnitDigits(currency);
+	const kept = parsed.fraction.slice(0, digits).padEnd(digits, "0");
+	const dropped = parsed.fraction.charAt(digits);
+	const magnitude = BigInt(`${parsed.whole || "0"}${kept}`) + (dropped >= "5" ? 1n : 0n);
+	const value = Number(parsed.sign === "-" ? -magnitude : magnitude);
+	return Number.isSafeInteger(value) ? cents(value) : null;
+};
+/** The inverse: a stored amount as the major-unit number a person reads. */
+const toMajorUnits = ({ amountCents, currency }) => amountCents / 10 ** currencyMinorUnitDigits(currency);
+/**
+* Money is stored in minor units, and how many of them make a major one is a
+* property of the currency. Ask the currency rather than assuming a hundred.
+*
+* A code `Intl` rejects falls back to the amount beside the raw code: a column
+* showing "15.00 A1C" is wrong-looking data, which is the truth, where a thrown
+* RangeError would take the whole board down with it.
+*/
+const formatMoneyCents = ({ amountCents, currency, locale, fractionDigits }) => {
+	const major = toMajorUnits({
+		amountCents,
+		currency
+	});
+	const digits = fractionDigits ?? currencyMinorUnitDigits(currency);
+	const formatted = Result.try(() => new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency,
+		minimumFractionDigits: digits,
+		maximumFractionDigits: digits
+	}).format(major));
+	return formatted.isErr() ? `${major.toFixed(digits)} ${currency}` : formatted.value;
+};
+//#endregion
+//#region src/index.ts
+/**
+* Branded monetary amounts and minor-unit billing arithmetic.
+*
+* Money in this codebase is stored and computed in minor units
+* ("cents" for USD/EUR, halere for CZK, etc.). The `CentsAmount`
+* brand prevents the canonical 100x bug where a major-unit value
+* (12.50 dollars) is silently mixed with minor-unit math (1250 cents).
+*
+* The brand lives in this package, so it threads end to end:
+* the same `CentsAmount` flows from a Drizzle column declared with
+* `.$type<CentsAmount>()`, across the API boundary (Eden infers the
+* brand from the handler's return type), into browser previews and back.
+* A plain `number` is not assignable to `CentsAmount`; mint one with
+* `cents()` after validating minor-unit input, or `unsafeCents()` at a
+* documented boundary.
+*
+* Currency-agnostic: the currency code lives alongside the amount in the
+* schema (e.g. invoices.currency); pairing them is the call site's
+* responsibility.
+*/
 const prorateHourlyCents = ({ billedMinutes, hourlyRateCents }) => {
 	assertNonNegativeInteger("billedMinutes", billedMinutes);
 	assertNonNegativeInteger("hourlyRateCents", hourlyRateCents);
@@ -30,8 +217,9 @@ const applyMarkupCents = ({ amountCents, markupPercent }) => {
 	return cents(Math.floor((amountCents * (100 + markupPercent) + 50) / 100));
 };
 function assertNonNegativeInteger(name, value) {
-	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) throw new TypeError(`${name} must be a finite non-negative integer`);
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) panic(`${name} must be a finite non-negative integer`);
 }
+const isCurrencyCents = (amount, currency) => currency !== "" && isMinorUnitAmount(amount);
 /**
 * Construct a `CurrencyCents<C>` from a currency code and a minor-unit
 * amount. The only producer of `CurrencyCents`; downstream code narrows `C`
@@ -39,8 +227,9 @@ function assertNonNegativeInteger(name, value) {
 * infers `CurrencyCents<"USD">`).
 */
 const currencyCents = (currency, amount) => {
-	if (!currency) throw new TypeError("currencyCents(): currency must be a non-empty code");
-	return cents(amount);
+	if (!currency) return panic("currencyCents(): currency must be a non-empty code");
+	const minorUnits = cents(amount);
+	return isCurrencyCents(minorUnits, currency) ? minorUnits : panic("currencyCents(): currency must be a non-empty code");
 };
 /**
 * Add two `CurrencyCents` amounts of the SAME currency. The second
@@ -68,7 +257,7 @@ var MoneyTotals = class {
 	#totals = /* @__PURE__ */ new Map();
 	/** Add `amountCents` to the running total for `currency`. */
 	add(currency, amountCents) {
-		if (!currency) throw new TypeError("MoneyTotals.add(): currency must be a non-empty code");
+		if (!currency) panic("MoneyTotals.add(): currency must be a non-empty code");
 		const running = this.#totals.get(currency) ?? cents(0);
 		this.#totals.set(currency, cents(running + amountCents));
 	}
@@ -79,11 +268,11 @@ var MoneyTotals = class {
 	* `localeCompare`, so ordering does not vary with the runtime's locale.
 	*/
 	entries() {
-		return [...this.#totals.keys()].sort().map((currency) => ({
+		return [...this.#totals.keys()].toSorted().map((currency) => ({
 			currency,
 			amountCents: this.#totals.get(currency) ?? cents(0)
 		}));
 	}
 };
 //#endregion
-export { MoneyTotals, addCents, applyMarkupCents, cents, currencyCents, prorateHourlyCents, unsafeCents };
+export { MoneyTotals, addCents, applyMarkupCents, cents, currencyCents, currencyMinorUnitDigits, formatMoneyCents, prorateHourlyCents, toMajorUnits, toMinorUnits, tryToMinorUnits, unsafeCents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/money",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Branded minor-unit monetary amounts and currency-safe billing arithmetic.",
   "keywords": [
     "billing",
@@ -40,15 +40,18 @@
     "pack:dry-run": "bun pm pack --dry-run",
     "test": "bun test src",
     "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
-    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/money",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware packages/money",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/money",
-    "format": "oxfmt .",
+    "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build"
   },
+  "dependencies": {
+    "better-result": "3.0.1"
+  },
   "devDependencies": {
     "@stll/typescript-config": "0.0.0",
-    "@types/bun": "1.3.14",
-    "tsdown": "0.22.14"
+    "bun-types": "1.4.2",
+    "tsdown": "0.23.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"