@rzl-zone/utils-js 3.11.1 → 3.12.1-beta.0

package/dist/index-BPPQjAfs.d.cts

@@ -0,0 +1,2359 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+import { i as ArrayFallback, r as IsHasKeysObject, t as IsPlainObjectResult } from "./isPlainObject-doTI11Ib.cjs";
+import { AnObjectNonArray, AnyFunction, AnyString, CharAt, Extends, IsAny, IsArray, IsEmptyString, IsNever, IsPositive, IsStringLiteral, NumberRangeUnion, OrArr, ParseNumber, Prettify, Trim, TypedArray } from "@rzl-zone/ts-types-plus";
+/** ----------------------------------------------------------
+ * * ***Predicate: `areArraysEqual`.***
+ * ----------------------------------------------------------
+ * **Compares two arrays deeply to check if they are equal.**
+ * @description Supports deep comparison of arrays containing nested arrays or objects,
+ *  can also ignore the order of elements at all levels by recursively sorting.
+ * @param {unknown[]} array1
+ *   ***The first array to compare, can contain nested arrays or objects.***
+ * @param {unknown[]} array2
+ *   ***The second array to compare against, should match structure of `array1`.***
+ * @param {boolean|undefined} [ignoreOrder=false]
+ *   ***Whether to ignore the order of elements when comparing.***
+ *    - If `true`, will sort both arrays recursively before comparing, default is `false`.
+ * @returns {boolean}
+ *    Returns `true` if both arrays are deeply equal, otherwise `false`.
+ * @throws **{@link TypeError | `TypeError`}** if `array1` or `array2` are not arrays, or if `ignoreOrder` is not a boolean.
+ * @example
+ * ```ts
+ * areArraysEqual([1, 2, 3], [1, 2, 3]);
+ * // ➔ true
+ * areArraysEqual([1, 2, 3], [3, 2, 1]);
+ * // ➔ false
+ * areArraysEqual([1, 2, 3], [3, 2, 1], true);
+ * // ➔ true (order ignored)
+ * areArraysEqual([{ x: 1 }, { y: 2 }], [{ y: 2 }, { x: 1 }], true);
+ * // ➔ true
+ * ```
+ */
+declare const areArraysEqual: (array1: unknown[], array2: unknown[], ignoreOrder?: boolean) => boolean;
+/** ---------------------------------
+ * * ***Predicate: `areObjectsEqual`.***
+ * ---------------------------------
+ * **Compares two objects for deep equality.**
+ * @template T1 The type of the first object.
+ * @template T2 The type of the second object.
+ * @param {*} object1 - The first object to compare.
+ * @param {*} object2 - The second object to compare.
+ * @returns {boolean} Return `true` if both objects are deeply equal, otherwise `false`.
+ * @example
+ * areObjectsEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
+ * // ➔ true
+ * areObjectsEqual({ a: 1 }, { a: 1, b: undefined });
+ * // ➔ false
+ * areObjectsEqual([1, 2, 3], [1, 2, 3]);
+ * // ➔ true
+ */
+declare const areObjectsEqual: (object1: unknown, object2: unknown) => boolean;
+/** ---------------------------------
+ * * ***Predicate: `areURLsEqualPath`.***
+ * ---------------------------------
+ * **Checks if two URLs are the same, ignoring query parameters, this function compares only the protocol, host, and pathname.**
+ * @param {URL} urlA - The first URL to compare.
+ * @param {URL} urlB - The second URL to compare.
+ * @returns {boolean} Returns `true` if both URLs are the same (ignoring search parameters), otherwise `false`.
+ * @example
+ * // Same domain, same path, different query -> true
+ * areURLsEqualPath(
+ *   new URL("https://example.com/page?a=1"),
+ *   new URL("https://example.com/page?b=2")
+ * );
+ * // ➔ true
+ *
+ * // Same domain, different path -> false
+ * areURLsEqualPath(
+ *   new URL("https://example.com/page1"),
+ *   new URL("https://example.com/page2")
+ * );
+ * // ➔ false
+ *
+ * // Different protocol -> false
+ * areURLsEqualPath(
+ *   new URL("http://example.com/page"),
+ *   new URL("https://example.com/page")
+ * );
+ * // ➔ false
+ *
+ * // Same protocol, same host, same path (ignores query & hash) -> true
+ * areURLsEqualPath(
+ *   new URL("https://example.com/page#section"),
+ *   new URL("https://example.com/page")
+ * );
+ * // ➔ true
+ */
+declare const areURLsEqualPath: (urlA: URL, urlB: URL) => boolean;
+/** ---------------------------------
+ * * ***Predicate: `areURLsIdentical`.***
+ * ---------------------------------
+ * **Checks if two URLs are exactly the same, including protocol, host, pathname, and query parameters.**
+ * @param {URL} urlA - The first URL to compare.
+ * @param {URL} urlB - The second URL to compare.
+ * @returns {boolean} Returns `true` if both URLs are identical, otherwise `false`.
+ * @example
+ * // Identical URLs -> true
+ * areURLsIdentical(
+ *   new URL("https://example.com/page?a=1"),
+ *   new URL("https://example.com/page?a=1")
+ * );
+ * // ➔ true
+ *
+ * // Same path, different query parameter -> false
+ * areURLsIdentical(
+ *   new URL("https://example.com/page?a=1"),
+ *   new URL("https://example.com/page?b=2")
+ * );
+ * // ➔ false
+ *
+ * // Same host & query, but different protocol -> false
+ * areURLsIdentical(
+ *   new URL("http://example.com/page?a=1"),
+ *   new URL("https://example.com/page?a=1")
+ * );
+ * // ➔ false
+ *
+ * // Same everything except trailing slash -> false
+ * areURLsIdentical(
+ *   new URL("https://example.com/page"),
+ *   new URL("https://example.com/page/")
+ * );
+ * // ➔ false
+ */
+declare const areURLsIdentical: (urlA: URL, urlB: URL) => boolean;
+type OptionsTextContainsAll = {
+  /** If `true`, matches whole words only, defaultValue is `false`.
+   *
+   * @default false
+   */
+  exactMatch?: boolean;
+  /** Optional regex flags (default: `"i"` for case-insensitive).
+   *
+   * @default "i"
+   */
+  flags?: string;
+};
+/** ----------------------------------------------------------
+ * * ***Predicate: `textContainsAll`.***
+ * ----------------------------------------------------------
+ * **Checks if the given `text` contains all of the specified `searchWords`.**
+ * - **Behavior:**
+ *    - Returns `false` if `text` or `searchWords` is `null`/`undefined`/invalid.
+ *    - Uses **regular expressions** for flexible pattern matching.
+ *    - **Escapes special characters** to prevent regex injection attacks.
+ *    - **Trims input** to avoid false positives with empty spaces.
+ *    - **Supports exact word matching** (optional).
+ * @param {string|null|undefined} text - The string text to search within.
+ * @param {string[]|null} [searchWords] - An array of words/phrases to match against the text.
+ * @param {OptionsTextContainsAll} [options] - Optional configuration object.
+ * @param {OptionsTextContainsAll["exactMatch"]} [options.exactMatch=false] - If `true`, matches whole words only, defaultValue is `false`.
+ * @param {OptionsTextContainsAll["flags"]} [options.flags="i"] - Optional regex flags (default: `"i"` for case-insensitive).
+ * @returns {boolean} Return `true` if all `searchWords` are found in `text`, otherwise `false`.
+ * @example
+ * textContainsAll("Hello world, WithAI APP", ["Hello", "world"]);
+ * // ➔ true
+ * textContainsAll("JavaScript and TypeScript", ["Java", "Script"]);
+ * // ➔ true
+ * textContainsAll("Machine Learning", ["AI", "Learning"]);
+ * // ➔ false
+ * textContainsAll("open-source", ["open"], { exactMatch: true });
+ * // ➔ false (because options `exactMatch=true`)
+ * textContainsAll(null, ["test"]);
+ * // ➔ false (invalid text)
+ * textContainsAll("Hello", null);
+ * // ➔ false (invalid searchWords)
+ */
+declare const textContainsAll: <T extends string>(text?: T | null, searchWords?: T[] | string[] | null, options?: OptionsTextContainsAll) => boolean;
+type OptionsTextContainsAny = {
+  /** If `true`, matches whole words only, defaultValue is `false`.
+   *
+   * @default false
+   */
+  exactMatch?: boolean;
+  /** Optional regex flags (default: `"i"` for case-insensitive).
+   *
+   * @default "i"
+   */
+  flags?: string;
+};
+/** ----------------------------------------------------------
+ * * ***Predicate: `textContainsAny`.***
+ * ----------------------------------------------------------
+ * **Checks if the given `text` contains at least one of the specified `searchWords`.**
+ * - **Behavior:**
+ *    - Returns `false` if `text` or `searchWords` is `null`/`undefined`/invalid.
+ *    - Uses **regular expressions** for flexible pattern matching.
+ *    - **Escapes special characters** to prevent regex injection attacks.
+ *    - **Trims input** to avoid false positives with empty spaces.
+ *    - **Supports exact word matching** (optional).
+ * @param {string|null|undefined} text - The string text to search within.
+ * @param {string[]|null} [searchWords] - An array of words/phrases to match against the text.
+ * @param {OptionsTextContainsAny} [options] - Optional configuration object.
+ * @param {OptionsTextContainsAny["exactMatch"]} [options.exactMatch=false] - If `true`, matches whole words only, defaultValue is `false`.
+ * @param {OptionsTextContainsAny["flags"]} [options.flags="i"] - Optional regex flags (default: `"i"` for case-insensitive).
+ * @returns {boolean} Return `true` if at least one `searchWord` is found in `text`, otherwise `false`.
+ * @example
+ * textContainsAny("Hello world", ["hello", "test"]);
+ * // ➔ true
+ * textContainsAny("withAI APP", ["chat", "ai"]);
+ * // ➔ false
+ * textContainsAny("TypeScript is great!", ["script", "java"]);
+ * // ➔ true
+ * textContainsAny("open-source", ["open"], { exactMatch: true });
+ * // ➔ false (because options `exactMatch=true`)
+ * textContainsAny(null, ["test"]);
+ * // ➔ false (invalid text)
+ * textContainsAny("Hello", null);
+ * // ➔ false (invalid searchWords)
+ */
+declare const textContainsAny: <T extends string>(text?: T | null, searchWords?: T[] | string[] | null, options?: OptionsTextContainsAny) => boolean;
+/** ----------------------------------------------------------
+ * * ***Predicate: `doesKeyExist`.***
+ * ----------------------------------------------------------
+ * **Recursively checks if a given key exists in an object or array.**
+ * - **Behavior:**
+ *    - **Supports deeply nested objects and arrays**, searching recursively.
+ *    - Uses `Object.prototype.hasOwnProperty.call()` to safely check if the
+ *      key exists at each level, even if its value is `null` or `undefined`.
+ *    - Optimized to return `true` immediately when the key is found (short-circuits).
+ *    - Handles edge cases gracefully:
+ *      - Returns `false` for `null`, `undefined`, or non-object inputs.
+ *      - Returns `false` if key is not found anywhere, even in deeply nested
+ *        structures.
+ * - **ℹ️ Note:**
+ *    - This function only checks for **the existence of the key itself**,
+ *      not whether its value is non-null or non-undefined.
+ *    - If you need to check for both existence and meaningful value, write a stricter function.
+ * @template T - The type of the input object or array.
+ * @param {T | Record<string, unknown> | unknown[]} object - The object or array to search.
+ * @param {PropertyKey} key - The key to look for (string, number, or symbol).
+ * @returns {boolean} Returns `true` if the key exists anywhere in the object or array (even with `null` / `undefined` value), otherwise `false`.
+ * @example
+ * doesKeyExist({ name: "John", age: 30 }, "age");
+ * // ➔ true
+ * doesKeyExist({ user: { profile: { email: "test@example.com" } } }, "email");
+ * // ➔ true
+ * doesKeyExist([{ id: 1 }, { id: 2 }], "id");
+ * // ➔ true
+ * doesKeyExist({ a: { b: { c: 10 } } }, "d");
+ * // ➔ false
+ * doesKeyExist(null, "name");
+ * // ➔ false
+ * doesKeyExist(undefined, "test");
+ * // ➔ false
+ *
+ * // Key exists even if value is null or undefined:
+ * doesKeyExist({ a: null, b: undefined, c: { d: null } }, "a"); // ➔ true
+ * doesKeyExist({ a: null, b: undefined, c: { d: null } }, "b"); // ➔ true
+ * doesKeyExist({ a: null, b: undefined, c: { d: null } }, "d"); // ➔ true
+ *
+ * doesKeyExist({ a: 1 }, true);
+ * // ➔ ❌ Throws TypeError
+ * doesKeyExist({ a: 1 }, ["not", "valid"]);
+ * // ➔ ❌ Throws TypeError
+ */
+declare const doesKeyExist: (object: Record<string, unknown> | unknown[], key: PropertyKey) => boolean;
+/** ----------------------------------------------------------
+ * * ***Predicate: `arrayHasAnyMatch`.***
+ * ----------------------------------------------------------
+ * **Checks if at least one element from `targetArray` exists in `sourceArray`.**
+ * - **Behavior:**
+ *    - Uses `Set` for **faster lookup** compared to `Array.prototype.includes()`.
+ *    - Supports **any data type** (`number`, `string`, `boolean`, `object`, `array`, `function`, etc.).
+ *    - Uses **reference equality** for non-primitive values (object, array, function).
+ *    - Returns `false` if either array is missing, empty, or not an array.
+ * @template T - The expected type of array elements.
+ * @param {T[] | null | undefined} sourceArray - The array to search within.
+ * @param {T[] | null | undefined} targetArray - The array containing elements to match.
+ * @returns {boolean}
+ *  ***Return:***
+ *  - `true` if **at least one element from `targetArray` is strictly found
+ *  in `sourceArray`**.
+ *    - Comparison uses:
+ *      - **Value equality** for primitives (`number`, `string`, `boolean`, `null`, `undefined`).
+ *      - **Reference equality** for `objects`, `arrays`, and `functions`.
+ *  - `false` if:
+ *      - No matching elements exist,
+ *      - Either array is not provided, not an actual array, or is empty.
+ * @example
+ * arrayHasAnyMatch(["apple", "banana", "cherry"], ["banana", "grape"]);
+ * // ➔ true
+ * arrayHasAnyMatch(["red", "blue"], ["green", "yellow"]);
+ * // ➔ false
+ * arrayHasAnyMatch([1, 2, 3], [3, 4, 5]);
+ * // ➔ true
+ * arrayHasAnyMatch([], ["test"]);
+ * // ➔ false
+ * arrayHasAnyMatch(["A", "B", "C"], []);
+ * // ➔ false
+ *
+ * const obj = { x: 1 };
+ * arrayHasAnyMatch([obj], [obj]);
+ * // ➔ true (same reference)
+ * arrayHasAnyMatch([{ x: 1 }], [{ x: 1 }]);
+ * // ➔ false (different reference)
+ *
+ * const fn = () => "hello";
+ * arrayHasAnyMatch([fn], [fn]);
+ * // ➔ true
+ * arrayHasAnyMatch([() => "hello"], [() => "hello"]);
+ * // ➔ false (different function reference)
+ *
+ * const arr = [1, 2];
+ * arrayHasAnyMatch([arr], [arr]);
+ * // ➔ true
+ * arrayHasAnyMatch([[1, 2]], [[1, 2]]);
+ * // ➔ false (different array object)
+ */
+declare const arrayHasAnyMatch: <T>(sourceArray: T[] | null | undefined, targetArray: T[] | null | undefined) => boolean;
+/** Restrict array indices to a fixed numeric range (1–25). */
+type ArrayIndex = NumberRangeUnion<1, 25>;
+/** Remove `undefined` from a type. */
+type NonUndef<T> = T extends undefined ? never : T;
+/** Remove `null` from a type. */
+type NonNull<T> = T extends null ? never : T;
+/** Convert optional boolean for "discard undefined" to actual boolean. */
+type EffectiveDiscardUndefined<O extends boolean | undefined> = O extends boolean ? O : true;
+/** Convert optional boolean for "discard null" to actual boolean. */
+type EffectiveDiscardNull<O extends boolean | undefined> = O extends boolean ? O : false;
+/** Unwrap array type. */
+type UnwrapArray<T> = T extends (infer U)[] ? U : T extends readonly (infer U)[] ? U : T;
+/** Force symbol key to be deep required. */
+type IsOptionalKey<T, K extends keyof T> = Record<never, never> extends Pick<T, K> ? true : false;
+/** * ***Returns numeric keys of an object.***
+ *
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type NumericKeyOfHasOwnProp<Obj> = Extract<keyof Obj, number>;
+/** * ***Generate all nested keys of an object or array in dot/bracket notation.***
+ *
+ * @private ***types for {@link hasOwnProp}.***
+ *
+ * Example:
+ * ```ts
+ * type Keys = NestedKeyOfHasOwnProp<{ users: { name: string }[] }>
+ * // Keys = "users" | "users.[number]" | "users.[number].name"
+ * ```
+ */
+type NestedKeyOfHasOwnProp<T> = T extends readonly (infer U)[] ? `[${number}]` | `[${number}].${NestedKeyOfHasOwnProp<U>}` : T extends object ? { [K in keyof T & (string | number)]: K extends string | number ? NonNullable<T[K]> extends readonly unknown[] ? `${K}` | `${K}.[${ArrayIndex}]` | `${K}.[${ArrayIndex}].${NestedKeyOfHasOwnProp<UnwrapArray<T[K]>>}` : NonNullable<T[K]> extends object ? `${K}` | `${K}.${NestedKeyOfHasOwnProp<NonNullable<T[K]>>}` : `${K}` : never }[keyof T & (string | number)] : never;
+/** Apply discard rules to the last key of a path.
+ *
+ * Rules:
+ * - If discardUndefined=true -> remove `undefined` from value
+ * - If discardNull=true -> remove `null` from value
+ *
+ * Order: first strip undefined (if requested), then strip null (if requested)
+ */
+type ApplyLastRulesHasOwnProp<V, DiscardU extends boolean, DiscardN extends boolean> = DiscardU extends true ? DiscardN extends true ? NonNull<NonUndef<V>> : NonUndef<V> : DiscardN extends true ? NonNull<V> : V | Extract<V, undefined>;
+/** Force an array index N to type U. */
+type RefineArrayAtIndex<T extends readonly unknown[], N extends number, U> = T & { [K in N]: U };
+/** Narrow object/array type based on a path string.
+ *
+ * @template T - object type to narrow
+ * @template P - path string like "user.addresses.[2].zip"
+ * @template DU - discard undefined
+ * @template DN - discard null
+ */
+type NarrowByPathHasOwnProp<T, P extends string, DU extends boolean = true, DN extends boolean = false> = P extends `${infer Head}.${infer Rest}` ? Head extends `[${infer N extends number}]` ? T extends readonly (infer U)[] ? RefineArrayAtIndex<T, N, NarrowByPathHasOwnProp<U, Rest, DU, DN>> : T : Head extends keyof T ? Rest extends `[${infer M extends number}]${infer R}` ? M extends R ? { [K in keyof T]-?: NarrowByPathHasOwnProp<EffectiveDiscardUndefined<DU> extends true ? NonUndef<T[K]> : EffectiveDiscardNull<DN> extends true ? NonNull<T[K]> : T[K], Rest, DU, DN> } : EffectiveDiscardUndefined<DU> extends true ? { [K in keyof T]-?: K extends Head ? Exclude<NarrowByPathHasOwnProp<EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K], Rest, DU, DN>, undefined> : EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K] } : { [K in keyof T]: K extends Head ? NarrowByPathHasOwnProp<EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K], Rest, DU, DN> : EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K] } : { [K in keyof T]: K extends Head ? NarrowByPathHasOwnProp<NonNullable<T[K]>, Rest, DU, DN> : T[K] } & { [K in Head]-?: NarrowByPathHasOwnProp<NonNullable<T[K]>, Rest, DU, DN> } : T : P extends `[${infer N extends number}]` ? T extends readonly (infer U)[] ? RefineArrayAtIndex<T, N, ApplyLastRulesHasOwnProp<NonNullable<U>, DU, DN>> : T : P extends keyof T ? DU extends true ? { [K in keyof T]: K extends P ? ApplyLastRulesHasOwnProp<T[K], DU, DN> : T[K] } & { [K in P]-?: ApplyLastRulesHasOwnProp<T[P], DU, DN> } : { [K in keyof T]: K extends P ? ApplyLastRulesHasOwnProp<T[K], DU, DN> : T[K] } : T;
+/** * ***Expand an array/string/function into a nested type according
+ * to a dot/bracket path.***
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type SmartDetectStringHasOwnProp<Obj extends string | undefined | null, Key extends string | number> = Obj extends undefined ? undefined : Obj extends null ? null : IsPositive<ParseNumber<Key>> extends true ? Extends<IsStringLiteral<Obj>, true> extends true ? CharAt<Exclude<Obj, null | undefined>, ParseNumber<Key>> : string | undefined | null : IsPositive<ParseNumber<Key>> extends true ? string | undefined | null : AnyString | undefined | null;
+/** @private ***types for {@link hasOwnProp}.*** */
+type SmartDetectArrayFuncHasOwnProp<Obj extends unknown[] | AnyFunction, Key extends PropertyKey> = Prettify<Obj & DotToNestedSpecialSmartDetect<Key> & {
+  length: number;
+}, {
+  recursive: false;
+}>;
+/** * ***Smartly detect nested path keys of an unknown object or function,
+ * falls-back to inferred nested structure when path is not valid.***
+ *
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type SmartDetectUnknownKeyHasOwnProp<Obj extends unknown | AnyFunction, Key extends PropertyKey, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false> = Trim<Key> extends "" ? Obj : Prettify<Obj & (Key extends NestedKeyOfHasOwnProp<Obj> ? GuardedHasOwnProp<Obj, Key, DiscardUndefined, DiscardNull> : DotToNestedSpecialSmartDetect<Key>), {
+  recursive: true;
+}>;
+/** Convert dot/bracket path string to nested object type with leaf value.
+ * Path not found in object key ➔ return unknown.
+ */
+type DotToNestedSpecialSmartDetect<Path extends PropertyKey, Value = unknown> = IsEmptyString<Extract<Path, string>> extends true ? undefined : Path extends `${infer Head}.${infer Rest}` ? Head extends `[${number}]` ? DotToNestedSpecialSmartDetect<Rest, Value>[] : { [Key in Head]: DotToNestedSpecialSmartDetect<Rest, Value> } : Path extends `[${number}]` ? Value[] : { [Key in Path]: Value };
+/** * ***Guarded wrapper for `NarrowByPathHasOwnProp` with `Prettify`.***
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type GuardedHasOwnProp<Obj, Key extends NestedKeyOfHasOwnProp<Obj>, DiscardUndefined extends boolean | undefined, DiscardNull extends boolean | undefined> = Prettify<Obj & NarrowByPathHasOwnProp<Obj, Key & string, EffectiveDiscardUndefined<DiscardUndefined>, EffectiveDiscardNull<DiscardNull>>, {
+  recursive: true;
+}>;
+/** * ***Make a specific symbol key deeply required in an object symbols.***
+ * **Used internally to enforce stronger type narrowing.**
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type DeepRequiredSymbolHasOwnProp<Obj, Sym extends symbol, DU extends boolean = true, DN extends boolean = false> = Prettify<Obj & ({ [K in keyof Obj & Sym as DU extends true ? K : never]-?: DN extends true ? NonNull<NonUndef<Obj[K]>> : NonUndef<Obj[K]> } & { [K in keyof Obj & Sym as DU extends true ? never : K]?: DN extends true ? NonNull<Obj[K]> : Obj[K] }), {
+  recursive: true;
+}>;
+/** * ***Apply discard rules to numeric keys in an object type.***
+ *
+ * - If `discardUndefined = true` ➔ undefined removed, key required
+ * - If `discardNull = true` ➔ null removed
+ *
+ * @private ***types for {@link hasOwnProp}.***
+ */
+type NumericKeyHasOwnPropMapped<Obj extends object, K extends NumericKeyOfHasOwnProp<Obj>, DU extends boolean, DN extends boolean> = Prettify<Obj & (IsOptionalKey<Obj, K> extends true ? { [P in K]?: DN extends true ? NonNull<Obj[K]> : Obj[K] } & (DU extends true ? { [P in K]-?: NonUndef<Obj[K]> } : Record<never, never>) : { [P in K]-?: DN extends true ? NonNull<Obj[K]> : Obj[K] } & (DU extends true ? { [P in K]-?: NonUndef<Obj[K]> } : Record<never, never>)), {
+  recursive: true;
+}>;
+/** * ***Options to control `hasOwnProp` behavior.***
+ * @private ***types options for {@link hasOwnProp}.***
+ */
+type HasOwnPropOptions<DiscardUndefined extends boolean = true, DiscardNull extends boolean = false> = {
+  /** If `true` ***(default)***, properties with `undefined` values are treated as non-existent.
+   *
+   * - **Effects:**
+   *    - **Runtime:** `hasOwnProp(obj, key)` returns `false` if the property exists but its value is `undefined`.
+   *    - **TypeScript narrowing:** The property's type is narrowed to exclude `undefined`.
+   * - **Example:**
+   * ```ts
+   *     const obj = { a: undefined, b: 123 };
+   *     hasOwnProp(obj, "a"); // ➔ false
+   *     hasOwnProp(obj, "a", { discardUndefined: false }); // ➔ true
+   * ```
+   */
+  discardUndefined?: DiscardUndefined;
+  /** If `true` ***(default: `false`)***, properties with `null` values are treated as non-existent.
+   *
+   * - **Effects:**
+   *    - **Runtime:** `hasOwnProp(obj, key)` returns `false` if the property exists but its value is `null`.
+   *    - **TypeScript narrowing:** The property's type is narrowed to exclude `null`.
+   * - **Example:**
+   * ```ts
+   *     const obj = { a: null, b: 123 };
+   *     hasOwnProp(obj, "a"); // ➔ true (default discardNull = false)
+   *     hasOwnProp(obj, "a", { discardNull: true }); // ➔ false
+   * ```
+   */
+  discardNull?: DiscardNull;
+};
+/** -------------------------------------------------------
+ * * ***Predicate: `hasOwnProp`.***
+ * -------------------------------------------------------
+ * **A **type-safe** replacement for `Object.prototype.hasOwnProperty` with runtime validation and **TypeScript-aware type narrowing**.**
+ * - #### Supported Targets:
+ *    - **Plain objects** ➔ `{ foo: "bar" }`.
+ *    - **Arrays** ➔ `[ { id: 1 }, { id: 2 } ]`.
+ *    - **Strings** ➔ `"hello"` (as array-like objects with `.length`, index, etc.).
+ *    - **Functions** ➔ callable objects with extra props.
+ *    - **Symbols** ➔ own property symbols.
+ * - #### Key Advantages over `in` or `obj.hasOwnProperty(key)`:
+ *    - Supports **dot/bracket path notation** (e.g. `"user.address.city"`, `"addresses[0].zip"`).
+ *    - Handles **symbol** keys safely.
+ *    - **Narrows** the type of `obj` in TypeScript (stronger type safety).
+ *    - Configurable handling of **`undefined`** and **`null`**.
+ * - #### Runtime Behavior:
+ *    - ***✅ Returns `true` if:***
+ *        - Value `obj` is an object/array/string/function **and** the property
+ *          exists **and**, it passes the `options` checks.
+ *    - ***❌ Returns `false` if:***
+ *        - Value `obj` is not a valid type.
+ *        - The property does not exist.
+ *        - The value is `undefined` and `discardUndefined: true` (**default**).
+ *        - The value is `null` and `discardNull: true`.
+ *        - The `key` (after trimming) is an **empty string** ➔ treated as **invalid**.
+ * - #### TypeScript Behavior:
+ *    - ***Inside an `if (hasOwnProp(...)) {}` block:***
+ *      - The property is **guaranteed to exist**.
+ *      - Depending on `options`, the property type is narrowed to exclude
+ *        `undefined` and/or `null`.
+ * - #### ⚠️ Caveats:
+ *    - ***Empty keys are invalid:***
+ *        - If the `key` string is empty (`""`) after trimming whitespace or other characters,
+ *          it will **not** be considered a valid property and always returns `false`.
+ *    - ***Arrays are limited by TypeScript inference:***
+ *        - Checking index `[0]` only narrows **that specific index**, not the rest, example:
+ *          1. `hasOwnProp(users, "[0].id")` does **not** imply `users[1].id` exists.
+ *              - 👉 For different indices, use **optional chaining** (`users[1]?.id`).
+ *    - ***Autocomplete limitation for array indices:***
+ *        - Autocompletion for `[index]` is only supported up to **25** (`[0]` ➔ `[24]`).
+ *        - This limit is intentional for **performance and safety:**
+ *          1. Generating infinite union types for all possible indices would cause
+ *            **TypeScript IntelliSense to hang or crash**.
+ *              - ℹ️ You can still check higher indices manually (e.g. `"[999].id"`),
+ *                but they will not show up in IntelliSense suggestions.
+ * @param {HasOwnPropOptions} [options] - ***Optional configuration object.***
+ * @param {HasOwnPropOptions["discardUndefined"]} [options.discardUndefined=true]
+ *  ***If `true`, properties with `undefined` values are treated as **missing**, default: `true`.***
+ * @param {HasOwnPropOptions["discardNull"]} [options.discardNull=false]
+ *  ***If `true`, properties with `null` values are treated as **missing**, default: `false`.***
+ * @param {*} obj ***The `object`, `array`, `string`, `function`, or `other value` to check against.***
+ * @param {PropertyKey} key
+ *  ***The property key to check, can be:***
+ *    - `string` (supports dot/bracket paths, e.g. `"user.address.city"`, `"[0].id"`).
+ *    - `number` (array-like index).
+ *    - `symbol` (own property symbols).
+ * @returns {boolean} Return `true` if the property exists (and passes `options`), otherwise `false`.
+ * @example
+ *
+ * - #### ✅ Objects:
+ * ```ts
+ *    const obj: { name?: string | null } = {};
+ *
+ *    if (hasOwnProp(obj, "name")) {
+ *      // obj is now ➔ { name: string | null }
+ *      console.log(obj.name); // string | null
+ *    }
+ *
+ *    if (hasOwnProp(obj, "name", { discardUndefined: true, discardNull: true })) {
+ *      // obj is now ➔ { name: string }
+ *      console.log(obj.name.toUpperCase()); // safe
+ *    }
+ * ```
+ * - #### ✅ Arrays:
+ * ```ts
+ *    const users = [{ id: 1 }, { id: 2 }];
+ *
+ *    if (hasOwnProp(users, "[1].id")) {
+ *      // ➔ users[1].id is guaranteed to exist
+ *      console.log(users[1].id); // number
+ *    }
+ *
+ *    // ⚠️ Caveat: narrowing only applies to checked index
+ *    if (hasOwnProp(users, "[0].id")) {
+ *      console.log(users[0].id); // ✅ safe
+ *      console.log(users[1].id); // ❌ not guaranteed!
+ *    }
+ *
+ *    // 👉 Solution: optional chaining
+ *    console.log(users[1]?.id); // ➔ safe, even without narrowing
+ * ```
+ *
+ * - #### ✅ Symbols:
+ * ```ts
+ *    const secret = Symbol("secret");
+ *    const obj2 = { [secret]: 42 };
+ *
+ *    if (hasOwnProp(obj2, secret)) {
+ *      console.log(obj2[secret] + 1); // ➔ 43
+ *    }
+ * ```
+ * - #### ✅ Strings:
+ * ```ts
+ *    if (hasOwnProp("hello", "length")) {
+ *      console.log("hello".length); // ➔ 5
+ *    }
+ *
+ *    if (hasOwnProp("hello", 1)) {
+ *      console.log("hello"[1]); // ➔ "e"
+ *    }
+ * ```
+ * - #### ✅ Functions:
+ * ```ts
+ *    function fn() {}
+ *    fn.extra = 123;
+ *
+ *    if (hasOwnProp(fn, "extra")) {
+ *      console.log(fn.extra); // ➔ 123
+ *    }
+ * ```
+ * - #### ❌ Empty key:
+ * ```ts
+ *    const obj = { a: 1 };
+ *
+ *    hasOwnProp(obj, "");    // ➔ false (invalid key)
+ *    hasOwnProp(obj, "   "); // ➔ false (trimmed to empty)
+ * ```
+ */
+declare function hasOwnProp<Obj>(obj: IsAny<Obj> extends true ? Obj : never, key: PropertyKey, options?: HasOwnPropOptions<boolean, boolean> /** @ts-expect-error we force `any` to `unknown` at result */): obj is unknown;
+declare function hasOwnProp<Obj extends null | undefined>(obj: Obj, key: PropertyKey, options?: HasOwnPropOptions<boolean, boolean>): false;
+declare function hasOwnProp<Obj extends object | AnyFunction, Key extends NestedKeyOfHasOwnProp<Obj>, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false>(obj: Obj | null | undefined, key: Key, options?: HasOwnPropOptions<DiscardUndefined, DiscardNull> /** @ts-expect-error we force to override recursive type result */): obj is GuardedHasOwnProp<Obj, Key, DiscardUndefined, DiscardNull>;
+declare function hasOwnProp<Obj extends object, Num extends NumericKeyOfHasOwnProp<Obj>, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false>(obj: Obj | null | undefined, key: Num, options?: HasOwnPropOptions<DiscardUndefined, DiscardNull> /** @ts-expect-error we force to override recursive type result */): obj is NumericKeyHasOwnPropMapped<Obj, Num, DiscardUndefined, DiscardNull>;
+declare function hasOwnProp<Obj extends object | AnyFunction, Sym extends symbol, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false>(obj: Obj | null | undefined, key: Sym, options?: HasOwnPropOptions<DiscardUndefined, DiscardNull> /** @ts-expect-error we force to override recursive type result */): obj is DeepRequiredSymbolHasOwnProp<Obj, Sym, DiscardUndefined, DiscardNull>;
+declare function hasOwnProp<Obj extends string | null | undefined, Key extends string | number>(obj: Obj | null | undefined, key: Key, options?: HasOwnPropOptions<boolean, boolean> /** @ts-expect-error we force to override recursive type result */): obj is IsStringLiteral<SmartDetectStringHasOwnProp<Obj, Key>> extends true ? AnyString | SmartDetectStringHasOwnProp<Obj, Key> : SmartDetectStringHasOwnProp<Obj, Key>;
+declare function hasOwnProp<Obj extends unknown[] | AnyFunction, Key extends PropertyKey>(obj: Obj, key: Key, options?: HasOwnPropOptions<boolean, boolean>): obj is SmartDetectArrayFuncHasOwnProp<Obj, Key>;
+declare function hasOwnProp<Obj extends unknown | AnyFunction, Key extends PropertyKey, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false>(obj: Obj, key: Key | "length" | (IsPlainObjectResult<Obj> extends never ? never : keyof Obj), options?: HasOwnPropOptions<DiscardUndefined, DiscardNull> /** @ts-expect-error we force to override recursive type result */): obj is SmartDetectUnknownKeyHasOwnProp<Obj, Key, DiscardUndefined, DiscardNull>;
+/** -------------------
+ * * ***Type guard: `isArguments`.***
+ * -------------------
+ * **Checks if `value` is likely an `arguments` object.**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is an ***[`IArguments`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments)*** object, else `false`.
+ * @example
+ * isArguments(function() { return arguments; }());
+ * // ➔ true
+ * isArguments([1, 2, 3]);
+ * // ➔ false
+ */
+declare const isArguments: (value: unknown) => value is IArguments;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isArray`.***
+ * ----------------------------------------------------------
+ ***Checks if a value is an ***[`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)***.**
+ * - **Behavior:**
+ *    - Uses ***[`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)*** for reliable and safe type checking.
+ *    - Supports TypeScript **type narrowing** using `value is T[]`.
+ *    - Handles edge cases like `null`, `undefined`, and non-array objects.
+ * @template T - The expected type of array elements.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is an `array`, otherwise `false`.
+ * @example
+ * isArray([1, 2, 3]);
+ * // ➔ true
+ * isArray([]);
+ * // ➔ true
+ * isArray("hello");
+ * // ➔ false
+ * isArray({ key: "value" });
+ * // ➔ false
+ * isArray(null);
+ * // ➔ false
+ * isArray(undefined);
+ * // ➔ false
+ */
+declare function isArray(value: []): value is [];
+declare function isArray<T>(value: T): value is ArrayFallback<T>;
+declare function isArray(value: unknown): value is unknown[];
+/** ----------------------------------------------------
+ * * ***Type guard: `isArrayBuffer`.***
+ * ----------------------------------------------------
+ * **Checks if `value` is classified as an `ArrayBuffer` object.**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is instance of ***[`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)***, else `false`.
+ * @example
+ * isArrayBuffer(new ArrayBuffer(2));
+ * // ➔ true
+ * isArrayBuffer(new Array(2));
+ * // ➔ false
+ */
+declare function isArrayBuffer(value: unknown): value is ArrayBuffer;
+/** ----------------------------------------------------
+ * * ***Type guard: `isArrayLike`.***
+ * ----------------------------------------------------
+ * **Checks if `value` is array-like, a value is considered array-like if it's
+ * not a function and has a `value.length` that's an integer greater than or
+ * equal to `0` and less than or equal to `Number.MAX_SAFE_INTEGER`.**
+ * @template T - The type of the value being checked.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is array-like, else `false`.
+ * @example
+ * isArrayLike([1, 2, 3]);
+ * // ➔ true
+ * isArrayLike(document.body.children);
+ * // ➔ true
+ * isArrayLike(noop);
+ * // ➔ false
+ * isArrayLike('abc');
+ * // ➔ false
+ */
+declare function isArrayLike<T extends {
+  __anyHack: unknown;
+}>(value: T): boolean;
+declare function isArrayLike(value: AnyFunction | null | undefined): value is never;
+declare function isArrayLike(value: unknown): value is {
+  length: number;
+};
+/** ----------------------------------------------------
+ * * ***Type guard: `isArrayLikeObject`.***
+ * ----------------------------------------------------
+ * **This method is like ***`isArrayLike` utility function*** except that
+ *   it also checks if `value` is an object.**
+ * @template T - The type of the value being checked.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is `array-like object`, else `false`.
+ * @example
+ * isArrayLikeObject([1, 2, 3]);
+ * // ➔ true
+ * isArrayLikeObject(document.body.children);
+ * // ➔ true
+ * isArrayLikeObject('abc');
+ * // ➔ false
+ * isArrayLikeObject(noop);
+ * // ➔ false
+ */
+declare function isArrayLikeObject<T extends {
+  __anyHack: unknown;
+}>(value: T): boolean;
+declare function isArrayLikeObject(value: AnyFunction | string | boolean | number | null | undefined): value is never;
+declare function isArrayLikeObject(value: unknown): value is object & {
+  length: number;
+};
+/** ----------------------------------------------------------
+ * * ***Type guard: `isBigInt`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is of type **[`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)**.**
+ * - **Behavior:**
+ *    - Uses `typeof value === "bigint"` for strict type checking.
+ *    - Supports TypeScript type narrowing with `value is bigint`.
+ *    - Returns `false` for `BigInt` object (object-wrapped), e.g:
+ *      - `Object(BigInt(123))`.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if value is a primitive bigint.
+ * @example
+ * isBigInt(123n);
+ * // ➔ true
+ * isBigInt(BigInt(123));
+ * // ➔ true
+ * isBigInt("123");
+ * // ➔ false
+ * isBigInt(Object(BigInt(1)));
+ * // ➔ false
+ */
+declare const isBigInt: (value: unknown) => value is bigint;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isBoolean`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is of type **[`boolean`](https://developer.mozilla.org/en-US/docs/Glossary/Boolean/JavaScript)**.**
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a `boolean`, otherwise `false`.
+ * @example
+ * isBoolean(true);   // ➔ true
+ * isBoolean(false);  // ➔ true
+ * isBoolean("true"); // ➔ false
+ */
+declare const isBoolean: (value: unknown) => value is boolean;
+/** ----------------------------------------------------
+ * * ***Type guard: `isBooleanObject`.***
+ * ----------------------------------------------------
+ * **Checks if a value is a **`Boolean` object wrapper**
+ * (`new Boolean(...)`), not a primitive boolean.**
+ * @param {*} value The value to check.
+ * @returns {value is Boolean} Returns `true` if `value` is a `Boolean` object.
+ * @example
+ * isBooleanObject(new Boolean(true));
+ * // ➔ true
+ * isBooleanObject(true);
+ * // ➔ false
+ */
+declare function isBooleanObject(value: unknown): value is Boolean;
+/** ----------------------------------------------------
+ * * ***Type guard: `isBuffer`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a *****{@link Buffer | `Node.js - Buffer`}***** instance.**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a `Buffer`, else `false`.
+ * @example
+ * isBuffer(new Buffer(2));
+ * // ➔ true
+ * isBuffer(Buffer.alloc(10));
+ * // ➔ true
+ * isBuffer(Buffer.from('foo'));
+ * // ➔ true
+ * isBuffer([]);
+ * // ➔ false
+ * isBuffer('a string');
+ * // ➔ false
+ * isBuffer(new Uint8Array(1024));
+ * // ➔ false
+ */
+declare const isBuffer: (value: unknown) => value is Buffer;
+/** -----------------------------------------------------------
+ * * ***Predicate: `isCurrencyLike`.***
+ * -----------------------------------------------------------
+ * **Determines if the given `input` can be interpreted as a currency-like number,
+ * using the same **multi-locale parsing logic** as ***`parseCurrencyString`***.**
+ * - **Highlights:**
+ *    - *Supports strings or numbers like:*
+ *      - `"15.000,10"` ***(European)***.
+ *      - `"15,000.10"` ***(US)***.
+ *      - `"15'000.10"` ***(Swiss)***.
+ *      - `"15 000,10"` ***(French)***.
+ *      - `"Rp 15.000,10"` or `"$15,000.10"`.
+ *    - Also accepts simple numbers (`15300.95`).
+ * - **ℹ️ Note:**
+ *    - Uses the same core logic as
+ *      ***`parseCurrencyString`*** but
+ *      just checks if a final parsed float is sensible.
+ * @param {*} input - The input value to check.
+ * @returns {boolean} Return `true` if it can be reasonably parsed into a currency-like number, `false` otherwise.
+ * @example
+ * isCurrencyLike(15300.95);
+ * // ➔ true
+ * isCurrencyLike("$15,000.10");
+ * // ➔ true
+ * isCurrencyLike("(15'000.10)");
+ * // ➔ true
+ * isCurrencyLike("Rp 15.000,10");
+ * // ➔ true
+ * isCurrencyLike("");
+ * // ➔ false
+ * isCurrencyLike("abc");
+ * // ➔ false
+ */
+declare const isCurrencyLike: (input: unknown) => boolean;
+type isDateOptions = {
+  /** * ***Skip the validity check (`!isNaN(date.getTime())`).***
+   *
+   * When `true`, the function only checks that the value is an
+   * instance of `Date` without verifying that it represents a valid
+   * date value, default: `false`.
+   *
+   * @default false
+   */
+  skipInvalidDate?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Type guard: `isDate`.***
+ * ----------------------------------------------------------
+ * **Determines whether the given `value` is a real, valid JavaScript
+ *   **[`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** object.**
+ * - **Behavior:**
+ *    - Returns **true** only if:
+ *      - `value` is an instance of `Date`.
+ *      - and, unless `options.skipInvalidDate` is `true`,
+ *        the underlying time value is valid (`!isNaN(value.getTime())`).
+ *    - Returns **false** for:
+ *      - non-Date values (strings, numbers, etc.).
+ *      - `Date` instances that represent an invalid time value
+ *        (e.g. `new Date("bad")`), unless skipping is enabled.
+ * @param {*} value - The value to check.
+ * @param {isDateOptions} [options] - Optional settings.
+ * @returns {boolean} Return `true` if value is a valid Date object.
+ * @example
+ * isDate(new Date());
+ * // ➜ true
+ * isDate(new Date("invalid"));
+ * // ➜ false
+ * isDate("2024-01-01");
+ * // ➜ false
+ *
+ * // Skipping validity check:
+ * isDate(new Date("invalid"), { skipInvalidDate: true });
+ * // ➜ true
+ */
+declare const isDate: (value: unknown, options?: isDateOptions) => value is Date;
+/** ----------------------------------------------------------
+ * * ***Predicate: `isDeepEqual`.***
+ * ----------------------------------------------------------
+ * **Performs a deep equality check between two values.**
+ * - **Behavior:**
+ *    - Compares nested `arrays`, `objects`, `Dates`, `RegExp`, `NaN`, `Symbols`,
+ *      `Set`, and `Map`.
+ *    - Handles special cases:
+ *        - `NaN` is considered equal to `NaN`.
+ *        - `Date` objects are equal if `.getTime()` is equal.
+ *        - `RegExp` objects are equal if `.toString()` is equal.
+ *        - `Symbol("x")` and `Symbol("x")` are treated equal if
+ *          `.toString()` matches.
+ *        - `Set` and `Map` are deeply compared by content (order-insensitive).
+ * - **ℹ️ Note:**
+ *    - Does not support circular references.
+ * @param {*} a - First value to compare.
+ * @param {*} b - Second value to compare.
+ * @returns {boolean} `true` if both values are deeply equal, otherwise `false`.
+ * @example
+ * // ✅ Primitives
+ * isDeepEqual(1, 1);
+ * // ➔ true
+ * isDeepEqual(NaN, NaN);
+ * // ➔ true
+ * isDeepEqual("hello", "world");
+ * // ➔ false
+ *
+ * // ✅ Objects
+ * isDeepEqual({ x: 1 }, { x: 1 });
+ * // ➔ true
+ * isDeepEqual({ x: 1 }, { y: 1 });
+ * // ➔ false
+ *
+ * // ✅ Arrays
+ * isDeepEqual([1, 2], [1, 2]);
+ * // ➔ true
+ * isDeepEqual([1, 2], [2, 1]);
+ * // ➔ false
+ *
+ * // ✅ Dates
+ * isDeepEqual(new Date(123), new Date(123));
+ * // ➔ true
+ *
+ * // ✅ Sets
+ * isDeepEqual(new Set([1, 2]), new Set([2, 1]));
+ * // ➔ true
+ *
+ * // ✅ Maps
+ * isDeepEqual(new Map([["a", 1]]), new Map([["a", 1]]));
+ * // ➔ true
+ *
+ * // ❌ Different types
+ * isDeepEqual(1, "1");
+ * // ➔ false
+ */
+declare const isDeepEqual: (a: unknown, b: unknown) => boolean;
+/** ----------------------------------------------------
+ * * ***Type guard: `isElement`.***
+ * ----------------------------------------------------------
+ * **Checks if `value` is likely a
+ *   **[`DOM Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element)**.**
+ * @template T - The type of the value being checked.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is extends instance of **[`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element)**, else `false`.
+ * @example
+ * isElement(document.body);
+ * // ➔ true
+ * isElement(document.createElement("div"));
+ * // ➔ true
+ * isElement('<body>');
+ * // ➔ false
+ * isElement(document);
+ * // ➔ false
+ * isElement({ tagName: "DIV" });
+ * // ➔ false
+ */
+declare function isElement(value: []): value is [];
+declare function isElement<T extends Element>(value: T): value is T;
+declare function isElement(value: unknown): value is Element;
+/**
+ * -------------------------------------------------------------------
+ * * ***Array-like structure interface.***
+ * -------------------------------------------------------------------
+ * **Represents objects with indexed elements and a `length` property,
+ * similar to arrays, but not necessarily full Array instances.**
+ * @template T The type of elements stored in the array-like object.
+ * @example
+ * ```ts
+ * function logArrayLike<T>(items: ArrayLike<T>) {
+ *   for (let i = 0; i < items.length; i++) {
+ *     console.log(items[i]);
+ *   }
+ * }
+ *
+ * const myNodeList: ArrayLike<Element> = document.querySelectorAll("div");
+ * logArrayLike(myNodeList);
+ * ```
+ */
+interface ArrayLike<T> {
+  /** * ***Number of elements in the array-like object.*** */
+  readonly length: number;
+  /** * ***Indexed access to elements.*** */
+  readonly [n: number]: T;
+}
+/** -------------------------------------------------------------------
+ * * ***Represents an object with no allowed properties.***
+ * -------------------------------------------------------------------
+ * **Useful for cases where you want to ensure a type has **no keys**.**
+ * @template T - The base type to convert into an empty object type.
+ * @example
+ * ```ts
+ * type Test = EmptyObject<{ a: number }>;
+ * // ➔ { a?: never }
+ * ```
+ */
+type EmptyObject<T> = { [K in keyof T]?: never };
+/** -------------------------------------------------------------------
+ * * ***Conditional empty object type.***
+ * -------------------------------------------------------------------
+ * **Produces `EmptyObject<T>` only if it is assignable to `T`.**
+ * @template T - The base type to check.
+ * @example
+ * ```ts
+ * type Test = EmptyObjectOf<{ a: number }>;
+ * // ➔ { a?: never } | never depending on assignability
+ * ```
+ */
+type EmptyObjectOf<T> = EmptyObject<T> extends T ? EmptyObject<T> : never;
+/** -------------------------------------------------------------------
+ * * ***List type alias.***
+ * -------------------------------------------------------------------
+ * **Represents any array-like structure.**
+ * @template T - The type of elements in the list.
+ * @example
+ * ```ts
+ * const arr: List<number> = [1, 2, 3];
+ * const nodeList: List<Element> = document.querySelectorAll("div");
+ * ```
+ */
+type List<T> = ArrayLike<T>;
+/** ----------------------------------------------------
+ * * ***Predicate: `isEmpty`.***
+ * ----------------------------------------------------------
+ * **Checks if `value` is an empty object, collection, map, or set.**
+ * - **Behavior:**
+ *    - **Objects** are empty if they have no own enumerable string keyed properties.
+ *    - **Array-like values** (arrays, strings, `arguments`, typed arrays, buffers)
+ *      are empty if their `length` is `0`.
+ *    - **Maps** and **Sets** are empty if their `size` is `0`.
+ *    - **Booleans**, **numbers** (including `NaN`), **symbols**, and `null`/
+ *      `undefined` are treated as empty.
+ *    - **Functions** are considered empty if they have no own enumerable keys.
+ * - **ℹ️ Note:**
+ *    - For more `Strict`, you can use
+ *      ***`isEmptyValue` utility function*** instead.
+ * @template T - The type of the value being checked.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is empty, else `false`.
+ * @example
+ * isEmpty(null);
+ * // ➔ true
+ * isEmpty(true);
+ * // ➔ true
+ * isEmpty(false);
+ * // ➔ true
+ * isEmpty(1);
+ * // ➔ true
+ * isEmpty(0);
+ * // ➔ true
+ * isEmpty(Symbol("x"));
+ * // ➔ true
+ * isEmpty(() => {});
+ * // ➔ true
+ * isEmpty("");
+ * // ➔ true
+ * isEmpty("   ");
+ * // ➔ false
+ * isEmpty([1, 2, 3]);
+ * // ➔ false
+ * isEmpty({ 'a': 1 });
+ * // ➔ false
+ */
+declare function isEmpty<T extends {
+  __trapAny: any;
+}>(value?: T): boolean;
+declare function isEmpty(value: string): value is "";
+declare function isEmpty(value: Map<any, any> | Set<any> | List<any> | null | undefined): boolean;
+declare function isEmpty(value: object): boolean;
+declare function isEmpty<T extends object>(value: T | null | undefined): value is EmptyObjectOf<T> | null | undefined;
+declare function isEmpty(value: any): boolean;
+/** ----------------------------------------------------------
+ * * ***Predicate: `isEmptyArray`.***
+ * ----------------------------------------------------------
+ * **Checks whether a given value is an empty array.**
+ * - **Behavior:**
+ *    - Non-array inputs are considered ***`empty`*** ***(defensive strategy)***.
+ * @param {*} [value] - The value to check.
+ * @returns {boolean} Returns `true` if it's ***not an array*** or ***an empty-array***.
+ * @example
+ * isEmptyArray([]);             // ➔ true
+ * isEmptyArray([1, 2, 3]);      // ➔ false
+ * isEmptyArray("not an array"); // ➔ true
+ * isEmptyArray(null);           // ➔ true
+ * isEmptyArray(undefined);      // ➔ true
+ *
+ * if (isEmptyArray(data.items)) {
+ *   console.log("No items to display.");
+ * }
+ */
+declare const isEmptyArray: (value: unknown) => boolean;
+/** ----------------------------------------------------------
+ * * ***Predicate: `isEmptyDeep`.***
+ * ----------------------------------------------------------
+ * **Recursively checks whether a value is **deeply empty**.**
+ * - **Returns `true` for:**
+ *    - Empty objects: `{}`
+ *    - Empty arrays: `[]`
+ *    - Nested empty structures: `{ a: [], b: {} }`
+ *    - Falsy values (except numbers): `null`, `undefined`, `false`, `""`, `NaN`
+ * - **Returns `false` for:**
+ *    - Non-zero numbers
+ *    - Objects or arrays containing non-empty values
+ *    - Non-empty strings, `true`, functions, symbols, etc.
+ * @param {*} value - The value to deeply check.
+ * @returns {boolean} `true` if the value is deeply empty, otherwise `false`.
+ * @example
+ * isEmptyDeep({});
+ * // ➔ true
+ * isEmptyDeep([]);
+ * // ➔ true
+ * isEmptyDeep({ a: {} });
+ * // ➔ true
+ * isEmptyDeep([[], {}]);
+ * // ➔ true
+ * isEmptyDeep({ a: [1] });
+ * // ➔ false
+ * isEmptyDeep([0]);
+ * // ➔ false
+ * isEmptyDeep("test");
+ * // ➔ false
+ * isEmptyDeep("");
+ * // ➔ true
+ * isEmptyDeep(0);
+ * // ➔ false
+ * isEmptyDeep(NaN);
+ * // ➔ true
+ */
+declare const isEmptyDeep: (value: unknown) => boolean;
+type IsEmptyObjectOptions = {
+  /** Whether to check for symbol properties in addition to string keys, defaultValue: `false`.
+   *
+   * @default false
+   */
+  checkSymbols?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Predicate: `isEmptyObject`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a plain object with **no own enumerable string-key properties**,
+ * and optionally **no own enumerable symbol-key properties** when `checkSymbols` is `true`.**
+ * - **Behavior:**
+ *    - If the value is **not an object** (e.g. `null`, array, primitive), it is considered empty.
+ *    - If `options.checkSymbols` is `true`, **symbol properties** are also checked.
+ * @param {*} value - The value to check.
+ * @param {IsEmptyObjectOptions} [options] - Optional settings.
+ * @param {IsEmptyObjectOptions["checkSymbols"]} [options.checkSymbols=false] - Whether to also check symbol properties.
+ * @returns {boolean} Return `true` if the value is considered empty or not an object, false otherwise.
+ * @example
+ * isEmptyObject({});
+ * // ➔ true
+ * isEmptyObject({}, { checkSymbols: true });
+ * // ➔ true
+ * isEmptyObject({ a: 1 });
+ * // ➔ false
+ * isEmptyObject({ [Symbol('s')]: 1 });
+ * // ➔ true
+ * isEmptyObject({ [Symbol('s')]: 1 }, { checkSymbols: true });
+ * // ➔ false
+ * isEmptyObject(null);
+ * // ➔ true (not object)
+ * isEmptyObject([]);
+ * // ➔ true (not plain object)
+ * isEmptyObject(123);
+ * // ➔ true (not object)
+ */
+declare function isEmptyObject(value: unknown, options?: IsEmptyObjectOptions): boolean;
+type IsEmptyStringOptions = {
+  /** Whether to trim the string before checking, defaultValue: `true`.
+   *
+   * @default true */
+  trim?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Predicate: `isEmptyString`.***
+ * ----------------------------------------------------------
+ * **Checks whether a given value is an **empty-string**.**
+ * - **Behavior:**
+ *    - Considers `""` and whitespace-only strings as
+ *      empty (if `trim` is enabled, which is the default).
+ *    - Non-string inputs are also considered empty.
+ * @param {*} value - The value to check.
+ * @param {IsEmptyStringOptions} [options] - Optional settings.
+ * @param {IsEmptyStringOptions["trim"]} [options.trim=true] - Whether to trim the string before checking, defaultValue: `true`.
+ * @returns {boolean} Returns `true` if the value is string not a string or value string is considered empty.
+ * @example
+ * isEmptyString("");
+ * // ➔ true
+ * isEmptyString("   ");
+ * // ➔ true (default trims)
+ * isEmptyString("   ", { trim: false });
+ * // ➔ false
+ * isEmptyString("hello");
+ * // ➔ false
+ * isEmptyString(undefined);
+ * // ➔ true
+ * isEmptyString(null);
+ * // ➔ true
+ * isEmptyString(123 as any);
+ * // ➔ true
+ *
+ * // Used in validation
+ * if (isEmptyString(form.name)) {
+ *   throw new Error("Name cannot be empty.");
+ * }
+ */
+declare const isEmptyString: (value: unknown, options?: IsEmptyStringOptions) => boolean;
+type IsEmptyValueOptions = {
+  /** **Whether to check symbol properties when checking empty objects.**
+   * - **DefaultValue:** `false`.
+   *
+   * @default false
+   */
+  checkSymbols?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Predicate: `isEmptyValue`.***
+ * ----------------------------------------------------------
+ * **Determines if a value is **`empty`**.**
+ * - **Covering:**
+ *    - Empty objects: `{}`
+ *    - Empty arrays: `[]`
+ *    - Empty strings: `""` or whitespace-only (trimmed)
+ *    - `null`, `undefined`, `false`, or `NaN`
+ * - **Returns **`false`** for:**
+ *    - Non-empty objects/arrays
+ *    - Non-empty strings
+ *    - Numbers (except `NaN`)
+ *    - `Functions`, `true`, `symbols`, `etc`.
+ * @param {*} value - The value to evaluate.
+ * @param {IsEmptyValueOptions} [options] - Optional settings.
+ * @returns {boolean} Return `true` if the value is considered empty, otherwise `false`.
+ * @example
+ * isEmptyValue({});
+ * // ➔ true
+ * isEmptyValue([]);
+ * // ➔ true
+ * isEmptyValue({ key: "value" });
+ * // ➔ false
+ * isEmptyValue({ [Symbol("foo")]: 123 });
+ * // ➔ true (default `checkSymbols` is `false`)
+ * isEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: false });
+ * // ➔ true (default `checkSymbols` is `false`)
+ * isEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: true });
+ * // ➔ false
+ * isEmptyValue([1, 2, 3]);
+ * // ➔ false
+ * isEmptyValue(NaN);
+ * // ➔ true
+ * isEmptyValue(true);
+ * // ➔ false
+ * isEmptyValue(false);
+ * // ➔ true
+ * isEmptyValue(null);
+ * // ➔ true
+ * isEmptyValue(undefined);
+ * // ➔ true
+ * isEmptyValue("");
+ * // ➔ true
+ * isEmptyValue("   ");
+ * // ➔ true
+ * isEmptyValue(0);
+ * // ➔ false
+ * isEmptyValue(-1);
+ * // ➔ false
+ * isEmptyValue(2);
+ * // ➔ false
+ * isEmptyValue(() => {});
+ * // ➔ false
+ */
+declare const isEmptyValue: (value: unknown, options?: IsEmptyValueOptions) => boolean;
+/** ----------------------------------------------------
+ * * ***Predicate: `isEqual`.***
+ * ----------------------------------------------------------
+ * **Performs a deep comparison between two values to determine if they are equivalent.**
+ * @description
+ * Checks whether two values are **deeply equal**, not just reference-equal (`===`).
+ * - **✅ This method compares:**
+ *   - Arrays and TypedArrays
+ *   - ArrayBuffers
+ *   - Plain objects (`Object`) ➔ own enumerable properties only
+ *   - Booleans, Numbers, Strings, Symbols
+ *   - Dates
+ *   - Errors
+ *   - Maps
+ *   - Sets
+ *   - Regular expressions
+ * - ❌ `Functions` and `DOM nodes` are ***not supported***.
+ * @param {*} value The value to compare.
+ * @param {*} other The other value to compare.
+ * @returns {boolean} Returns `true` if the values are equivalent, else `false`.
+ * @example
+ * const obj1 = { user: "fred" };
+ * const obj2 = { user: "fred" };
+ *
+ * isEqual(obj1, obj2);
+ * // ➔ true
+ * obj1 === obj2;
+ * // ➔ false (different references)
+ * isEqual([1, 2, 3], [1, 2, 3]);
+ * // ➔ true
+ * isEqual(new Date("2020-01-01"), new Date("2020-01-01"));
+ * // ➔ true
+ * isEqual(new Set([1, 2]), new Set([2, 1]));
+ * // ➔ true
+ * isEqual(/abc/i, new RegExp("abc", "i"));
+ * // ➔ true
+ * isEqual({ a: 1 }, { a: 1, b: undefined });
+ * // ➔ false
+ */
+declare function isEqual(value: unknown, other: unknown): boolean;
+/** -------------------------------------------------------------------
+ * * ***Customizer function for `isEqualWith`.***
+ * -------------------------------------------------------------------
+ * **Allows customizing how two values are compared for deep equality.**
+ * @param value
+ * - The current value being compared.
+ * @param other
+ * - The corresponding value from the other object.
+ * @param indexOrKey
+ * - The property key (for objects) or index (for arrays) of the current value.
+ * @param parent
+ * - The parent object or array containing `value`.
+ * @param otherParent
+ * - The parent object or array containing `other`.
+ * @param stack
+ * - WeakMap or tracking structure for already visited objects to handle circular references.
+ * @returns
+ * - `true`  → Treat the values as equal.
+ * - `false` → Treat the values as unequal.
+ * - `undefined` → Fallback to default deep equality comparison.
+ * @example
+ * ```ts
+ * const customizer: CustomizerIsEqualWith = (value, other, key) => {
+ *   if (typeof value === "string" && typeof other === "string") {
+ *     return value.toLowerCase() === other.toLowerCase();
+ *   }
+ *   return undefined;
+ * };
+ *
+ * baseDeepEqual({ name: "Alice" }, { name: "alice" }, customizer);
+ * // returns true
+ * ```
+ */
+type CustomizerIsEqualWith = (/** * ***The current value being compared.*** */
+
+value: unknown, /** * ***The corresponding value from the other object.*** */
+
+other: unknown, /** * ***Property key (for objects) or index (for arrays) of the current value.*** */
+
+indexOrKey: PropertyKey, /** * ***Parent object or array containing `value`.*** */
+
+parent: unknown, /** * ***Parent object or array containing `other`.*** */
+
+otherParent: unknown, /** * ***WeakMap or tracking structure for visited objects to handle circular references.*** */
+
+stack: unknown) => boolean | undefined;
+/** ----------------------------------------------------
+ * * ***Predicate: `isEqualWith`.***
+ * ----------------------------------------------------
+ * **Performs a deep comparison between two values with support for a
+ * customizer function.**
+ * @description
+ * This method is like ***`isEqual` utility function*** except that it
+ * accepts a `customizer` which is invoked to compare values.
+ * - **Behavior:**
+ *     - If `customizer` returns `undefined`, the comparison is handled by
+ *       the default deep equality algorithm.
+ *     - The `customizer` is invoked with up to six arguments:
+ *       - `(value, other, indexOrKey, parent, otherParent, stack)`,
+ *         see **{@link CustomizerIsEqualWith | `CustomizerIsEqualWith`}**.
+ *     - Supports comparing `arrays`, `objects`, `maps`, `sets`, `dates`,
+ *       `regexes`, `typed arrays`, `etc`.
+ *     - Functions and DOM nodes are **not** supported.
+ * @param {*} value The value to compare.
+ * @param {*} other The other value to compare.
+ * @param {CustomizerIsEqualWith} [customizer] The function to customize comparisons.
+ * @returns {boolean} Returns `true` if the values are equivalent, else `false`.
+ * @example
+ * function isGreeting(value: unknown) {
+ *   return typeof value === "string" && /^h(?:i|ello)$/.test(value);
+ * }
+ *
+ * function customizer(objValue: unknown, othValue: unknown) {
+ *   if (isGreeting(objValue) && isGreeting(othValue)) {
+ *     return true;
+ *   }
+ * }
+ *
+ * const array = ["hello", "goodbye"];
+ * const other = ["hi", "goodbye"];
+ *
+ * isEqualWith(array, other, customizer);
+ * // ➔ true
+ */
+declare function isEqualWith(value: unknown, other: unknown, customizer?: CustomizerIsEqualWith): boolean;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isError`.***
+ * ----------------------------------------------------------
+ * **Checks whether the given value is an ****[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** object**.**
+ * - **Behavior:**
+ *    - Ensures that the provided value is a valid JavaScript error instance.
+ *    - Useful in TypeScript for narrowing types during error handling.
+ * @param {*} error - The value to check.
+ * @returns {boolean} Returns `true` if `value` is instance of **[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)**, else `false`.
+ * @example
+ * isError(new Error("Something went wrong"));
+ * // ➔ true
+ * isError("Error message");
+ * // ➔ false
+ * isError(null);
+ * // ➔ false
+ */
+declare const isError: (error: unknown) => error is Error;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isFinite`.***
+ * -----------------------------------------------------------
+ * **Checks if a value is a finite primitive number.**
+ * @description
+ * This function verifies that `value` is a **primitive number** and is **finite**
+ * (i.e., not `NaN`, `Infinity`, or `-Infinity`).
+ * - **Behavior:**
+ *    - Behaves like
+ *      [`Number.isFinite()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite).
+ *    - But also works as a **TypeScript type guard**.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if `value` is a finite primitive number, else `false`.
+ * @example
+ * import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
+ *
+ * // Strict finite number check (only primitive numbers)
+ * RzlUtilsJs.isFinite(3);
+ * // ➔ true
+ * RzlUtilsJs.isFinite(Number.MIN_VALUE);
+ * // ➔ true
+ * RzlUtilsJs.isFinite("3");
+ * // ➔ false (string is not a number)
+ * RzlUtilsJs.isFinite(NaN);
+ * // ➔ false
+ * RzlUtilsJs.isFinite(Infinity);
+ * // ➔ false
+ * RzlUtilsJs.isFinite(new Number(3));
+ * // ➔ false (Number object is not primitive)
+ *
+ * // Comparison with global isFinite()
+ * isFinite("3");
+ * // ➔ true (global coerces string to number)
+ * isFinite(new Number(3));
+ * // ➔ true (object coerced to primitive number)
+ */
+declare function isFinite(value: unknown): value is number;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isFunction`.***
+ * -----------------------------------------------------------
+ * **Checks if a value is a function.**
+ * - **Behavior:**
+ *    - Uses `typeof value === "function"` for strict type checking.
+ *    - Safe alternative to `Function` type (doesn't trigger ESLint warning).
+ *    - Supports TypeScript type narrowing with `value is (...args: any[]) => any`.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if the value is a function.
+ * @example
+ * isFunction(() => {});
+ * // ➔ true
+ * isFunction(async () => {});
+ * // ➔ true
+ * isFunction(null);
+ * // ➔ false
+ * isFunction({});
+ * // ➔ false
+ */
+declare const isFunction: (value: unknown) => value is AnyFunction;
+/** ----------------------------------------------------
+ * * ***Type guard: `isInfinityNumber`.***
+ * ----------------------------------------------------
+ * **Checks if a value is positive or negative
+ * [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity).**
+ * - **ℹ️ Note:**
+ *    - This is stricter than the global `isFinite`,
+ *      because it only returns `true` for `Infinity` or `-Infinity`,
+ *      not other non-finite values.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is `Infinity` or `-Infinity`, else `false`.
+ * @example
+ * import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
+ *
+ * RzlUtilsJs.isInfinityNumber(Infinity);
+ * // ➔ true
+ * RzlUtilsJs.isInfinityNumber(-Infinity);
+ * // ➔ true
+ * RzlUtilsJs.isInfinityNumber(new Number(Infinity));
+ * // ➔ true
+ * RzlUtilsJs.isInfinityNumber(NaN);
+ * // ➔ false
+ * RzlUtilsJs.isInfinityNumber(123);
+ * // ➔ false
+ */
+declare function isInfinityNumber(value: unknown): boolean;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isInteger`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is an integer number.**
+ * - **ℹ️ Note:**
+ *    - This method is based on
+ *      [`Number.isInteger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger).
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is an integer, else `false`.
+ * @example
+ * isInteger(3);
+ * // ➔ true
+ * isInteger(Number.MIN_VALUE);
+ * // ➔ false
+ * isInteger(NaN);
+ * // ➔ false
+ * isInteger(Infinity);
+ * // ➔ false
+ * isInteger(-Infinity);
+ * // ➔ false
+ * isInteger('3');
+ * // ➔ false
+ */
+declare function isInteger(value: unknown): value is number;
+/** ----------------------------------------
+ * * ***Predicate: `isLength`.***
+ * ----------------------------------------------------------
+ * **Checks whether the given value is a **valid array-like length**.**
+ * - **Behavior:**
+ *    - ✅ Ensures the value is a **non-negative integer**.
+ *    - ✅ Ensures the value is **not greater than `Number.MAX_SAFE_INTEGER`**.
+ *    - ❌ Excludes non-numeric values, `Infinity`, and fractional numbers.
+ * - **ℹ️ Note:**
+ *    - This method is loosely based-on
+ *      [`ToLength`](http://ecma-international.org/ecma-262/7.0/#sec-tolength).
+ *    - A valid length must be a non-negative integer and **not greater
+ *      than `Number.MAX_SAFE_INTEGER`**.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a valid length, else `false`.
+ * @example
+ * isLength(3);
+ * // ➔ true
+ * isLength(Number.MAX_SAFE_INTEGER);
+ * // ➔ true
+ * isLength(Number.MAX_SAFE_INTEGER + 1);
+ * // ➔ false
+ * isLength("3");
+ * // ➔ false
+ * isLength(-1);
+ * // ➔ false
+ * isLength(3.14);
+ * // ➔ false
+ * isLength(Infinity);
+ * // ➔ false
+ * isLength(-Infinity);
+ * // ➔ false
+ * isLength(Number.MIN_VALUE);
+ * // ➔ false
+ */
+declare function isLength(value: unknown): boolean;
+/** --------------------------------------------------
+ * * ***Type guard: `isMap`.***
+ * ----------------------------------------------------------
+ * **Checks whether the given value is a **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object**.**
+ * - **Behavior:**
+ *    - Ensures that the provided value is an instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**.
+ *    - Useful in TypeScript for narrowing types when working with collections.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**, else `false`.
+ * @example
+ * isMap(new Map());
+ * // ➔ true
+ * isMap(new WeakMap());
+ * // ➔ false
+ * isMap({});
+ * // ➔ false
+ */
+declare function isMap<K = unknown, V = unknown>(value: Map<K, V>): value is Map<K, V>;
+declare function isMap(value: unknown): value is Map<unknown, unknown>;
+/** ----------------------------------------------------
+ * * ***Predicate: `isMatch`.***
+ * ----------------------------------------------------
+ * **Performs a partial deep comparison between `object` and `source`.**
+ * @description
+ * Determines whether `object` contains equivalent property values from `source`.
+ * - **Behavior:**
+ *    - ✅ Returns `true` if **all properties** in `source` exist in `object` and are deeply equal.
+ *    - ❌ Does **not** require `object` and `source` to be the same shape—`object` may have extra properties.
+ *    - ⚠️ Arrays are treated as objects: only matching indexed keys are compared.
+ * - **Remarks:**
+ *    - This is functionally equivalent to a partially applied `matches(source)` predicate.
+ *    - Special cases:
+ *      - An empty array (`[]`) in `source` matches any array in `object`.
+ *      - An empty object (`{}`) in `source` matches any object in `object`.
+ * @param {object} object - The object to inspect.
+ * @param {object} source - The object containing property values to match.
+ * @returns {boolean} Returns `true` if `object` is a match, else `false`.
+ * @example
+ * const object = { a: 1, b: 2 };
+ *
+ * isMatch(object, { b: 2 });
+ * // ➔ true
+ * isMatch(object, { b: 1 });
+ * // ➔ false
+ * isMatch([1, 2, 3], [1, 2]);
+ * // ➔ true (treats arrays as objects with index keys)
+ */
+declare function isMatch(object: object, source: object): boolean;
+/** -------------------------------------------------------------------
+ * * ***Customizer function for `isMatchWith`.***
+ * -------------------------------------------------------------------
+ * **Allows customizing how two values are compared for partial/object match.**
+ * @param value
+ * - The current value from the object being tested.
+ * @param other
+ * - The corresponding value from the source object.
+ * @param indexOrKey
+ * - The property key (for objects) or index (for arrays) of the current value.
+ * @param object
+ * - The parent object containing `value`.
+ * @param source
+ * - The parent source object containing `other`.
+ * @returns
+ * - `true`  → Treat the values as matching.
+ * - `false` → Treat the values as not matching.
+ * - `undefined` → Fallback to default match comparison.
+ * @example
+ * ```ts
+ * const customizer: CustomizerIsMatchWith = (value, other) => {
+ *   if (typeof value === "string" && typeof other === "string") {
+ *     return value.toLowerCase() === other.toLowerCase();
+ *   }
+ *   return undefined;
+ * };
+ *
+ * baseIsMatch({ name: "Alice" }, { name: "alice" }, customizer);
+ * // returns true
+ * ```
+ */
+type CustomizerIsMatchWith = (/** * ***Current value from the object being tested.*** */
+
+value: unknown, /** * ***Corresponding value from the source object.*** */
+
+other: unknown, /** * ***Property key (objects) or index (arrays) of the current value.*** */
+
+indexOrKey: PropertyKey, /** * ***Parent object containing `value`.*** */
+
+object: object, /** * ***Parent source object containing `other`.*** */
+
+source: object) => boolean | undefined;
+/** ----------------------------------------------------
+ * * ***Predicate: `isMatchWith`.***
+ * ----------------------------------------------------
+ * **Performs a partial deep comparison between `object` and `source`, like `isMatch`, but with a `customizer` function to control comparisons.**
+ * @description
+ * If `customizer` returns a value other than `undefined`, that value is used
+ * as the result of the comparison for the current property. Otherwise,
+ * the comparison falls back to the default deep equality logic.
+ * - **Behavior:**
+ *    - The `customizer` function is invoked with up to **five** arguments:
+ *        - `(objValue, srcValue, keyOrIndex, object, source)`,
+ *        see **{@link CustomizerIsMatchWith | `CustomizerIsMatchWith`}**.
+ *    - Returning `true` from `customizer` will short-circuit further comparison
+ *      for that key.
+ *    - Returning `false` will cause `isMatchWith` to return `false` immediately.
+ *    - Returning `undefined` allows default comparison to proceed.
+ * @param {object} value - The object to inspect.
+ * @param {object} other - The object of property values to match.
+ * @param {CustomizerIsMatchWith} [customizer] - The function to customize comparisons.
+ * @returns Returns `true` if `object` is a match, else `false`.
+ * @example
+ * function isGreeting(value: unknown) {
+ *   return typeof value === 'string' && /^h(?:i|ello)$/.test(value);
+ * }
+ *
+ * function customizer(objValue: unknown, srcValue: unknown) {
+ *   if (isGreeting(objValue) && isGreeting(srcValue)) {
+ *     return true;
+ *   }
+ * }
+ *
+ * const object = { greeting: 'hello' };
+ * const source = { greeting: 'hi' };
+ *
+ * isMatchWith(object, source, customizer);
+ * // ➔ true
+ */
+declare function isMatchWith(value: object, other: object, customizer?: CustomizerIsMatchWith): boolean;
+/** ----------------------------------------------------
+ * * ***Type guard: `isNaN`.***
+ * ----------------------------------------------------
+ * **Checks if a value is [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN).**
+ * - **ℹ️ Note:**
+ *    - This method is based on
+ *      [`Number.isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN)
+ *      and is **not** the same as the global
+ *      [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN),
+ *      which returns `true` for `undefined` and other non-number values.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is `NaN`, else `false`.
+ * @example
+ * import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
+ *
+ * RzlUtilsJs.isNaN(NaN);
+ * // ➔ true
+ * RzlUtilsJs.isNaN(new Number(NaN));
+ * // ➔ true
+ * RzlUtilsJs.isNaN(undefined);
+ * // ➔ false
+ *
+ * // This global isNaN:
+ * isNaN(undefined);
+ * // ➔ true
+ */
+declare function isNaN(value: unknown): boolean;
+/** ----------------------------------------------------
+ * * ***Type guard: `isNative`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a **pristine native function**.**
+ * - **ℹ️ Note:**
+ *    - This method may not reliably detect native functions when using packages
+ *      like `core-js`, as they override native behavior.
+ *    - Attempts to detect native functions in such environments may fail or
+ *      throw errors.
+ *    - This also affects packages like
+ *      **[`babel-polyfill`](https://www.npmjs.com/package/babel-polyfill).**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a native function, else `false`.
+ * @example
+ * isNative(Array.prototype.push);
+ * // ➔ true
+ *
+ * import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
+ * isNative(RzlUtilsJs);
+ * // ➔ false
+ */
+declare function isNative(value: unknown): value is AnyFunction;
+/** ----------------------------------------------------
+ * * ***Type guard: `isNil`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is **[`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null)** or **[`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)**.**
+ * - **Behavior:**
+ *    - Narrows type to `null` or `undefined` when true.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is `null` or `undefined`, otherwise `false`.
+ * @example
+ * isNil(null);
+ * // ➔ true
+ * isNil(undefined);
+ * // ➔ true
+ * isNil(void 0);
+ * // ➔ true
+ * isNil(NaN);
+ * // ➔ false
+ */
+declare function isNil(value: unknown): value is null | undefined;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isNonEmptyArray`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a **non-empty array**.**
+ * - **Behavior:**
+ *    - Ensures the value is an actual array using **[`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)**.
+ *    - Ensures the array contains at least one item.
+ *    - Narrows type to `T[]` (non-empty array) when true.
+ * @template T - The type of the value being checked.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if value is a non-empty array.
+ * @example
+ * isNonEmptyArray([1, 2, 3]); // ➔ true
+ * isNonEmptyArray([]);        // ➔ false
+ * isNonEmptyArray(null);      // ➔ false
+ * isNonEmptyArray("test");    // ➔ false
+ */
+declare function isNonEmptyArray(value: []): value is [];
+declare function isNonEmptyArray<T>(value: T): value is ArrayFallback<T>;
+declare function isNonEmptyArray(value: unknown): value is unknown[];
+type IsNonEmptyStringOptions = {
+  /** Whether to trim the string before checking, defaultValue: `true`.
+   *
+   * @default true */
+  trim?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Type guard: `isNonEmptyString`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a **non-empty string**.**
+ * @description
+ * Determines whether the given `value` is a string containing at least one non-whitespace character, with optional trimming behavior.
+ * - **Behavior:**
+ *    - Ensures the value is a string using ***`isString` utility function***.
+ *    - Optionally trims whitespace before checking (`trim` defaults to `true`).
+ *    - Narrows type to `string` when true.
+ * @param {*} value - The value to test.
+ * @param {IsNonEmptyStringOptions} [options] - Optional settings.
+ * @param {boolean} options.trim - If `true`, trims the string before checking, defaults: `true`.
+ * @returns {boolean} Return `true` if `value` is a non-empty string, otherwise `false`.
+ * @example
+ * isNonEmptyString("hello");
+ * // ➔ true
+ * isNonEmptyString("   ", { trim: true });
+ * // ➔ false
+ * isNonEmptyString("   ", { trim: false });
+ * // ➔ true
+ * isNonEmptyString("");
+ * // ➔ false
+ * isNonEmptyString(123);
+ * // ➔ false
+ * isNonEmptyString(undefined);
+ * // ➔ false
+ * isNonEmptyString(null);
+ * // ➔ false
+ * isNonEmptyString({});
+ * // ➔ false
+ * isNonEmptyString([]);
+ * // ➔ false
+ */
+declare const isNonEmptyString: (value: unknown, options?: IsNonEmptyStringOptions) => value is string;
+type IsNonEmptyValueOptions = {
+  /** Whether to check symbol properties when checking empty objects, default: `false`.
+   *
+   * @default false
+   */
+  checkSymbols?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Predicated: `isNonEmptyValue`.***
+ * ----------------------------------------------------------
+ * **Determines if a value is a **non-empty** object (`{}` with props), **non-empty** array (`[]` with items) or generally truthy.**
+ * - **Behavior:**
+ *    - Returns `true` for:
+ *      - Objects **with properties**
+ *      - Arrays **with items**
+ *      - Non-empty, non-whitespace strings
+ *      - Numbers (except `NaN`, includes `0`)
+ *      - Functions
+ *      - `true`
+ *    - Returns `false` for:
+ *      - Empty objects (`{}`)
+ *      - Empty arrays (`[]`)
+ *      - `null` or `undefined`
+ *      - Empty strings (`""`) or whitespace-only strings (`"  "`)
+ *      - `false`
+ *      - `NaN`
+ *    - Safely handles `null`, `undefined`, and non-object types without throwing.
+ * @param {*} value - The value to evaluate.
+ * @param {IsNonEmptyValueOptions} [options] - Optional settings.
+ * @returns {boolean} Return `true` if the value is considered non-empty/truthy, otherwise `false`.
+ * @example
+ * isNonEmptyValue({});
+ * // ➔ false
+ * isNonEmptyValue([]);
+ * // ➔ false
+ * isNonEmptyValue({ key: "value" });
+ * // ➔ true
+ * isNonEmptyValue({ [Symbol("foo")]: 123 });
+ * // ➔ false (default `checkSymbols` is `false`)
+ * isNonEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: false });
+ * // ➔ false (default `checkSymbols` is `false`)
+ * isNonEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: true });
+ * // ➔ true
+ * isNonEmptyValue([1, 2, 3]);
+ * // ➔ true
+ * isNonEmptyValue(NaN);
+ * // ➔ false
+ * isNonEmptyValue(true);
+ * // ➔ true
+ * isNonEmptyValue(false);
+ * // ➔ false
+ * isNonEmptyValue(null);
+ * // ➔ false
+ * isNonEmptyValue(undefined);
+ * // ➔ false
+ * isNonEmptyValue("");
+ * // ➔ false
+ * isNonEmptyValue("   ");
+ * // ➔ false
+ * isNonEmptyValue(0);
+ * // ➔ true
+ * isNonEmptyValue(-1);
+ * // ➔ true
+ * isNonEmptyValue(2);
+ * // ➔ true
+ * isNonEmptyValue(() => {});
+ * // ➔ true
+ */
+declare const isNonEmptyValue: (value: unknown, options?: IsNonEmptyValueOptions) => boolean;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isNull`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is **[`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null)**.**
+ * - **Behavior:**
+ *    - Narrows type to `null` when true.
+ *    - Strictly compares the value against `null`.
+ * @param {*} val - The value to check.
+ * @returns {boolean} Returns `true` if the value is `null`, otherwise `false`.
+ * @example
+ * isNull(null);      // ➔ true
+ * isNull(0);         // ➔ false
+ * isNull(undefined); // ➔ false
+ */
+declare const isNull: (val: unknown) => val is null;
+/** ----------------------------------------------------
+ * * ***Type guard: `isNumberObject`.***
+ * ----------------------------------------------------
+ * **Checks if a value is a **`Number` object wrapper**
+ * (`new Number(...)`), not a primitive number.**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a `Number` object.
+ * @example
+ * isNumberObject(new Number(42));
+ * // ➔ true
+ * isNumberObject(42);
+ * // ➔ false
+ */
+declare function isNumberObject(value: unknown): value is Number;
+type IsObject<T> = unknown extends T ? T & Record<PropertyKey, unknown> : T extends object ? T extends AnObjectNonArray ? T : IsHasKeysObject<T> extends false ? T & Record<PropertyKey, unknown> : IsArray<T> extends true ? Exclude<T, unknown[]> : T : never;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isObject`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is an **object** (excluding `null` and `arrays`).**
+ * - **✅ Returns `true` for any non-null object (arrays excluded), including:**
+ *    - Plain-objects (`{}`, `Object.create(null)`)
+ *    - Custom class instances
+ *    - Built-ins: `Date`, `RegExp`, `Error`, `URL`, `URLSearchParams`
+ *    - Collections: `Map`, `Set`, `WeakMap`, `WeakSet`
+ *    - Binary/typed data: `ArrayBuffer`, `DataView`, typed arrays (`Uint8Array`, `Int32Array`, etc.)
+ *    - DOM/Node objects: `HTMLElement`, `DocumentFragment`, etc.
+ *    - Proxies (wrapping any object type)
+ * - **❌ Returns `false` for:**
+ *    - `null`
+ *    - Arrays (`[]`, `new Array()`)
+ *    - Functions (regular functions, arrow functions, class constructors)
+ *    - Primitives: `string`, `number`, `boolean`, `symbol`, `bigint`
+ *    - Boxed primitives: `new String()`, `new Number()`, `new Boolean()`
+ *    - `undefined` (including `NaN`, which is a primitive number)
+ * - **ℹ️ Note:**
+ *    - If you specifically need to check for ***plain-objects*** only, use ***`isPlainObject` utility function*** instead.
+ *    - If you specifically need to check for ***object***, ***plain-objects***, and include ***array***, use ***`isObjectOrArray` utility function*** instead.
+ * @template T - The type of the value being checked.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a ***plain-objects***, otherwise `false`.
+ * @example
+ * isObject({});                  // ➔ true
+ * isObject(Object.create(null)); // ➔ true
+ * isObject(new Date());          // ➔ true
+ * isObject(new Map());           // ➔ true
+ * isObject(new Uint8Array());    // ➔ true
+ * isObject(new String("x"));     // ➔ true
+ * isObject([]);                  // ➔ false
+ * isObject(null);                // ➔ false
+ * isObject(undefined);           // ➔ false
+ * isObject(123);                 // ➔ false
+ * isObject(() => {});            // ➔ false
+ */
+declare function isObject<T extends object>(value: T): value is IsObject<T>;
+declare function isObject(value: unknown): value is Record<PropertyKey, unknown>;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isObjectLoose`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is the
+ * [ECMAScript language type ***Object***](http://www.ecma-international.org/ecma-262/7.0/#sec-ecmascript-language-types).**
+ * - **✅ Returns `true` for:**
+ *    - Plain objects (`{}`)
+ *    - Arrays (`[]`)
+ *    - Functions
+ *    - Regexes (`/abc/`)
+ *    - Boxed primitives:
+ *      - `new Number(0)`
+ *      - `new String("")`
+ *      - `new Boolean(false)`
+ * - **❌ Returns `false` for:**
+ *    - `null`
+ *    - `undefined`
+ *    - Primitives:
+ *      - `string`
+ *      - `number`
+ *      - `boolean`
+ *      - `symbol`
+ *      - `bigint`
+ * - **ℹ️ Note:**
+ *    - **For More Strict Object Use ***`isObject`*** or ***`isPlainObject` utility function*** instead.**
+ * @template T - The type of the value being checked.
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is an object, else `false`.
+ * @example
+ * isObjectLoose({});
+ * // ➔ true
+ * isObjectLoose([1, 2, 3]);
+ * // ➔ true
+ * isObjectLoose(()=> {});
+ * // ➔ true
+ * isObjectLoose(null);
+ * // ➔ false
+ * isObjectLoose(undefined);
+ * // ➔ false
+ */
+declare function isObjectLoose<T = object>(value: unknown): value is T;
+type IsObjectOrArray<T> = OrArr<[IsNever<T>, Extends<T, Record<PropertyKey, unknown>>, Extends<unknown, T>]> extends true ? T & Record<PropertyKey, unknown> & unknown[] : T extends object ? T extends unknown[] ? T : T extends AnObjectNonArray ? T : IsHasKeysObject<T> extends false ? T & Record<PropertyKey, unknown> : T : Extract<T, Record<PropertyKey, unknown> & unknown[]>;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isObjectOrArray`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is an **object** or an **array**.**
+ * - **✅ Returns `true` for:**
+ *    - Plain objects (`{}`, `Object.create(null)`)
+ *    - Custom objects
+ *    - Arrays (`[]`, `[1,2,3]`)
+ * - **❌ Returns `false` for:**
+ *    - `null`
+ *    - `undefined`
+ *    - Primitives:
+ *        - `string`
+ *        - `number`
+ *        - `boolean`
+ *        - `symbol`
+ *        - `bigint`
+ *    - Functions
+ * @template T - The type of the value being checked.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is an `object` or `array`.
+ * @example
+ * isObjectOrArray([1,2,3]);           // ➔ true
+ * isObjectOrArray({ name: "Alice" }); // ➔ true
+ * isObjectOrArray(null);              // ➔ false
+ * isObjectOrArray(undefined);         // ➔ false
+ * isObjectOrArray("hello");           // ➔ false
+ */
+declare function isObjectOrArray(value: []): value is [];
+declare function isObjectOrArray<T>(value: T): value is IsObjectOrArray<T>;
+/** ----------------------------------------------------------
+ * * ***Type guard: `PropertyKey`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a valid `PropertyKey`.**
+ * - **In JavaScript/TypeScript, a **`PropertyKey`** is any of:**
+ *    - **`string`**
+ *    - **`number`**
+ *    - **`symbol`**
+ * - **This function ensures the given `value` is one of these types.**
+ *    - Narrows type to {@link PropertyKey | ***`PropertyKey`***} when true.
+ *    - Useful for working with dynamic object keys.
+ *    - Strictly rejects `null`, `undefined`, `boolean`, `object`, `function`, etc.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if `value` is a valid property key, otherwise `false`.
+ * @example
+ * isPropertyKey("foo");
+ * // ➔ true
+ * isPropertyKey(123);
+ * // ➔ true
+ * isPropertyKey(Symbol("id"));
+ * // ➔ true
+ * isPropertyKey({});
+ * // ➔ false
+ * isPropertyKey(null);
+ * // ➔ false
+ */
+declare function isPropertyKey(value: unknown): value is PropertyKey;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isRegExp`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) instance.**
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if value is an instance of **`RegExp`**.
+ * @example
+ * isRegExp(/abc/);             // ➔ true
+ * isRegExp(new RegExp("abc")); // ➔ true
+ * isRegExp("abc");             // ➔ false
+ */
+declare const isRegExp: (value: unknown) => value is RegExp;
+/** --------------------------------------------------
+ * * ***Type guard: `isSafeInteger`.***
+ * --------------------------------------------------
+ * **Checks if `value` is a **[`Safe-Integer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger)**.**
+ * - **Behavior:**
+ *    - Narrows type to `number` when true.
+ * - **An integer is considered *safe* if:**
+ *    - It is an `IEEE-754` **double precision number**.
+ *    - It can be exactly represented without rounding errors.
+ *    - It lies within the range **-(2^53 - 1) to 2^53 - 1**.
+ * - **Note:**
+ *    - This method is based on **{@link Number.isSafeInteger | `Number.isSafeInteger`}**.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Return `true` if `value` is a safe integer, otherwise `false`.
+ * @example
+ * isSafeInteger(3);
+ * // ➔ true
+ * isSafeInteger(Number.MIN_VALUE);
+ * // ➔ false
+ * isSafeInteger(Infinity);
+ * // ➔ false
+ * isSafeInteger('3');
+ * // ➔ false
+ */
+declare function isSafeInteger(value: unknown): value is number;
+/** ---------------------------------------------------------
+ * * ***Environment Predicate: `isServer`.***
+ * ---------------------------------------------------------
+ * **Detects whether the current code is executing in a
+ * **non-browser JavaScript runtime** (server-side) rather
+ * than in a web browser.**
+ * @description
+ * It simply checks for the absence of key browser globals like
+ * [**`window`**](https://developer.mozilla.org/docs/Web/API/Window/window) and
+ * [**`document`**](https://developer.mozilla.org/docs/Web/API/Window/document).
+ *  - *If those globals aren’t present, we treat the runtime as a server environment.*
+ * @returns {boolean}
+ *  * ***true**  – Code is executing on the `server`.*
+ *  * ***false** – Code is executing in a `browser`.*
+ * @example
+ * if (isServer()) {
+ *   console.log("Running on a server-side runtime");
+ * } else {
+ *   console.log("Running in a browser");
+ * }
+ */
+declare const isServer: () => boolean;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isSet`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a **[`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/Set)** object.**
+ * - **Behavior:**
+ *    - Narrows type to `Set<T>` when true.
+ *    - Excludes `WeakSet`, arrays, plain objects, and other non-Set values.
+ * @template T - The type of the value being checked.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a `Set`, otherwise `false`.
+ * @example
+ * isSet(new Set);
+ * // ➔ true
+ * isSet(new WeakSet);
+ * // ➔ false
+ */
+declare function isSet<T = unknown>(value: Set<T>): value is Set<T>;
+declare function isSet(value: unknown): value is Set<unknown>;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isString`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is of type
+ * **[`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**.**
+ * - **Behavior:**
+ *    - Narrows type to `string` when true.
+ *    - Uses the `typeof` operator for strict checking.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a string, otherwise `false`.
+ * @example
+ * isString("hello"); // ➔ true
+ * isString(123);     // ➔ false
+ *
+ * // Usage in type narrowing
+ * const value: unknown = getValue();
+ * if (isString(value)) {
+ *   // TypeScript now knows `value` is a string
+ *   console.log(value.toUpperCase());
+ * }
+ */
+declare const isString: (value: unknown) => value is string;
+/** ----------------------------------------------------
+ * * ***Type guard: `isStringObject`.***
+ * ----------------------------------------------------
+ * **Checks if a value is a **`String` object wrapper**
+ * (`new String(...)`), not a primitive string.**
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a `String` object.
+ * @example
+ * isStringObject(new String("hello"));
+ * // ➔ true
+ * isStringObject("hello");
+ * // ➔ false
+ */
+declare function isStringObject(value: unknown): value is String;
+/** ----------------------------------------------------------
+ * * ***Type guard: `isSymbol`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is of type
+ * **[`symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/Symbol)**.**
+ * - **Behavior:**
+ *    - Narrows type to `symbol` when true.
+ *    - Uses the `typeof` operator for strict checking.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a symbol, otherwise `false`.
+ * @example
+ * isSymbol(Symbol("id"));   // ➔ true
+ * isSymbol("not a symbol"); // ➔ false
+ * isSymbol(123);            // ➔ false
+ * isSymbol(undefined);      // ➔ false
+ */
+declare const isSymbol: (value: unknown) => value is symbol;
+/** --------------------------------------------------
+ * * ***Type guard: `isTypedArray`.***
+ * ----------------------------------------------------------
+ * **Checks if `value` is classified as a
+ * **[`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)**.**
+ * - **Behavior:**
+ *    - Validates that `value` is a non-null object.
+ *    - Uses `Object.prototype.toString` tag matching against known typed array tags.
+ *    - Narrows type to **{@link TypedArray | `TypedArray`}** when true.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a typed array, otherwise `false`.
+ * @example
+ * isTypedArray(new Uint8Array);          // ➔ true
+ * isTypedArray(new Uint8Array());        // ➔ true
+ * isTypedArray(new Float32Array());      // ➔ true
+ * isTypedArray(new Uint8ClampedArray()); // ➔ true
+ * isTypedArray([]);                      // ➔ false
+ * isTypedArray(Buffer.from("hi"));       // ➔ false
+ */
+declare function isTypedArray(value: unknown): value is TypedArray;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isURL`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is an instance of the
+ * **[`URL`](https://developer.mozilla.org/docs/Web/API/URL)** class.**
+ * - **Behavior:**
+ *    - Narrows type to `URL` when true.
+ *    - Excludes `strings`, `plain-objects`, and `other non-URL values`.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is an instance of `URL`, otherwise `false`.
+ * @example
+ * isURL(new URL("https://example.com"));
+ * // ➔ true
+ * isURL("https://example.com");
+ * // ➔ false
+ */
+declare const isURL: (value: unknown) => value is URL;
+/** ---------------------------------------------------------
+ * * ***Type guard: `isUndefined`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is
+ * **[`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)**.**
+ * - **Behavior:**
+ *    - Narrows type to `undefined` when true.
+ *    - Excludes `null`, `objects`, `arrays`, `strings`, `numbers`, and
+ *      `all other values`.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is `undefined`, otherwise `false`.
+ * @example
+ * isUndefined(undefined); // ➔ true
+ * isUndefined([]);        // ➔ false
+ * isUndefined(123);       // ➔ false
+ * isUndefined(null);      // ➔ false
+ * isUndefined("abc");     // ➔ false
+ */
+declare const isUndefined: (value: unknown) => value is undefined;
+/** ---------------------------------------------------------
+ * * ***Options for `isValidDomain` predicate.***
+ * ---------------------------------------------------------
+ * **Customize the behavior of domain validation.**
+ */
+type IsValidDomainOptions = {
+  /** * ***Enable conversion of Unicode domains (IDN) to ASCII (punycode).***
+   *
+   * - Example: `"пример.рф"` ➔ `"xn--e1afmkfd.xn--p1ai"`
+   * - Allows validating Unicode domains correctly.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  allowUnicode?: boolean;
+  /** * ***If `true`, validates **only top-level domains (TLDs)** that are not part of any SLD/second-level domain.***
+   *
+   * - Accepts country-code TLDs like `"ai"` or `"ai."` ✅
+   * - Rejects common TLDs that are part of SLDs like `"com"` ❌
+   * - Only the final label is checked; subdomains are ignored.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  topLevel?: boolean;
+  /** * ***Allow or disallow subdomains.***
+   *
+   * - Example: `"sub.example.com"` ✅ if `subdomain` is `true`, ❌ if `false`
+   * - Wildcards and SLDs are considered when evaluating subdomains.
+   * - Default: `true`
+   *
+   * @defaultValue `true`.
+   */
+  subdomain?: boolean;
+  /** * ***Allow a wildcard `*` in the left-most label.***
+   *
+   * - Example: `"*.example.com"` ✅ if `wildcard` is `true`, ❌ if `false`
+   * - Wildcards are only valid in the first label and require at least one additional label.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  wildcard?: boolean;
+  /** * ***Allow a port after the domain.***
+   *
+   * - Example: `"localhost:3000"` or `"example.com:8080"` ✅ if `allowPort` is `true`
+   * - Validates that the port is a number between `1` and `65535`.
+   * - Does not affect domain validation rules otherwise.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  allowPort?: boolean;
+  /** * ***Allow special domains like `localhost`.***
+   *
+   * - Example: `"localhost"` ✅ if `allowLocalhost` is `true`
+   * - Works with or without a port if `allowPort` is enabled.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  allowLocalhost?: boolean;
+  /** * ***Allow URLs with protocol (`http`/`https`) and automatically extract the hostname.***
+   *
+   * - Example: `"https://example.com/foo/bar"` ➔ `"example.com"`
+   * - The function will validate only the hostname part and ignore the path, query, and fragment.
+   * - Default: `false`
+   *
+   * @defaultValue `false`.
+   */
+  allowProtocol?: boolean;
+};
+/** ---------------------------------------------------------
+ * * ***Predicate: `isValidDomain`.***
+ * ---------------------------------------------------------
+ * **Validates whether a given string is a properly formatted domain name.**
+ *
+ * - **Supports options for:**
+ *    - `allowUnicode` ➔ allows internationalized domain names (IDN) with Unicode characters.
+ *    - `topLevel` ➔ validates **only top-level domains (TLDs)**; ignores subdomains and SLDs.
+ *    - `subdomain` ➔ allows or disallows subdomains.
+ *    - `wildcard` ➔ allows wildcard (`*`) in the left-most label.
+ *    - `allowPort` ➔ allows a port number after the domain (e.g., `example.com:8080`).
+ *    - `allowLocalhost` ➔ allows the special domain `"localhost"`.
+ *    - `allowProtocol` ➔ allows a URL with protocol (`http`/`https`) and extracts the hostname.
+ *
+ * - **Behavior:**
+ *    - ✅ Converts Unicode to ASCII (punycode) if `allowUnicode` is `true`.
+ *    - ✅ Checks label lengths (≤63 chars), valid characters, and punycode consistency.
+ *    - ✅ Validates port if `allowPort` is `true` (must be 1–65535).
+ *    - ✅ Accepts `"localhost"` if `allowLocalhost` is `true`.
+ *    - ✅ Extracts hostname from URLs if `allowProtocol` is `true`.
+ *    - ❌ Rejects invalid domains, labels starting/ending with `-`, double dots, malformed TLDs, or invalid port numbers.
+ *    - ✅ Handles both standard domains (example.com), URLs with protocols (https://example.com/foo), and IDNs (пример.рф).
+ *
+ * @param {*} value - The value to validate; only strings are valid domains.
+ * @param {IsValidDomainOptions} [options] - Optional configuration for domain validation.
+ * @param {boolean} [options.allowUnicode=false] - Enable punycode conversion for Unicode domains.
+ * @param {boolean} [options.topLevel=false] - Validate only TLDs (e.g., `ai`, `uk.`); ignores SLDs like `com`.
+ * @param {boolean} [options.subdomain=true] - Allow subdomains; set `false` to reject any subdomain.
+ * @param {boolean} [options.wildcard=false] - Allow wildcard `*` in the left-most label (e.g., `*.example.com`).
+ * @param {boolean} [options.allowPort=false] - Allow port number after domain (e.g., `:3000`); must be 1–65535.
+ * @param {boolean} [options.allowLocalhost=false] - Allow special domain `"localhost"`.
+ * @param {boolean} [options.allowProtocol=false] - Allow URLs with protocol (`http`/`https`) and extract hostname only.
+ * @returns {boolean} Returns `true` if the value is a valid domain according to the rules and options; otherwise `false`.
+ *
+ * @example
+ * isValidDomain("google.com");
+ * // ➔ true
+ * isValidDomain("пример.рф", { allowUnicode: true });
+ * // ➔ true
+ * isValidDomain("sub.example.com", { subdomain: false });
+ * // ➔ false
+ * isValidDomain("*.example.com", { wildcard: true });
+ * // ➔ true
+ * isValidDomain("com", { topLevel: true });
+ * // ➔ false (common TLD rejected because it's part of SLD)
+ * isValidDomain("ai.", { topLevel: true });
+ * // ➔ true (country-code TLD accepted)
+ * isValidDomain("localhost", { allowLocalhost: true });
+ * // ➔ true
+ * isValidDomain("localhost:3000", { allowLocalhost: true, allowPort: true });
+ * // ➔ true
+ * isValidDomain("example.com:8080", { allowPort: true });
+ * // ➔ true
+ * isValidDomain("https://example.com/foo/bar", { allowProtocol: true });
+ * // ➔ true (protocol stripped and hostname validated)
+ * isValidDomain("invalid_domain.com");
+ * // ➔ false
+ */
+declare function isValidDomain(value: unknown, options?: IsValidDomainOptions): boolean;
+/** ---------------------------------------------------------
+ * * ***Predicate: `isValidURL`.***
+ * ---------------------------------------------------------
+ * **Validates whether a given string is a properly formatted URL.**
+ * - **Ensures that the input is:**
+ *    - A non-empty string.
+ *    - A valid **[`URL`](https://developer.mozilla.org/docs/Web/API/URL)** with `http://` or `https://` scheme.
+ * - **Behavior:**
+ *    - ✅ Includes decoding for percent-encoded URLs (e.g., `https%3A%2F%2F...`).
+ *    - ❌ Rejects invalid strings, unsupported schemes, and malformed domains.
+ * @param {*} url - The value to validate.
+ * @returns {boolean} Return `true` if the value is a **valid URL string**, otherwise `false`.
+ * @example
+ * isValidURL("https://example.com");
+ * // ➔ true
+ * isValidURL("ftp://example.com");
+ * // ➔ false
+ * isValidURL("not-a-url");
+ * // ➔ false
+ */
+declare const isValidURL: (url: unknown) => boolean;
+/** --------------------------------------------------
+ * * ***Type guard: `isWeakMap`.***
+ * ----------------------------------------------------------
+ * **Checks if a value is a **[`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/WeakMap)** object.**
+ * - **Behavior:**
+ *    - Narrows type to `WeakMap<K, V>` when true.
+ *    - Excludes `Map`, `arrays`, `plain-objects,` and `other non-WeakMap values`.
+ * @template K - Keys must be objects.
+ * @template V - Type of values stored in the WeakMap.
+ * @param {*} value - The value to check.
+ * @returns {boolean} Returns `true` if the value is a `WeakMap`, otherwise `false`.
+ * @example
+ * isWeakMap(new WeakMap);
+ * // ➔ true
+ * isWeakMap(new Map);
+ * // ➔ false
+ */
+declare function isWeakMap<K extends object = object, V = unknown>(value: unknown): value is WeakMap<K, V>;
+export { isArrayBuffer as $, isInteger as A, isEmptyDeep as B, isNil as C, isMatch as D, isMatchWith as E, isEqualWith as F, isDate as G, isEmpty as H, isEqual as I, isBooleanObject as J, isCurrencyLike as K, isEmptyValue as L, isFunction as M, isFinite as N, isMap as O, isError as P, isArrayLike as Q, isEmptyString as R, isNonEmptyArray as S, isNaN as T, isElement as U, isEmptyArray as V, isDeepEqual as W, isBigInt as X, isBoolean as Y, isArrayLikeObject as Z, isObject as _, isURL as a, textContainsAny as at, isNonEmptyValue as b, isStringObject as c, areURLsEqualPath as ct, isServer as d, isArray as et, isSafeInteger as f, isObjectLoose as g, isObjectOrArray as h, isUndefined as i, doesKeyExist as it, isInfinityNumber as j, isLength as k, isString as l, areObjectsEqual as lt, isPropertyKey as m, isValidURL as n, hasOwnProp as nt, isTypedArray as o, textContainsAll as ot, isRegExp as p, isBuffer as q, isValidDomain as r, arrayHasAnyMatch as rt, isSymbol as s, areURLsIdentical as st, isWeakMap as t, isArguments as tt, isSet as u, areArraysEqual as ut, isNumberObject as v, isNative as w, isNonEmptyString as x, isNull as y, isEmptyObject as z };