❤
npm
Sign UpSign In

@dfinity/utils
TypeScript icon, indicating that this package has built-in type declarations

2.3.0 • Public • Published

utils-js

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

npm version GitHub license

Table of contents

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:

🧰 Functions

⚙️ 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

🔗 Source

⚙️ isNullish

Is null or undefined

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

🔗 Source

⚙️ nonNullish

Not null and not undefined

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

🔗 Source

⚙️ notEmptyString

Not null and not undefined and not empty

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

🔗 Source

⚙️ defaultAgent

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

Function Type
defaultAgent () => Agent

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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...

🔗 Source

⚙️ assertNonNullish

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

🔗 Source

⚙️ assertPercentageNumber

Function Type
assertPercentageNumber (percentage: number) => void

🔗 Source

⚙️ uint8ArrayToBigInt

Function Type
uint8ArrayToBigInt (array: Uint8Array) => bigint

🔗 Source

⚙️ bigIntToUint8Array

Function Type
bigIntToUint8Array (value: bigint) => Uint8Array

🔗 Source

⚙️ numberToUint8Array

Function Type
numberToUint8Array (value: number) => Uint8Array

🔗 Source

⚙️ arrayBufferToUint8Array

Function Type
arrayBufferToUint8Array (buffer: ArrayBuffer) => Uint8Array

🔗 Source

⚙️ uint8ArrayToArrayOfNumber

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

🔗 Source

⚙️ arrayOfNumberToUint8Array

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

🔗 Source

⚙️ asciiStringToByteArray

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

🔗 Source

⚙️ hexStringToUint8Array

Function Type
hexStringToUint8Array (hexString: string) => Uint8Array

🔗 Source

⚙️ uint8ArrayToHexString

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

🔗 Source

⚙️ encodeBase32

Encode an Uint8Array to a base32 string.

Function Type
encodeBase32 (input: Uint8Array) => string

Parameters:

  • input: The input array to encode.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ bigEndianCrc32

Function Type
bigEndianCrc32 (bytes: Uint8Array) => Uint8Array

🔗 Source

⚙️ 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.

🔗 Source

⚙️ debounce

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

🔗 Source

⚙️ toNullable

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

🔗 Source

⚙️ fromNullable

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

🔗 Source

⚙️ fromDefinedNullable

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

🔗 Source

⚙️ jsonReplacer

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

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

🔗 Source

⚙️ jsonReviver

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

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

🔗 Source

⚙️ 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

🔗 Source

⚙️ 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"

🔗 Source

🔧 Constants

⚙️ E8S_PER_TOKEN

Constant Type
E8S_PER_TOKEN bigint

🔗 Source

⚙️ ICPToken

Constant Type
ICPToken Token

🔗 Source

🏭 TokenAmount

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

Represents an amount of tokens.

🔗 Source

Methods

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ toE8s
Method Type
toE8s () => bigint

🔗 Source

🏭 TokenAmountV2

Represents an amount of tokens.

🔗 Source

Methods

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ toUlps
Method Type
toUlps () => bigint

🔗 Source

⚙️ toE8s
Method Type
toE8s () => bigint

🔗 Source

🏭 Canister

🔗 Source

🏭 InvalidPercentageError

🔗 Source

🏭 NullishError

🔗 Source

Readme

Keywords

Package Sidebar

Install

npm i @dfinity/utils

Repository

github.com/dfinity/ic-js

Homepage

github.com/dfinity/ic-js#readme

Weekly Downloads

6,380

Version

2.3.0

License

Apache-2.0

Unpacked Size

159 kB

Total Files

30

Last publish

Collaborators

  • dfx-json
  • dfn_wndlng
  • nathan.mcgrath.dfinity
  • frederikrothenberger
  • bitdivine
  • ielashi
  • dayyildiz
  • eric-swanson-dfinity
  • krpeacock
  • npm-dfinity-org
Try on RunKit
Report malware