@onrail-xyz/amount 1.0.0

package/src/aggregating.ts

@@ -0,0 +1,160 @@
+import type { RoArray, RoTuple, HeadTail } from "@onrail-xyz/utils";
+import { type Rationalish, Rational } from "./rational.js";
+import type { Kind } from "./kind.js";
+import { type Amount, isAmount } from "./amount.js";
+import { type Rate, _Rate, isRate } from "./rate.js";
+
+//An aggregate of amounts is an amount of the kind every operand has, or a kind mismatch at
+//  runtime; the intersection says so exactly. Two distinct kinds intersect to never (their names
+//  are disjoint literals), and an Amount of never is never: the type of a call that cannot return.
+//only a fixed tuple's positions witness a kind: a plain array may be empty at runtime, which
+//  returns the first operand unchanged, so it narrows nothing (nor, conservatively, does an
+//  open-ended tuple)
+//the tuple test is against the bare RoTuple: an element constraint in the extends type would
+//  leave `[K] extends RoTuple<Kind>` undecided at an open K, since tsc settles a definitely-true
+//  check with K's own constraint stripped, and the fold below would stay deferred
+export type CommonKind<Ks extends RoArray<Kind>> =
+  Ks extends RoTuple
+  ? Ks extends HeadTail<Ks, infer H, infer T>
+    ? H & CommonKind<T>
+    : unknown
+  : unknown;
+
+//kinds are inferred through the mapped tuple, so the result is exact even at an open K, where
+//  a kind extracted from an Amount<K> would stay a deferred conditional
+type AmountsOf<Ks extends RoArray<Kind>> = { readonly [I in keyof Ks]: Amount<Ks[I]> };
+
+//Rates carry two kinds and a pair tuple does not infer, so their kinds are read back from the
+//  inferred rate tuple, one side at a time; assignable to Rate<NK, DK> at an open kind, exact at
+//  a concrete one
+type SideOf<R, S extends 0 | 1> = R extends _Rate<infer NK, infer DK> ? [NK, DK][S] : never;
+type SidesOf<Rs extends RoArray, S extends 0 | 1> = { readonly [I in keyof Rs]: SideOf<Rs[I], S> };
+
+type CommonRate<NK extends Kind, DK extends Kind, Rs extends RoArray> =
+  Rate<NK & CommonKind<SidesOf<Rs, 0>>, DK & CommonKind<SidesOf<Rs, 1>>>;
+
+export function min<K extends Kind, Ks extends RoArray<Kind>>(
+  first:   Amount<K>,
+  ...rest: AmountsOf<Ks>
+): Amount<K & CommonKind<Ks>>;
+export function min<NK extends Kind, DK extends Kind, Rs extends RoArray<Rate<Kind, Kind>>>(
+  first:   Rate<NK, DK>,
+  ...rest: Rs
+): CommonRate<NK, DK, Rs>;
+export function min(
+  first:   Rationalish,
+  ...rest: RoArray<Rationalish>
+): Rational;
+export function min(
+  first:   Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  ...rest: RoArray<Amount<Kind> | Rate<Kind, Kind> | Rationalish>
+): Amount<Kind> | Rate<Kind, Kind> | Rational {
+  if (isAmount(first) || isRate(first))
+    return rest.reduce((acc, value) => (acc as any).le(value) ? acc : value, first) as any;
+
+  return (rest as RoArray<Rationalish>).reduce<Rational>(
+    (acc, value) => acc.le(value) ? acc : Rational.from(value), Rational.from(first));
+}
+
+export function max<K extends Kind, Ks extends RoArray<Kind>>(
+  first:   Amount<K>,
+  ...rest: AmountsOf<Ks>
+): Amount<K & CommonKind<Ks>>;
+export function max<NK extends Kind, DK extends Kind, Rs extends RoArray<Rate<Kind, Kind>>>(
+  first:   Rate<NK, DK>,
+  ...rest: Rs
+): CommonRate<NK, DK, Rs>;
+export function max(
+  first:   Rationalish,
+  ...rest: RoArray<Rationalish>
+): Rational;
+export function max(
+  first:   Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  ...rest: RoArray<Amount<Kind> | Rate<Kind, Kind> | Rationalish>
+): Amount<Kind> | Rate<Kind, Kind> | Rational {
+  if (isAmount(first) || isRate(first))
+    return rest.reduce((acc, value) => (acc as any).ge(value) ? acc : value, first) as any;
+
+  return (rest as RoArray<Rationalish>).reduce<Rational>(
+    (acc, value) => acc.ge(value) ? acc : Rational.from(value), Rational.from(first));
+}
+
+export function sum<K extends Kind, Ks extends RoArray<Kind>>(
+  first:   Amount<K>,
+  ...rest: AmountsOf<Ks>
+): Amount<K & CommonKind<Ks>>;
+export function sum<NK extends Kind, DK extends Kind, Rs extends RoArray<Rate<Kind, Kind>>>(
+  first:   Rate<NK, DK>,
+  ...rest: Rs
+): CommonRate<NK, DK, Rs>;
+export function sum(
+  first:   Rationalish,
+  ...rest: RoArray<Rationalish>
+): Rational;
+export function sum(
+  first:   Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  ...rest: RoArray<Amount<Kind> | Rate<Kind, Kind> | Rationalish>
+): Amount<Kind> | Rate<Kind, Kind> | Rational {
+  if (typeof first === "number" || typeof first === "bigint")
+    first = Rational.from(first);
+
+  return rest.reduce((acc, value) => (acc as any).add(value), first) as any;
+}
+
+//three-way comparison, usable directly as an Array.prototype.sort comparator. Its result
+//  carries no kind, so nothing can express "the kind both share": the first operand's set of
+//  kinds is authoritative and the second must fall within it
+export function compare<K extends Kind>(
+  a: Amount<K>,
+  b: NoInfer<Amount<K>>,
+): -1 | 0 | 1;
+export function compare<NK extends Kind, DK extends Kind>(
+  a: Rate<NK, DK>,
+  b: NoInfer<Rate<NK, DK>>,
+): -1 | 0 | 1;
+export function compare(
+  a: Rationalish,
+  b: Rationalish,
+): -1 | 0 | 1;
+export function compare(
+  a: Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  b: Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+): -1 | 0 | 1 {
+  if (typeof a === "number" || typeof a === "bigint")
+    a = Rational.from(a);
+
+  if (a instanceof Rational)
+    return a.cmp(b as Rationalish);
+
+  //no subtraction: a sort calls this n·log n times, and an amount's or rate's own gt/lt check
+  //  the kinds
+  const ordered = a as { gt(other: unknown): boolean, lt(other: unknown): boolean };
+  return ordered.gt(b) ? 1 : ordered.lt(b) ? -1 : 0;
+}
+
+export function clamp<K extends Kind, KL extends Kind, KH extends Kind>(
+  x:  Amount<K>,
+  lo: Amount<KL>,
+  hi: Amount<KH>,
+): Amount<K & KL & KH>;
+export function clamp<
+  NK extends Kind, DK extends Kind,
+  NL extends Kind, DL extends Kind,
+  NH extends Kind, DH extends Kind,
+>(
+  x:  Rate<NK, DK>,
+  lo: Rate<NL, DL>,
+  hi: Rate<NH, DH>,
+): Rate<NK & NL & NH, DK & DL & DH>;
+export function clamp(
+  x:  Rationalish,
+  lo: Rationalish,
+  hi: Rationalish,
+): Rational;
+export function clamp(
+  x:  Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  lo: Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+  hi: Amount<Kind> | Rate<Kind, Kind> | Rationalish,
+): Amount<Kind> | Rate<Kind, Kind> | Rational {
+  return min(max(x as any, lo as any), hi as any);
+}

package/src/allocating.ts

@@ -0,0 +1,70 @@
+import type { OfLength, RoArray, RoNeTuple } from "@onrail-xyz/utils";
+import { isArray } from "@onrail-xyz/utils";
+import type { Rationalish } from "./rational.js";
+import { Rational } from "./rational.js";
+import type { Kind, KindWithAtomic, SymbolsOf } from "./kind.js";
+import type { Amount } from "./amount.js";
+
+//a literal count or weights tuple yields a length-typed tuple; a runtime length degrades to a
+//  plain array
+type Allocation<K extends Kind, P extends number | RoArray<Rationalish>> =
+  P extends RoArray<Rationalish>
+  ? OfLength<Amount<K>, P["length"]>
+  : OfLength<Amount<K>, P & number>;
+
+//Parts are pro-rata by weight (any sign, nonzero total), or equal when a count is given;
+//  each part is a whole number of the given unit (atomic by default) and the parts sum exactly
+//  to the amount, leftover units going to the largest fractional shares (earlier index breaks
+//  ties). The amount must itself be whole in that unit: allocation never rounds the total, so
+//  quantization — and the dust decision that comes with it — stays with the caller.
+export function allocate<
+        K extends KindWithAtomic,
+  const P extends number | RoNeTuple<Rationalish>,
+>(amount: Amount<K>, parts: P): Allocation<K, P>;
+export function allocate<
+        K extends Kind,
+  const P extends number | RoNeTuple<Rationalish>,
+>(amount: Amount<K>, parts: P, unitSymbol: SymbolsOf<K>): Allocation<K, P>;
+export function allocate(
+  amount:     Amount<Kind>,
+  parts:      number | RoArray<Rationalish>,
+  unitSymbol: SymbolsOf<Kind> = "atomic",
+): RoArray<Amount<Kind>> {
+  if (!amount.eq(amount.floorTo(unitSymbol)))
+    throw new Error(
+      `Amount is not a whole number of ${unitSymbol} units - quantize it first ` +
+      `(floorTo/roundTo/ceilTo)`
+    );
+
+  if (isArray(parts) ? parts.length === 0 : !(Number.isSafeInteger(parts) && parts > 0))
+    throw new Error("parts must be a nonempty weights list or a positive integer count");
+
+  const weights = isArray(parts)
+    ? parts.map(w => Rational.from(w))
+    : Array.from({ length: parts }, () => Rational.from(1n));
+  const totalWeight = weights.reduce((acc, w) => acc.add(w), Rational.from(0n));
+  if (totalWeight.eq(0n))
+    throw new Error("weights must not sum to zero");
+
+  const inUnit: Rational | bigint = amount.in(unitSymbol);
+  const total = typeof inUnit === "bigint" ? inUnit : inUnit.floor(); //integral, so floor is exact
+
+  const shares = weights.map(w => Rational.from(total).mul(w).div(totalWeight));
+  const floors = shares.map(s => s.floor());
+  let leftover = total - floors.reduce((acc, f) => acc + f, 0n);
+
+  const byFraction = shares
+    .map((s, i) => [s.sub(floors[i]!), i] as const)
+    .sort((a, b) => a[0].eq(b[0]) ? a[1] - b[1] : a[0].gt(b[0]) ? -1 : 1);
+
+  const bumped = new Set<number>();
+  for (const [, i] of byFraction) {
+    if (leftover === 0n)
+      break;
+
+    bumped.add(i);
+    --leftover;
+  }
+
+  return floors.map((f, i) => amount.ofSame(bumped.has(i) ? f + 1n : f, unitSymbol));
+}

package/src/amount.ts

@@ -0,0 +1,291 @@
+import type { Brand, NarrowTo, Opts, RoArray } from "@onrail-xyz/utils";
+import { brand } from "@onrail-xyz/utils";
+import type { Rationalish, ToFixedOptions } from "./rational.js";
+import { Rational } from "./rational.js";
+import type { Kind, KindWithHuman, SymbolsOf,
+              DecimalSymbolsOf, KindUnitSymbols, CandidateKinds } from "./kind.js";
+import { getUnit, identifyKind, sameKind } from "./kind.js";
+import { Rate, isRate } from "./rate.js";
+import { approximate, exact, inUnit, parse as parseFormat } from "./format.js";
+
+export type AmountFromArgs<K extends Kind> = [kind: K, unitSymbol: SymbolsOf<K>];
+
+export const scalar = brand<"scalar">();
+
+//Free functions, not statics: a static is entered with a kind in hand (ofKind, from, parse, the
+//  *OfKind guards) and produces or narrows towards an amount of it; these are entered with an
+//  amount - or with nothing at all - and recover what the receiver's erased K cannot give back
+//  (Amount.md, "Free functions get fresh generic parameters"). rate.ts follows the same split.
+//exact kind reads at an open K, where the `kind` property erases
+export const kindOf = <K extends Kind>(amount: Amount<K>): K => amount.kind as K;
+
+//class check without touching the underscored class:
+//  a union narrows to exactly its amount constituents
+//  an open Amount<K> keeps its K
+//  an unknown narrows to Amount<Kind>
+export const isAmount = <T>(value: T): value is NarrowTo<T, Amount<Kind>> =>
+  value instanceof _Amount;
+
+//see end of file for the actual exports
+//two Amount spellings:
+//  * _Amount<K> is the implementation class that's only exported for type-reachability
+//  * Amount<K> (see end of file) is the  distributive alias over it. It's the only spelling that
+//      should be used by consumers
+//
+//Kind-preserving members return this so things match as intended, even when deferred at an open K
+export class _Amount<K extends Kind> {
+  private readonly value: Rational;
+  readonly kind: K;
+
+  private constructor(value: Rational, kind: K) {
+    this.value = value;
+    this.kind = kind;
+  }
+
+  static ofKind<const K extends KindWithHuman>(kind: K):
+    (numericalValue: Rationalish | string, unitSymbol?: SymbolsOf<K>) => Amount<K>;
+  static ofKind<const K extends Kind>(kind: K):
+    (numericalValue: Rationalish | string, unitSymbol: SymbolsOf<K>) => Amount<K>;
+  static ofKind(kind: Kind) {
+    return (numericalValue: Rationalish | string, unitSymbol?: string) =>
+      _Amount.fromInternal(numericalValue, kind, unitSymbol ?? kind.human) as Amount<Kind>;
+  }
+
+  static from<const K extends KindWithHuman>(
+    numericalValue: Rationalish | string,
+    ...args:        [kind: K, unitSymbol?: SymbolsOf<K>]
+  ): Amount<K>;
+  static from<const K extends Kind>(
+    numericalValue: Rationalish | string,
+    ...args:        AmountFromArgs<K>
+  ): Amount<K>;
+  static from<const K extends Kind>(
+    numericalValue: Rationalish | string,
+    ...args:        [kind: K, unitSymbol?: SymbolsOf<K>]
+  ): Amount<K> {
+    return _Amount.fromInternal(numericalValue, args[0], args[1]) as Amount<K>;
+  }
+
+  //the candidates are inferred as a tuple, not as one K: a single type param would bind to the
+  //  first kind and reject every other, which is the whole point of passing several
+  static parse<const KS extends RoArray<Kind>>(str: string, ...kinds: KS): Amount<KS[number]> {
+    const kind = identifyKind(kinds, str);
+    if (!kind)
+      throw new Error("Could not identify kind from string");
+
+    const value = parseFormat(kind, str);
+    return _Amount.fromInternal(value, kind, kind.standard.unit) as Amount<KS[number]>;
+  }
+
+  static isOfKind<
+    A extends Amount<Kind>,
+    K extends CandidateKinds<A["kind"]>,
+  >(amt: A, kind: K): amt is NarrowTo<A, Amount<K>> {
+    return sameKind(amt.kind, kind);
+  }
+
+  static allOfKind<
+    A extends Amount<Kind>,
+    K extends CandidateKinds<A["kind"]>,
+  >(amts: RoArray<A>, kind: K): amts is RoArray<NarrowTo<A, Amount<K>>> {
+    return amts.every(amt => sameKind(amt.kind, kind));
+  }
+
+  //instance factories — "an amount of my own kind". The kind-generic replacement for reading
+  //  `kind` back and feeding it to ofKind: `kind` erases at an open K, `this` does not.
+  zero(): this {
+    return new _Amount(Rational.from(0n), this.kind) as this;
+  }
+
+  ofSame<S extends SymbolsOf<K>>(numericalValue: Rationalish | string, unitSymbol: S): this {
+    return _Amount.fromInternal(numericalValue, this.kind, unitSymbol) as this;
+  }
+
+  toString(): string;
+  toString(
+    system: Extract<keyof K["systems"], string>,
+    opts?:  Opts<ToFixedOptions>,
+  ): string;
+  toString(
+    mode:  "approximate" | "exact",
+    opts?: Opts<ToFixedOptions & { system: Extract<keyof K["systems"], string> }>,
+  ): string;
+  toString<S extends SymbolsOf<K>>(
+    mode:   "inUnit",
+    symbol: S,
+    opts?:  Opts<ToFixedOptions & {
+      precision: number | (S extends DecimalSymbolsOf<K> ? DecimalSymbolsOf<K> : never);
+    }>,
+  ): string;
+  toString(
+    modeOrSys?:    string,
+    symbolOrOpts?: SymbolsOf<K> | Opts<ToFixedOptions & { system?: string }>,
+    opts?:         Opts<ToFixedOptions & { precision?: number | DecimalSymbolsOf<K> }>,
+  ): string {
+    if (modeOrSys === "inUnit") {
+      const symbol = getUnit(this.kind, symbolOrOpts as SymbolsOf<K>).symbol as KindUnitSymbols<K>;
+      const prec = typeof opts?.precision === "string"
+        ? getUnit(this.kind, opts.precision as SymbolsOf<K>).symbol as KindUnitSymbols<K>
+        : opts?.precision;
+
+      return inUnit(this.kind, this.value, symbol, prec, opts);
+    }
+
+    const isMode = !modeOrSys || modeOrSys === "approximate" || modeOrSys === "exact";
+    const o = (
+      isMode ? symbolOrOpts : { system: modeOrSys, ...(symbolOrOpts as object) }
+    ) as Opts<ToFixedOptions & { system?: string }> | undefined;
+
+    return modeOrSys === "exact"
+      ? exact      (this.kind, this.value, o)
+      : approximate(this.kind, this.value, o);
+  }
+
+  toJSON(): string {
+    return this.toString("exact");
+  }
+
+  in<S extends SymbolsOf<K>>(unitSymbol: S): S extends "atomic" ? bigint : Rational;
+  in(unitSymbol: K extends { human: string } ? "human" : never): Rational;
+  in(unitSymbol: K extends { atomic: string } ? "atomic" : never): bigint;
+  in<S extends SymbolsOf<K>>(unitSymbol: S): S extends "atomic" ? bigint : Rational {
+    const rat = this.getIn(unitSymbol);
+    return (unitSymbol === "atomic" ? rat.floor() : rat) as S extends "atomic" ? bigint : Rational;
+  }
+
+  //the S on the unit-symbol methods might seem pointless, but it's in fact crucial:
+  //  a bare SymbolsOf<K> breaks overload/implementation compatibility of the this-returning methods
+  //  (the compatibility check relates _Amount<K> to _Amount<Kind>, where only same-shape generic
+  //  signatures unify across the deferred SymbolsOf<K> / string constraint divide)
+  ceilTo<S extends SymbolsOf<K>>(unitSymbol: S): this {
+    return _Amount.fromInternal(this.getIn(unitSymbol).ceil(), this.kind, unitSymbol) as this;
+  }
+
+  roundTo<S extends SymbolsOf<K>>(unitSymbol: S): this {
+    return _Amount.fromInternal(this.getIn(unitSymbol).round(), this.kind, unitSymbol) as this;
+  }
+
+  floorTo<S extends SymbolsOf<K>>(unitSymbol: S): this {
+    return _Amount.fromInternal(this.getIn(unitSymbol).floor(), this.kind, unitSymbol) as this;
+  }
+
+  isZero(): boolean {
+    return this.value.eq(0n);
+  }
+
+  sign(): -1 | 0 | 1 {
+    return this.value.sign();
+  }
+
+  eq(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.eq(other.value);
+  }
+
+  ne(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.ne(other.value);
+  }
+
+  lt(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.lt(other.value);
+  }
+
+  le(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.le(other.value);
+  }
+
+  gt(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.gt(other.value);
+  }
+
+  ge(other: this): boolean {
+    this.checkKind(other.kind);
+    return this.value.ge(other.value);
+  }
+
+  abs(): this {
+    return new _Amount(this.value.abs(), this.kind) as this;
+  }
+
+  neg(): this {
+    return new _Amount(this.value.neg(), this.kind) as this;
+  }
+
+  add(other: this): this {
+    this.checkKind(other.kind);
+    return new _Amount(this.value.add(other.value), this.kind) as this;
+  }
+
+  sub(other: this): this {
+    this.checkKind(other.kind);
+    return new _Amount(this.value.sub(other.value), this.kind) as this;
+  }
+
+  mul(other: Rationalish | Amount<Brand<Kind, "scalar">>): this;
+  mul<NK extends Kind>(other: Rate<NK, K>): Amount<NK>;
+  mul(other: Rationalish | Amount<Brand<Kind, "scalar">> | Rate<Kind, K>): Amount<Kind> {
+    if (isRate(other)) {
+      this.checkKind(other.den);
+      return new _Amount(this.value.mul(other.ratio), other.num) as Amount<Kind>;
+    }
+    const rhs = isAmount(other) ? other.value : other;
+    return new _Amount(this.value.mul(rhs), this.kind) as Amount<Kind>;
+  }
+
+  div(other: Rationalish | Amount<Brand<Kind, "scalar">>): this;
+  div<DK extends Kind>(other: Rate<K, DK>): Amount<DK>;
+  div(other: Rationalish | Amount<Brand<Kind, "scalar">> | Rate<K, Kind>): Amount<Kind> {
+    if (isRate(other)) {
+      this.checkKind(other.num);
+      return new _Amount(this.value.div(other.ratio), other.den) as Amount<Kind>;
+    }
+    const rhs = isAmount(other) ? other.value : other;
+    return new _Amount(this.value.div(rhs), this.kind) as Amount<Kind>;
+  }
+
+  //the quotient of two amounts of one kind, which is a plain number. It is not a `div` overload
+  //  because an open K may be instantiated as a union (a tranche kind known only at runtime):
+  //  at K1 | K2 an overload for `this` accepts an operand of the other kind - a scalar one
+  //  included, which `div` scales by - and no runtime check can tell which of the two readings
+  //  the types chose. `div` takes scalars only, and this checks the kind like add and sub do
+  ratio(other: this): Rational {
+    this.checkKind(other.kind);
+    return this.value.div(other.value);
+  }
+
+  mod(other: this): this {
+    this.checkKind(other.kind);
+    return new _Amount(this.value.mod(other.value), this.kind) as this;
+  }
+
+  per<const DK extends Kind>(den: KindWithHuman & DK | Amount<DK>): Rate<K, DK> {
+    return Rate.from(this as any, den as any);
+  }
+
+  private static fromInternal<const K extends Kind>(
+    numericalValue: Rationalish | string,
+    kind:           K,
+    unitSymbol?:    string,
+  ): _Amount<K> {
+    const unit = getUnit(kind, (unitSymbol ?? "human") as SymbolsOf<K>);
+    return new _Amount(Rational.from(numericalValue).mul(unit.scale), kind);
+  }
+
+  private getIn(unitSymbol: SymbolsOf<K>): Rational {
+    return this.value.div(getUnit(this.kind, unitSymbol).scale);
+  }
+
+  private checkKind(otherKind: Kind): void {
+    if (!sameKind(this.kind, otherKind))
+      throw new Error(`Kind mismatch: ${this.kind.name} vs ${otherKind.name}`);
+  }
+}
+
+//always distribute because _Amount<KindUnion> is useless
+type Amount<K extends Kind> = K extends Kind ? _Amount<K> : never;
+const Amount = _Amount;
+export { Amount };