@rzl-zone/utils-js 3.13.1-beta.0 → 3.14.0-beta.0

package/dist/index-DZHiYYR7.d.ts

@@ -0,0 +1,2179 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.14.0-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+/*!
+* ========================================================================
+*  @rzl-zone/ts-types-plus
+* ------------------------------------------------------------------------
+*  Version: `0.1.8-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/ts-types-plus`
+* ========================================================================
+*/
+/** -------------------------------------------------------
+ * * ***Utility Type: `If`.***
+ * -------------------------------------------------------
+ * - **Conditional:**
+ *      - Returns the second argument if the first argument is `true`, otherwise
+ *        returns the third argument.
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template Condition - The boolean condition to check.
+ * @template IfTrue - The branch type if condition is `true`. (default: `true`).
+ * @template IfFalse - The branch type if condition is `false`. (default: `false`).
+ * @example
+ * ```ts
+ * type A = If<true, "valid">;
+ * // ➔ "valid"
+ * type B = If<false, "valid", "invalid">;
+ * // ➔ "invalid"
+ * ```
+ */
+type If<Condition, IfTrue = true, IfFalse = false> = Condition extends true ? IfTrue : IfFalse;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsNever`.***
+ * -------------------------------------------------------
+ * ****Conditional**: returns `true` if `T` is `never`, otherwise `false`.**
+ * @template T - Type to check.
+ * @example
+ * ```ts
+ * type A = IsNever<never>; // ➔ true
+ * type B = IsNever<true>;  // ➔ false
+ * ```
+ */
+type IsNever<T> = [T] extends [never] ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfNever`.***
+ * -------------------------------------------------------
+ * **Conditional**: Selects one of two branches depending on whether `T` is `never`.**
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template T - Type to check.
+ * @template IfTrue - The branch type if `T` is `never`, (default: `true`).
+ * @template IfFalse - The branch type if `T` is not `never`, (default: `false`).
+ * @example
+ * ```ts
+ * type A = IfNever<never>;
+ * // ➔ true
+ * type B = IfNever<string>;
+ * // ➔ false
+ * type C = IfNever<never, 'valid', 'no'>;
+ * // ➔ 'valid'
+ * type D = IfNever<string, 'valid', 'no'>;
+ * // ➔ 'no'
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `EmptyArray`.***
+ * -------------------------------------------------------
+ * **A type-level utility that returns `T` if it is an ***empty array***,
+ * otherwise returns `never`.**
+ * @template T - The array type to check.
+ * @example
+ * ```ts
+ * type A = EmptyArray<[]>;
+ * // ➔ []
+ * type B = EmptyArray<[1]>;
+ * // ➔ never
+ * type C = EmptyArray<string[]>;
+ * // ➔ string[]
+ * type D = EmptyArray<number[]>;
+ * // ➔ number[]
+ * type E = EmptyArray<readonly []>;
+ * // ➔ readonly []
+ * ```
+ */
+type EmptyArray<T extends readonly unknown[]> = T extends readonly [unknown, ...unknown[]] ? never : T;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NonEmptyArray`.***
+ * -------------------------------------------------------
+ * **A type-level utility that returns `T` if it is a ***non-empty array***,
+ * otherwise returns `never`.**
+ * @template T - The array type to check.
+ * @example
+ * ```ts
+ * type A = NonEmptyArray<[]>;
+ * // ➔ never
+ * type B = NonEmptyArray<[1]>;
+ * // ➔ [1]
+ * type C = NonEmptyArray<string[]>;
+ * // ➔ never
+ * type D = NonEmptyArray<number[]>;
+ * // ➔ never
+ * type E = NonEmptyArray<readonly []>;
+ * // ➔ never
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsNonEmptyArray`.***
+ * -------------------------------------------------------
+ * **A type-level utility that evaluates to `true` if `T` is a ***non-empty array.***
+ * (strictly a non-empty tuple), otherwise `false`.**
+ * @template T - The array type to check.
+ * @example
+ * ```ts
+ * type A = IsNonEmptyArray<[]>;
+ * // ➔ false
+ * type B = IsNonEmptyArray<[1]>;
+ * // ➔ true
+ * type C = IsNonEmptyArray<string[]>;
+ * // ➔ false
+ * type D = IsNonEmptyArray<number[]>;
+ * // ➔ false
+ * type E = IsNonEmptyArray<readonly []>;
+ * // ➔ false
+ * ```
+ */
+type IsNonEmptyArray<T extends readonly unknown[]> = If<IsNever<EmptyArray<T>>, true, false>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfEmptyArray`.***
+ * -------------------------------------------------------
+ * **Returns the second argument if `T` is an ***empty array*** (per this utility),
+ * otherwise returns the third argument.**
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template T - The array type to check.
+ * @template IfTrue - Returned type if `T` is empty by this definition.
+ * @template IfFalse - Returned type if `T` is not empty by this definition.
+ * @example
+ * ```ts
+ * type A = IfEmptyArray<[]>;
+ * // ➔ true
+ * type B = IfEmptyArray<[1]>;
+ * // ➔ false
+ * type C = IfEmptyArray<string[]>;
+ * // ➔ true
+ * type D = IfEmptyArray<readonly []>;
+ * // ➔ true
+ * type E = IfEmptyArray<[], "yes", "no">;
+ * // ➔ "yes"
+ * type F = IfEmptyArray<[1], "yes", "no">;
+ * // ➔ "no"
+ * type G = IfEmptyArray<string[], "yes", "no">;
+ * // ➔ "yes"
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfNonEmptyArray`.***
+ * -------------------------------------------------------
+ * **Returns the second argument if `T` is a ***non-empty array*** (strict tuple),
+ * otherwise returns the third argument.**
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template T - The array type to check.
+ * @template IfTrue - Returned type if `T` is non-empty by this definition.
+ * @template IfFalse - Returned type if `T` is not non-empty by this definition.
+ * @example
+ * ```ts
+ * type A = IfNonEmptyArray<[]>;
+ * // ➔ false
+ * type B = IfNonEmptyArray<[1]>;
+ * // ➔ true
+ * type C = IfNonEmptyArray<string[]>;
+ * // ➔ false
+ * type D = IfNonEmptyArray<readonly []>;
+ * // ➔ false
+ * type E = IfNonEmptyArray<[1], "yes", "no">;
+ * // ➔ "yes"
+ * type F = IfNonEmptyArray<[], "yes", "no">;
+ * // ➔ "no"
+ * type G = IfNonEmptyArray<string[], "yes", "no">;
+ * // ➔ "no"
+ * ```
+ */
+type IfNonEmptyArray<T extends readonly unknown[], IfTrue = true, IfFalse = false> = If<IsNonEmptyArray<T>, IfTrue, IfFalse>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Not`.***
+ * -------------------------------------------------------
+ * **Accepts a boolean type `T` and returns its negation.**
+ * @template T - Boolean type to negate.
+ * @example
+ * ```ts
+ * type A = Not<true>;  // ➔ false
+ * type B = Not<false>; // ➔ true
+ * ```
+ */
+type Not<T extends boolean> = T extends true ? false : true;
+/** ---------------------------------------------------------------------------
+ * * ***Options for {@link Pop|`Pop`}.***
+ * ---------------------------------------------------------------------------
+ * **Configuration options for the {@link Pop | **`Pop`**} type utility.**
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `Extends`.***
+ * -------------------------------------------------------
+ * **Returns a boolean indicating whether the first argument ***extends*** the second argument.**
+ * @template T - The type to check.
+ * @template Base - The type to compare against.
+ * @example
+ * ```ts
+ * type A = Extends<1, number>;  // ➔ true
+ * type B = Extends<number, 1>;  // ➔ false
+ * ```
+ */
+type Extends<T, Base> = [T] extends [Base] ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NotExtends`.***
+ * -------------------------------------------------------
+ * **Returns a boolean indicating whether the first argument does ***not extend*** the second argument.**
+ * @template T - The type to check.
+ * @template Base - The type to compare against.
+ * @example
+ * ```ts
+ * type A = NotExtends<1, number>; // ➔ false
+ * type B = NotExtends<number, 1>; // ➔ true
+ * ```
+ */
+type NotExtends<T, Base> = Not<Extends<T, Base>>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfExtends`.***
+ * -------------------------------------------------------
+ * - **Conditional:**
+ *      - Returns the third argument if the first argument ***extends*** the second
+ *        argument, otherwise returns the fourth argument.
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template T - The type to check.
+ * @template Base - The type to compare against.
+ * @template IfTrue - The branch type if condition is met, (default: `true`).
+ * @template IfFalse - The branch type if condition is not met, (default: `false`).
+ * @example
+ * ```ts
+ * type A = IfExtends<1, number, "valid">;
+ * // ➔ "valid"
+ * type B = IfExtends<1, string, "valid", "invalid">;
+ * // ➔ "invalid"
+ * ```
+ */
+type IfExtends<T, Base, IfTrue = true, IfFalse = false> = If<Extends<T, Base>, IfTrue, IfFalse>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfNotExtends`.***
+ * -------------------------------------------------------
+ * - **Conditional:**
+ *      - Returns the third argument if the first argument does ***not extend*** the
+ *        second argument, otherwise returns the fourth argument.
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template T - The type to check.
+ * @template Base - The type to compare against.
+ * @template IfTrue - The branch type if condition is met, (default: `true`).
+ * @template IfFalse - The branch type if condition is not met, (default: `false`).
+ * @example
+ * ```ts
+ * type A = IfNotExtends<1, string, "valid">;
+ * // ➔ "valid"
+ * type B = IfNotExtends<1, number, "valid", "invalid">;
+ * // ➔ "invalid"
+ * ```
+ */
+type IfNotExtends<T, Base, IfTrue = true, IfFalse = false> = If<NotExtends<T, Base>, IfTrue, IfFalse>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `ExtendsArr`.***
+ * -------------------------------------------------------
+ * **Returns a boolean indicating whether every element of the first array argument ***extends*** the second argument.**
+ * @template T - The array to check.
+ * @template Base - The type to compare each element against.
+ * @example
+ * ```ts
+ * type A = ExtendsArr<[1, 2, 3], number>;
+ * // ➔ true
+ * type B = ExtendsArr<[1, "2", 3], number>;
+ * // ➔ false
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `And`.***
+ * -------------------------------------------------------
+ * **Performs a **logical AND** operation between two boolean types.**
+ * - **Behavior:**
+ *      - Returns `true` if **both** conditions extend `true`.
+ *      - Returns `false` for otherwise.
+ * @template Condition1 - The first condition.
+ * @template Condition2 - The second condition.
+ * @example
+ * ```ts
+ * type Case1 = And<true, true>;
+ * // ➔ true
+ * type Case2 = And<false, true>;
+ * // ➔ false
+ * type Case3 = And<true, false>;
+ * // ➔ false
+ * type Case4 = And<false, false>;
+ * // ➔ false
+ * ```
+ */
+type And<Condition1, Condition2> = IfExtends<Condition1, true, Extends<Condition2, true>>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `AndArr`.***
+ * -------------------------------------------------------
+ * **Performs a **logical AND** operation across all elements in an array of
+ * boolean types.**
+ * - **Behavior:**
+ *      - Returns `true` if **all elements** extend `true`.
+ *      - Returns `false` if **any element** is not `true`.
+ * @template Conditions - A readonly array of boolean conditions.
+ * @example
+ * ```ts
+ * type Case1 = AndArr<[true, true, true]>;
+ * // ➔ true
+ * type Case2 = AndArr<[true, true, false]>;
+ * // ➔ false
+ * type Case3 = AndArr<[false, false, false]>;
+ * // ➔ false
+ * type Case4 = AndArr<[]>;
+ * // ➔ false
+ * ```
+ */
+type AndArr<Conditions extends readonly unknown[]> = Extends<[], Conditions> extends true ? false : Extends<Conditions[number], true>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsStringLiteral`.***
+ * -------------------------------------------------------
+ * **Returns a boolean whether the passed argument is literal string.**
+ * @template T - The type value to check.
+ * @example
+ * type Case1 = IsStringLiteral<'a'>;    // ➔ true
+ * type Case2 = IsStringLiteral<1>;      // ➔ false
+ * type Case3 = IsStringLiteral<string>; // ➔ false
+ */
+type IsStringLiteral<T> = If<Extends<T, string>, Extends<string, T> extends true ? false : true>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfNot`.***
+ * -------------------------------------------------------
+ * - **Conditional:**
+ *      - Returns the second argument if the first argument is `false`, otherwise returns the third argument.
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ * @template Condition - The boolean condition to check.
+ * @template IfTrue - The branch type if condition is `false`. (default: `true`).
+ * @template IfFalse - The branch type if condition is `true`. (default: `false`).
+ * @example
+ * ```ts
+ * type A = IfNot<false, "valid">;
+ * // ➔ "valid"
+ * type B = IfNot<false, "valid", "invalid">;
+ * // ➔ "invalid"
+ * ```
+ */
+type IfNot<Condition, IfTrue = true, IfFalse = false> = If<Condition, IfFalse, IfTrue>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `WordSeparator`.***
+ * -------------------------------------------------------
+ * **A type-level utility that defines all valid ***word separators***.**
+ * - Can be a space `" "`, a dash `"-"`, or an underscore `"_"`.
+ * @example
+ * type A = WordSeparator; // ➔ " " | "-" | "_"
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `Whitespace`.***
+ * --------------------------------------------------
+ * **Represents common whitespace characters.**
+ * - ✅ Used as the default trimming characters in string utility types.
+ * @example
+ * type W = Whitespace; // ➔ " " | "\t" | "\r" | "\n"
+ */
+type Whitespace = " " | "\t" | "\r" | "\n";
+/**
+ * **Helper Type Internal.**
+ */
+type SafeKeyTrimming<T> = Exclude<T, symbol>;
+/** --------------------------------------------------
+ * * ***Utility Type: `TrimLeft`.***
+ * --------------------------------------------------
+ * **Recursively trims specified characters (default: **{@link Whitespace | `Whitespace`}**) from the **start (left)** of a string.**
+ * @template Text - The string to trim.
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ * @example
+ * type T1 = TrimLeft<"\n  hello", " " | "\n">;
+ * // ➔ "hello"
+ * type T2 = TrimLeft<"  world">;
+ * // ➔ "world"
+ * type T3 = TrimLeft<"  world ">;
+ * // ➔ "world "
+ */
+type TrimLeft<Text extends PropertyKey, Chars extends PropertyKey = Whitespace> = Text extends `${SafeKeyTrimming<Chars>}${infer Rest}` ? TrimLeft<Rest, Chars> : Text;
+/** --------------------------------------------------
+ * * ***Utility Type: `TrimRight`.***
+ * --------------------------------------------------
+ * **Recursively trims specified characters (default: **{@link Whitespace | `Whitespace`}**) from the **end (right)** of a string.**
+ * @template Text - The string to trim.
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ * @example
+ * type T1 = TrimRight<"hello  \t", " " | "\t">;
+ * // ➔ "hello"
+ * type T2 = TrimRight<"world  ">;
+ * // ➔ "world"
+ * type T2 = TrimRight<" world  ">;
+ * // ➔ " world"
+ */
+type TrimRight<Text extends PropertyKey, Chars extends PropertyKey = Whitespace> = Text extends `${infer Rest}${SafeKeyTrimming<Chars>}` ? TrimRight<Rest, Chars> : Text;
+/** --------------------------------------------------
+ * * ***Utility Type: `Trim`.***
+ * --------------------------------------------------
+ * **Trims specified characters (default: **{@link Whitespace | `Whitespace`}**)
+ * from **both the start and end** of a string.**
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ * @example
+ * type T1 = Trim<"  hello  ", " ">;
+ * // ➔ "hello"
+ * type T2 = Trim<"\n  world \t">;
+ * // ➔ "world"
+ */
+type Trim<Text extends PropertyKey, Chars extends PropertyKey = Whitespace> = TrimRight<TrimLeft<Text, Chars>, Chars>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `TrimsLower`.***
+ * -------------------------------------------------------
+ * **Trims leading & trailing whitespace from a string and
+ * converts it to **lowercase**.**
+ * @description
+ * Utilizes **{@link Trim | `Trim`}** to remove whitespace and
+ * **{@link Lowercase | `Lowercase`}** to convert the string to lowercase.
+ * @template S - The input string to transform.
+ * @example
+ * ```ts
+ * type T1 = TrimsLower<"  HeLLo \n">;
+ * // ➔ "hello"
+ * type T2 = TrimsLower<"  WoRLD  ">;
+ * // ➔ "world"
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `AnyString`.***
+ * -------------------------------------------------------
+ * **A utility type that represents **any string value** while
+ * preventing unwanted widening of string literals to `string`.**
+ * @description
+ * This is achieved by intersecting `string` with `{}`,
+ * ensuring that the type remains assignable to `string`
+ * but is treated as a unique type in generic constraints.
+ * - **Useful in scenarios where:**
+ *      - You want to accept **any string**, but still preserve
+ *        literal types in inference.
+ *      - You need stricter typing than just `string`.
+ * @example
+ * ```ts
+ * declare function acceptsAnyString<T extends AnyString>(value: T): T;
+ *
+ * // Preserves literal
+ * const a = acceptsAnyString("hello");
+ * // ➔ "hello"
+ *
+ * // Also allows generic string
+ * const b = acceptsAnyString(String("world"));
+ * // ➔ string
+ * ```
+ */
+type AnyString = {} & string;
+/** -------------------------------------------------------
+ * * ***Utility Type: `EmptyString`.***
+ * -------------------------------------------------------
+ * - **Conditional type:**
+ *      - Returns the type `T` only if it is the empty string `""`.
+ *      - Optionally trims whitespace before checking.
+ * - **Behavior:**
+ *      - If `WithTrim` is `true` (default), trims `T` before checking.
+ *      - If `T` is the general `string` type, returns `never`.
+ *      - If `T` is empty (after optional trimming), returns `T` or `Trim<T>`.
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ * @example
+ * ```ts
+ * // Basic empty string
+ * type Case1 = EmptyString<"">;
+ * // ➔ ""
+ *
+ * // Non-empty string
+ * type Case2 = EmptyString<"abc">;
+ * // ➔ never
+ *
+ * // General string type
+ * type Case3 = EmptyString<string>;
+ * // ➔ never
+ *
+ * // With leading/trailing whitespace
+ * type Case4 = EmptyString<"  ", true>;
+ * // ➔ "" (trimmed)
+ * type Case5 = EmptyString<"  ", false>;
+ * // ➔ never (not trimmed)
+ * ```
+ */
+type EmptyString<T extends string, WithTrim extends boolean = true> = "" extends (WithTrim extends true ? Trim<T> : T) ? string extends (WithTrim extends true ? Trim<T> : T) ? never : WithTrim extends true ? Trim<T> : T : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NonEmptyString`.***
+ * -------------------------------------------------------
+ * - **Conditional type:**
+ *      - Returns the type `T` only if it is a non-empty string.
+ *      - Optionally trims whitespace before checking.
+ * - **Behavior:**
+ *      - If `WithTrim` is `true` (default), trims `T` before checking.
+ *      - If `T` is the general `string` type, returns `string`.
+ *      - If `T` is empty (after optional trimming), returns `never`.
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ * @example
+ * ```ts
+ * // Non-empty string
+ * type Case1 = NonEmptyString<"abc">; // ➔ "abc"
+ *
+ * // Empty string
+ * type Case2 = NonEmptyString<"">; // ➔ never
+ *
+ * // General string type
+ * type Case3 = NonEmptyString<string>; // ➔ string
+ *
+ * // String with whitespace
+ * type Case4 = NonEmptyString<"  ", true>; // ➔ never (trimmed to empty)
+ * type Case5 = NonEmptyString<"  ", false>; // ➔ "  " (not trimmed)
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsEmptyString`.***
+ * -------------------------------------------------------
+ * - **Conditional type:**
+ *      - Returns `true` if `T` is exactly the empty string `""`.
+ *      - Optionally trims whitespace before checking.
+ * - **Behavior:**
+ *      - If `WithTrim` is `true` (default), trims `T` before checking.
+ *      - If `T` is empty after optional trimming, returns `true`.
+ *      - Otherwise, returns `false`.
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ * @example
+ * ```ts
+ * type Case1 = IsEmptyString<"">;
+ * // ➔ true
+ * type Case2 = IsEmptyString<"abc">;
+ * // ➔ false
+ * type Case3 = IsEmptyString<"  ", true>;
+ * // ➔ true (trimmed)
+ * type Case4 = IsEmptyString<"  ", false>;
+ * // ➔ false (not trimmed)
+ * ```
+ */
+type IsEmptyString<T extends string, WithTrim extends boolean = true> = IfNot<IsNever<EmptyString<T, WithTrim>>>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsNonEmptyString`.***
+ * -------------------------------------------------------
+ * - **Conditional type:**
+ *      - Returns `true` if `T` is a non-empty string.
+ *      - Optionally trims whitespace before checking.
+ * - **Behavior:**
+ *      - If `WithTrim` is `true` (default), trims `T` before checking.
+ *      - Returns `true` if `T` is non-empty after optional trimming.
+ *      - Returns `false` if `T` is empty (after trimming if `WithTrim=true`).
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ * @example
+ * ```ts
+ * type Case1 = IsNonEmptyString<"abc">;
+ * // ➔ true
+ * type Case2 = IsNonEmptyString<"">;
+ * // ➔ false
+ * type Case3 = IsNonEmptyString<"  ", true>;
+ * // ➔ false (trimmed)
+ * type Case4 = IsNonEmptyString<"  ", false>;
+ * // ➔ true (not trimmed)
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsAny`.***
+ * -------------------------------------------------------
+ * **A type-level utility that checks whether a type is ***`any`***.**
+ * - **Behavior:**
+ *      - Returns `true` if `T` is `any`.
+ *      - Returns `false` for otherwise.
+ * @template T - The type to evaluate.
+ * @example
+ * ```ts
+ * type A = IsAny<any>;     // ➔ true
+ * type B = IsAny<string>;  // ➔ false
+ * type C = IsAny<unknown>; // ➔ false
+ * type D = IsAny<never>;   // ➔ false
+ * ```
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IfAny`.***
+ * -------------------------------------------------------
+ * **A type-level conditional utility that returns one type if ***`T` is `any`***,
+ * and another type otherwise.**
+ * - **Behavior:**
+ *      - Defaults to `true` when `T` is `any`.
+ *      - Defaults to `false` for otherwise.
+ * @template T - The type to check.
+ * @template IfTrue - The type to return if `T` is `any`, *(default: `true`)*.
+ * @template IfFalse - The type to return if `T` is not `any`, *(default: `false`)*.
+ * @example
+ * ```ts
+ * type A = IfAny<any, string, number>;
+ * // ➔ string
+ * type B = IfAny<string, string, number>;
+ * // ➔ number
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `AnyFunction`.***
+ * --------------------------------------------------
+ * **A generic type representing **any function** with
+ * any arguments and any return type.**
+ * @example
+ * const fn: AnyFunction = (a, b) => a + b;
+ * console.log(fn(1, 2)); // ➔ 3
+ *
+ * const fn2: AnyFunction = (x, y, z) => x + y - z;
+ * console.log(fn2(10, 20, 5)); // ➔ 25
+ */
+type AnyFunction = (...args: any[]) => any;
+/** --------------------------------------------------
+ * * ***Utility Type: `ArgumentTypes`.***
+ * --------------------------------------------------
+ * **Extracts the **argument types** of a given function type `F`.**
+ * - ✅ Useful when you need to infer or reuse the parameter types
+ *    from an existing function signature.
+ * @template F - A function type from which to extract argument types.
+ * @example
+ * ```ts
+ * type Args = ArgumentTypes<(a: number, b: string) => void>;
+ * // ➔ [number, string]
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `FixNeverArrayRecursive`.***
+ * -------------------------------------------------------
+ * **A type-level utility that **recursively transforms arrays of type `never[]` into empty arrays**.**
+ * - **Behavior:**
+ *      - Preserves `readonly` modifiers.
+ *      - Applies recursively for nested arrays.
+ *      - Leaves other types unchanged.
+ * @template T - The input type to recursively fix.
+ * @example
+ * ```ts
+ * type A = FixNeverArrayRecursive<never[]>;
+ * // ➔ []
+ * type B = FixNeverArrayRecursive<readonly never[]>;
+ * // ➔ readonly []
+ * type C = FixNeverArrayRecursive<string[]>;
+ * // ➔ string[]
+ * type D = FixNeverArrayRecursive<(never | string)[]>;
+ * // ➔ (never | string)[]
+ * type E = FixNeverArrayRecursive<(never[])[]>;
+ * // ➔ [][]
+ * ```
+ */
+type FixNeverArrayRecursive<T> = T extends readonly never[] ? T extends never[] ? [] : readonly [] : T extends (infer U)[] ? FixNeverArrayRecursive<U>[] : T extends readonly (infer U)[] ? readonly FixNeverArrayRecursive<U>[] : T;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NormalizeEmptyArraysRecursive`.***
+ * -------------------------------------------------------
+ * **A type-level utility that **recursively normalizes empty array types** by converting arrays whose element type is `never`, `null`, or `undefined` into empty tuple types (`[]`).**
+ * - **Behavior:**
+ *      - Preserves `readonly` modifiers.
+ *      - Recurses into nested arrays.
+ *      - Leaves other array types unchanged.
+ * @template T - The input type to normalize.
+ * @example
+ * ```ts
+ * type A = NormalizeEmptyArraysRecursive<never[]>;
+ * // ➔ []
+ * type B = NormalizeEmptyArraysRecursive<readonly never[]>;
+ * // ➔ readonly []
+ * type C = NormalizeEmptyArraysRecursive<null[]>;
+ * // ➔ []
+ * type D = NormalizeEmptyArraysRecursive<(null[] | string[])[]>;
+ * // ➔ ([] | string[])[]
+ * type E = NormalizeEmptyArraysRecursive<string[]>;
+ * // ➔ string[]
+ * ```
+ */
+type NormalizeEmptyArraysRecursive<T> = T extends readonly (infer U)[] ? U extends never | null | undefined ? T extends readonly unknown[] ? T extends (infer _E)[] ? [] : readonly [] : never : T extends (infer _E)[] ? NormalizeEmptyArraysRecursive<U>[] : readonly NormalizeEmptyArraysRecursive<U>[] : T;
+/** -------------------------------------------------------
+ * * ***Utility Type: `RemoveEmptyArrayElements`.***
+ * -------------------------------------------------------
+ * **A type-level utility that **recursively removes empty array elements (`[]`) from a tuple type**.**
+ * - **Behavior:**
+ *      - If `T` is a tuple, checks the first element:
+ *          - If `Head` is an empty array type (`[]`), it is removed.
+ *          - Otherwise, `Head` is preserved.
+ *      - Repeats recursively on the rest of the tuple.
+ *      - Leaves non-tuple types unchanged.
+ * @template T - The tuple type to process.
+ * @example
+ * ```ts
+ * type A = RemoveEmptyArrayElements<[[], 1, [], 2]>;
+ * // ➔ [1, 2]
+ * type B = RemoveEmptyArrayElements<[]>;
+ * // ➔ []
+ * type C = RemoveEmptyArrayElements<[[], [], []]>;
+ * // ➔ []
+ * type D = RemoveEmptyArrayElements<[1, 2, 3]>;
+ * // ➔ [1, 2, 3]
+ * ```
+ */
+type RemoveEmptyArrayElements<T> = T extends [infer Head, ...infer Tail] ? Head extends [] ? RemoveEmptyArrayElements<Tail> : [Head, ...RemoveEmptyArrayElements<Tail>] : T extends [] ? [] : T;
+/** ---------------------------------------------------------------------------
+ * * ***Type Options for {@link LastCharacter | `LastCharacter`}.***
+ * ---------------------------------------------------------------------------
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `OrArr`.***
+ * -------------------------------------------------------
+ * **Computes the logical OR of all elements inside a tuple or array of boolean types.**
+ * @template Conditions - An array of boolean type elements.
+ * @example
+ * ```ts
+ * type Case1 = OrArr<[true, true, true]>;    // ➔ true
+ * type Case2 = OrArr<[true, true, false]>;   // ➔ true
+ * type Case3 = OrArr<[false, false, false]>; // ➔ false
+ * type Case4 = OrArr<[]>;                    // ➔ false
+ * ```
+ * @remarks
+ * - Uses TypeScript's indexed access types and conditional type inference.
+ * - Returns `true` if at least one element in the array is `true`.
+ * - Returns `false` if all elements are `false` or array is empty.
+ */
+type OrArr<Conditions extends readonly unknown[]> = true extends Conditions[number] ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Push`.***
+ * -------------------------------------------------------
+ * **Appends a type `U` to the end of a tuple or readonly array type `T`.**
+ * @template T - The tuple or readonly array type to append U.
+ * @template U - The type of the element to push.
+ * @example
+ * ```ts
+ * type Case1 = Push<[1, 2, 3, 4], 5>;
+ * // ➔ [1, 2, 3, 4, 5]
+ *
+ * type Case2 = Push<["a", "b"], "c">;
+ * // ➔ ["a", "b", "c"]
+ * ```
+ */
+type Push<T extends readonly unknown[], U> = [...T, U];
+type _Repeat<T extends string, Count extends number, Result extends string = "", Iteration extends unknown[] = []> = Iteration["length"] extends Count ? Result : _Repeat<T, Count, `${T}${Result}`, Push<Iteration, unknown>>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Repeat`.***
+ * -------------------------------------------------------
+ * **Repeats a string literal type `T` a specified number of times `Count`.**
+ * - **Behavior:**
+ *      - Supports a range of `[0, 999]` due to TypeScript recursion limits.
+ *      - If `Count > 999`, it is automatically to `any` because error `Type instantiation is excessively deep and possibly infinite.ts(2589)`.
+ * @template T - The string literal to repeat.
+ * @template Count - Number of times to repeat.
+ * @example
+ * ```ts
+ * type Case0 = Repeat<'x', 0>;  // ➔ ''
+ * type Case1 = Repeat<'x', 1>;  // ➔ 'x'
+ * type Case2 = Repeat<'x', 5>;  // ➔ 'xxxxx'
+ * type Case3 = Repeat<'ab', 3>; // ➔ 'ababab'
+ *
+ * // ❌ Invalid:
+ * type Case1000 = Repeat<'x', 1000>;
+ * // ➔ same as any (because: TypeScript recursion limits)
+ * ```
+ */
+type Repeat<T extends string, Count extends number> = _Repeat<T, Count>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `OddDigit`.***
+ * -------------------------------------------------------
+ * **A union of string literal digits considered ***odd***.**
+ * - Includes: `"1" | "3" | "5" | "7" | "9"`.
+ * @example
+ * ```ts
+ * type A = OddDigit; // ➔ "1" | "3" | "5" | "7" | "9"
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `Negative`.***
+ * -------------------------------------------------------
+ * **Extracts `T` if it is ***negative***, otherwise `never`.**
+ * @template T - A number type to check.
+ * @example
+ * ```ts
+ * type A = Negative<-10>; // ➔ -10
+ * type B = Negative<5>;   // ➔ never
+ * type C = Negative<0>;   // ➔ never
+ * ```
+ */
+type Negative<T extends number> = `${T}` extends `-${string}` ? T : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Positive`.***
+ * -------------------------------------------------------
+ * **Extracts `T` if it is ***positive*** (or zero), otherwise `never`.**
+ * @template T - A number type to check.
+ * @example
+ * ```ts
+ * type A = Positive<10>; // ➔ 10
+ * type B = Positive<0>;  // ➔ 0
+ * type C = Positive<-5>; // ➔ never
+ * ```
+ */
+type Positive<T extends number> = If<IsNever<Negative<T>>, T, never>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `PositiveInteger`.***
+ * -------------------------------------------------------
+ * **Restricts `T` to ***positive integers*** only.**
+ * @template T - A number type.
+ * @example
+ * ```ts
+ * type A = PositiveInteger<42>;   // ➔ 42
+ * type B = PositiveInteger<0>;    // ➔ 0
+ * type C = PositiveInteger<-5>;   // ➔ never
+ * type D = PositiveInteger<3.14>; // ➔ never
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsPositive`.***
+ * -------------------------------------------------------
+ * **Whether `T` is ***positive***.**
+ * @example
+ * ```ts
+ * type A = IsPositive<10>;   // ➔ true
+ * type B = IsPositive<0>;    // ➔ true
+ * type C = IsPositive<-5>;   // ➔ false
+ * type D = IsPositive<3.5>;  // ➔ true
+ * type E = IsPositive<-3.5>; // ➔ false
+ * ```
+ */
+type IsPositive<T extends number> = Not<IsNever<Positive<T>>>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsNegative`.***
+ * -------------------------------------------------------
+ * **Whether `T` is ***negative***.**
+ * @example
+ * ```ts
+ * type A = IsNegative<-10>;  // ➔ true
+ * type B = IsNegative<5>;    // ➔ false
+ * type C = IsNegative<0>;    // ➔ false
+ * type D = IsPositive<3.5>;  // ➔ false
+ * type E = IsPositive<-3.5>; // ➔ true
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `ParseNumber`.***
+ * --------------------------------------------------------
+ * **Converts a string or property key literal into a ***number literal***.**
+ * - **Behavior:**
+ *      - Supports decimal numbers only.
+ *      - Automatically trims whitespace.
+ *      - Returns the number literal if valid.
+ *      - Supports scientific notation strings (e.g., `"2e-3"`, `"-5e2"`, `"2E-3"`, `"-5E2"`).
+ *        - **Note:**
+ *            - TypeScript cannot represent very small (`< 1e-6`) or very large (`> 1e15`)
+ *              numbers as literal types:
+ *              - In such cases, scientific notation strings return `0`.
+ *      - Returns `0` for strings representing hexadecimal (`0x...`), octal (`0o...`), or
+ *        binary (`0b...`) if they are string literals.
+ * - Returns `never` for non-numeric strings or unsupported formats.
+ * @template T - A string, number, or symbol (property key).
+ * @example
+ * ```ts
+ * // Number:
+ * type A = ParseNumber<0>;     // ➔ 0
+ * type B = ParseNumber<-0>;    // ➔ 0
+ * type C = ParseNumber<-0.>;   // ➔ 0
+ * type D = ParseNumber<42>;    // ➔ 42
+ * type E = ParseNumber<0.42>;  // ➔ 0.42
+ * type F = ParseNumber<-5>;    // ➔ -5
+ * type G = ParseNumber<-2.5>;  // ➔ -2.5
+ * type H = ParseNumber<2.5e3>; // ➔ 2500
+ * type I = ParseNumber<-2.5e3>;// ➔ -2500
+ * type J = ParseNumber<5e3>;   // ➔ 5000
+ * type K = ParseNumber<-5e3>;  // ➔ -5000
+ * type L = ParseNumber<5e21>;  // ➔ 5e+21
+ * type M = ParseNumber<5e-3>;  // ➔ 0.005
+ * type N = ParseNumber<5e-21>; // ➔ 5e-21
+ * type O = ParseNumber<-5e-3>; // ➔ -0.005
+ *
+ * // Numeric String:
+ * type A = ParseNumber<"0">;     // ➔ 0
+ * type B = ParseNumber<"-0">;    // ➔ 0
+ * type C = ParseNumber<"42">;    // ➔ 42
+ * type D = ParseNumber<"0.42">;  // ➔ 0.42
+ * type E = ParseNumber<"-42">;   // ➔ -42
+ * type F = ParseNumber<"-0.42">; // ➔ -0.42
+ * type G = ParseNumber<" 42 ">;  // ➔ 42
+ * type H = ParseNumber<" -42 ">; // ➔ -1
+ *
+ * // Scientific notation string:
+ * type S1 = ParseNumber<"2e3">;    // ➔  2000
+ * type S2 = ParseNumber<"-2e3">;   // ➔  -2000
+ * type S3 = ParseNumber<"2e-3">;   // ➔  0.002
+ * type S4 = ParseNumber<"-2e-3">;  // ➔  -0.002
+ * type S5 = ParseNumber<"2.5e3">;  // ➔  0
+ * type S6 = ParseNumber<"2.5e-3">; // ➔  0
+ * type S7 = ParseNumber<"2e-7">;   // ➔  0 (too small include "-2e-7" for TypeScript literal)
+ * type S8 = ParseNumber<"5e21">;   // ➔  0 (too large include "-5e21" for TypeScript literal)
+ *
+ * // Number representing hexadecimal, octal or binary:
+ * type A = ParseNumber<"011">;    // ➔ 9 (same as octal but deprecated)
+ * type B = ParseNumber<"0o11">;   // ➔ 9 (octal)
+ * type C = ParseNumber<"-0o11">;  // ➔ -9 (octal)
+ * type D = ParseNumber<"0x12">;   // ➔ 18 (hexadecimal)
+ * type E = ParseNumber<"-0x12">;  // ➔ -18 (hexadecimal)
+ * type F = ParseNumber<"0b111">;  // ➔ 7 (binary)
+ * type G = ParseNumber<"-0b111">; // ➔ -7 (binary)
+ *
+ * // String representing hexadecimal, octal or binary:
+ * type A = ParseNumber<"0x2A">;     // ➔ 0 (hex on string not supported)
+ * type B = ParseNumber<"0o52">;     // ➔ 0 (octal on string not supported)
+ * type C = ParseNumber<"0b101010">; // ➔ 0 (binary on string not supported)
+ *
+ * // Never Result
+ * type A = ParseNumber<string>; // ➔ never
+ * type B = ParseNumber<number>; // ➔ never
+ * type C = ParseNumber<"abc">;  // ➔ never
+ * type D = ParseNumber<"a1">;   // ➔ never
+ * type E = ParseNumber<"3b">;   // ➔ never
+ * ```
+ */
+type ParseNumber<T extends PropertyKey | bigint> = T extends bigint ? T : If<number extends T ? false : true, IfExtends<OrArr<[Extends<"-0", Trim<Extract<T, PropertyKey>>>, Extends<-0, T>, Extends<T, `${"-" | ""}${"0"}.`>]>, true, 0, T extends `${"-" | ""}0${"x" | "b" | "o"}${number}` ? 0 : Trim<Extract<T, PropertyKey>> extends `${infer NumT extends number | string}` ? T extends `${infer N extends number}.` ? N : NumT extends string ? ParseScientificNumber<NumT> : NumT : Trim<Extract<T, PropertyKey>> extends number ? T : never>, never>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsScientificNumber`.***
+ * -------------------------------------------------------
+ * **Checks if a string literal `T` represents a **scientific number**.**
+ * - **A scientific number is defined as a number in the form of:**
+ *      - Optional negative sign (`-`).
+ *      - Mantissa (digits, can be integer or decimal).
+ *      - Exponent indicated by `e` or `E`.
+ *      - Exponent value (digits, optional negative sign).
+ *      - **Important:**
+ *         - TypeScript cannot detect numeric literals in scientific notation
+ *            at type-level because number literals are normalized to decimals:
+ *            - Only string literals like `"2.5E3"` or `"-1e-5"` can be detected.
+ * @template T - A string literal to check.
+ * @example
+ * ```ts
+ * type A = IsScientificNumber<"1e5">;   // ➔ true
+ * type B = IsScientificNumber<"-1e-5">; // ➔ true
+ * type C = IsScientificNumber<"2.5E3">; // ➔ true
+ * type D = IsScientificNumber<"42">;    // ➔ false
+ * type E = IsScientificNumber<"-0.42">; // ➔ false
+ * type F = IsScientificNumber<string>;  // ➔ false
+ * ```
+ * @remarks
+ * - Uses template literal types and conditional type {@link Extends | **`Extends`**}.
+ * - Returns `true` if `T` is scientific number string literal, otherwise `false`.
+ * - Returns `boolean` if `T` is generic `string`.
+ */
+/** * ***Helper for {@link ParseScientificNumber | **`ParseScientificNumber`**}.***
+ *
+ */
+type BuildTuple<L extends number, T extends unknown[] = []> = T["length"] extends L ? T : BuildTuple<L, [...T, unknown]>;
+/** * ***Helper for {@link ParseScientificNumber | **`ParseScientificNumber`**}.***
+ *
+ */
+type _DecrementParseScientific<N extends number> = BuildTuple<N> extends [infer _, ...infer Rest] ? Rest["length"] : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `ParseScientificNumber`.***
+ * -------------------------------------------------------
+ * **Converts a numeric string in scientific notation (e.g., `"2e-3"`, `"-5e2"`)
+ * into a literal number type.**
+ * - **Important:**
+ *      - TypeScript cannot represent very small or very large numbers
+ *        as literal types:
+ *        - In such cases, this utility will return `0`.
+ * @template T - A numeric string to parse. Can be in:
+ * - Positive or negative scientific notation (e.g., `"1e3"`, `"-2e-2"`).
+ * - Regular number literal (e.g., `"42"`, `"-5"`).
+ * @example
+ * ```ts
+ * type A1 = ParseScientificNumber<"2e-3">;  // ➔ 0.002
+ * type A2 = ParseScientificNumber<"-2e-3">; // ➔ -0.002
+ * type A3 = ParseScientificNumber<"5e2">;   // ➔ 500
+ * type A4 = ParseScientificNumber<"-5e2">;  // ➔ -500
+ * type A5 = ParseScientificNumber<"2e-7">;  // ➔ 0 (TypeScript cannot represent literal)
+ * type A6 = ParseScientificNumber<"5e21">;  // ➔ 0 (TypeScript cannot represent literal)
+ * type A7 = ParseScientificNumber<"42">;    // ➔ 42
+ * type A8 = ParseScientificNumber<"-42">;   // ➔ -42
+ * ```
+ * @remarks
+ * - Uses type-level string manipulation to handle scientific notation.
+ * - Negative exponents are adjusted with {@link _DecrementParseScientific | **`_DecrementParseScientific`**} and
+ *  {@link Repeat | **`Repeat`**}.
+ * - Returns `0` if TypeScript cannot infer the exact numeric literal.
+ */
+type ParseScientificNumber<T extends string> = T extends `-${infer Mantissa}${"e" | "E"}-${infer Exp extends number}` ? `-${"0."}${Repeat<"0", _DecrementParseScientific<Exp>>}${Mantissa}` extends `${infer N extends number}` ? number extends N ? 0 : N : never : T extends `${infer Mantissa}${"e" | "E"}-${infer Exp extends number}` ? `0.${Repeat<"0", _DecrementParseScientific<Exp>>}${Mantissa}` extends `${infer N extends number}` ? number extends N ? 0 : N : never : T extends `-${infer Mantissa}${"e" | "E"}${infer Exp extends number}` ? `-${Mantissa}${Repeat<"0", Exp>}` extends `${infer N extends number}` ? number extends N ? 0 : N : never : T extends `${infer Mantissa}${"e" | "E"}${infer Exp extends number}` ? `${Mantissa}${Repeat<"0", Exp>}` extends `${infer N extends number}` ? number extends N ? 0 : N : never : T extends `${infer N extends number}` ? number extends N ? 0 : N : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Abs`.***
+ * -------------------------------------------------------
+ * **Computes the ***absolute value*** of `T`.**
+ * - **Behavior:**
+ *      - Accepts `number` literals or numeric `string` literals.
+ *      - Returns the ***absolute value*** as a `number`.
+ *      - If `T` is not a valid number, ***`like`***:
+ *        - `hex`, `binary`, `octal`, or `non-numeric string` will return `never`.
+ * @template T - A number type or string literal representing a number.
+ * @example
+ * ```ts
+ * type A = Abs<-42>;   // ➔ 42
+ * type B = Abs<10>;    // ➔ 10
+ * type C = Abs<"11">;  // ➔ 11
+ * type D = Abs<"-11">; // ➔ 11
+ *
+ * // Not a number
+ * type Invalid1 = Abs<"1a">;    // ➔ never
+ * type Invalid2 = Abs<"a1">;    // ➔ never
+ * type Invalid3 = Abs<"a1a">;   // ➔ never
+ * type Invalid4 = Abs<"abc">;   // ➔ never
+ * type Invalid5 = Abs<string>;  // ➔ never
+ * type Invalid6 = Abs<number>;  // ➔ never
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `Stringify`.***
+ * -------------------------------------------------------
+ * **Converts a value of type `number`, `boolean`, `string`, `bigint`, `undefined`, or `null` into a string literal type.**
+ * - **Behavior:**
+ *      - `number` ➔ string representation (e.g., `123` ➔ `"123"`)
+ *      - `boolean` ➔ `"true"` or `"false"`
+ *      - `string` ➔ itself
+ *      - `bigint` ➔ string representation with `"n"` suffix (e.g., `123n` ➔ `"123n"`)
+ *      - `undefined` ➔ `"undefined"`
+ *      - `null` ➔ `"null"`
+ *      - Other types ➔ `never`
+ * @template T - The value type to stringify.
+ * @example
+ * ```ts
+ * // Boolean
+ * type Result1 = Stringify<true>;
+ * // ➔ "true"
+ *
+ * // Number
+ * type Result2 = Stringify<123>;
+ * // ➔ "123"
+ *
+ * // BigInt
+ * type Result3 = Stringify<123n>;
+ * // ➔ "123n"
+ *
+ * // String
+ * type Result4 = Stringify<"hello">;
+ * // ➔ "hello"
+ *
+ * // Undefined
+ * type Result5 = Stringify<undefined>;
+ * // ➔ "undefined"
+ *
+ * // Null
+ * type Result6 = Stringify<null>;
+ * // ➔ "null"
+ *
+ * // Other type
+ * type Result7 = Stringify<{}>;
+ * // ➔ never
+ * ```
+ */
+type Stringify<T> = T extends number | boolean | string | bigint | undefined | null ? T extends bigint ? `${T}n` : `${T}` : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Split`***
+ * -------------------------------------------------------
+ * **A type-level utility that mimics `String.prototype.split()`.**
+ * @description
+ * Splits a string literal `Str` into a tuple of substrings,
+ * using `Del` as the delimiter.
+ * - **Behavior:**
+ *      - If `Del` is the empty string `""`, the result is a tuple of characters.
+ *      - If `Del` is not found in `Str`, the result is a tuple with the original string.
+ *      - Works only with string literals. If `Str` is just `string`, the result is `string[]`.
+ * @template Str - The input string literal to be split.
+ * @template Del - The delimiter used to split the string.
+ *                 Defaults to `""` (character-level split).
+ * @constraints
+ * - `Str` must be a string literal to get precise results.
+ * - `Del` can be a string or number (numbers are converted to strings).
+ * @example
+ * ```ts
+ * // ✅ Split into characters
+ * type A = Split<"abc">; // ➔ ["a", "b", "c"]
+ *
+ * // ✅ Split by a comma
+ * type B = Split<"a,b,c", ",">; // ➔ ["a", "b", "c"]
+ *
+ * // ✅ Split by multi-char delimiter
+ * type C = Split<"2025-08-22", "-">; // ➔ ["2025", "08", "22"]
+ *
+ * // ✅ Delimiter not found ➔ returns whole string
+ * type D = Split<"hello", "|">; // ➔ ["hello"]
+ *
+ * // ⚠️ Non-literal string
+ * type E = Split<string, ",">; // string[]
+ * ```
+ */
+type Split<Str extends string, Del extends string | number = ""> = string extends Str ? string[] : "" extends Str ? [] : Str extends `${infer T}${Del}${infer U}` ? [T, ...Split<U, Del>] : [Str];
+/** @private ***types for {@link CharAt}.***
+ *
+ */
+type _CharAt<I extends string, N extends number | `${number}`, _S extends string[] = Split<I, "">> = IfExtends<And<Extends<IsPositive<ParseNumber<N>>, true>, Extends<And<Extends<N, keyof _S>, Extends<IsStringLiteral<I>, true>>, true>>, true, _S[Extract<N, keyof _S>], undefined>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `CharAt`.***
+ * -------------------------------------------------------
+ * **A type-level utility that extracts the character at a given index `N`
+ * from a string literal type `I`.**
+ * - **Behavior:**
+ *      - If the index is out of range, the result is `undefined`.
+ *      - If `I` is not a literal string (just `string`), the result is `undefined`.
+ *      - Only **positive indices** are supported (`0` and above`).
+ * @template I - The input string literal to extract the character from.
+ * @template N - The zero-based index of the character to retrieve.
+ * @example
+ * ```ts
+ * // ✅ Basic usage
+ * type A = CharAt<"hello", 0>; // ➔ "h"
+ * type B = CharAt<"hello", 1>; // ➔ "e"
+ * type C = CharAt<"hello", 4>; // ➔ "o"
+ *
+ * // ⚠️ Index out of range ➔ undefined
+ * type D = CharAt<"hello", 5>; // ➔ undefined
+ * type E = CharAt<"abc", 99>;  // ➔ undefined
+ *
+ * // ✅ Stringified index also works
+ * type F = CharAt<"testing", "0">; // ➔ "t"
+ * type G = CharAt<"testing", "2">; // ➔ "s"
+ * type H = CharAt<"testing", "6">; // ➔ "g"
+ * type I = CharAt<"testing", "7">; // ➔ undefined
+ *
+ * // ⚠️ Non-literal strings ➔ undefined
+ * type J = CharAt<string, 2>; // ➔ undefined
+ *
+ * // ⚠️ Negative indices are not supported
+ * type K = CharAt<"abc", -1>; // ➔ undefined
+ * ```
+ */
+type CharAt<I extends string, N extends number | `${number}`> = _CharAt<I, N>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `ColorCssNamed`.***
+ * -------------------------------------------------------
+ * **Represents a **named CSS color keyword**, including `transparent`.**
+ * @description
+ * This type includes all standard color names defined in the CSS Color Module Level 4
+ * specification, and ensures type safety for string values in strongly typed UI libraries,
+ * themes, or design systems.
+ * - **Behavior:**
+ *      - Only recognized, browser-supported named colors are allowed.
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+ * @see https://drafts.csswg.org/css-color-4/#named-colors
+ * @example
+ * ```ts
+ * const textColor1: ColorCssNamed = "rebeccapurple"; // ➔ ✅ valid
+ * const textColor2: ColorCssNamed = "navy";          // ➔ ✅ valid
+ * const textColor3: ColorCssNamed = "superblue";     // ➔ ❌ Type error
+ *
+ * // Usage in a theme object
+ * const theme: Record<string, ColorCssNamed> = {
+ *   primary: "blue",
+ *   secondary: "goldenrod",
+ *   highlight: "transparent",
+ * };
+ * ```
+ */
+declare global {
+  namespace NodeJS {
+    interface EventEmitter {}
+    interface ReadableStream {}
+    interface WritableStream {}
+    interface Process {}
+  }
+  interface Buffer {}
+}
+type Global<K extends PropertyKey> = K extends keyof typeof globalThis ? (typeof globalThis)[K] : never;
+type Empty<T> = keyof T extends never ? never : T;
+/** --------------------------------------------------
+ * * ***Utility Type: `NodeBuiltins`.***
+ * --------------------------------------------------
+ * Represents commonly used Node.js runtime objects
+ * when Node.js type definitions are available.
+ *
+ * @description
+ * Includes frequently encountered Node.js core objects
+ * and runtime-related built-ins.
+ *
+ * - **Examples:**
+ *      - `Buffer`
+ *      - `EventEmitter`
+ *      - `ReadableStream`
+ *      - `WritableStream`
+ *      - `process`
+ *      - `URL`
+ *
+ * - ❌ Excludes:
+ *      - Plain objects (`{}`)
+ *      - Primitive values
+ *      - Most Node.js modules/classes
+ *
+ * - ⚠️ Notes:
+ *      - This type is intentionally **not exhaustive**.
+ *      - Missing Node.js types automatically resolve to `never`.
+ *      - `URL` is always included because it exists in both
+ *        browser and Node.js environments.
+ */
+type NodeBuiltins = Empty<Global<"Buffer">> | Empty<NodeJS.EventEmitter> | Empty<NodeJS.ReadableStream> | Empty<NodeJS.WritableStream> | Empty<NodeJS.Process> | URL;
+/** --------------------------------------------------
+ * * ***Utility Type: `DataTypes`.***
+ * --------------------------------------------------
+ * **Represents a broad union of commonly used JavaScript data types.**
+ * - ✅ ***Includes:***
+ *     - `Primitive-Types`.
+ *     - `object`.
+ *     - `null`.
+ *     - `undefined`.
+ *     - `symbol`.
+ *     - `Any-Function` signature.
+ * @example
+ * ```ts
+ * function isValidType(value: DataTypes): boolean {
+ *   return value !== undefined && value !== null;
+ * }
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `TypedArray`.***
+ * --------------------------------------------------
+ * **Represents all JavaScript **TypedArray** types used for binary data manipulation.**
+ * - ✅ ***Includes:***
+ *     - `Int8Array`.
+ *     - `Uint8Array`.
+ *     - `Uint8ClampedArray`.
+ *     - `Int16Array`.
+ *     - `Uint16Array`.
+ *     - `Int32Array`.
+ *     - `Uint32Array`.
+ *     - `Float32Array`.
+ *     - `Float64Array`.
+ *     - `BigInt64Array`.
+ *     - `BigUint64Array`.
+ */
+type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+/** --------------------------------------------------
+ * * ***Utility Type: `WebApiObjects`.***
+ * --------------------------------------------------
+ * **Represents common **Web API objects** available in the browser.**
+ * - ✅ ***Includes:***
+ *     - URL: `URL`, `URLSearchParams`.
+ *     - Networking: `Request`, `Response`, `Headers`, `WebSocket`.
+ *     - Streams: `ReadableStream`, `WritableStream`, `TransformStream`.
+ *     - Events: `Event`, `CustomEvent`, `MessageChannel`, `MessagePort`, `MessageEvent`.
+ *     - DOM: `HTMLElement`, `Node`, `Document`, `Window`, `CanvasRenderingContext2D`.
+ *     - Encoding: `TextEncoder`, `TextDecoder`.
+ *     - File: `File`, `FileList`, `ImageBitmap`, `FormData`.
+ *     - Abort: `AbortController`, `AbortSignal`.
+ *     - Crypto: `CryptoKey`.
+ */
+type WebApiObjects = URL | URLSearchParams | FormData | Headers | Response | Request | ReadableStream<any> | WritableStream<any> | TransformStream<any, any> | MessageChannel | MessagePort | MessageEvent | Event | CustomEvent | HTMLElement | Node | Document | Window | AbortController | AbortSignal | TextEncoder | TextDecoder | CryptoKey | File | FileList | ImageBitmap | CanvasRenderingContext2D | WebSocket;
+/** --------------------------------------------------
+ * * ***Utility Type: `IntlObjects`.***
+ * --------------------------------------------------
+ * **Represents all **ECMAScript Internationalization API** objects from `Intl`.**
+ * - ✅ ***Includes:***
+ *     - `Intl.Collator`.
+ *     - `Intl.DateTimeFormat`.
+ *     - `Intl.NumberFormat`.
+ *     - `Intl.RelativeTimeFormat`.
+ *     - `Intl.PluralRules`.
+ *     - `Intl.ListFormat`. (if environment is supported).
+ *     - `Intl.Locale`. (if environment is supported).
+ */
+type IntlObjects = { [K in keyof typeof Intl]: (typeof Intl)[K] extends (abstract new (...args: any[]) => infer R) ? R : never }[keyof typeof Intl];
+/** --------------------------------------------------
+ * * ***Utility Type: `BoxedPrimitivesTypes`.***
+ * --------------------------------------------------
+ * **Represents JavaScript **boxed primitive objects** (object wrappers for primitive values).**
+ * @description
+ * Boxed primitives are created using the `new` keyword on primitive wrapper constructors.
+ * - ✅ ***Includes (object wrappers):***
+ *     - `new Number(123)` ➔ `Number`.
+ *     - `new String("hello")` ➔ `String`.
+ *     - `new Boolean(true)` ➔ `Boolean`.
+ * - ❌ ***Excludes (primitive values):***
+ *     - `123` ➔ `number`.
+ *     - `"hello"` ➔ `string`.
+ *     - `true` ➔ `boolean`.
+ * - ℹ️ ***Note:***
+ *     - These are **rarely used directly** in modern **JavaScript/TypeScript**.
+ *     - However, they exist for completeness and are sometimes relevant
+ *       when distinguishing between **primitive values** and **object wrappers**.
+ * @example
+ * ```ts
+ * const a: BoxedPrimitivesTypes = new Number(123);
+ * // ➔ ✅ valid
+ * const b: BoxedPrimitivesTypes = new String("abc");
+ * // ➔ ✅ valid
+ * const c: BoxedPrimitivesTypes = new Boolean(false);
+ * // ➔ ✅ valid
+ *
+ * // ❌ Not allowed (primitive values):
+ * const x: BoxedPrimitivesTypes = 123;
+ * const y: BoxedPrimitivesTypes = "abc";
+ * const z: BoxedPrimitivesTypes = true;
+ * ```
+ */
+type BoxedPrimitivesTypes = Number | String | Boolean;
+/** --------------------------------------------------
+ * * ***Utility Type: `NonPlainObject`.***
+ * --------------------------------------------------
+ * **Represents all known **non-plain object types**,
+ * i.e., values that are **not** considered a `"plain object"` (`{ [key: string]: any }`).**
+ * - ✅ ***Includes:***
+ *     - **Functions**.
+ *     - **Arrays**.
+ *     - **Native objects:** `Date`, `RegExp`, `Map`, `Set`, `WeakMap`, `WeakSet`.
+ *     - **Built-in classes & APIs:** `Promise`, `Error`, `ArrayBuffer`, `DataView`.
+ *     - **Typed arrays:** `TypedArray`.
+ *     - **Browser & Node APIs:** `WebApiObjects`, `IntlObjects`, `NodeBuiltins`.
+ *     - **Symbols**.
+ *     - **Proxies** (wrapping any object).
+ *     - The global **`Reflect`** object.
+ * - ❌ ***Excludes:***
+ *     - Plain objects (`{ foo: string }`, `Record<string, any>`), `null` and `undefined`.
+ * - ℹ️ ***Note:***
+ *     - Use this type when you need to differentiate **plain objects** from **all other object-like values**.
+ * @example
+ * ```ts
+ * type A = NonPlainObject;
+ *
+ * const x: A = new Date();
+ * // ➔ ✅ Allowed
+ * const y: A = [1, 2, 3];
+ * // ➔ ✅ Allowed
+ * const z: A = Promise.resolve(123);
+ * // ➔ ✅ Allowed
+ *
+ * // ❌ Not allowed (plain object):
+ * // const bad: A = { foo: "bar" };
+ * ```
+ */
+type NonPlainObject = BoxedPrimitivesTypes | AnyFunction | Promise<any> | Array<any> | AnObjectNonArray;
+/** --------------------------------------------------
+ * * ***Utility Type: `AnObjectNonArray`.***
+ * --------------------------------------------------
+ * **Represents all **non-null, non-array, object-like values** in JavaScript/Node.js.**
+ * - ✅ ***Includes:***
+ *     - **Built-in objects:** `Date`, `RegExp`, `Error`, `ArrayBuffer`, `DataView`.
+ *     - **Collections:** `Map`, `Set`, `WeakMap`, `WeakSet`.
+ *     - **Typed arrays:**
+ *       `Int8Array`, `Uint8Array`, `Uint8ClampedArray`,
+ *       `Int16Array`, `Uint16Array`,
+ *       `Int32Array`, `Uint32Array`,
+ *       `Float32Array`, `Float64Array`,
+ *       `BigInt64Array`, `BigUint64Array`.
+ *     - **Browser Web APIs:**
+ *       `URL`, `URLSearchParams`, `FormData`, `Headers`, `Response`, `Request`,
+ *       `ReadableStream`, `WritableStream`, `TransformStream`,
+ *       `MessageChannel`, `MessagePort`, `MessageEvent`,
+ *       `Event`, `CustomEvent`, `HTMLElement`, `Node`, `Document`, `Window`,
+ *       `CanvasRenderingContext2D`,
+ *       `AbortController`, `AbortSignal`,
+ *       `TextEncoder`, `TextDecoder`,
+ *       `CryptoKey`, `File`, `FileList`, `ImageBitmap`, `WebSocket`.
+ *     - **ECMAScript Internationalization API objects:**
+ *       `Intl.Collator`, `Intl.DateTimeFormat`, `Intl.NumberFormat`,
+ *       `Intl.RelativeTimeFormat`, `Intl.PluralRules`,
+ *       `Intl.ListFormat`, `Intl.Locale`.
+ *     - **Node.js built-ins:** `Buffer`.
+ *     - **Symbols**.
+ *     - **Proxies** (wrapping any object).
+ *     - The global **`Reflect`** object.
+ * - ❌ ***Excludes:***
+ *     - `null`.
+ *     - Arrays (`[]`, `new Array()`).
+ * - ℹ️ ***Note:***
+ *     - Use this type when you need to represent **any object-like value except arrays and `null`**.
+ * @example
+ * ```ts
+ * const a: AnObjectNonArray = new Date();
+ * const b: AnObjectNonArray = new Map();
+ * const c: AnObjectNonArray = Symbol("id");
+ *
+ * // ❌ These are NOT allowed:
+ * // const x: AnObjectNonArray = null;
+ * // const y: AnObjectNonArray = [];
+ * ```
+ */
+type AnObjectNonArray = Date | RegExp | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Error | ArrayBuffer | DataView | TypedArray | WebApiObjects | IntlObjects | NodeBuiltins | symbol | {
+  [Symbol.toStringTag]: "Proxy";
+} | typeof Reflect;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsGeneralArray`.***
+ * -------------------------------------------------------
+ * **Checks if `T` is a **general array type** (`X[]` or `ReadonlyArray<X>`)
+ * instead of a tuple literal.**
+ * - **Behavior:**
+ *      - Returns `true` for `string[]`, `(number | boolean)[]`, `any[]`, etc.
+ *      - Returns `false` for tuples like `[]`, `[1, 2, 3]`, or `[string, number]`.
+ * @template T - The type to check.
+ * @example
+ * ```ts
+ * type A = IsGeneralArray<string[]>;  // ➔ true
+ * type B = IsGeneralArray<[]>;        // ➔ false
+ * type C = IsGeneralArray<[1, 2, 3]>; // ➔ false
+ * type D = IsGeneralArray<ReadonlyArray<number>>; // ➔ true
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `ExtractStrict`.***
+ * --------------------------------------------------
+ * **Performs a stricter version of the built-in `Extract<T, U>`
+ * with improved type narrowing.**
+ * - ✅ Especially useful in generic utilities where the
+ *   standard `Extract` can widen or collapse unions.
+ * @template T - The full union or set of types.
+ * @template U - The type(s) to be kept from `T`.
+ * @example
+ * ```ts
+ * type A = 'a' | 'b' | 'c';
+ * type B = ExtractStrict<A, 'b' | 'c'>;
+ * // ➔ 'b' | 'c'
+ * ```
+ */
+type ExtractStrict<T, U extends T> = T extends unknown ? 0 extends (U extends T ? ([T] extends [U] ? 0 : never) : never) ? T : never : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsArrayOrTuple`.***
+ * -------------------------------------------------------
+ * **Checks if a given type `T` is an array or tuple type.**
+ * - This includes both mutable (`T[]`) and readonly (`readonly T[]`) arrays.
+ * @template T - The type to check.
+ * @example
+ * type A = IsArrayOrTuple<string[]>;
+ * // ➔ true
+ * type B = IsArrayOrTuple<readonly [string, number]>;
+ * // ➔ true
+ * type C = IsArrayOrTuple<string>; // ➔ false
+ */
+type IsArrayOrTuple<T> = T extends readonly any[] ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsConstructor`.***
+ * -------------------------------------------------------
+ * **Checks whether a given type `T` is a constructor type.**
+ *
+ * This utility evaluates to `true` if `T` has a constructor
+ * signature, including constructors of **abstract classes**.
+ *
+ * It uses the `abstract new (...args) => instance` signature,
+ * meaning it matches any type that represents a constructor —
+ * even if the class cannot be instantiated directly.
+ *
+ * - **Behavior:**
+ *      - Evaluates to `true` if `T` has a compatible constructor signature.
+ *      - Optionally validates the **constructor parameter tuple**
+ *        and **instance type** using the generic parameters `A` and `R`.
+ *
+ * - **Difference from {@link IsNewable | `IsNewable`}:**
+ *      - `IsConstructor` returns `true` for **both concrete and abstract constructors**.
+ *      - `IsNewable` only returns `true` for constructors that can be
+ *        instantiated with `new`.
+ *
+ * In other words:
+ *
+ * ```ts
+ * IsConstructor ⊇ IsNewable
+ * ```
+ *
+ * @template T - The type to check.
+ * @template A - Expected constructor parameter tuple (default: `any[]`).
+ * @template R - Expected instance type (default: `any`).
+ *
+ * @example
+ * ```ts
+ * class A {}
+ * abstract class B {}
+ *
+ * type T1 = IsConstructor<typeof A>;
+ * // ➔ true
+ * type T2 = IsConstructor<typeof B>;
+ * // ➔ true
+ * ```
+ *
+ * @example
+ * ```ts
+ * class User {
+ *   constructor(x: number, y: string) {}
+ * }
+ *
+ * type T1 = IsConstructor<typeof User, [number, string], User>;
+ * // ➔ true
+ * type T2 = IsConstructor<typeof User, [string], User>;
+ * // ➔ false
+ * ```
+ *
+ * @example
+ * ```ts
+ * type T1 = IsConstructor<() => void>;
+ * // ➔ false
+ * ```
+ */
+type IsConstructor<T, A extends any[] = any[], R = any> = T extends (abstract new (...args: A) => R) ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsFunction`.***
+ * -------------------------------------------------------
+ * **Checks if a given type `T` is a callable function type.**
+ * @template T - The type to check.
+ * @example
+ * type A = IsFunction<() => void>; // ➔ true
+ * type B = IsFunction<string>;     // ➔ false
+ */
+type IsFunction<T> = T extends AnyFunction ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Primitive`.***
+ * -------------------------------------------------------
+ * **Represents **all primitive types in JavaScript/TypeScript**,
+ * including their literal variants.**
+ * - **This type matches:**
+ *      - Core primitive types:
+ *        - `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `undefined`.
+ *      - Literal counterparts:
+ *        - `"foo"`, `42`, `true`, etc.
+ * - ⚠️ ***Note:***
+ *      - Unlike some definitions, this does **not** include `void` or `never`,
+ *        since they are TypeScript-specific keywords, not runtime primitives.
+ * @example
+ * ```ts
+ * type A = Primitive;
+ * // ➔ any strict primitive type
+ * type B = "hello" extends Primitive ? true : false;
+ * // ➔ true
+ * type C = void extends Primitive ? true : false;
+ * // ➔ false
+ * ```
+ */
+type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsPrimitive`.***
+ * -------------------------------------------------------
+ * **Checks if a given type `T` is a **strict primitive type** in JavaScript/TypeScript,
+ * including literal variants.**
+ * - **Behavior:**
+ *      - ***Includes:***
+ *          - `string`, `number`, `bigint`, `boolean`, `symbol`, `null`, `undefined`.
+ *          - Literal types like: `"foo"`, `42`, `true`.
+ *      - ***Excludes:***
+ *          - `void` (absence of value).
+ *          - `never` (impossible type).
+ *          - `object`, `unknown`, `Date`, `arrays`, `functions`, etc.
+ * @template T - The type to check
+ * @example
+ * ```ts
+ * type A = IsPrimitive<"foo">;      // ➔ true
+ * type B = IsPrimitive<null>;       // ➔ true
+ * type C = IsPrimitive<number>;     // ➔ true
+ * type D = IsPrimitive<undefined>;  // ➔ true
+ * type E = IsPrimitive<{}>;         // ➔ false
+ * type F = IsPrimitive<void>;       // ➔ false
+ * type G = IsPrimitive<never>;      // ➔ false
+ * type H = IsPrimitive<unknown>;    // ➔ false
+ * type I = IsPrimitive<object>;     // ➔ false
+ * type J = IsPrimitive<Date>;       // ➔ false
+ * type K = IsPrimitive<[]>;         // ➔ false
+ * type L = IsPrimitive<() => void>; // ➔ false
+ * ```
+ */
+type IsPrimitive<T> = IsNever<T> extends true ? false : T extends Primitive ? true : false;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsRealPrimitive`.***
+ * -------------------------------------------------------
+ * **Checks if a given type `T` is a **real primitive type** in JavaScript/TypeScript,
+ * based on runtime behavior, **excluding `null`** but including `undefined`.**
+ * - **Behavior:**
+ *      - ***Includes:***
+ *          - `string`, `number`, `bigint`, `boolean`, `symbol`, `undefined`.
+ *          - Literal types like: `"foo"`, `42`, `true`.
+ *      - ***Excludes:***
+ *          - `null`.
+ *          - `never` (impossible type).
+ *          - Objects, arrays, functions, `Date`, `unknown`, etc.
+ * - ⚠️ ***Note:***
+ *      - This aligns with runtime `typeof` checks in JS:
+ *         - `typeof null === "object"`,
+ *            so `null` is excluded from **“real primitives”**.
+ * @template T - The type to check.
+ * @example
+ * ```ts
+ * type A = IsRealPrimitive<42>;         // ➔ true
+ * type B = IsRealPrimitive<string>;     // ➔ true
+ * type C = IsRealPrimitive<boolean>;    // ➔ true
+ * type D = IsRealPrimitive<undefined>;  // ➔ true
+ * type E = IsRealPrimitive<{}>;         // ➔ false
+ * type F = IsRealPrimitive<[]>;         // ➔ false
+ * type G = IsRealPrimitive<null>;       // ➔ false
+ * type H = IsRealPrimitive<Date>;       // ➔ false
+ * type I = IsRealPrimitive<() => void>; // ➔ false
+ * ```
+ */
+/** * Applies readonly behavior according to mode.
+ *
+ */
+type ApplyReadonlyMode<T, Mode extends PrettifyOptions["readonlyMode"]> = Mode extends "remove" ? { -readonly [K in keyof T]: T[K] } : Mode extends "preserve" ? { readonly [K in keyof T]: T[K] } : { [K in keyof T]: T[K] };
+/** ---------------------------------------------------------------------------
+ * * ***Options for {@link Prettify|`Prettify`}.***
+ * ---------------------------------------------------------------------------
+ * **Options for customizing the behavior of the {@link Prettify | **`Prettify`**} type utility.**
+ */
+type PrettifyOptions = {
+  /** -------------------------------------------------------
+   * * ***recursive***
+   * -------------------------------------------------------
+   * **Enables **deep prettification** of types when set to `true`.**
+   * @description
+   * By default (`false`), {@link Prettify | **`Prettify`**} only flattens the **top-level shape**
+   * of objects and intersections. Nested objects, arrays, and tuples remain as-is
+   * unless this option is enabled.
+   * - ***Behavior when `true`:***
+   *      - **Plain objects**: Nested intersections are expanded recursively.
+   *      - **Arrays & tuples**: Each element type is recursively prettified.
+   *      - **Readonly handling**: Nested properties respect the `readonlyMode` option.
+   *      - **Functions, constructors, and built-in objects** (Set, Map, Date, Promise, etc.)
+   *        are **not** affected or expanded.
+   *      - **Nested intersections**: Combined properties are flattened recursively.
+   * - ⚠️ ***Notes:***
+   *      - Recursive mode only applies to **plain objects**, **arrays**, and **tuples**.
+   *      - Readonly modifiers on nested properties follow the `readonlyMode` rules:
+   *        - `"auto"` ➔ keep as-is
+   *        - `"remove"` ➔ strip readonly
+   *        - `"preserve"` ➔ make readonly
+   *      - Arrays and tuples maintain `readonly` if the original type is `readonly` and `readonlyMode` is `"auto"` or `"preserve"`.
+   * @default false
+   * @example
+   * ```ts
+   * type Nested = {
+   *   a: {
+   *       readonly b: { c: number } & { d: string }
+   *   } & { e: boolean };
+   *   list: readonly ({ id: number } & { name: string })[];
+   *   set: Set<{ x: number } & { y: string }>;
+   * };
+   *
+   * // Top-level only (default)
+   * type Shallow = Prettify<Nested>;
+   * // ➔ {
+   * //      a: { readonly b: { c: number } & { d: string } } & { e: boolean };
+   * //      list: readonly ({ id: number } & { name: string })[];
+   * //      set: Set<{ x: number } & { y: string }>;
+   * //    }
+   *
+   * // Fully recursive flatten
+   * type Deep = Prettify<Nested, { recursive: true }>;
+   * // ➔ {
+   * //      a: { readonly b: { c: number; d: string }; e: boolean };
+   * //      list: readonly { id: number; name: string }[];
+   * //      set: Set<{ x: number } & { y: string }>; // built-in ignored
+   * //    }
+   * ```
+   */
+  recursive?: boolean;
+  /** -------------------------------------------------------
+   * * ***readonlyMode***
+   * -------------------------------------------------------
+   * **Determines how `readonly` modifiers are applied to properties
+   * when using {@link Prettify}.**
+   * - **Modes:**
+   *      - `"auto"` ➔ Keep `readonly` exactly as in the original type (default).
+   *      - `"remove"` ➔ Remove all `readonly` modifiers.
+   *      - `"preserve"` ➔ Make all properties `readonly`.
+   * - **Behavior:**
+   *      - Applies to both **top-level** and **nested properties** (if `recursive` is `true`).
+   *      - Arrays and tuples preserve or adjust `readonly` according to the selected mode:
+   *        - `"auto"` ➔ preserve array/tuple readonly as-is.
+   *        - `"remove"` ➔ array/tuple becomes mutable.
+   *        - `"preserve"` ➔ array/tuple becomes readonly.
+   *      - Functions, constructors, and built-in objects (Set, Map, Date, Promise, etc.) are **not affected**.
+   *      - Nested intersections respect `readonlyMode` recursively if `recursive` is enabled.
+   * - ⚠️ ***Notes:***
+   *      - For nested objects, `readonly` behavior only changes if `recursive: true`.
+   *      - `readonlyMode` does **not** override `readonly` on function parameters, methods, or constructors.
+   * @default "auto"
+   * @example
+   * ```ts
+   * type T = { readonly a: number; b: string };
+   *
+   * // Default: auto
+   * type Auto = Prettify<T, { readonlyMode: "auto" }>;
+   * // ➔ { readonly a: number; b: string }
+   *
+   * // Remove readonly
+   * type Remove = Prettify<T, { readonlyMode: "remove" }>;
+   * // ➔ { a: number; b: string }
+   *
+   * // Force all readonly
+   * type Preserve = Prettify<T, { readonlyMode: "preserve" }>;
+   * // ➔ { readonly a: number; readonly b: string }
+   *
+   * // Recursive + preserve
+   * type Nested = {
+   *   config: { readonly port: number } & { host: string }
+   * };
+   * type RecursivePreserve = Prettify<Nested, { recursive: true; readonlyMode: "preserve" }>;
+   * // ➔ { readonly config: { readonly port: number; readonly host: string } }
+   * ```
+   */
+  readonlyMode?: Extract<"auto" | "remove" | "preserve", string>;
+  /** ---------------------------------
+   * * ***Skips applying the prettify transformation.***
+   * ---------------------------------
+   *
+   * When enabled, the output will be returned as-is without running the
+   * prettify step.
+   *
+   * @default false
+   *
+   */
+  skipPrettify?: boolean;
+};
+/** -------------------------------------------------------
+ * * ***DefaultPrettifyOptions***
+ * -------------------------------------------------------
+ * **Default options {@link Prettify | **`Prettify`**} used when no custom options are provided.**
+ */
+type DefaultPrettifyOptions = {
+  skipPrettify: false;
+  recursive: false;
+  readonlyMode: "auto";
+};
+type MergeReadonlyIntersection<T> = T extends readonly any[] ? T : T extends object ? { [K in keyof T]: T[K] } : T;
+/** -------------------------------------------------------
+ * * ***Utility Type: `Prettify`.***
+ * -------------------------------------------------------
+ * **Flattens and simplifies complex TypeScript types into a more
+ * human-readable form, by forcing the compiler to expand intersections.**
+ * @description
+ * By default, only the **top-level shape** of an object is flattened.
+ * To also prettify **nested objects**, set the `recursive` option.
+ * - ⚠️ ***Note:***
+ *      - `recursive: true` only affects **plain objects** and **arrays/tuples**.
+ *      - Built-in objects like `Set`, `Map`, `Date`, `Promise`, etc.
+ *        will **not** be recursively prettified.
+ *      - `readonly` handling is controlled via the `readonlyMode` option.
+ * - **ℹ️ Options:**
+ *      - `recursive?: boolean` (default: `false`):
+ *        - Whether to recursively expand nested objects and intersections.
+ *      - `readonlyMode?: "auto" | "remove" | "preserve"` (default: `"auto"`):
+ *        - How `readonly` modifiers are treated:
+ *          - `"auto"`     ➔ preserve `readonly` as-is (**default**).
+ *          - `"remove"`   ➔ strip all `readonly`.
+ *          - `"preserve"` ➔ enforce `readonly` everywhere.
+ * @template T - The type to prettify.
+ * @template Options - Configuration options.
+ * @example
+ * ```ts
+ * // --- Top-level only (default) ---
+ * type T0 = Prettify<{ a: number } & { b: string }>;
+ * // ➔ { a: number; b: string }
+ *
+ * // --- Recursive expansion of nested objects ---
+ * type T1 = Prettify<
+ *   { a: { x: number } & { y: string } } & { b: boolean },
+ *   { recursive: true }
+ * >;
+ * // ➔ { a: { x: number; y: string }; b: boolean }
+ *
+ * // --- Readonly handling modes ---
+ * type T2 = { readonly id: number; name: string };
+ *
+ * type R1 = Prettify<T2>;
+ * // (default: readonlyMode = "auto")
+ * // ➔ { readonly id: number; name: string }
+ *
+ * type R2 = Prettify<T2, { readonlyMode: "remove" }>;
+ * // ➔ { id: number; name: string }
+ *
+ * type R3 = Prettify<T2, { readonlyMode: "preserve" }>;
+ * // ➔ { readonly id: number; readonly name: string }
+ *
+ * // --- Readonly + mutable intersection ---
+ * type T3 = Prettify<{ readonly a: number } & { a: number; b: boolean }>;
+ * // ➔ { a: number; b: boolean }
+ * // (in "auto" mode, readonly lose over mutable)
+ *
+ * // --- Nested readonly with recursive ---
+ * type T4 = Prettify<
+ *   { config: { readonly port: number } & { host: string } },
+ *   { recursive: true }
+ * >;
+ * // ➔ { config: { readonly port: number; host: string } }
+ *
+ * // --- Arrays with readonly ---
+ * type T5 = Prettify<
+ *   { list: readonly ({ id: number } & { name: string })[] },
+ *   { recursive: true }
+ * >;
+ * // (readonly on array is preserved in "auto" mode)
+ * // ➔ { list: readonly { id: number; name: string }[] }
+ *
+ * type T6 = Prettify<
+ *   { list: readonly ({ id: number } & { name: string })[] },
+ *   { recursive: true; readonlyMode: "remove" }
+ * >;
+ * // ➔ { list: { id: number; name: string }[] }
+ *
+ * // --- Built-in objects are ignored (not expanded) ---
+ * type T7 = Prettify<
+ *   { s: Set<{ a: number } & { b: string }> },
+ *   { recursive: true }
+ * >;
+ * // ➔ { s: Set<{ a: number } & { b: string }> }
+ * ```
+ */
+type Prettify<T, Options extends PrettifyOptions = DefaultPrettifyOptions> = Options["skipPrettify"] extends true ? T : IsPrimitive<T> extends true ? T : IsFunction<T> extends true ? T : IsConstructor<T> extends true ? T : IsArrayOrTuple<T> extends true ? ApplyReadonlyMode<{ [K in keyof T]: If<Options["recursive"], Prettify<T[K], Options>, T[K]> }, Options["readonlyMode"]> : T extends NonPlainObject ? T : T extends object ? ApplyReadonlyMode<MergeReadonlyIntersection<{ [K in keyof T]: If<Options["recursive"], Prettify<T[K], Options>, T[K]> }>, Options["readonlyMode"]> : T;
+/** ---------------------------------------------------------------------------
+ * * ***Options for {@link Mutable | `Mutable`}.***
+ * ---------------------------------------------------------------------------
+ * **Configuration options for the ***{@link Mutable | **`Mutable`**}*** type utilities.**
+ * @example
+ * ```ts
+ * type Opt1 = MutableOptions;
+ * // ➔ { recursive: boolean }
+ * ```
+ */
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsArray`.***
+ * -------------------------------------------------------
+ * **Returns a boolean whether the passed argument is an array.**
+ * @example
+ * type Case1 = IsArray<[]>;
+ * // ➔ true
+ * type Case2 = IsArray<string>;
+ * // ➔ false
+ */
+type IsArray<T> = AndArr<[Not<IsAny<T>>, Not<IsNever<T>>, Extends<T, readonly unknown[]>]>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `IsMutableArray`.***
+ * -------------------------------------------------------
+ * **Returns a boolean whether the passed argument is a mutable array.**
+ * @example
+ * type Case1 = IsMutableArray<[]>;
+ * // ➔ true
+ * type Case2 = IsMutableArray<readonly []>;
+ * // ➔ false
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `Nullish`.***
+ * --------------------------------------------------
+ * **Useful as a shorthand when working with optional or missing values.**
+ * - **Represents all values considered **`nullish`**:**
+ *      - `null`
+ *      - `undefined`
+ */
+type Nullish = null | undefined;
+/** --------------------------------------------------
+ * * ***Utility Type: `Nullable`.***
+ * --------------------------------------------------
+ * **Represents a type that can be either `T` or `null`.**
+ * @template T - The base type.
+ * @example
+ * ```ts
+ * type A = Nullable<string>; // ➔ string | null
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `Nilable`.***
+ * --------------------------------------------------
+ * **Represents a type that can be either `T`, `null`, or `undefined`.**
+ * @template T - The base type.
+ * @example
+ * ```ts
+ * type A = Nilable<number>; // ➔ number | null | undefined
+ * ```
+ */
+type Nilable<T> = T | null | undefined;
+/** --------------------------------------------------
+ * * ***Utility Type: `Undefinedable`.***
+ * --------------------------------------------------
+ * **Represents a type that can be either `T` or `undefined`.**
+ * @template T - The base type.
+ * @example
+ * ```ts
+ * type A = Undefinedable<boolean>; // ➔ boolean | undefined
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `KeepNull`.***
+ * --------------------------------------------------
+ * **Keeps `null` in the output type **only if** the input type `T` includes `null`, otherwise resolves to `never`.**
+ * @template T - Input type to check for `null`.
+ * @example
+ * ```ts
+ * type A = KeepNull<string | null>; // ➔ null
+ * type B = KeepNull<string>;        // ➔ never
+ * ```
+ */
+type KeepNull<T> = null extends T ? null : never;
+/** --------------------------------------------------
+ * * ***Utility Type: `KeepUndef`.***
+ * --------------------------------------------------
+ * **Keeps `undefined` in the output type **only if** the input type `T` includes `undefined`, otherwise resolves to `never`.**
+ * @template T - Input type to check for `undefined`.
+ * @example
+ * ```ts
+ * type A = KeepUndef<number | undefined>; // ➔ undefined
+ * type B = KeepUndef<number>;             // ➔ never
+ * ```
+ */
+type KeepUndef<T> = undefined extends T ? undefined : never;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NullToUndefined`.***
+ * -------------------------------------------------------
+ * **Transforms `null` or `undefined` types into `undefined`, otherwise, returns
+ * the original type `T` unchanged.**
+ * @template T - The input type to transform.
+ * @example
+ * ```ts
+ * type A = NullToUndefined<null>;      // ➔ undefined
+ * type B = NullToUndefined<undefined>; // ➔ undefined
+ * type C = NullToUndefined<string>;    // ➔ string
+ * type D = NullToUndefined<null[]>;    // ➔ null[]
+ * type E = NullToUndefined<(string | null)[]>; // ➔ (string | null)[]
+ * ```
+ */
+type NullToUndefined<T> = T extends null ? undefined : T extends undefined ? undefined : T;
+/** -------------------------------------------------------
+ * * ***Utility Type: `NonNullableObject`.***
+ * -------------------------------------------------------
+ * **Makes all properties of the object type `T` non-nullable.**
+ * @template T - Object type to transform.
+ * @example
+ * ```ts
+ * type A = NonNullableObject<{ a: string | null; b: number | undefined }>;
+ * // ➔ { a: string; b: number }
+ * ```
+ */
+/** --------------------------------------------------
+ * * ***Internal Utility Type for: {@link NumberRangeUnion | `NumberRangeUnion`}.***
+ * --------------------------------------------------
+ * @template N - Starting/Ending number of the range (inclusive).
+ * @template Acc - Internal accumulator for recursion (do not set manually).
+ */
+type Enumerate<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc["length"]]>;
+/** --------------------------------------------------
+ * * ***Utility Type: `NumberRangeUnion`.***
+ * --------------------------------------------------
+ * **Generate a union type of numbers from `From` to `To` using enumeration.**
+ * @description
+ * Produces a **numeric union type** from `From` to `To` (inclusive),
+ * using a simpler approach based on `Enumerate<N>` helper type.
+ * - ✅ Straightforward & easy to reason about.
+ * - ⚠️ Still limited by TypeScript recursion depth (safe up to `999`).
+ * - ⚙️ Best used for **smaller ranges** (`≤ 100`) or when readability matters.
+ * - ℹ️ For **larger ranges** (`≥ 101`) use {@link NumberRangeLimit | `NumberRangeLimit`} instead.
+ * @template From - Starting number of the range (inclusive).
+ * @template To - Ending number of the range (inclusive).
+ * @example
+ * ```ts
+ * type RangeA = NumberRangeUnion<3, 6>;
+ * // ➔ 3 | 4 | 5 | 6
+ * type RangeB = NumberRangeUnion<0, 2>;
+ * // ➔ 0 | 1 | 2
+ * type RangeC = NumberRangeUnion<8, 8>;
+ * // ➔ 8
+ * type RangeD = NumberRangeUnion<20, 10>;
+ * // ➔ 10
+ * ```
+ */
+type NumberRangeUnion<From extends number, To extends number> = From extends To ? From : Exclude<Enumerate<To>, Enumerate<From>> extends never ? To : Exclude<Enumerate<To>, Enumerate<From>> | To;
+/** --------------------------------------------------
+ * * ***Internal Utility Type for: {@link NumberRangeLimit | `NumberRangeLimit`}.***
+ * --------------------------------------------------
+ * @template From - Starting number of the range (inclusive).
+ * @template To - Ending number of the range (inclusive).
+ * @template Result - Internal accumulator for recursion (do not set manually).
+ */
+/** --------------------------------------------------
+ * * ***Utility Type: `OmitStrict`.***
+ * --------------------------------------------------
+ * **Strictly omits keys `K` from type `T`, with optional flattening for readability using `Prettify`.**
+ * - **Behavior:**
+ *      - ✅ Enhances autocomplete and type inspection clarity in editors.
+ *      - ✅ Optionally flattens nested intersections or mapped types into a cleaner shape.
+ * @template T - The original object type.
+ * @template K - The keys to omit from `T`.
+ * @template PrettifyOptions - Options controlling whether the resulting
+ * type should be normalized using the `Prettify` helper.
+ * @example
+ * ```ts
+ * type A = { a: number; b: string; c: boolean };
+ * type B = OmitStrict<A, 'b'>;
+ * // ➔ { a: number; c: boolean }
+ *
+ * type C = OmitStrict<A, 'b', { skipPrettify: true }>;
+ * // ➔ Omit without prettifying, keeps intersection structure
+ *
+ * type D = OmitStrict<A, 'b', true, { recursive: false }>;
+ * // ➔ Prettifies only top level, does not recurse into nested objects
+ * ```
+ */
+type OmitStrict<T, K extends keyof T, PrettifyOptions$9 extends PrettifyOptions = DefaultPrettifyOptions> = Prettify<Omit<T, K>, PrettifyOptions$9>;
+/** ----------------------------------------------------------------
+ * * ***Options for {@link OverrideTypes | `OverrideTypes`}.***
+ * ----------------------------------------------------------------
+ * Configuration options controlling how overriding behaves.
+ */
+type OverrideTypesOptions = {
+  /** * ***Whether overriding keys must exist in the base type `T`.***
+   *
+   * - If `true`, all keys of `U` must exist in `T`.
+   * - If `false`, additional keys from `U` are allowed and will be added
+   *   to the resulting type.
+   *
+   * @default true
+   */
+  strictKeys: boolean;
+  /** * ***Options forwarded to {@link Prettify | `Prettify`}.***
+   *
+   * Controls how the resulting type is normalized.
+   */
+  prettifyOptions?: PrettifyOptions;
+};
+type StrictOverrideConstraint<T, U, Strict extends boolean> = Strict extends true ? { [K in keyof U]: K extends keyof T ? unknown : never } : unknown;
+type ResolvePrettifyOptions<O extends OverrideTypesOptions> = O["prettifyOptions"] extends PrettifyOptions ? O["prettifyOptions"] : DefaultPrettifyOptions;
+/** --------------------------------------------------
+ * * ***Utility Type: `OverrideTypes`.***
+ * --------------------------------------------------
+ * Overrides properties in type `T` using properties from type `U`.
+ *
+ * Keys that exist in both `T` and `U` will take the value type from `U`,
+ * while all other properties from `T` remain unchanged.
+ *
+ * The behavior can be configured using {@link OverrideTypesOptions}.
+ *
+ * @template T - The base object type whose properties will be overridden.
+ * @template U - The object type providing overriding property types.
+ * @template Options - Configuration controlling override behavior.
+ *
+ * @remarks
+ * - When `Options["strictKeys"]` is `true` (default), all keys in `U`
+ *   **must already exist in `T`**.
+ * - When `strictKeys` is `false`, `U` may introduce **additional keys**
+ *   which will be added to the resulting type.
+ * - The resulting type is normalized using {@link Prettify}.
+ *
+ * @example
+ * // Basic override
+ * type A = { a: number; b: string };
+ * type B = { b: boolean };
+ * type C = OverrideTypes<A, B>;
+ * // Result:
+ * // {
+ * //   a: number;
+ * //   b: boolean;
+ * // }
+ *
+ * @example
+ * // Strict key enforcement (default)
+ * type A = { a: number; b: string };
+ * type B = { x: string[]; b: boolean };
+ * // @ts-expect-error
+ * type C = OverrideTypes<A, B>;
+ * // Error: "x" is not assignable to keyof A
+ *
+ * @example
+ * // Allow additional keys
+ * type A = { a: number; b: string };
+ * type B = { x: string[]; b: boolean };
+ * type C = OverrideTypes<A, B, { strictKeys: false }>;
+ * // Result:
+ * // {
+ * //   a: number;
+ * //   b: boolean;
+ * //   x: string[];
+ * // }
+ *
+ * @example
+ * // Custom Prettify options
+ * type A = { a: number; b: string };
+ * type B = { b: boolean };
+ * type C = OverrideTypes<
+ *   A,
+ *   B,
+ *   {
+ *     strictKeys: true;
+ *     prettifyOptions: { skipPrettify: true };
+ *   }
+ * >;
+ */
+type OverrideTypes<T, U extends StrictOverrideConstraint<T, U, Options["strictKeys"]>, Options extends OverrideTypesOptions = {
+  strictKeys: true;
+  prettifyOptions: DefaultPrettifyOptions;
+}> = Options["strictKeys"] extends true ? Exclude<keyof U, keyof T> extends never ? Prettify<OmitStrict<T, Extract<keyof U, keyof T>, ResolvePrettifyOptions<Options>> & U, ResolvePrettifyOptions<Options>> : never : Prettify<OmitStrict<T, Extract<keyof U, keyof T>, ResolvePrettifyOptions<Options>> & { [K in keyof U]: U[K] }, ResolvePrettifyOptions<Options>>;
+/** --------------------------------------------------
+ * * ***Utility Type: `PickStrict`.***
+ * --------------------------------------------------
+ * **Utility type that behaves exactly like the native `Pick<T, K>`,
+ * but can help with type inference and IDE autocomplete in stricter scenarios.**
+ * @template T - The base object type.
+ * @template K - The keys from `T` to be picked.
+ * @example
+ * ```ts
+ * type A = { a: number; b: string; c: boolean };
+ * type B = PickStrict<A, 'a' | 'c'>;
+ * // ➔ { a: number; c: boolean }
+ * ```
+ */
+type PickStrict<T, K extends keyof T> = Pick<T, K>;
+interface CustomPromiseLike<OnSuccess, OnError> {
+  /**
+   * Attaches callbacks for the resolution and/or rejection of the Promise.
+   * @param onfulfilled The callback to execute when the Promise is resolved.
+   * @param onrejected The callback to execute when the Promise is rejected.
+   * @returns A Promise for the completion of which ever callback is executed.
+   */
+  then<TResult1 = OnSuccess, TResult2 = never>(onfulfilled?: ((value: OnSuccess) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: OnError) => TResult2 | PromiseLike<TResult2>) | null | undefined): CustomPromiseType<TResult1 | TResult2, OnError>;
+  /**
+   * Attaches a callback for only the rejection of the Promise.
+   * @param onrejected The callback to execute when the Promise is rejected.
+   * @returns A Promise for the completion of the callback.
+   */
+  catch<TResult = never>(onrejected?: ((reason: OnError) => TResult | PromiseLike<TResult>) | null | undefined): CustomPromiseType<OnSuccess | TResult, OnError>;
+  /**
+   * Registers a callback to be invoked **exactly once** when the
+   * promise settles, with access to both the resolved value and
+   * the rejection reason.
+   *
+   * If the promise is already settled when `finish` is called,
+   * the callback executes immediately on the same tick.
+   *
+   * @param cb Callback receiving the final `(value, error)`.
+   * @returns `this` for fluent chaining.
+   */
+  finish(cb: (value: OnSuccess | undefined, error: OnError | undefined) => void): CustomPromiseType<OnSuccess, OnError>;
+}
+/** --------------------------------------------------
+ * * ***Utility Type: `CustomPromiseType`.***
+ * --------------------------------------------------
+ * **Extends the native `Promise` type to provide explicit typing
+ * for both the resolved (`onSuccess`) and rejected (`onError`) values,
+ * plus an optional `finish` hook.**
+ * - **Behavior:**
+ *      - ✅ **Strongly types** `success`, `error`, and `finish` handlers.
+ *      - ⚙️ `finish` runs exactly once after the promise settles (similar to `finish`).
+ * @template OnSuccess - The type of the fulfilled value.
+ * @template OnError   - The type of the rejection reason, defaults to `unknown`.
+ * @example
+ * ```ts
+ * import type { CustomPromiseType } from "@rzl-zone/ts-types-plus";
+ * import { CustomPromise } from "@rzl-zone/utils-js/promises";
+ *
+ * const fetchUser = (): CustomPromiseType<User, ApiError> =>
+ *   new CustomsPromise<User, ApiError>((resolve, reject) => {
+ *      apiCall().then(resolve).catch(reject);
+ *   });
+ *
+ * fetchUser()
+ *   .then(user => console.log(user))
+ *   .catch(err => console.error(err))
+ *   .finish((result, error) => {
+ *      console.log("always runs", { result, error });
+ *   });
+ * ```
+ */
+type CustomPromiseType<OnSuccess, OnError = unknown> = CustomPromiseLike<OnSuccess, OnError>;
+/** -------------------------------------------------------
+ * * ***Utility Type: `ReadonlyOnly`.***
+ * -------------------------------------------------------
+ * **Makes the specified keys `K` of an object type `T` readonly,
+ * while leaving the other properties mutable.**
+ * @template T - The object type.
+ * @template K - Keys of `T` to make readonly.
+ * @template PrettifyOptions - Options controlling whether the resulting
+ * type should be normalized using the `Prettify` helper.
+ * @example
+ * ```ts
+ * type T0 = ReadonlyOnly<{ a: string; b: number }, 'a'>;
+ * // ➔ { readonly a: string; b: number }
+ *
+ * type T1 = ReadonlyOnly<{ x: boolean; y: number; z: string }, 'y' | 'z'>;
+ * // ➔ { x: boolean; readonly y: number; readonly z: string }
+ * ```
+ */
+export { OverrideTypes as A, NonPlainObject as C, NumberRangeUnion as D, Nullish as E, Stringify as F, Trim as I, TypedArray as L, PickStrict as M, Prettify as N, OmitStrict as O, RemoveEmptyArrayElements as P, WebApiObjects as R, Nilable as S, NullToUndefined as T, IsNever as _, CharAt as a, KeepNull as b, ExtractStrict as c, IfNonEmptyArray as d, IfNotExtends as f, IsEmptyString as g, IsArray as h, AnyString as i, ParseNumber as j, OrArr as k, FixNeverArrayRecursive as l, IsAny as m, AndArr as n, CustomPromiseType as o, IntlObjects as p, AnyFunction as r, Extends as s, AnObjectNonArray as t, IfExtends as u, IsPositive as v, NormalizeEmptyArraysRecursive as w, KeepUndef as x, IsStringLiteral as y };