@superutils/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1320 @@
+/**
+ * Defines an async function
+ */
+type AsyncFn<TOut = unknown, TArgs extends unknown[] = []> = (...args: TArgs) => Promise<Awaited<TOut>>;
+/**
+ * Create a tuple of specific type with given length
+ * ---
+ * @example Create a new tuple
+ * ```typescript
+ * type CreatedTuple =  CreateTuple<number, 3>
+ * // Result: [number, number, number]
+ * ```
+ *
+ * @example Create a new tuple by extending an existing tuple
+ * ```typescript
+ * type ExtendedTuple = CreateTuple<string, 6, CreatedTuple>
+ * // Result: [number, number, number, string, string, string]
+ * ```
+ */
+type CreateTuple<T, Length extends number, Output extends readonly unknown[] = []> = Output['length'] extends Length ? Output : CreateTuple<T, Length, [...Output, T]>;
+/**
+ * A recursive helper type that defines the signature of the curry function.
+ * @template TParams The tuple of remaining parameters.
+ * @template TData The final return type.
+ */
+type Curry<TData, TParams extends unknown[]> = <TArgs extends unknown[]>(...args: TArgs & KeepFirstN<TParams, TArgs['length']>) => DropFirstN<TParams, TArgs['length']> extends [unknown, ...unknown[]] ? Curry<TData, DropFirstN<TParams, TArgs['length']>> : TData;
+/**
+ * Deferred function config
+ */
+interface DeferredConfig<ThisArg = unknown> {
+    leading?: boolean | 'global';
+    onError?: (err: unknown) => ValueOrPromise<unknown>;
+    thisArg?: ThisArg;
+    tid?: TimeoutId;
+}
+/**
+ * Drop the first item from an array/tuple and keep the rest
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: string, second: number, third: boolean]
+ * type MyTupleWOFirst = DropFirst<MyTuple> // result: [second: number, third: boolean]
+ * ```
+ */
+type DropFirst<T extends unknown[]> = T extends [unknown, ...infer Rest] ? Rest : [];
+/**
+ * Drop first N items from an array/tuple and keep the rest
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: string, second: number, third: boolean]
+ * type MyTupleWO2 = DropFirstN<MyTuple, 2> // result: [third: boolean]
+ * ```
+ */
+type DropFirstN<T extends unknown[], N extends number, Dropped extends unknown[] = []> = TupleMaxLength<Dropped> extends N ? T : T extends [infer First, ...infer Rest] ? DropFirstN<Rest, N, [...Dropped, First]> : never;
+/**
+ * Drop the last item from an array/tuple and keep the rest
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: string, second: number, third: boolean]
+ * type MyTupleWOLast = DropLast<MyTuple> // result: [first: string, second: number]
+ * ```
+ */
+type DropLast<T extends unknown[]> = T extends [...infer Rest, unknown] ? Rest : [];
+type IsFiniteTuple<T extends unknown[]> = number extends T['length'] ? false : true;
+type IsOptional<T, K extends keyof T> = {} extends Pick<T, K> ? true : false;
+/**
+ * Keep the first item from an array/tuple and drop the rest
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: string, second: number, third: boolean]
+ * type MyTupleWFirst = KeepFirst<MyTuple> // result: [first: string]
+ * ```
+ */
+type KeepFirst<T extends unknown[]> = T extends readonly [
+    infer First,
+    ...DropFirst<T>
+] ? [First] : never;
+/**
+ * Keep first N items from an array/tuple and drop the rest
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: string, second: number, third: boolean]
+ * type MyTupleWith1st2 = KeepFirstN<MyTuple, 2> // result: [first: string, second: number]
+ * ```
+ */
+type KeepFirstN<T extends readonly unknown[], N extends number = 1> = TupleMaxLength<T> extends N ? T : T extends readonly [...infer TWithoutLast, unknown] ? KeepFirstN<TWithoutLast, N> : never;
+/**
+ * Extract optional members of a tuple.
+ *
+ * @template Tuple  tuple
+ * @template Require (optional) if true, all returned member of the returned tuple will be required field and TAlt will be added as union.
+ * Defaults to `false`
+ * @template TAlt   (optional) Defaults to `undefined`
+ *
+ * @example usage
+ * ```typescript
+ * import { KeepOptionals } from '@superutils/core
+ * type MyTuple = [first: string, second?: number, third?: boolean]
+ * type Optionals = KeepOptionals<MyTuple>
+ * // Result: [second?: number, third?: boolean]
+ * type AsRequired = KeepOptionals<MyTuple, true>
+ * // Result: [second: number | undefined, third: boolean | undefined]
+ * type AsRequiredWNull = KeepOptionals<MyTuple, true, null>
+ * // Result: [second: number | null, third: boolean | null]
+ * ```
+ */
+type KeepOptionals<Tuple extends unknown[], Require extends true | false = false, TAlt = undefined> = Require extends true ? Required<DropFirstN<Tuple, Tuple['length']>> extends [...infer Optionals] ? TupleWithAlt<Optionals, TAlt> : never : DropFirstN<Tuple, Tuple['length']>;
+/**
+ * Extract all required members of a tuple
+ */
+type KeepRequired<T extends unknown[]> = KeepFirstN<Required<T>, // force all members to be required to avoid getting `never` because of optional members
+MinLength<T>>;
+type MinLength<T extends unknown[], Count extends unknown[] = []> = T extends [infer F, ...infer R] ? undefined extends F ? MinLength<R, Count> : MinLength<R, [...Count, unknown]> : Count['length'];
+/** Make T1 optional if T2 is undefined */
+type OptionalIf<T1, T2, T2IF = undefined, T1Alt = undefined> = T2 extends T2IF ? T1 : T1 | T1Alt;
+type MakeOptional<Tuple extends unknown[], IndexStart extends number, IndexEnd extends number = TupleMaxLength<Tuple>> = Tuple extends readonly [
+    ...infer Left,
+    ...Slice<Tuple, IndexStart, IndexEnd>,
+    ...infer Right
+] ? [...Left, ...Partial<Slice<Tuple, IndexStart>>, ...Right] : never;
+/**
+ * Create a new slices tuple from an existing tuple
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [a: string, b: boolean, c: number, d: Record<string, unknown>]
+ * type FirstHalf = Slice<MyTuple, 0, 2>
+ * type LastHalf = Slice<MyTuple, 2>
+ * ```
+ */
+type Slice<Tuple extends unknown[], IndexStart extends number, IndexEnd extends number = TupleMaxLength<Tuple>> = [...KeepRequired<Tuple>, ...KeepOptionals<Tuple, true>] extends [
+    ...infer All
+] ? DropFirstN<KeepFirstN<All, IndexEnd>, IndexStart> extends [
+    ...infer Sliced
+] ? Sliced : never : never;
+type TimeoutId = Parameters<typeof clearTimeout>[0];
+/**
+ * Get the maximum possible length of a tuple
+ *
+ * This is particularly useful when a tuple (or function paramenters) contains optional members.
+ *
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [string, number?, boolean?]
+ * type Lengths = MyTuple['length'] // 1 | 2 | 3 // union because of optional parameters
+ * type MaxLength = TupleMaxLength<MyTuple> // 3
+ * ```
+ */
+type TupleMaxLength<T extends readonly unknown[]> = Required<T>['length'];
+/**
+ * Add alt type to all members of a tuple.
+ *
+ * ---
+ * @example usage
+ * ```typescript
+ * type MyTuple = [first: boolean, second: string]
+ * type MyTupleWithUndefined = TupleWithAlt<MyTuple>
+ * // Result: [first: boolean | undefined, second: string | undefined]
+ * type MyTupleWithNull = TupleWithAlt<MyTuple, null>
+ * // Result: [first: boolean | null, second: string | null]
+ * ```
+ */
+type TupleWithAlt<Tuple extends unknown[], TAlt = undefined> = {
+    -readonly [K in keyof Tuple]: Tuple[K] | TAlt;
+};
+/**
+ * Accept value or a function that returns the value
+ *
+ * Examples:
+ * ---
+ * @example usage
+ * ```typescript
+ * import { isFn, ValueOrFunc } from '@superutils/core'
+ * const print = (value: ValueOrFunc<string>) => isFn(value)
+ *  ? value()
+ *  : value
+ * print('Print me!')
+ * print(() => 'Print me too!')
+ * ```
+ */
+type ValueOrFunc<Value, Args extends unknown[] = []> = Value | ((...args: Args) => Value);
+/** Accept value a promise resolving to value */
+type ValueOrPromise<T> = T | Promise<T>;
+
+/**
+ * Creates a curried version of a function. The curried function can be
+ * called with one or more or all arguments at a time. Once all arguments have been
+ * supplied, the original function is executed.
+ *
+ * ---
+ *
+ * PS:
+ * ---
+ * To get around Typescript's limitations, all optional parameters to will be
+ * turned required and unioned with `undefined`.
+ *
+ * ---
+ *
+ * @param func The function to curry.
+ * @returns A new, curried function that is fully type-safe.
+
+ *
+ * @example Convert any function into a curried function
+ * ```typescript
+ * const func = (
+ *     first: string,
+ *     second: number,
+ *     third?: boolean,
+ *     fourth?: string
+ * ) => `${first}-${second}-${third}-${fourth}`
+ * // We create a new function from the `func()` function that acts like a type-safe curry function
+ * // while also being flexible with the number of arguments supplied.
+ * const curriedFunc = curry(func)
+ *
+ * // Example 1: usage like a regular curry function and provide one argument at a time.
+ * // Returns a function expecting args: second, third, fourth
+ * const fnWith1 = curriedFunc('first')
+ * // Returns a function expecting args: third, fourth
+ * const fnWith2 = fnWith1(2)
+ * // returns a function epecting only fourth arg
+ * const fnWith3 = fnWith2(false)
+ * // All args are now provided, the original function is called and result is returned.
+ * const result = fnWith3('last')
+ * ```
+ *
+ * @example Flexible curried function arguments
+ * ```typescript
+ * // Provide as many arguments as you wish. Upto the limit of the original function.
+ * // Returns a function expecting only the remaining argument(s)
+ * const fnWith3 = curriedFunc('first', 2, false)
+ * // All args provided, returns the result
+ * const result = fnWith3('last')
+ * ```
+ *
+ * @example Early invocation using "arity".
+ * Useful when a function has
+ *  - non-finite arguments (eg: number[])
+ *  - optional arguments and you do not want to avoid one or more optional arguments
+ * ```typescript
+ * const curriedWArity3 = curry(func, 3)
+ * const result = curriedWArity3('first', 2, false)
+ * ```
+ */
+declare function curry<TData, TArgs extends unknown[], TArgsIsFinite extends boolean = IsFiniteTuple<TArgs>, TArity extends TArgs['length'] = TArgsIsFinite extends true ? TupleMaxLength<TArgs> : number>(func: (...args: TArgs) => TData, ...[arity]: TArgsIsFinite extends true ? [arity?: TArity] : [
+    arity: TArity
+]): Curry<TData, CurriedArgs<TArgs, TArgsIsFinite, (...args: TArgs) => TData, TArity>>;
+type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc extends (...args: any[]) => unknown, TArity extends number> = TArgsIsFinite extends false ? CreateTuple<Parameters<TFunc>[number], TArity> : KeepFirstN<[
+    ...KeepRequired<TArgs>,
+    ...KeepOptionals<TArgs, true, undefined>
+], TArity>;
+
+/**
+ * @function deferred AKA debounce
+ * @summary returns a function that invokes the callback function after certain delay/timeout.
+ * All errors will be gracefully swallowed.
+ *
+ * @param	callback 	function to be invoked after timeout
+ * @param	delay		(optional) timeout duration in milliseconds. Default: 50
+ * @param   config.onError (optional)
+ * @param   config.leading (optional) if true, will enable leading-edge debounce mechanism.
+ * @param   config.thisArg (optional) the special `thisArgs` to be used when invoking the callback.
+ * @param	config.tid	   (optional) Timeout Id. If provided, will clear the timeout on first invocation.
+ *
+ * @example Debounce function calls
+ * ```typescript
+ * import { deferred } from '@superutils/core'
+ *
+ * const handleChange = deferred(
+ *     event => console.log(event.target.value),
+ *     300 // debounce delay in milliseconds
+ * )
+ *
+ * handleChange({ target: { value 1 } }) // will be ignored
+ * handleChange({ target: { value 2 } }) // will be ingored
+ * handleChange({ target: { value 3 } }) // will be invoked
+ * ```
+ *
+ *
+ */
+declare const deferred: {
+    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: DeferredConfig<ThisArg>): (...args: TArgs) => void;
+    defaults: {
+        /**
+         * Set the default value of argument `leading` for the `deferred` function.
+         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+         */
+        leading: false;
+        /**
+         * Set the default value of argument `onError` for the `deferred` function.
+         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+         */
+        onError: undefined;
+    };
+};
+
+/** Super for `deferred()` function */
+declare function debounce(...args: Parameters<typeof deferred>): (...args: unknown[]) => void;
+
+/**
+ * If `T` is a promise turn it into an union type by adding the value type
+ */
+type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
+/**
+ * @function fallbackIfFails
+ * @summary a flexible try-catch wrapper for invoking functions and ignore errors gracefully.
+ * Yes, the goal of `fallbackIfFails` is to ignore all runtime errors
+ * and ensure there's always a value returned.
+ *
+ * ---
+ *
+ * `fallbackValue` PS:
+ *
+ * 1. If function provided and Error is thrown it will not be caught.
+ * A fallback of the fallback is out of the scope of this function.
+ * 2. If `target` a promise or async function, `fallbackValue` must either be a promise or resolve to a promise
+ *
+ * ---
+ *
+ * @param target        promise or function to execute
+ * @param args			arguments to be supplied to `func` fuction
+ * @param fallbackValue alternative value to be used when target throws error.
+ *
+ * @returns if func is a promise the return a promise
+ *
+ * Examples:
+ * ---
+ * @example Async functions
+ * Working with async functions or functions that returns a promise
+ * ```typescript
+ * const args = ['some value', true] as const
+ * const ensureValue = async (value: string, criteria?: boolean) => {
+ *     if (criteria !== false && !value.trim()) throw new Error('No value. Should use fallback value')
+ *     return value
+ * }
+ * // This makes sure there's always a value without having to manually write try-catch block.
+ * const value = await fallbackIfFails(
+ *     ensureValue,
+ *     () => args,
+ *     async () => 'fallback value'
+ * )
+ * ```
+ *
+ * @example Non-async functions
+ * Working synchronous function that returns value synchronously
+ * ```typescript
+ * const args = ['some value', true] as const
+ * const ensureValue = (value: string, criteria?: boolean) => {
+ *     if (criteria !== false && !value.trim()) throw new Error('No value. Should use fallback value')
+ *     return value
+ * }
+ * // this makes sure there's always a value without having to manually write try-catch block.
+ * const value = fallbackIfFails(
+ *     ensureValue,
+ *     () => args,
+ *     () => 'fallback value'
+ * )
+ * ```
+ *
+ * @example Hybrid functions
+ * Working with function that returns value sync/async circumstantially
+ * ```typescript
+ * const getData = (useCache = true, cacheKey = 'data-cache') => {
+ *     if (useCache && localStorage[cacheKey]) return localStorage[cacheKey]
+ *     return fetch('https://my.domain.com/api')
+ *         .then(r => r.json())
+ *         .then(data => {
+ * 		       if(cacheKey) localStorage[cacheKey] = data
+ *             return data
+ *         })
+ * }
+ * // First call: no cache, will execute fetch and return a promise
+ * const first = await fallbackIfFails(getData, [false], {})
+ * // Second call: cache available and will return data synchronously
+ * const second = fallbackIfFails(getData, [true], {})
+ * ```
+ */
+declare const fallbackIfFails: <T, TArgs extends unknown[] = unknown[]>(target: T | ((...args: TArgs) => T), args: TArgs | (() => TArgs), fallbackValue: IfPromiseAddValue<T> | ((reason: unknown) => IfPromiseAddValue<T>)) => T;
+
+/** Cast a value as `any` type to bypass type check. Use with caution. */
+declare const asAny: <T = any>(x: unknown) => T;
+/** Force cast one type into another to bypass type checks. Use with caution. */
+declare const forceCast: <T>(x: unknown) => T;
+
+/** Check if value is an array */
+declare const isArr: <Item = unknown>(x: unknown) => x is Item[];
+/**
+ * Check if value is an array of objects
+ */
+declare const isArrObj: <K extends PropertyKey, V, T extends Record<K, V>[]>(x: unknown, strict?: boolean) => x is T[];
+/** Check if argument is a 2-dimentional array */
+declare const isArr2D: <Item = unknown>(x: unknown) => x is Item[][];
+/** Check if value is convertible to an array by using `Array.from(x)` */
+declare const isArrLike: (x: any) => x is typeof x extends (infer Value)[] ? Value[] : typeof x extends Set<infer Value> ? Set<Value> : typeof x extends Map<infer Key, infer Value> ? Map<Key, Value> : never;
+/**
+ * Check if value is convertible to an array by using `Array.from(x)` even if it comes from a different realm
+ * (eg: iframe, iframes, worker contexts, node vm contexts, browser extensions).
+ *
+ * Caution: much slower than {@link isArrLike()} due to use of `Object.prototype.toString.call()`
+ */
+declare const isArrLikeSafe: <T = unknown, MapKey = unknown>(x: unknown) => x is Set<T> | Map<MapKey, T> | T[];
+/** Check if all values in the array are unique */
+declare const isArrUnique: <T = unknown>(arr: T[]) => boolean;
+/** Check if value is instance of Uint8Array */
+declare const isUint8Arr: (arr: unknown) => arr is Uint8Array<ArrayBufferLike>;
+
+/** Check if value is instance of Date */
+declare const isDate: (x: unknown) => x is Date;
+/**
+ * Check if a value is a valid date.
+ *
+ * @param   date The value to check. Can be a Date object or a string.
+ *
+ * @returns `true` if the value is a valid date, `false` otherwise.
+ */
+declare const isDateValid: (date: unknown) => boolean;
+
+/**
+ * Check if variable contains empty, null-ish value.
+ *
+ * Depending on the type certain criteria applies:
+ * - `null` | `undefined`: always empty
+ * - `String`: empty text or only white-spaces
+ * - `Number`: non-finite or NaN
+ * - `Array` | `Uint8Array` | `Map` | `Set` | `Object`: contains zero items/properties
+ * - `Boolean` | `Function` | `Symbol` | `BigInt`: never empty
+ *
+ * @param x The value to check for emptiness.
+ * @param nonNumerable (optional) when `true`, considers non-enumerable properties
+ * while checking objects for emptiness. Default: `false`
+ * @param fallback (optional) value to return when type is unrecognized.
+ * Default: `false`
+ *
+ * @example Check strings
+ * ```typescript
+ * import { isEmpty } from '@superutils/core'
+ * isEmpty('') // true
+ * isEmpty(' ') // true
+ * isEmpty(`
+ *
+ *
+ * `) // true
+ * isEmpty('    not empty   ') // false
+ * isEmpty(`
+ *
+ *     not empty
+ *
+ * `) // false
+ * ```
+ *
+ * @example check numbers
+ * ```typescript
+ * import { isEmpty } from '@superutils/core'
+ * isEmpty(NaN) // true
+ * isEmpty(Infinity) // true
+ * isEmpty(0) // false
+ * ```
+ *
+ *
+ * @example check objects (includes arrays, maps & sets)
+ * ```typescript
+ * import { isEmpty } from '@superutils/core'
+ * isEmpty({}) // true
+ * isEmpty([]) // true
+ * isEmpty(new Map()) // true
+ * isEmpty(new Set()) // true
+ * ```
+ */
+declare const isEmpty: (x: unknown, nonNumerable?: boolean, fallback?: boolean | 0 | 1) => boolean | 0 | 1;
+/**
+ * Safe version of {@link isEmpty} with extended type checks and cross-realm handling.
+ *
+ * CAUTION: much slower than {@link isEmpty} due to use of Object.prototype.toString.call()
+ *
+ * Cross-realm means objects created in different JavaScript contexts.
+ * Eg: iframe, node vm context, worker context, browser extensions etc.
+ *
+ *
+ * @param x The value to check for emptiness.
+ *
+ * @returns `true` if the value is considered empty, `false` otherwise.
+ */
+declare const isEmptySafe: (x: unknown, numberableOnly?: boolean) => boolean | 1;
+
+/** Check if the environment is Browser */
+declare const isEnvBrowser: () => boolean;
+/** Check if the environment is NodeJS */
+declare const isEnvNode: () => boolean;
+/** Check if page is loaded on a touchscreen device */
+declare const isEnvTouchable: () => boolean;
+
+/** Check if value is a function */
+declare const isFn: <T extends (...args: any[]) => any>(x: unknown) => x is T;
+/**
+ * Check if value is an Async function.
+ * Caution: May not work at runtime when Babel/Webpack is used due to code compilation.
+ *
+ * ---
+ * @example usage
+ * ```typescript
+ * isAsyncFn(async () => {}) // result: true
+ * isAsyncFn(() => {}) // result: false
+ * ```
+ */
+declare const isAsyncFn: <TData = unknown, TArgs extends unknown[] = unknown[]>(x: unknown) => x is AsyncFn<TData, TArgs>;
+
+/** Check if value is instance of Map */
+declare const isMap: <TKey = unknown, TValue = unknown>(x: unknown) => x is Map<TKey, TValue>;
+/** Check if provided is a Map and all values are objects */
+declare const isMapObj: <K extends PropertyKey, V, T extends Record<K, V>>(x: unknown, strict?: boolean) => x is Map<K, V>;
+
+/** Check if value is an integer */
+declare const isInteger: (x: unknown) => x is number;
+/** Check if value is a positive integer */
+declare const isPositiveInteger: (x: unknown) => x is number;
+/** Check if value is a positive number */
+declare const isPositiveNumber: (x: unknown) => x is number;
+/** Check if value is a valid finite number */
+declare const isNumber: (x: unknown) => x is number;
+
+/**
+ * Check if value is an object.
+ *
+ *
+ * @param x value to check
+ * @param strict (optional) whether to exclude anything other than plain object. Eg: Array, Map, RegExp, Set etc.
+ *
+ * Default: `true`
+ *
+ * Valid objects:
+ * - object literals (Prototype: `Object.prototype`)
+ * - objects created using `Object.create(null)`
+ *
+ * Valid when strict mode off (false):
+ * - all of above
+ * - buit-in objects like Date, Error, Map, Set, Uint8Array etc
+ * - custom Class instances
+ * - objects created using `Object.create(object)`
+ *
+ * Always invalid:
+ * - `null`, `undefined`, `NaN`, `Infinity`
+ * - primitive: String, Number, BigInt...
+ *
+ * @example Examples
+ * ```typescript
+ * import { isObj } from '@superutils/core'
+ *
+ * console.log(isObj(null)) // false
+ * console.log(isObj(undefined)) // false
+ * console.log(isObj(NaN)) // false
+ * console.log(isObj(Infinity)) // false
+ * console.log(isObj({})) // true
+ * console.log(isObj({ a: 1, b: 2})) // true
+ * console.log(isObj(Object.create(null))) // true
+ * console.log(isObj(new Map())) // false (strict)
+ * console.log(isObj(new Map(), false)) // true (non-strict)
+ * console.log(isObj(new Error('error'))) // false (strict)
+ * console.log(isObj(new Error('error'), false)) // true (non-strict)
+ * class Test { a = 1 }) // a custom class
+ * console.log(isObj(new Test())) // false
+ * console.log(isObj(new Test(), false)) // true
+ * ```
+ */
+declare const isObj: <T = Record<PropertyKey, unknown>>(x: unknown, strict?: boolean) => x is T;
+
+/** Check if value is instance of URL */
+declare const isUrl: (x: unknown) => x is URL;
+/**
+ * Check if a value is a valid URL/string-URL.
+ *
+ * @param x The value to check.
+ * @param strict If true:
+ * - requires a domain name with a TLDs etc.
+ * - and x is string, catches any auto-correction (eg: trailing spaces being removed, spaces being replaced by `%20`)
+ * by `new URL()` to ensure string URL is valid
+ * Defaults to `true`.
+ * @param tldExceptions when in strict mode, treat these hosts as valid despite no domain name extensions
+ * Defaults to `['localhost']`
+ *
+ * @returns `true` if the value is a valid URL, `false` otherwise.
+ */
+declare const isUrlValid: (x: unknown, strict?: boolean, tldExceptions?: string[]) => boolean;
+
+/** Check if value is boolean */
+declare const isBool: (x: unknown) => x is boolean;
+/** Check if value is not undefined or null */
+declare const isDefined: <T = unknown>(x: T | undefined | null) => x is T;
+/** Check if value is instance of Error */
+declare const isError: (x: unknown) => x is Error;
+/** Check if value is a Promise */
+declare const isPromise: <T = unknown>(x: unknown) => x is Promise<T>;
+/** Check if value is a regular expession */
+declare const isRegExp: (x: unknown) => x is RegExp;
+/** Check if value is instance of Set */
+declare const isSet: <T = unknown>(x: unknown) => x is Set<T>;
+/** Check if value is string */
+declare const isStr: (x: unknown) => x is string;
+/** Check if value is a Symbol */
+declare const isSymbol: (x: unknown) => x is symbol;
+/**
+ * Compilation of all the compile-time & runtime utilities functions above
+ */
+declare const is: {
+    arr: <Item = unknown>(x: unknown) => x is Item[];
+    arr2D: <Item = unknown>(x: unknown) => x is Item[][];
+    arrLike: (x: any) => x is typeof x extends (infer Value)[] ? Value[] : typeof x extends Set<infer Value> ? Set<Value> : typeof x extends Map<infer Key, infer Value> ? Map<Key, Value> : never;
+    arrLikeSafe: <T = unknown, MapKey = unknown>(x: unknown) => x is Set<T> | Map<MapKey, T> | T[];
+    arrObj: <K extends PropertyKey, V, T extends Record<K, V>[]>(x: unknown, strict?: boolean) => x is T[];
+    arrUnique: <T = unknown>(arr: T[]) => boolean;
+    asyncFn: <TData = unknown, TArgs extends unknown[] = unknown[]>(x: unknown) => x is AsyncFn<TData, TArgs>;
+    bool: (x: unknown) => x is boolean;
+    date: (x: unknown) => x is Date;
+    dateValid: (date: unknown) => boolean;
+    defined: <T = unknown>(x: T | undefined | null) => x is T;
+    empty: (x: unknown, nonNumerable?: boolean, fallback?: boolean | 0 | 1) => boolean | 0 | 1;
+    emptySafe: (x: unknown, numberableOnly?: boolean) => boolean | 1;
+    envBrowser: () => boolean;
+    envNode: () => boolean;
+    envTouchable: () => boolean;
+    error: (x: unknown) => x is Error;
+    fn: <T extends (...args: any[]) => any>(x: unknown) => x is T;
+    integer: (x: unknown) => x is number;
+    map: <TKey = unknown, TValue = unknown>(x: unknown) => x is Map<TKey, TValue>;
+    mapObj: <K extends PropertyKey, V, T extends Record<K, V>>(x: unknown, strict?: boolean) => x is Map<K, V>;
+    number: (x: unknown) => x is number;
+    obj: <T = Record<PropertyKey, unknown>>(x: unknown, strict?: boolean) => x is T;
+    positiveInteger: (x: unknown) => x is number;
+    positiveNumber: (x: unknown) => x is number;
+    promise: <T = unknown>(x: unknown) => x is Promise<T>;
+    regExp: (x: unknown) => x is RegExp;
+    set: <T = unknown>(x: unknown) => x is Set<T>;
+    str: (x: unknown) => x is string;
+    symbol: (x: unknown) => x is symbol;
+    uint8Arr: (arr: unknown) => arr is Uint8Array<ArrayBufferLike>;
+    url: (x: unknown) => x is URL;
+    urlValid: (x: unknown, strict?: boolean, tldExceptions?: string[]) => boolean;
+};
+
+/** Placeholder function that does nothing */
+declare function noop(): void;
+declare function noopAsync(): Promise<void>;
+
+type ThrottleConfig<ThisArg = unknown> = {
+    onError?: (err: unknown) => ValueOrPromise<unknown>;
+    thisArg?: ThisArg;
+    trailing?: boolean;
+    tid?: TimeoutId;
+};
+/**
+ * @function throttle
+ * @summary returns a function that invokes the `callback` maximum twice (once if `executeLast = false`) per interval
+ *
+ * @param	callback function to be invoked after timeout
+ * @param	delay	 (optional) interval duration in milliseconds. Default: 50
+ * @param   config.onError  (optional)
+ * @param   config.tid      (optional)
+ * @param	config.thisArg  (optional) the special `thisArgs` to be used when invoking the callback.
+ * @param   config.trailing (optional) whether to enable trailing edge execution. Default: `true`
+ */
+declare const throttled: {
+    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: ThrottleConfig<ThisArg>): (...args: TArgs) => void;
+    /**
+     * Set the default values
+     * This change is applicable application-wide and only applies to any new invocation of `throttle()`.
+     */
+    defaults: {
+        onError: undefined;
+        trailing: true;
+    };
+};
+
+/**
+ * Convert timestamp to `input["datetime-local"]` compatible format.
+ *
+ * ---
+ * @example Convert ISO datetime string
+ * ```typescript
+ * toDatetimeLocal('2000-01-01T01:01:01.001Z')
+ * // result: "2000-01-01T01:01" // assuming local timezone is UTC+0
+ * ```
+ *
+ * @example Convert Date object
+ * ```typescript
+ * const date = new Date('2000-01-01T01:01:01.001Z')
+ * toDatetimeLocal(date)
+ * // result: "2000-01-01T01:01" // assuming local timezone is UTC+0
+ * ```
+ *
+ * @example Convert Unix Timestamp (epoch time) number
+ * ```typescript
+ * const epoch = new Date('2000-01-01T01:01:01.001Z').getTime()
+ * toDatetimeLocal(epoch)
+ * // result: "2000-01-01T01:01" // assuming local timezone is UTC+0
+ * ```
+ */
+declare const toDatetimeLocal: (dateStr: string | Date | number) => "" | `${number}-${number}-${number}T${number}:${number}`;
+
+/**
+ * Constructs a new object with only the supplied property names (keys) and their respective values
+ *
+ * @param obj
+ * @param keys property names to keep
+ * @param ignoreIfNotExist (optional) if truthy, will ignore non-existent `keys`. Default: `true`
+ */
+declare const objClean: <T extends Record<PropertyKey, unknown>, Key extends keyof T = keyof T>(obj: T, keys: Key[], ignoreIfNotExist?: boolean) => Record<Key, T[Key]>;
+
+/**
+ * Deep-copy an object to another object
+ *
+ * @param input input object
+ * @param ignoreKeys (optional) input peroperties to be ignored. Prevents output's property to be overriden.
+ *
+ * For child object properties use "." (dot) separated path.
+ *
+ * Eg: `"child.grandchild1"` where input is `{ child: { grandchild1: 1, grandchild2: 2 }}`
+ *
+ * @param output (optional) output object
+ * @param override (optional) whether to allow override output (if provided) properties.
+ * Accepted values:
+ * `true`: input property will override output property
+ * `false`: no overriding if output contains the property. Even if the property value is `undefined`.
+ * `"empty"`: only allow overriding output property if it's value is empty by using {@link isEmpty}.
+ *
+ * Default: `false`
+ *
+ *
+ * @returns copied and/or merged object
+ */
+declare const objCopy: <Key extends string | symbol, T extends Record<Key, unknown>, IgnoredKey extends Key | string>(input: T, output?: Record<PropertyKey, unknown>, ignoreKeys?: IgnoredKey[] | Set<IgnoredKey>, override?: boolean | "empty", recursive?: boolean) => Record<PropertyKey, unknown>;
+
+/**
+ * Creates an object from an array of keys and a corresponding array of values.
+ * It pairs each key with the value at the same index.
+ *
+ * @param keys An array of property keys (strings or symbols).
+ * @param values (optional) An array of property values. The value at each index corresponds to the key at the same index. If a value is missing for a key, it will be `undefined`.
+ * @param result (optional) An existing object to add or overwrite properties on. If not provided, a new object is created.
+ * @returns The newly created object, or the `result` object merged with the new properties.
+ *
+ * @example Creating a new object from keys and values
+ * ```typescript
+ * const keys = ['a', 'b', 'c'];
+ * const values = [1, 2, 3];
+ * const newObj = objCreate(keys, values);
+ * // newObj is { a: 1, b: 2, c: 3 }
+ * ```
+ *
+ * @example Merging into an existing object
+ * ```typescript
+ * const existingObj = { a: 0, d: 4 };
+ * const keys = ['b', 'c'];
+ * const values = [2, 3];
+ * objCreate(keys, values, existingObj);
+ * // existingObj is now { a: 0, d: 4, b: 2, c: 3 }
+ * ```
+ */
+declare const objCreate: <V, K extends PropertyKey, RV, RK extends PropertyKey, Result extends Record<K | RK, V | RV>>(keys?: K[], values?: V[], result?: Result) => Result;
+
+/**
+ * Get object property names/keys
+ *
+ * @param obj target object
+ * @param sorted (optional) Whether to sort the keys. Default: `true`
+ * @param includeSymbols (optional) Whether to include `Symbol` object. Default: `false`
+ */
+declare const objKeys: <T extends object, Include extends true | false = true>(obj: T, sorted?: boolean, includeSymbols?: Include) => Include extends true ? (keyof T)[] : (keyof T)[] & string[];
+
+type ReadOnlyAllowAddFn<T> = (obj: T, key: string | symbol, valule: unknown) => boolean;
+type ReadOnlyConfig<T, Revocable extends true | false = false> = {
+    /** Whether to allow adding new properties. Default: `false` */
+    add?: boolean | ReadOnlyAllowAddFn<T>;
+    /** Default: `false` */
+    revocable?: Revocable;
+    /** Whether to throw error when a write operation is rejected. Default: `true` */
+    silent?: boolean;
+};
+
+/**
+ * Constructs a new read-only object where only new properties can be added.
+ *
+ * Applies only to the top-level properties.
+ *
+ * @param obj input object
+ * @param config (optional) extra configuration
+ * @param config.add (optional) Whether to allow adding new properties. Default: `false`
+ * @param config.revocable (optional) Whether to create a revokable proxy. Default: `false`
+ * @param config.silent (optional) whether to throw error when a write operation is rejected. Default: `false`
+ *
+ * @returns	Readonly object or object containing readonly object and revoke function
+ */
+declare const objReadOnly: <T extends object | unknown[], Revocable extends true | false = false, Result = Revocable extends true ? ReturnType<typeof Proxy.revocable<T>> : T>(obj: T, config?: ReadOnlyConfig<T, Revocable>) => Result;
+
+/**
+ * Assign value to an object property
+ *
+ * @param obj
+ * @param key
+ * @param falsyValue (optional) Default: `obj[key]`
+ * @param condition	(optional)
+ * @param truthyValue (optional) value to use if condition is truthy
+ */
+declare const objSetProp: <K extends PropertyKey, V, OutKey extends K | string>(obj: Record<K, V>, key: OutKey, falsyValue?: V, condition?: boolean | ((value: V | undefined, key: OutKey, obj: Record<K, V>) => boolean), truthyValue?: V) => Record<OutKey, V>;
+/** Assign value to an object property only if current value is undefined */
+declare const objSetPropUndefined: (...[obj, key, ...args]: Parameters<typeof objSetProp>) => Record<PropertyKey, unknown>;
+
+/** create a new object with properties sorted by key */
+declare const objSort: <T>(obj: T, recursive?: boolean, _done?: Map<unknown, boolean>) => T;
+
+/**
+ * @function	objWithoutKeys
+ * @summary constructs a new object excluding specific properties
+ *
+ * @param	{Object}	input
+ * @param	{Array}		keys	property names to exclude
+ * @param	{Object}	output	(optional) to delete unwanted props from the original `input` use it here.
+ * 								Default: a copy of the `input` object
+ *
+ * @returns {Object}
+ */
+declare const objWithoutKeys: (input: unknown, keys: string[], output?: Record<PropertyKey, unknown>) => Record<PropertyKey, unknown>;
+
+/**
+ * Sugar for `objReadOnly()` for an Array
+ *
+ * @param arr
+ * @param config (optional)
+ * @param config.add (optional) Whether to allow adding new properties. Default: `false`
+ * @param config.revocable (optional) Default: `false`
+ * @param config.silent (optional) Whether to throw error when a write operation is rejected. Default: `true`
+ *
+ * @returns Readonly Array or object containing readonly Array and revoke function
+ */
+declare const arrReadOnly: <T>(arr: T[], config?: Omit<ReadOnlyConfig<T[]>, "revoke">) => T[];
+
+/**
+ * Helper class for creating read-only arrays.
+ *
+ * Caution: This class can by itself only make the array partially read-only.
+ * Use {@link arrReadOnly()} instead.
+ */
+declare class ReadOnlyArrayHelper<T> extends Array<T> {
+    readonly config: Omit<ReadOnlyConfig<T[]>, 'revoke'>;
+    constructor(config: Omit<ReadOnlyConfig<T[]>, 'revoke'>, arr: T[]);
+    private ignoreOrThrow;
+    pop: () => T;
+    push: (...items: T[]) => number;
+    reverse: () => this;
+    shift: () => T;
+    splice: (..._ignoredArgs: unknown[]) => never[];
+    unshift: (..._ignoredArgs: T[]) => number;
+    reduce: {
+        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
+        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
+        <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
+    };
+    reduceRight: {
+        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
+        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
+        <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
+    };
+}
+
+/**
+ * Reverse an array conditionally
+ *
+ * @param   arr
+ * @param	reverse	 (optional) condition to reverse the array. Default: `true`
+ * @param	newArray (optional) whether to cnstruct new array or use input. Default: `false`
+ *
+ * @returns array
+ */
+declare const arrReverse: <T = unknown>(arr: T[], reverse?: boolean, newArray?: boolean) => T[];
+
+/**
+ * Generate a Map from one or more arrays
+ *
+ * @param arr
+ * @param key (optional) Array object-item property name or a function to generate keys for each array items.
+ * @param flatDepth (optional) maximum recursion depth to flatten the array. Default: `0`
+ *
+ * @returns Converted Map
+ *
+ * @example Convert Array to Map
+ * ```typescript
+ * type Item = { a: number }
+ * const arr: Item[] = [{ a: 1 }, { a: 2 }, { a: 3 }, [{ a: 4 }]]
+ * const map: Map<number, Item> = arrToMap(
+ * 	   arr,
+ * 	   (_: Item, i: number) => item.a,
+ * )
+ *
+ * @example Flatten and convert Array to Map
+ * ```typescript
+ * type Item = { key: number; value: string }
+ * const arr: (Item | Item[])[] = [
+ * 	{ key: 1, value: 'a' },
+ * 	{ key: 2, value: 'b' },
+ * 	{ key: 3, value: 'c' },
+ * 	[{ key: 4, value: 'd' }],
+ * ]
+ * const map = arrToMap(arr, (item: Item) => item.key, 1) // Map<number, Item>
+ * ```
+ */
+declare function arrToMap<T extends unknown[], FlatDepth extends number = 0>(arr: T, flatDepth?: FlatDepth): Map<number, FlatArray<T, FlatDepth>>;
+declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, MapItem = FlatArray<T, FlatDepth>, MapKey = unknown>(arr: T, key: (item: MapItem, index: number, flatArr: MapItem[]) => MapKey, flatDepth?: FlatDepth): Map<MapKey, MapItem>;
+declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, MapItem = FlatArray<T, FlatDepth>, KeyProp extends keyof MapItem = keyof MapItem>(arr: T, key: KeyProp, flatDepth?: FlatDepth): Map<MapItem[KeyProp], MapItem>;
+
+/**
+ * @function	arrUnique
+ * @summary		constructs a new array of unique values
+ */
+declare const arrUnique: <T = unknown>(arr: T[], flatDepth?: number) => FlatArray<T, 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -1 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20>[];
+
+/** Configuration for finding {@link IterableList} items */
+type FindOptions<K, V, IncludeKey extends boolean = false> = Omit<SearchOptions<K, V>, 'limit' | 'asMap'> & {
+    /**
+     * Whether to include the key in the return type.
+     *
+     * If `true`, return type is `[K, V]` else `V`
+     *
+     * Default: `false`
+     */
+    includeKey?: IncludeKey;
+};
+/** A general type to capture all iterables like Array, Map, Set.... */
+type IterableList<K = unknown, V = unknown> = {
+    entries: () => IterableIterator<[K, V]>;
+    hasOwnProperty: (name: string) => boolean;
+    keys: () => IterableIterator<K>;
+    values: () => IterableIterator<V>;
+} & ({
+    clear: () => void;
+    size: number;
+} | {
+    length: number;
+});
+/** Configuration for sorting iterables */
+type SortOptions = {
+    ignoreCase?: boolean;
+    /**
+     * Whether to create a new instance of preserve original reference
+     *
+     * Default: `true` for Array, `false` for Map.
+     */
+    newInstance?: boolean;
+    /** Reverse sorted result */
+    reverse?: boolean;
+    /**
+     * Whether to place undefined/null values at the beginning of the sorted array.
+     *
+     * Default: `false`
+     */
+    undefinedFirst?: boolean;
+};
+/** Search criteria for searcheing iterables */
+type SearchOptions<K, V, AsMap extends boolean = false> = {
+    /** Whethere to return the result as a map (`true`) or array (`false`). Default: `true` */
+    asMap?: AsMap;
+    /** case-insensitive search for strings. Default: `false` */
+    ignoreCase?: boolean;
+    /** limit number of results. Default: `Infinity` */
+    limit?: number;
+    /** partial match for values. Default: `false` */
+    matchExact?: boolean;
+    /** match all supplied key-value pairs. Default: `false` */
+    matchAll?: boolean;
+    /** key-value pairs */
+    query: Record<string, unknown> | string | RegExp;
+    /** Map to store results in. Default: `new Map()` */
+    result?: Map<K, V>;
+    /** Callback to convert item/item-property to string */
+    transform?: (
+    /** List item */
+    item: V, 
+    /** Item property value or `undefined` for fuzzy search. */
+    value?: V[keyof V], 
+    /** Item property key provided by query or `undefined` for fuzzy search. */
+    key?: keyof V) => string | undefined;
+};
+
+/**
+ * Filter {@link IterableList} (Array, Map, Set) items.
+ *
+ * @param data
+ * @param predicate callback function to filter values
+ *
+ * @returns new Map with filtered items
+ *
+ * @example
+ * ```typescript
+ * import { filter } from '@superutils/core'
+ *
+ * const map = new Map<number, { name: string; age: number }>([
+ * 	[1, { name: 'Alice', age: 30 }],
+ * 	[2, { name: 'Bob', age: 25 }],
+ * 	[3, { name: 'Charlie', age: 35 }],
+ * ])
+ *
+ * const filtered = filter(map, item => item.age >= 30)
+ * // result: Map(2) {
+ * //   1 => { name: 'Alice', age: 30 },
+ * //   3 => { name: 'Charlie', age: 35 }
+ * // }
+ * ```
+ */
+declare const filter: <K, V, AsArray extends boolean = false, Result = AsArray extends true ? V[] : Map<K, V>>(data: IterableList<K, V>, predicate: (value: V, key: K, data: IterableList<K, V>) => boolean, limit?: number, asArray?: AsArray, result?: Map<K, V>) => Result;
+
+/**
+ * Finds a first item matching criteria in an {@link IterableList}.
+ *
+ * @returns first item matched or `undefined` if not found
+ *
+ * @example Find item using callback
+ * ```typescript
+ * import { find } from '@superutils/core'
+ *
+ * const map = new Map<number, { name: string; age: number }>([
+ * 	[1, { name: 'Alice', age: 30 }],
+ * 	[2, { name: 'Bob', age: 25 }],
+ * 	[3, { name: 'Charlie', age: 35 }],
+ * ])
+ * const result = mapFind(testMap, ({ name }) => name === 'Bob')
+ * // result: { name: 'Bob', age: 25 }
+ * ```
+ *
+ * @example Find item using search options
+ * ```typescript
+ * import { find } from '@superutils/core'
+ *
+ * const map = new Map<number, { name: string; age: number }>([
+ * 	[1, { name: 'Alice', age: 30 }],
+ * 	[2, { name: 'Bob', age: 25 }],
+ * 	[3, { name: 'Charlie', age: 35 }],
+ * ])
+ *	const result = mapFind(testmap, {
+ *		query: 'Bob',
+ *		key: 'name',
+ *	})
+ * // result: { name: 'Bob', age: 25 }
+ * ```
+ */
+declare function find<K, V extends Record<string, unknown>, IncludeKey extends boolean = false, Return = undefined | (IncludeKey extends true ? [K, V] : V)>(data: IterableList<K, V>, callback: Parameters<typeof filter<K, V>>[1]): Return;
+declare function find<K, V extends Record<string, unknown>, IncludeKey extends boolean = false, Return = undefined | (IncludeKey extends true ? [K, V] : V)>(data: IterableList<K, V>, options: FindOptions<K, V, IncludeKey>): Return;
+
+/** Map entries as array */
+declare const getEntries: <K, V>(map: Map<K, V>) => [K, V][];
+
+/** Get {@link IterableList} keys as array */
+declare const getKeys: <K, V>(data: IterableList<K, V>) => K[];
+
+/** Get size/length of Array/Map/Set */
+declare const getSize: (x: IterableList) => number;
+
+/** Get Map values as Array */
+declare const getValues: <K, V>(data: IterableList<K, V>) => V[];
+
+/**
+ * Reverse a {@link IterableList} (Array/Map/Set) conditionally
+ *
+ * @param   data
+ * @param	reverse	 (optional) condition to reverse the list. Default: `true`
+ * @param	newInstance (optional) whether to return a new instance of the list. Default: `false`
+ *
+ * @returns reversed data in original type or empty array for unsupported type
+ */
+declare const reverse: <K, V, T extends IterableList<K, V>>(data: T, reverse?: boolean, newInstance?: boolean) => V[] | [K, V][] | Map<K, V> | Set<V> | (T & Record<"clear", unknown>);
+
+/**
+ * A versatile utility for searching through an iterable list (e.g., Array, Map, Set) of objects.
+ * It supports both a simple "fuzzy" search with a string query across all properties and a
+ * detailed, field-specific search using a query object.
+ *
+ * @param data The list of objects to search within. Compatible types include:
+ * - `Array`
+ * - `Map`
+ * - `Set`
+ * - `NodeList` (in DOM environments): `options.transform()` required
+ * - `HTMLCollection` (in DOM environments): should accompany `options.transform()`
+ * @param options The search criteria.
+ * @param options.query The search query. Can be a string to search all fields, or an object for field-specific
+ * searches (e.g., `{ name: 'John', city: 'New York' }`).
+ * @param options.asMap (optional) If `true`, returns a `Map`. If `false`, returns an `Array`. Default: `true`.
+ * @param options.ignoreCase (optional) If `true`, performs a case-insensitive search for strings. Default: `true`.
+ * @param options.limit (optional) The maximum number of results to return. Default: `Infinity`.
+ * @param options.matchAll (optional) If `true`, an item must match all key-value pairs in the `query` object. If
+ * `false`, it matches if at least one pair is found. Default: `false`.
+ * @param options.matchExact (optional) If `true`, performs an exact match. If `false`, performs a partial match
+ * (i.e., `includes()`). Default: `false`.
+ * @param options.result (optional) An optional `Map` to which the results will be added.
+ * @param options.transform (optional) Callback to transform item/item-property to string
+ *
+ * @returns A `Map` or an `Array` containing the matched items, based on the `asMap` option.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { id: 1, name: 'John Doe', city: 'New York' },
+ *   { id: 2, name: 'Jane Doe', city: 'London' },
+ *   { id: 3, name: 'Peter Jones', city: 'New York' },
+ * ];
+ *
+ * // Simple string search (case-insensitive, partial match by default)
+ * const doeUsers = search(users, { query: 'doe' });
+ * // Returns: [{ id: 1, ... }, { id: 2, ... }]
+ *
+ * // Field-specific search, requiring all fields to match
+ * const peterInNY = search(users, {
+ *   query: { name: 'Peter', city: 'New York' },
+ *   matchAll: true,
+ * });
+ * // Returns: [{ id: 3, ... }]
+ * ```
+ */
+declare const search: {
+    <K, V, AsMap extends boolean = true, Result = AsMap extends true ? Map<K, V> : V[]>(data: IterableList<K, V>, options: SearchOptions<K, V, AsMap>): Result;
+    defaultOptions: Pick<Required<SearchOptions<unknown, unknown, true>>, "matchAll" | "limit" | "asMap" | "ignoreCase" | "matchExact">;
+};
+/** Utility for use with {@link search()} function */
+declare function matchItemOrProp<K, V>(// extends Record<string, unknown>
+{ query, ignoreCase, matchExact, transform, }: Pick<SearchOptions<K, V, boolean>, 'transform' | 'query' | 'ignoreCase' | 'matchExact'>, item: V, propertyName?: string): boolean;
+
+type SliceMapCallback<Data, Value, Key> = (item: Value, key: Key, data: Data) => Value;
+type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
+    /** Whether to return the result as a Map (preserving original keys) or an Array */
+    asMap?: AsMap;
+    /** callback to transform each item */
+    transform?: SliceMapCallback<Data, Value, Key>;
+    /** End index (exclusive). Default: `undefined` (end of the list) */
+    end?: number;
+    /** Whether to exclude item if value is `undefined | null` */
+    ignoreEmpty?: boolean;
+    /** Start index. Default: `0` */
+    start?: number;
+};
+/**
+ * Slice an iterable list and map the values into an Array/Map
+ *
+ * @param data		Array, Map, Set...
+ * @param start		Default: `0`
+ * @param end		(optional) last index - exclusive. Default: index of the last item
+ * @param callback	to be executed on each item within the set range.
+ *
+ * If callback throws error or returnes `undefined`, the item will be ignored.
+ *
+ * Callback Params:
+ *   - item: current item
+ *   - key: index/key of the current item
+ *   - data: original list
+ *
+ * @returns Array/Map
+ */
+declare const sliceMap: <Data extends IterableList, Key = Data extends IterableList<infer Key_1, unknown> ? Key_1 : never, Value = Data extends IterableList<unknown, infer Value_1> ? Value_1 : never, AsMap extends boolean = false>(data: Data, options?: SliceMapOptions<Data, Value, Key, AsMap> | SliceMapCallback<Data, Value, Key>) => AsMap extends false ? Value[] : Map<Key, Value>;
+
+type EntryComparator<K, V> = (a: [K, V], b: [K, V]) => number;
+type ArrayComparator<V> = (a: V, b: V) => number;
+/**
+ * Sort iterable lists (Array/Map/Set).
+ *
+ *
+ * @param data
+ * @param propertyName Accepted values:
+ * - `string`: value object property name
+ * - `function`: comparator function. Recommended for performance.
+ * - `true`: indicates to sort by Map keys instead of values.
+ * @param options (optional) extra sorting opitons
+ * @param options.ignoreCase	(optional) case-insensitive sort for strings. Default: `true`
+ * @param options.reverse (optional) True: accending sort. False: descending sort. Default: `false`
+ * @param options.undefinedFirst (optional) Where to place undefined/null values.
+ * Not avaible when `comparator` function is used.
+ * - `true`: at the beginning
+ * - `false`: at the end
+ *
+ * Default: `false`
+ *
+ * @returns sorted map
+ *
+ * @example sort map of simple values (string/number/boolean)
+ * ```typescript
+ * import { sort } from '@superutils/core'
+ * const map = new Map([
+ * 	   [1, 1],
+ * 	   [2, 2],
+ *     [0, 0],
+ * ])
+ * sort(map)
+ * // result: Map(3) { 0 => 0, 1 => 1, 2 => 2 }
+ * ```
+ *
+ * @example sort map of objects
+ * ```typescript
+ * import { sort } from '@superutils/core'
+ * const map = new Map([
+ *     [0, { name: 'Charlie' }],
+ *     [1, { name: 'Alice' }],
+ *     [2, { name: 'Bob' }],
+ * ])
+ * sort(map, 'name')
+ * // result: Map(3) {
+ * //   1 => { name: 'Alice' },
+ * //   2 => { name: 'Bob' },
+ * //   0 => { name: 'Charlie' }
+ * // }
+ * ```
+ */
+declare function sort<K, V extends Record<PropertyKey, unknown>, T extends IterableList<K, V>>(data: T, propertyName: keyof V & string, options?: SortOptions): T;
+/** Sort `Map` by map-keys `K` */
+declare function sort<K, V>(data: Map<K, V>, byKey: true, options?: SortOptions): Map<K, V>;
+/** Sort `Map` with comparator function */
+declare function sort<K, V>(map: Map<K, V>, comparator: EntryComparator<K, V>, options?: SortOptions): Map<K, V>;
+/** Sort `Array` with comparator function */
+declare function sort<V>(array: V[], comparator: ArrayComparator<V>, options?: SortOptions): V[];
+/** Sort `Set` with comparator function */
+declare function sort<V>(set: Set<V>, comparator: ArrayComparator<V>, options?: SortOptions): Set<V>;
+/** Sort Array/Map/Set with `string | boolean | number` values */
+declare function sort<K, V extends string | boolean | number, T extends IterableList<K, V>>(data: T, options?: SortOptions): T;
+declare namespace sort {
+    var defaultOptions: {
+        ignoreCase: true;
+        newInstance: false;
+        reverse: false;
+        undefinedFirst: false;
+    };
+}
+
+/**
+ * Creates a new Map by combining two or more Maps
+ *
+ * @param inputs A rest parameter of Maps and/or Map-entry (key-value pair tuples) Array.
+ *
+ * @returns new combined Map
+ *
+ * @example Join two Maps
+ * ```typescript
+ * import { mapJoin } from '@superutils/core'
+ *
+ * const maps = [
+ * 	new Map([['a', 1]]),
+ * 	new Map([['b', 2]]),
+ * ]
+ * const joined = mapJoin(...maps)
+ * // Result: Map(2) {'a' => 1, 'b' => 2}
+ * ```
+ *
+ * @example Join entries and Maps into a single Map
+ * ```typescript
+ * import { mapJoin } from '@superutils/core'
+ *
+ * const joined = mapJoin(
+ * 	new Map([['a', 1]]),
+ * 	[['b', 2]],
+ * 	new Map([['c', 3]]),
+ * )
+ * // Result: Map(2) {'a' => 1, 'b' => 2, 'c' => 3}
+ * ```
+ */
+declare const mapJoin: <K, V>(...inputs: (Map<K, V> | [K, V][])[]) => Map<K, V>;
+
+/**
+ * Generates random number within a range
+ *
+ * @param min lowest number
+ * @param max highest number
+ */
+declare const randomInt: (min?: number, max?: number) => number;
+
+/**
+ * Clears clutter from strings
+ *
+ * - removes trailing & leading whitespaces
+ * - removes empty/whitespace-only lines
+ * - converts multiline strings to single line
+ *
+ * @param	text	string to clear clutter from
+ * @param	lineSeparator	(optional) string to use as line separator. Default: single space `' '`
+ *
+ * @returns cleaned string
+ */
+declare const clearClutter: (text: string, lineSeparator?: string) => string;
+
+/**
+ * @summary Copies text to browser clipboard.
+ *
+ * CAUTION:
+ * Based on browser security policy it may be required to invoke `copyToClipboard` from an user-generated event handler.
+ *
+ * This function first attempts to use the modern, asynchronous Clipboard API (`window.navigator.clipboard.writeText`).
+ * If that fails or is unavailable, it falls back to the legacy `document.execCommand('copy')` method.
+ *
+ *
+ * @param	{String} str
+ *
+ * @returns number
+ * `0`: copy failed (both methods attempted)
+ * `1`: modern API success
+ * `2`: fallback success
+ */
+declare const copyToClipboard: (str: string) => Promise<0 | 1 | 2>;
+
+/**
+ * Read parameters of a given URL
+ *
+ * @param name   (optional) name of a specific parameter to get value of.
+ * If not provided, will return an object containing all the URL parameters with respective values.
+ * @param url (optional) default: `window.location.href`
+ * @param asArray (optional) parameter names that should be returned as Array.
+ * By default if a parameter contains multiple values it will be returned as unique Array.
+ *
+ * @returns {String|Object}
+ */
+declare const getUrlParam: <TName extends string | undefined, TAsArray extends undefined | string[] | (TName extends undefined ? never : true), TResult = TName extends undefined ? Record<string, string> : string | string[]>(name?: TName, url?: string | URL, asArray?: TAsArray) => TResult;
+
+declare const EMAIL_REGEX: RegExp;
+declare const HEX_REGEX: RegExp;
+declare const HASH_REGEX: RegExp;
+
+export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DeferredConfig, type DropFirst, type DropFirstN, type DropLast, EMAIL_REGEX, type EntryComparator, type FindOptions, HASH_REGEX, HEX_REGEX, type IfPromiseAddValue, type IsFiniteTuple, type IsOptional, type IterableList, type KeepFirst, type KeepFirstN, type KeepOptionals, type KeepRequired, type MakeOptional, type MinLength, type OptionalIf, type ReadOnlyAllowAddFn, ReadOnlyArrayHelper, type ReadOnlyConfig, type SearchOptions, type Slice, type SliceMapCallback, type SliceMapOptions, type SortOptions, type ThrottleConfig, type TimeoutId, type TupleMaxLength, type TupleWithAlt, type ValueOrFunc, type ValueOrPromise, arrReadOnly, arrReverse, arrToMap, arrUnique, asAny, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, forceCast, getEntries, getKeys, getSize, getUrlParam, getValues, is, isArr, isArr2D, isArrLike, isArrLikeSafe, isArrObj, isArrUnique, isAsyncFn, isBool, isDate, isDateValid, isDefined, isEmpty, isEmptySafe, isEnvBrowser, isEnvNode, isEnvTouchable, isError, isFn, isInteger, isMap, isMapObj, isNumber, isObj, isPositiveInteger, isPositiveNumber, isPromise, isRegExp, isSet, isStr, isSymbol, isUint8Arr, isUrl, isUrlValid, mapJoin, matchItemOrProp, noop, noopAsync, objClean, objCopy, objCreate, objKeys, objReadOnly, objSetProp, objSetPropUndefined, objSort, objWithoutKeys, randomInt, reverse, search, sliceMap, sort, throttled, toDatetimeLocal };