@rallycash/numbers 0.0.0-stage → 0.2.0

package/dist/number-utils.js

@@ -0,0 +1,276 @@
+import { coerceNumber } from './decimal.js';
+import { formatUnits, parseUnits } from './units.js';
+export const expToString = (value) => {
+    const raw = value.toString();
+    const negative = raw.startsWith('-');
+    const expanded = expandUnsignedExponent(negative ? raw.slice(1) : raw);
+    if (!negative || expanded === '0')
+        return expanded;
+    return `-${expanded}`;
+};
+const expandUnsignedExponent = (expString) => {
+    const [maybeNumber, exponent] = expString.split('e');
+    const number = maybeNumber ?? '0';
+    if (!exponent)
+        return number;
+    const decimalPosition = number.indexOf('.');
+    const removedDecimalNumber = number.replace('.', '');
+    const actualDecimalPosition = decimalPosition === -1 ? number.length : decimalPosition;
+    const decimalMovement = actualDecimalPosition + parseInt(exponent, 10);
+    const additionaltrailingZeros = Math.max(decimalMovement - removedDecimalNumber.length, 0);
+    const additionalLeadingZeros = actualDecimalPosition + parseInt(exponent, 10) < 0
+        ? Math.abs(decimalMovement)
+        : 0;
+    const numberArr = Array(additionalLeadingZeros)
+        .fill('0')
+        .concat(removedDecimalNumber.split(''))
+        .concat(Array(additionaltrailingZeros).fill('0'));
+    const newDecimalPosition = Math.max(decimalMovement, 0);
+    if (newDecimalPosition < numberArr.length) {
+        const decimalInsertion = newDecimalPosition === 0 ? '0.' : '.';
+        numberArr.splice(newDecimalPosition, 0, decimalInsertion);
+    }
+    return numberArr.join('');
+};
+function getMagnitude(n) {
+    if (n === 0)
+        return 0;
+    return Math.floor(Math.log10(Math.abs(n)));
+}
+function toSubscript(text) {
+    const subscriptMap = {
+        '0': '₀',
+        '1': '₁',
+        '2': '₂',
+        '3': '₃',
+        '4': '₄',
+        '5': '₅',
+        '6': '₆',
+        '7': '₇',
+        '8': '₈',
+        '9': '₉',
+    };
+    let result = '';
+    for (const char of expToString(text)) {
+        result += subscriptMap[char] || char;
+    }
+    return result;
+}
+const abbreviateNumber = (num, decimals = 2, preserveTrailingZeros = false) => {
+    const lookup = [
+        { value: 1, symbol: '' },
+        { value: 1e3, symbol: 'K' },
+        { value: 1e6, symbol: 'M' },
+        { value: 1e9, symbol: 'B' },
+        { value: 1e12, symbol: 'T' },
+        { value: 1e15, symbol: 'P' },
+        { value: 1e18, symbol: 'E' },
+    ];
+    const rx = /\.0+$|(\.[0-9]*[1-9])0+$/;
+    const formatFixed = (fixed) => preserveTrailingZeros ? fixed : fixed.replace(rx, '$1');
+    if (!Number.isFinite(num))
+        return formatFixed(num.toFixed(decimals));
+    const absNum = Math.abs(num);
+    let tier = 0;
+    for (let i = lookup.length - 1; i >= 0; i--) {
+        const entry = lookup[i];
+        if (entry && absNum >= entry.value) {
+            tier = i;
+            break;
+        }
+    }
+    const renderTier = (index) => {
+        const entry = lookup[index];
+        if (!entry)
+            return { text: formatFixed(num.toFixed(decimals)), rounded: num };
+        const rounded = Number((num / entry.value).toFixed(decimals) || 0);
+        const formattedNumber = rounded.toLocaleString('en-us', {
+            minimumFractionDigits: decimals,
+            maximumFractionDigits: decimals,
+        });
+        return { text: formatFixed(formattedNumber) + entry.symbol, rounded };
+    };
+    let rendered = renderTier(tier);
+    if (Math.abs(rendered.rounded) >= 1000 && tier < lookup.length - 1) {
+        rendered = renderTier(tier + 1);
+    }
+    return rendered.text;
+};
+const formatNumber = (value, { showExponents = true, minSignificantDigits = 4, maxDecimals: maxDecimalsParam, minDecimals: minDecimalsParam, abbrThreshold = 1e7, abbreviateLargeNumbers = true, abbrMinSignificantDigits = 3, prefix = '', } = {}) => {
+    let minDecimals;
+    let maxDecimals;
+    if (maxDecimalsParam == null && minDecimalsParam != null) {
+        minDecimals = minDecimalsParam;
+        maxDecimals = Math.max(6, minDecimalsParam);
+    }
+    else if (minDecimalsParam == null && maxDecimalsParam != null) {
+        maxDecimals = maxDecimalsParam;
+        minDecimals = Math.min(2, maxDecimalsParam);
+    }
+    else if (maxDecimalsParam != null && minDecimalsParam != null) {
+        maxDecimals = maxDecimalsParam;
+        minDecimals = Math.min(maxDecimalsParam, minDecimalsParam);
+    }
+    else {
+        maxDecimals = 6;
+        minDecimals = 2;
+    }
+    const num = coerceNumber(value);
+    if (num === 0) {
+        const zeros = '0'.repeat(minDecimals);
+        return `0${zeros ? `.${zeros}` : ''}`;
+    }
+    if (!num)
+        return '';
+    const absNumber = Math.abs(num);
+    const magnitude = getMagnitude(num);
+    if (magnitude <= -Math.abs(maxDecimals) && minSignificantDigits) {
+        if (!showExponents) {
+            const numberToRound = Math.abs(num) * 10 ** (Math.abs(magnitude) + minSignificantDigits - 1);
+            const fullNumber = expToString(Math.round(numberToRound) /
+                10 ** (Math.abs(magnitude) + minSignificantDigits - 1));
+            const sign = num < 0 ? '-' : '';
+            return `${sign}${prefix}${fullNumber}`;
+        }
+        const unsignedEndPart = Math.abs(num) / 10 ** magnitude;
+        const formattedEndPart = Number(unsignedEndPart.toFixed(minSignificantDigits - 1))
+            .toLocaleString('en-us', {
+            minimumFractionDigits: minDecimals,
+            maximumFractionDigits: Math.max(0, Math.min(20, Math.max(minSignificantDigits - 2, minDecimals))),
+        })
+            .replace(/\./g, '');
+        const sign = num < 0 ? '-' : '';
+        return `${sign}${prefix}0.0${toSubscript(Math.abs(magnitude) - 1)}${formattedEndPart}`;
+    }
+    const smallestDisplayableNumber = 1 / 10 ** maxDecimals;
+    if (absNumber < smallestDisplayableNumber) {
+        const zeros = '0'.repeat(minDecimals);
+        return `0${zeros ? `.${zeros}` : ''}`;
+    }
+    if (abbreviateLargeNumbers && absNumber >= abbrThreshold) {
+        const numbersBeforeDecimal = (magnitude + 1) % 3 || 3;
+        return `${prefix}${abbreviateNumber(num, Math.max(abbrMinSignificantDigits - numbersBeforeDecimal, 0))}`;
+    }
+    if (absNumber < 1) {
+        const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals));
+        return `${prefix}${Number(num.toFixed(maxDecimals)).toLocaleString('en-us', {
+            minimumFractionDigits: minDecimals,
+            maximumFractionDigits: clampedMaxDecimals,
+        })}`;
+    }
+    if (absNumber >= 1 && absNumber < 10000) {
+        const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals));
+        return `${prefix}${Number(num.toFixed(Math.min(maxDecimals, 2))).toLocaleString('en-us', {
+            minimumFractionDigits: minDecimals,
+            maximumFractionDigits: clampedMaxDecimals,
+        })}`;
+    }
+    const rounded = maxDecimals === 0 ? Math.round(num) : num;
+    const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals));
+    return `${prefix}${Number(rounded.toFixed(maxDecimals)).toLocaleString('en-us', {
+        minimumFractionDigits: minDecimals,
+        maximumFractionDigits: clampedMaxDecimals,
+    })}`;
+};
+const USD_BALANCE_PRESET = {
+    minDecimals: 2,
+    maxDecimals: 2,
+    minSignificantDigits: 0,
+    showExponents: false,
+};
+const PERCENTAGE_PRESET = {
+    minDecimals: 0,
+    maxDecimals: 2,
+    minSignificantDigits: 0,
+    showExponents: false,
+};
+const INTEGER_PRESET = {
+    minDecimals: 0,
+    maxDecimals: 0,
+    minSignificantDigits: 0,
+    showExponents: false,
+};
+function mergePreset(preset, options) {
+    if (options === undefined)
+        return preset;
+    return { ...preset, ...options };
+}
+function coerceUsd(value) {
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return coerceNumber(value);
+}
+function formatSignedUsd(value, formatAbs) {
+    const numeric = coerceUsd(value);
+    if (numeric == null || !Number.isFinite(numeric) || numeric === 0)
+        return '$0.00';
+    const body = formatAbs(Math.abs(numeric));
+    return numeric < 0 ? `-$${body}` : `$${body}`;
+}
+const formatUsd = (value) => formatSignedUsd(value, (absolute) => abbreviateNumber(absolute, 2, true));
+const formatUsdBalance = (value, options) => formatSignedUsd(value, (absolute) => formatNumber(absolute, mergePreset(USD_BALANCE_PRESET, options)));
+const formatCryptoBalance = (value, options) => formatNumber(value, options);
+const formatPercentage = (value, options) => formatNumber(value, mergePreset(PERCENTAGE_PRESET, options));
+const formatInteger = (value, options) => formatNumber(value, mergePreset(INTEGER_PRESET, options));
+const formatTokenPrice = (price) => formatNumber(price);
+const formatBigInt = (input, decimals, formatOptions) => {
+    let atomic;
+    if (typeof input === 'bigint') {
+        atomic = input;
+    }
+    else if (typeof input === 'string') {
+        atomic = BigInt(input);
+    }
+    else {
+        atomic = parseUnits(input.toFixed(0), 0);
+    }
+    return formatNumber(Number(formatUnits(atomic, decimals)), formatOptions);
+};
+const formatLargeNumber = (value) => {
+    const numeric = typeof value === 'number' ? value : value.toNumber();
+    return abbreviateNumber(numeric, 2);
+};
+const formatSwapAmount = (value) => {
+    const number = typeof value === 'string' ? Number.parseFloat(value) : value;
+    if (!number || number === 0)
+        return '0';
+    if (number < 0)
+        return '<0';
+    const [integerPart, decimalPart = ''] = expToString(number).split('.');
+    if (!decimalPart)
+        return integerPart ?? '0';
+    const leadingZeroLength = (decimalPart.match(/^0+/) || [''])[0].length;
+    const significantDigits = decimalPart.replace(/^0+/, '').substring(0, 3);
+    if (!significantDigits)
+        return '0';
+    return `${integerPart}.${'0'.repeat(leadingZeroLength)}${significantDigits}`;
+};
+function computePercentile(sorted, percentile) {
+    if (sorted.length === 0)
+        return null;
+    const index = (percentile / 100) * (sorted.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    if (lower === upper)
+        return sorted[lower] ?? null;
+    const lowerValue = sorted[lower] ?? 0;
+    const upperValue = sorted[upper] ?? lowerValue;
+    return lowerValue + (upperValue - lowerValue) * (index - lower);
+}
+export const NumberUtils = {
+    formatNumber,
+    formatCryptoBalance,
+    formatUsdBalance,
+    formatPercentage,
+    formatUsd,
+    formatInteger,
+    formatTokenPrice,
+    formatBigInt,
+    abbreviateNumber,
+    formatLargeNumber,
+    formatSwapAmount,
+    expToString,
+    computePercentile,
+};

package/dist/units.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `formatUnits` / `parseUnits` behavior from viem's `Value` module.
+ * Inlined so this package does not depend on viem.
+ */
+export declare function formatUnits(value: bigint, decimals: number): string;
+export declare function parseUnits(value: string, decimals: number): bigint;
+//# sourceMappingURL=units.d.ts.map

package/dist/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../src/units.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAanE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8ClE"}

package/dist/units.js

@@ -0,0 +1,82 @@
+/**
+ * `formatUnits` / `parseUnits` behavior from viem's `Value` module.
+ * Inlined so this package does not depend on viem.
+ */
+export function formatUnits(value, decimals) {
+    assertDecimals(decimals);
+    let display = value.toString();
+    const negative = display.startsWith('-');
+    if (negative)
+        display = display.slice(1);
+    display = display.padStart(decimals, '0');
+    const integer = display.slice(0, display.length - decimals);
+    let fraction = display.slice(display.length - decimals);
+    fraction = fraction.replace(/(0+)$/, '');
+    return `${negative ? '-' : ''}${integer || '0'}${fraction ? `.${fraction}` : ''}`;
+}
+export function parseUnits(value, decimals) {
+    assertDecimals(decimals);
+    if (!/^-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)$/.test(value)) {
+        throw new Error(`\`${value}\` is not a valid decimal number.`);
+    }
+    let [integer = '', fraction = '0'] = value.split('.');
+    const negative = integer.startsWith('-');
+    if (negative)
+        integer = integer.slice(1);
+    if (integer === '')
+        integer = '0';
+    fraction = fraction.replace(/(0+)$/, '');
+    if (decimals === 0) {
+        const firstFractionDigit = fraction[0];
+        if (fraction.length > 0 &&
+            firstFractionDigit !== undefined &&
+            Number.parseInt(firstFractionDigit, 10) >= 5) {
+            integer = `${BigInt(integer) + 1n}`;
+        }
+        fraction = '';
+    }
+    else if (fraction.length > decimals) {
+        const left = fraction.slice(0, decimals);
+        const roundDigitChar = fraction.slice(decimals, decimals + 1);
+        const roundDigit = Number.parseInt(roundDigitChar, 10);
+        if (roundDigit >= 5) {
+            const carried = carry(left);
+            if (carried.length > decimals) {
+                fraction = carried.slice(1);
+                integer = `${BigInt(integer) + 1n}`;
+            }
+            else {
+                fraction = carried;
+            }
+        }
+        else {
+            fraction = left;
+        }
+    }
+    else {
+        fraction = fraction.padEnd(decimals, '0');
+    }
+    return BigInt(`${negative ? '-' : ''}${integer}${fraction}`);
+}
+function assertDecimals(decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new Error(`decimals must be a non-negative integer. Got \`${decimals}\`.`);
+    }
+}
+function carry(digits) {
+    const out = digits.split('');
+    let i = out.length - 1;
+    while (i >= 0) {
+        const current = out[i];
+        if (current === undefined)
+            break;
+        const next = Number.parseInt(current, 10) + 1;
+        if (next < 10) {
+            out[i] = String(next);
+            return out.join('');
+        }
+        out[i] = '0';
+        i -= 1;
+    }
+    return `1${out.join('')}`;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@rallycash/numbers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Number formatting and fixed-point bigint conversion",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -b --force",
+    "typecheck": "../../node_modules/.bin/tsc --noEmit -p tsconfig.json",
+    "test": "../../node_modules/.bin/vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
 }

package/src/bigint-utils.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest'
+
+import { BigIntUtils } from './bigint-utils.js'
+
+describe('BigIntUtils.toBigInt', () => {
+  it('parses a decimal string at the given scale', () => {
+    expect(BigIntUtils.toBigInt('1.5', 6)).toBe(1_500000n)
+  })
+
+  it('expands scientific notation before parsing', () => {
+    expect(BigIntUtils.toBigInt(1e-7, 18)).toBe(100_000_000_000n)
+    expect(BigIntUtils.toBigInt(-1e-7, 18)).toBe(-100_000_000_000n)
+  })
+
+  it('leaves a bigint untouched', () => {
+    expect(BigIntUtils.toBigInt(5n, 6)).toBe(5n)
+  })
+
+  it('reads a decimal-like via toFixed', () => {
+    const value = {
+      toFixed(digits: number) {
+        return (1.25).toFixed(digits)
+      },
+      toNumber() {
+        return 1.25
+      },
+    }
+    expect(BigIntUtils.toBigInt(value, 2)).toBe(125n)
+  })
+})
+
+describe('BigIntUtils.multiplyByNumber', () => {
+  it('scales a float multiplier at 18 decimals by default', () => {
+    expect(BigIntUtils.multiplyByNumber(1000n, 1.5)).toBe(1500n)
+    expect(BigIntUtils.multiplyByNumber(1000n, 0.5)).toBe(500n)
+  })
+
+  it('returns 0 when the multiplier is 0', () => {
+    expect(BigIntUtils.multiplyByNumber(1000n, 0)).toBe(0n)
+  })
+})
+
+describe('BigIntUtils.createPercentage', () => {
+  it('divides two numbers directly', () => {
+    expect(BigIntUtils.createPercentage(0.0000000005, 0.0000000025)).toBe(0.2)
+  })
+
+  it('divides bigints through the float scale', () => {
+    expect(BigIntUtils.createPercentage(10n, 100n)).toBe(0.1)
+  })
+})
+
+describe('BigIntUtils.usdToTokenAmount', () => {
+  it('converts a USD notional when the caller passes the USD scale', () => {
+    expect(BigIntUtils.usdToTokenAmount(5, 2, 6, 18)).toBe(2_500_000n)
+  })
+
+  it('handles 18-decimal tokens without a float 1e18 multiply', () => {
+    expect(BigIntUtils.usdToTokenAmount(5, 2500, 18, 18)).toBe(
+      2_000_000_000_000_000n,
+    )
+  })
+
+  it('returns 0 for non-positive inputs', () => {
+    expect(BigIntUtils.usdToTokenAmount(0, 1, 6, 18)).toBe(0n)
+    expect(BigIntUtils.usdToTokenAmount(5, 0, 6, 18)).toBe(0n)
+  })
+})
+
+describe('BigIntUtils.multiplyAsBigInt', () => {
+  it('multiplies at the caller scale and returns a number', () => {
+    expect(BigIntUtils.multiplyAsBigInt(2, 3, 2)).toBe(6)
+  })
+})
+
+describe('BigIntUtils.splitEvenly', () => {
+  it('splits evenly with the remainder absorbed by the last bucket', () => {
+    const buckets = BigIntUtils.splitEvenly(100n, 3)
+    expect(buckets).toEqual([33n, 33n, 34n])
+    expect(buckets.reduce((sum, bucket) => sum + bucket, 0n)).toBe(100n)
+  })
+
+  it('returns [amount] when count is 1', () => {
+    expect(BigIntUtils.splitEvenly(7n, 1)).toEqual([7n])
+  })
+
+  it('throws when count is <= 0', () => {
+    expect(() => BigIntUtils.splitEvenly(10n, 0)).toThrow()
+    expect(() => BigIntUtils.splitEvenly(10n, -1)).toThrow()
+  })
+})
+
+describe('BigIntUtils.splitWithVariance', () => {
+  function makeSeq(values: number[]): () => number {
+    let i = 0
+    return () => values[i++ % values.length] ?? 0
+  }
+
+  it('degenerates to splitEvenly when variance <= 0', () => {
+    const variance0 = BigIntUtils.splitWithVariance(100n, 4, 0)
+    expect(variance0).toEqual(BigIntUtils.splitEvenly(100n, 4))
+
+    const negative = BigIntUtils.splitWithVariance(100n, 4, -0.1)
+    expect(negative).toEqual(BigIntUtils.splitEvenly(100n, 4))
+  })
+
+  it('degenerates to splitEvenly when count is 1', () => {
+    expect(BigIntUtils.splitWithVariance(42n, 1, 0.5)).toEqual([42n])
+  })
+
+  it('degenerates to splitEvenly when amount is 0', () => {
+    expect(BigIntUtils.splitWithVariance(0n, 5, 0.2)).toEqual([
+      0n,
+      0n,
+      0n,
+      0n,
+      0n,
+    ])
+  })
+
+  it('preserves the total sum exactly regardless of variance', () => {
+    const rng = makeSeq([0.0, 1.0, 0.25, 0.75, 0.5])
+    const buckets = BigIntUtils.splitWithVariance(1_000_000n, 5, 0.2, rng)
+    expect(buckets).toHaveLength(5)
+    expect(buckets.reduce((sum, bucket) => sum + bucket, 0n)).toBe(1_000_000n)
+  })
+
+  it('jitters the first N-1 buckets within ±variance of the even base', () => {
+    const rng = makeSeq([0.0, 1.0, 0.0, 1.0])
+    const amount = 1_000_000n
+    const count = 4
+    const variance = 0.2
+    const base = amount / BigInt(count)
+    const buckets = BigIntUtils.splitWithVariance(amount, count, variance, rng)
+
+    expect(buckets[0]).toBe(200_000n)
+    expect(buckets[1]).toBe(300_000n)
+    expect(buckets[2]).toBe(200_000n)
+    expect(buckets[3]).toBe(
+      amount - (buckets[0] ?? 0n) - (buckets[1] ?? 0n) - (buckets[2] ?? 0n),
+    )
+    expect(buckets[3]).toBe(300_000n)
+
+    for (let i = 0; i < count - 1; i++) {
+      const bucket = buckets[i] ?? 0n
+      const expectedMax = (base * 120n) / 100n
+      const expectedMin = (base * 80n) / 100n
+      expect(bucket).toBeGreaterThanOrEqual(expectedMin)
+      expect(bucket).toBeLessThanOrEqual(expectedMax)
+    }
+  })
+
+  it('never produces negative buckets even if the last-bucket drift would go negative', () => {
+    const rng = makeSeq([1.0, 1.0, 1.0, 1.0])
+    const buckets = BigIntUtils.splitWithVariance(100n, 5, 0.5, rng)
+    for (const bucket of buckets) expect(bucket).toBeGreaterThanOrEqual(0n)
+    expect(buckets.reduce((sum, bucket) => sum + bucket, 0n)).toBe(100n)
+  })
+
+  it('throws when count is <= 0', () => {
+    expect(() => BigIntUtils.splitWithVariance(10n, 0, 0.2)).toThrow()
+  })
+})
+
+describe('BigIntUtils.clampToCaps', () => {
+  it('moves overflow onto the bucket with the most headroom', () => {
+    expect(BigIntUtils.clampToCaps([80n, 10n], [50n, 100n])).toEqual([50n, 40n])
+  })
+
+  it('throws when the total cannot fit', () => {
+    expect(() => BigIntUtils.clampToCaps([80n, 30n], [50n, 50n])).toThrow()
+  })
+})