@reventlessdev/reventless-spec 3.0.0-alpha.123 → 3.0.0-alpha.124

package/src/semantic/Money.res

@@ -5,7 +5,7 @@ those units belong to.
 ## Why the currency travels with the number
 
 A minor unit is currency-dependent — ISO 4217 gives EUR two decimal places, **JPY
-zero** and **TND three** — so a bare `1000` is €10.00 or ¥1000 or 1.000 TND, and
+zero** and TND three — so a bare `1000` is €10.00 or ¥1000 or 1.000 TND, and
 there is no way to tell which. It cannot be rendered, compared, summed or
 sanity-checked without knowing. The currency is part of the number's meaning, not
 metadata beside it.
@@ -22,6 +22,20 @@ instead — see below.
 `0.1 +. 0.2` is not `0.3`, and money is summed. Minor units keep every amount an
 exact integer, so addition is exact and equality means what it says.
 
+This was tried the other way — an amount holding the decimal a person types —
+and reverted. What it bought was a readable log; what it cost was the guarantee.
+Every sum outside `add` became a float sum, including the ones a read side does
+over a page of rows, and the failure is a figure that is a cent out and looks
+entirely plausible. Binary floating point is not what money is counted in, and
+holding the exact value in a `float` only works while nothing does arithmetic on
+it — which is not a property a framework type can promise on behalf of everyone
+downstream.
+
+**The complaint that prompted the attempt was real and is answered elsewhere.** A
+form generated from this schema must not ask anyone for `1050`; it asks for
+`10.50` and converts at its own boundary, with `ofMajor`/`toMajor` below. That is
+a presentation concern, and this type had been letting it leak.
+
 ## Why `float` for a whole number
 
 Because ReScript's `int` is int32, and sury enforces that — an `int` amount caps
@@ -72,12 +86,15 @@ let validateAmount = (amount: float): result<float, string> =>
     Ok(amount)
   }
 
-/** The amount's own schema. The check sits on the field rather than on the pair
-    because wholeness is a property of the amount — and because sury 11-alpha
-    miscompiles a refinement wrapping a *record* schema (it hoists the result
-    object above the field reads, so both parse and serialize throw
-    `Cannot access 'v0' before initialization`). Refining the field is both the
-    honest placement and the one that works. */
+/** The amount's own schema.
+
+    The check sits on the field rather than on the pair because wholeness is a
+    property of the amount: it does not need the currency, and a rule placed
+    where it needs nothing else is a rule that cannot be read wrong. (A
+    record-level refinement is available — sury 11.0.0-rc.2 compiles one
+    correctly, where 11-alpha hoisted the result object above the field reads and
+    threw `Cannot access 'v0' before initialization` — it is simply not what this
+    check wants.) */
 let amountSchema: S.t<float> =
   S.float->S.refine(
     amount =>
@@ -109,34 +126,41 @@ let make = (~amount: float, ~currency: Currency.t): t => {amount, currency}
     euros" are different claims, and only the second one adds to a total. */
 let zero = (~currency: Currency.t): t => {amount: 0.0, currency}
 
+/** Ten to the power of the currency's decimal count — the factor between a major
+    amount and the minor units it is. Named because the two conversions below
+    both need it and neither should spell out `Math.pow` again. */
+let scale = (currency: Currency.t): float =>
+  Math.pow(10.0, ~exp=Int.toFloat(Currency.exponent(currency)))
+
 /**
 Convert a major-unit decimal (`10.5`) into minor units (`1050`), using the
 currency's own exponent.
 
 This is the one place a decimal is allowed to become money, and it is here rather
 than at each call site precisely so that `*. 100.0` is written once and is
-correct for JPY and TND — where it would be `*. 1.0` and `*. 1000.0`.
+correct for JPY and TND — where it would be `*. 1.0` and `*. 1000.0`. It is what
+a form, a supplier feed or any other boundary that speaks in decimals converts
+through.
 
-Rounds half away from zero (`10.005` EUR → `1001`), which is what a reader
-expects of a price. That is a *boundary conversion* and not an arithmetic
-policy: the half-even question that FX and tax rounding turn on is a separate
-decision, and nothing here forecloses it.
+Rounds half away from zero, in both directions: `Math.round` alone rounds half
+toward positive infinity, so `-2.5` would come back `-2` and a refund would round
+the other way from the charge it reverses. That is a *boundary conversion* and
+not an arithmetic policy: the half-even question that FX and tax rounding turn on
+is a separate decision, and nothing here forecloses it.
 */
 let ofMajor = (~amount: float, ~currency: Currency.t): t => {
-  let scale = Math.pow(10.0, ~exp=Int.toFloat(Currency.exponent(currency)))
-  {amount: Math.round(amount *. scale), currency}
+  let scaled = amount *. scale(currency)
+  {amount: scaled < 0.0 ? -.Math.round(-.scaled) : Math.round(scaled), currency}
 }
 
-/** The amount as a major-unit decimal — for charts, averages and anything that
-    has to be a number rather than money. Lossy by nature: the result is a float
-    again, so it is an output, not something to compute a balance in. */
-let toMajor = (m: t): float =>
-  m.amount /. Math.pow(10.0, ~exp=Int.toFloat(Currency.exponent(m.currency)))
+/** The amount as a major-unit decimal — what a form shows, and what a chart axis
+    or an average needs. Lossy by nature: the result is a float again, so it is an
+    output, not something to compute a balance in. */
+let toMajor = (m: t): float => m.amount /. scale(m.currency)
 
 /**
 The amount as text: the decimal point placed by the currency's exponent, digits
-grouped in threes, and the ISO code after it — `"1,234.50 EUR"`, `"1,000 JPY"`,
-`"1.000 TND"`.
+grouped in threes, and the ISO code after it — `"1,234.50 EUR"`, `"1,000 JPY"`.
 
 Deliberately locale-independent, matching the rest of the framework's
 formatters: the same value reads the same in every log line and every test. A
@@ -176,6 +200,9 @@ branded-scalar shape was that mixing currencies could not be written at all; the
 answer is to *check* it rather than to delete the information that makes checking
 possible. An aggregate that must hold one currency rejects a line item in
 another — a decider's concern, and one it can now actually express.
+
+The addition itself is integer addition, because both amounts are whole minor
+units. That is the whole reason they are.
 */
 let add = (a: t, b: t): result<t, string> =>
   a.currency == b.currency
@@ -185,6 +212,81 @@ let add = (a: t, b: t): result<t, string> =>
         `Converting between them needs a rate, which is not something an amount carries.`,
       )
 
+/** The largest whole number a `float` holds exactly, 2^53 - 1. Bound here
+    because `Float.Constants` does not carry it, and named because it is the
+    range every guarantee in this module is stated over. */
+@val @scope("Number") external maxSafeInteger: float = "MAX_SAFE_INTEGER"
+
+/**
+Multiply an amount by a count — a line item's unit price by its quantity.
+
+`~by` is an `int` because the operand is a *count* and not a rate: three of
+something, not 15% of something. Whole minor units times a whole count is
+whole-number arithmetic, so the result is an exact amount and no rounding
+question arises at all. That is the property this function exists to keep, and it
+is why a call site should not write `amount *. Int.toFloat(quantity)` itself.
+
+A rate is the other operation, and deliberately not this one. 15% of €10.50 is
+€8.925, which is not an amount of euros in the first place — so applying a rate
+is a rounding decision the domain has to state, through `toMajor`, the
+arithmetic, and `ofMajor` back, with the rounding visible where someone chose it.
+
+Refuses a product past the range where a `float` is an exact integer. Handing
+back an inexact amount is the failure the wholeness check exists to prevent, and
+it would not do to introduce it here.
+*/
+let times = (m: t, ~by: int): result<t, string> => {
+  let product = m.amount *. Int.toFloat(by)
+  Math.abs(product) <= maxSafeInteger
+    ? Ok({amount: product, currency: m.currency})
+    : Error(
+        `cannot multiply ${format(m)} by ${Int.toString(by)}: the result is past the ` ++
+        `largest amount that stays exact, ${Float.toString(maxSafeInteger)} minor units.`,
+      )
+}
+
+/**
+Split an amount into `into` parts that add back up to it.
+
+The last minor unit has to go somewhere. Dividing and rounding each part on its
+own loses or invents one — €10.00 into three is €3.33 three times, which is
+€9.99 — so the remainder is handed out instead: the first parts get one minor
+unit more than the rest. €10.00 into three is €3.34, €3.33, €3.33, and those add
+up to €10.00.
+
+*Which* parts get the extra unit is arbitrary, but it has to be decided rather
+than left to a rounding mode, and "the earliest" is the decision here. A caller
+that needs it somewhere else — the largest share, the payer's — reorders what it
+gets back. A caller that needs uneven shares wants a split by ratio, which is a
+different function and not this one.
+
+A negative amount splits away from zero the same way: -€10.00 into three is
+-€3.34, -€3.33, -€3.33. A refund divides like a charge.
+*/
+let allocate = (m: t, ~into: int): result<array<t>, string> =>
+  if into <= 0 {
+    Error(
+      `cannot split ${format(m)} into ${Int.toString(into)} parts: ` ++
+      `a split is into at least one part.`,
+    )
+  } else {
+    let parts = Int.toFloat(into)
+    // Truncated toward zero, so the remainder carries the sign of the amount and
+    // every part stays on the same side of zero as the whole it came from.
+    let share = Math.trunc(m.amount /. parts)
+    // Taken from the share actually used rather than from the ideal one, which
+    // is what makes the parts add back up by construction.
+    let remainder = m.amount -. share *. parts
+    let step = remainder < 0.0 ? -1.0 : 1.0
+    let extra = Math.abs(remainder)
+    Ok(
+      Array.fromInitializer(~length=into, i => {
+        amount: share +. (Int.toFloat(i) < extra ? step : 0.0),
+        currency: m.currency,
+      }),
+    )
+  }
+
 /** Add a run of amounts, refusing at the first currency that does not match the
     first amount's. `None` for an empty run — the sum of no amounts has no
     currency to be in. */

package/src/semantic/Money.res.mjs

@@ -54,10 +54,14 @@ function zero(currency) {
   };
 }
 
+function scale(currency) {
+  return Math.pow(10.0, Currency$Reventless.exponent(currency));
+}
+
 function ofMajor(amount, currency) {
-  let scale = Math.pow(10.0, Currency$Reventless.exponent(currency));
+  let scaled = amount * Math.pow(10.0, Currency$Reventless.exponent(currency));
   return {
-    amount: Math.round(amount * scale),
+    amount: scaled < 0.0 ? - Math.round(- scaled) : Math.round(scaled),
     currency: currency
   };
 }
@@ -108,6 +112,46 @@ function add(a, b) {
   }
 }
 
+function times(m, by) {
+  let product = m.amount * by;
+  if (Math.abs(product) <= Number.MAX_SAFE_INTEGER) {
+    return {
+      TAG: "Ok",
+      _0: {
+        amount: product,
+        currency: m.currency
+      }
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: `cannot multiply ` + format(m) + ` by ` + by.toString() + `: the result is past the ` + (`largest amount that stays exact, ` + Number.MAX_SAFE_INTEGER.toString() + ` minor units.`)
+    };
+  }
+}
+
+function allocate(m, into) {
+  if (into <= 0) {
+    return {
+      TAG: "Error",
+      _0: `cannot split ` + format(m) + ` into ` + into.toString() + ` parts: a split is into at least one part.`
+    };
+  }
+  let share = Math.trunc(m.amount / into);
+  let remainder = m.amount - share * into;
+  let step = remainder < 0.0 ? -1.0 : 1.0;
+  let extra = Math.abs(remainder);
+  return {
+    TAG: "Ok",
+    _0: Stdlib_Array.fromInitializer(into, i => ({
+      amount: share + (
+        i < extra ? step : 0.0
+      ),
+      currency: m.currency
+    }))
+  };
+}
+
 function sum(amounts) {
   if (amounts.length !== 0) {
     return Stdlib_Array.reduce(amounts, {
@@ -126,10 +170,13 @@ export {
   schema$1 as schema,
   make,
   zero,
+  scale,
   ofMajor,
   toMajor,
   format,
   add,
+  times,
+  allocate,
   sum,
 }
 /* amountSchema Not a pure module */

package/scripts/generate-currency.mjs

@@ -1,215 +0,0 @@
-#!/usr/bin/env node
-// Generates `src/semantic/Currency.res` from the ISO 4217 table beside this
-// script (`iso-4217-list-one.xml`, the standard's own "current currency & funds"
-// publication).
-//
-// Why generated rather than hand-written: the codes and the minor-unit
-// exponents have to agree, and the exponent is what makes `Money.format`
-// derivable instead of a hardcoded `/100`. Taking both from one source makes
-// them agree by construction — nobody has to remember that JPY has no decimals
-// and TND has three.
-//
-// Updating to a newer ISO publication:
-//
-//     curl -sL https://www.six-group.com/dam/download/financial-information/\
-//     data-center/iso-currrency/lists/list-one.xml \
-//       -o reventless/spec/scripts/iso-4217-list-one.xml
-//     pnpm --filter @reventlessdev/reventless-spec run generate:currency
-//
-// The output is committed: it is read in review, and a currency appearing or
-// disappearing is exactly the kind of change that has to show up in a diff.
-
-import {readFileSync, writeFileSync} from 'node:fs'
-import {dirname, join} from 'node:path'
-import {fileURLToPath} from 'node:url'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const source = join(here, 'iso-4217-list-one.xml')
-const target = join(here, '..', 'src', 'semantic', 'Currency.res')
-
-const xml = readFileSync(source, 'utf8')
-
-const published = xml.match(/<ISO_4217[^>]*Pblshd="([^"]+)"/)?.[1]
-if (!published) throw new Error(`no Pblshd date in ${source} — is this the ISO 4217 list?`)
-
-const field = (entry, tag) => entry.match(new RegExp(`<${tag}>([^<]*)</${tag}>`))?.[1]?.trim()
-
-// One entry per country, so a currency used in several countries repeats. Keyed
-// by code; a repeat that disagrees about the exponent is a corrupt table, not
-// something to pick a winner from.
-const byCode = new Map()
-const skipped = []
-
-for (const [, entry] of xml.matchAll(/<CcyNtry>([\s\S]*?)<\/CcyNtry>/g)) {
-  const code = field(entry, 'Ccy')
-  // Territories with no currency of their own (Antarctica) carry no <Ccy>.
-  if (!code) continue
-  const minorUnits = field(entry, 'CcyMnrUnts')
-  const name = field(entry, 'CcyNm')
-
-  // `N.A.` means the entry has no minor unit at all: the precious metals (XAU,
-  // XAG, XPD, XPT), the bond market units (XBA–XBD), XDR, XUA, XSU, the testing
-  // code XTS and the "no currency" sentinel XXX. Admitting them would make
-  // `exponent` partial, which is the one property this type exists to have — so
-  // the standard's own table draws the line rather than a curated opinion. A
-  // field holding a weight of gold is not holding money.
-  if (!/^\d+$/.test(minorUnits ?? '')) {
-    if (!skipped.some(s => s.code === code)) skipped.push({code, name, minorUnits})
-    continue
-  }
-
-  const exponent = Number(minorUnits)
-  const seen = byCode.get(code)
-  if (seen && seen.exponent !== exponent) {
-    throw new Error(
-      `${code} has two exponents in ${source}: ${seen.exponent} and ${exponent}`,
-    )
-  }
-  if (!seen) byCode.set(code, {code, name, exponent})
-}
-
-const currencies = [...byCode.values()].sort((a, b) => a.code.localeCompare(b.code))
-if (currencies.length < 100) {
-  throw new Error(`only ${currencies.length} currencies parsed — the table did not parse`)
-}
-
-// The generated file quotes each currency's ISO name beside its constructor, so
-// a reviewer reading a three-letter code does not have to look it up.
-const constructors = currencies
-  .map(c => `  | /** ${c.name} */ ${c.code}`)
-  .join('\n')
-
-const exponentArms = currencies
-  .map(c => `  | ${c.code} => ${c.exponent}`)
-  .join('\n')
-
-const toStringArms = currencies.map(c => `  | ${c.code} => "${c.code}"`).join('\n')
-
-// Wrapped rather than one 1,000-character line, so a code added or removed by a
-// future ISO publication shows up as a one-line diff.
-const all = currencies
-  .map(c => c.code)
-  .reduce((lines, code) => {
-    const last = lines[lines.length - 1]
-    if (last && `${last} ${code},`.length <= 96) lines[lines.length - 1] = `${last} ${code},`
-    else lines.push(`  ${code},`)
-    return lines
-  }, [])
-  .join('\n')
-
-const exponentCounts = [...new Set(currencies.map(c => c.exponent))]
-  .sort()
-  .map(e => `${currencies.filter(c => c.exponent === e).length}×${e}`)
-  .join(', ')
-
-const skippedCodes = skipped.map(s => s.code).sort()
-const group = codes => codes.filter(c => skippedCodes.includes(c)).join(', ')
-const metals = group(['XAG', 'XAU', 'XPD', 'XPT'])
-const bondUnits = group(['XBA', 'XBB', 'XBC', 'XBD'])
-const rights = group(['XDR', 'XSU', 'XUA'])
-
-const out = `// AUTO-GENERATED from ISO 4217 (published ${published}) — do not edit.
-// Run \`pnpm --filter @reventlessdev/reventless-spec run generate:currency\`,
-// or see \`scripts/generate-currency.mjs\` to update the source table first.
-
-/**
-A currency, closed to the ${currencies.length} codes ISO 4217 defines a minor unit for.
-
-## Why a type and not a three-letter string
-
-A string field invites \`"eur"\` beside \`"EUR"\`, and two spellings of one
-currency is a class of bug that reads as a data problem long after it became a
-correctness problem — the values are present, and they simply never match. A
-closed type makes the second spelling unwritable.
-
-## Why generated, and why every code
-
-The alternative was a curated handful (EUR, USD, GBP, JPY, …), which is small
-and readable and wrong the first time an application needs a currency nobody
-listed — a compile error in someone else's domain, fixable only by a framework
-release. The thing being avoided by curating is ${currencies.length} constructors that are
-machine-written and never read in full; the thing being risked is a release.
-
-Generation also buys the property that makes this type worth having: \`exponent\`
-comes from the *same* source as the codes, so it cannot drift from them
-(${exponentCounts} decimal places across the set). That is what lets
-\`Money.format\` derive its decimal placement instead of hardcoding \`/100\`, and
-therefore what makes it correct for JPY and TND without anyone remembering that
-those two are special.
-
-## What is deliberately absent
-
-The ${skipped.length} entries ISO lists with no minor unit: the precious metals
-(${metals}), the bond market units (${bondUnits}), the accounting
-units (${rights}), the testing code XTS, and the "no currency"
-sentinel XXX. Each would make \`exponent\` partial, and a weight of gold is not
-an amount of money. The standard's own table draws that line, so it is not a
-curated opinion after all.
-
-## The wire form
-
-A payload-less variant, so the stored and transmitted form is the three-letter
-code itself — \`{"amount": 1000, "currency": "EUR"}\`. Standard at the boundary,
-a checked type in the domain.
-*/
-@schema
-type t =
-${constructors}
-
-/** Every currency, in code order. \`fromString\` is derived from this, so a code
-    that parses and a code that exists are the same set by construction. */
-let all: array<t> = [
-${all}
-]
-
-/** The currency's ISO 4217 alphabetic code. */
-let toString = (currency: t): string =>
-  switch currency {
-${toStringArms}
-  }
-
-/**
-How many decimal places the currency's minor unit is: 2 for EUR, **0 for JPY**,
-**3 for TND**, 4 for the Chilean Unidad de Fomento.
-
-Total by construction — this is the whole reason the type is closed and the
-table is generated. An amount is stored in integer minor units, so this is the
-only thing that says where its decimal point goes.
-*/
-let exponent = (currency: t): int =>
-  switch currency {
-${exponentArms}
-  }
-
-let byCode: dict<t> = {
-  let d = Dict.make()
-  all->Array.forEach(c => d->Dict.set(toString(c), c))
-  d
-}
-
-/**
-Parse an ISO 4217 alphabetic code, saying why when it is not one.
-
-Case-sensitive on purpose: \`"eur"\` is rejected rather than repaired. This type
-exists because a silent case mismatch is expensive to find, and quietly
-accepting the wrong spelling at the boundary would put it back — a producer
-sending lowercase codes should learn that at its first request, not at the first
-report that two halves of a ledger disagree.
-*/
-let fromString = (raw: string): result<t, string> =>
-  switch byCode->Dict.get(raw) {
-  | Some(c) => Ok(c)
-  | None =>
-    Error(
-      \`expected an ISO 4217 currency code such as "EUR", got \${raw
-        ->JSON.Encode.string
-        ->JSON.stringify}. Codes are upper-case and exactly three letters.\`,
-    )
-  }
-`
-
-writeFileSync(target, out)
-console.log(
-  `Currency.res: ${currencies.length} currencies (${exponentCounts} decimals), ` +
-    `ISO 4217 published ${published}, ${skipped.length} minor-unit-less entries skipped.`,
-)