@dfinity/utils

utils-js

A collection of utilities and constants for NNS/SNS projects.

Table of contents

• Installation
• Features

Installation

You can use utils-js by installing it in your project.

npm i @dfinity/utils

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @dfinity/agent @dfinity/candid @dfinity/principal

Features

utils-js implements following features:

:toolbox: Functions

• convertStringToE8s
• isNullish
• nonNullish
• notEmptyString
• defaultAgent
• createAgent
• createServices
• assertNonNullish
• asNonNullish
• assertPercentageNumber
• uint8ArrayToBigInt
• bigIntToUint8Array
• numberToUint8Array
• arrayBufferToUint8Array
• uint8ArrayToArrayOfNumber
• arrayOfNumberToUint8Array
• asciiStringToByteArray
• hexStringToUint8Array
• uint8ArrayToHexString
• candidNatArrayToBigInt
• encodeBase32
• decodeBase32
• bigEndianCrc32
• secondsToDuration
• debounce
• toNullable
• fromNullable
• fromDefinedNullable
• jsonReplacer
• jsonReviver
• principalToSubAccount
• smallerVersion

:gear: convertStringToE8s

Receives a string representing a number and returns the big int or error.

Function	Type
convertStringToE8s	(value: string) => bigint or FromStringToTokenError

Parameters:

• amount: - in string format

:link: Source

:gear: isNullish

Is null or undefined

Function	Type
isNullish	<T>(argument: T or null or undefined) => argument is null or undefined

:link: Source

:gear: nonNullish

Not null and not undefined

Function	Type
nonNullish	<T>(argument: T or null or undefined) => argument is NonNullable<T>

:link: Source

:gear: notEmptyString

Not null and not undefined and not empty

Function	Type
notEmptyString	(value: string or null or undefined) => boolean

:link: Source

:gear: defaultAgent

Get a default agent that connects to mainnet with the anonymous identity.

Function	Type
defaultAgent	() => Agent

:link: Source

:gear: createAgent

Create an agent for a given identity

Function	Type
createAgent	({ identity, host, fetchRootKey, verifyQuerySignatures, retryTimes, }: { identity: Identity; host?: string or undefined; fetchRootKey?: boolean or undefined; verifyQuerySignatures?: boolean or undefined; retryTimes?: number or undefined; }) => Promise<...>

Parameters:

• identity: A mandatory identity to use for the agent
• host: An optional host to connect to
• fetchRootKey: Fetch root key for certificate validation during local development or on testnet
• verifyQuerySignatures: Check for signatures in the state tree signed by the node that replies to queries - i.e. certify responses.
• retryTimes: Set the number of retries the agent should perform before errorring.

:link: Source

:gear: createServices

Function	Type
createServices	<T>({ options: { canisterId, serviceOverride, certifiedServiceOverride, agent: agentOption, callTransform, queryTransform, }, idlFactory, certifiedIdlFactory, }: { options: Required<Pick<CanisterOptions<T>, "canisterId">> and Omit<CanisterOptions<T>, "canisterId"> and Pick<...>; idlFactory: InterfaceFactory; certifiedId...

:link: Source

:gear: assertNonNullish

Function	Type
assertNonNullish	<T>(value: T, message?: string or undefined) => asserts value is NonNullable<T>

:link: Source

:gear: asNonNullish

Function	Type
asNonNullish	<T>(value: T, message?: string or undefined) => NonNullable<T>

:link: Source

:gear: assertPercentageNumber

Function	Type
assertPercentageNumber	(percentage: number) => void

:link: Source

:gear: uint8ArrayToBigInt

Function	Type
uint8ArrayToBigInt	(array: Uint8Array) => bigint

:link: Source

:gear: bigIntToUint8Array

Function	Type
bigIntToUint8Array	(value: bigint) => Uint8Array

:link: Source

:gear: numberToUint8Array

Function	Type
numberToUint8Array	(value: number) => Uint8Array

:link: Source

:gear: arrayBufferToUint8Array

Function	Type
arrayBufferToUint8Array	(buffer: ArrayBuffer) => Uint8Array

:link: Source

:gear: uint8ArrayToArrayOfNumber

Function	Type
uint8ArrayToArrayOfNumber	(array: Uint8Array) => number[]

:link: Source

:gear: arrayOfNumberToUint8Array

Function	Type
arrayOfNumberToUint8Array	(numbers: number[]) => Uint8Array

:link: Source

:gear: asciiStringToByteArray

Function	Type
asciiStringToByteArray	(text: string) => number[]

:link: Source

:gear: hexStringToUint8Array

Function	Type
hexStringToUint8Array	(hexString: string) => Uint8Array

:link: Source

:gear: uint8ArrayToHexString

Function	Type
uint8ArrayToHexString	(bytes: Uint8Array or number[]) => string

:link: Source

:gear: candidNatArrayToBigInt

Function	Type
candidNatArrayToBigInt	([lowPart, highPart]: [number, (number or undefined)?]) => bigint

:link: Source

:gear: encodeBase32

Encode an Uint8Array to a base32 string.

Function	Type
encodeBase32	(input: Uint8Array) => string

Parameters:

• input: The input array to encode.

:link: Source

:gear: decodeBase32

Decode a base32 string to Uint8Array.

Function	Type
decodeBase32	(input: string) => Uint8Array

Parameters:

• input: The input string to decode.
• input: The base32 encoded string to decode.

:link: Source

:gear: bigEndianCrc32

Function	Type
bigEndianCrc32	(bytes: Uint8Array) => Uint8Array

:link: Source

:gear: secondsToDuration

Convert seconds to a human-readable duration, such as "6 days, 10 hours."

Function	Type
secondsToDuration	({ seconds, i18n, }: { seconds: bigint; i18n?: I18nSecondsToDuration or undefined; }) => string

Parameters:

• options: - The options object.
• options.seconds: - The number of seconds to convert.
• options.i18n: - The i18n object for customizing language and units. Defaults to English.

:link: Source

:gear: debounce

Function	Type
debounce	(func: Function, timeout?: number or undefined) => (...args: unknown[]) => void

:link: Source

:gear: toNullable

Function	Type
toNullable	<T>(value?: T or null or undefined) => [] or [T]

:link: Source

:gear: fromNullable

Function	Type
fromNullable	<T>(value: [] or [T]) => T or undefined

:link: Source

:gear: fromDefinedNullable

Function	Type
fromDefinedNullable	<T>(value: [] or [T]) => T

:link: Source

:gear: jsonReplacer

A parser that interprets revived BigInt, Principal, and Uint8Array when constructing JavaScript values or objects.

Function	Type
jsonReplacer	(_key: string, value: unknown) => unknown

:link: Source

:gear: jsonReviver

A function that alters the behavior of the stringification process for BigInt, Principal and Uint8Array.

Function	Type
jsonReviver	(_key: string, value: unknown) => unknown

:link: Source

:gear: principalToSubAccount

Convert a principal to a Uint8Array 32 length. e.g. Useful to convert a canister ID when topping up cycles with the Cmc canister

Function	Type
principalToSubAccount	(principal: Principal) => Uint8Array

Parameters:

• principal: The principal that needs to be converted to Subaccount

:link: Source

:gear: smallerVersion

Returns true if the current version is smaller than the minVersion, false if equal or bigger. Tags after patch version are ignored, e.g. 1.0.0-beta.1 is considered equal to 1.0.0.

Function	Type
smallerVersion	({ minVersion, currentVersion, }: { minVersion: string; currentVersion: string; }) => boolean

Parameters:

• params.minVersion: Ex: "1.0.0"
• params.currentVersion: Ex: "2.0.0"

:link: Source

:wrench: Constants

• E8S_PER_TOKEN
• ICPToken

:gear: E8S_PER_TOKEN

Constant	Type
E8S_PER_TOKEN	bigint

:link: Source

:gear: ICPToken

Constant	Type
ICPToken	Token

:link: Source

:factory: TokenAmount

Deprecated. Use TokenAmountV2 instead which supports decimals !== 8.

Represents an amount of tokens.

:link: Source

Methods

• fromE8s
• fromString
• fromNumber
• toE8s

:gear: fromE8s

Initialize from a bigint. Bigint are considered e8s.

Method	Type
fromE8s	({ amount, token, }: { amount: bigint; token: Token; }) => TokenAmount

Parameters:

• params.amount: The amount in bigint format.
• params.token: The token type.

:link: Source

:gear: fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Method	Type
fromString	({ amount, token, }: { amount: string; token: Token; }) => FromStringToTokenError or TokenAmount

Parameters:

• params.amount: The amount in string format.
• params.token: The token type.

:link: Source

:gear: fromNumber

Initialize from a number.

1 integer is considered E8S_PER_TOKEN

Method	Type
fromNumber	({ amount, token, }: { amount: number; token: Token; }) => TokenAmount

Parameters:

• params.amount: The amount in number format.
• params.token: The token type.

:link: Source

:gear: toE8s

Method	Type
toE8s	() => bigint

:link: Source

:factory: TokenAmountV2

Represents an amount of tokens.

:link: Source

Methods

• fromUlps
• fromString
• fromNumber
• toUlps
• toE8s

:gear: fromUlps

Initialize from a bigint. Bigint are considered ulps.

Method	Type
fromUlps	({ amount, token, }: { amount: bigint; token: Token; }) => TokenAmountV2

Parameters:

• params.amount: The amount in bigint format.
• params.token: The token type.

:link: Source

:gear: fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Method	Type
fromString	({ amount, token, }: { amount: string; token: Token; }) => FromStringToTokenError or TokenAmountV2

Parameters:

• params.amount: The amount in string format.
• params.token: The token type.

:link: Source

:gear: fromNumber

Initialize from a number.

1 integer is considered 10^{token.decimals} ulps

Method	Type
fromNumber	({ amount, token, }: { amount: number; token: Token; }) => TokenAmountV2

Parameters:

• params.amount: The amount in number format.
• params.token: The token type.

:link: Source

:gear: toUlps

Method	Type
toUlps	() => bigint

:link: Source

:gear: toE8s

Method	Type
toE8s	() => bigint

:link: Source

:factory: Canister

:link: Source

:factory: InvalidPercentageError

:link: Source

:factory: NullishError

:link: Source