@ntnyq/utils 0.6.4 → 0.7.0

package/dist/index.d.cts

@@ -1,621 +0,0 @@
-/**
- * A function that does nothing.
- */
-declare function noop(): void;
-/**
- * Alias of {@link noop}.
- */
-declare const NOOP: typeof noop;
-
-declare function once<T extends unknown[]>(func: (...args: T) => void): (this: unknown, ...args: T) => boolean;
-
-/**
- * @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;
-
-/**
- * @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>;
-
-/**
- * check if two values are deeply equal
- */
-declare function isDeepEqual(value1: any, value2: any): boolean;
-
-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;
-
-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;
-
-/**
- * A literal type that supports custom further strings but preserves autocompletion in IDEs.
- *
- * @see https://github.com/microsoft/TypeScript/issues/29729#issuecomment-471566609
- */
-type LiteralUnion<Union extends Base, Base = string> = Union | (Base & {
-    zz_IGNORE_ME?: never;
-});
-/**
- * Non empty object `{}`
- */
-type NonEmptyObject<T> = T extends Record<string, never> ? never : T;
-
-/**
- * interop module
- */
-type InteropModuleDefault<T> = T extends {
-    default: infer U;
-} ? U : T;
-
-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 PrimitiveType = bigint | boolean | number | string | symbol | null | undefined;
-/**
- * Resolve `boolean | Record<string, any>` to `Record<string, any>`
- */
-type ResolvedOptions<T> = T extends boolean ? never : NonNullable<T>;
-
-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;
-
-/**
- * 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;
-
-/**
- * @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;
-
-/**
- * Escape html chars
- */
-declare function escapeHTML(str: string): string;
-/**
- * Unescape html chars
- */
-declare function unescapeHTML(str: string): string;
-
-/**
- * @file raf.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;
-
-/**
- * @file time utils
- * @module Time
- */
-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;
-
-/**
- * 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;
-
-/**
- * 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>;
-
-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;
-};
-
-/**
- * Warn message only once
- *
- * @param message - warning message
- */
-declare function warnOnce(message: string): void;
-
-/**
- * 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;
-
-/**
- * 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[][];
-
-/**
- * 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[];
-
-/**
- * Converts a value to an array.
- * @param array - The value to convert.
- * @returns The array.
- */
-declare function toArray<T>(array?: Nullable<Arrayable<T>>): 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 | 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>;
-
-/**
- * Get intersect items
- *
- * @returns intersect items
- */
-declare function intersect<T>(a: T[], b: T[]): T[];
-
-/**
- * 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;
-
-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;
-}
-
-/**
- * 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;
-
-/**
- * enhance object
- * @module proxy
- */
-declare function enhance<T extends Record<PropertyKey, any>, E extends Record<PropertyKey, any>>(module: T, extra: E): T;
-
-/**
- * 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>>;
-
-/**
- * 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]>>;
-
-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;
-
-declare function omit<T, K extends keyof T>(object: T, ...keys: K[]): Omit<T, K>;
-
-declare function pick<T, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
-
-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;
-
-/**
- * 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;
-
-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;
-
-interface CreatePadStringOptions {
-    length: number;
-    char: string;
-}
-declare function createPadString(options: CreatePadStringOptions): (value: string) => string;
-
-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;
-
-/**
- * Replace backslash to slash
- */
-declare function slash(input: string): 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;
-
-/**
- * Default slugify function
- */
-declare function slugify(str: string): string;
-
-/**
- * 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;
-
-declare function ensurePrefix(input: string, prefix: string): string;
-
-declare function ensureSuffix(input: string, suffix: string): string;
-
-/**
- * Special chars
- */
-declare const SPECIAL_CHAR: {
-    newline: string;
-};
-
-/**
- * 注释正则
- *
- * 匹配 \<!-- 或 /* 开头的注释，直到 --> 或 *\/ 结尾
- */
-declare const RE_COMMENTS: RegExp;
-/**
- * JavaScript line comment
- */
-declare const RE_LINE_COMMENT: RegExp;
-/**
- * JavaScript block comment
- */
-declare const RE_BLOCK_COMMENT: RegExp;
-
-export { type AnyFn, type Arrayable, type Awaitable, type Callable, type CleanObjectOptions, Color, type CreatePadStringOptions, type InteropModuleDefault, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type LiteralUnion, type MayBe, NOOP, type NonEmptyObject, type NonEmptyString, type Nullable, type OpenExternalURLOptions, type Overwrite, type Prettify, type PrettifyV2, type PrimitiveType, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, type RamdomNumberOptions, type ResolvedOptions, SPECIAL_CHAR, type SortObjectOptions, type ThrottleDebounceOptions, type Whitespace, at, cAF, chunk, clamp, cleanObject, createPadString, days, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, flattenArrayable, getObjectType, 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, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce, weeks };