@ultimat3/money 29.4.0 → 30.1.0

package/README.md

@@ -4,6 +4,8 @@
 `0.1 + 0.2 !== 0.3`, so no amount is ever a float. `Money` carries `minor` and `currency` together
 — plus an optional `scale` — and arithmetic across two currencies throws instead of guessing.
 
+`bun add @ultimat3/money` · guide: [Money](https://github.com/developerz-ai/ultimate/wiki/Money)
+
 `Money` **is** `@ultimat3/schema`'s `MoneyValue`, and so is `@ultimat3/entity`'s: one declaration
 at tier 0, aliased twice, never restated. A row a `money()` column decodes is therefore a `Money`
 already — `add(row.price, shipping)` and `formatMoney(row.price, locale)` take it with no cast.

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@ultimat3/money",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "money",
+    "currency",
+    "intl"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Money",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -35,7 +44,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/schema": "29.4.0"
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/schema": "30.1.0"
   }
 }

package/src/errors.ts

@@ -15,6 +15,7 @@ export const MONEY_ERROR_CODES = [
   'X_ALLOCATION_INVALID',
   'X_RATE_MISSING',
   'X_MONEY_SCALE_INVALID',
+  'X_MONEY_INPUT_INVALID',
 ] as const;
 
 export type MoneyErrorCode = (typeof MONEY_ERROR_CODES)[number];
@@ -28,6 +29,7 @@ export const MONEY_ERROR_TITLES: Readonly<Record<MoneyErrorCode, string>> = {
   X_ALLOCATION_INVALID: 'split ratios or part count are unusable',
   X_RATE_MISSING: 'no FX rate for the pair',
   X_MONEY_SCALE_INVALID: 'a Money.scale that is not a usable decimal exponent',
+  X_MONEY_INPUT_INVALID: 'a typed amount could not be read in this locale',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -38,11 +40,17 @@ registerErrorCodes(
 );
 
 export class MoneyError extends UltimateError {
-  constructor(init: { code: MoneyErrorCode; cause: string; fix: string }) {
+  constructor(init: {
+    code: MoneyErrorCode;
+    cause: string;
+    fix: string;
+    meta?: Readonly<Record<string, unknown>>;
+  }) {
     super({
       code: init.code,
       cause: init.cause,
       fix: init.fix,
+      ...(init.meta === undefined ? {} : { meta: init.meta }),
     });
   }
 }

package/src/index.ts

@@ -87,6 +87,7 @@ export {
   toDecimalString,
   zero,
 } from './money';
+export { type ParseAmountOptions, parseAmount } from './parse-input';
 export { rescale } from './rescale';
 export {
   DEFAULT_ROUNDING,

package/src/parse-input.ts

@@ -0,0 +1,138 @@
+// Single responsibility: an amount a PERSON typed, read in their locale — `1.234,56` in `de-DE`,
+// `1,234.56` in `en-US`, Arabic-Indic digits in `ar-EG` — into `Money`, or refused. The separators
+// and digits are `Intl`'s, never a table here; an ambiguous or over-precise reading is refused,
+// never rounded, and no float is ever made: the digits go on to `fromDecimal` as a string.
+
+import { assertLocale, cachedFormatter, renderCauseValue } from '@ultimat3/core';
+import { assertCurrency, exponentOf } from './currency';
+import { MoneyError } from './errors';
+import type { Money } from './money';
+import { fromDecimal } from './money';
+
+export interface ParseAmountOptions {
+  readonly currency: string;
+  /** The person's locale: whose separators and digits the text is read with. */
+  readonly locale: string;
+}
+
+interface LocaleNumerals {
+  readonly decimal: string;
+  readonly group: string;
+  readonly minus: string;
+  /** Each of the locale's ten digits → its ASCII digit. */
+  readonly digits: ReadonlyMap<string, string>;
+  /** The locale's own grouping of an integer, in ASCII digits: what a typed group must match. */
+  readonly grouped: (integer: string) => string;
+}
+
+const formatters = new Map<string, Intl.NumberFormat>();
+/** Every formatter through core's bounded cache, keyed on the screened tag: `format.ts`'s rule. */
+const formatterOf = (tag: string, kind: string): Intl.NumberFormat =>
+  cachedFormatter(formatters, `${tag}|${kind}`, () =>
+    kind === 'grouped' || kind === 'plain'
+      ? new Intl.NumberFormat(tag, { useGrouping: kind === 'grouped', maximumFractionDigits: 0 })
+      : kind === 'parts'
+        ? new Intl.NumberFormat(tag)
+        : new Intl.NumberFormat(tag, { style: 'currency', currency: kind }),
+  );
+
+/** The spaces a group separator may be typed as: a keyboard has no narrow no-break space. */
+const SPACES = new Set([' ', ' ', ' ', ' ']);
+
+function numeralsOf(tag: string): LocaleNumerals {
+  const parts = formatterOf(tag, 'parts').formatToParts(-1234567.5);
+  const part = (type: string, fallback: string): string =>
+    parts.find((each) => each.type === type)?.value ?? fallback;
+  const plain = formatterOf(tag, 'plain');
+  const digits = new Map<string, string>();
+  for (let digit = 0; digit <= 9; digit += 1) digits.set(plain.format(digit), String(digit));
+  const toAscii = (text: string): string =>
+    [...text].map((char) => digits.get(char) ?? char).join('');
+  const grouping = formatterOf(tag, 'grouped');
+  return {
+    decimal: part('decimal', '.'),
+    group: part('group', ','),
+    minus: part('minusSign', '-'),
+    digits,
+    // `BigInt` formats an integer of any length exactly: no float between the digits and `Intl`.
+    grouped: (integer) => toAscii(grouping.format(BigInt(integer))),
+  };
+}
+
+const refused = (text: string, locale: string, currency: string, reason: string): MoneyError =>
+  new MoneyError({
+    code: 'X_MONEY_INPUT_INVALID',
+    cause: `the amount typed could not be read as ${currency} in ${locale}: ${reason}`,
+    fix: `parseAmount(text, { currency: '${currency}', locale: '${locale}' })   # re-prompt the person for the amount; nothing was rounded or guessed`,
+    meta: { locale, currency, length: text.length },
+  });
+
+/**
+ * `parseAmount('1.234,56', { currency: 'EUR', locale: 'de-DE' })` → 123456 EUR. A currency symbol
+ * or code the locale writes is allowed and ignored; a sign is the locale's minus or `-`. Refused
+ * (`X_MONEY_INPUT_INVALID`): a character the locale does not use in a number, a group separator out
+ * of the locale's own grouping (`1.5` in `de-DE` is not 1.5 and not 15), a second decimal mark, and
+ * more fraction digits than the currency has — `1,234` in `de-DE` is 1.234, and EUR has two.
+ */
+export function parseAmount(text: string, options: ParseAmountOptions): Money {
+  const tag = assertLocale(options.locale);
+  const code = assertCurrency(options.currency);
+  const fail = (reason: string): MoneyError => refused(text, tag, code, reason);
+  const numerals = numeralsOf(tag);
+  const symbols = formatterOf(tag, code)
+    .formatToParts(1)
+    .filter((each) => each.type === 'currency')
+    .map((each) => each.value);
+
+  let rest = text.trim();
+  for (const symbol of [...symbols, code]) rest = rest.replace(symbol, '').trim();
+  // Bidi marks travel with a copied right-to-left amount; they are not characters of the number.
+  rest = rest.replace(/[‎‏؜]/g, '');
+  let negative = false;
+  if (rest.startsWith(numerals.minus) || rest.startsWith('-')) {
+    negative = true;
+    rest = rest.slice(rest.startsWith(numerals.minus) ? numerals.minus.length : 1).trim();
+  }
+  if (rest === '') throw fail('there are no digits');
+
+  const isGroup = (char: string): boolean =>
+    char === numerals.group || (SPACES.has(numerals.group) && SPACES.has(char));
+  let integer = '';
+  let typedInteger = '';
+  let fraction: string | undefined;
+  for (const char of rest) {
+    const digit = numerals.digits.get(char) ?? (/^[0-9]$/.test(char) ? char : undefined);
+    if (digit !== undefined) {
+      if (fraction === undefined) {
+        integer += digit;
+        typedInteger += digit;
+      } else fraction += digit;
+    } else if (char === numerals.decimal) {
+      if (fraction !== undefined) throw fail(`${renderCauseValue(char)} appears twice`);
+      fraction = '';
+    } else if (isGroup(char)) {
+      if (fraction !== undefined) {
+        throw fail(`${renderCauseValue(char)} groups digits after the decimal mark`);
+      }
+      typedInteger += numerals.group;
+    } else {
+      throw fail(`${renderCauseValue(char)} is not part of a number in ${tag}`);
+    }
+  }
+  if (integer === '' && (fraction === undefined || fraction === '')) {
+    throw fail('there are no digits');
+  }
+  // Grouped as the locale groups, or not grouped at all: anything else is a reading two people
+  // would disagree on, and the person is asked again rather than one of them being guessed.
+  if (typedInteger !== integer && typedInteger !== numerals.grouped(integer)) {
+    throw fail(`${renderCauseValue(numerals.group)} does not group the digits the way ${tag} does`);
+  }
+  const exponent = exponentOf(code);
+  if (fraction !== undefined && fraction.length > exponent) {
+    throw fail(`${fraction.length} digits after the decimal mark, and ${code} has ${exponent}`);
+  }
+  const decimal = `${negative ? '-' : ''}${integer === '' ? '0' : integer}${
+    fraction === undefined || fraction === '' ? '' : `.${fraction}`
+  }`;
+  return fromDecimal(decimal, code);
+}