@stll/money 0.3.1 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ The package keeps money in integer minor units, rejects fractional cents, and
 separates totals by currency so incompatible amounts cannot be combined.
 
 ```ts
-import { MoneyTotals, cents } from "@stll/money";
+import { cents, MoneyTotals } from "@stll/money";
 
 const totals = new MoneyTotals();
 totals.add("EUR", cents(1250));

package/dist/index.d.ts

@@ -1,11 +1,4 @@
-//#region src/cents.d.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.
- */
+import { Result } from "better-result";
 declare const __cents: unique symbol;
 type CentsAmount = number & {
   readonly [__cents]: "CentsAmount";
@@ -13,7 +6,7 @@ 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 `tMinorUnitAmount(...)` or after
+ * minor-unit value (e.g. after `minorUnitAmountSchema(...)` or after
  * scaling a typed major-unit amount by the currency's exponent).
  *
  * SAFE integer, not merely integer: `Number.isInteger` is true for 2^53 and
@@ -30,8 +23,6 @@ export declare const cents: (value: number) => CentsAmount;
  * comment naming why the value is already a valid minor-unit integer.
  */
 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
@@ -41,6 +32,55 @@ export declare const unsafeCents: (value: number) => CentsAmount;
  * `?? 2` on its result could help, so the fallback has to wrap the call.
  */
 export declare const currencyMinorUnitDigits: (currency: string) => number;
+type LocaleAmountParseError = {
+  reason: "empty" | "syntax" | "ambiguous" | "precision" | "unsafe-integer" | "locale";
+  message: string;
+};
+type ParseLocaleMinorUnitsParams = {
+  amount: string;
+  currency: string;
+  locale: string;
+};
+type ParseLocaleDecimalParams = {
+  amount: string;
+  locale: string;
+  maximumFractionDigits?: number;
+};
+declare const localeInputTextBrand: unique symbol;
+/** Text whose separators and digits belong to a person's formatting locale. */
+type LocaleInputText = string & {
+  readonly [localeInputTextBrand]: "LocaleInputText";
+};
+/** The control a person typed into: an input or textarea element. */
+type LocaleInputSource = {
+  readonly value: string;
+  readonly tagName: string;
+};
+/**
+ * The text of the control a person typed into. It takes the element, not its
+ * string, so canonical stored text cannot be passed off as locale input; stored
+ * values reach a field only through the redisplay formatters below.
+ */
+export declare const localeInputText: (source: LocaleInputSource) => LocaleInputText;
+/** The text of a cleared locale input. */
+export declare const EMPTY_LOCALE_INPUT_TEXT: LocaleInputText;
+/** Normalize a human-entered locale decimal without converting through a float. */
+export declare const parseLocaleDecimal: ({ amount, locale, maximumFractionDigits }: ParseLocaleDecimalParams) => Result<string, LocaleAmountParseError>;
+/** Parse human-entered major units according to their formatting locale. */
+export declare const parseLocaleMinorUnits: ({ amount, currency, locale }: ParseLocaleMinorUnitsParams) => Result<CentsAmount, LocaleAmountParseError>;
+type FormatLocaleMinorUnitsInputParams = {
+  amountCents: number;
+  currency: string;
+  locale: string;
+};
+type FormatLocaleDecimalInputParams = {
+  amount: string;
+  locale: string;
+};
+/** Render canonical decimal text using locale digits and its decimal mark. */
+export declare const formatLocaleDecimalInput: ({ amount, locale }: FormatLocaleDecimalInputParams) => LocaleInputText;
+/** Render stored minor units as locale input text that parses back unchanged. */
+export declare const formatLocaleMinorUnitsInput: ({ amountCents, currency, locale }: FormatLocaleMinorUnitsInputParams) => LocaleInputText;
 type ToMinorUnitsParams = {
   /**
    * The amount in major units: the decimal text a form holds, or a number.
@@ -84,6 +124,14 @@ type ToMajorUnitsParams = {
 };
 /** The inverse: a stored amount as the major-unit number a person reads. */
 export declare const toMajorUnits: ({ amountCents, currency }: ToMajorUnitsParams) => number;
+/**
+ * A stored amount as exact major-unit decimal text, with no grouping and a
+ * dot separator: 123456 EUR is "1234.56", 1500 JPY is "1500". The digits are
+ * moved, not divided, so a value near the safe-integer edge keeps every minor
+ * unit that `toMajorUnits` would round away. For machine readers (a prompt,
+ * an export), not for display; display goes through `formatMoneyCents`.
+ */
+export declare const toMajorUnitsText: ({ amountCents, currency }: ToMajorUnitsParams) => string;
 type FormatMoneyCentsParams = {
   amountCents: number;
   currency: string;
@@ -103,8 +151,6 @@ type FormatMoneyCentsParams = {
  * 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;
@@ -156,7 +202,7 @@ type IsSingletonCurrency<C extends string> = string extends C ? never : [C] exte
  * Both operands are further constrained by `IsSingletonCurrency` to reject
  * any non-singleton currency type: the WIDE `CurrencyCents<string>`, and
  * also a finite union such as `CurrencyCents<"USD" | "EUR">` (e.g. from a
- * validator's `t.UnionEnum`). A currency read back from a DB row or
+ * validator's `v.picklist`). A currency read back from a DB row or
  * narrowed only to a finite set of allowed codes types as `string` or a
  * union, not a single literal, so without this, `addCents(currencyCents(a,
  * x), currencyCents(b, y))` would still typecheck even when `a`/`b` are
@@ -204,5 +250,4 @@ export declare class MoneyTotals {
    */
   entries(): MoneyTotalsEntry[];
 }
-//#endregion
-export type { CentsAmount, FormatMoneyCentsParams, ToMajorUnitsParams, ToMinorUnitsParams };
+export type { CentsAmount, FormatLocaleDecimalInputParams, FormatLocaleMinorUnitsInputParams, FormatMoneyCentsParams, LocaleAmountParseError, LocaleInputSource, LocaleInputText, ParseLocaleDecimalParams, ParseLocaleMinorUnitsParams, ToMajorUnitsParams, ToMinorUnitsParams };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { Result, panic } from "better-result";
-//#region src/cents.ts
+// src/cents.ts
 /**
 * The minor-unit brand and its constructors.
 *
@@ -12,7 +12,7 @@ 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 `tMinorUnitAmount(...)` or after
+* minor-unit value (e.g. after `minorUnitAmountSchema(...)` or after
 * scaling a typed major-unit amount by the currency's exponent).
 *
 * SAFE integer, not merely integer: `Number.isInteger` is true for 2^53 and
@@ -32,8 +32,7 @@ const cents = (value) => {
 * comment naming why the value is already a valid minor-unit integer.
 */
 const unsafeCents = (value) => value;
-//#endregion
-//#region src/format.ts
+// src/format.ts
 /**
 * Moving between a stored minor-unit amount and the major-unit number a
 * person types, and rendering either as text.
@@ -72,6 +71,176 @@ const currencyMinorUnitDigits = (currency) => {
 };
 /** A decimal amount in major units: an optional sign, digits, an optional point. */
 const DECIMAL_AMOUNT = /^(?<sign>[+-]?)(?<whole>\d*)(?:\.(?<fraction>\d*))?$/u;
+const localeSeparators = (locale) => Result.try(() => {
+	const formatter = new Intl.NumberFormat(locale, { useGrouping: false });
+	const groupedParts = new Intl.NumberFormat(locale).formatToParts(1234567890123);
+	const digits = /* @__PURE__ */ new Map();
+	for (let digit = 0; digit <= 9; digit += 1) digits.set(formatter.format(digit), String(digit));
+	const integerGroups = groupedParts.filter((part) => part.type === "integer").map((part) => part.value.length);
+	return {
+		decimal: new Intl.NumberFormat(locale).formatToParts(12345.6).find((part) => part.type === "decimal")?.value ?? ".",
+		group: groupedParts.find((part) => part.type === "group")?.value,
+		primaryGroupSize: integerGroups.at(-1) ?? 3,
+		secondaryGroupSize: integerGroups.at(-2) ?? integerGroups.at(-1) ?? 3,
+		digits
+	};
+});
+const normalizeGroupedWhole = ({ whole, grouping, primaryGroupSize, secondaryGroupSize }) => {
+	const groups = whole.split(grouping);
+	const leadingGroup = groups.at(0) ?? "";
+	const trailingGroup = groups.at(-1) ?? "";
+	const middleGroups = groups.slice(1, -1);
+	if (!new RegExp(`^[0-9]{1,${secondaryGroupSize}}$`, "u").test(leadingGroup) || !new RegExp(`^[0-9]{${primaryGroupSize}}$`, "u").test(trailingGroup) || middleGroups.some((part) => !new RegExp(`^[0-9]{${secondaryGroupSize}}$`, "u").test(part))) return null;
+	return groups.join("");
+};
+const ASCII_DECIMAL_MARKS = [".", ","];
+const normalizeInputSeparators = ({ unsigned, decimal, group, primaryGroupSize }) => {
+	const alternateDecimal = ASCII_DECIMAL_MARKS.filter((mark) => mark !== decimal).find((mark) => unsigned.includes(mark)) ?? (decimal === "," ? "." : ",");
+	const alternateParts = unsigned.split(alternateDecimal);
+	const hasLocaleDecimal = unsigned.includes(decimal);
+	const hasSingleAlternate = alternateParts.length === 2;
+	const alternateFractionLength = alternateParts.at(1)?.length;
+	if (!hasLocaleDecimal && hasSingleAlternate && alternateFractionLength === primaryGroupSize) return { status: "ambiguous" };
+	if (!hasLocaleDecimal && hasSingleAlternate && alternateFractionLength !== primaryGroupSize) return {
+		status: "normalized",
+		unsigned: unsigned.replace(alternateDecimal, () => decimal),
+		grouping: group
+	};
+	let grouping = group;
+	if (decimal === "," && unsigned.split(decimal).at(0)?.includes(".")) grouping = ".";
+	return {
+		status: "normalized",
+		unsigned,
+		grouping
+	};
+};
+/**
+* The fraction kept at the allowed places, undefined when none is left, or
+* null when a digit past them is not zero. Trailing zeros carry no value
+* (100.00 yen is 100 yen); any other extra digit would need rounding.
+*/
+const exactFraction = (fraction, maximumFractionDigits) => {
+	if (fraction === void 0 || maximumFractionDigits === void 0 || fraction.length <= maximumFractionDigits) return fraction;
+	if (!/^0*$/u.test(fraction.slice(maximumFractionDigits))) return null;
+	const kept = fraction.slice(0, maximumFractionDigits);
+	return kept === "" ? void 0 : kept;
+};
+function brandLocaleInputText(value) {
+	return value;
+}
+/**
+* The text of the control a person typed into. It takes the element, not its
+* string, so canonical stored text cannot be passed off as locale input; stored
+* values reach a field only through the redisplay formatters below.
+*/
+const localeInputText = (source) => brandLocaleInputText(source.value);
+/** The text of a cleared locale input. */
+const EMPTY_LOCALE_INPUT_TEXT = brandLocaleInputText("");
+/** Normalize a human-entered locale decimal without converting through a float. */
+const parseLocaleDecimal = ({ amount, locale, maximumFractionDigits }) => {
+	const text = amount.trim();
+	if (text.length === 0) return Result.err({
+		reason: "empty",
+		message: "Amount is empty"
+	});
+	const separators = localeSeparators(locale);
+	if (separators.isErr()) return Result.err({
+		reason: "locale",
+		message: "Invalid locale"
+	});
+	const { decimal, group, primaryGroupSize, secondaryGroupSize, digits } = separators.value;
+	const whitespaceGroup = group !== void 0 && /^\s$/u.test(group);
+	let localizedDigits = "";
+	for (const character of text) localizedDigits += digits.get(character) ?? character;
+	const normalizedWhitespace = whitespaceGroup ? localizedDigits.replace(/[\u0020\u00a0\u202f]/gu, () => group) : localizedDigits;
+	const sign = /^[+-]/u.exec(normalizedWhitespace)?.at(0) ?? "";
+	const unsignedInput = sign ? normalizedWhitespace.slice(1) : normalizedWhitespace;
+	const normalizedSeparators = normalizeInputSeparators({
+		unsigned: unsignedInput,
+		decimal,
+		group,
+		primaryGroupSize
+	});
+	if (normalizedSeparators.status === "ambiguous") return Result.err({
+		reason: "ambiguous",
+		message: "Amount has an ambiguous separator"
+	});
+	const { unsigned, grouping } = normalizedSeparators;
+	const decimalParts = unsigned.split(decimal);
+	if (decimalParts.length > 2 || decimalParts.length === 1 && decimalParts.at(0)?.length === 0 || decimalParts.length === 2 && decimalParts.at(1)?.length === 0) return Result.err({
+		reason: "syntax",
+		message: "Invalid amount format"
+	});
+	const whole = decimalParts.at(0) || "0";
+	const fraction = decimalParts.at(1);
+	let wholeDigits = whole;
+	if (grouping !== void 0 && whole.includes(grouping)) {
+		const normalizedWhole = normalizeGroupedWhole({
+			whole,
+			grouping,
+			primaryGroupSize,
+			secondaryGroupSize
+		});
+		if (normalizedWhole === null) return Result.err({
+			reason: "syntax",
+			message: "Invalid amount grouping"
+		});
+		wholeDigits = normalizedWhole;
+	}
+	if (!/^[0-9]+$/u.test(wholeDigits) || fraction !== void 0 && !/^[0-9]+$/u.test(fraction)) return Result.err({
+		reason: "syntax",
+		message: "Invalid amount format"
+	});
+	const exact = exactFraction(fraction, maximumFractionDigits);
+	if (exact === null) return Result.err({
+		reason: "precision",
+		message: "Amount has too many fraction digits"
+	});
+	return Result.ok(`${sign}${wholeDigits}${exact === void 0 ? "" : `.${exact}`}`);
+};
+/** Parse human-entered major units according to their formatting locale. */
+const parseLocaleMinorUnits = ({ amount, currency, locale }) => {
+	const normalized = parseLocaleDecimal({
+		amount,
+		locale,
+		maximumFractionDigits: currencyMinorUnitDigits(currency)
+	});
+	if (normalized.isErr()) return normalized;
+	const parsed = tryToMinorUnits({
+		amount: normalized.value,
+		currency
+	});
+	return parsed === null ? Result.err({
+		reason: "unsafe-integer",
+		message: "Amount exceeds the supported range"
+	}) : Result.ok(parsed);
+};
+const localizeAsciiDigits = (value, digits) => {
+	const localizedByAscii = new Map([...digits].map(([localized, ascii]) => [ascii, localized]));
+	return value.split("").map((character) => localizedByAscii.get(character) ?? character).join("");
+};
+/** Render canonical decimal text using locale digits and its decimal mark. */
+const formatLocaleDecimalInput = ({ amount, locale }) => {
+	const groups = DECIMAL_AMOUNT.exec(amount)?.groups;
+	const whole = groups?.["whole"] ?? "";
+	const fraction = groups?.["fraction"];
+	if (groups === void 0 || `${whole}${fraction ?? ""}`.length === 0) return panic(`formatLocaleDecimalInput(${JSON.stringify(amount)}): not a canonical decimal`);
+	const separators = localeSeparators(locale).unwrap("formatLocaleDecimalInput: invalid locale");
+	const canonical = `${groups["sign"] ?? ""}${whole || "0"}${fraction === void 0 ? "" : `${separators.decimal}${fraction}`}`;
+	return brandLocaleInputText(localizeAsciiDigits(canonical, separators.digits));
+};
+/** Render stored minor units as locale input text that parses back unchanged. */
+const formatLocaleMinorUnitsInput = ({ amountCents, currency, locale }) => {
+	const fractionDigits = currencyMinorUnitDigits(currency);
+	const sign = amountCents < 0 ? "-" : "";
+	const digits = String(Math.abs(amountCents)).padStart(fractionDigits + 1, "0");
+	const split = digits.length - fractionDigits;
+	const canonical = fractionDigits === 0 ? `${sign}${digits}` : `${sign}${digits.slice(0, split)}.${digits.slice(split)}`;
+	return formatLocaleDecimalInput({
+		amount: canonical,
+		locale
+	});
+};
 /** Scientific notation, which `String(1e21)` and `String(1e-7)` both produce. */
 const EXPONENT_AMOUNT = /^(?<sign>[+-]?)(?<whole>\d+)(?:\.(?<fraction>\d+))?[eE](?<exponent>[+-]?\d+)$/u;
 /**
@@ -163,6 +332,21 @@ const tryToMinorUnits = ({ amount, currency }) => {
 /** The inverse: a stored amount as the major-unit number a person reads. */
 const toMajorUnits = ({ amountCents, currency }) => amountCents / 10 ** currencyMinorUnitDigits(currency);
 /**
+* A stored amount as exact major-unit decimal text, with no grouping and a
+* dot separator: 123456 EUR is "1234.56", 1500 JPY is "1500". The digits are
+* moved, not divided, so a value near the safe-integer edge keeps every minor
+* unit that `toMajorUnits` would round away. For machine readers (a prompt,
+* an export), not for display; display goes through `formatMoneyCents`.
+*/
+const toMajorUnitsText = ({ amountCents, currency }) => {
+	const digits = currencyMinorUnitDigits(currency);
+	const magnitude = BigInt(Math.abs(amountCents)).toString();
+	const sign = amountCents < 0 ? "-" : "";
+	if (digits === 0) return `${sign}${magnitude}`;
+	const padded = magnitude.padStart(digits + 1, "0");
+	return `${sign}${padded.slice(0, -digits)}.${padded.slice(-digits)}`;
+};
+/**
 * 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.
 *
@@ -200,8 +384,7 @@ const formatMoneyCents = ({ amountCents, currency, locale, fractionDigits }) =>
 	});
 	return formatted.isErr() ? `${negative ? "-" : ""}${whole}${digits === 0 ? "" : `.${fraction}`} ${currency}` : formatted.value;
 };
-//#endregion
-//#region src/index.ts
+// src/index.ts
 /**
 * Branded monetary amounts and minor-unit billing arithmetic.
 *
@@ -212,8 +395,9 @@ const formatMoneyCents = ({ amountCents, currency, locale, fractionDigits }) =>
 *
 * 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.
+* `.$type<CentsAmount>()`, across the API boundary (the API route types
+* carry 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.
@@ -263,7 +447,7 @@ const currencyCents = (currency, amount) => {
 * Both operands are further constrained by `IsSingletonCurrency` to reject
 * any non-singleton currency type: the WIDE `CurrencyCents<string>`, and
 * also a finite union such as `CurrencyCents<"USD" | "EUR">` (e.g. from a
-* validator's `t.UnionEnum`). A currency read back from a DB row or
+* validator's `v.picklist`). A currency read back from a DB row or
 * narrowed only to a finite set of allowed codes types as `string` or a
 * union, not a single literal, so without this, `addCents(currencyCents(a,
 * x), currencyCents(b, y))` would still typecheck even when `a`/`b` are
@@ -296,5 +480,4 @@ var MoneyTotals = class {
 		}));
 	}
 };
-//#endregion
-export { MoneyTotals, addCents, applyMarkupCents, cents, currencyCents, currencyMinorUnitDigits, formatMoneyCents, prorateHourlyCents, timeEntryAmount, toMajorUnits, toMinorUnits, tryToMinorUnits, unsafeCents };
+export { EMPTY_LOCALE_INPUT_TEXT, MoneyTotals, addCents, applyMarkupCents, cents, currencyCents, currencyMinorUnitDigits, formatLocaleDecimalInput, formatLocaleMinorUnitsInput, formatMoneyCents, localeInputText, parseLocaleDecimal, parseLocaleMinorUnits, prorateHourlyCents, timeEntryAmount, toMajorUnits, toMajorUnitsText, toMinorUnits, tryToMinorUnits, unsafeCents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/money",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Branded minor-unit monetary amounts and currency-safe billing arithmetic.",
   "keywords": [
     "billing",
@@ -39,10 +39,9 @@
     "build": "tsdown",
     "pack:dry-run": "bun pm pack --dry-run",
     "test": "bun test src",
-    "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "typecheck": "bun check --no-pretty --all --project=tsconfig.json",
     "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/money",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/money",
-    "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build"
   },
   "dependencies": {
@@ -50,8 +49,8 @@
   },
   "devDependencies": {
     "@stll/typescript-config": "0.0.0",
-    "bun-types": "1.4.2",
-    "tsdown": "0.23.0"
+    "bun-types": "1.4.4",
+    "tsdown": "0.23.4"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"