@lifi/perps-sdk 23.1.0 → 25.0.0

package/dist/esm/decimal/convert.d.ts

@@ -1,55 +1,63 @@
-import { type DecimalString } from '@lifi/perps-types';
 /**
- * Off-grid resolution for {@link decimalToBaseUnits}:
- * - `truncate` — toward zero, for sizes and collateral amounts. The wire
- *   value never exceeds the caller's intent.
- * - `round` — half away from zero, for prices, which snap to the nearest
- *   tick.
+ * Off-grid resolution for {@link roundDecimalString}:
+ * - `truncate`: toward zero, for sizes and collateral amounts. The result
+ *   never exceeds the caller's intent.
+ * - `round`: half away from zero, for prices, which snap to the nearest tick.
+ * - `up`: away from zero, for an amount that must cover a target.
  * @public
  */
-export type BaseUnitsRounding = 'truncate' | 'round';
+export type DecimalRounding = 'truncate' | 'round' | 'up';
 /**
- * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
- * on-grid input maps to its exact scaled integer with no binary float
- * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
- * per `rounding`; there is no silent default.
+ * Round a decimal string to `decimals` places with exact decimal arithmetic.
+ * The result has no trailing zeros: `roundDecimalString('1.50', 1, 'round')`
+ * is `'1.5'`.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, `decimals` is not a non-negative integer, or the scaled
- *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   or `decimals` is not a non-negative integer.
  * @public
  */
-export declare const decimalToBaseUnits: (value: DecimalString, decimals: number, rounding: BaseUnitsRounding) => number;
+export declare function roundDecimalString(value: string, decimals: number, rounding: DecimalRounding): string;
 /**
- * Convert a base-unit amount (integer string) to a decimal string.
+ * {@link roundDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export declare const safeRoundDecimalString: (value: string, decimals: number, rounding: DecimalRounding) => string | undefined;
+/**
+ * Scale a decimal string to an integer at `decimals` places in exact decimal
+ * arithmetic: `'0.29'` at 2 decimals is 29, never 28. Off-grid input resolves
+ * per `rounding`. No `$`, `%` or `,` is removed first.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   `decimals` is not a non-negative integer, or the result's magnitude
+ *   exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export declare function decimalStringToScaledInteger(value: string, decimals: number, rounding: DecimalRounding): number;
+/**
+ * {@link decimalStringToScaledInteger}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export declare const safeDecimalStringToScaledInteger: (value: string, decimals: number, rounding: DecimalRounding) => number | undefined;
+export declare const BASE_UNITS_PATTERN: RegExp;
+/**
+ * Convert a scaled integer string (a token amount in base units) to a decimal
+ * string: `scaledIntegerToDecimalString('1000000', 6)` is `'1'`.
  *
- * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
- * @param decimals - Token decimals (e.g. 6 for USDC)
  * @throws {PerpsError} `ValidationError` when `amount` is not an integer
  *   string, or `decimals` is not a non-negative integer.
- * @example
- * ```ts
- * baseUnitsToDecimal('1000000', 6) // '1'
- * ```
  * @public
  */
-export declare function baseUnitsToDecimal(amount: DecimalString, decimals: number): DecimalString;
+export declare function scaledIntegerToDecimalString(amount: string, decimals: number): string;
 /**
- * Round `value` down to `decimals` and pad the result to exactly that many
- * decimal places. The padding is the point: this seeds a fixed-decimal input,
- * where `'500.00'` and `'500'` are two renderings of one amount and the field
- * wants the first. For a canonical wire amount with no trailing zeros, read
- * the amount off `calculateOrderAmounts` or a provider snap instead.
- *
- * Exact decimal arithmetic throughout, so there is no 2^53 ceiling and no
- * float artifact: `'0.01'` at 18 decimals gives
- * `'0.010000000000000000'`, which `Number#toFixed` cannot.
+ * {@link scaledIntegerToDecimalString}, or `undefined` with a warning when it
+ * throws.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, or `decimals` is not a non-negative integer.
  * @public
  */
-export declare function truncateDecimal(value: DecimalString, decimals: number): DecimalString;
+export declare const safeScaledIntegerToDecimalString: (amount: string, decimals: number) => string | undefined;
 /**
  * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
  * becomes `'0.0000001'`, never `'1e-7'`. The boundary helper for a venue or
@@ -60,5 +68,11 @@ export declare function truncateDecimal(value: DecimalString, decimals: number):
  * @throws {PerpsError} `ValidationError` when `value` is `NaN` or infinite.
  * @public
  */
-export declare function numberToDecimalString(value: number): DecimalString;
+export declare function numberToDecimalString(value: number): string;
+/**
+ * {@link numberToDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export declare const safeNumberToDecimalString: (value: number) => string | undefined;
 //# sourceMappingURL=convert.d.ts.map

package/dist/esm/decimal/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/decimal/convert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,mBAAmB,CAAA;AAMtE;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,aAAa,EACpB,UAAU,MAAM,EAChB,UAAU,iBAAiB,KAC1B,MAiBF,CAAA;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,GACf,aAAa,CAcf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,GACf,aAAa,CAaf;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CASlE"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/decimal/convert.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAA;AAQzD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,eAAe,GACxB,MAAM,CAUR;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,oFAGlC,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,eAAe,GACxB,MAAM,CAuBR;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,oFAG5C,CAAA;AAED,eAAO,MAAM,kBAAkB,QAAY,CAAA;AAE3C;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,CAcR;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,0DAG5C,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS3D;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uCAGrC,CAAA"}

package/dist/esm/decimal/convert.js

@@ -2,76 +2,92 @@ import { PerpsErrorCode } from '@lifi/perps-types';
 import Big from 'big.js';
 import { formatUnits } from 'viem';
 import { PerpsError } from '../errors/PerpsError.js';
-import { requireDecimal } from './requireDecimal.js';
+import { createSafeFunction } from '../utils/createSafeFunction.js';
+import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js';
+import { isDecimalString } from './parse.js';
+const BIG_ROUNDING = {
+    truncate: Big.roundDown,
+    round: Big.roundHalfUp,
+    up: Big.roundUp,
+};
+/**
+ * Round a decimal string to `decimals` places with exact decimal arithmetic.
+ * The result has no trailing zeros: `roundDecimalString('1.50', 1, 'round')`
+ * is `'1.5'`.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   or `decimals` is not a non-negative integer.
+ * @public
+ */
+export function roundDecimalString(value, decimals, rounding) {
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid decimals for rounding: ${decimals}`);
+    }
+    return bigToDecimalString(decimalStringToBig(value).round(decimals, BIG_ROUNDING[rounding]));
+}
 /**
- * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
- * on-grid input maps to its exact scaled integer with no binary float
- * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
- * per `rounding`; there is no silent default.
+ * {@link roundDecimalString}, or `undefined` with a warning when it throws.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, `decimals` is not a non-negative integer, or the scaled
- *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
  * @public
  */
-export const decimalToBaseUnits = (value, decimals, rounding) => {
+export const safeRoundDecimalString = createSafeFunction('roundDecimalString', roundDecimalString);
+/**
+ * Scale a decimal string to an integer at `decimals` places in exact decimal
+ * arithmetic: `'0.29'` at 2 decimals is 29, never 28. Off-grid input resolves
+ * per `rounding`. No `$`, `%` or `,` is removed first.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   `decimals` is not a non-negative integer, or the result's magnitude
+ *   exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export function decimalStringToScaledInteger(value, decimals, rounding) {
+    if (!isDecimalString(value)) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `'${value}' does not match the decimal pattern.`);
+    }
     if (!Number.isInteger(decimals) || decimals < 0) {
         throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid decimals for integer scaling: ${decimals}`);
     }
-    const scaled = requireDecimal(value, 'decimalToBaseUnits(value)')
+    const scaled = new Big(value)
         .times(new Big(10).pow(decimals))
-        .round(0, rounding === 'truncate' ? Big.roundDown : Big.roundHalfUp);
+        .round(0, BIG_ROUNDING[rounding]);
     if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
         throw new PerpsError(PerpsErrorCode.ValidationError, `Scaled value ${scaled.toFixed()} exceeds Number.MAX_SAFE_INTEGER and cannot be encoded exactly.`);
     }
     return scaled.toNumber();
-};
-const BASE_UNITS_PATTERN = /^-?\d+$/;
+}
 /**
- * Convert a base-unit amount (integer string) to a decimal string.
+ * {@link decimalStringToScaledInteger}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeDecimalStringToScaledInteger = createSafeFunction('decimalStringToScaledInteger', decimalStringToScaledInteger);
+export const BASE_UNITS_PATTERN = /^-?\d+$/;
+/**
+ * Convert a scaled integer string (a token amount in base units) to a decimal
+ * string: `scaledIntegerToDecimalString('1000000', 6)` is `'1'`.
  *
- * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
- * @param decimals - Token decimals (e.g. 6 for USDC)
  * @throws {PerpsError} `ValidationError` when `amount` is not an integer
  *   string, or `decimals` is not a non-negative integer.
- * @example
- * ```ts
- * baseUnitsToDecimal('1000000', 6) // '1'
- * ```
  * @public
  */
-export function baseUnitsToDecimal(amount, decimals) {
+export function scaledIntegerToDecimalString(amount, decimals) {
     if (!Number.isInteger(decimals) || decimals < 0) {
-        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid \`baseUnitsToDecimal(decimals)\`: ${decimals} is not a non-negative integer.`);
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid \`scaledIntegerToDecimalString(decimals)\`: ${decimals} is not a non-negative integer.`);
     }
     if (!BASE_UNITS_PATTERN.test(amount)) {
-        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid \`baseUnitsToDecimal(amount)\`: '${amount}' is not an integer base-unit string.`);
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid \`scaledIntegerToDecimalString(amount)\`: '${amount}' is not an integer base-unit string.`);
     }
     return formatUnits(BigInt(amount), decimals);
 }
 /**
- * Round `value` down to `decimals` and pad the result to exactly that many
- * decimal places. The padding is the point: this seeds a fixed-decimal input,
- * where `'500.00'` and `'500'` are two renderings of one amount and the field
- * wants the first. For a canonical wire amount with no trailing zeros, read
- * the amount off `calculateOrderAmounts` or a provider snap instead.
- *
- * Exact decimal arithmetic throughout, so there is no 2^53 ceiling and no
- * float artifact: `'0.01'` at 18 decimals gives
- * `'0.010000000000000000'`, which `Number#toFixed` cannot.
+ * {@link scaledIntegerToDecimalString}, or `undefined` with a warning when it
+ * throws.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, or `decimals` is not a non-negative integer.
  * @public
  */
-export function truncateDecimal(value, decimals) {
-    if (!Number.isInteger(decimals) || decimals < 0) {
-        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid decimals for truncation: ${decimals}`);
-    }
-    const truncated = requireDecimal(value, 'truncateDecimal(value)').round(decimals, Big.roundDown);
-    // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
-    return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals);
-}
+export const safeScaledIntegerToDecimalString = createSafeFunction('scaledIntegerToDecimalString', scaledIntegerToDecimalString);
 /**
  * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
  * becomes `'0.0000001'`, never `'1e-7'`. The boundary helper for a venue or
@@ -89,4 +105,10 @@ export function numberToDecimalString(value) {
     const parsed = new Big(value);
     return (parsed.eq(0) ? new Big(0) : parsed).toFixed();
 }
+/**
+ * {@link numberToDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeNumberToDecimalString = createSafeFunction('numberToDecimalString', numberToDecimalString);
 //# sourceMappingURL=convert.js.map

package/dist/esm/decimal/convert.js.map

@@ -1 +1 @@
-{"version":3,"file":"convert.js","sourceRoot":"","sources":["../../../src/decimal/convert.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"convert.js","sourceRoot":"","sources":["../../../src/decimal/convert.ts"],"names":[],"mappings":"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"}

package/dist/esm/decimal/decimalStringToBig.d.ts

@@ -0,0 +1,25 @@
+import Big from 'big.js';
+/**
+ * Read a decimal string as a `Big`. The string must match `DECIMAL_PATTERN`,
+ * so `'$1,234.5'`, `'0.05%'` and the exponent form `'1e5'` are rejected.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the
+ *   decimal pattern.
+ * @internal
+ */
+export declare function decimalStringToBig(value: string): Big;
+/**
+ * Spell a `Big` as a canonical decimal string, with no exponent and no `-0`.
+ *
+ * @internal
+ */
+export declare function bigToDecimalString(value: Big): string;
+/**
+ * {@link decimalStringToBig} as a `DivBig`, so a later `div` keeps 40 decimal
+ * places.
+ *
+ * @throws {PerpsError} `ValidationError` as {@link decimalStringToBig}.
+ * @internal
+ */
+export declare function decimalStringToDivBig(value: string): Big;
+//# sourceMappingURL=decimalStringToBig.d.ts.map

package/dist/esm/decimal/decimalStringToBig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimalStringToBig.d.ts","sourceRoot":"","sources":["../../../src/decimal/decimalStringToBig.ts"],"names":[],"mappings":"AACA,OAAO,GAAG,MAAM,QAAQ,CAAA;AAIxB;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAQrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAExD"}

package/dist/esm/decimal/decimalStringToBig.js

@@ -0,0 +1,37 @@
+import { DECIMAL_PATTERN, PerpsErrorCode } from '@lifi/perps-types';
+import Big from 'big.js';
+import { PerpsError } from '../errors/PerpsError.js';
+import { DivBig } from './big.js';
+/**
+ * Read a decimal string as a `Big`. The string must match `DECIMAL_PATTERN`,
+ * so `'$1,234.5'`, `'0.05%'` and the exponent form `'1e5'` are rejected.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the
+ *   decimal pattern.
+ * @internal
+ */
+export function decimalStringToBig(value) {
+    if (typeof value !== 'string' || !DECIMAL_PATTERN.test(value)) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `'${String(value)}' does not match the decimal pattern.`);
+    }
+    return new Big(value);
+}
+/**
+ * Spell a `Big` as a canonical decimal string, with no exponent and no `-0`.
+ *
+ * @internal
+ */
+export function bigToDecimalString(value) {
+    return value.eq(0) ? '0' : value.toFixed();
+}
+/**
+ * {@link decimalStringToBig} as a `DivBig`, so a later `div` keeps 40 decimal
+ * places.
+ *
+ * @throws {PerpsError} `ValidationError` as {@link decimalStringToBig}.
+ * @internal
+ */
+export function decimalStringToDivBig(value) {
+    return new DivBig(decimalStringToBig(value));
+}
+//# sourceMappingURL=decimalStringToBig.js.map

package/dist/esm/decimal/decimalStringToBig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimalStringToBig.js","sourceRoot":"","sources":["../../../src/decimal/decimalStringToBig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,GAAG,MAAM,QAAQ,CAAA;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,uCAAuC,CACzD,CAAA;IACH,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAU;IAC3C,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAA;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,OAAO,IAAI,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAA;AAC9C,CAAC"}

package/dist/esm/decimal/format.d.ts

@@ -7,7 +7,10 @@ import type { DecimalString } from '@lifi/perps-types';
 export interface FormatOptions {
     /** Fixed number of decimal places. Defaults are per-formatter. */
     decimals?: number;
-    /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+    /**
+     * Rendered when the value is null, undefined, blank or a non-finite number.
+     * A string that is not a decimal is shown unchanged. Defaults to `'—'`.
+     */
     placeholder?: string;
     /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
     locale?: string;

package/dist/esm/decimal/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/decimal/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAA;AAI7C,KAAK,WAAW,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AA6FrE;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAaR;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAaR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAqBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkBR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/decimal/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAItD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAA;AAI7C,KAAK,WAAW,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AA+ErE;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAgBR;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAgBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAwBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAqBR"}

package/dist/esm/decimal/format.js

@@ -1,66 +1,49 @@
+import Big from 'big.js';
+import { decimalStringToBig } from './decimalStringToBig.js';
 const DEFAULT_PLACEHOLDER = '—';
 /**
- * Extra decimal places used to normalise IEEE-754 representation noise before
- * truncating. `toFixed` at this higher precision cleans values like
- * `0.28999999…` back to `0.29`; truncation then chops the guard digits.
+ * Read a display input as a `Big`. `null` means the formatter renders the
+ * placeholder; a string that does not match the decimal pattern is returned
+ * unchanged for display.
  */
-const FLOAT_GUARD_DIGITS = 9;
-/**
- * Tolerantly coerce a display input to a finite number.
- *
- * Strips `$`, `,`, and surrounding whitespace from strings. Returns `null`
- * when the value is null/undefined/blank or does not resolve to a finite
- * number, so callers can render a placeholder instead of `$0.00` or `$NaN`.
- */
-function toFiniteNumber(value) {
-    let n;
-    if (typeof value === 'string') {
-        const cleaned = value.replace(/[$,\s]/g, '');
-        if (!cleaned) {
-            return null;
-        }
-        n = Number(cleaned);
-    }
-    else if (typeof value === 'number') {
-        n = value;
-    }
-    else {
+function toBig(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? new Big(value) : null;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
         return null;
     }
-    return Number.isFinite(n) ? n : null;
+    try {
+        return decimalStringToBig(value);
+    }
+    catch {
+        return value;
+    }
 }
-/**
- * Truncate a non-negative value toward zero to `decimals` places using its
- * decimal string, never float scaling. Representation noise is first
- * normalised by `toFixed` at {@link FLOAT_GUARD_DIGITS} extra precision, then
- * the guard digits are chopped: `99.999` at 2dp → `99.99`, `0.29` → `0.29`.
- */
-function truncateAbs(abs, decimals) {
-    // `toFixed` emits exponent notation at >= 1e21; every double that large is an integer.
-    if (Number.isInteger(abs)) {
-        return abs;
-    }
-    const s = abs.toFixed(Math.min(decimals + FLOAT_GUARD_DIGITS, 100));
-    const dot = s.indexOf('.');
-    const cut = decimals === 0 ? dot : dot + 1 + decimals;
-    return Number(s.slice(0, cut));
+function decimalSeparator(locale) {
+    return (new Intl.NumberFormat(locale)
+        .formatToParts(1.5)
+        .find((part) => part.type === 'decimal')?.value ?? '.');
 }
 /**
- * Reduce `n` to `decimals` places then split into a sign and the
+ * Reduce `value` to `decimals` places then split into a sign and the
  * locale-formatted absolute body. The sign is derived from the reduced value
  * so magnitudes that collapse to zero render without a spurious `-`/`+`.
  * `signed` emits `+` for positives; `rounding` selects half-up or truncation.
  */
-function signAndBody(n, decimals, locale, grouping, rounding, signed) {
-    const reduced = rounding === 'floor'
-        ? (n < 0 ? -1 : 1) * truncateAbs(Math.abs(n), decimals)
-        : Number(n.toFixed(decimals));
-    const sign = reduced < 0 ? '-' : signed && reduced > 0 ? '+' : '';
-    const body = Math.abs(reduced).toLocaleString(locale, {
-        minimumFractionDigits: decimals,
-        maximumFractionDigits: decimals,
-        useGrouping: grouping,
-    });
+function signAndBody(value, decimals, locale, grouping, rounding, signed) {
+    const reduced = value.round(decimals, rounding === 'floor' ? Big.roundDown : Big.roundHalfUp);
+    const sign = reduced.lt(0) ? '-' : signed && reduced.gt(0) ? '+' : '';
+    const [integerPart = '0', fractionPart] = reduced
+        .abs()
+        .toFixed(decimals)
+        .split('.');
+    const integerBody = grouping
+        ? BigInt(integerPart).toLocaleString(locale)
+        : integerPart;
+    const body = fractionPart === undefined
+        ? integerBody
+        : `${integerBody}${decimalSeparator(locale)}${fractionPart}`;
     return { sign, body };
 }
 /**
@@ -68,13 +51,13 @@ function signAndBody(n, decimals, locale, grouping, rounding, signed) {
  * `>=1` → 2, `>=0.1` → 4, `>=0.01` → 5, otherwise 6.
  */
 function autoDecimals(abs) {
-    if (abs >= 1) {
+    if (abs.gte(1)) {
         return 2;
     }
-    if (abs >= 0.1) {
+    if (abs.gte('0.1')) {
         return 4;
     }
-    if (abs >= 0.01) {
+    if (abs.gte('0.01')) {
         return 5;
     }
     return 6;
@@ -93,10 +76,13 @@ function autoDecimals(abs) {
  */
 export function formatNumber(value, options = {}) {
     const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale, rounding = 'halfUp', } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
+    if (typeof n === 'string') {
+        return n;
+    }
     const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false);
     return `${sign}${body}`;
 }
@@ -110,10 +96,13 @@ export function formatNumber(value, options = {}) {
  */
 export function formatUsd(value, options = {}) {
     const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale, rounding = 'halfUp', } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
+    if (typeof n === 'string') {
+        return n;
+    }
     const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false);
     return `${sign}$${body}`;
 }
@@ -128,10 +117,13 @@ export function formatUsd(value, options = {}) {
  */
 export function formatSignedUsd(value, options = {}) {
     const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale, rounding = 'halfUp', } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
+    if (typeof n === 'string') {
+        return n;
+    }
     const { sign, body } = signAndBody(n, decimals, locale, true, rounding, true);
     return `${sign}$${body}`;
 }
@@ -146,10 +138,13 @@ export function formatSignedUsd(value, options = {}) {
  */
 export function formatSignedPercent(value, options = {}) {
     const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale, rounding = 'halfUp', } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
+    if (typeof n === 'string') {
+        return n;
+    }
     const { sign, body } = signAndBody(n, decimals, locale, false, rounding, true);
     return `${sign}${body}%`;
 }
@@ -165,13 +160,16 @@ export function formatSignedPercent(value, options = {}) {
  */
 export function formatPrice(value, options = {}) {
     const { placeholder = DEFAULT_PLACEHOLDER, locale, rounding = 'halfUp', } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
-    const abs = Math.abs(n);
+    if (typeof n === 'string') {
+        return n;
+    }
+    const abs = n.abs();
     const decimals = options.decimals ?? autoDecimals(abs);
-    const { sign, body } = signAndBody(n, decimals, locale, abs >= 1000, rounding, false);
+    const { sign, body } = signAndBody(n, decimals, locale, abs.gte(1000), rounding, false);
     return `${sign}$${body}`;
 }
 /**
@@ -185,20 +183,23 @@ export function formatPrice(value, options = {}) {
  */
 export function formatCompactUsd(value, options = {}) {
     const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options;
-    const n = toFiniteNumber(value);
+    const n = toBig(value);
     if (n === null) {
         return placeholder;
     }
-    const sign = n < 0 ? '-' : '';
-    const abs = Math.abs(n);
-    if (abs >= 1_000_000_000) {
-        return `${sign}$${(abs / 1_000_000_000).toFixed(decimals)}B`;
+    if (typeof n === 'string') {
+        return n;
+    }
+    const sign = n.lt(0) ? '-' : '';
+    const abs = n.abs();
+    if (abs.gte(1_000_000_000)) {
+        return `${sign}$${abs.div(1_000_000_000).toFixed(decimals)}B`;
     }
-    if (abs >= 1_000_000) {
-        return `${sign}$${(abs / 1_000_000).toFixed(decimals)}M`;
+    if (abs.gte(1_000_000)) {
+        return `${sign}$${abs.div(1_000_000).toFixed(decimals)}M`;
     }
-    if (abs >= 1_000) {
-        return `${sign}$${(abs / 1_000).toFixed(decimals)}K`;
+    if (abs.gte(1_000)) {
+        return `${sign}$${abs.div(1_000).toFixed(decimals)}K`;
     }
     return `${sign}$${abs.toFixed(decimals)}`;
 }