@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/semantic/GeoPoint.res.mjs

@@ -0,0 +1,190 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function validateLat(raw) {
+  if (isFinite(raw)) {
+    if (raw < -90.0 || raw > 90.0) {
+      return {
+        TAG: "Error",
+        _0: `a latitude runs from -90 to 90 degrees, got ` + raw.toString() + `. A value beyond ±90 is usually a longitude in the latitude's place.`
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a latitude must be a finite number of degrees, got ` + raw.toString()
+    };
+  }
+}
+
+function validateLng(raw) {
+  if (isFinite(raw)) {
+    if (raw < -180.0 || raw > 180.0) {
+      return {
+        TAG: "Error",
+        _0: `a longitude runs from -180 to 180 degrees, got ` + raw.toString()
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a longitude must be a finite number of degrees, got ` + raw.toString()
+    };
+  }
+}
+
+let latSchema = S.refine(S.float, s => (raw => {
+  let why = validateLat(raw);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let lngSchema = S.refine(S.float, s => (raw => {
+  let why = validateLng(raw);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let schema = S.schema(s => ({
+  lat: s.m(latSchema),
+  lng: s.m(lngSchema)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.geoPoint, undefined);
+
+function make(lat, lng) {
+  let match = validateLat(lat);
+  let match$1 = validateLng(lng);
+  if (match.TAG === "Ok") {
+    if (match$1.TAG === "Ok") {
+      return {
+        TAG: "Ok",
+        _0: {
+          lat: match._0,
+          lng: match$1._0
+        }
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: match$1._0
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: match._0
+    };
+  }
+}
+
+function format(p) {
+  return p.lat.toString() + `, ` + p.lng.toString();
+}
+
+function toRadians(degrees) {
+  return degrees * Math.PI / 180.0;
+}
+
+function distanceTo(a, b) {
+  let lat1 = toRadians(a.lat);
+  let lat2 = toRadians(b.lat);
+  let dLat = toRadians(b.lat - a.lat);
+  let dLng = toRadians(b.lng - a.lng);
+  let h = Math.sin(dLat / 2.0) * Math.sin(dLat / 2.0) + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2.0) * Math.sin(dLng / 2.0);
+  return 2.0 * Math.asin(Math.sqrt(Math.min(1.0, h))) * 6371008.8;
+}
+
+function toGeoJson(p) {
+  return Object.fromEntries([
+    [
+      "type",
+      "Point"
+    ],
+    [
+      "coordinates",
+      [
+        p.lng,
+        p.lat
+      ]
+    ]
+  ]);
+}
+
+function fromGeoJson(json) {
+  let o = Stdlib_JSON.Decode.object(json);
+  if (o === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point is an object"
+    };
+  }
+  let other = Stdlib_Option.flatMap(o["type"], Stdlib_JSON.Decode.string);
+  if (other === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON geometry has a type"
+    };
+  }
+  if (other !== "Point") {
+    return {
+      TAG: "Error",
+      _0: `expected a GeoJSON Point, got ` + other
+    };
+  }
+  let coords = Stdlib_Option.flatMap(o["coordinates"], Stdlib_JSON.Decode.array);
+  if (coords === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point has a coordinates array"
+    };
+  }
+  let match = Stdlib_Option.flatMap(coords[0], Stdlib_JSON.Decode.float);
+  let match$1 = Stdlib_Option.flatMap(coords[1], Stdlib_JSON.Decode.float);
+  if (match !== undefined && match$1 !== undefined) {
+    return make(match$1, match);
+  } else {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point's coordinates are two numbers, [lng, lat]"
+    };
+  }
+}
+
+let earthRadiusMetres = 6371008.8;
+
+export {
+  validateLat,
+  validateLng,
+  latSchema,
+  lngSchema,
+  schema$1 as schema,
+  make,
+  format,
+  earthRadiusMetres,
+  toRadians,
+  distanceTo,
+  toGeoJson,
+  fromGeoJson,
+}
+/* latSchema Not a pure module */

package/src/semantic/Geocoding.res

@@ -0,0 +1,127 @@
+/**
+Turning an address into a point, and deciding whether to believe the answer.
+
+The *transport* is provider-specific — Amazon Location, a self-hosted Nominatim,
+a vendor's HTTP API — and lives with its provider. What lives here is everything
+that is the same regardless of who answers: the shape of an answer, the two ways
+a lookup can fail, and the rule for when a ranked list is confident enough to
+write a coordinate into an event log.
+
+That split matters because the confidence rule is the part that is easy to get
+wrong and expensive to get wrong twice. A caller that re-derives it — takes
+`results[0]` because the list was ranked — produces a plausible marker in the
+wrong region, drawn without an error anywhere. Deciding it once, here, is what
+stops each transport inventing its own answer.
+*/
+
+/** One candidate a geocoder returned. */
+type candidate = {
+  /** The provider's canonical rendering of the address it matched. */
+  label: string,
+  point: GeoPoint.t,
+  /**
+  How well this result matches the query, 0…1.
+
+  `None` when the provider does not score its results. That is not the same as a
+  low score and must not be read as a high one — `confidentMatch` declines it,
+  because an unscored list cannot support an unattended decision.
+  */
+  relevance: option<float>,
+}
+
+/**
+Why a lookup produced no usable point.
+
+Two constructors rather than one message because the caller's retry decision
+turns on exactly this distinction, and a `switch` is the only form of it that
+cannot be got wrong. A translator that cannot tell "no such address" from "the
+service is down" turns one outage into a permanent verdict on every address in
+flight.
+*/
+type failure =
+  | /** The provider could not be reached, or refused the call. Retry. */
+  Unavailable(string)
+  | /** The provider answered, and had nothing for this text. Do not retry. */
+  NoMatch
+
+/**
+The port a caller reaches a geocoder through.
+
+Everything above says what an answer looks like; this says how one is asked for.
+Written down as a type before anything is injected against it, so that swapping
+the implementation underneath a caller is a change of *supplier* rather than a
+change of call site: whatever eventually hands a translator its geocoder — an
+HTTP client reading an endpoint out of its environment, a provider SDK called
+directly — has to satisfy this, and the `await search(~text=…)` in the caller
+does not move.
+
+`~text` is the address as a human typed it, unnormalised. Normalising it is the
+provider's job, and its canonical rendering comes back as `candidate.label`.
+*/
+type search = (~text: string) => promise<result<array<candidate>, failure>>
+
+/**
+The default confidence floor, calibrated against Amazon Location's Esri index.
+
+Measured, not guessed — and the measurement moved it a long way. Esri does not
+spread its scores over 0…1: everything it is willing to return at all lands in
+roughly 0.9…1.0, so a floor of `0.8` admitted almost every answer and left the
+ambiguity margin doing all the work. The separation is up at the top of the
+range instead — in a 24-address corpus the correct pinpoint matches scored
+≥ 0.988 while the wrong ones (a misspelling resolved to the wrong state, a
+street name matched to a different street in the right city) scored 0.913…0.958.
+
+`0.97` sits in that gap. The wider consequence is that these numbers are
+*provider-calibrated* even though everything else in this module is
+provider-neutral, which is exactly why both are labelled arguments: a geocoder
+that scores on a different curve needs its own pair, and the defaults are the
+Esri answer rather than a universal one.
+*/
+let defaultMinRelevance = 0.97
+
+/**
+How close the runner-up may come before the answer is called ambiguous.
+
+Deliberately small, for the same reason the floor is large. Genuine ambiguity in
+Esri shows up as a *tie* — "Springfield" returns five states at exactly 1.0,
+"221B Baker" five towns at exactly 0.8222 — not as a near miss. A wide margin
+does not catch more of those; it only starts rejecting clear winners, because a
+correct match at 0.991 routinely has a plausible runner-up at 0.962.
+*/
+let defaultAmbiguityMargin = 0.01
+
+/**
+The one candidate confident enough to store, or `None`.
+
+Two ways to be unsure, and both decline:
+
+- the top candidate scores below `minRelevance` — the provider matched
+  something, loosely;
+- the runner-up scores within `ambiguityMargin` of the top — the provider
+  matched several things about equally well, which is what a bare town name
+  does.
+
+`None` means "ask a human", not "no result". The candidates are still there for
+a caller that wants to show them.
+*/
+let confidentMatch = (
+  candidates: array<candidate>,
+  ~minRelevance: float=defaultMinRelevance,
+  ~ambiguityMargin: float=defaultAmbiguityMargin,
+): option<candidate> =>
+  switch candidates->Array.get(0) {
+  | None => None
+  | Some(top) =>
+    switch top.relevance {
+    | None => None
+    | Some(topScore) =>
+      if topScore < minRelevance {
+        None
+      } else {
+        switch candidates->Array.get(1)->Option.flatMap(c => c.relevance) {
+        | Some(runnerUp) if topScore -. runnerUp < ambiguityMargin => None
+        | _ => Some(top)
+        }
+      }
+    }
+  }

package/src/semantic/Geocoding.res.mjs

@@ -0,0 +1,36 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function confidentMatch(candidates, minRelevanceOpt, ambiguityMarginOpt) {
+  let minRelevance = minRelevanceOpt !== undefined ? minRelevanceOpt : 0.97;
+  let ambiguityMargin = ambiguityMarginOpt !== undefined ? ambiguityMarginOpt : 0.01;
+  let top = candidates[0];
+  if (top === undefined) {
+    return;
+  }
+  let topScore = top.relevance;
+  if (topScore === undefined) {
+    return;
+  }
+  if (topScore < minRelevance) {
+    return;
+  }
+  let runnerUp = Stdlib_Option.flatMap(candidates[1], c => c.relevance);
+  if (runnerUp !== undefined && topScore - runnerUp < ambiguityMargin) {
+    return;
+  } else {
+    return top;
+  }
+}
+
+let defaultMinRelevance = 0.97;
+
+let defaultAmbiguityMargin = 0.01;
+
+export {
+  defaultMinRelevance,
+  defaultAmbiguityMargin,
+  confidentMatch,
+}
+/* No side effect */

package/src/semantic/Money.res

@@ -0,0 +1,196 @@
+/**
+An amount of money: a whole number of a currency's minor units, and the currency
+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
+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.
+
+The alternative considered and rejected was a branded `amount` scalar with the
+currency held once on the aggregate. Its appeal is real: mixing currencies
+becomes unrepresentable rather than merely checkable. But it only works while
+every amount an aggregate touches shares one currency, and the moment one does
+not, the information needed to notice has already been deleted. `add` checks
+instead — see below.
+
+## Why whole minor units and not a decimal major amount
+
+`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.
+
+## Why `float` for a whole number
+
+Because ReScript's `int` is int32, and sury enforces that — an `int` amount caps
+at 2,147,483,647 minor units, which is €21,474,836.47. A framework type that
+cannot express a €22M total is not a money type. `float` is exact for every
+integer below 2^53 (about €90 trillion in cents), and the wholeness that `int`
+would have given for free is recovered by checking it in `schema`.
+
+This is the same correction `Bytes` already made for the same reason, and the
+wire form is identical either way: both are JSON numbers.
+
+## How a field declares it
+
+Unlike the branded scalars, this is not an `@s.matches` refinement — the field's
+declared type *is* `Money.t`, and sury-ppx resolves it to this module's `schema`:
+
+```rescript
+@schema type state = {
+  productId: string,
+  price: Reventless.Money.t,
+}
+```
+
+which serializes as `{"amount": 1000, "currency": "EUR"}`.
+
+**That is a structural change to the field.** Retyping an existing `price: float`
+rewrites the wire shape, so stored events no longer decode and projections must
+be rebuilt. Retyping a field in a log that has to survive needs an upcaster
+first; a log that can be discarded can take it today.
+*/
+
+/**
+Validate a minor-unit amount, saying why when it is not one.
+
+The single definition of what an amount may hold; `amountSchema` is derived from
+it rather than hand-rolling a second check, the rule `StorageRef` established.
+*/
+let validateAmount = (amount: float): result<float, string> =>
+  if !Float.isFinite(amount) {
+    Error(`an amount must be a finite number of minor units, got ${Float.toString(amount)}`)
+  } else if amount !== Math.trunc(amount) {
+    Error(
+      `an amount is a whole number of a currency's minor units, got ` ++
+      `${Float.toString(amount)}. There is no such thing as a fraction of the ` ++
+      `smallest unit — a major amount converts with Money.ofMajor.`,
+    )
+  } else {
+    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. */
+let amountSchema: S.t<float> =
+  S.float->S.refine(s => amount =>
+    switch validateAmount(amount) {
+    | Ok(_) => ()
+    | Error(why) => s.fail(why)
+    }
+  )
+
+@schema
+type t = {
+  /** Whole minor units of `currency` — 1000 is €10.00, ¥1000 or 1.000 TND
+      depending on which. Negative amounts are allowed: a refund is money. */
+  amount: @s.matches(amountSchema) float,
+  currency: Currency.t,
+}
+
+/** The sury schema for a money field, carrying the `money` semantic.
+
+    Shadows the schema sury-ppx derived from the type above: the derived one is
+    the shape, and this adds the marker the shape cannot carry. */
+let schema: S.t<t> = schema->Semantic.mark(~id=Semantic.Id.money)
+
+/** An amount already counted in minor units. */
+let make = (~amount: float, ~currency: Currency.t): t => {amount, currency}
+
+/** Nothing, in a currency. A zero still has a currency — "no money" and "no
+    euros" are different claims, and only the second one adds to a total. */
+let zero = (~currency: Currency.t): t => {amount: 0.0, 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`.
+
+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.
+*/
+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}
+}
+
+/** 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 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"`.
+
+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
+locale-aware, symbol-bearing rendering is the presentation layer's job, and it
+has the currency code to do it with.
+*/
+let format = (m: t): string => {
+  let exponent = Currency.exponent(m.currency)
+  let negative = m.amount < 0.0
+  let digits = Float.toString(negative ? -.m.amount : m.amount)
+  // Pad so there is always at least one digit left of the point: 5 minor units
+  // of EUR is "0.05", not ".05".
+  let padded = digits->String.padStart(exponent + 1, "0")
+  let split = String.length(padded) - exponent
+  let whole = padded->String.slice(~start=0, ~end=split)
+  let fraction = padded->String.slice(~start=split, ~end=String.length(padded))
+  let rec group = (s: string): string => {
+    let length = String.length(s)
+    length <= 3
+      ? s
+      : group(s->String.slice(~start=0, ~end=length - 3)) ++
+        "," ++
+        s->String.slice(~start=length - 3, ~end=length)
+  }
+  (negative ? "-" : "") ++
+  group(whole) ++
+  (exponent == 0 ? "" : "." ++ fraction) ++
+  " " ++
+  Currency.toString(m.currency)
+}
+
+/**
+Add two amounts, refusing to add across currencies.
+
+This is §15.1's second rider made executable. The genuine appeal of the
+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.
+*/
+let add = (a: t, b: t): result<t, string> =>
+  a.currency == b.currency
+    ? Ok({amount: a.amount +. b.amount, currency: a.currency})
+    : Error(
+        `cannot add ${format(b)} to ${format(a)}: they are different currencies. ` ++
+        `Converting between them needs a rate, which is not something an amount carries.`,
+      )
+
+/** 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. */
+let sum = (amounts: array<t>): option<result<t, string>> =>
+  switch amounts {
+  | [] => None
+  | _ => Some(amounts->Array.reduce(Ok(zero(~currency=(amounts->Array.getUnsafe(0)).currency)), (
+      acc,
+      m,
+    ) => acc->Result.flatMap(total => add(total, m))))
+  }

package/src/semantic/Money.res.mjs

@@ -0,0 +1,138 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Currency$Reventless from "./Currency.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function validateAmount(amount) {
+  if (isFinite(amount)) {
+    if (amount !== Math.trunc(amount)) {
+      return {
+        TAG: "Error",
+        _0: `an amount is a whole number of a currency's minor units, got ` + (amount.toString() + `. There is no such thing as a fraction of the `) + `smallest unit — a major amount converts with Money.ofMajor.`
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: amount
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `an amount must be a finite number of minor units, got ` + amount.toString()
+    };
+  }
+}
+
+let amountSchema = S.refine(S.float, s => (amount => {
+  let why = validateAmount(amount);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let schema = S.schema(s => ({
+  amount: s.m(amountSchema),
+  currency: s.m(Currency$Reventless.schema)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.money, undefined);
+
+function make(amount, currency) {
+  return {
+    amount: amount,
+    currency: currency
+  };
+}
+
+function zero(currency) {
+  return {
+    amount: 0.0,
+    currency: currency
+  };
+}
+
+function ofMajor(amount, currency) {
+  let scale = Math.pow(10.0, Currency$Reventless.exponent(currency));
+  return {
+    amount: Math.round(amount * scale),
+    currency: currency
+  };
+}
+
+function toMajor(m) {
+  return m.amount / Math.pow(10.0, Currency$Reventless.exponent(m.currency));
+}
+
+function format(m) {
+  let exponent = Currency$Reventless.exponent(m.currency);
+  let negative = m.amount < 0.0;
+  let digits = (
+    negative ? - m.amount : m.amount
+  ).toString();
+  let padded = digits.padStart(exponent + 1 | 0, "0");
+  let split = padded.length - exponent | 0;
+  let whole = padded.slice(0, split);
+  let fraction = padded.slice(split, padded.length);
+  let group = s => {
+    let length = s.length;
+    if (length <= 3) {
+      return s;
+    } else {
+      return group(s.slice(0, length - 3 | 0)) + "," + s.slice(length - 3 | 0, length);
+    }
+  };
+  return (
+    negative ? "-" : ""
+  ) + group(whole) + (
+    exponent === 0 ? "" : "." + fraction
+  ) + " " + Currency$Reventless.toString(m.currency);
+}
+
+function add(a, b) {
+  if (a.currency === b.currency) {
+    return {
+      TAG: "Ok",
+      _0: {
+        amount: a.amount + b.amount,
+        currency: a.currency
+      }
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: `cannot add ` + format(b) + ` to ` + format(a) + `: they are different currencies. Converting between them needs a rate, which is not something an amount carries.`
+    };
+  }
+}
+
+function sum(amounts) {
+  if (amounts.length !== 0) {
+    return Stdlib_Array.reduce(amounts, {
+      TAG: "Ok",
+      _0: {
+        amount: 0.0,
+        currency: amounts[0].currency
+      }
+    }, (acc, m) => Stdlib_Result.flatMap(acc, total => add(total, m)));
+  }
+}
+
+export {
+  validateAmount,
+  amountSchema,
+  schema$1 as schema,
+  make,
+  zero,
+  ofMajor,
+  toMajor,
+  format,
+  add,
+  sum,
+}
+/* amountSchema Not a pure module */