@agoric/ertp 0.16.3-other-dev-8f8782b.0 → 0.16.3-other-dev-fbe72e7.0.fbe72e7

package/src/purse.js

@@ -1,27 +1,73 @@
-import { M } from '@agoric/store';
-import { prepareExoClassKit, makeScalarBigSetStore } from '@agoric/vat-data';
+import { Fail } from '@endo/errors';
+import { M, makeCopySet } from '@agoric/store';
 import { AmountMath } from './amountMath.js';
 import { makeTransientNotifierKit } from './transientNotifier.js';
+import { makeAmountStore } from './amountStore.js';
 
-const { Fail } = assert;
+/** @import {AssetKind, RecoverySetsOption, Brand, Payment} from './types.js' */
 
+const EMPTY_COPY_SET = makeCopySet([]);
+
+// TODO Type InterfaceGuard better than InterfaceGuard<any>
+/**
+ * @param {import('@agoric/zone').Zone} issuerZone
+ * @param {string} name
+ * @param {AssetKind} assetKind
+ * @param {Brand} brand
+ * @param {{
+ *   purse: import('@endo/patterns').InterfaceGuard<any>;
+ *   depositFacet: import('@endo/patterns').InterfaceGuard<any>;
+ * }} PurseIKit
+ * @param {{
+ *   depositInternal: any;
+ *   withdrawInternal: any;
+ * }} purseMethods
+ * @param {RecoverySetsOption} recoverySetsState
+ * @param {WeakMapStore<Payment, SetStore<Payment>>} paymentRecoverySets
+ */
 export const preparePurseKind = (
-  issuerBaggage,
+  issuerZone,
   name,
   assetKind,
   brand,
   PurseIKit,
   purseMethods,
+  recoverySetsState,
+  paymentRecoverySets,
 ) => {
   const amountShape = brand.getAmountShape();
 
   // Note: Virtual for high cardinality, but *not* durable, and so
   // broken across an upgrade.
+  // TODO propagate zonifying to notifiers, maybe?
   const { provideNotifier, update: updateBalance } = makeTransientNotifierKit();
 
-  const updatePurseBalance = (state, newPurseBalance, purse) => {
-    state.currentBalance = newPurseBalance;
-    updateBalance(purse, purse.getCurrentAmount());
+  /**
+   * If `recoverySetsState === 'hasRecoverySets'` (the normal state), then just
+   * return `state.recoverySet`.
+   *
+   * If `recoverySetsState === 'noRecoverySets'`, return `undefined`. Callers
+   * must be aware that the `undefined` return happens iff `recoverySetsState
+   * === 'noRecoverySets'`, and to avoid storing or retrieving anything from the
+   * actual recovery set.
+   *
+   * @param {{ recoverySet: SetStore<Payment> }} state
+   * @returns {SetStore<Payment> | undefined}
+   */
+  const maybeRecoverySet = state => {
+    const { recoverySet } = state;
+    if (recoverySetsState === 'hasRecoverySets') {
+      return recoverySet;
+    } else {
+      recoverySetsState === 'noRecoverySets' ||
+        Fail`recoverSetsState must be noRecoverySets if it isn't hasRecoverSets`;
+      paymentRecoverySets !== undefined ||
+        Fail`paymentRecoverySets must always be defined`;
+      recoverySet.getSize() === 0 ||
+        Fail`With noRecoverySets, recoverySet must be empty`;
+
+      return undefined;
+    }
   };
 
   // - This kind is a pair of purse and depositFacet that have a 1:1
@@ -31,17 +77,14 @@ export const preparePurseKind = (
   //   that created depositFacet as needed. But this approach ensures a constant
   //   identity for the facet and exercises the multi-faceted object style.
   const { depositInternal, withdrawInternal } = purseMethods;
-  const makePurseKit = prepareExoClassKit(
-    issuerBaggage,
+  const makePurseKit = issuerZone.exoClassKit(
     `${name} Purse`,
     PurseIKit,
     () => {
       const currentBalance = AmountMath.makeEmpty(brand, assetKind);
 
       /** @type {SetStore<Payment>} */
-      const recoverySet = makeScalarBigSetStore('recovery set', {
-        durable: true,
-      });
+      const recoverySet = issuerZone.detached().setStore('recovery set');
 
       return {
         currentBalance,
@@ -54,28 +97,36 @@ export const preparePurseKind = (
           // PurseI does *not* delay `deposit` until `srcPayment` is fulfulled.
           // See the comments on PurseI.deposit in typeGuards.js
           const { state } = this;
+          const { purse } = this.facets;
+          const balanceStore = makeAmountStore(state, 'currentBalance');
           // Note COMMIT POINT within deposit.
-          return depositInternal(
-            state.currentBalance,
-            newPurseBalance =>
-              updatePurseBalance(state, newPurseBalance, this.facets.purse),
+          const srcPaymentBalance = depositInternal(
+            balanceStore,
             srcPayment,
             optAmountShape,
           );
+          updateBalance(purse, balanceStore.getAmount());
+          return srcPaymentBalance;
         },
         withdraw(amount) {
           const { state } = this;
+          const { purse } = this.facets;
+
+          const optRecoverySet = maybeRecoverySet(state);
+          const balanceStore = makeAmountStore(state, 'currentBalance');
           // Note COMMIT POINT within withdraw.
-          return withdrawInternal(
-            state.currentBalance,
-            newPurseBalance =>
-              updatePurseBalance(state, newPurseBalance, this.facets.purse),
+          const payment = withdrawInternal(
+            balanceStore,
             amount,
-            state.recoverySet,
+            optRecoverySet,
           );
+          updateBalance(purse, balanceStore.getAmount());
+          return payment;
         },
         getCurrentAmount() {
-          return this.state.currentBalance;
+          const { state } = this;
+          const balanceStore = makeAmountStore(state, 'currentBalance');
+          return balanceStore.getAmount();
         },
         getCurrentAmountNotifier() {
           return provideNotifier(this.facets.purse);
@@ -83,24 +134,33 @@ export const preparePurseKind = (
         getAllegedBrand() {
           return brand;
         },
-        // eslint-disable-next-line no-use-before-define
+
         getDepositFacet() {
           return this.facets.depositFacet;
         },
 
         getRecoverySet() {
-          return this.state.recoverySet.snapshot();
+          const { state } = this;
+          const optRecoverySet = maybeRecoverySet(state);
+          if (optRecoverySet === undefined) {
+            return EMPTY_COPY_SET;
+          }
+          return optRecoverySet.snapshot();
         },
         recoverAll() {
           const { state, facets } = this;
           let amount = AmountMath.makeEmpty(brand, assetKind);
-          for (const payment of state.recoverySet.keys()) {
+          const optRecoverySet = maybeRecoverySet(state);
+          if (optRecoverySet === undefined) {
+            return amount; // empty at this time
+          }
+          for (const payment of optRecoverySet.keys()) {
             // This does cause deletions from the set while iterating,
             // but this special case is allowed.
             const delta = facets.purse.deposit(payment);
             amount = AmountMath.add(amount, delta, brand);
           }
-          state.recoverySet.getSize() === 0 ||
+          optRecoverySet.getSize() === 0 ||
             Fail`internal: Remaining unrecovered payments: ${facets.purse.getRecoverySet()}`;
           return amount;
         },

package/src/ratio.d.ts

@@ -0,0 +1,48 @@
+export function assertIsRatio(ratio: any): void;
+export function makeRatio(numerator: bigint, numeratorBrand: Brand, denominator?: bigint, denominatorBrand?: Brand): Ratio;
+export function makeRatioFromAmounts(numeratorAmount: Amount, denominatorAmount: Amount): Ratio;
+/** @type {ScaleAmount} */
+export const floorMultiplyBy: ScaleAmount;
+/** @type {ScaleAmount} */
+export const ceilMultiplyBy: ScaleAmount;
+/** @type {ScaleAmount} */
+export const multiplyBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, truncating the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const floorDivideBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, rounding up the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const ceilDivideBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, rounding to nearest with ties to even (aka
+ * Banker's Rounding) as in IEEE 754 default rounding.
+ *
+ * @type {ScaleAmount}
+ */
+export const divideBy: ScaleAmount;
+export function invertRatio(ratio: Ratio): Ratio;
+export function addRatios(left: Ratio, right: Ratio): Ratio;
+export function subtractRatios(left: Ratio, right: Ratio): Ratio;
+export function multiplyRatios(left: Ratio, right: Ratio): Ratio;
+export function oneMinus(ratio: Ratio): Ratio;
+export function ratioGTE(left: Ratio, right: Ratio): boolean;
+export function ratiosSame(left: Ratio, right: Ratio): boolean;
+export function quantize(ratio: Ratio, newDen: bigint): Ratio;
+export function parseRatio(numeric: ParsableNumber, numeratorBrand: Brand<"nat">, denominatorBrand?: Brand<"nat">): Ratio;
+export function assertParsableNumber(specimen: unknown): asserts specimen is ParsableNumber;
+export function ratioToNumber(ratio: Ratio): number;
+export type Ratio = {
+    numerator: Amount<"nat">;
+    denominator: Amount<"nat">;
+};
+export type ScaleAmount = (amount: Amount<"nat">, ratio: Ratio) => Amount<"nat">;
+export type ParsableNumber = bigint | number | string;
+import type { Brand } from '@agoric/ertp';
+import type { Amount } from '@agoric/ertp';
+//# sourceMappingURL=ratio.d.ts.map

package/src/ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratio.d.ts","sourceRoot":"","sources":["ratio.js"],"names":[],"mappings":"AAwDO,gDAcN;AASM,qCANI,MAAM,kBACN,KAAK,gBACL,MAAM,qBACN,KAAK,GACH,KAAK,CAejB;AAOM,sDAJI,MAAM,qBACN,MAAM,GACJ,KAAK,CAYjB;AA2BD,0BAA0B;AAC1B,8BADW,WAAW,CAGpB;AAEF,0BAA0B;AAC1B,6BADW,WAAW,CAGpB;AAEF,0BAA0B;AAC1B,yBADW,WAAW,CAGpB;AA2BF;;;;GAIG;AACH,4BAFU,WAAW,CAInB;AAEF;;;;GAIG;AACH,2BAFU,WAAW,CAInB;AAEF;;;;;GAKG;AACH,uBAFU,WAAW,CAInB;AAMK,mCAHI,KAAK,GACH,KAAK,CAWjB;AAOM,gCAJI,KAAK,SACL,KAAK,GACH,KAAK,CAwBjB;AAOM,qCAJI,KAAK,SACL,KAAK,GACH,KAAK,CAmBjB;AAOM,qCAJI,KAAK,SACL,KAAK,GACH,KAAK,CA8BjB;AAQM,gCAHI,KAAK,GACH,KAAK,CAcjB;AAOM,+BAJI,KAAK,SACL,KAAK,GACH,OAAO,CAkBnB;AAUM,iCAJI,KAAK,SACL,KAAK,GACH,OAAO,CAOnB;AAWM,gCAJI,KAAK,UACL,MAAM,GACJ,KAAK,CAiBjB;AAaM,oCALI,cAAc,kBACd,MAAM,KAAK,CAAC,qBACZ,MAAM,KAAK,CAAC,GACV,KAAK,CAmBjB;AAMM,+CAHI,OAAO,GACL,QAAQ,QAAQ,IAAI,cAAc,CAK9C;AAQM,qCAHI,KAAK,GACH,MAAM,CAMlB;;eAxaa,OAAO,KAAK,CAAC;iBACb,OAAO,KAAK,CAAC;;mCAKhB,OAAO,KAAK,CAAC,SACb,KAAK,KACH,OAAO,KAAK,CAAC;6BAgXZ,MAAM,GAAG,MAAM,GAAG,MAAM;2BAhYkB,cAAc;4BAAd,cAAc"}

package/src/ratio.js

@@ -0,0 +1,441 @@
+import { q, Fail } from '@endo/errors';
+import { assertRecord } from '@endo/marshal';
+import { isNat } from '@endo/nat';
+
+import { AmountMath } from './amountMath.js';
+import { natSafeMath } from './safeMath.js';
+
+/**
+ * @import {Amount, Brand, Issuer, Payment, Purse} from '@agoric/ertp';
+ */
+
+const { multiply, floorDivide, ceilDivide, bankersDivide, add, subtract } =
+  natSafeMath;
+
+/**
+ * @typedef {object} Ratio
+ * @property {Amount<'nat'>} numerator
+ * @property {Amount<'nat'>} denominator
+ */
+
+/**
+ * @callback ScaleAmount
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @returns {Amount<'nat'>}
+ */
+
+// make a Ratio, which represents a fraction. It is a pass-by-copy record.
+//
+// The natural syntax for the most common operations we want to support
+// are Amount * Ratio and Amount / Ratio. Since the operations want to adhere to
+// the ratio rather than the amount, we settled on a calling convention of
+// [ceil|floor]MultiplyBy(Amount, Ratio) and [ceil|floor]DivideBy(Amount, Ratio)
+//
+// The most common kind of Ratio can be applied to Amounts of a particular
+// brand, and produces results of the same brand. This represents a multiplier
+// that is only applicable to that brand. The less common kind of Ratio can be
+// applied to one particular brand of amounts, and produces results of another
+// particular brand. This represents some kind of exchange rate. The
+// brand-checking helps us ensure that normal Ratios aren't applied to amounts
+// of the wrong brand, and that exchange rates are only used in the appropriate
+// direction.
+//
+// Since the ratios are represented by a numerator and a denominator, every
+// multiplication or division operation that produces an amount ends with a
+// division of the underlying bigints, and integer division requires a mode
+// of [rounding to integer](https://en.wikipedia.org/wiki/Rounding#Rounding_to_integer).
+// Because `Ratio` only work with Natural numbers, just three modes suffice:
+//   - floor rounds down
+//   - ceil rounds up
+//   - default (without prefix) minimizes bias by rounding half to even
+
+const PERCENT = 100n;
+
+const ratioPropertyNames = ['numerator', 'denominator'];
+
+export const assertIsRatio = ratio => {
+  assertRecord(ratio, 'ratio');
+  const keys = Object.keys(ratio);
+  keys.length === 2 || Fail`Ratio ${ratio} must be a record with 2 fields.`;
+  for (const name of keys) {
+    ratioPropertyNames.includes(name) ||
+      Fail`Parameter must be a Ratio record, but ${ratio} has ${q(name)}`;
+  }
+  const numeratorValue = ratio.numerator.value;
+  const denominatorValue = ratio.denominator.value;
+  isNat(numeratorValue) ||
+    Fail`The numerator value must be a NatValue, not ${numeratorValue}`;
+  isNat(denominatorValue) ||
+    Fail`The denominator value must be a NatValue, not ${denominatorValue}`;
+};
+
+/**
+ * @param {bigint} numerator
+ * @param {Brand} numeratorBrand
+ * @param {bigint} [denominator] The default denominator is 100
+ * @param {Brand} [denominatorBrand] The default is to reuse the numeratorBrand
+ * @returns {Ratio}
+ */
+export const makeRatio = (
+  numerator,
+  numeratorBrand,
+  denominator = PERCENT,
+  denominatorBrand = numeratorBrand,
+) => {
+  denominator > 0n ||
+    Fail`No infinite ratios! Denominator was 0 ${q(denominatorBrand)}`;
+
+  return harden({
+    numerator: AmountMath.make(numeratorBrand, numerator),
+    denominator: AmountMath.make(denominatorBrand, denominator),
+  });
+};
+
+/**
+ * @param {Amount} numeratorAmount
+ * @param {Amount} denominatorAmount
+ * @returns {Ratio}
+ */
+export const makeRatioFromAmounts = (numeratorAmount, denominatorAmount) => {
+  AmountMath.coerce(numeratorAmount.brand, numeratorAmount);
+  AmountMath.coerce(denominatorAmount.brand, denominatorAmount);
+  return makeRatio(
+    // @ts-expect-error value can be any AmountValue but makeRatio() supports only bigint
+    numeratorAmount.value,
+    numeratorAmount.brand,
+    denominatorAmount.value,
+    denominatorAmount.brand,
+  );
+};
+
+/**
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @param {any} divideOp
+ * @returns {Amount<'nat'>}
+ */
+const multiplyHelper = (amount, ratio, divideOp) => {
+  AmountMath.coerce(amount.brand, amount);
+  assertIsRatio(ratio);
+  amount.brand === ratio.denominator.brand ||
+    Fail`amount's brand ${q(amount.brand)} must match ratio's denominator ${q(
+      ratio.denominator.brand,
+    )}`;
+
+  return /** @type {Amount<'nat'>} */ (
+    AmountMath.make(
+      ratio.numerator.brand,
+      divideOp(
+        multiply(amount.value, ratio.numerator.value),
+        ratio.denominator.value,
+      ),
+    )
+  );
+};
+
+/** @type {ScaleAmount} */
+export const floorMultiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, floorDivide);
+};
+
+/** @type {ScaleAmount} */
+export const ceilMultiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, ceilDivide);
+};
+
+/** @type {ScaleAmount} */
+export const multiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, bankersDivide);
+};
+
+/**
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @param {any} divideOp
+ * @returns {Amount<'nat'>}
+ */
+const divideHelper = (amount, ratio, divideOp) => {
+  AmountMath.coerce(amount.brand, amount);
+  assertIsRatio(ratio);
+  amount.brand === ratio.numerator.brand ||
+    Fail`amount's brand ${q(amount.brand)} must match ratio's numerator ${q(
+      ratio.numerator.brand,
+    )}`;
+
+  return /** @type {Amount<'nat'>} */ (
+    AmountMath.make(
+      ratio.denominator.brand,
+      divideOp(
+        multiply(amount.value, ratio.denominator.value),
+        ratio.numerator.value,
+      ),
+    )
+  );
+};
+
+/**
+ * Divide the amount by the ratio, truncating the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const floorDivideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, floorDivide);
+};
+
+/**
+ * Divide the amount by the ratio, rounding up the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const ceilDivideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, ceilDivide);
+};
+
+/**
+ * Divide the amount by the ratio, rounding to nearest with ties to even (aka
+ * Banker's Rounding) as in IEEE 754 default rounding.
+ *
+ * @type {ScaleAmount}
+ */
+export const divideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, bankersDivide);
+};
+
+/**
+ * @param {Ratio} ratio
+ * @returns {Ratio}
+ */
+export const invertRatio = ratio => {
+  assertIsRatio(ratio);
+
+  return makeRatio(
+    ratio.denominator.value,
+    ratio.denominator.brand,
+    ratio.numerator.value,
+    ratio.numerator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const addRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+  left.numerator.brand === right.numerator.brand ||
+    Fail`numerator brands must match: ${q(left)} ${q(right)}`;
+  left.denominator.brand === right.denominator.brand ||
+    Fail`denominator brands must match: ${q(left)} ${q(right)}`;
+
+  // Simplifying the expression:
+  //  (and + bnd) / y d**2
+  //  (a + b) nd / y d**2
+  //  ((a + b) n / y d) * (d / d)
+  //  (a + b) n / yd
+  return makeRatio(
+    add(
+      multiply(left.numerator.value, right.denominator.value), // a nd
+      multiply(left.denominator.value, right.numerator.value), // b nd
+    ), // (a + b) nd
+    left.numerator.brand,
+    multiply(left.denominator.value, right.denominator.value), // y d**2
+    left.denominator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const subtractRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+  left.numerator.brand === right.numerator.brand ||
+    Fail`numerator brands must match: ${q(left)} ${q(right)}`;
+  left.denominator.brand === right.denominator.brand ||
+    Fail`denominator brands must match: ${q(left)} ${q(right)}`;
+
+  return makeRatio(
+    subtract(
+      multiply(left.numerator.value, right.denominator.value), // a nd
+      multiply(left.denominator.value, right.numerator.value), // b nd
+    ), // (a - b) nd
+    left.numerator.brand,
+    multiply(left.denominator.value, right.denominator.value), // y d**2
+    left.denominator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const multiplyRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+
+  const getRemainingBrands = () => {
+    // Prefer results that have the same brand as the left operand.
+    if (right.numerator.brand === right.denominator.brand) {
+      return [left.numerator.brand, left.denominator.brand];
+    }
+    if (right.numerator.brand === left.denominator.brand) {
+      return [left.numerator.brand, right.denominator.brand];
+    }
+    if (left.numerator.brand === right.denominator.brand) {
+      return [right.numerator.brand, left.denominator.brand];
+    }
+    if (left.numerator.brand === left.denominator.brand) {
+      return [right.numerator.brand, right.denominator.brand];
+    }
+    throw Fail`at least one brand must cancel out: ${q(left)} ${q(right)}`;
+  };
+
+  const [numeratorBrand, denominatorBrand] = getRemainingBrands();
+  return makeRatio(
+    multiply(left.numerator.value, right.numerator.value),
+    numeratorBrand,
+    multiply(left.denominator.value, right.denominator.value),
+    denominatorBrand,
+  );
+};
+
+/**
+ * If ratio is between 0 and 1, subtract from 1.
+ *
+ * @param {Ratio} ratio
+ * @returns {Ratio}
+ */
+export const oneMinus = ratio => {
+  assertIsRatio(ratio);
+  ratio.numerator.brand === ratio.denominator.brand ||
+    Fail`oneMinus only supports ratios with a single brand, but ${ratio.numerator.brand} doesn't match ${ratio.denominator.brand}`;
+  ratio.numerator.value <= ratio.denominator.value ||
+    Fail`Parameter must be less than or equal to 1: ${ratio.numerator.value}/${ratio.denominator.value}`;
+  return makeRatio(
+    subtract(ratio.denominator.value, ratio.numerator.value),
+    ratio.numerator.brand,
+    ratio.denominator.value,
+    ratio.numerator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {boolean}
+ */
+export const ratioGTE = (left, right) => {
+  if (left.numerator.brand === right.numerator.brand) {
+    left.denominator.brand === right.denominator.brand ||
+      Fail`numerator brands match, but denominator brands don't: ${q(left)} ${q(
+        right,
+      )}`;
+  } else if (left.numerator.brand === left.denominator.brand) {
+    right.numerator.brand === right.denominator.brand ||
+      Fail`lefthand brands match, but righthand brands don't: ${q(left)} ${q(
+        right,
+      )}`;
+  }
+  return natSafeMath.isGTE(
+    multiply(left.numerator.value, right.denominator.value),
+    multiply(right.numerator.value, left.denominator.value),
+  );
+};
+
+/**
+ * True iff the ratios are the same values (equal or equivalant may return
+ * false)
+ *
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {boolean}
+ */
+export const ratiosSame = (left, right) => {
+  return (
+    AmountMath.isEqual(left.numerator, right.numerator) &&
+    AmountMath.isEqual(left.denominator, right.denominator)
+  );
+};
+
+/**
+ * Make a new ratio with a smaller denominator that approximates the ratio. If
+ * the proposed denominator is larger than the current one, return the
+ * original.
+ *
+ * @param {Ratio} ratio
+ * @param {bigint} newDen
+ * @returns {Ratio}
+ */
+export const quantize = (ratio, newDen) => {
+  const oldDen = ratio.denominator.value;
+  const oldNum = ratio.numerator.value;
+  if (newDen > oldDen) {
+    return ratio;
+  }
+
+  const newNum =
+    newDen === oldDen ? oldNum : bankersDivide(oldNum * newDen, oldDen);
+  return makeRatio(
+    newNum,
+    ratio.numerator.brand,
+    newDen,
+    ratio.denominator.brand,
+  );
+};
+
+const NUMERIC_RE = /^(\d\d*)(?:\.(\d*))?$/;
+/** @typedef {bigint | number | string} ParsableNumber */
+
+/**
+ * Create a ratio from a given numeric value.
+ *
+ * @param {ParsableNumber} numeric
+ * @param {Brand<'nat'>} numeratorBrand
+ * @param {Brand<'nat'>} [denominatorBrand]
+ * @returns {Ratio}
+ */
+export const parseRatio = (
+  numeric,
+  numeratorBrand,
+  denominatorBrand = numeratorBrand,
+) => {
+  const match = `${numeric}`.match(NUMERIC_RE);
+  if (!match) {
+    throw Fail`Invalid numeric data: ${numeric}`;
+  }
+
+  const [_, whole, part = ''] = match;
+  return makeRatio(
+    BigInt(`${whole}${part}`),
+    numeratorBrand,
+    10n ** BigInt(part.length),
+    denominatorBrand,
+  );
+};
+
+/**
+ * @param {unknown} specimen
+ * @returns {asserts specimen is ParsableNumber}
+ */
+export const assertParsableNumber = specimen => {
+  const match = `${specimen}`.match(NUMERIC_RE);
+  match || Fail`Invalid numeric data: ${specimen}`;
+};
+
+/**
+ * Ratios might be greater or less than one.
+ *
+ * @param {Ratio} ratio
+ * @returns {number}
+ */
+export const ratioToNumber = ratio => {
+  const n = Number(ratio.numerator.value);
+  const d = Number(ratio.denominator.value);
+  return n / d;
+};

package/src/safeMath.d.ts

@@ -0,0 +1,11 @@
+export namespace natSafeMath {
+    let add: NatOp;
+    let subtract: NatOp;
+    let multiply: NatOp;
+    let floorDivide: NatOp;
+    let ceilDivide: NatOp;
+    let bankersDivide: NatOp;
+    let isGTE: (x: number | bigint, y: number | bigint) => boolean;
+}
+export type NatOp = (x: number | bigint, y: number | bigint) => bigint;
+//# sourceMappingURL=safeMath.d.ts.map

package/src/safeMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeMath.d.ts","sourceRoot":"","sources":["safeMath.js"],"names":[],"mappings":";aAYa,KAAK;kBAGL,KAAK;kBAEL,KAAK;qBAEL,KAAK;oBAEL,KAAK;uBASN,KAAK;eAiBJ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO;;oBA7ClD,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM"}