@storepass/money 0.2.1 → 0.3.1

package/README.md

@@ -60,6 +60,11 @@ const diff = a.subtract(b); // 7.5
 
 Money.compare(a, b); // 1
 Money.greaterThan(a, b); // true
+
+Money.zero(Currency.USD); // $0.00
+Money.sum([], Currency.USD); // $0.00; without a currency, an empty list throws
+Money.sum([a, b], Currency.USD); // 12.5; every item must be USD
+Money.sameCurrency([a, b], Currency.USD); // true; never throws
 ```
 
 ### Allocation
@@ -92,6 +97,26 @@ subtotal.incrementByPercent(8.25).toNumber(); // 108.25
 subtotal.decrementByPercent(10).toNumber(); // 90
 ```
 
+### Ratio scaling
+
+`scaleByRatio` multiplies by `numerator ÷ denominator` exactly on BigInt minor
+units and rounds once. Use it instead of turning a ratio into a float percent.
+The ratio's two values must share a currency with each other, but not with the
+value being scaled.
+
+```ts
+const value = Money.fromMinor(Currency.USD, 123456789);
+const one = Money.fromMinor(Currency.EUR, 1);
+const six = Money.fromMinor(Currency.EUR, 6);
+
+value.scaleByRatio(one, six); // 20576132 minor units (exact 20576131.5, rounded once)
+value.scaleByRatio(one, six, { rounding: "floor" }); // 20576131
+Money.scaleByRatio(value, one, six); // static form
+```
+
+It throws on a zero denominator, when the ratio's currencies differ, and when
+the result exceeds the safe integer range.
+
 ### Custom currencies
 
 ```ts
@@ -101,6 +126,18 @@ const XAU = defineCurrency("XAU", 4);
 const gold = Money.fromNumber(XAU, 1.2345);
 ```
 
+`resolveCurrency` looks a definition up by code. A built-in code returns the
+same object as `Currency[code]`; an unknown code returns `undefined`, or, with
+`fallbackDecimalPlaces`, a cached `defineCurrency(code, fallbackDecimalPlaces)`.
+
+```ts
+import { resolveCurrency } from "@storepass/money";
+
+resolveCurrency("USD"); // Currency.USD
+resolveCurrency("XYZ"); // undefined
+resolveCurrency("XYZ", { fallbackDecimalPlaces: 2 }); // same object on every call
+```
+
 ### Serialization
 
 ```ts
@@ -192,7 +229,11 @@ and update both `decimalPlaces` and `numericCode` for any drift.
 
 - Currency mismatch operations throw (for example, adding USD to EUR).
 - Results that exceed JavaScript safe integer range throw.
-- Rounding modes supported: `"floor" | "ceil" | "round" | "trunc"`.
+- Rounding modes supported: `"floor" | "ceil" | "round" | "trunc"`. `"floor"`
+  goes toward -Infinity, `"ceil"` toward +Infinity, and `"trunc"` toward zero.
+  `"round"` (the default) goes to the nearest minor unit and resolves an exact
+  half toward +Infinity: 2.5 becomes 3 and -2.5 becomes -2. It is not half away
+  from zero.
 - `Money` instances are immutable; operations return new instances.
 
 ## Development

package/dist/currency.d.ts

@@ -195,6 +195,20 @@ export declare const Currency: {
 };
 export type CurrencyCode = keyof typeof Currency;
 export type CurrencyType = (typeof Currency)[CurrencyCode];
+export interface ResolveCurrencyOptions {
+    /**
+     * When set, an unknown code resolves to `defineCurrency(code, fallbackDecimalPlaces)`
+     * instead of `undefined`. The definition is cached, so repeated calls with
+     * the same code and decimal places return the same object.
+     */
+    fallbackDecimalPlaces?: number;
+}
+/**
+ * Looks up a currency definition by code. A built-in code returns the same
+ * object as `Currency[code]`; an unknown code returns `undefined` unless
+ * `fallbackDecimalPlaces` is given.
+ */
+export declare function resolveCurrency(code: string, options?: ResolveCurrencyOptions): CurrencyDefinition | undefined;
 export interface DefineCurrencyOptions {
     numericCode?: number;
     iso4217?: boolean;

package/dist/index.cjs

@@ -39,9 +39,10 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
-  defineCurrency: () => defineCurrency,
+  Currency: () => Currency,
   Money: () => Money,
-  Currency: () => Currency
+  defineCurrency: () => defineCurrency,
+  resolveCurrency: () => resolveCurrency
 });
 module.exports = __toCommonJS(exports_src);
 
@@ -76,6 +77,23 @@ var Currency = {
   SAR: { code: "SAR", decimalPlaces: 2, numericCode: 682, iso4217: true },
   BTC: { code: "BTC", decimalPlaces: 8, iso4217: false }
 };
+var builtInCurrencies = new Map(Object.entries(Currency));
+var fallbackCurrencies = new Map;
+function resolveCurrency(code, options = {}) {
+  const builtIn = builtInCurrencies.get(code);
+  if (builtIn !== undefined)
+    return builtIn;
+  const { fallbackDecimalPlaces } = options;
+  if (fallbackDecimalPlaces === undefined)
+    return;
+  const key = `${code}:${fallbackDecimalPlaces}`;
+  let definition = fallbackCurrencies.get(key);
+  if (definition === undefined) {
+    definition = defineCurrency(code, fallbackDecimalPlaces);
+    fallbackCurrencies.set(key, definition);
+  }
+  return definition;
+}
 var ISO_ALPHA3 = /^[A-Z]{3}$/;
 function defineCurrency(code, decimalPlaces, options = {}) {
   if (!code || typeof code !== "string") {
@@ -156,16 +174,17 @@ function parseDecimalStringToScaled(str) {
   const result = scaledInt + scaledDec;
   return negative ? -result : result;
 }
-function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
-  const targetScale = 10n ** BigInt(targetDecimalPlaces);
-  const divisor = INTERNAL_SCALE / targetScale;
-  const quotient = scaled / divisor;
-  const remainder = scaled % divisor;
+function divideAndRound(dividend, divisor, mode) {
+  if (divisor < 0n) {
+    dividend = -dividend;
+    divisor = -divisor;
+  }
+  const quotient = dividend / divisor;
+  const remainder = dividend % divisor;
   if (remainder === 0n)
     return quotient;
-  const isNegative = scaled < 0n;
-  const absRemainder = isNegative ? -remainder : remainder;
-  const halfDivisor = divisor / 2n;
+  const isNegative = dividend < 0n;
+  const doubledRemainder = (isNegative ? -remainder : remainder) * 2n;
   switch (mode) {
     case "floor":
       return isNegative ? quotient - 1n : quotient;
@@ -174,14 +193,21 @@ function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
     case "trunc":
       return quotient;
     default:
-      if (absRemainder > halfDivisor || absRemainder === halfDivisor && !isNegative) {
+      if (doubledRemainder > divisor || doubledRemainder === divisor && !isNegative) {
         return isNegative ? quotient - 1n : quotient + 1n;
       }
       return quotient;
   }
 }
+function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
+  const targetScale = 10n ** BigInt(targetDecimalPlaces);
+  return divideAndRound(scaled, INTERNAL_SCALE / targetScale, mode);
+}
+function currenciesMatch(a, b) {
+  return a.code === b.code && a.decimalPlaces === b.decimalPlaces;
+}
 function assertCurrenciesMatch(a, b, operation) {
-  if (a.code !== b.code || a.decimalPlaces !== b.decimalPlaces) {
+  if (!currenciesMatch(a, b)) {
     throw new Error(`Cannot ${operation} ${a.code} and ${b.code}: currency mismatch`);
   }
 }
@@ -245,6 +271,9 @@ class Money {
   static fromMinor(currency, minor) {
     return new Money(BigInt(minor), currency);
   }
+  static zero(currency) {
+    return new Money(0n, currency);
+  }
   toNumber() {
     const divisor = 10 ** this.#currency.decimalPlaces;
     return Number(this.#minor) / divisor;
@@ -264,12 +293,14 @@ class Money {
     assertSafeResult(result);
     return new Money(result, a.#currency);
   }
-  static sum(items) {
-    const first = items[0];
-    if (first === undefined) {
-      throw new Error("Cannot sum empty array: at least one Money value required");
+  static sum(items, currency) {
+    if (currency === undefined) {
+      const first = items[0];
+      if (first === undefined) {
+        throw new Error("Cannot sum empty array: at least one Money value required");
+      }
+      currency = first.#currency;
     }
-    const currency = first.#currency;
     let total = 0n;
     for (const item of items) {
       assertCurrenciesMatch(item.#currency, currency, "sum");
@@ -278,6 +309,12 @@ class Money {
     assertSafeResult(total);
     return new Money(total, currency);
   }
+  static sameCurrency(items, currency) {
+    const target = currency ?? items[0]?.currency;
+    if (target === undefined)
+      return true;
+    return items.every((item) => currenciesMatch(item.#currency, target));
+  }
   static equals(a, b) {
     assertCurrenciesMatch(a.#currency, b.#currency, "compare");
     return a.#minor === b.#minor;
@@ -427,6 +464,19 @@ class Money {
   round(increment, mode) {
     return Money.roundTo(this, increment, mode);
   }
+  static scaleByRatio(money, numerator, denominator, options = {}) {
+    assertCurrenciesMatch(numerator.#currency, denominator.#currency, "form a ratio from");
+    if (denominator.#minor === 0n) {
+      throw new Error("Cannot scale by a ratio with a zero denominator");
+    }
+    const { rounding = "round" } = options;
+    const resultMinor = divideAndRound(money.#minor * numerator.#minor, denominator.#minor, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  scaleByRatio(numerator, denominator, options) {
+    return Money.scaleByRatio(this, numerator, denominator, options);
+  }
   static percentOf(money, percent, options = {}) {
     const { rounding = "round" } = options;
     const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { Currency, type CurrencyCode, type CurrencyDefinition, type CurrencyType, type DefineCurrencyOptions, defineCurrency, } from "./currency";
+export { Currency, type CurrencyCode, type CurrencyDefinition, type CurrencyType, type DefineCurrencyOptions, defineCurrency, type ResolveCurrencyOptions, resolveCurrency, } from "./currency";
 export { type FromNumberOptions, Money, type RoundingMode, type SerializedMoney, } from "./money";

package/dist/index.mjs

@@ -29,6 +29,23 @@ var Currency = {
   SAR: { code: "SAR", decimalPlaces: 2, numericCode: 682, iso4217: true },
   BTC: { code: "BTC", decimalPlaces: 8, iso4217: false }
 };
+var builtInCurrencies = new Map(Object.entries(Currency));
+var fallbackCurrencies = new Map;
+function resolveCurrency(code, options = {}) {
+  const builtIn = builtInCurrencies.get(code);
+  if (builtIn !== undefined)
+    return builtIn;
+  const { fallbackDecimalPlaces } = options;
+  if (fallbackDecimalPlaces === undefined)
+    return;
+  const key = `${code}:${fallbackDecimalPlaces}`;
+  let definition = fallbackCurrencies.get(key);
+  if (definition === undefined) {
+    definition = defineCurrency(code, fallbackDecimalPlaces);
+    fallbackCurrencies.set(key, definition);
+  }
+  return definition;
+}
 var ISO_ALPHA3 = /^[A-Z]{3}$/;
 function defineCurrency(code, decimalPlaces, options = {}) {
   if (!code || typeof code !== "string") {
@@ -109,16 +126,17 @@ function parseDecimalStringToScaled(str) {
   const result = scaledInt + scaledDec;
   return negative ? -result : result;
 }
-function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
-  const targetScale = 10n ** BigInt(targetDecimalPlaces);
-  const divisor = INTERNAL_SCALE / targetScale;
-  const quotient = scaled / divisor;
-  const remainder = scaled % divisor;
+function divideAndRound(dividend, divisor, mode) {
+  if (divisor < 0n) {
+    dividend = -dividend;
+    divisor = -divisor;
+  }
+  const quotient = dividend / divisor;
+  const remainder = dividend % divisor;
   if (remainder === 0n)
     return quotient;
-  const isNegative = scaled < 0n;
-  const absRemainder = isNegative ? -remainder : remainder;
-  const halfDivisor = divisor / 2n;
+  const isNegative = dividend < 0n;
+  const doubledRemainder = (isNegative ? -remainder : remainder) * 2n;
   switch (mode) {
     case "floor":
       return isNegative ? quotient - 1n : quotient;
@@ -127,14 +145,21 @@ function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
     case "trunc":
       return quotient;
     default:
-      if (absRemainder > halfDivisor || absRemainder === halfDivisor && !isNegative) {
+      if (doubledRemainder > divisor || doubledRemainder === divisor && !isNegative) {
         return isNegative ? quotient - 1n : quotient + 1n;
       }
       return quotient;
   }
 }
+function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
+  const targetScale = 10n ** BigInt(targetDecimalPlaces);
+  return divideAndRound(scaled, INTERNAL_SCALE / targetScale, mode);
+}
+function currenciesMatch(a, b) {
+  return a.code === b.code && a.decimalPlaces === b.decimalPlaces;
+}
 function assertCurrenciesMatch(a, b, operation) {
-  if (a.code !== b.code || a.decimalPlaces !== b.decimalPlaces) {
+  if (!currenciesMatch(a, b)) {
     throw new Error(`Cannot ${operation} ${a.code} and ${b.code}: currency mismatch`);
   }
 }
@@ -198,6 +223,9 @@ class Money {
   static fromMinor(currency, minor) {
     return new Money(BigInt(minor), currency);
   }
+  static zero(currency) {
+    return new Money(0n, currency);
+  }
   toNumber() {
     const divisor = 10 ** this.#currency.decimalPlaces;
     return Number(this.#minor) / divisor;
@@ -217,12 +245,14 @@ class Money {
     assertSafeResult(result);
     return new Money(result, a.#currency);
   }
-  static sum(items) {
-    const first = items[0];
-    if (first === undefined) {
-      throw new Error("Cannot sum empty array: at least one Money value required");
+  static sum(items, currency) {
+    if (currency === undefined) {
+      const first = items[0];
+      if (first === undefined) {
+        throw new Error("Cannot sum empty array: at least one Money value required");
+      }
+      currency = first.#currency;
     }
-    const currency = first.#currency;
     let total = 0n;
     for (const item of items) {
       assertCurrenciesMatch(item.#currency, currency, "sum");
@@ -231,6 +261,12 @@ class Money {
     assertSafeResult(total);
     return new Money(total, currency);
   }
+  static sameCurrency(items, currency) {
+    const target = currency ?? items[0]?.currency;
+    if (target === undefined)
+      return true;
+    return items.every((item) => currenciesMatch(item.#currency, target));
+  }
   static equals(a, b) {
     assertCurrenciesMatch(a.#currency, b.#currency, "compare");
     return a.#minor === b.#minor;
@@ -380,6 +416,19 @@ class Money {
   round(increment, mode) {
     return Money.roundTo(this, increment, mode);
   }
+  static scaleByRatio(money, numerator, denominator, options = {}) {
+    assertCurrenciesMatch(numerator.#currency, denominator.#currency, "form a ratio from");
+    if (denominator.#minor === 0n) {
+      throw new Error("Cannot scale by a ratio with a zero denominator");
+    }
+    const { rounding = "round" } = options;
+    const resultMinor = divideAndRound(money.#minor * numerator.#minor, denominator.#minor, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  scaleByRatio(numerator, denominator, options) {
+    return Money.scaleByRatio(this, numerator, denominator, options);
+  }
   static percentOf(money, percent, options = {}) {
     const { rounding = "round" } = options;
     const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
@@ -453,7 +502,8 @@ class Money {
   }
 }
 export {
-  defineCurrency,
+  Currency,
   Money,
-  Currency
+  defineCurrency,
+  resolveCurrency
 };

package/dist/money.d.ts

@@ -1,4 +1,13 @@
 import type { CurrencyDefinition } from "./currency";
+/**
+ * How a value between two minor units is resolved.
+ *
+ * - `"floor"`: toward -Infinity.
+ * - `"ceil"`: toward +Infinity.
+ * - `"trunc"`: toward zero.
+ * - `"round"`: to the nearest minor unit; an exact half goes toward
+ *   +Infinity, so 2.5 becomes 3 and -2.5 becomes -2 (not half away from zero).
+ */
 export type RoundingMode = "floor" | "ceil" | "round" | "trunc";
 export interface FromNumberOptions {
     rounding?: RoundingMode;
@@ -19,11 +28,23 @@ export declare class Money {
     get currency(): CurrencyDefinition;
     static fromNumber(currency: CurrencyDefinition, value: number, options?: FromNumberOptions): Money;
     static fromMinor(currency: CurrencyDefinition, minor: number): Money;
+    static zero(currency: CurrencyDefinition): Money;
     toNumber(): number;
     toMinor(): number;
     static add(a: Money, b: Money): Money;
     static subtract(a: Money, b: Money): Money;
-    static sum(items: Money[]): Money;
+    /**
+     * Adds every item. Without `currency`, the list must be non-empty and the
+     * first item sets the currency. With `currency`, an empty list returns
+     * `Money.zero(currency)` and every item must match `currency`.
+     */
+    static sum(items: readonly Money[], currency?: CurrencyDefinition): Money;
+    /**
+     * True when every item's currency matches `currency` (or the first item's
+     * currency when omitted), using the same rule as arithmetic: equal `code`
+     * and `decimalPlaces`. An empty list is true.
+     */
+    static sameCurrency(items: readonly Money[], currency?: CurrencyDefinition): boolean;
     static equals(a: Money, b: Money): boolean;
     static compare(a: Money, b: Money): number;
     static lessThan(a: Money, b: Money): boolean;
@@ -51,6 +72,21 @@ export declare class Money {
     }): Money;
     static roundTo(money: Money, increment: number, mode?: RoundingMode): Money;
     round(increment: number, mode?: RoundingMode): Money;
+    /**
+     * Returns `money × numerator ÷ denominator` in `money`'s currency, computed
+     * exactly on minor units with a single rounding (default `"round"`).
+     *
+     * The ratio is dimensionless: `numerator` and `denominator` must share a
+     * currency with each other, but not with `money`. Throws when the
+     * denominator is zero, when the ratio's currencies differ, or when the
+     * result exceeds the safe integer range.
+     */
+    static scaleByRatio(money: Money, numerator: Money, denominator: Money, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    scaleByRatio(numerator: Money, denominator: Money, options?: {
+        rounding?: RoundingMode;
+    }): Money;
     static percentOf(money: Money, percent: number, options?: {
         rounding?: RoundingMode;
     }): Money;

package/dist/zod.cjs

@@ -39,14 +39,14 @@ var __export = (target, all) => {
 // src/zod.ts
 var exports_zod = {};
 __export(exports_zod, {
-  serializedMoneySchema: () => serializedMoneySchema,
-  moneySchema: () => moneySchema,
-  moneyInstanceSchema: () => moneyInstanceSchema,
-  moneyCodec: () => moneyCodec,
-  currencyDefinitionSchema: () => currencyDefinitionSchema,
-  currencyCodeSchema: () => currencyCodeSchema,
+  builtInSerializedMoneySchema: () => builtInSerializedMoneySchema,
   createMoneyCodec: () => createMoneyCodec,
-  builtInSerializedMoneySchema: () => builtInSerializedMoneySchema
+  currencyCodeSchema: () => currencyCodeSchema,
+  currencyDefinitionSchema: () => currencyDefinitionSchema,
+  moneyCodec: () => moneyCodec,
+  moneyInstanceSchema: () => moneyInstanceSchema,
+  moneySchema: () => moneySchema,
+  serializedMoneySchema: () => serializedMoneySchema
 });
 module.exports = __toCommonJS(exports_zod);
 var import_money = require("@storepass/money");

package/dist/zod.mjs

@@ -72,12 +72,12 @@ function createMoneyCodec(currencies) {
 }
 var moneyCodec = createMoneyCodec(Currency);
 export {
-  serializedMoneySchema,
-  moneySchema,
-  moneyInstanceSchema,
-  moneyCodec,
-  currencyDefinitionSchema,
-  currencyCodeSchema,
+  builtInSerializedMoneySchema,
   createMoneyCodec,
-  builtInSerializedMoneySchema
+  currencyCodeSchema,
+  currencyDefinitionSchema,
+  moneyCodec,
+  moneyInstanceSchema,
+  moneySchema,
+  serializedMoneySchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@storepass/money",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "Money primitive library",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.mjs",
@@ -46,11 +46,11 @@
 	"author": "darling (https://github.com/darling)",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/Atlas-Alpha/sp-money"
+		"url": "git+https://github.com/Storepass/money.git"
 	},
-	"homepage": "https://github.com/Atlas-Alpha/sp-money#readme",
+	"homepage": "https://github.com/Storepass/money#readme",
 	"bugs": {
-		"url": "https://github.com/Atlas-Alpha/sp-money/issues"
+		"url": "https://github.com/Storepass/money/issues"
 	},
 	"keywords": [
 		"money",