@dfinity/utils NPM

utils-js

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

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

: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, }: CreateAgentParams) => Promise<HttpAgent>`

Parameters:

params: The parameters to create a new HTTP agent
params.identity: A mandatory identity to use for the agent
params.host: An optional host to connect to, particularly useful for local development
params.fetchRootKey: Fetch root key for certificate validation during local development or on testnet
params.verifyQuerySignatures: Check for signatures in the state tree signed by the node that replies to queries - i.e. certify responses.
params.retryTimes: Set the number of retries the agent should perform before error.

: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: candidNumberArrayToBigInt

Function	Type
`candidNumberArrayToBigInt`	`(array: number[]) => 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

: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

: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

: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: AgentManager

AgentManager class manages HttpAgent instances for different identities.

It caches agents by identity to optimise resource usage and avoid unnecessary agent creation. Provides functionality to create new agents, retrieve cached agents, and clear the cache when needed.

:link: Source

Methods

:gear: create

Static factory method to create a new AgentManager instance.

This method serves as an alternative to directly using the private constructor, making it more convenient to create instances of AgentManager using a simple and clear method.

Method	Type
`create`	`(config: AgentManagerConfig) => AgentManager`

Parameters:

config: - Configuration options for the AgentManager instance.
config.fetchRootKey: - Whether to fetch the root key for certificate validation.
config.host: - The host to connect to.

:link: Source

:gear: getAgent

Get or create an HTTP agent for a given identity.

If the agent for the specified identity has been created and cached, it is retrieved from the cache. If no agent exists for the identity, a new one is created, cached, and then returned.

Method	Type
`getAgent`	`({ identity, }: { identity: Identity; }) => Promise<HttpAgent>`

Parameters:

identity: - The identity to be used to create the agent.

:link: Source

:gear: clearAgents

Clear the cache of HTTP agents.

This method removes all cached agents, forcing new agent creation on the next request for any identity. Useful when identities have changed or if you want to reset all active connections.

utils-js

Table of contents

Installation

Features

:toolbox: Functions

:gear: convertStringToE8s

:gear: isNullish

:gear: nonNullish

:gear: notEmptyString

:gear: defaultAgent

:gear: createAgent

:gear: createServices

:gear: assertNonNullish

:gear: asNonNullish

:gear: assertPercentageNumber

:gear: uint8ArrayToBigInt

:gear: bigIntToUint8Array

:gear: numberToUint8Array

:gear: arrayBufferToUint8Array

:gear: uint8ArrayToArrayOfNumber

:gear: arrayOfNumberToUint8Array

:gear: asciiStringToByteArray

:gear: hexStringToUint8Array

:gear: uint8ArrayToHexString

:gear: candidNumberArrayToBigInt

:gear: encodeBase32

:gear: decodeBase32

:gear: bigEndianCrc32

:gear: secondsToDuration

:gear: debounce

:gear: toNullable

:gear: fromNullable

:gear: fromDefinedNullable

:gear: jsonReplacer

:gear: jsonReviver

:gear: principalToSubAccount

:gear: smallerVersion

:wrench: Constants

:gear: E8S_PER_TOKEN

:gear: ICPToken

:factory: TokenAmount

Methods

:gear: fromE8s

:gear: fromString

:gear: fromNumber

:gear: toE8s

:factory: TokenAmountV2

Methods

:gear: fromUlps

:gear: fromString

:gear: fromNumber

:gear: toUlps

:gear: toE8s

:factory: Canister

:factory: AgentManager

Methods

:gear: create

:gear: getAgent

:gear: clearAgents

:factory: InvalidPercentageError

:factory: NullishError