@ntnyq/utils 0.10.0 → 0.11.1

package/dist/index.d.ts

@@ -1,52 +1,52 @@
 //#region src/fn/noop.d.ts
 /**
-* A function that does nothing.
-*/
+ * A function that does nothing.
+ */
 declare function noop(): void;
 /**
-* Alias of {@link noop}.
-*/
+ * Alias of {@link noop}.
+ */
 declare const NOOP: typeof noop;
 //#endregion
 //#region src/fn/once.d.ts
 /**
-* Creates a function that is restricted to invoking `func` once. Repeat calls to the function return `false`.
-*
-* @param func - The function to restrict.
-* @returns A new function that returns `true` when `func` is invoked for the first time and `false` on subsequent calls.
-*
-* @example
-*
-* ```ts
-* const initialize = once(() => {
-*   console.log('Initialized')
-* })
-*
-* initialize() // Logs: 'Initialized', returns true
-* ```
-*/
+ * Creates a function that is restricted to invoking `func` once. Repeat calls to the function return `false`.
+ *
+ * @param func - The function to restrict.
+ * @returns A new function that returns `true` when `func` is invoked for the first time and `false` on subsequent calls.
+ *
+ * @example
+ *
+ * ```ts
+ * const initialize = once(() => {
+ *   console.log('Initialized')
+ * })
+ *
+ * initialize() // Logs: 'Initialized', returns true
+ * ```
+ */
 declare function once<T extends unknown[]>(func: (...args: T) => void): (this: unknown, ...args: T) => boolean;
 //#endregion
 //#region src/is/dom.d.ts
 /**
-* @file is/dom.ts
-*/
+ * @file is/dom.ts
+ */
 /**
-* Check if given value is an HTMLElement
-* @param value - The value to check
-* @returns True if the value is an HTMLElement, false otherwise
-*/
+ * Check if given value is an HTMLElement
+ * @param value - The value to check
+ * @returns True if the value is an HTMLElement, false otherwise
+ */
 declare function isHTMLElement(value: unknown): value is HTMLElement;
 //#endregion
 //#region src/is/core.d.ts
 /**
-* @file is utils
-* @module is
-* @copyright {@link https://github.com/sindresorhus/is}
-*/
-type Whitespace = " ";
+ * @file is utils
+ * @module is
+ * @copyright {@link https://github.com/sindresorhus/is}
+ */
+type Whitespace = ' ';
 type NonEmptyString = string & {
-  0: "";
+  0: '';
 };
 declare function getObjectType(value: unknown): string;
 declare function isUndefined(value: unknown): value is undefined;
@@ -54,10 +54,10 @@ declare function isNull(value: unknown): value is null;
 declare function isNil(value: unknown): value is null | undefined;
 declare const isNullOrUndefined: typeof isNil;
 declare function isString(value: unknown): value is string;
-declare function isEmptyString(value: unknown): value is "";
+declare function isEmptyString(value: unknown): value is '';
 declare function isNonEmptyString(value: unknown): value is NonEmptyString;
 declare function isWhitespaceString(value: unknown): value is Whitespace;
-declare function isEmptyStringOrWhitespace(value: unknown): value is "" | Whitespace;
+declare function isEmptyStringOrWhitespace(value: unknown): value is '' | Whitespace;
 declare function isNumbericString(value: unknown): value is `${number}`;
 declare function isNumber(value: unknown): value is number;
 declare function isZero(value: unknown): value is 0;
@@ -70,12 +70,12 @@ declare function isFunction(value: unknown): value is Function;
 declare function isArray(value: unknown): value is unknown[];
 declare function isEmptyArray(value: unknown): value is [];
 declare function isNonEmptyArray<T = unknown, Item = unknown>(value: T | Item[]): value is [Item, ...Item[]];
-declare function isObject(value: unknown): value is object;
-declare function isEmptyObject(value: unknown): value is {};
 declare function isMap<Key = unknown, Value = unknown>(value: unknown): value is Map<Key, Value>;
-declare function isEmptyMap(value: unknown): value is Map<never, never>;
 declare function isSet<Value = unknown>(value: unknown): value is Set<Value>;
 declare function isEmptySet(value: unknown): value is Set<never>;
+declare function isObject(value: unknown): value is object;
+declare function isEmptyObject(value: unknown): value is {};
+declare function isEmptyMap(value: unknown): value is Map<never, never>;
 declare function isRegExp(value: unknown): value is RegExp;
 declare function isError(value: unknown): value is Error;
 declare function isNativePromise<T = unknown>(value: unknown): value is Promise<T>;
@@ -85,29 +85,29 @@ declare function isBlob(value: unknown): value is Blob;
 declare function isFormData(value: unknown): value is FormData;
 declare function isFile(value: unknown): value is File;
 type UrlString = string & {
-  readonly __brand: "UrlString";
+  readonly __brand: 'UrlString';
 };
 declare function isUrlString(value: unknown): value is UrlString;
 //#endregion
 //#region src/is/isDeepEqual.d.ts
 /**
-* check if two values are deeply equal
-*/
+ * check if two values are deeply equal
+ */
 declare function isDeepEqual(value1: any, value2: any): boolean;
 //#endregion
 //#region src/dom/scrollIntoView.d.ts
 interface Options extends ScrollIntoViewOptions {
   /**
-  * @default `document.body`
-  */
+   * @default `document.body`
+   */
   parent?: HTMLElement;
 }
 /**
-* Scroll element into view if it is out of view.
-*
-* @param element - element to scroll
-* @param options - scroll options
-*/
+ * Scroll element into view if it is out of view.
+ *
+ * @param element - element to scroll
+ * @param options - scroll options
+ */
 declare function scrollElementIntoView(element: HTMLElement, options?: Options): void;
 //#endregion
 //#region src/types/base.d.ts
@@ -118,12 +118,12 @@ type Callable<T> = AnyFn<any, T> | T;
 type MayBe<T> = T | undefined;
 type Nullable<T> = T | null;
 /**
-* Overwrite some keys type
-*/
-type Overwrite<T, U$1> = Pick<T, Exclude<keyof T, keyof U$1>> & U$1;
+ * Overwrite some keys type
+ */
+type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
 /**
-* Prettify object type
-*/
+ * Prettify object type
+ */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 type PrettifyV2<T> = Omit<T, never>;
 type Primitive = bigint | boolean | number | string | symbol | AnyFn | null | undefined;
@@ -136,166 +136,172 @@ type JsonArray = JsonValue[] | readonly JsonValue[];
 type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: JsonValue | undefined };
 type JsonPrimitive = boolean | number | string | null;
 /**
-* @copyright {@link https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts}
-*/
+ * @copyright {@link https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts}
+ */
 type JsonValue = JsonArray | JsonObject | JsonPrimitive;
 //#endregion
 //#region src/types/utils.d.ts
 /**
-* A literal type that supports custom further strings but preserves autocompletion in IDEs.
-*
-* @see {@link https://github.com/microsoft/TypeScript/issues/29729#issuecomment-471566609}
-*/
+ * A literal type that supports custom further strings but preserves autocompletion in IDEs.
+ *
+ * @see {@link https://github.com/microsoft/TypeScript/issues/29729#issuecomment-471566609}
+ */
 type LiteralUnion<Union extends Base, Base = string> = Union | (Base & {
   zz_IGNORE_ME?: never;
 });
 /**
-* @see {@link TODO:}
-*/
-type Merge<T, U$1> = keyof T & keyof U$1 extends never ? T & U$1 : Omit<T, keyof T & keyof U$1> & U$1;
+ * @see {@link TODO:}
+ */
+type Merge<T, U> = keyof T & keyof U extends never ? T & U : Omit<T, keyof T & keyof U> & U;
 /**
-* Non empty object `{}`
-*/
+ * Non empty object `{}`
+ */
 type NonEmptyObject<T> = T extends Record<string, never> ? never : T;
 /**
-* A type that represents the values of an object type.
-*/
+ * A type that represents the values of an object type.
+ */
 type ValueOf<T> = T[keyof T];
 /**
-* A type that represents the elements of an array type.
-*/
-type ElementOf<T extends unknown[] | null | undefined> = T extends Array<infer U> ? U : never;
+ * A type that represents the elements of an array type.
+ */
+type ElementOf<T extends unknown[] | null | undefined> = T extends (infer U)[] ? U : never;
 //#endregion
 //#region src/types/module.d.ts
 /**
-* interop module
-*/
+ * interop module
+ */
 type InteropModuleDefault<T> = T extends {
   default: infer U;
 } ? U : T;
 /**
-* Resolve `boolean | Options` to `Options`
-*/
+ * Resolve `boolean | Options` to `Options`
+ */
 type ResolvedOptions<T> = T extends boolean ? never : NonNullable<T>;
 //#endregion
 //#region src/dom/openExternalURL.d.ts
 interface OpenExternalURLOptions {
   /**
-  * open target
-  *
-  * @default `_blank`
-  */
-  target?: LiteralUnion<"_self" | "_top" | "_blank" | "_parent">;
+   * open target
+   *
+   * @default `_blank`
+   */
+  target?: LiteralUnion<'_self' | '_top' | '_blank' | '_parent'>;
 }
 /**
-* Open external url
-* @param url - URL to open
-* @param options - open options
-* @returns window proxy
-*/
+ * Open external url
+ * @param url - URL to open
+ * @param options - open options
+ * @returns window proxy
+ */
 declare function openExternalURL(url: string | URL, options?: OpenExternalURLOptions): WindowProxy | null;
 //#endregion
 //#region src/dom/isVisibleInViewport.d.ts
 /**
-* Check if element is in viewport
-* @param element - checked element
-* @param targetWindow - window
-* @returns true if element is in viewport, false otherwise
-*/
+ * Check if element is in viewport
+ * @param element - checked element
+ * @param targetWindow - window
+ * @returns true if element is in viewport, false otherwise
+ */
 declare function isElementVisibleInViewport(element: HTMLElement, targetWindow?: Window): boolean;
 //#endregion
 //#region src/env/isBrowser.d.ts
 /**
-* @file env.ts
-*/
-/**
-* Checks if the code is running in a browser
-*
-* @returns boolean - true if the code is running in a browser
-*/
+ * Checks if the code is running in a browser
+ *
+ * @returns true if the code is running in a browser
+ */
 declare function isBrowser(): boolean;
 //#endregion
-//#region src/file/removeExtension.d.ts
+//#region src/file/extension.d.ts
 /**
-* Removes the file extension from a filename.
-*
-* @param filename - The filename to remove the extension from.
-* @returns The filename without the extension.
-*/
+ * Removes the file extension from a filename.
+ *
+ * @param filename - The filename to remove the extension from.
+ * @returns The filename without the extension.
+ */
 declare function removeFileExtension(filename: string): string;
+/**
+ * Gets the file extension from a filename.
+ * @param filePath - The filePath to get the extension from.
+ * @returns The file extension, or undefined if there is none.
+ */
+declare function getFileExtension(filePath?: string): string | undefined;
 //#endregion
 //#region src/html/escape.d.ts
 /**
-* Escape html chars
-*/
+ * Escape html chars
+ */
 declare function escapeHTML(str: string): string;
 /**
-* Unescape html chars
-*/
+ * Unescape html chars
+ */
 declare function unescapeHTML(str: string): string;
 //#endregion
 //#region src/misc/raf.d.ts
 /**
-* Gets the global root object.
-* @returns the global root object
-*/
+ * @file raf.ts
+ */
+/**
+ * Gets the global root object.
+ * @returns the global root object
+ */
 declare function getRoot(): Window | typeof globalThis;
 /**
-* Request animation frame
-*
-* @param fn - callback
-* @returns id
-*/
+ * Request animation frame
+ *
+ * @param fn - callback
+ * @returns id
+ */
 declare function rAF(fn: FrameRequestCallback): number;
 /**
-* Cancel animation frame
-*
-* @param id - id
-* @returns void
-*/
+ * Cancel animation frame
+ *
+ * @param id - id
+ * @returns void
+ */
 declare function cAF(id: number): void;
 //#endregion
 //#region src/misc/clamp.d.ts
 /**
-* Clamps a number between a minimum and maximum value
-* @param value - the value to clamp within the given range
-* @param min - the minimum value to clamp
-* @param max - the maximum value to clamp
-* @returns the new value
-*/
+ * Clamps a number between a minimum and maximum value
+ * @param value - the value to clamp within the given range
+ * @param min - the minimum value to clamp
+ * @param max - the maximum value to clamp
+ * @returns the new value
+ */
 declare function clamp(value: number, min?: number, max?: number): number;
 //#endregion
 //#region src/misc/waitFor.d.ts
 /**
-* Wait for a number of milliseconds
-*
-* @param ms - millseconds to wait
-* @returns a promise that resolves after ms milliseconds
-*
-* @example
-* ```
-* import { waitFor } from '@ntnyq/utils'
-* await waitFor(3e3)
-* // do somthing after 3 seconds
-* ```
-*/
+ * Wait for a number of milliseconds
+ *
+ * @param ms - millseconds to wait
+ * @returns a promise that resolves after ms milliseconds
+ *
+ * @example
+ * ```
+ * import { waitFor } from '@ntnyq/utils'
+ * await waitFor(3e3)
+ * // do somthing after 3 seconds
+ * ```
+ */
 declare function waitFor(ms: number): Promise<void>;
 //#endregion
 //#region src/misc/throttle.d.ts
 interface ThrottleDebounceOptions {
   /**
-  * @default false
-  */
+   * @default false
+   */
   isDebounce?: boolean;
 }
 /**
-* Throttle a function to limit its execution to a maximum of once per a specified time interval.
-*
-* @param delay - Zero or greater delay in milliseconds
-* @param callback - A function to be throttled
-* @param options - throttle options
-* @returns A throttled function
-*/
+ * Throttle a function to limit its execution to a maximum of once per a specified time interval.
+ *
+ * @param delay - Zero or greater delay in milliseconds
+ * @param callback - A function to be throttled
+ * @param options - throttle options
+ * @returns A throttled function
+ */
 declare function throttle<T extends ((...args: any[]) => undefined | void) | undefined | null>(delay: number, callback: Exclude<T, undefined | null>, options?: ThrottleDebounceOptions): T & {
   cancel: () => void;
 };
@@ -305,20 +311,20 @@ declare function debounce<T extends ((...args: any[]) => undefined | void) | und
 //#endregion
 //#region src/misc/warnOnce.d.ts
 /**
-* Warn message only once
-*
-* @param message - warning message
-*/
+ * Warn message only once
+ *
+ * @param message - warning message
+ */
 declare function warnOnce(message: string): void;
 //#endregion
 //#region src/misc/convertTime.d.ts
 /**
-* @file time utils
-* @module Time
-*/
+ * @file time utils
+ * @module Time
+ */
 /**
-* Time unit conversion constants (in milliseconds)
-*/
+ * Time unit conversion constants (in milliseconds)
+ */
 declare const TIME_UNITS: {
   readonly MILLISECOND: 1;
   readonly SECOND: 1000;
@@ -329,54 +335,54 @@ declare const TIME_UNITS: {
 };
 type TimeUnit = keyof typeof TIME_UNITS;
 /**
-* Converts time units to milliseconds.
-* @param value - The time value.
-* @param fromUnit - The source unit (default: 'SECOND').
-* @returns The time in milliseconds.
-* @example
-* ```ts
-* convertToMilliseconds(5, 'SECOND') // 5000
-* convertToMilliseconds(2, 'MINUTE') // 120000
-* convertToMilliseconds(1, 'HOUR') // 3600000
-* ```
-*/
+ * Converts time units to milliseconds.
+ * @param value - The time value.
+ * @param fromUnit - The source unit (default: 'SECOND').
+ * @returns The time in milliseconds.
+ * @example
+ * ```ts
+ * convertToMilliseconds(5, 'SECOND') // 5000
+ * convertToMilliseconds(2, 'MINUTE') // 120000
+ * convertToMilliseconds(1, 'HOUR') // 3600000
+ * ```
+ */
 declare function convertToMilliseconds(value: number, fromUnit?: TimeUnit): number;
 /**
-* Converts milliseconds to specified time unit.
-* @param milliseconds - The time in milliseconds.
-* @param toUnit - The target unit (default: 'SECOND').
-* @returns The time in the specified unit.
-* @example
-* ```ts
-* convertFromMilliseconds(5000, 'SECOND') // 5
-* convertFromMilliseconds(120000, 'MINUTE') // 2
-* convertFromMilliseconds(3600000, 'HOUR') // 1
-* ```
-*/
+ * Converts milliseconds to specified time unit.
+ * @param milliseconds - The time in milliseconds.
+ * @param toUnit - The target unit (default: 'SECOND').
+ * @returns The time in the specified unit.
+ * @example
+ * ```ts
+ * convertFromMilliseconds(5000, 'SECOND') // 5
+ * convertFromMilliseconds(120000, 'MINUTE') // 2
+ * convertFromMilliseconds(3600000, 'HOUR') // 1
+ * ```
+ */
 declare function convertFromMilliseconds(milliseconds: number, toUnit?: TimeUnit): number;
 /**
-* Converts between time units.
-* @param value - The time value.
-* @param fromUnit - The source unit.
-* @param toUnit - The target unit.
-* @returns The converted time.
-* @example
-* ```ts
-* convertTimeUnit(1, 'HOUR', 'MINUTE') // 60
-* convertTimeUnit(120, 'SECOND', 'MINUTE') // 2
-* convertTimeUnit(2, 'WEEK', 'DAY') // 14
-* ```
-*/
+ * Converts between time units.
+ * @param value - The time value.
+ * @param fromUnit - The source unit.
+ * @param toUnit - The target unit.
+ * @returns The converted time.
+ * @example
+ * ```ts
+ * convertTimeUnit(1, 'HOUR', 'MINUTE') // 60
+ * convertTimeUnit(120, 'SECOND', 'MINUTE') // 2
+ * convertTimeUnit(2, 'WEEK', 'DAY') // 14
+ * ```
+ */
 declare function convertTimeUnit(value: number, fromUnit: TimeUnit, toUnit: TimeUnit): number;
 //#endregion
 //#region src/misc/convertStorage.d.ts
 /**
-* @file storage utils
-* @module Storage
-*/
+ * @file storage utils
+ * @module Storage
+ */
 /**
-* Storage unit conversion constants
-*/
+ * Storage unit conversion constants
+ */
 declare const STORAGE_UNITS: {
   readonly BYTE: 1;
   readonly KB: 1024;
@@ -386,122 +392,140 @@ declare const STORAGE_UNITS: {
 };
 type StorageUnit = keyof typeof STORAGE_UNITS;
 /**
-* Converts storage units to bytes.
-* @param value - The size value.
-* @param fromUnit - The source unit (default: 'MB').
-* @returns The size in bytes.
-* @example
-* ```ts
-* convertToBytes(5, 'MB') // 5242880
-* convertToBytes(1, 'GB') // 1073741824
-* convertToBytes(512, 'KB') // 524288
-* ```
-*/
+ * Converts storage units to bytes.
+ * @param value - The size value.
+ * @param fromUnit - The source unit (default: 'MB').
+ * @returns The size in bytes.
+ * @example
+ * ```ts
+ * convertToBytes(5, 'MB') // 5242880
+ * convertToBytes(1, 'GB') // 1073741824
+ * convertToBytes(512, 'KB') // 524288
+ * ```
+ */
 declare function convertToBytes(value: number, fromUnit?: StorageUnit): number;
 /**
-* Converts bytes to specified storage unit.
-* @param bytes - The size in bytes.
-* @param toUnit - The target unit (default: 'MB').
-* @returns The size in the specified unit.
-* @example
-* ```ts
-* convertFromBytes(5242880, 'MB') // 5
-* convertFromBytes(1073741824, 'GB') // 1
-* convertFromBytes(524288, 'KB') // 512
-* ```
-*/
+ * Converts bytes to specified storage unit.
+ * @param bytes - The size in bytes.
+ * @param toUnit - The target unit (default: 'MB').
+ * @returns The size in the specified unit.
+ * @example
+ * ```ts
+ * convertFromBytes(5242880, 'MB') // 5
+ * convertFromBytes(1073741824, 'GB') // 1
+ * convertFromBytes(524288, 'KB') // 512
+ * ```
+ */
 declare function convertFromBytes(bytes: number, toUnit?: StorageUnit): number;
 /**
-* Converts between storage units.
-* @param value - The size value.
-* @param fromUnit - The source unit.
-* @param toUnit - The target unit.
-* @returns The converted size.
-* @example
-* ```ts
-* convertStorageUnit(1, 'GB', 'MB') // 1024
-* convertStorageUnit(2048, 'MB', 'GB') // 2
-* convertStorageUnit(1024, 'KB', 'MB') // 1
-* ```
-*/
+ * Converts between storage units.
+ * @param value - The size value.
+ * @param fromUnit - The source unit.
+ * @param toUnit - The target unit.
+ * @returns The converted size.
+ * @example
+ * ```ts
+ * convertStorageUnit(1, 'GB', 'MB') // 1024
+ * convertStorageUnit(2048, 'MB', 'GB') // 2
+ * convertStorageUnit(1024, 'KB', 'MB') // 1
+ * ```
+ */
 declare function convertStorageUnit(value: number, fromUnit: StorageUnit, toUnit: StorageUnit): number;
 //#endregion
 //#region src/array/at.d.ts
 /**
-* Get array item by index, negative for backward
-* @param array - given array
-* @param index - index of item
-* @returns undefined if not match, otherwise matched item
-*/
+ * Get array item by index, negative for backward
+ * @param array - given array
+ * @param index - index of item
+ * @returns undefined if not match, otherwise matched item
+ */
 declare function at<T>(array: readonly T[], index: number): T | undefined;
 /**
-* Get the last item of given array
-* @param array - given array
-* @returns undefined if empty array, otherwise last item
-*/
+ * Get the last item of given array
+ * @param array - given array
+ * @returns undefined if empty array, otherwise last item
+ */
 declare function last<T>(array: readonly T[]): T | undefined;
 //#endregion
 //#region src/array/chunk.d.ts
 /**
-* Splits an array into smaller chunks of a given size.
-* @param array - The array to split
-* @param size - The size of each chunk
-* @returns An array of arrays, where each sub-array has `size` elements from the original array.
-*/
+ * Splits an array into smaller chunks of a given size.
+ * @param array - The array to split
+ * @param size - The size of each chunk
+ * @returns An array of arrays, where each sub-array has `size` elements from the original array.
+ */
 declare function chunk<T>(array: T[], size: number): T[][];
 //#endregion
+//#region src/array/remove.d.ts
+/**
+ * Remove given item from an array
+ * @param array - given array
+ * @param value - item to be removed
+ * @returns true if item was removed, otherwise false
+ */
+declare function remove<T>(array: T[], value: T): boolean;
+//#endregion
 //#region src/array/unique.d.ts
 /**
-* Returns a new array with unique values.
-* @param array - The array to process.
-* @returns The new array.
-*/
+ * Returns a new array with unique values.
+ * @param array - The array to process.
+ * @returns The new array.
+ */
 declare function unique<T>(array: T[]): T[];
 /**
-* Returns a new array with unique values.
-* @param array - The array to process.
-* @param equalFn - The function to compare values.
-* @returns The new array.
-*/
+ * Returns a new array with unique values.
+ * @param array - The array to process.
+ * @param equalFn - The function to compare values.
+ * @returns The new array.
+ */
 declare function uniqueBy<T>(array: T[], equalFn: (a: T, b: T) => boolean): T[];
 //#endregion
+//#region src/array/shuffle.d.ts
+/**
+ * Fisher–Yates shuffle
+ *
+ * @param array - array to shuffle
+ * @returns shuffled array
+ */
+declare function shuffle<T>(array: T[]): T[];
+//#endregion
 //#region src/array/toArray.d.ts
 /**
-* Converts a value to an array.
-* @param array - The value to convert.
-* @returns The array.
-*/
+ * Converts a value to an array.
+ * @param array - The value to convert.
+ * @returns The array.
+ */
 declare function toArray<T>(array?: Nullable<Arrayable<T>>): T[];
 //#endregion
 //#region src/array/arrayable.d.ts
 /**
-* Convert `Arrayable<T>` to `Array<T>` and flatten the result
-* @param array - given array
-* @returns Array<T>
-*/
-declare function flattenArrayable<T>(array?: Nullable<Arrayable<T | Array<T>>>): Array<T>;
+ * Convert `Arrayable<T>` to `Array<T>` and flatten the result
+ * @param array - given array
+ * @returns Array<T>
+ */
+declare function flattenArrayable<T>(array?: Nullable<Arrayable<T | T[]>>): T[];
 /**
-* Use rest arguments to merge arrays
-* @param args - rest arguments
-* @returns Array<T>
-*/
-declare function mergeArrayable<T>(...args: Nullable<Arrayable<T>>[]): Array<T>;
+ * Use rest arguments to merge arrays
+ * @param args - rest arguments
+ * @returns Array<T>
+ */
+declare function mergeArrayable<T>(...args: Nullable<Arrayable<T>>[]): T[];
 //#endregion
 //#region src/array/intersect.d.ts
 /**
-* Get intersect items
-*
-* @returns intersect items
-*/
+ * Get intersect items
+ *
+ * @returns intersect items
+ */
 declare function intersect<T>(a: T[], b: T[]): T[];
 //#endregion
 //#region src/array/isArrayEqual.d.ts
 /**
-* Check if values of two arrays are equal
-* @param array1 - array 1
-* @param array2 - array 2
-* @returns `true` if equal
-*/
+ * Check if values of two arrays are equal
+ * @param array1 - array 1
+ * @param array2 - array 2
+ * @returns `true` if equal
+ */
 declare function isArrayEqual(array1: unknown[], array2: unknown[]): boolean;
 //#endregion
 //#region src/color/color.d.ts
@@ -520,246 +544,314 @@ declare class Color {
   toHexString(isUpperCase?: boolean): string;
   toRGBAString(): string;
   /**
-  * add alpha value to {@link Color}
-  *
-  * @param alpha - alpha value
-  * @returns instance of {@link Color}
-  */
+   * add alpha value to {@link Color}
+   *
+   * @param alpha - alpha value
+   * @returns instance of {@link Color}
+   */
   withAlpha(alpha?: number): Color;
   /**
-  * lighten the color by percentage
-  *
-  * @param percentage - percentage to lighten
-  */
+   * lighten the color by percentage
+   *
+   * @param percentage - percentage to lighten
+   */
   lighten(percentage?: number): Color;
   /**
-  * darken the color by percentage
-  *
-  * @param percentage - percentage to darken
-  */
+   * darken the color by percentage
+   *
+   * @param percentage - percentage to darken
+   */
   darken(percentage?: number): Color;
 }
 //#endregion
 //#region src/color/random.d.ts
 /**
-* get a random RGB color
-* @returns a random RGB color
-*/
+ * get a random RGB color
+ * @returns a random RGB color
+ */
 declare function randomRGBColor(): string;
 /**
-* get a random RGBA color
-* @returns a random RGBA color
-*/
+ * get a random RGBA color
+ * @returns a random RGBA color
+ */
 declare function randomRGBAColor(): string;
 /**
-* get a random hex color
-* @returns a random hex color
-*/
+ * get a random hex color
+ * @returns a random hex color
+ */
 declare function randomHexColor(): string;
 //#endregion
 //#region src/proxy/enhance.d.ts
 /**
-* enhance object
-* @module proxy
-*/
+ * enhance object
+ * @module proxy
+ */
 declare function enhance<T extends Record<PropertyKey, any>, E extends Record<PropertyKey, any>>(module: T, extra: E): T;
 //#endregion
+//#region src/tree/flatTree.d.ts
+interface FlatTreeOptions<T extends Record<PropertyKey, any>, K extends keyof T> {
+  /**
+   * children key, maybe `children`, `nodes`, `items` or other name
+   *
+   * @default `children`
+   */
+  childrenKey?: K;
+  /**
+   * whether to include the current node in the result
+   * @default true
+   */
+  includeSelf?: boolean;
+  /**
+   * map function, return value will be used as the result of the current node, if not provided, the current node will be used as the result
+   */
+  map?: (ctx: {
+    node: T;
+    parent: T | null;
+    depth: number;
+    /**
+     * index of the current node in the current level, starting from 0
+     */
+    index: number;
+    path: T[];
+  }) => any;
+}
+/**
+ * Flatten tree nodes into a one-dimensional array with depth-first pre-order traversal.
+ *
+ * If `options.map` is not provided, original nodes are returned.
+ *
+ * @param roots - Root nodes of the tree.
+ * @param options - Flatten options.
+ * @returns Flattened nodes.
+ */
+declare function flatTree<T extends Record<PropertyKey, any>, K extends keyof T>(roots: readonly T[], options?: FlatTreeOptions<T, K>): T[];
+/**
+ * Flatten tree nodes and map each visited node to a custom result.
+ *
+ * @param roots - Root nodes of the tree.
+ * @param options - Flatten options with a `map` callback.
+ * @returns Flattened mapped results.
+ */
+declare function flatTree<T extends Record<PropertyKey, any>, K extends keyof T, R>(roots: readonly T[], options: FlatTreeOptions<T, K> & {
+  map: (ctx: any) => R;
+}): R[];
+//#endregion
 //#region src/module/interopDefault.d.ts
 /**
-* Interop default export from a module
-*
-* @param mod - The module
-* @returns The default export
-*
-* @example
-*
-* ```ts
-* import { interopDefault } from '@ntnyq/utils'
-*
-* const { unindent } = await interopDefault(import('@ntnyq/utils'))
-* ```
-*/
+ * Interop default export from a module
+ *
+ * @param mod - The module
+ * @returns The default export
+ *
+ * @example
+ *
+ * ```ts
+ * import { interopDefault } from '@ntnyq/utils'
+ *
+ * const { unindent } = await interopDefault(import('@ntnyq/utils'))
+ * ```
+ */
 declare function interopDefault<T>(mod: Awaitable<T>): Promise<InteropModuleDefault<T>>;
 //#endregion
 //#region src/module/resolveSubOptions.d.ts
 /**
-* Resolve sub options `boolean | Options` to `Options`
-* @param options - core options
-* @param key - sub options key
-* @returns resolved sub options
-*
-* @example
-*
-* ```ts
-* import { resolveSubOptions } from '@ntnyq/utils'
-*
-* interface Options {
-*   compile?: boolean | {
-*     include?: string[]
-*     exclude?: string[]
-*   }
-* }
-*
-* const options: Options = {
-*   compile: true
-* }
-*
-* console.log(resolveSubOptions(options, 'compile'))
-*
-* // => {}
-* ```
-*/
-declare function resolveSubOptions<T extends Record<string, any>, K$1 extends keyof T>(options: T, key: K$1): Partial<ResolvedOptions<T[K$1]>>;
+ * Resolve sub options `boolean | Options` to `Options`
+ * @param options - core options
+ * @param key - sub options key
+ * @returns resolved sub options
+ *
+ * @example
+ *
+ * ```ts
+ * import { resolveSubOptions } from '@ntnyq/utils'
+ *
+ * interface Options {
+ *   compile?: boolean | {
+ *     include?: string[]
+ *     exclude?: string[]
+ *   }
+ * }
+ *
+ * const options: Options = {
+ *   compile: true
+ * }
+ *
+ * console.log(resolveSubOptions(options, 'compile'))
+ *
+ * // => {}
+ * ```
+ */
+declare function resolveSubOptions<T extends Record<string, any>, K extends keyof T>(options: T, key: K): Partial<ResolvedOptions<T[K]>>;
 //#endregion
 //#region src/number/random.d.ts
 interface RamdomNumberOptions {
   /**
-  * include max value
-  *
-  * @default false
-  */
+   * include max value
+   *
+   * @default false
+   */
   includeMax?: boolean;
 }
 /**
-* random an integer by given range
-*
-* @param min - min value
-* @param max - max value
-* @returns random integer in range
-*/
+ * random an integer by given range
+ *
+ * @param min - min value
+ * @param max - max value
+ * @returns random integer in range
+ */
 declare function randomNumber(min: number, max?: number, options?: RamdomNumberOptions): number;
 //#endregion
 //#region src/number/toInteger.d.ts
 interface ToIntegerOptions {
   /**
-  * The number to convert to an integer.
-  *
-  * @default 0
-  */
+   * The number to convert to an integer.
+   *
+   * @default 0
+   */
   defaultValue?: number;
   /**
-  * @default false
-  */
+   * @default false
+   */
   allowDecimal?: boolean;
   /**
-  * @default false
-  */
+   * @default false
+   */
   allowNaN?: boolean;
   /**
-  * @default `useDefault`
-  */
-  onError?: "useDefault" | "throwError" | "returnOriginal";
+   * @default `useDefault`
+   */
+  onError?: 'useDefault' | 'throwError' | 'returnOriginal';
   /**
-  * Minimum value of the number. included
-  */
+   * Minimum value of the number. included
+   */
   min?: number;
   /**
-  * Maximum value of the number. included
-  */
+   * Maximum value of the number. included
+   */
   max?: number;
   /**
-  * @default `clamp`
-  */
-  outOfRange?: "clamp" | "useDefault" | "throwError";
+   * @default `clamp`
+   */
+  outOfRange?: 'clamp' | 'useDefault' | 'throwError';
 }
 /**
-* Transforms a value to an integer.
-* @param value - The value to convert to an integer.
-* @param options - Options for the conversion.
-* @returns The converted integer.
-*/
+ * Transforms a value to an integer.
+ * @param value - The value to convert to an integer.
+ * @param options - Options for the conversion.
+ * @returns The converted integer.
+ */
 declare function toInteger(value: unknown, options?: ToIntegerOptions): number;
 //#endregion
 //#region src/object/omit.d.ts
-declare function omit<T, K$1 extends keyof T>(object: T, ...keys: K$1[]): Omit<T, K$1>;
+declare function omit<T, K extends keyof T>(object: T, ...keys: K[]): Omit<T, K>;
 //#endregion
 //#region src/object/pick.d.ts
-declare function pick<T, K$1 extends keyof T>(object: T, keys: K$1[]): Pick<T, K$1>;
+declare function pick<T, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
 //#endregion
 //#region src/object/clean.d.ts
 interface CleanObjectOptions {
   /**
-  * clean undefined
-  *
-  * @default true
-  */
+   * clean undefined
+   *
+   * @default true
+   */
   cleanUndefined?: boolean;
   /**
-  * clean null
-  *
-  * @default true
-  */
+   * clean null
+   *
+   * @default true
+   */
   cleanNull?: boolean;
   /**
-  * clean zero
-  *
-  * @default false
-  */
+   * clean zero
+   *
+   * @default false
+   */
   cleanZero?: boolean;
   /**
-  * clean NaN
-  *
-  * @default true
-  */
+   * clean NaN
+   *
+   * @default true
+   */
   cleanNaN?: boolean;
   /**
-  * clean empty string
-  *
-  * @default false
-  */
+   * clean empty string
+   *
+   * @default false
+   */
   cleanEmptyString?: boolean;
   /**
-  * clean empty array
-  *
-  * @default false
-  */
+   * clean empty array
+   *
+   * @default false
+   */
   cleanEmptyArray?: boolean;
   /**
-  * clean empty object
-  *
-  * @default false
-  */
+   * clean empty object
+   *
+   * @default false
+   */
   cleanEmptyObject?: boolean;
   /**
-  * recursive clean object
-  *
-  * @default true
-  */
+   * recursive clean object
+   *
+   * @default true
+   */
   recursive?: boolean;
 }
 /**
-* clean undefined, null, zero, empty string, empty array, empty object from object
-* @param obj - object to be cleaned
-* @param options - clean options
-* @returns cleaned object
-*/
+ * clean undefined, null, zero, empty string, empty array, empty object from object
+ * @param obj - object to be cleaned
+ * @param options - clean options
+ * @returns cleaned object
+ */
 declare function cleanObject<T extends object>(obj: T, options?: CleanObjectOptions): T;
 //#endregion
 //#region src/object/hasOwn.d.ts
 /**
-* check object has a property with given key
-* @param object - the object to check
-* @param key - the key to check
-* @returns true if object has a property with given key, false otherwise
-*/
+ * check object has a property with given key
+ * @param object - the object to check
+ * @param key - the key to check
+ * @returns true if object has a property with given key, false otherwise
+ */
 declare function hasOwn<T>(object: T, key: PropertyKey): boolean;
 //#endregion
+//#region src/object/isKeyOf.d.ts
+/**
+ * Type guard for any key, `k`
+ * marks `k` as a key of `T` if `k` is a key of `T`
+ *
+ * @param obj - object to query for key
+ * @param k - key to check for
+ * @returns true if `k` is a key of `T`
+ */
+declare function isKeyOf<T extends object>(obj: T, k: keyof T): k is keyof T;
+//#endregion
 //#region src/object/sortObject.d.ts
 interface SortObjectOptions {
   /**
-  * Recursive sorting
-  * @default false
-  */
+   * Recursive sorting
+   * @default false
+   */
   deep?: boolean;
   /**
-  * Compare function
-  */
+   * Compare function
+   */
   compareFn?: (left: string, right: string) => number;
 }
 /**
-* Sort object properties
-*/
-declare function sortObject<T extends Record<string, any>>(obj: T, options?: SortObjectOptions): T;
+ * Sort object properties
+ */
+declare function sortObject<T extends Record<string, any>>(object: T, options?: SortObjectOptions): T;
+//#endregion
+//#region src/object/isPlainObject.d.ts
+/**
+ * Check if a value is a plain object (not an array, Date, RegExp, Map, Set, etc.)
+ *
+ * @param value - Checked value
+ * @copyright {@link https://github.com/sindresorhus/is/blob/main/source/index.ts}
+ */
+declare function isPlainObject<Value = unknown>(value: unknown): value is Record<PropertyKey, Value>;
 //#endregion
 //#region src/string/pad.d.ts
 interface CreatePadStringOptions {
@@ -772,64 +864,70 @@ declare function createPadString(options: CreatePadStringOptions): (value: strin
 type JoinableValue = string | number | null | undefined;
 interface JoinOptions {
   /**
-  * @default ''
-  */
+   * @default ''
+   */
   separator?: string;
 }
 /**
-* Joins an array of strings or numbers into a single string.
-* @param array - An array of strings or numbers.
-* @param options - An object of options.
-* @returns A string.
-*/
+ * Joins an array of strings or numbers into a single string.
+ * @param array - An array of strings or numbers.
+ * @param options - An object of options.
+ * @returns A string.
+ */
 declare function join(array: JoinableValue[], options?: JoinOptions): string;
 //#endregion
 //#region src/string/slash.d.ts
 /**
-* Replace backslash to slash
-*/
+ * Replace backslash to slash
+ */
 declare function slash(input: string): string;
 //#endregion
+//#region src/string/escape.d.ts
+/**
+ * @copyright {@link https://github.com/sindresorhus/escape-string-regexp}
+ */
+declare function escapeStringRegexp(value: string): string;
+//#endregion
 //#region src/string/random.d.ts
 /**
-* randome a string useing given chars
-*
-* @param length - string length
-* @param chars - string chars
-* @returns random string
-*/
+ * randome a string useing given chars
+ *
+ * @param length - string length
+ * @param chars - string chars
+ * @returns random string
+ */
 declare function randomString(length?: number, chars?: string): string;
 //#endregion
 //#region src/string/slugify.d.ts
 /**
-* Default slugify function
-*/
+ * Default slugify function
+ */
 declare function slugify(str: string): string;
 //#endregion
 //#region src/string/unindent.d.ts
 /**
-* Remove common leading whitespace from a template string
-* Empty lines at the beginning and end of the template string are also removed.
-* @param input - template string
-*
-* @example
-*
-* ```ts
-* const str = unindent`
-*   if (foo) {
-*     bar()
-*   }
-* `
-* ```
-*/
+ * Remove common leading whitespace from a template string
+ * Empty lines at the beginning and end of the template string are also removed.
+ * @param input - template string
+ *
+ * @example
+ *
+ * ```ts
+ * const str = unindent`
+ *   if (foo) {
+ *     bar()
+ *   }
+ * `
+ * ```
+ */
 declare function unindent(input: TemplateStringsArray | string): string;
 //#endregion
 //#region src/string/getLength.d.ts
 /**
-* Counts graphemes in a given string
-* @param value - A string to count graphemes.
-* @returns The number of graphemes in `value`.
-*/
+ * Counts graphemes in a given string
+ * @param value - A string to count graphemes.
+ * @returns The number of graphemes in `value`.
+ */
 declare function getStringLength(value: string): number;
 //#endregion
 //#region src/string/ensurePrefix.d.ts
@@ -840,67 +938,67 @@ declare function ensureSuffix(input: string, suffix: string): string;
 //#endregion
 //#region src/string/getSimilarity.d.ts
 /**
-* @copyright {@link https://github.com/stephenjjbrown/string-similarity-js}
-*/
+ * @copyright {@link https://github.com/stephenjjbrown/string-similarity-js}
+ */
 interface GetStringSimilarityOptions {
   /**
-  * The length of the slice to compare.
-  * @default 2
-  */
+   * The length of the slice to compare.
+   * @default 2
+   */
   sliceLength?: number;
   /**
-  * Whether to ignore case when comparing strings.
-  * @default false
-  */
+   * Whether to ignore case when comparing strings.
+   * @default false
+   */
   caseSensitive?: boolean;
 }
 declare function getStringSimilarity(str1: string, str2: string, options?: GetStringSimilarityOptions): number;
 //#endregion
 //#region src/constants/char.d.ts
 /**
-* Special chars
-*/
+ * Special chars
+ */
 declare const SPECIAL_CHAR: {
   /**
-  * 中文顿号
-  */
+   * 中文顿号
+   */
   chineseComma: string;
   /**
-  * 英文逗号
-  */
+   * 英文逗号
+   */
   englishComma: string;
   /**
-  * 英文句号
-  */
+   * 英文句号
+   */
   englishPeriod: string;
   /**
-  * 连接符
-  */
+   * 连接符
+   */
   hyphen: string;
   /**
-  * 换行
-  */
+   * 换行
+   */
   newline: string;
   /**
-  * 空格
-  */
+   * 空格
+   */
   whitespace: string;
 };
 //#endregion
 //#region src/constants/regexp.d.ts
 /**
-* 注释正则
-*
-* 匹配 \<!-- 或 /* 开头的注释，直到 --> 或 *\/ 结尾
-*/
+ * 注释正则
+ *
+ * 匹配 \<!-- 或 /* 开头的注释，直到 --> 或 *\/ 结尾
+ */
 declare const RE_COMMENTS: RegExp;
 /**
-* JavaScript line comment
-*/
+ * JavaScript line comment
+ */
 declare const RE_LINE_COMMENT: RegExp;
 /**
-* JavaScript block comment
-*/
+ * JavaScript block comment
+ */
 declare const RE_BLOCK_COMMENT: RegExp;
 //#endregion
-export { AnyFn, Arrayable, Awaitable, Callable, CleanObjectOptions, Color, CreatePadStringOptions, DeepRequired, ElementOf, GetStringSimilarityOptions, InteropModuleDefault, JsonArray, JsonObject, JsonPrimitive, JsonValue, LiteralUnion, MayBe, Merge, NOOP, NonEmptyObject, NonEmptyString, Nullable, OpenExternalURLOptions, Overwrite, Prettify, PrettifyV2, Primitive, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, RamdomNumberOptions, ResolvedOptions, SPECIAL_CHAR, STORAGE_UNITS, SortObjectOptions, StorageUnit, TIME_UNITS, ThrottleDebounceOptions, TimeUnit, ToIntegerOptions, UrlString, ValueOf, Whitespace, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, flattenArrayable, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, removeFileExtension, resolveSubOptions, scrollElementIntoView, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };
+export { AnyFn, Arrayable, Awaitable, Callable, CleanObjectOptions, Color, CreatePadStringOptions, DeepRequired, ElementOf, FlatTreeOptions, GetStringSimilarityOptions, InteropModuleDefault, JsonArray, JsonObject, JsonPrimitive, JsonValue, LiteralUnion, MayBe, Merge, NOOP, NonEmptyObject, NonEmptyString, Nullable, OpenExternalURLOptions, Overwrite, Prettify, PrettifyV2, Primitive, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, RamdomNumberOptions, ResolvedOptions, SPECIAL_CHAR, STORAGE_UNITS, SortObjectOptions, StorageUnit, TIME_UNITS, ThrottleDebounceOptions, TimeUnit, ToIntegerOptions, UrlString, ValueOf, Whitespace, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, escapeStringRegexp, flatTree, flattenArrayable, getFileExtension, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isKeyOf, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPlainObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, remove, removeFileExtension, resolveSubOptions, scrollElementIntoView, shuffle, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };