@rzl-zone/build-tools 0.0.5

package/dist/extra-CxDwtQEy.d.cts

@@ -0,0 +1,994 @@
+/*!
+* ========================================================================
+*  @rzl-zone/build-tools
+* ------------------------------------------------------------------------
+*  Version: `0.0.5`
+*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
+* ========================================================================
+*/
+
+/** -------------------------------------------------------
+* * ***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: `Arrayable`.***
+* -------------------------------------------------------
+* **Useful when a function or API accepts **either one item or multiple items**.**
+* - **Represents a type that can be either:**
+*      - a single value of type `T`, or an array of values of type `T`.
+* @template T - The element type.
+* @example
+* ```ts
+* function toArray<T>(input: Arrayable<T>): T[] {
+*   return Array.isArray(input) ? input : [input];
+* }
+*
+* type A = Arrayable<string>;
+* // ➔ string | string[]
+*
+* const a: A = "foo";
+* const b: A = ["foo", "bar"];
+* ```
+*/
+type Arrayable<T> = T | Array<T>;
+/** -------------------------------------------------------
+* * ***Utility Type: `MutableArray`.***
+* -------------------------------------------------------
+* **Recursively creates a **mutable version** of a readonly array, tuple, or object type.**
+* @description
+* By default, TypeScript infers tuple/array literals as `readonly` (especially with `as const`).
+* This utility removes the `readonly` modifier from all elements recursively,
+* turning a readonly tuple, array, or object into a mutable one.
+* - **Behavior:**
+*      - Optionally, if `Widen` is `true`, literal types (`1`, `'foo'`, `true`) are widened to
+*        their primitive equivalents (`number`, `string`, `boolean`) for easier assignment.
+* @template T - The readonly array, tuple, or object type to make mutable.
+* @template Widen - Whether to widen literal primitive types to their base types (default: `false`).
+* @example
+* ```ts
+* type A = readonly [1, 2, 3];
+* type B = MutableArray<A>;
+* // ➔ [1, 2, 3]
+*
+* const x: A = [1, 2, 3] as const;
+* // x[0] = 9; // ❌ Error: read-only
+*
+* const y: MutableArray<B,true> = [1, 2, 3];
+* y[0] = 9; // ✅ Allowed
+*
+* // Recursive example with objects
+* type Obj = readonly [{ a: 1, b: readonly [2] }];
+* type MutableObj = MutableArray<Obj, true>;
+* // ➔ [{ a: number; b: [number]; }]
+* ```
+*/
+/** -------------------------------------------------------
+* * ***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)
+* ```
+*/
+/** --------------------------------------------------
+* * ***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: `NodeBuiltins`.***
+* --------------------------------------------------
+* **Represents Node.js built-in core objects.**
+* @description
+* Includes commonly used Node.js core classes/objects that are not plain objects.
+* - **Examples:**
+*      - `Buffer`.
+*      - `EventEmitter`.
+*      - `Stream`.
+*      - `URL`.
+*      - `process`.
+* - ❌ Excludes plain objects (`{}`) and primitives.
+* - ⚠️ Note:
+*      - This is **not exhaustive** because Node.js has
+*        many built-in modules, but it covers the main
+*        runtime objects often encountered.
+*/
+type NodeBuiltins = Buffer | NodeJS.EventEmitter | NodeJS.ReadableStream | NodeJS.WritableStream | 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: `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: `NonUndefined`.***
+* -------------------------------------------------------
+* **Remove `undefined` from the given type `T`.**
+* @template T - The type to filter.
+* @example
+* ```ts
+* type A = NonUndefined<string | undefined>;
+* // ➔ string
+* type B = NonUndefined<number | null | undefined>;
+* // ➔ number | null
+* type C = NonUndefined<undefined>;
+* // ➔ never
+* ```
+*/
+type NonUndefined<T> = T extends undefined ? never : T;
+/** --------------------------------------------------
+* * ***Utility Type: `KeepNil`.***
+* --------------------------------------------------
+* **Keeps `null` and/or `undefined` in the output type **only if** they
+* exist in the input type `T`, otherwise, resolves to `never`.**
+* @template T - Input type to check for `null` and `undefined`.
+* @example
+* ```ts
+* type A = KeepNil<string | null>;
+* // ➔ null
+* type B = KeepNil<number | undefined>;
+* // ➔ undefined
+* type C = KeepNil<string | null | undefined>;
+* // ➔ null | undefined
+* type D = KeepNil<boolean>;
+* // ➔ never
+* ```
+*/
+/** --------------------------------------------------
+* * ***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: `StrictAwaitable`.***
+* --------------------------------------------------
+* **Represents a value that may be synchronous or a
+* native `Promise`.**
+*
+* Unlike {@link Awaitable | `Awaitable`}, this type **does not accept
+* arbitrary thenables (`PromiseLike`)** and only allows
+* real `Promise` instances.
+*
+* This is sometimes preferred for **tooling APIs or
+* controlled async flows** where supporting generic
+* thenables is unnecessary or undesirable.
+*
+* --------------------------------------------------
+* @template T - The inner value type.
+*
+* @example
+* ```ts
+* function maybeAsync<T>(v: StrictAwaitable<T>): Promise<T> {
+*   return Promise.resolve(v);
+* }
+*
+* maybeAsync(123); // Promise<number>
+* maybeAsync(Promise.resolve("ok")); // Promise<string>
+* ```
+*/
+type StrictAwaitable<T> = T | Promise<T>;
+export { OmitStrict as a, PrettifyOptions as c, NonUndefined as i, StrictAwaitable as l, Arrayable as n, OverrideTypes as o, DefaultPrettifyOptions as r, Prettify as s, AnyString as t };
+//# sourceMappingURL=extra-CxDwtQEy.d.cts.map