@smounters/kit 2.22.1 → 2.24.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.24.0 - 2026-09-11
+
+### Added
+- `kit/money`: `createMoney({ scale, pad })` — арифметика, привязанная к масштабу хранения, который
+  выбирает ПРИЛОЖЕНИЕ. Прежние `MONEY_SCALE`/`toMoneyAmount`/`applyDelta` остались как масштаб-4 по
+  умолчанию и ничего не меняют для тех, кто выбора не делал. Понадобилось потребителю, расширившему
+  денежные колонки до `numeric(40,20)`: на четырёх знаках срезалась точность токенов.
+  Добивки нулями у новой формы по умолчанию нет — при широком масштабе она отдаёт стену нулей, а
+  `"0.00000000000000000000" !== "0"` ломает сравнения ниже по течению.
+
+### Changed
+- `kit/money`: `Decimal.set` поднят с `precision: 50` до `80`. У самой decimal.js умолчание — 20
+  ЗНАЧАЩИХ цифр, и она молча округляет до них даже обычное сложение; на 18–20 знаках после запятой
+  это теряет хвост каждой суммы. Самая широкая колонка потребителя — 40 значащих цифр, и две такие
+  встречаются в одном умножении, поэтому запас взят двойной.
+
 ## 2.2.0 - 2026-07-30
 
 ### Added

package/README.md

@@ -104,6 +104,26 @@ quantizeToDecimals(due, 6, ROUND_UP); // сумма, достижимая у т
 знаками не переведёт значение с восемью, и «ожидаемая» сумма, скруглённая до масштаба книги, окажется
 неоплатной точно — а строгое сравнение назовёт это недоплатой, которой плательщик не мог избежать.
 
+### Свой масштаб хранения
+
+Функции выше привязаны к масштабу 4 — это фиат. Приложению, которое держит в той же книге токены,
+четырёх знаков мало, а масштаб — **политика**, поэтому его задаёт потребитель:
+
+```ts
+import { createMoney } from "@smounters/kit/money";
+
+const money = createMoney({ scale: 20 }); // numeric(40,20)
+
+money.toAmount("10.123456");              // "10.123456" — точность токена сохранена
+money.toAmount("0.123456789012345678901") // null — точнее, чем хранит колонка
+money.applyDelta("0", "100");             // "100", а не "100.00000000000000000000"
+money.quantize("10.126", ROUND_HALF_UP);  // "10.13" — округление, когда его ПОПРОСИЛИ
+```
+
+Добивки нулями по умолчанию нет намеренно: при широком масштабе она возвращала бы стену нулей, а
+`"0.00000000000000000000" !== "0"` ломает любое наивное сравнение ниже по течению. Нужна старая
+форма — `createMoney({ scale: 4, pad: true })`.
+
 ## Защита от SSRF
 
 ```ts

package/dist/money/index.d.ts

@@ -33,6 +33,32 @@ export declare function quantizeToDecimals(amount: string, decimals: number, rou
 export declare function sumAmounts(amounts: readonly string[]): Decimal;
 /** Apply a signed delta to a balance, at money scale. */
 export declare function applyDelta(balance: string, amount: string): string;
+export interface MoneyOptions {
+    /** Decimal places the storage column keeps. Anything more precise is rejected, never rounded away. */
+    scale: number;
+    /**
+     * Pad results to `scale` (`"100"` → `"100.0000"`). Off by default: a wide column (scale 20) would
+     * otherwise hand every caller a string of trailing zeros, and `"0.00000000000000000000" !== "0"`
+     * breaks every naive comparison downstream.
+     */
+    pad?: boolean;
+}
+export interface MoneyOps {
+    readonly scale: number;
+    readonly zero: string;
+    fits(amount: string): boolean;
+    toAmount(amount: string): string | null;
+    applyDelta(balance: string, amount: string): string;
+    quantize(amount: string, rounding?: Decimal.Rounding): string;
+}
+/**
+ * Money arithmetic bound to one storage scale.
+ *
+ * The scale is POLICY — a fiat-only ledger settles at 4 decimals, one that also holds tokens needs 18
+ * or more — so it belongs to the application, not to this package. The module-level `MONEY_SCALE`
+ * helpers remain as the scale-4 default for callers that never had to choose.
+ */
+export declare function createMoney({ scale, pad }: MoneyOptions): MoneyOps;
 export interface PostingLine {
     /** Signed decimal string: debit > 0, credit < 0. */
     amount: string;

package/dist/money/index.js

@@ -4,8 +4,12 @@ import { Decimal } from "decimal.js";
 // Nothing here may use a JS number: a double cannot represent 0.1 exactly, and a ledger that cannot
 // represent its own amounts stops balancing within a day. Amounts travel as decimal STRINGS end to end
 // (numeric in the database, string on the wire) and are only turned into Decimal for the arithmetic.
-// Precision must exceed the widest intermediate we produce (a 20-digit amount divided by an 18-dp rate).
-Decimal.set({ precision: 50, toExpNeg: -50, toExpPos: 50 });
+// Precision must exceed the widest intermediate we produce. The widest column a consumer stores is
+// numeric(40,20) — 40 significant digits — and two of those can meet in one multiplication, so the
+// library must carry twice that before it starts rounding. decimal.js defaults to 20 SIGNIFICANT
+// digits and rounds even a plain addition down to them, silently: at 18 decimal places that loses
+// the tail of every sum. Importing this module is what fixes it for the whole process.
+Decimal.set({ precision: 80, toExpNeg: -80, toExpPos: 80 });
 /** Money scale: `numeric(20,4)`. Four decimal places cover fiat and keep every posting exact. */
 export const MONEY_SCALE = 4;
 /** Ratio scale: `numeric(20,8)` — returns, coverage, shares of a fee. */
@@ -53,6 +57,30 @@ export function sumAmounts(amounts) {
 export function applyDelta(balance, amount) {
     return toDecimal(balance).plus(toDecimal(amount)).toFixed(MONEY_SCALE);
 }
+/**
+ * Money arithmetic bound to one storage scale.
+ *
+ * The scale is POLICY — a fiat-only ledger settles at 4 decimals, one that also holds tokens needs 18
+ * or more — so it belongs to the application, not to this package. The module-level `MONEY_SCALE`
+ * helpers remain as the scale-4 default for callers that never had to choose.
+ */
+export function createMoney({ scale, pad = false }) {
+    if (!Number.isInteger(scale) || scale < 0 || scale > 40) {
+        throw new RangeError(`Money scale must be an integer in 0..40, got ${scale}`);
+    }
+    const render = (d) => (pad ? d.toFixed(scale) : d.toFixed());
+    return {
+        scale,
+        zero: render(new Decimal(0)),
+        fits: (amount) => toDecimal(amount).decimalPlaces() <= scale,
+        toAmount: (amount) => {
+            const d = toDecimal(amount);
+            return d.decimalPlaces() > scale ? null : render(d);
+        },
+        applyDelta: (balance, amount) => render(toDecimal(balance).plus(toDecimal(amount))),
+        quantize: (amount, rounding = ROUND_HALF_UP) => toDecimal(amount).toFixed(scale, rounding),
+    };
+}
 /**
  * Is this a valid double-entry posting? At least two lines, no zero-amount line, and the signed amounts
  * sum to EXACTLY zero. This is the invariant that makes a ledger auditable, so it is checked in code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/kit",
-  "version": "2.22.1",
+  "version": "2.24.0",
   "description": "Batteries for Imperium services: structured logging, Redis module with a distributed lock, SSRF-safe fetch, decimal money, request context, env schemas",
   "keywords": [
     "imperium",
@@ -101,10 +101,10 @@
     "@bufbuild/protobuf": "^2.10.2",
     "@bufbuild/protovalidate": "^1.0.0",
     "@connectrpc/connect": "^2.1.1",
+    "@smounters/core": "2.0.1",
     "fastify": "^5.8.4",
     "ioredis": "^5.9.3",
-    "zod": "^4.3.6",
-    "@smounters/core": "2.0.1"
+    "zod": "^4.3.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",