or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@ethersproject/units

Unit conversion functions for Ethereum, providing high-precision arithmetic for converting between different Ethereum unit denominations (wei, gwei, ether, etc.) and formatting numeric values for display. This package handles values beyond JavaScript's native number range using BigNumber for safe blockchain applications.

Package Information

Package Name: @ethersproject/units
Package Type: npm
Language: TypeScript
Installation: npm install @ethersproject/units

Core Imports

import { 
  formatUnits, 
  parseUnits, 
  formatEther, 
  parseEther, 
  commify 
} from "@ethersproject/units";

For CommonJS:

const { 
  formatUnits, 
  parseUnits, 
  formatEther, 
  parseEther, 
  commify 
} = require("@ethersproject/units");

Basic Usage

import { formatEther, parseEther, formatUnits, parseUnits, commify } from "@ethersproject/units";

// Convert wei to ether for display
const weiValue = "1000000000000000000"; // 1 ETH in wei
const etherValue = formatEther(weiValue);
console.log(etherValue); // "1.0"

// Parse ether string to wei BigNumber
const etherString = "1.5";
const weiBigNumber = parseEther(etherString);
console.log(weiBigNumber.toString()); // "1500000000000000000"

// Format numbers with thousands separators
const largeNumber = "1234567890";
const formatted = commify(largeNumber);
console.log(formatted); // "1,234,567,890"

// Work with different units using names
const gweiValue = parseUnits("21", "gwei");
const gweiFormatted = formatUnits(gweiValue, "gwei");
console.log(gweiFormatted); // "21.0"

// Work with different units using decimal places
const customValue = parseUnits("100", 6); // 6 decimal places (mwei)
const customFormatted = formatUnits(customValue, 6);
console.log(customFormatted); // "100.0"

Architecture

The package provides a simple, focused API for Ethereum unit conversions:

Core Functions: Five primary functions handle parsing and formatting
Unit System: Supports standard Ethereum units from wei (base) to ether (18 decimals)
BigNumber Integration: Uses @ethersproject/bignumber for precision beyond JavaScript's native number limits
Error Handling: Validates inputs and provides clear error messages via @ethersproject/logger
Performance: Lightweight utility functions with minimal dependencies

Capabilities

Unit Conversion - Parse Functions

Convert string representations of Ethereum units into BigNumber objects for arithmetic operations.

/**
 * Parse a string value into a BigNumber with the specified unit denomination
 * @param value - String representation of the value to parse
 * @param unitName - Unit name ("wei", "kwei", "mwei", "gwei", "szabo", "finney", "ether") or decimal places as number
 * @returns BigNumber representation in wei
 */
function parseUnits(value: string, unitName?: BigNumberish): BigNumber;

/**
 * Parse an ether value string into a BigNumber in wei (convenience function for 18 decimal places)
 * @param ether - String representation of ether value
 * @returns BigNumber representation in wei
 */
function parseEther(ether: string): BigNumber;

Unit Conversion - Format Functions

Convert BigNumber values into human-readable string representations with proper unit formatting.

/**
 * Format a BigNumber value into a string representation with the specified unit denomination
 * @param value - BigNumber, string, or number value to format
 * @param unitName - Unit name ("wei", "kwei", "mwei", "gwei", "szabo", "finney", "ether") or decimal places as number
 * @returns String representation of the formatted value
 */
function formatUnits(value: BigNumberish, unitName?: string | BigNumberish): string;

/**
 * Format wei values as ether strings (convenience function for 18 decimal places)
 * @param wei - BigNumber, string, or number value in wei
 * @returns String representation in ether format
 */
function formatEther(wei: BigNumberish): string;

Number Formatting

Format numeric values with thousands separators for improved readability.

/**
 * Add comma separators to numeric strings for display formatting
 * @param value - String or number to format with comma separators
 * @returns Formatted string with comma separators
 */
function commify(value: string | number): string;

Types

// From @ethersproject/bignumber
type BigNumberish = string | number | BigNumber;

class BigNumber {
  // Core BigNumber class for arbitrary precision arithmetic
  // Used as return type for parsing functions and input type for formatting functions
}

Supported Units

The package supports these Ethereum unit names (case-sensitive):

"wei" - Base unit (0 decimal places)
"kwei" - Thousand wei (3 decimal places)
"mwei" - Million wei (6 decimal places)
"gwei" - Giga wei (9 decimal places) - commonly used for gas prices
"szabo" - Micro ether (12 decimal places)
"finney" - Milli ether (15 decimal places)
"ether" - Full ether (18 decimal places)

Unit names can also be specified as numeric values representing decimal places:

// These are equivalent
parseUnits("1", "gwei");
parseUnits("1", 9);

formatUnits(value, "ether"); 
formatUnits(value, 18);

Error Handling

Functions throw ArgumentError for invalid inputs:

parseUnits: Throws if value is not a string
commify: Throws if value format is invalid (invalid numeric format, multiple decimal points)
Unit conversion functions: Validation is delegated to underlying BigNumber functions

Common error scenarios:

try {
  const result = parseUnits(123, "ether"); // Invalid: number instead of string
} catch (error) {
  console.error("ArgumentError: value must be a string");
}

try {
  const formatted = commify("12.34.56"); // Invalid: multiple decimal points
} catch (error) {
  console.error("ArgumentError: invalid value");
}

try {
  const invalid = commify("abc"); // Invalid: non-numeric string
} catch (error) {
  console.error("ArgumentError: invalid value");
}

// Note: Invalid unit names don't throw errors, they fall back to original value or 18 decimals
const result1 = parseUnits("1.0", "invalid"); // Falls back to 18 decimals (ether)
const result2 = parseUnits("1.0", 6); // Uses 6 decimal places
const result3 = formatUnits(result2, "invalid"); // Falls back to original unitName or 18