@bangbu/decimaljs-crypto-extensions

A lightweight, zero-dependency package that extends the decimal.js library with utility functions commonly needed in cryptocurrency applications. It uses monkey-patching to add new methods directly to the Decimal class, making them seamlessly available throughout your project.

Features

• Immutable operations that align with the design principles of decimal.js.
• Adds instance method toBigInt() for easy conversion to JavaScript's native bigint.
• Adds static method formatUnits() for handling token unit conversions, similar to libraries like Ethers.js.

Installation

Install the package and its peer dependency, decimal.js.

npm install decimal.js @bangbu/decimaljs-crypto-extensions

Or using yarn:

yarn add decimal.js @bangbu/decimaljs-crypto-extensions

Usage

You can choose to either import all extensions at once or select only the specific ones you need for your project.

Basic Usage: All-in-One

To activate all extensions, simply import the package once in your application's entry point (e.g., index.ts or main.ts). This single import will apply all available patches to the Decimal class.

1. Apply the patch:

// In your project's main entry file (e.g., index.ts)
import '@bangbu/decimaljs-crypto-extensions';

// That's it! All extensions are now available on the Decimal object.

2. Use the extended methods:

In any other file in your project, you can import Decimal directly from decimal.js as you normally would.

import { Decimal } from 'decimal.js';

// Now you can use the extended methods
const bigNumber = Decimal.formatUnits('123450000000000000000', 18); // 123.45
const asBigInt = new Decimal('98765').toBigInt();

Advanced Usage: Selective Imports

If you only need a specific extension and want to minimize your bundle size, you can import extensions individually. This approach only applies the patch for the feature you import.

Importing toBigInt only:

import '@bangbu/decimaljs-crypto-extensions/extensions/toBigInt';
import { Decimal } from 'decimal.js';

const myNumber = new Decimal('12345');
console.log(myNumber.toBigInt()); // Works!

// Decimal.formatUnits(..); // This would throw a TypeError because it was not imported.

Importing formatUnits only:

import '@bangbu/decimaljs-crypto-extensions/extensions/formatUnits';
import { Decimal } from 'decimal.js';

const formatted = Decimal.formatUnits('123e18', 18);
console.log(formatted.toString()); // Works!

// const d = new Decimal('123');
// d.toBigInt(); // This would throw a TypeError because it was not imported.

API Reference

toBigInt(force?: boolean): bigint

An instance method that converts a Decimal value to a native JavaScript bigint.

• If the Decimal value is a whole number, it converts directly.
• If the Decimal value has fractional parts, it will throw an error to prevent accidental precision loss.
• force (optional boolean, default false): If set to true, it will truncate the decimal part and convert the integer part to a bigint without throwing an error.

Examples:

import { Decimal } from 'decimal.js';

// Simple conversion
const intDecimal = new Decimal('12345678901234567890');
const bigIntValue = intDecimal.toBigInt();
// => 12345678901234567890n

// Throws an error by default for non-integers
const nonIntDecimal = new Decimal('123.45');
try {
  nonIntDecimal.toBigInt();
} catch (e) {
  console.error(e.message); // => "Decimal value is not an integer."
}

// Use `force` to truncate the decimal part
const forcedBigInt = nonIntDecimal.toBigInt(true);
// => 123n

Decimal.formatUnits(value, decimals): Decimal

A static method to convert a value from its smallest unit (e.g., wei) into its standard, human-readable representation (e.g., ether) by dividing it by 10 to the power of decimals.

• value: The amount in its smallest unit. Can be a bigint, string, or number.
• decimals: The number of decimal places the token uses (e.g., 18 for ETH, 6 for USDC).

Examples:

import { Decimal } from 'decimal.js';

// Example 1: Convert an amount of a token with 18 decimals
const tokenAmountInWei = '123450000000000000000'; // Represents 123.45 tokens
const formattedAmount = Decimal.formatUnits(tokenAmountInWei, 18);
console.log(formattedAmount.toString()); // => "123.45"

// Example 2: Convert a BigInt value for a token with 9 decimals
const gweiAmount = 420000000000n;
const formattedGwei = Decimal.formatUnits(gweiAmount, 9);
console.log(formattedGwei.toString()); // => "420"

License

This project is licensed under the MIT License. See the LICENSE file for details.