@ntnyq/utils 0.6.5 → 0.7.0

package/dist/index.d.cts

@@ -1,763 +0,0 @@
-//#region src/fn/noop.d.ts
-/**
-* A function that does nothing.
-*/
-declare function noop(): void;
-/**
-* Alias of {@link noop}.
-*/
-declare const NOOP: typeof noop;
-
-//#endregion
-//#region src/fn/once.d.ts
-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
-*/
-/**
-* 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 = " ";
-type NonEmptyString = string & {
-  0: "";
-};
-declare function getObjectType(value: unknown): string;
-declare function isUndefined(value: unknown): value is undefined;
-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 isNonEmptyString(value: unknown): value is NonEmptyString;
-declare function isWhitespaceString(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;
-declare function isNaN(value: unknown): value is typeof Number.NaN;
-declare function isInteger(value: unknown): value is number;
-declare function isBigInt(value: unknown): value is bigint;
-declare function isBoolean(value: unknown): value is boolean;
-declare function isTruthy<T>(value: T | undefined): value is T;
-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 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>;
-declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
-declare function isIterable<T = unknown>(value: unknown): value is Iterable<T>;
-
-//#endregion
-//#region src/is/isDeepEqual.d.ts
-/**
-* 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`
-  */
-  parent?: HTMLElement;
-}
-/**
-* 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
-type AnyFn<T = any, R = any> = (...args: T[]) => R;
-type Arrayable<T> = T | T[];
-type Awaitable<T> = Promise<T> | T;
-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> = Pick<T, Exclude<keyof T, keyof U>> & U;
-/**
-* 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;
-
-//#endregion
-//#region src/types/deep.d.ts
-type DeepRequired<T> = T extends Primitive ? NonNullable<T> : { [P in keyof T]-?: T[P] extends (infer U)[] ? DeepRequired<U>[] : T[P] extends readonly (infer V)[] ? NonNullable<V> : DeepRequired<T[P]> };
-
-//#endregion
-//#region src/types/json.d.ts
-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}
-*/
-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}
-*/
-type LiteralUnion<Union extends Base, Base = string> = Union | (Base & {
-  zz_IGNORE_ME?: never;
-});
-/**
-* @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 `{}`
-*/
-type NonEmptyObject<T> = T extends Record<string, never> ? never : T;
-
-//#endregion
-//#region src/types/module.d.ts
-/**
-* interop module
-*/
-type InteropModuleDefault<T> = T extends {
-  default: infer U;
-} ? U : T;
-/**
-* 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 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
-*/
-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
-*/
-declare const isBrowser: () => boolean;
-
-//#endregion
-//#region src/html/escape.d.ts
-/**
-* Escape html chars
-*/
-declare function escapeHTML(str: string): string;
-/**
-* Unescape html chars
-*/
-declare function unescapeHTML(str: string): string;
-
-//#endregion
-//#region src/misc/raf.d.ts
-/**
-* Request animation frame
-*
-* @param fn - callback
-* @returns id
-*/
-declare function rAF(fn: FrameRequestCallback): number;
-/**
-* Cancel animation frame
-*
-* @param id - id
-* @returns void
-*/
-declare function cAF(id: number): void;
-
-//#endregion
-//#region src/misc/time.d.ts
-declare function seconds(count: number): number;
-declare function minutes(count: number): number;
-declare function hours(count: number): number;
-declare function days(count: number): number;
-declare function weeks(count: number): number;
-
-//#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
-*/
-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
-* ```
-*/
-declare function waitFor(ms: number): Promise<void>;
-
-//#endregion
-//#region src/misc/throttle.d.ts
-interface ThrottleDebounceOptions {
-  /**
-  * @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
-*/
-declare function throttle<T extends ((...args: any[]) => undefined | void) | undefined | null>(delay: number, callback: Exclude<T, undefined | null>, options?: ThrottleDebounceOptions): T & {
-  cancel: () => void;
-};
-declare function debounce<T extends ((...args: any[]) => undefined | void) | undefined | null>(delay: number, callback: Exclude<T, undefined | null>, options?: ThrottleDebounceOptions): T & {
-  cancel: () => void;
-};
-
-//#endregion
-//#region src/misc/warnOnce.d.ts
-/**
-* Warn message only once
-*
-* @param message - warning message
-*/
-declare function warnOnce(message: string): void;
-
-//#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
-*/
-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
-*/
-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.
-*/
-declare function chunk<T>(array: T[], size: number): T[][];
-
-//#endregion
-//#region src/array/unique.d.ts
-/**
-* 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.
-*/
-declare function uniqueBy<T>(array: T[], equalFn: (a: T, b: T) => boolean): T[];
-
-//#endregion
-//#region src/array/toArray.d.ts
-/**
-* 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>;
-/**
-* Use rest arguments to merge arrays
-* @param args - rest arguments
-* @returns Array<T>
-*/
-declare function mergeArrayable<T>(...args: Nullable<Arrayable<T>>[]): Array<T>;
-
-//#endregion
-//#region src/array/intersect.d.ts
-/**
-* 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
-*/
-declare function isArrayEqual(array1: unknown[], array2: unknown[]): boolean;
-
-//#endregion
-//#region src/color/color.d.ts
-declare class Color {
-  red: number;
-  green: number;
-  blue: number;
-  alpha: number;
-  constructor(red?: number, green?: number, blue?: number, alpha?: number);
-  static fromRGB(red: number, green: number, blue: number): Color;
-  static fromRGBA(red: number, green: number, blue: number, alpha: number): Color;
-  static fromHex(hex: string): Color;
-  get brightness(): number;
-  get isDark(): boolean;
-  get isLight(): boolean;
-  toHexString(isUpperCase?: boolean): string;
-  toRGBAString(): string;
-  /**
-  * 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(percentage?: number): Color;
-  /**
-  * 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
-*/
-declare function randomRGBColor(): string;
-/**
-* get a random RGBA color
-* @returns a random RGBA color
-*/
-declare function randomRGBAColor(): string;
-/**
-* 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
-*/
-declare function enhance<T extends Record<PropertyKey, any>, E extends Record<PropertyKey, any>>(module: T, extra: E): T;
-
-//#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'))
-* ```
-*/
-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 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
-  */
-  includeMax?: boolean;
-}
-/**
-* 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
-  */
-  defaultValue?: number;
-  /**
-  * @default false
-  */
-  allowDecimal?: boolean;
-  /**
-  * @default false
-  */
-  allowNaN?: boolean;
-  /**
-  * @default `useDefault`
-  */
-  onError?: "useDefault" | "throwError" | "returnOriginal";
-  /**
-  * Minimum value of the number. included
-  */
-  min?: number;
-  /**
-  * Maximum value of the number. included
-  */
-  max?: number;
-  /**
-  * @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.
-*/
-declare function toInteger(value: unknown, options?: ToIntegerOptions): number;
-
-//#endregion
-//#region src/object/omit.d.ts
-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 extends keyof T>(object: T, keys: K[]): Pick<T, K>;
-
-//#endregion
-//#region src/object/clean.d.ts
-interface CleanObjectOptions {
-  /**
-  * clean undefined
-  *
-  * @default true
-  */
-  cleanUndefined?: boolean;
-  /**
-  * clean null
-  *
-  * @default true
-  */
-  cleanNull?: boolean;
-  /**
-  * clean zero
-  *
-  * @default false
-  */
-  cleanZero?: boolean;
-  /**
-  * clean NaN
-  *
-  * @default true
-  */
-  cleanNaN?: boolean;
-  /**
-  * clean empty string
-  *
-  * @default false
-  */
-  cleanEmptyString?: boolean;
-  /**
-  * clean empty array
-  *
-  * @default false
-  */
-  cleanEmptyArray?: boolean;
-  /**
-  * clean empty object
-  *
-  * @default false
-  */
-  cleanEmptyObject?: boolean;
-  /**
-  * 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
-*/
-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
-*/
-declare function hasOwn<T>(object: T, key: PropertyKey): boolean;
-
-//#endregion
-//#region src/object/sortObject.d.ts
-interface SortObjectOptions {
-  /**
-  * Recursive sorting
-  * @default false
-  */
-  deep?: boolean;
-  /**
-  * Compare function
-  */
-  compareFn?: (left: string, right: string) => number;
-}
-/**
-* Sort object properties
-*/
-declare function sortObject<T extends Record<string, any>>(obj: T, options?: SortObjectOptions): T;
-
-//#endregion
-//#region src/string/pad.d.ts
-interface CreatePadStringOptions {
-  length: number;
-  char: string;
-}
-declare function createPadString(options: CreatePadStringOptions): (value: string) => string;
-
-//#endregion
-//#region src/string/join.d.ts
-type JoinableValue = string | number | null | undefined;
-interface JoinOptions {
-  /**
-  * @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.
-*/
-declare function join(array: JoinableValue[], options?: JoinOptions): string;
-
-//#endregion
-//#region src/string/slash.d.ts
-/**
-* Replace backslash to slash
-*/
-declare function slash(input: 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
-*/
-declare function randomString(length?: number, chars?: string): string;
-
-//#endregion
-//#region src/string/slugify.d.ts
-/**
-* 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()
-*   }
-* `
-* ```
-*/
-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`.
-*/
-declare function getStringLength(value: string): number;
-
-//#endregion
-//#region src/string/ensurePrefix.d.ts
-declare function ensurePrefix(input: string, prefix: string): string;
-
-//#endregion
-//#region src/string/ensureSuffix.d.ts
-declare function ensureSuffix(input: string, suffix: string): string;
-
-//#endregion
-//#region src/constants/char.d.ts
-/**
-* Special chars
-*/
-declare const SPECIAL_CHAR: {
-  newline: string;
-};
-
-//#endregion
-//#region src/constants/regexp.d.ts
-/**
-* 注释正则
-*
-* 匹配 \<!-- 或 /* 开头的注释，直到 --> 或 *\/ 结尾
-*/
-declare const RE_COMMENTS: RegExp;
-/**
-* JavaScript line comment
-*/
-declare const RE_LINE_COMMENT: RegExp;
-/**
-* JavaScript block comment
-*/
-declare const RE_BLOCK_COMMENT: RegExp;
-
-//#endregion
-export { AnyFn, Arrayable, Awaitable, Callable, CleanObjectOptions, Color, CreatePadStringOptions, DeepRequired, 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, SortObjectOptions, ThrottleDebounceOptions, ToIntegerOptions, Whitespace, at, cAF, chunk, clamp, cleanObject, createPadString, days, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, flattenArrayable, getObjectType, getStringLength, hasOwn, hours, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isWhitespaceString, isZero, join, last, mergeArrayable, minutes, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, resolveSubOptions, scrollElementIntoView, seconds, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce, weeks };