@solana/fixed-points 6.9.0-canary-20260505230336 → 6.9.0

package/README.md

@@ -151,6 +151,27 @@ decimalFixedPointToString(usdc('42.5'), { padTrailingZeros: true }); // "42.5000
 decimalFixedPointToNumber(usdc('42.5')); // 42.5
 ```
 
+For locale-aware output, pass any `Intl.NumberFormat` instance to `formatDecimalFixedPoint` or `formatBinaryFixedPoint`. The helpers route the raw bigint through string scientific notation so precision is preserved beyond JavaScript's `number` mantissa.
+
+```ts
+const eurc = decimalFixedPoint('unsigned', 64, 6);
+const eurFormatter = new Intl.NumberFormat('de-DE', { currency: 'EUR', style: 'currency' });
+formatDecimalFixedPoint(eurFormatter, eurc('1234.5')); // "1.234,50 €"
+```
+
+The same helper exists for binary fixed-points.
+
+```ts
+const fr = new Intl.NumberFormat('fr-FR', { maximumFractionDigits: 4 });
+formatBinaryFixedPoint(fr, audioSample('0.1')); // "0,1"
+```
+
+To plug a binary fixed-point into a custom formatter, convert it to its exact base-10 representation with `binaryFixedPointToBase10` first. Decimal fixed-points already carry `raw` and `decimals` directly on the value object, so no equivalent helper is needed for them.
+
+```ts
+binaryFixedPointToBase10(audioSample('0.5')); // { raw: 500000000000000n, decimals: 15 }
+```
+
 ## Type guards
 
 The `is*` and `assertIs*` guards narrow an unknown value to a fixed-point. All shape arguments are optional — pass `undefined` for any dimension you don't care about.

package/dist/index.browser.cjs

@@ -390,6 +390,11 @@ function gteBinaryFixedPoint(a, b) {
 }
 
 // src/binary/conversions.ts
+function binaryFixedPointToBase10(value) {
+  const decimals = value.fractionalBits;
+  const raw = decimals === 0 ? value.raw : value.raw * 5n ** BigInt(decimals);
+  return { decimals, raw };
+}
 function toUnsignedBinaryFixedPoint(value) {
   if (value.signedness === "unsigned") {
     return value;
@@ -535,11 +540,14 @@ function formatScaledBigint(raw, decimals, padTrailingZeros) {
 
 // src/binary/formatting.ts
 function binaryFixedPointToString(value, options) {
-  const base10Decimals = value.fractionalBits;
-  const base10Raw = base10Decimals === 0 ? value.raw : value.raw * 5n ** BigInt(base10Decimals);
-  const { decimals, raw } = applyDecimalsOption("binaryFixedPoint", base10Raw, base10Decimals, options);
+  const base10 = binaryFixedPointToBase10(value);
+  const { decimals, raw } = applyDecimalsOption("binaryFixedPoint", base10.raw, base10.decimals, options);
   return formatScaledBigint(raw, decimals, options?.padTrailingZeros ?? false);
 }
+function formatBinaryFixedPoint(formatter, value) {
+  const { decimals, raw } = binaryFixedPointToBase10(value);
+  return formatter.format(`${raw}E-${decimals}`);
+}
 function binaryFixedPointToNumber(value) {
   const { fractionalBits, raw } = value;
   if (fractionalBits === 0) {
@@ -813,6 +821,9 @@ function decimalFixedPointToString(value, options) {
   const { decimals, raw } = applyDecimalsOption("decimalFixedPoint", value.raw, value.decimals, options);
   return formatScaledBigint(raw, decimals, options?.padTrailingZeros ?? false);
 }
+function formatDecimalFixedPoint(formatter, value) {
+  return formatter.format(`${value.raw}E-${value.decimals}`);
+}
 function decimalFixedPointToNumber(value) {
   return Number(value.raw) / 10 ** value.decimals;
 }
@@ -847,6 +858,7 @@ exports.addDecimalFixedPoint = addDecimalFixedPoint;
 exports.assertIsBinaryFixedPoint = assertIsBinaryFixedPoint;
 exports.assertIsDecimalFixedPoint = assertIsDecimalFixedPoint;
 exports.binaryFixedPoint = binaryFixedPoint;
+exports.binaryFixedPointToBase10 = binaryFixedPointToBase10;
 exports.binaryFixedPointToNumber = binaryFixedPointToNumber;
 exports.binaryFixedPointToString = binaryFixedPointToString;
 exports.cmpBinaryFixedPoint = cmpBinaryFixedPoint;
@@ -858,6 +870,8 @@ exports.divideBinaryFixedPoint = divideBinaryFixedPoint;
 exports.divideDecimalFixedPoint = divideDecimalFixedPoint;
 exports.eqBinaryFixedPoint = eqBinaryFixedPoint;
 exports.eqDecimalFixedPoint = eqDecimalFixedPoint;
+exports.formatBinaryFixedPoint = formatBinaryFixedPoint;
+exports.formatDecimalFixedPoint = formatDecimalFixedPoint;
 exports.getBinaryFixedPointCodec = getBinaryFixedPointCodec;
 exports.getBinaryFixedPointDecoder = getBinaryFixedPointDecoder;
 exports.getBinaryFixedPointEncoder = getBinaryFixedPointEncoder;