@stll/money 0.2.0 → 0.2.3

package/dist/index.d.ts

@@ -22,14 +22,14 @@ type CentsAmount = number & {
  * moving. An amount that far out is a caller defect rather than a runtime
  * condition, like a fractional one, so it panics the same way.
  */
-declare const cents: (value: number) => CentsAmount;
+export declare const cents: (value: number) => CentsAmount;
 /**
  * Escape hatch for code paths that genuinely need to attach the brand
  * without a runtime check (test fixtures, generated code). Prefer
  * `cents()` everywhere else; reach for this only with a `// SAFETY:`
  * comment naming why the value is already a valid minor-unit integer.
  */
-declare const unsafeCents: (value: number) => CentsAmount;
+export declare const unsafeCents: (value: number) => CentsAmount;
 //#endregion
 //#region src/format.d.ts
 /**
@@ -40,7 +40,7 @@ declare const unsafeCents: (value: number) => CentsAmount;
  * A malformed code makes the `Intl.NumberFormat` constructor throw, before any
  * `?? 2` on its result could help, so the fallback has to wrap the call.
  */
-declare const currencyMinorUnitDigits: (currency: string) => number;
+export declare const currencyMinorUnitDigits: (currency: string) => number;
 type ToMinorUnitsParams = {
   /**
    * The amount in major units: the decimal text a form holds, or a number.
@@ -67,7 +67,7 @@ type ToMinorUnitsParams = {
  * and a result outside the safe integer range, are caller defects: gate the
  * text with `isDecimalAmount` first.
  */
-declare const toMinorUnits: (params: ToMinorUnitsParams) => CentsAmount;
+export declare const toMinorUnits: (params: ToMinorUnitsParams) => CentsAmount;
 /**
  * The same conversion for text nobody has vouched for yet: null when the text
  * is not a decimal amount, and null when the scaled value would leave the safe
@@ -77,13 +77,13 @@ declare const toMinorUnits: (params: ToMinorUnitsParams) => CentsAmount;
  * past that gate calls `toMinorUnits`, which panics, because by then the
  * decision has been made.
  */
-declare const tryToMinorUnits: ({ amount, currency }: ToMinorUnitsParams) => CentsAmount | null;
+export declare const tryToMinorUnits: ({ amount, currency }: ToMinorUnitsParams) => CentsAmount | null;
 type ToMajorUnitsParams = {
   amountCents: number;
   currency: string;
 };
 /** The inverse: a stored amount as the major-unit number a person reads. */
-declare const toMajorUnits: ({ amountCents, currency }: ToMajorUnitsParams) => number;
+export declare const toMajorUnits: ({ amountCents, currency }: ToMajorUnitsParams) => number;
 type FormatMoneyCentsParams = {
   amountCents: number;
   currency: string;
@@ -102,19 +102,19 @@ type FormatMoneyCentsParams = {
  * showing "15.00 A1C" is wrong-looking data, which is the truth, where a thrown
  * RangeError would take the whole board down with it.
  */
-declare const formatMoneyCents: ({ amountCents, currency, locale, fractionDigits }: FormatMoneyCentsParams) => string;
+export declare const formatMoneyCents: ({ amountCents, currency, locale, fractionDigits }: FormatMoneyCentsParams) => string;
 //#endregion
 //#region src/index.d.ts
-type ProrateHourlyCentsInput = {
+export type ProrateHourlyCentsInput = {
   billedMinutes: number;
   hourlyRateCents: CentsAmount;
 };
-declare const prorateHourlyCents: ({ billedMinutes, hourlyRateCents }: ProrateHourlyCentsInput) => CentsAmount;
-type ApplyMarkupCentsInput = {
+export declare const prorateHourlyCents: ({ billedMinutes, hourlyRateCents }: ProrateHourlyCentsInput) => CentsAmount;
+export type ApplyMarkupCentsInput = {
   amountCents: CentsAmount;
   markupPercent: number;
 };
-declare const applyMarkupCents: ({ amountCents, markupPercent }: ApplyMarkupCentsInput) => CentsAmount;
+export declare const applyMarkupCents: ({ amountCents, markupPercent }: ApplyMarkupCentsInput) => CentsAmount;
 declare const __currency: unique symbol;
 /**
  * A `CentsAmount` additionally branded with its ISO 4217-ish currency code
@@ -128,7 +128,7 @@ declare const __currency: unique symbol;
  * currency code is a plain string carried alongside it, so there is no
  * boundary that needs to skip it.
  */
-type CurrencyCents<C extends string = string> = CentsAmount & {
+export type CurrencyCents<C extends string = string> = CentsAmount & {
   readonly [__currency]: C;
 };
 /**
@@ -137,7 +137,7 @@ type CurrencyCents<C extends string = string> = CentsAmount & {
  * from the literal `currency` argument (e.g. `currencyCents("USD", 100)`
  * infers `CurrencyCents<"USD">`).
  */
-declare const currencyCents: <C extends string>(currency: C, amount: number) => CurrencyCents<C>;
+export declare const currencyCents: <C extends string>(currency: C, amount: number) => CurrencyCents<C>;
 type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 type IsSingletonCurrency<C extends string> = string extends C ? never : [C] extends [UnionToIntersection<C>] ? C : never;
 /**
@@ -161,7 +161,7 @@ type IsSingletonCurrency<C extends string> = string extends C ? never : [C] exte
  * instead, which buckets by currency at runtime and is the runtime-correct
  * tool for that case.
  */
-declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurrency<A> extends never ? never : CurrencyCents<A>, b: IsSingletonCurrency<B> extends never ? never : CurrencyCents<B>) => CurrencyCents<A>;
+export declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurrency<A> extends never ? never : CurrencyCents<A>, b: IsSingletonCurrency<B> extends never ? never : CurrencyCents<B>) => CurrencyCents<A>;
 /**
  * Per-currency accumulator for aggregating money across rows that may carry
  * different currencies (e.g. time entries across matters, expenses across
@@ -182,11 +182,11 @@ declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurren
  * the same "never sum across currencies" invariant at runtime via the
  * per-currency `Map`.
  */
-type MoneyTotalsEntry = {
+export type MoneyTotalsEntry = {
   currency: string;
   amountCents: CentsAmount;
 };
-declare class MoneyTotals {
+export declare class MoneyTotals {
   #private;
   /** Add `amountCents` to the running total for `currency`. */
   add(currency: string, amountCents: CentsAmount): void;
@@ -199,4 +199,4 @@ declare class MoneyTotals {
   entries(): MoneyTotalsEntry[];
 }
 //#endregion
-export { ApplyMarkupCentsInput, type CentsAmount, CurrencyCents, type FormatMoneyCentsParams, MoneyTotals, MoneyTotalsEntry, ProrateHourlyCentsInput, type ToMajorUnitsParams, type ToMinorUnitsParams, addCents, applyMarkupCents, cents, currencyCents, currencyMinorUnitDigits, formatMoneyCents, prorateHourlyCents, toMajorUnits, toMinorUnits, tryToMinorUnits, unsafeCents };
+export type { CentsAmount, FormatMoneyCentsParams, ToMajorUnitsParams, ToMinorUnitsParams };

package/dist/index.js

@@ -7,6 +7,8 @@ import { Result, panic } from "better-result";
 * conversion helpers there return a `CentsAmount`, and a module the package
 * entry re-exports cannot import back from that entry without a cycle.
 */
+/** The brand is nominal: every safe integer is a valid minor-unit amount. */
+const isMinorUnitAmount = (value) => Number.isSafeInteger(value);
 /**
 * Construct a CentsAmount from a value already known to be in minor
 * units. Use at boundaries where the input is validated as an integer
@@ -20,7 +22,7 @@ import { Result, panic } from "better-result";
 * condition, like a fractional one, so it panics the same way.
 */
 const cents = (value) => {
-	if (!Number.isSafeInteger(value)) return panic(`cents(${value}): money values must be safe integer minor units`);
+	if (!isMinorUnitAmount(value)) return panic(`cents(${value}): money values must be safe integer minor units`);
 	return value;
 };
 /**
@@ -207,16 +209,19 @@ const formatMoneyCents = ({ amountCents, currency, locale, fractionDigits }) =>
 const prorateHourlyCents = ({ billedMinutes, hourlyRateCents }) => {
 	assertNonNegativeInteger("billedMinutes", billedMinutes);
 	assertNonNegativeInteger("hourlyRateCents", hourlyRateCents);
-	return cents(Math.floor((billedMinutes * hourlyRateCents + 30) / 60));
+	const product = BigInt(billedMinutes) * BigInt(hourlyRateCents);
+	return cents(Number((product + 30n) / 60n));
 };
 const applyMarkupCents = ({ amountCents, markupPercent }) => {
 	assertNonNegativeInteger("amountCents", amountCents);
 	assertNonNegativeInteger("markupPercent", markupPercent);
-	return cents(Math.floor((amountCents * (100 + markupPercent) + 50) / 100));
+	const product = BigInt(amountCents) * (100n + BigInt(markupPercent));
+	return cents(Number((product + 50n) / 100n));
 };
 function assertNonNegativeInteger(name, value) {
-	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) panic(`${name} must be a finite non-negative integer`);
+	if (!Number.isSafeInteger(value) || value < 0) panic(`${name} must be a finite non-negative integer within the safe range`);
 }
+const isCurrencyCents = (amount, currency) => currency !== "" && isMinorUnitAmount(amount);
 /**
 * Construct a `CurrencyCents<C>` from a currency code and a minor-unit
 * amount. The only producer of `CurrencyCents`; downstream code narrows `C`
@@ -225,7 +230,8 @@ function assertNonNegativeInteger(name, value) {
 */
 const currencyCents = (currency, amount) => {
 	if (!currency) return panic("currencyCents(): currency must be a non-empty code");
-	return cents(amount);
+	const minorUnits = cents(amount);
+	return isCurrencyCents(minorUnits, currency) ? minorUnits : panic("currencyCents(): currency must be a non-empty code");
 };
 /**
 * Add two `CurrencyCents` amounts of the SAME currency. The second
@@ -264,7 +270,7 @@ var MoneyTotals = class {
 	* `localeCompare`, so ordering does not vary with the runtime's locale.
 	*/
 	entries() {
-		return [...this.#totals.keys()].sort().map((currency) => ({
+		return [...this.#totals.keys()].toSorted().map((currency) => ({
 			currency,
 			amountCents: this.#totals.get(currency) ?? cents(0)
 		}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/money",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Branded minor-unit monetary amounts and currency-safe billing arithmetic.",
   "keywords": [
     "billing",
@@ -40,18 +40,18 @@
     "pack:dry-run": "bun pm pack --dry-run",
     "test": "bun test src",
     "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
-    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/money",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/money",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/money",
     "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "better-result": "3.0.0"
+    "better-result": "3.0.1"
   },
   "devDependencies": {
     "@stll/typescript-config": "0.0.0",
     "bun-types": "1.4.2",
-    "tsdown": "0.22.14"
+    "tsdown": "0.23.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"