@c9up/atom 0.1.10 → 0.1.12

package/src/Decimal.ts

@@ -43,9 +43,16 @@ export interface BetweenOptions {
 	inclusive?: boolean;
 }
 
+/**
+ * `quantize` takes a rounding mode and nothing else.
+ *
+ * It used to accept a `precision` too, which it validated and then ignored:
+ * `quantize('0.01', { precision: 4 })` answered `1.23`, the same as without it.
+ * There is nothing the option could have meant — the result's scale comes from
+ * the step, which is the whole point of quantizing to one.
+ */
 export interface QuantizeOptions {
 	mode?: RoundMode;
-	precision?: number;
 }
 
 export interface MedianOptions {
@@ -139,9 +146,13 @@ export class Decimal {
 		localesOrRosetta?: Intl.LocalesArgument | RosettaLike,
 	): Decimal {
 		if (isRosettaLike(localesOrRosetta)) {
-			return new Decimal(normalizeViaRosetta(value, localesOrRosetta));
+			return new Decimal(
+				normalizeLocalized(value, shapeFromRosetta(localesOrRosetta)),
+			);
 		}
-		return new Decimal(normalizeLocaleNumber(value, localesOrRosetta));
+		return new Decimal(
+			normalizeLocalized(value, shapeFromIntl(localesOrRosetta)),
+		);
 	}
 
 	plus(other: DecimalInput): Decimal {
@@ -332,9 +343,6 @@ export class Decimal {
 		if (!stepValue.gt(0)) {
 			throw new Error("Quantize step must be greater than zero");
 		}
-		if (options.precision !== undefined) {
-			assertScale(options.precision);
-		}
 		const thisParts = parseDecimal(this.#value);
 		const stepParts = parseDecimal(stepValue.#value);
 		const numerator = thisParts.int * pow10BigInt(stepParts.scale);
@@ -466,8 +474,7 @@ export class Decimal {
 		const remainders: Array<{ index: number; remainder: bigint }> = [];
 		let consumed = 0n;
 
-		for (let index = 0; index < normalized.length; index++) {
-			const ratio = normalized[index];
+		for (const [index, ratio] of normalized.entries()) {
 			const weighted = total * ratio;
 			const share = weighted / ratioTotal;
 			const remainder = weighted % ratioTotal;
@@ -485,7 +492,13 @@ export class Decimal {
 
 		let pointer = 0;
 		while (left > 0n) {
-			baseShares[remainders[pointer].index] += 1n;
+			// `remainders` has one entry per ratio and the pointer wraps inside
+			// it, so both reads land; naming them is what says so.
+			const target = remainders[pointer];
+			if (target === undefined) break;
+			const share = baseShares[target.index];
+			if (share === undefined) break;
+			baseShares[target.index] = share + 1n;
 			left -= 1n;
 			pointer++;
 			if (pointer >= remainders.length) pointer = 0;
@@ -505,10 +518,29 @@ export class Decimal {
 		};
 	}
 
+	/**
+	 * The canonical decimal — trailing zeros trimmed. `'001.2300'` prints
+	 * `'1.23'`, and `'100.0000000000'` prints `'100'`.
+	 *
+	 * **The scale belongs to your domain, not to the value.** To persist or to
+	 * allocate, pass the scale your column declares — `toFixed(10)`,
+	 * `toScale(10)` — never the one the value happens to be carrying. A scale
+	 * read back off a value is not a promise:
+	 *
+	 *     new Decimal('100.0000000000').toParts().scale        // 10
+	 *     new Decimal('100.0000000000').plus('0').toParts()    // scale 0
+	 *
+	 * Arithmetic does not carry a declared scale, so anything that has been
+	 * through `plus` or `times` has whatever scale its VALUE needs. That
+	 * matters because `allocate()` splits at the scale it finds: the same
+	 * amount divides into `33 + 67` or `33.3333333333 + 66.6666666667`
+	 * depending on a property this method deliberately does not show you.
+	 */
 	toString(): string {
 		return this.#value;
 	}
 
+	/** The canonical form — see {@link toString} on storing a scale. */
 	toJSON(): string {
 		return this.#value;
 	}
@@ -552,10 +584,7 @@ export class Decimal {
 		if (isRosettaLike(localesOrRosetta)) {
 			return localesOrRosetta.formatNumberString(this.#value, options);
 		}
-		const formatter = new Intl.NumberFormat(
-			localesOrRosetta,
-			options,
-		) as StringFormatter;
+		const formatter = stringFormatter(localesOrRosetta, options);
 		if (this.isInteger()) {
 			return formatter.format(BigInt(this.#value));
 		}
@@ -574,6 +603,20 @@ interface StringFormatter extends Intl.NumberFormat {
 	format(value: number | bigint | string): string;
 }
 
+/**
+ * A formatter typed with that overload.
+ *
+ * A method parameter is compared bivariantly, so the constructed formatter
+ * satisfies the wider signature on its own — the assertion that used to sit
+ * here was claiming something the compiler could check.
+ */
+function stringFormatter(
+	locales?: Intl.LocalesArgument,
+	options?: Intl.NumberFormatOptions,
+): StringFormatter {
+	return new Intl.NumberFormat(locales, options);
+}
+
 function normalizeInput(value: DecimalInput): string {
 	if (value instanceof Decimal) {
 		return value.toString();
@@ -623,7 +666,7 @@ function decimalStringFromNumber(value: number): string {
 
 	const [coefficient, exponentRaw] = raw.toLowerCase().split("e");
 	const exponent = Number(exponentRaw);
-	if (!Number.isInteger(exponent)) {
+	if (coefficient === undefined || !Number.isInteger(exponent)) {
 		throw new Error(`Invalid decimal: ${value}`);
 	}
 	const negative = coefficient.startsWith("-");
@@ -631,7 +674,7 @@ function decimalStringFromNumber(value: number): string {
 		negative || coefficient.startsWith("+")
 			? coefficient.slice(1)
 			: coefficient;
-	const [wholeRaw, fracRaw = ""] = unsigned.split(".");
+	const [wholeRaw = "", fracRaw = ""] = unsigned.split(".");
 	const digits = `${wholeRaw}${fracRaw}`;
 	const decimalIndex = wholeRaw.length + exponent;
 
@@ -847,85 +890,177 @@ function isRosettaLike(arg: unknown): arg is RosettaLike {
 		typeof arg === "object" &&
 		arg !== null &&
 		"getNumberFormatData" in arg &&
-		typeof (arg as RosettaLike).getNumberFormatData === "function" &&
+		typeof arg.getNumberFormatData === "function" &&
 		"formatNumberString" in arg &&
-		typeof (arg as RosettaLike).formatNumberString === "function"
+		typeof arg.formatNumberString === "function"
 	);
 }
 
-function normalizeViaRosetta(input: string, rosetta: RosettaLike): string {
-	const trimmed = input.trim();
-	if (!trimmed) {
-		throw new Error("Invalid localized decimal: empty string");
-	}
+/**
+ * Everything reading one locale's numbers takes.
+ *
+ * There is one normalizer, and both ways of naming a locale build one of
+ * these for it. Written as two normalizers, the Rosetta one carried a subset
+ * of the rules: it substituted the separators but never mapped the locale's
+ * digits and validated grouping against the 3-3 of en-US whatever the locale
+ * actually grouped by. `parseLocale('١٬٢٣٤٫٥٦', 'ar-EG')` and
+ * `parseLocale('١٬٢٣٤٫٥٦', rosetta)` therefore disagreed about the same locale
+ * — the second refused it — and so did every Indic locale, whose 3-2 grouping
+ * only the first one asked about.
+ */
+interface LocaleNumberShape {
+	decimal: string;
+	group: string;
+	minus: string;
+	plusSign: string;
+	/** The locale's digits, mapped back to ASCII. Empty when they are ASCII. */
+	digits: ReadonlyMap<string, string>;
+	grouping: GroupingSpec;
+}
+
+interface GroupingSpec {
+	primary: number;
+	secondary: number;
+}
+
+/** Format a decimal string the way one locale writes it. */
+type FormatNumber = (
+	value: string,
+	options?: Intl.NumberFormatOptions,
+) => string;
+
+function shapeFromIntl(locales?: Intl.LocalesArgument): LocaleNumberShape {
+	const format: FormatNumber = (value, options) =>
+		stringFormatter(locales, options).format(value);
+	const parts = new Intl.NumberFormat(locales).formatToParts(-12345.6);
+	const signed = new Intl.NumberFormat(locales, {
+		signDisplay: "always",
+	}).formatToParts(1);
+	const group = parts.find((part) => part.type === "group")?.value ?? ",";
+	const digits = digitsOf(format);
+	return {
+		decimal: parts.find((part) => part.type === "decimal")?.value ?? ".",
+		group,
+		minus: parts.find((part) => part.type === "minusSign")?.value ?? "-",
+		plusSign: signed.find((part) => part.type === "plusSign")?.value ?? "+",
+		digits,
+		grouping: groupingOf(format, group, digits),
+	};
+}
+
+/**
+ * The same shape, read off a Rosetta.
+ *
+ * `getNumberFormatData` names the separators; the digits and the grouping come
+ * out of `formatNumberString`, which the same interface already declares — so
+ * the Rosetta path honours its fallback chain for all four without asking the
+ * caller for a locale tag it deliberately does not take.
+ */
+function shapeFromRosetta(rosetta: RosettaLike): LocaleNumberShape {
+	const format: FormatNumber = (value, options) =>
+		rosetta.formatNumberString(value, options);
 	const raw = rosetta.getNumberFormatData();
-	// Guard: a malformed `RosettaLike` returning empty separators
-	// would produce regexes matching every position. Fall back to
-	// ASCII defaults rather than corrupting the input.
-	const data = {
+	// A malformed `RosettaLike` returning empty separators would build regexes
+	// matching every position. Fall back to ASCII rather than corrupt the input.
+	const group = raw.group || ",";
+	const digits = digitsOf(format);
+	return {
 		decimal: raw.decimal || ".",
-		group: raw.group || ",",
+		group,
 		minus: raw.minus || "-",
 		plusSign: raw.plusSign || "+",
+		digits,
+		grouping: groupingOf(format, group, digits),
 	};
-	let normalized = trimmed.replace(/\s| | /g, "");
-	if (data.minus !== "-") {
-		normalized = normalized.replace(
-			new RegExp(escapeRegExp(data.minus), "g"),
-			"-",
-		);
-	}
-	normalized = normalized.replace(/[−﹣－]/g, "-");
-	// Substitute the locale's plus sign (e.g., U+FF0B `＋`,
-	// U+FB29 `﬩`) to ASCII so the strict validator accepts it.
-	if (data.plusSign !== "+") {
-		normalized = normalized.replace(
-			new RegExp(escapeRegExp(data.plusSign), "g"),
-			"+",
-		);
-	}
+}
 
-	if (/^\(.*\)$/.test(normalized)) {
-		normalized = `-${normalized.slice(1, -1)}`;
+/**
+ * The locale's ten digits, read off the formatter rather than a table.
+ *
+ * One call names all ten in a known order, so a numbering system whose code
+ * points are not contiguous — or one the runtime added after this was written
+ * — needs nothing here.
+ */
+function digitsOf(format: FormatNumber): ReadonlyMap<string, string> {
+	const map = new Map<string, string>();
+	let formatted: string;
+	try {
+		formatted = format("9876543210", { useGrouping: false });
+	} catch {
+		return map;
 	}
-
-	validateLocalizedSyntax(normalized, data.group, data.decimal);
-	normalized = normalized.replace(
-		new RegExp(escapeRegExp(data.group), "g"),
-		"",
-	);
-	normalized = normalized.replace(
-		new RegExp(escapeRegExp(data.decimal), "g"),
-		".",
-	);
-
-	if (!/^[+-]?\d+(\.\d+)?$/.test(normalized)) {
-		throw new Error(`Invalid localized decimal: ${input}`);
+	let value = 9;
+	for (const char of formatted) {
+		if (!map.has(char) && value >= 0) {
+			map.set(char, String(value));
+			value--;
+		}
 	}
-	return normalized;
+	return map;
+}
+
+/**
+ * How wide the locale's groups are — 3-3 for `1,234,567`, 3-2 for the Indic
+ * `12,34,567`. Measured on a number long enough to show both.
+ */
+function groupingOf(
+	format: FormatNumber,
+	group: string,
+	digits: ReadonlyMap<string, string>,
+): GroupingSpec {
+	const fallback: GroupingSpec = { primary: 3, secondary: 3 };
+	let formatted: string;
+	try {
+		formatted = format("1234567890123");
+	} catch {
+		return fallback;
+	}
+	const segments = toAsciiDigits(formatted, digits).split(group);
+	if (segments.length < 2) return fallback;
+	// Code points, not UTF-16 units: a digit outside the BMP counts once.
+	const lengths = segments.map((segment) => [...segment].length);
+	const primary = lengths.at(-1) ?? 3;
+	const secondary = lengths.at(-2) ?? primary;
+	return { primary, secondary };
 }
 
-function normalizeLocaleNumber(
+function toAsciiDigits(
 	input: string,
-	locales?: Intl.LocalesArgument,
+	digits: ReadonlyMap<string, string>,
 ): string {
+	if (digits.size === 0) return input;
+	let out = "";
+	for (const char of input) {
+		out += digits.get(char) ?? char;
+	}
+	return out;
+}
+
+function normalizeLocalized(input: string, shape: LocaleNumberShape): string {
 	const trimmed = input.trim();
 	if (!trimmed) {
 		throw new Error("Invalid localized decimal: empty string");
 	}
 
-	const formatter = new Intl.NumberFormat(locales);
-	const parts = formatter.formatToParts(-12345.6);
-	const group = parts.find((part) => part.type === "group")?.value ?? ",";
-	const decimal = parts.find((part) => part.type === "decimal")?.value ?? ".";
-	const minus = parts.find((part) => part.type === "minusSign")?.value ?? "-";
-
-	let normalized = normalizeLocaleDigits(trimmed, locales);
-	normalized = normalized.replace(/\s|\u00A0|\u202F/g, "");
-	if (minus !== "-") {
-		normalized = normalized.replace(new RegExp(escapeRegExp(minus), "g"), "-");
+	let normalized = toAsciiDigits(trimmed, shape.digits);
+	// `\s` already covers U+00A0 and U+202F, which is what the space-grouping
+	// locales separate with.
+	normalized = normalized.replace(/\s/g, "");
+	if (shape.minus !== "-") {
+		normalized = normalized.replace(
+			new RegExp(escapeRegExp(shape.minus), "g"),
+			"-",
+		);
 	}
 	normalized = normalized.replace(/[−﹣－]/g, "-");
+	// The locale's plus sign (e.g. U+FF0B `＋`, U+FB29 `﬩`) becomes ASCII so the
+	// strict validator below accepts it.
+	if (shape.plusSign !== "+") {
+		normalized = normalized.replace(
+			new RegExp(escapeRegExp(shape.plusSign), "g"),
+			"+",
+		);
+	}
 
 	if (/^\(.*\)$/.test(normalized)) {
 		normalized = `-${normalized.slice(1, -1)}`;
@@ -933,12 +1068,18 @@ function normalizeLocaleNumber(
 
 	validateLocalizedSyntax(
 		normalized,
-		group,
-		decimal,
-		getLocaleGrouping(locales),
+		shape.group,
+		shape.decimal,
+		shape.grouping,
+	);
+	normalized = normalized.replace(
+		new RegExp(escapeRegExp(shape.group), "g"),
+		"",
+	);
+	normalized = normalized.replace(
+		new RegExp(escapeRegExp(shape.decimal), "g"),
+		".",
 	);
-	normalized = normalized.replace(new RegExp(escapeRegExp(group), "g"), "");
-	normalized = normalized.replace(new RegExp(escapeRegExp(decimal), "g"), ".");
 
 	if (!/^[+-]?\d+(\.\d+)?$/.test(normalized)) {
 		throw new Error(`Invalid localized decimal: ${input}`);
@@ -946,62 +1087,6 @@ function normalizeLocaleNumber(
 	return normalized;
 }
 
-function normalizeLocaleDigits(
-	input: string,
-	locales?: Intl.LocalesArgument,
-): string {
-	const digitMap = getLocaleDigitMap(locales);
-	let out = "";
-	for (const char of input) {
-		out += digitMap.get(char) ?? char;
-	}
-	return out;
-}
-
-function getLocaleDigitMap(
-	locales?: Intl.LocalesArgument,
-): Map<string, string> {
-	const formatter = new Intl.NumberFormat(locales, { useGrouping: false });
-	const digits = formatter.format(9876543210);
-	const map = new Map<string, string>();
-	let value = 9;
-	for (const char of digits) {
-		if (!map.has(char) && value >= 0) {
-			map.set(char, String(value));
-			value--;
-		}
-	}
-	return map;
-}
-
-interface GroupingSpec {
-	primary: number;
-	secondary: number;
-}
-
-function getLocaleGrouping(locales?: Intl.LocalesArgument): GroupingSpec {
-	const parts = new Intl.NumberFormat(locales)
-		.formatToParts(1234567890123)
-		.filter((part) => part.type === "integer" || part.type === "group");
-	const lengths: number[] = [];
-	let current = 0;
-	for (const part of parts) {
-		if (part.type === "integer") {
-			current += [...part.value].length;
-		} else {
-			lengths.push(current);
-			current = 0;
-		}
-	}
-	lengths.push(current);
-	if (lengths.length < 2) {
-		return { primary: 3, secondary: 3 };
-	}
-	const primary = lengths[lengths.length - 1];
-	const secondary = lengths[lengths.length - 2] ?? primary;
-	return { primary, secondary };
-}
-
 function validateLocalizedSyntax(
 	value: string,
 	group: string,
@@ -1035,11 +1120,14 @@ function validateLocalizedSyntax(
 	}
 	for (let i = groups.length - 1, distance = 0; i >= 0; i--, distance++) {
 		const size = distance === 0 ? grouping.primary : grouping.secondary;
+		const group = groups[i];
+		if (group === undefined)
+			throw new Error(`Invalid localized decimal: ${value}`);
 		if (i === 0) {
-			if (groups[i].length < 1 || groups[i].length > size) {
+			if (group.length < 1 || group.length > size) {
 				throw new Error(`Invalid localized decimal: ${value}`);
 			}
-		} else if (groups[i].length !== size) {
+		} else if (group.length !== size) {
 			throw new Error(`Invalid localized decimal: ${value}`);
 		}
 	}

package/src/Money.ts

@@ -7,18 +7,53 @@ export interface MoneyOptions {
 	mode?: RoundMode;
 }
 
+/**
+ * What `times` and `div` take.
+ *
+ * The rounding mode, and only that. They used to declare the whole
+ * {@link MoneyOptions} and forward one field of it: `scale` and `exact` were
+ * overwritten on the way through, so `.times("1.5", { scale: 4 })` came back at
+ * the currency's scale and `.times("1.333", { exact: true })` rounded anyway.
+ * Neither could ever have been honoured — a multiplied amount of money is still
+ * money, and money is held at the scale its currency has.
+ */
+export interface MoneyRoundingOptions {
+	mode?: RoundMode;
+}
+
 export interface MoneyFormatOptions
 	extends Omit<Intl.NumberFormatOptions, "style" | "currency"> {
 	locale?: Intl.LocalesArgument;
 }
 
+/**
+ * ISO 4217 minor units, for every currency that does not have two.
+ *
+ * Only the exceptions are listed; anything absent is two, which is what the
+ * lookups below fall back to. Written as a partial list of the ones someone
+ * happened to think of, the fallback answered for the rest — and answered
+ * wrong. A `Money` built for ISK, whose króna has no subunit, was held at two
+ * decimals: `toMinorUnits()` returned 123400 for 1234 króna, a hundredfold
+ * error on its way into an integer column, `toString()` printed a fractional
+ * part the currency does not have, and `format()` asked Intl for two decimals
+ * it would otherwise have refused to print. JPY, three lines away in the same
+ * table, was correct — the difference between the two was which one someone
+ * had typed in.
+ *
+ * ISO is the source of truth here, not CLDR, and they disagree on one entry:
+ * ISO gives IQD three minor units, `Intl` prints zero. `format()` passes this
+ * scale to Intl explicitly, so the value keeps the fils ISO says it has.
+ */
 const ISO_MINOR_UNITS: Record<string, number> = Object.freeze({
 	BHD: 3,
+	BIF: 0,
 	CLF: 4,
 	CLP: 0,
 	DJF: 0,
-	EUR: 2,
-	GBP: 2,
+	GNF: 0,
+	IQD: 3,
+	ISK: 0,
+	JOD: 3,
 	JPY: 0,
 	KMF: 0,
 	KRW: 0,
@@ -26,9 +61,13 @@ const ISO_MINOR_UNITS: Record<string, number> = Object.freeze({
 	LYD: 3,
 	OMR: 3,
 	PYG: 0,
+	RWF: 0,
 	TND: 3,
-	USD: 2,
+	UGX: 0,
+	UYI: 0,
+	UYW: 4,
 	VND: 0,
+	VUV: 0,
 	XAF: 0,
 	XOF: 0,
 	XPF: 0,
@@ -102,7 +141,7 @@ export class Money {
 		});
 	}
 
-	times(multiplier: DecimalInput, options: MoneyOptions = {}): Money {
+	times(multiplier: DecimalInput, options: MoneyRoundingOptions = {}): Money {
 		return new Money(this.#amount.times(multiplier), this.#currency, {
 			scale: this.#scale,
 			exact: false,
@@ -110,7 +149,7 @@ export class Money {
 		});
 	}
 
-	div(divisor: DecimalInput, options: MoneyOptions = {}): Money {
+	div(divisor: DecimalInput, options: MoneyRoundingOptions = {}): Money {
 		return new Money(this.#amount.div(divisor), this.#currency, {
 			scale: this.#scale,
 			exact: false,

package/src/atlas.ts

@@ -5,9 +5,8 @@
  * column pipeline. Lives on a sub-export so the default `@c9up/atom` import
  * surface stays adapter-free.
  *
- * Mirrors Adonis Lucid's `@column.prepare` / `@column.consume` pattern —
- * callbacks are baked into the entity definition; no global registry, no
- * boot-time wiring.
+ * The callbacks are baked into the entity definition: no global registry, no
+ * boot-time wiring, nothing to import in a provider.
  *
  * Usage:
  *
@@ -19,8 +18,6 @@
  *       @PrimaryKey() id!: number
  *       @Column(decimalAtlasAdapter) balance!: Decimal | null
  *     }
- *
- * @implements Story 35.10
  */
 
 import { Decimal, type RoundMode } from "./Decimal.js";