@layerzerolabs/lz-utilities 2.3.41 → 2.3.43

package/dist/index.d.ts

@@ -39,6 +39,7 @@ interface Deployment {
 }
 /**
  * Find the matching deployments based on the given options
+ * @todo Use Partial<EndpointSpec> instead of options
  * @param deployments list of deployments
  * @param nameOrAddress contract name
  * @param options options to match against
@@ -49,8 +50,14 @@ declare function findDeployment(deployments: Deployment[], nameOrAddress: string
     source?: string;
     network?: Network;
     endpointId?: EndpointId;
-}): Deployment | undefined;
+}): Deployment;
 declare function deploymentToEvmContract<T extends ethers.Contract>(deployment: Deployment, provider?: ethers.providers.Provider): T;
+declare function findContract<T extends ethers.Contract>(provider: ethers.providers.Provider | undefined, deployments: Deployment[], nameOrAddress: string, options: {
+    chain?: Chain;
+    source?: string;
+    network?: Network;
+    endpointId?: EndpointId;
+}): T;
 
 /**
  * A function to return dirname of a path
@@ -131,20 +138,43 @@ declare const firstFactory: <TInput extends unknown[], TOutput>(...factories: Fa
  */
 type NonPromise<T> = T extends Promise<unknown> ? never : T;
 
-type RequiredOnly<T> = {
-    [K in keyof T as Required<T>[K] extends NonNullable<Required<T>[K]> ? K : never]: T[K];
-};
 /**
- * Make some properties in T required
+ * Type representing a hexadecimal string prefixed with '0x'.
  */
-type AtLeast<T, K extends keyof T> = Partial<T> & RequiredOnly<T> & Required<Pick<T, K>>;
+type Hex = `0x${string}`;
 /**
- * RequireAtLeastOne helps create a type where at least one of the properties of an interface (can be any property) is required to exist.
- * https://learn.microsoft.com/en-us/javascript/api/@azure/keyvault-certificates/requireatleastone?view=azure-node-latest
+ * Type representing a hash string prefixed with '0x'.
  */
-type RequireAtLeastOne<T> = {
-    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
-}[keyof T];
+type Hash = `0x${string}`;
+/**
+ * Checks if a given string is a valid hexadecimal string.
+ * @param value - The string to check.
+ * @returns True if the string is a valid hexadecimal string, false otherwise.
+ */
+declare function isHex(value: string): value is Hex;
+/**
+ * Checks if a given string is a valid hash string.
+ * @param value - The string to check.
+ * @returns True if the string is a valid hash string, false otherwise.
+ */
+declare function isHash(value: string): value is Hash;
+/**
+ * Represents a byte array.
+ */
+type Bytes = Uint8Array;
+
+declare function assert(condition: boolean, message?: string): asserts condition;
+/**
+ * assertType
+ * assertType can be used to assert that a value is of a certain type, and without naming a new variable explicitly.
+ * @param value
+ * @param fn
+ * @param message
+ */
+declare function assertType<T, M>(value: T, fn: (v: unknown) => v is M, message?: string): asserts value is T & M;
+declare function assertDefined<T>(value?: T, message?: string): asserts value is NonNullable<T>;
+declare function asType<T, M>(value: T, fn: (v: unknown) => v is M, message?: string): M;
+declare function assumeType<T>(value: unknown): asserts value is T;
 
 /**
  * Calls a defined callback function on each element of an array, and returns an array that contains the results.
@@ -153,15 +183,71 @@ type RequireAtLeastOne<T> = {
  */
 declare function safeMap<T, R>(elements: T[], callbackfn: (item: T, index: number) => R): [R[], Error | undefined];
 
+/**
+ * Converts a string or number value to a corresponding enum value.
+ * @param enumType - The enum object.
+ * @param value - The value to convert.
+ * @returns The converted enum value.
+ * @throws Error if the value is not a valid enum value.
+ * @example
+ * // Usage
+ * enum Color {
+ *   Red = 'red',
+ *   Green = 'green',
+ *   Blue = 'blue'
+ * }
+ *
+ * const color: Color = asEnum(Color, 'red');
+ * expect(color).toBe(Color.Red);
+ *
+ * enum Direction {
+ *  Up = 1,
+ *  Down,
+ * }
+ *
+ * const direction: Direction = asEnum(Direction, 1);
+ * expect(direction).toBe(Direction.Up);
+ */
+declare function asEnum<T extends object>(enumType: T, value: string | number): T[keyof T];
+
+interface PadOptions {
+    dir?: 'left' | 'right' | undefined;
+    size?: number | null | undefined;
+}
+type PadReturnType<value extends Bytes | Hex> = value extends Hex ? Hex : Bytes;
+type SizeExceedsPaddingSizeErrorType = SizeExceedsPaddingSizeError & {
+    name: 'SizeExceedsPaddingSizeError';
+};
+declare class SizeExceedsPaddingSizeError extends Error {
+    name: string;
+    constructor({ size, targetSize, type }: {
+        size: number;
+        targetSize: number;
+        type: 'hex' | 'bytes';
+    });
+}
+/**
+ * Pads a hexadecimal string or byte array to a specified size.
+ *
+ * @param hexOrBytes - The hexadecimal string or byte array to pad.
+ * @param options - The padding options.
+ * @param options.dir - The direction of the padding. Defaults to undefined.
+ * @param options.size - The size to pad to. Defaults to 32.
+ * @returns The padded hexadecimal string or byte array.
+ */
+declare function padify<value extends Bytes | Hex>(hexOrBytes: value, { dir, size }?: PadOptions): PadReturnType<value>;
+
 /**
  * A function to convert Uint8Array to hex string
+ * @deprecated use `hexlify` instead
  * @param bytes Uint8Array
- * @returns hex string
+ * @returns hex string without 0x prefix, e.g., '0102030405'
  */
 declare function bytesToHex(bytes: Uint8Array): string;
 /**
  * A function to convert hex string to Uint8Array
- * @param hex hex string
+ * @deprecated use `arrayify` instead
+ * @param hex hex string, e.g., '0x0102030405' or '0102030405'
  * @returns Uint8Array
  */
 declare function hexToBytes(hex: string): Uint8Array;
@@ -176,13 +262,196 @@ declare function trim0x(hex: string): string;
  * @param hex hex string
  * @returns hex string with 0x prefix
  */
-declare function ensure0x(hex: string): string;
+declare function ensure0x(hex: string): Hex;
 /**
  * A function to check if a string is a hex string
+ * @deprecated use `isHex` instead
  * @param value
  * @returns
  */
 declare function isHexString(value: string): boolean;
+/**
+ * A function to convert a string|number|Uint8Array|Buffer|BigInt to Uint8Array
+ * @param value - the value to convert
+ * @param size - the size of the Uint8Array to return, if not specified, the size of the input will be returned
+ */
+declare function arrayify(value: string | number | Uint8Array | Buffer | bigint, size?: number): Uint8Array;
+/**
+ * A function to convert a string|number|Uint8Array|Buffer|BigInt to hex string
+ */
+declare function hexlify(value: string | number | Uint8Array | Buffer | bigint): Hex;
+
+/**
+ * Represents a type that allows partial modification of all properties in a given object type.
+ * This type is similar to the built-in `Partial` type in TypeScript.
+ * However, it supports deep partial modification, allowing partial modification of nested object properties.
+ *
+ * @typeparam T - The object type to be partially modified.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Represents a type that makes all properties of the given type required deeply.
+ *
+ * This utility type recursively makes all properties of the given type required, including nested properties.
+ * If a property is already required, it remains unchanged.
+ *
+ * @typeParam T - The type to make all properties required.
+ * @returns A new type with all properties required.
+ *
+ * @example
+ * ```typescript
+ * type Person = {
+ *     name?: string;
+ *     age?: number;
+ *     address?: {
+ *         street?: string;
+ *         city?: string;
+ *     };
+ * };
+ *
+ * type RequiredPerson = DeepRequired<Person>;
+ * // Result: {
+ * //     name: string;
+ * //     age: number;
+ * //     address: {
+ * //         street: string;
+ * //         city: string;
+ * //     };
+ * // }
+ * ```
+ */
+type DeepRequired<T> = {
+    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+/**
+ * Checks if an object has all the required properties specified by the given paths.
+ *
+ * @template T - The type of the object.
+ * @param {DeepPartial<T>} obj - The object to check.
+ * @param {string[]} paths - The paths of the required properties.
+ * @returns {boolean} - Returns true if the object has all the required properties, otherwise returns false.
+ */
+declare function hasRequiredProperties<T>(obj: DeepPartial<T>, paths: string[]): boolean;
+/**
+ * Retrieves the nested keys of an object type.
+ *
+ * @typeParam T - The object type.
+ * @returns The union of all nested keys in the object type.
+ *
+ * @example
+ * // Given the following object type:
+ * type Person = {
+ *   name: string;
+ *   age: number;
+ *   address: {
+ *     street: string;
+ *     city: string;
+ *   };
+ * };
+ *
+ * // The `NestedKeys` type will return the following union type:
+ * // "name" | "age" | "address" | "address.street" | "address.city"
+ * type AllKeys = NestedKeys<Person>;
+ */
+type NestedKeys<T> = {
+    [K in keyof T]: T[K] extends object ? K | `${K & string}.${NestedKeys<T[K]> & string}` : K;
+}[keyof T];
+/**
+ * Creates a new type that includes only the properties from the input type `T` that are required and not nullable.
+ *
+ * @typeParam T - The input type.
+ * @returns A new type that includes only the required and non-nullable properties from `T`.
+ *
+ * @example
+ * // Define a type with optional and nullable properties
+ * type Person = {
+ *     name?: string;
+ *     age?: number | null;
+ *     email: string;
+ * };
+ *
+ * // Create a new type with only the required and non-nullable properties from `Person`
+ * type RequiredPerson = RequiredOnly<Person>;
+ *
+ * // `RequiredPerson` will be:
+ * // {
+ * //     email: string;
+ * // }
+ */
+type RequiredOnly<T> = {
+    [K in keyof T as Required<T>[K] extends NonNullable<Required<T>[K]> ? K : never]: T[K];
+};
+/**
+ * `AtLeast` ensures that at least the specified keys `K` of the type `T` are required,
+ * while the rest of the properties are optional.
+ *
+ * @template T - The original type.
+ * @template K - The keys of `T` that should be required.
+ *
+ * @example
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email?: string;
+ *   age?: number;
+ * }
+ *
+ * // At least 'id' and 'name' are required, the rest are optional
+ * const user: AtLeast<User, 'email'> = {
+ *   id: '123',
+ *   name: 'Alice',
+ *   email: 'alice@example.com'
+ *   // age are optional
+ * };
+ */
+type AtLeast<T, K extends keyof T> = Partial<T> & RequiredOnly<T> & Required<Pick<T, K>>;
+/**
+ * RequireAtLeastOne helps create a type where at least one of the properties of an interface (can be any property) is required to exist.
+ * https://learn.microsoft.com/en-us/javascript/api/@azure/keyvault-certificates/requireatleastone?view=azure-node-latest
+ */
+type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
+}[keyof T];
+
+/**
+ * Finds files in the current directory and its parent directories.
+ * @param cwd The current working directory.
+ * @param expectations The expected file names.
+ * @returns An array of file paths that match the expectations.
+ */
+declare function findUp(cwd: string, expectations: string[]): string[];
+
+/**
+ * Enables TypeScript support for the specified file or module.
+ *
+ * @param relativeToPath - The path relative to which the TypeScript module should be resolved.
+ * @returns void
+ *
+ * @remarks
+ * This function enables TypeScript support by registering the 'ts-node' module and configuring it with the provided options.
+ * The 'ts-node' module allows for on-the-fly TypeScript transpilation without the need for a separate build step.
+ *
+ * @example
+ * enableTS(process.cwd());
+ */
+declare function enableTS(relativeToPath: string): void;
+/**
+ * Loads a JavaScript or TypeScript module.
+ *
+ * @param fileName - The name of the file to load.
+ * @param relativeToPath - The path relative to which the file should be resolved.
+ * @returns The loaded module.
+ *
+ * @example
+ * // Load a JavaScript module
+ * const myModule = loadJSorTS('myModule.js', '/path/to/file.js');
+ *
+ * // Load a TypeScript module
+ * const myModule = loadJSorTS('myModule.ts', '/path/to/file.js');
+ */
+declare function loadJSorTS(fileName: string, relativeToPath: string): any;
 
 declare const logger: winston.Logger;
 declare function sleep(timeout: number): Promise<void>;
@@ -195,4 +464,4 @@ declare function extractUrlInfo(url: string): {
     port: string;
 };
 
-export { type AccountMnemonic, type AtLeast, type Deployment, type Factory, type NonPromise, type RequireAtLeastOne, type RequiredOnly, bytesToHex, createLogger, deploymentToEvmContract, dirname, ensure0x, extractUrlInfo, findDeployment, first, firstFactory, getAptosAccountFromMnemonic, getBIP044Path, getCircularReplacer, getEvmAccountFromMnemonic, getKeypairFromMnemonic, getLogger, getProjectPackageManager, getProjectRootDir, getSolanaAccountFromMnemonic, hexToBytes, initLogger, isHexString, isHttpServiceReachable, logger, parallel, pkgroot, safeMap, sequence, sleep, trim0x };
+export { type AccountMnemonic, type AtLeast, type Bytes, type DeepPartial, type DeepRequired, type Deployment, type Factory, type Hash, type Hex, type NestedKeys, type NonPromise, type PadReturnType, type RequireAtLeastOne, type RequiredOnly, SizeExceedsPaddingSizeError, type SizeExceedsPaddingSizeErrorType, arrayify, asEnum, asType, assert, assertDefined, assertType, assumeType, bytesToHex, createLogger, deploymentToEvmContract, dirname, enableTS, ensure0x, extractUrlInfo, findContract, findDeployment, findUp, first, firstFactory, getAptosAccountFromMnemonic, getBIP044Path, getCircularReplacer, getEvmAccountFromMnemonic, getKeypairFromMnemonic, getLogger, getProjectPackageManager, getProjectRootDir, getSolanaAccountFromMnemonic, hasRequiredProperties, hexToBytes, hexlify, initLogger, isHash, isHex, isHexString, isHttpServiceReachable, loadJSorTS, logger, padify, parallel, pkgroot, safeMap, sequence, sleep, trim0x };