or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arrays.mdbig-numbers.mdcompact.mddata-conversion.mdformatting.mdindex.mdobjects.mdstrings.mdsystem.mdtype-checking.md
tile.json

tessl/npm-polkadot--util

A collection of useful utilities for @polkadot ecosystem with type checking, data conversion, and performance optimization functions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@polkadot/util@13.5.x

To install, run

npx @tessl/cli install tessl/npm-polkadot--util@13.5.0

index.mddocs/

@polkadot/util

@polkadot/util is a comprehensive TypeScript utility library providing essential functions for the Polkadot ecosystem. It offers type-safe utilities for data conversion, type checking, numeric operations, array manipulation, string processing, and cryptographic helpers designed to reduce boilerplate code in blockchain applications.

Package Information

  • Package Name: @polkadot/util
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @polkadot/util or yarn add @polkadot/util

Core Imports

import { 
  isHex, isU8a, isString, 
  hexToU8a, u8aToHex, 
  BN, bnToBn,
  arrayChunk, objectSpread 
} from "@polkadot/util";

For CommonJS:

const { 
  isHex, isU8a, isString, 
  hexToU8a, u8aToHex, 
  BN, bnToBn,
  arrayChunk, objectSpread 
} = require("@polkadot/util");

Basic Usage

import { isHex, hexToU8a, u8aToHex, BN, formatBalance } from "@polkadot/util";

// Type checking
if (isHex("0x1234abcd")) {
  console.log("Valid hex string");
}

// Data conversion
const bytes = hexToU8a("0x48656c6c6f"); // Convert hex to Uint8Array
const hex = u8aToHex(bytes); // Convert back to hex

// Big number operations
const balance = new BN("1000000000000"); // 1 trillion in smallest units
const formatted = formatBalance(balance, { decimals: 12, withUnit: 'DOT' });

console.log(formatted); // "1.0000 DOT"

Architecture

@polkadot/util is organized into focused modules, each providing specialized functionality:

  • Type System: Comprehensive type checking utilities (is* functions) for runtime validation
  • Data Conversion: Bi-directional conversion between hex strings, Uint8Arrays, numbers, and BigInts
  • Big Number Support: Both native BigInt and BN.js support with utility functions and constants
  • Array Operations: Functional utilities for array manipulation (chunk, flatten, zip, etc.)
  • String Processing: Case conversion, formatting, and encoding utilities
  • Object Utilities: Property manipulation and object transformation helpers
  • System Detection: Environment capability detection for cross-platform compatibility
  • Performance Optimization: Memoization, lazy evaluation, and efficient data structures

Capabilities

Type Checking Utilities

Comprehensive runtime type validation with 28 utility functions for checking data types and formats in JavaScript/TypeScript applications.

function isHex(value: unknown, bitLength?: number, ignoreLength?: boolean): value is HexString;
function isU8a(value: unknown): value is Uint8Array;
function isString(value: unknown): value is string;
function isBn(value: unknown): value is BN;
function isNumber(value: unknown): value is number;

Type Checking

Data Conversion

Bi-directional conversion utilities for transforming data between different formats commonly used in blockchain applications.

function hexToU8a(value?: string | null, bitLength?: number): Uint8Array;
function u8aToHex(value?: Uint8Array | null, bitLength?: number, isPrefixed?: boolean): HexString;
function stringToU8a(value: string): Uint8Array;
function u8aToString(value: Uint8Array): string;

Data Conversion

Big Number Operations

Support for both native BigInt and BN.js big numbers with utility functions, constants, and conversion methods for high-precision arithmetic.

// BigInt utilities
function nToBigInt(value: number | bigint | string): bigint;
function nToHex(value: bigint, bitLength?: number): HexString;

// BN.js utilities  
function bnToBn(value: BN | number | string | bigint | Uint8Array): BN;
function bnToHex(value: BN, bitLength?: number): HexString;

class BN {
  constructor(number: number | string | number[] | Uint8Array | Buffer | BN, base?: number | 'hex', endian?: 'le' | 'be');
}

Big Number Operations

Array Utilities

Functional array manipulation utilities for common operations like chunking, flattening, and data transformation.

function arrayChunk<T>(array: T[], size: number): T[][];
function arrayFlatten<T>(array: (T | T[])[]): T[];
function arrayRange(size: number, startAt?: number): number[];
function arrayZip<T>(...arrays: T[][]): T[][];

Array Utilities

String Processing

String manipulation utilities including case conversion, formatting, and encoding/decoding operations.

function stringCamelCase(value: string): string;
function stringPascalCase(value: string): string;
function stringShorten(value: string, prefixLength?: number, suffixLength?: number): string;
function stringToHex(value: string): HexString;

String Processing

Object Utilities

Object manipulation helpers for property access, copying, and transformation operations.

function objectSpread<T, S>(dest: T, ...sources: S[]): T & S;
function objectCopy<T>(source: T): T;
function objectKeys<T>(value: T): (keyof T)[];
function objectEntries<T>(value: T): [keyof T, T[keyof T]][];

Object Utilities

Formatting and Display

Utilities for formatting numbers, balances, dates, and other data for user display with internationalization support.

function formatBalance(value: BN | bigint | string | number, options?: FormatBalanceOptions): string;
function formatNumber(value: BN | bigint | string | number): string;
function formatDate(date: Date, fmt?: string): string;

interface FormatBalanceOptions {
  decimals?: number;
  forceUnit?: string;
  locale?: string;
  withSi?: boolean;
  withUnit?: boolean | string;
  withZero?: boolean;
}

Formatting

Compact Encoding

SCALE (Simple Concatenated Aggregate Little-Endian) compact encoding and decoding utilities for efficient data serialization.

function compactToU8a(value: BN | bigint | number | string): Uint8Array;
function compactFromU8a(input: Uint8Array): [BN, number];
function compactAddLength(input: Uint8Array): Uint8Array;
function compactStripLength(input: Uint8Array): [Uint8Array, number];

Compact Encoding

System and Environment

Environment detection utilities and system-level helpers for cross-platform compatibility and feature detection.

const hasBigInt: boolean;
const hasBuffer: boolean;
const hasWasm: boolean;

function detectPackage(packageInfo: PackageInfo, path?: string, deps?: PackageInfo[]): void;

System Utilities

Types

type HexString = `0x${string}`;
type U8aLike = number[] | Uint8Array | string;
type AnyString = string | String;

interface Logger {
  debug: (...values: unknown[]) => void;
  error: (...values: unknown[]) => void;
  log: (...values: unknown[]) => void;
  warn: (...values: unknown[]) => void;
}

interface Time {
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  milliseconds: number;
}

interface ToBn {
  toBn(): BN;
}

interface ToBigInt {
  toBigInt(): bigint;
}