full-utils 3.0.7 → 3.0.8

package/dist/index.d.cts

@@ -1,174 +1,5 @@
-/**
- * Parse a human-typed string of function-like arguments into a normalized array of JS values.
- *
- * @summary
- * Splits by **top-level commas** (ignoring commas that appear inside quotes, parentheses,
- * brackets, or braces) and **coerces** each token to a sensible JavaScript type:
- * `null`, `undefined`, booleans, numbers (including `Infinity`/`-Infinity`), strings
- * (with quote stripping and unescaping), and JSON objects/arrays. Tokens that look like
- * a macro or call marker (start with `$` and end with `)`) are returned **as is**.
- *
- * @remarks
- * ### How parsing works
- * 1. **Input normalization**
- *    - Non-string inputs are returned as a single-element array `[value]`.
- *    - Leading/trailing whitespace is trimmed.
- *    - If the entire string is wrapped in square brackets (`[...]`), the brackets are
- *      removed (so the function accepts both `a,b,c` and `[a, b, c]`).
- *    - Empty input (after trimming or after removing `[...]`) yields `[]`.
- *
- * 2. **Tokenization by top-level commas**
- *    - The string is scanned left-to-right.
- *    - The parser tracks nesting **depth** for `()`, `[]`, `{}` and whether it is
- *      currently **inside quotes**. A comma only splits tokens at **depth 0** and
- *      **outside quotes**.
- *
- * 3. **Per-token coercion (in this order)**
- *    - **Macro / call marker**: If a token starts with `$`, contains `(`, and ends
- *      with `)`, it is returned unchanged (e.g., `"$env(PATH)"`).
- *    - **Literals**: `null` → `null`, `undefined` → `undefined`.
- *    - **Booleans**: Using {@link isStrBool} + {@link boolNormalize} (e.g., `"true"`,
- *      `"False"`, `"yes"`, `"0"` depending on your implementation).
- *    - **Numbers**: Using {@link numNormalize}. If the result is finite, it is returned.
- *      Explicit `"Infinity"` and `"-Infinity"` are also supported.
- *    - **Quoted strings**: `'text'` or `"text"` → inner text with escapes processed
- *      (`\\` → `\`, `\'` → `'`, `\"` → `"`).
- *    - **JSON**: If token begins with `{` and ends with `}`, or begins with `[` and
- *      ends with `]`, the function attempts `jsonDecode`. On failure, the raw string
- *      is returned.
- *    - **Fallback**: Raw token as string.
- *
- * ### Escaping inside quotes
- * - Backslash escaping is supported while inside quotes:
- *   - `\\` for a literal backslash
- *   - `\"` inside double quotes
- *   - `\'` inside single quotes
- *
- * ### Non-throwing behavior
- * - The function aims to be **robust** and **non-throwing**. Invalid JSON will be
- *   returned as a plain string rather than crashing.
- *
- * ### Security considerations
- * - The parser **does not** evaluate code; it only returns strings or parsed values.
- *   If you plan to execute anything returned (e.g., tokens starting with `$...`),
- *   do so in a sandbox with explicit allow-lists.
- *
- * ### Limitations
- * - Numerical parsing relies on {@link numNormalize}. Extremely large or high-precision
- *   decimals may still be subject to JavaScript `number` precision limits unless your
- *   `numNormalize` converts to a safer representation.
- * - Only basic backslash escapes are handled in quoted strings (no `\uXXXX` decoding here).
- * - Whitespace outside quotes is trimmed from each token; internal whitespace is preserved.
- *
- * @example
- * // Basic values
- * arrFuncArgs('1, true, "hello"'); // => [1, true, "hello"]
- *
- * @example
- * // Bracket-wrapped list
- * arrFuncArgs('[1, 2, 3]'); // => [1, 2, 3]
- *
- * @example
- * // Nested structures and quoting
- * arrFuncArgs('{"a":1,"b":[2,3]}, "te,xt", (x,y)'); // => [ {a:1,b:[2,3]}, "te,xt", "(x,y)" ]
- *
- * @example
- * // Booleans, null/undefined, and Infinity
- * arrFuncArgs('yes, NO, null, undefined, Infinity, -Infinity');
- * // => [true, false, null, undefined, Infinity, -Infinity]
- *
- * @example
- * // Macro-like token (returned as-is)
- * arrFuncArgs('$env(PATH)'); // => ["$env(PATH)"]
- *
- * @example
- * // Escapes inside quotes
- * arrFuncArgs('"He said: \\"Hi\\"", \'It\\\'s ok\', "\\\\path"');
- * // => ['He said: "Hi"', "It's ok", "\\path"]
- *
- * @example
- * // Empty and whitespace inputs
- * arrFuncArgs('   ');          // => []
- * arrFuncArgs('[]');           // => []
- * arrFuncArgs('[   ]');        // => []
- * arrFuncArgs('  [ a , b ] '); // => ["a", "b"]
- *
- * @param value - Raw string containing comma-separated arguments.
- * If `value` is **not** a string, the function returns `[value]` unchanged.
- *
- * @returns An array of coerced values (`unknown[]`). Each item is one parsed token.
- *
- * @see isStrBool
- * @see boolNormalize
- * @see numNormalize
- * @see jsonDecode
- *
- * @public
- * @since 2.0.0
- */
 declare function arrFuncArgs(value: string): unknown[];
 
-/**
- * Splits an input array into smaller subarrays (portions) of a given fixed size.
- *
- * @summary
- * Returns an array of chunks, where each chunk contains at most `portionLength` elements.
- * The final chunk may contain fewer elements if the input array length is not evenly divisible
- * by `portionLength`.
- *
- * @typeParam T - Type of the elements in the input array.
- *
- * @param arr - The source array to be split. It can be any readonly array (or tuple).
- * @param portionLength - The desired size of each portion. Must be a **positive integer**.
- *
- * @returns A new two-dimensional array (`T[][]`), where each inner array is one portion.
- * If `portionLength` is not a positive integer, an empty array is returned.
- *
- * @remarks
- * - This function is **non-mutating**: the original array is never modified.
- * - If `portionLength` exceeds the array length, the result will be a single chunk
- *   containing the entire array.
- * - If the input array is empty, the result is an empty array.
- * - Uses `Array.prototype.slice()` internally, so the returned chunks are **shallow copies**.
- *
- * ### Performance
- * - Time complexity: **O(n)** — each element is visited exactly once.
- * - Space complexity: **O(n)** — proportional to the total number of elements copied.
- * - For extremely large arrays (millions of elements), prefer a streaming approach
- *   if memory is a concern.
- *
- * ### Edge cases
- * - `portionLength <= 0` → returns `[]`.
- * - `portionLength` is not an integer (e.g. `2.5`, `NaN`) → returns `[]`.
- * - `arr.length === 0` → returns `[]`.
- * - Works correctly with frozen arrays and readonly tuples.
- *
- * @example
- * // Split an array into groups of 3
- * arrSplitBatches([1, 2, 3, 4, 5, 6, 7], 3);
- * // => [[1, 2, 3], [4, 5, 6], [7]]
- *
- * @example
- * // Portion length larger than array
- * arrSplitBatches(['a', 'b'], 5);
- * // => [['a', 'b']]
- *
- * @example
- * // Non-integer or invalid sizes
- * arrSplitBatches([1, 2, 3], 0);   // => []
- * arrSplitBatches([1, 2, 3], -2);  // => []
- * arrSplitBatches([1, 2, 3], NaN); // => []
- *
- * @example
- * // Works with readonly arrays
- * const input = [10, 20, 30, 40] as const;
- * const result = arrSplitBatches(input, 2);
- * // result: [[10, 20], [30, 40]]
- *
- * @category Array
- * @public
- * @since 2.0.0
- */
 declare function arrSplitBatches<T>(arr: readonly T[], portionLength: number): T[][];
 
 type AnyObj = Record<string, any>;
@@ -182,237 +13,12 @@ interface UniqueDeepOptions<T = unknown> {
 }
 declare function arrUniqueDeep<T>(input: T, opts?: UniqueDeepOptions<unknown>): T;
 
-/**
- * Converts any given value into a normalized boolean (`true` / `false`).
- *
- * @summary
- * Performs **loose coercion** of different input types into a `boolean`
- * following predictable rules for numbers, strings, and actual boolean values.
- * Non-recognized values always return `false`.
- *
- * @param value - Any unknown input that should be interpreted as a boolean.
- *
- * @returns The normalized boolean result (`true` or `false`).
- *
- * @remarks
- * This function is designed to **gracefully handle** a wide variety of input forms —
- * including primitive values, numeric types, and user-typed strings (like `"yes"`, `"no"`, `"on"`, `"off"`).
- *
- * ### Conversion Rules (in order of precedence)
- * 1. **Native booleans** → returned as-is.
- *    - `true` → `true`
- *    - `false` → `false`
- *
- * 2. **Positive numbers** → interpreted as `true`.
- *    - `isNumP(value)` check passes (typically `> 0`).
- *    - Examples: `1`, `42`, `3.14` → `true`
- *
- * 3. **Zero or negative numbers** → interpreted as `false`.
- *    - `isNumNZ(value)` check passes (typically `<= 0`).
- *    - Examples: `0`, `-1` → `false`
- *
- * 4. **Truthy strings** → `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive)
- *    - `"TrUe"` → `true`
- *    - `"  YES  "` → `true`
- *
- * 5. **Falsy strings** → `"false"`, `"0"`, `"no"`, `"off"` (case-insensitive)
- *    - `"False"` → `false`
- *    - `" off "` → `false`
- *
- * 6. **Everything else** → `false`
- *    - `null`, `undefined`, `NaN`, empty string, symbols, objects, arrays, etc.
- *
- * ### String Handling
- * - Strings are **trimmed** and **lower-cased** before comparison.
- * - Case and whitespace are ignored.
- * - Empty strings (`""`) return `false`.
- *
- * ### Error Safety
- * - The function **never throws**.
- * - Non-primitive or unexpected types are handled safely and result in `false`.
- *
- * ### Performance
- * - Time complexity: **O(1)**.
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Native booleans
- * boolNormalize(true);            // => true
- * boolNormalize(false);           // => false
- *
- * @example
- * // Numeric values
- * boolNormalize(1);               // => true
- * boolNormalize(0);               // => false
- * boolNormalize(-5);              // => false
- *
- * @example
- * // String values
- * boolNormalize('yes');           // => true
- * boolNormalize('No');            // => false
- * boolNormalize('TRUE');          // => true
- * boolNormalize('false');         // => false
- * boolNormalize('on');            // => true
- * boolNormalize('off');           // => false
- *
- * @example
- * // Mixed and invalid inputs
- * boolNormalize(null);            // => false
- * boolNormalize(undefined);       // => false
- * boolNormalize([]);              // => false
- * boolNormalize({});              // => false
- * boolNormalize('maybe');         // => false
- *
- * @see isBool
- * @see isNumP
- * @see isNumNZ
- * @see isStrFilled
- *
- * @category Conversion
- * @public
- * @since 2.0.0
- */
 declare function boolNormalize(value: unknown): boolean;
 
-/**
- * Waits asynchronously for the specified amount of time.
- *
- * @summary
- * A tiny promise-based delay utility that resolves after `timeout` milliseconds.
- * It wraps `setTimeout` in a `Promise`, making it convenient to use with
- * `async/await` or as part of larger promise chains.
- *
- * @param timeout - The delay duration in **milliseconds** before the promise resolves.
- * @defaultValue 0
- *
- * @returns A `Promise<void | true>` that settles after the given delay.
- *
- * @example
- * // Basic usage: pause for ~500 ms
- * await wait(500);
- * console.log('Half a second later…');
- *
- * @example
- * // Measure elapsed time
- * const started = Date.now();
- * await wait(1200);
- * const elapsed = Date.now() - started; // ~= 1200ms (subject to timer clamping and scheduling)
- *
- * @example
- * // Use inside a retry/backoff loop
- * for (let attempt = 1; attempt <= 5; attempt++) {
- *   try {
- *     await doWork();
- *     break;
- *   } catch (err) {
- *     // exponential backoff between attempts
- *     await wait(2 ** attempt * 100);
- *   }
- * }
- *
- * @example
- * // Parallel delays (resolve when the longest finishes)
- * await Promise.all([wait(100), wait(250), wait(50)]);
- *
- * @remarks
- * - **Timing accuracy:** JavaScript timers are **best-effort** and may be delayed
- *   by event-loop load, CPU throttling, tab being backgrounded, or platform-specific
- *   clamping. Treat `timeout` as a *minimum* delay, not an exact scheduler.
- * - **Negative or non-finite values:** Passing `<= 0`, `NaN`, or a non-finite value
- *   effectively behaves like `0` and resolves on a future macrotask tick.
- * - **Cancellation:** This helper **does not support cancellation**. If you need to
- *   abort a wait, consider a variant that accepts an `AbortSignal` and clears the
- *   timer when aborted.
- * - **Event loop semantics:** `setTimeout(0)` schedules a **macrotask**; it does not
- *   run synchronously. Code after `await wait(0)` will execute on a subsequent turn
- *   of the event loop.
- *
- * Notes:
- * - Suitable for throttling UI interactions, pacing network retries, and writing
- *   deterministic tests (with caution re: flakiness).
- * - Keep delays small in performance-critical code paths; prefer debouncing or
- *   requestAnimationFrame for UI-animation pacing when appropriate.
- *
- * 	Complexity:
- * - Time: **O(1)** (scheduling a single timer)
- * - Space: **O(1)** (a promise and a timer reference)
- *
- * Performance:
- * - The function allocates a single promise and a timer handle.
- * - Timer resolution is platform dependent; Node.js and browsers may clamp very
- *   small delays to a minimum threshold under load.
- *
- * Security:
- * - No I/O, side effects, or data exposure. Purely schedules a future resolution.
- *
- * <b>Returns remarks</b>:
- * The internal promise resolves with the value `true`, but callers typically
- * use `await wait(...)` and ignore the value. If you need a strictly `void`
- * result, you can cast or ignore the resolution value.
- *
- * @category Utilities • Timing
- * @since 1.0.0
- * @see {@link https://developer.mozilla.org/docs/Web/API/setTimeout MDN: setTimeout}
- */
 declare function wait(timeout?: number): Promise<void>;
 
 declare function env(k: any): string | undefined;
 
-/**
- * Represents a human-readable breakdown of a time duration
- * into its fundamental components — **days**, **hours**, **minutes**, and **seconds**.
- *
- * @remarks
- * This interface is used by time utility functions such as
- * {@link dateSecParts} and {@link datePartsSec} to represent durations
- * in a normalized structure that is easy to read, format, or serialize.
- *
- * Each field is an **integer number** representing the whole count of that unit.
- * None of the fields are fractional, and they are expected to follow
- * these conventional bounds when generated by {@link dateSecParts}:
- *
- * ```
- * days    ≥ 0
- * hours   ∈ [0, 23]
- * minutes ∈ [0, 59]
- * seconds ∈ [0, 59]
- * ```
- *
- * However, when constructing manually, these constraints are **not enforced**
- * by TypeScript — it is up to the user or calling function to maintain validity.
- *
- * @example
- * ```ts
- * // Example 1: Typical decomposition
- * const t: TimeParts = { days: 1, hours: 2, minutes: 30, seconds: 45 };
- *
- * // Example 2: Used with utility converters
- * const total = datePartsSec(t);   // -> 95445
- * const back  = dateSecParts(total); // -> same structure again
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Display formatting
- * const p: TimeParts = { days: 0, hours: 5, minutes: 3, seconds: 9 };
- * console.log(`${p.hours}h ${p.minutes}m ${p.seconds}s`);
- * // -> "5h 3m 9s"
- * ```
- *
- * @property days - Whole number of days (24-hour periods).
- * @property hours - Whole number of hours in the remaining day (0–23 typical).
- * @property minutes - Whole number of minutes (0–59 typical).
- * @property seconds - Whole number of seconds (0–59 typical).
- *
- * @see {@link dateSecParts} — converts total seconds into this structure.
- * @see {@link datePartsSec} — converts this structure back into total seconds.
- *
- * @public
- * @category Date & Time
- * @since 2.0.0
- */
 interface TimeParts {
     days: number;
     hours: number;
@@ -420,2845 +26,94 @@ interface TimeParts {
     seconds: number;
 }
 
-/**
- * Floors a given {@link Date} object down to the nearest time interval in minutes.
- *
- * @remarks
- * This utility function is commonly used for time bucketing, grouping logs, or
- * aligning timestamps to fixed intervals (e.g. 5-minute or 15-minute marks).
- *
- * It takes an arbitrary `Date` and returns a **new** `Date` instance (it does not
- * mutate the input) where:
- *
- * - The `minutes` value is floored down to the nearest multiple of `everyMinutes`.
- * - `seconds` and `milliseconds` are reset to `0`.
- * - The hour and day remain unchanged.
- *
- * The step is automatically clamped to the range **1 – 60 minutes** to prevent
- * invalid or nonsensical values.
- *
- * The function allocates a single new `Date` object.
- * It is safe for high-frequency use in real-time systems and event batching.
- *
- * @param everyMinutes - The step interval (in minutes) used for rounding down.
- * Must be a positive finite number.
- * Values below 1 are treated as 1, values above 60 as 60.
- *
- * @param date - The input date to be floored.
- * Defaults to the current time (`new Date()`).
- *
- * @returns A **new** `Date` instance, representing the same hour as the input,
- * but with minutes rounded down to the nearest `everyMinutes` multiple.
- *
- * @example
- * ```ts
- * // Example 1: Floor to the nearest 15-minute mark
- * const d = new Date('2025-10-18T10:43:27');
- * dateFloorMin(15, d);
- * // -> 2025-10-18T10:30:00.000Z
- * ```
- *
- * @example
- * ```ts
- * // Example 2: Using default date (current time)
- * const nowFloored = dateFloorMin(10);
- * // -> e.g. 2025-10-18T09:20:00.000Z
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Clamp behavior
- * dateFloorMin(-5, new Date());  // treated as 1 minute
- * dateFloorMin(999, new Date()); // treated as 60 minutes
- * ```
- *
- * @throws Never throws — invalid step values are automatically normalized.
- *
- * @see {@link Date#setMinutes} for the underlying mutation logic.
- * @see {@link Date#getMinutes} for how minutes are extracted from a Date.
- *
- * @public
- * @category Date & Time
- * @since 2.0.0
- */
 declare function dateFloorMin(everyMinutes?: number, date?: Date): Date;
 
-/**
- * Formats a {@link Date} object into a human-readable timestamp string
- * using the pattern `"YYYY-MM-DD HH:mm:ss"`.
- *
- * @remarks
- * This function is a simple and locale-independent date formatter that always
- * outputs a **24-hour clock** timestamp with leading zeros for all numeric parts.
- *
- * It does **not** depend on the user's locale or time zone settings beyond what
- * is stored in the provided `Date` object. If you pass a `Date` constructed
- * from UTC or local time, the formatted output will reflect that same basis.
- *
- * Each date/time component (month, day, hours, minutes, seconds) is padded to
- * two digits using {@link String.padStart}, ensuring consistent width such as
- * `2025-03-07 09:04:02`.
- *
- * - The format is fixed-width and consistent — ideal for logs, filenames,
- *   and database-friendly timestamps.
- * - The output is **not ISO 8601** (which uses a `'T'` separator and optional
- *   timezone offset).
- *   Example: ISO → `"2025-10-18T10:43:27Z"`
- *   This function → `"2025-10-18 10:43:27"`.
- *
- * @param date - The date to format. Defaults to the **current system time**
- * (`new Date()`).
- *
- * @returns A formatted timestamp string in `"YYYY-MM-DD HH:mm:ss"` form.
- *
- * @example
- * ```ts
- * // Example 1: Specific date
- * const d = new Date('2025-10-18T10:43:27Z');
- * dateStr(d);
- * // -> "2025-10-18 10:43:27"
- * ```
- *
- * @example
- * ```ts
- * // Example 2: Default (current) date
- * dateStr();
- * // -> e.g. "2025-10-18 12:07:55"
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Padding behavior
- * const d = new Date('2025-03-07T09:04:02');
- * dateStr(d);
- * // -> "2025-03-07 09:04:02"
- * ```
- *
- * @throws Never throws.
- *
- * @see {@link Date} for JavaScript’s native date-handling API.
- * @see {@link Intl.DateTimeFormat} for locale-aware formatting if needed.
- *
- * @public
- * @category Date & Time
- * @since 2.0.0
- */
 declare function dateStr(date?: Date): string;
 
-/**
- * Converts a partial {@link TimeParts} structure (days, hours, minutes, seconds)
- * into a total number of **seconds**.
- *
- * @remarks
- * This helper provides a simple way to normalize human-readable time components
- * into a single scalar duration in seconds.
- * It can be useful for:
- * - time-based arithmetic (e.g., adding offsets to timestamps),
- * - scheduling or delay computation,
- * - serializing durations into numeric fields (e.g., databases or APIs).
- *
- * All fields (`days`, `hours`, `minutes`, `seconds`) are **optional**; any missing
- * value defaults to `0`. The calculation uses fixed conversion factors:
- *
- * - 1 day = 86 400 seconds
- * - 1 hour = 3 600 seconds
- * - 1 minute = 60 seconds
- *
- * - Fractional or negative numbers are accepted and processed arithmetically.
- *   Example: `{ minutes: 1.5 }` → `90`; `{ hours: -1 }` → `-3600`.
- * - The function performs no validation; it assumes numeric input.
- *   TypeScript typing (`number`) ensures intended usage.
- *
- * @param parts - A partial object containing any subset of time fields.
- * Missing values default to zero.
- *
- * @returns The total number of seconds represented by the provided time parts.
- *
- * @example
- * ```ts
- * // Example 1: Simple conversion
- * datePartsSec({ hours: 1, minutes: 30 }); // -> 5400
- *
- * // Example 2: Full time span
- * datePartsSec({ days: 2, hours: 3, minutes: 5, seconds: 10 });
- * // -> 183910
- *
- * // Example 3: Partial / missing fields
- * datePartsSec({}); // -> 0
- * datePartsSec({ minutes: 5 }); // -> 300
- * ```
- *
- * @throws Never throws.
- *
- * @see {@link dateSecParts} — the inverse operation that expands seconds back into components.
- *
- * @public
- * @category Date & Time
- * @since 2.0.0
- */
 declare function datePartsSec(parts: TimeParts): number;
 
-/**
- * Decomposes a total number of seconds into discrete time components:
- * **days**, **hours**, **minutes**, and **seconds**.
- *
- * @remarks
- * This is the inverse operation of {@link datePartsSec}.
- * It converts a flat duration (in seconds) into a more human-readable structure
- * suitable for display, logging, or formatting.
- *
- * The function performs integer division using {@link Math.floor} for each component
- * and ensures that the result satisfies:
- *
- * ```
- * 0 <= hours < 24
- * 0 <= minutes < 60
- * 0 <= seconds < 60
- * ```
- *
- * Any fractional part of the input (e.g., `12.75`) is truncated (floored) to the
- * nearest lower whole second.
- * Negative or non-finite inputs are considered invalid and will throw an error.
- *
- * - Uses only a few arithmetic operations and is **O(1)**.
- * - Safe for real-time conversions or high-frequency usage (e.g., monitoring dashboards).
- *
- * @param total - Total duration in seconds.
- * Must be a **finite, non-negative number**.
- *
- * @returns A {@link TimeParts} object with integer fields:
- * - `days`
- * - `hours`
- * - `minutes`
- * - `seconds`
- *
- * @example
- * ```ts
- * // Example 1: Basic conversion
- * dateSecParts(3661);
- * // -> { days: 0, hours: 1, minutes: 1, seconds: 1 }
- * ```
- *
- * @example
- * ```ts
- * // Example 2: Multi-day value
- * dateSecParts(90061);
- * // -> { days: 1, hours: 1, minutes: 1, seconds: 1 }
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Invalid input
- * dateSecParts(-10); // throws Error("Invalid total seconds")
- * dateSecParts(NaN); // throws Error("Invalid total seconds")
- * ```
- *
- * @throws {Error}
- * Thrown when `total` is not a finite, non-negative number.
- *
- * @see {@link datePartsSec} — the complementary function that aggregates components into seconds.
- * @see {@link TimeParts} — the return type describing the breakdown of time.
- *
- * @public
- * @category Date & Time
- * @since 2.0.0
- */
 declare function dateSecParts(total: number): TimeParts;
 
-/**
- * Converts a dotted-decimal IPv4 address string (e.g. `"192.168.0.1"`)
- * into its **32-bit unsigned integer** representation.
- *
- * @remarks
- * This function performs a strict validation of the IPv4 address and encodes
- * each of its four octets into a 32-bit number using **big-endian (network byte order)**.
- *
- * The resulting number is in the range `0..4_294_967_295` (`0xFFFFFFFF`),
- * where:
- *
- * - `"0.0.0.0"` → `0`
- * - `"255.255.255.255"` → `4294967295`
- *
- * This representation is particularly useful for:
- * - performing numeric range comparisons (e.g., IP ranges, CIDR checks);
- * - storing IPv4 values compactly in binary structures or databases;
- * - bitwise operations such as masking and subnet arithmetic.
- *
- * - The conversion uses a {@link DataView} and explicit byte writes
- *   to guarantee consistent big-endian behavior across platforms.
- * - The output number is safe for 32-bit unsigned arithmetic via `>>> 0`.
- * - If you need the inverse operation, see {@link numToIpAddr}.
- *
- * @param ip - The IPv4 address in dotted-quad string form.
- *
- * @returns A 32-bit **unsigned integer** representing the given IPv4 address.
- *
- * @example
- * ```ts
- * // Example 1: Simple conversion
- * ipStrNum("192.168.0.1");
- * // -> 3232235521
- *
- * // Example 2: Edge values
- * ipStrNum("0.0.0.0");       // -> 0
- * ipStrNum("255.255.255.255"); // -> 4294967295
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Invalid input
- * ipStrNum("192.168.1");      // throws Error("Invalid IPv4 address")
- * ipStrNum("256.0.0.1");      // throws Error("Invalid IPv4 address")
- * ipStrNum("abc.def.ghi.jkl"); // throws Error("Invalid IPv4 address")
- * ```
- *
- * @throws {Error}
- * Thrown when:
- * - The input does not contain exactly four parts separated by dots.
- * - Any octet is not an integer between 0 and 255 inclusive.
- *
- * @see {@link numToIpAddr} — converts a 32-bit integer back to an IPv4 string.
- * @see {@link parseIPv4} — similar numeric parser using bitwise operations.
- *
- * @public
- * @category Network & IP
- * @since 2.0.0
- */
 declare function ipStrNum(ip: string): number;
 
-/**
- * Converts a 32-bit unsigned integer (numeric IPv4 representation)
- * back into its dotted-decimal string form (e.g. `"192.168.0.1"`).
- *
- * @remarks
- * This is the inverse of {@link ipStrNum}.
- * It interprets the input number as a **big-endian (network-byte-order)**
- * IPv4 value, extracting each of the four octets and joining them into
- * the standard dotted-quad notation.
- *
- * If the input is not a valid finite number (checked via {@link isNumP}),
- * an empty string `""` is returned instead of throwing an exception.
- *
- * The resulting string always consists of **exactly four decimal octets**
- * separated by dots, with each octet in the range `0–255`.
- *
- * - Internally uses {@link DataView} to ensure consistent big-endian behavior
- *   across all platforms.
- * - The output format is always normalized (no leading zeros, no spaces).
- * - For the forward direction (string → number), see {@link ipStrNum}.
- *
- * @param num - The 32-bit unsigned integer representing an IPv4 address.
- *
- * @returns A dotted-decimal IPv4 string (e.g. `"10.0.0.1"`),
- * or an empty string if the input is invalid.
- *
- * @example
- * ```ts
- * // Example 1: Basic conversion
- * ipNumStr(3232235521);
- * // -> "192.168.0.1"
- *
- * // Example 2: Edge values
- * ipNumStr(0);          // -> "0.0.0.0"
- * ipNumStr(4294967295); // -> "255.255.255.255"
- * ```
- *
- * @example
- * ```ts
- * // Example 3: Invalid inputs
- * ipNumStr(NaN);         // -> ""
- * ipNumStr(Infinity);    // -> ""
- * ipNumStr(-5);          // -> ""
- * ```
- *
- * @throws Never throws; invalid inputs simply return an empty string.
- *
- * @see {@link ipStrNum} — converts dotted IPv4 strings to numeric form.
- * @see {@link parseIPv4} — alternative parser using bitwise arithmetic.
- *
- * @public
- * @category Network & IP
- * @since 2.0.0
- */
 declare function ipNumStr(num: number): string;
 
-/**
- * Configuration options that define password validation rules.
- *
- * This interface allows you to specify various constraints
- * that determine whether a given password is considered valid.
- *
- * @example
- * ```ts
- * const options: PasswordOptions = {
- *   minLength: 8,
- *   maxLength: 32,
- *   requireUppercase: true,
- *   requireLowercase: true,
- *   requireDigit: true,
- *   requireSpecial: true,
- * };
- * ```
- *
- * @remarks
- * You can use these options to build password validation functions,
- * enforce strong password policies, or configure authentication modules.
- *
- * @since 2.0.0
- */
 interface PasswordOptions {
-    /**
-     * Minimum allowed number of characters in the password.
-     *
-     * @defaultValue `0`
-     * @example
-     * ```ts
-     * { minLength: 8 } // password must contain at least 8 characters
-     * ```
-     */
     minLength?: number;
-    /**
-     * Maximum allowed number of characters in the password.
-     *
-     * @defaultValue `Infinity`
-     * @example
-     * ```ts
-     * { maxLength: 32 } // password cannot exceed 32 characters
-     * ```
-     */
     maxLength?: number;
-    /**
-     * Whether the password must contain at least one uppercase Latin letter (A–Z).
-     *
-     * @defaultValue `false`
-     * @example
-     * ```ts
-     * { requireUppercase: true } // 'Password1' - OK 'password1' - BAD
-     * ```
-     */
     requireUppercase?: boolean;
-    /**
-     * Whether the password must contain at least one lowercase Latin letter (a–z).
-     *
-     * @defaultValue `false`
-     * @example
-     * ```ts
-     * { requireLowercase: true } // 'PASSWORD1' - BAD 'Password1' - OK
-     * ```
-     */
     requireLowercase?: boolean;
-    /**
-     * Whether the password must include at least one numeric digit (0–9).
-     *
-     * @defaultValue `false`
-     * @example
-     * ```ts
-     * { requireDigit: true } // 'Password' - BAD 'Password1' - OK
-     * ```
-     */
     requireDigit?: boolean;
-    /**
-     * Whether the password must include at least one special character
-     * (such as `!@#$%^&*()-_=+[]{};:'",.<>/?`).
-     *
-     * @defaultValue `false`
-     * @example
-     * ```ts
-     * { requireSpecial: true } // 'Password1' - BAD 'Password1!' - OK
-     * ```
-     */
     requireSpecial?: boolean;
 }
 
-/**
- * Checks whether a given value is an array.
- *
- * @summary
- * A strongly typed wrapper around {@link Array.isArray}, with an enhanced TypeScript
- * type guard that asserts the value as a **readonly non-empty array** (`readonly [T, ...T[]]`).
- *
- * @typeParam T - The expected element type of the array (defaults to `unknown`).
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is an array (of any kind), otherwise `false`.
- * The return type acts as a **type guard**, allowing TypeScript to infer that
- * `value` is a readonly array of `T` when the function returns `true`.
- *
- * @remarks
- * - Internally uses the native {@link Array.isArray} method.
- * - Works correctly across realms (e.g., iframes, worker contexts, etc.).
- * - The type guard ensures `value` is a **readonly non-empty array**, not just an empty list.
- *   This provides safer downstream access patterns when empty arrays are not expected.
- * - If you need to allow empty arrays, consider changing the type to `readonly T[]`.
- *
- * ### Performance
- * - Time complexity: **O(1)** — constant time native check.
- * - Space complexity: **O(1)**.
- *
- * ### Common pitfalls
- * - `isArr([])` → `true`, even though the static type is `readonly [T, ...T[]]`.
- *   TypeScript does not validate runtime emptiness; you should still check `value.length`.
- * - `isArr('abc')` → `false`
- * - `isArr({ length: 3 })` → `false`
- *
- * ### Examples
- *
- * @example
- * // Basic usage
- * isArr([1, 2, 3]); // => true
- * isArr('hello');    // => false
- * isArr({});         // => false
- *
- * @example
- * // With type inference
- * const val: unknown = [10, 20];
- * if (isArr<number>(val)) {
- *   // TypeScript now knows val: readonly [number, ...number[]]
- *   console.log(val[0]); // OK
- * }
- *
- * @example
- * // With mixed content
- * isArr([true, 'text', 123]); // => true
- *
- * @see Array.isArray
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isArr<T = unknown>(value: unknown): value is readonly [T, ...T[]];
 
-/**
- * Checks whether a value is a **non-empty array**.
- *
- * @summary
- * A strongly-typed type guard that returns `true` only if the input value is an array
- * (via {@link isArr}) and contains at least one element (`length > 0`).
- *
- * Useful for narrowing unknown data to a **readonly non-empty tuple type**
- * (`readonly [T, ...T[]]`), which gives TypeScript safer access guarantees.
- *
- * @typeParam T - Expected element type of the array (defaults to `unknown`).
- *
- * @param value - Any value to test.
- *
- * @returns `true` if `value` is an array with at least one element; otherwise `false`.
- *
- * @remarks
- * ### Type narrowing
- * When this function returns `true`, TypeScript automatically infers that:
- * ```ts
- * value is readonly [T, ...T[]]
- * ```
- *
- * That means inside the `if` block, you can safely access `value[0]`
- * without additional checks.
- *
- * ### Behavior
- * - Delegates the array check to {@link isArr}.
- * - Works with both mutable (`T[]`) and readonly arrays (`readonly T[]`).
- * - Does **not** mutate or clone the array.
- * - Returns `false` for:
- *   - Non-array values (`null`, `undefined`, `object`, `string`, etc.).
- *   - Empty arrays (`[]`).
- *
- * ### Performance
- * - Time complexity: **O(1)** (constant time check).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Basic usage
- * isArrFilled([1, 2, 3]);  // => true
- * isArrFilled([]);          // => false
- *
- * @example
- * // With type inference
- * const maybeNumbers: unknown = [10, 20];
- * if (isArrFilled<number>(maybeNumbers)) {
- *   // value is now typed as: readonly [number, ...number[]]
- *   console.log(maybeNumbers[0]); // OK
- * }
- *
- * @example
- * // Non-array values
- * isArrFilled('abc');       // => false
- * isArrFilled(null);        // => false
- * isArrFilled(undefined);   // => false
- * isArrFilled({ length: 2 }); // => false
- *
- * @see isArr
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isArrFilled<T = unknown>(value: unknown): value is readonly [T, ...T[]];
 
-/**
- * Checks whether a given value is a boolean (`true` or `false`).
- *
- * @summary
- * A strict type guard that returns `true` only if `value` is of type `"boolean"`.
- *
- * This helps safely narrow unknown or mixed-type values in TypeScript code,
- * especially when working with dynamic data sources, JSON, or user input.
- *
- * @param value - Any value to check.
- *
- * @returns `true` if the value is strictly a boolean, otherwise `false`.
- *
- * @remarks
- * - Uses the built-in `typeof` operator (`typeof value === "boolean"`).
- * - Does **not** coerce values — only primitive `true` or `false` are accepted.
- * - Returns `false` for Boolean objects created via `new Boolean()`, because those
- *   are of type `"object"`, not `"boolean"`.
- * - Designed as a **type guard**, so when it returns `true`, TypeScript will infer:
- *   ```ts
- *   value is boolean
- *   ```
- *
- * ### Performance
- * - Time complexity: **O(1)** (constant).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Basic usage
- * isBool(true);        // => true
- * isBool(false);       // => true
- * isBool(0);           // => false
- * isBool('true');      // => false
- *
- * @example
- * // With type narrowing
- * const val: unknown = Math.random() > 0.5 ? true : 'yes';
- * if (isBool(val)) {
- *   // TypeScript now knows val: boolean
- *   console.log(val ? 'OK' : 'NO');
- * }
- *
- * @example
- * // Boolean object is not accepted
- * isBool(new Boolean(true)); // => false
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isBool(value: unknown): value is boolean;
 
 declare function isBoolOrBoolTree(value: unknown): boolean;
 
-/**
- * Checks whether a value represents a **valid JavaScript date**.
- *
- * @summary
- * Returns `true` if the given value is either:
- * - an actual `Date` instance with a valid timestamp, or
- * - a string or number that can be successfully parsed by the JavaScript `Date` constructor.
- *
- * Returns `false` for invalid dates (`Invalid Date`), empty strings, `NaN`, or non-date types.
- *
- * @param value - Any value to test (can be a `Date`, string, number, or other type).
- *
- * @returns `true` if the value can be interpreted as a valid date, otherwise `false`.
- *
- * @remarks
- * ### Validation logic
- * 1. **If `value` is a `Date` instance:**
- *    Checks `!Number.isNaN(value.getTime())` — ensures it’s a real date, not an invalid one.
- *    ```ts
- *    isDate(new Date('invalid')); // false
- *    ```
- *
- * 2. **If `value` is a string or number:**
- *    Attempts to construct a new `Date(value)`.
- *    Returns `true` only if the resulting date’s timestamp is finite (not `NaN`).
- *
- * 3. **Otherwise:**
- *    Returns `false`.
- *
- * ### What counts as "valid"
- * - OK: `"2024-12-31"`, `"2024-12-31T23:59:59Z"`, `1728000000000`, `new Date()`
- * - BAD: `"abc"`, `NaN`, `{}`, `null`, `undefined`, `new Date('invalid')`
- *
- * ### Type safety
- * - This is **not** a strict type guard (it doesn’t narrow to `Date`),
- *   but you can pair it with a cast when `true`:
- *   ```ts
- *   if (isDate(v)) {
- *     const d = new Date(v); // guaranteed valid
- *   }
- *   ```
- *
- * ### Performance
- * - Time complexity: **O(1)**
- *   (`Date` construction and timestamp check are constant-time operations).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Valid Date instances
- * isDate(new Date());                  // => true
- * isDate(new Date('2024-05-01'));      // => true
- *
- * @example
- * // From strings or timestamps
- * isDate('2025-01-01T00:00:00Z');      // => true
- * isDate(1700000000000);               // => true
- * isDate('not-a-date');                // => false
- *
- * @example
- * // Invalid cases
- * isDate({});                          // => false
- * isDate([]);                          // => false
- * isDate('');                          // => false
- * isDate(new Date('invalid'));         // => false
- *
- * @see isStr
- * @see isNum
- * @see Date
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isDate(value: unknown): boolean;
 
-/**
- * Checks whether a given value is a **valid email address**.
- *
- * @summary
- * Validates that the input is a non-empty string and matches a simplified but
- * practical email pattern according to RFC 5322-compatible syntax rules.
- *
- * @param value - Any value to test (string or unknown).
- *
- * @returns `true` if the value is a non-empty string that looks like a valid email,
- * otherwise `false`.
- *
- * @remarks
- * ### Validation process
- * 1. Ensures the input is a **non-empty string** via {@link isStrFilled}.
- * 2. Tests the value against a precompiled **regular expression**:
- *    ```
- *    /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+
- *     @[a-zA-Z0-9]
- *     (?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
- *     (?:\.[a-zA-Z]{2,})+$/
- *    ```
- *    This allows standard ASCII characters in the local part and enforces:
- *    - at least one `@` separator
- *    - valid domain and subdomain segments
- *    - a top-level domain of at least two letters.
- *
- * ### Behavior notes
- * - Returns `false` for empty strings, `null`, `undefined`, or non-string inputs.
- * - Does **not** perform DNS or MX record validation — only syntactic matching.
- * - Intended for lightweight client-side or structural checks.
- * - If you need full compliance with RFC 6531 (Unicode / IDN), normalize the address first.
- *
- * ### Performance
- * - Time complexity: **O(n)** — proportional to input length.
- * - Space complexity: **O(1)**.
- * - The compiled regex is cached and reused for efficiency.
- *
- * ### Examples
- *
- * @example
- * // Valid emails
- * isEmail('user@example.com');           // => true
- * isEmail('john.doe+alias@mail.co.uk');  // => true
- *
- * @example
- * // Invalid formats
- * isEmail('');                           // => false
- * isEmail('user@');                      // => false
- * isEmail('@example.com');               // => false
- * isEmail('user@@example.com');          // => false
- * isEmail('user example@domain.com');    // => false
- *
- * @example
- * // Non-string inputs
- * isEmail(null);                         // => false
- * isEmail(undefined);                    // => false
- * isEmail(12345);                        // => false
- *
- * @see isStrFilled
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isEmail(value: unknown): value is string;
 
-/**
- * Checks whether a value **exists** — i.e. is neither `null` nor `undefined`.
- *
- * @summary
- * A minimal and strongly typed utility that acts as a **type guard**
- * to filter out `null` and `undefined` values in TypeScript.
- * It is especially useful in array filters and conditional checks
- * where you need to ensure a value is "present".
- *
- * @typeParam T - The original type of the tested value.
- *
- * @param value - Any value that may be `null` or `undefined`.
- *
- * @returns `true` if `value` is not `null` and not `undefined`, otherwise `false`.
- *
- * @remarks
- * ### Type narrowing
- * When this function returns `true`, TypeScript automatically infers:
- * ```ts
- * value is T
- * ```
- *
- * That means inside the `if` block (or after using `Array.filter(isExists)`),
- * the compiler knows the value cannot be `null` or `undefined`.
- *
- * ### Behavior
- * - Returns `false` for `null` and `undefined`.
- * - Returns `true` for any other type — including `false`, `0`, `''`, `NaN`, empty arrays, etc.
- * - The check is **strict** (`!==`) — no type coercion occurs.
- *
- * ### Typical use cases
- * - Filtering arrays that may contain `null` or `undefined`.
- * - Guarding optional values before access.
- * - Simplifying type-safe checks in functional chains.
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Basic checks
- * isExists(null);        // => false
- * isExists(undefined);   // => false
- * isExists(0);           // => true
- * isExists('');          // => true
- * isExists(false);       // => true
- *
- * @example
- * // With TypeScript narrowing
- * const val: string | null | undefined = getValue();
- * if (isExists(val)) {
- *   // val is now guaranteed to be a string
- *   console.log(val.toUpperCase());
- * }
- *
- * @example
- * // Filtering nullable arrays
- * const arr = [1, null, 2, undefined, 3];
- * const clean = arr.filter(isExists);
- * // clean: number[]  => [1, 2, 3]
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isExists<T>(value: T | null | undefined): value is T;
 
-/**
- * Checks whether a given value is a **function**.
- *
- * @summary
- * A strict type guard that returns `true` only if `value` is a callable function.
- * It works with regular functions, arrow functions, async functions, class constructors,
- * and built-in functions like `setTimeout`.
- *
- * @typeParam T - The expected function type to narrow to (defaults to the base `Function` type).
- *
- * @param value - Any value to check.
- *
- * @returns `true` if the value is of type `"function"`, otherwise `false`.
- *
- * @remarks
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers that:
- * ```ts
- * value is T
- * ```
- *
- * This allows safe calling of the function or using its specific signature.
- *
- * ### Behavior
- * - Returns `true` for:
- *   - Normal functions: `function test() {}`
- *   - Arrow functions: `() => {}`
- *   - Async functions: `async () => {}`
- *   - Generator functions: `function* gen() {}`
- *   - Class constructors (typeof `MyClass`).
- * - Returns `false` for:
- *   - Non-callable objects or primitives.
- *   - Function-like objects that aren't real functions (e.g., `{ call() {} }`).
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Basic usage
- * isFunc(() => {});           // => true
- * isFunc(function test() {}); // => true
- * isFunc(class A {});         // => true
- * isFunc(123);                // => false
- * isFunc({});                 // => false
- *
- * @example
- * // Type narrowing
- * const fn: unknown = () => 'ok';
- * if (isFunc<() => string>(fn)) {
- *   const result = fn(); // result: string
- * }
- *
- * @example
- * // Class constructors are also "functions"
- * class MyClass {}
- * isFunc(MyClass);            // => true
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isFunc<T extends Function = Function>(value: unknown): value is T;
 
-/**
- * Checks whether a given value is a **valid IPv4 address**.
- *
- * @summary
- * Validates that the input is a string containing four octets (e.g. `"192.168.0.1"`),
- * where each octet is a number between `0` and `255`, separated by dots.
- *
- * @param value - Any value to test (string or unknown).
- *
- * @returns `true` if the value is a syntactically valid IPv4 address, otherwise `false`.
- *
- * @remarks
- * ### Validation steps
- * 1. Ensures the input is a string via {@link isStr}.
- * 2. Trims leading and trailing whitespace.
- * 3. Tests the cleaned string against a strict regular expression for IPv4 format:
- *    ```
- *    /^(25[0-5]|2[0-4]\d|[01]?\d\d?)\.
- *      (25[0-5]|2[0-4]\d|[01]?\d\d?)\.
- *      (25[0-5]|2[0-4]\d|[01]?\d\d?)\.
- *      (25[0-5]|2[0-4]\d|[01]?\d\d?)$/
- *    ```
- *    Each group allows:
- *    - `0–9`, `00–99`, `100–199`, `200–249`, `250–255`
- *
- * ### Behavior notes
- * - Returns `false` for non-strings, empty strings, or malformed IPs.
- * - Does **not** support IPv6 (use a separate validator for that).
- * - Does **not** perform CIDR or subnet validation — only syntax checking.
- * - Leading zeros are allowed (e.g. `"010.000.000.001"` is accepted, as per regex).
- *
- * ### Performance
- * - Time complexity: **O(1)** (fixed regex evaluation).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Valid IPv4 addresses
- * isIpAddr('192.168.0.1');     // => true
- * isIpAddr('8.8.8.8');         // => true
- * isIpAddr('0.0.0.0');         // => true
- * isIpAddr('255.255.255.255'); // => true
- *
- * @example
- * // Invalid IPv4 strings
- * isIpAddr('256.0.0.1');       // => false  (octet > 255)
- * isIpAddr('192.168.0');       // => false  (missing octet)
- * isIpAddr('192.168.0.1.5');   // => false  (too many octets)
- * isIpAddr('192.168.0.A');     // => false  (non-numeric)
- * isIpAddr('192,168,0,1');     // => false  (wrong separator)
- *
- * @example
- * // Non-string inputs
- * isIpAddr(12345);             // => false
- * isIpAddr(null);              // => false
- * isIpAddr(undefined);         // => false
- *
- * @see isStr
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isIpAddr(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a **valid MAC address**.
- *
- * @summary
- * Validates that the input is a string formatted as a standard 6-octet
- * MAC (Media Access Control) address, consisting of 12 hexadecimal digits
- * separated by either colons (`:`) or hyphens (`-`).
- *
- * @param value - Any value to test (typically a string from user input or network data).
- *
- * @returns `true` if the value matches the MAC address pattern, otherwise `false`.
- *
- * @remarks
- * ### Accepted formats
- * - `00:1A:2B:3C:4D:5E`
- * - `00-1A-2B-3C-4D-5E`
- * - Both uppercase and lowercase hexadecimal digits are allowed.
- * - Mixed separators (e.g., `"00:1A-2B:3C-4D:5E"`) are **not** accepted.
- *
- * ### Validation logic
- * 1. Confirms that `value` is a string via {@link isStr}.
- * 2. Uses the following regular expression:
- *    ```
- *    /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/
- *    ```
- *    which enforces:
- *    - Exactly 6 byte segments (`xx:xx:xx:xx:xx:xx` or `xx-xx-xx-xx-xx-xx`)
- *    - Each segment: two hexadecimal digits (`0–9`, `A–F`, `a–f`)
- *    - A consistent separator (`:` or `-`)
- *
- * ### Behavior notes
- * - Returns `false` for empty strings, non-strings, or malformed addresses.
- * - Does **not** support 8-octet EUI-64 or Cisco short 3-octet formats.
- * - Does **not** check for broadcast or multicast address semantics — only syntax.
- *
- * ### Performance
- * - Time complexity: **O(1)** (fixed regex match)
- * - Space complexity: **O(1)** (no allocations beyond regex)
- *
- * ### Examples
- *
- * @example
- * // Valid MAC addresses
- * isMacAddr('00:1A:2B:3C:4D:5E');  // => true
- * isMacAddr('AA-BB-CC-DD-EE-FF');  // => true
- * isMacAddr('ff:ff:ff:ff:ff:ff');  // => true
- *
- * @example
- * // Invalid MAC addresses
- * isMacAddr('00:1A:2B:3C:4D');     // => false   (too short)
- * isMacAddr('00:1A:2B:3C:4D:5E:7F'); // => false (too long)
- * isMacAddr('00:1A:2B:3C:4D:ZZ');  // => false   (invalid hex)
- * isMacAddr('001A.2B3C.4D5E');     // => false   (wrong format)
- * isMacAddr('');                   // => false
- *
- * @example
- * // Non-string values
- * isMacAddr(null);                 // => false
- * isMacAddr(undefined);            // => false
- * isMacAddr(123456);               // => false
- *
- * @see isStr
- * @see isIp
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isMacAddr(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a **finite number**.
- *
- * @summary
- * A strict type guard that returns `true` only if `value` is of type `"number"`
- * and is a finite numeric value (not `NaN`, `Infinity`, or `-Infinity`).
- *
- * @param value - Any value to check.
- *
- * @returns `true` if the value is a finite number, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses the built-in `typeof` operator to ensure the value is a primitive number.
- * - Rejects special non-finite numeric values:
- *   - `NaN`
- *   - `Infinity`
- *   - `-Infinity`
- * - Does **not** coerce strings — `"123"` returns `false`.
- * - Works only with **number primitives**, not `Number` objects (`new Number(5)` returns `false`).
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript automatically infers:
- * ```ts
- * value is number
- * ```
- * allowing you to use numeric operators and arithmetic safely.
- *
- * ### Comparison with related checks
- * | Function       | Accepts                         | Rejects                        |
- * |----------------|---------------------------------|--------------------------------|
- * | `isNum`        | finite numbers only             | `NaN`, `Infinity`, non-numbers |
- * | `isNumP`       | positive finite numbers         | `0`, negatives, `NaN`          |
- * | `isNumNZ`      | zero or negative finite numbers | positives, `NaN`               |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Valid finite numbers
- * isNum(42);           // => true
- * isNum(0);            // => true
- * isNum(-3.14);        // => true
- *
- * @example
- * // Invalid numeric values
- * isNum(NaN);          // => false
- * isNum(Infinity);     // => false
- * isNum(-Infinity);    // => false
- *
- * @example
- * // Non-number inputs
- * isNum('123');        // => false
- * isNum(true);         // => false
- * isNum(null);         // => false
- * isNum(undefined);    // => false
- *
- * @example
- * // TypeScript narrowing
- * const x: unknown = 100;
- * if (isNum(x)) {
- *   console.log(x.toFixed(2)); // OK — x is number
- * }
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNum(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **finite non-integer (floating-point) number**.
- *
- * @summary
- * Returns `true` if the value is a finite number and **has a fractional part**
- * (i.e. not an integer).
- * Acts as a strict type guard for float-like numeric values.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a finite, non-integer number; otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - First verifies that the value is a finite number via {@link isNum}.
- * - Then ensures it is **not** an integer using `!Number.isInteger(value)`.
- * - Rejects all non-numeric, `NaN`, or infinite values.
- *
- * ### Comparison with related checks
- * | Function       | Matches                        | Rejects                            |
- * |----------------|--------------------------------|------------------------------------|
- * | `isNum`        | any finite number              | `NaN`, `Infinity`, `-Infinity`     |
- * | `isNumFloat`   | finite numbers **with fraction** | integers, `NaN`, non-numbers     |
- * | `isNumInt`     | finite **integers** only       | floats, `NaN`, non-numbers         |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Valid floats
- * isNumFloat(3.14);       // => true
- * isNumFloat(-0.001);     // => true
- * isNumFloat(1 / 3);      // => true
- *
- * @example
- * // Integers
- * isNumFloat(0);          // => false
- * isNumFloat(42);         // => false
- * isNumFloat(-7);         // => false
- *
- * @example
- * // Invalid or non-number values
- * isNumFloat(NaN);        // => false
- * isNumFloat(Infinity);   // => false
- * isNumFloat('3.14');     // => false
- * isNumFloat(null);       // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = 12.5;
- * if (isNumFloat(val)) {
- *   const n = val * 2; // val is number
- * }
- *
- * @see isNum
- * @see Number.isInteger
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNumFloat(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **negative finite number**.
- *
- * @summary
- * A strict type guard that returns `true` only if the input is a finite number
- * and its value is **less than 0**.
- * Useful for safely detecting negative numeric values without coercion.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a finite number less than zero, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Relies on {@link isNum} to ensure the value is a finite number (not `NaN`, `Infinity`, etc.).
- * - Then checks `value < 0`.
- * - Returns `false` for zero, positive numbers, and all non-numeric types.
- *
- * ### Comparison with related checks
- * | Function     | Description                            | Condition                   |
- * |--------------|----------------------------------------|-----------------------------|
- * | `isNum`      | Any finite number                      | `Number.isFinite(value)`    |
- * | `isNumP`     | Positive numbers only                  | `value > 0`                 |
- * | `isNumN`     | Negative numbers only                  | `value < 0`                 |
- * | `isNumNZ`    | Negative or zero numbers               | `value <= 0`                |
- * | `isNumFloat` | Finite non-integer (fractional) numbers | `!Number.isInteger(value)` |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Negative numbers
- * isNumN(-1);          // => true
- * isNumN(-3.14);       // => true
- * isNumN(-0.0001);     // => true
- *
- * @example
- * // Non-negative numbers
- * isNumN(0);           // => false
- * isNumN(1);           // => false
- * isNumN(42);          // => false
- *
- * @example
- * // Invalid values
- * isNumN(NaN);         // => false
- * isNumN('-5');        // => false
- * isNumN(null);        // => false
- * isNumN(undefined);   // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = -12;
- * if (isNumN(val)) {
- *   const abs = Math.abs(val); // val is number
- * }
- *
- * @see isNum
- * @see isNumP
- * @see isNumNZ
- * @see isNumFloat
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNumN(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **finite number that is less than or equal to zero**.
- *
- * @summary
- * A strict type guard that returns `true` if the input is a finite number and
- * its value is **negative or zero**.
- * Commonly used to identify non-positive numeric values.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a finite number less than or equal to zero; otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses {@link isNum} to ensure the input is a finite number (rejects `NaN`, `Infinity`, etc.).
- * - Then checks the condition `value <= 0`.
- * - Returns `false` for all positive numbers and non-numeric values.
- *
- * ### Comparison with related checks
- * | Function     | Description                       | Condition      |
- * |--------------|-----------------------------------|----------------|
- * | `isNum`      | Any finite number                 | —              |
- * | `isNumP`     | Positive numbers only             | `value > 0`    |
- * | `isNumN`     | Negative numbers only             | `value < 0`    |
- * | `isNumNZ`    | Negative **or zero** numbers      | `value <= 0`   |
- * | `isNumFloat` | Finite non-integer (fractional)   | `!Number.isInteger(value)` |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Negative and zero values
- * isNumNZ(-1);          // => true
- * isNumNZ(-0.5);        // => true
- * isNumNZ(0);           // => true
- *
- * @example
- * // Positive values
- * isNumNZ(0.0001);      // => false
- * isNumNZ(5);           // => false
- *
- * @example
- * // Invalid or non-numeric inputs
- * isNumNZ('0');         // => false
- * isNumNZ(NaN);         // => false
- * isNumNZ(Infinity);    // => false
- * isNumNZ(null);        // => false
- *
- * @example
- * // Type narrowing
- * const x: unknown = -10;
- * if (isNumNZ(x)) {
- *   console.log(x.toFixed(2)); // x is number
- * }
- *
- * @see isNum
- * @see isNumP
- * @see isNumN
- * @see isNumFloat
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNumNZ(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **positive finite number**.
- *
- * @summary
- * A strict type guard that returns `true` only if the input is a finite number
- * greater than zero (`> 0`).
- * Useful for safely validating numeric values that must be positive — such as
- * counters, IDs, amounts, or dimensions.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a finite positive number, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses {@link isNum} to ensure the input is a finite number (`NaN`, `Infinity`, and `-Infinity` are rejected).
- * - Returns `true` only when `value > 0`.
- * - Returns `false` for zero, negative, or non-numeric values.
- *
- * ### Comparison with related checks
- * | Function     | Description                       | Condition                  |
- * |--------------|-----------------------------------|----------------------------|
- * | `isNum`      | Any finite number                 | —                          |
- * | `isNumP`     | Positive numbers only             | `value > 0`                |
- * | `isNumN`     | Negative numbers only             | `value < 0`                |
- * | `isNumNZ`    | Negative **or zero** numbers      | `value <= 0`               |
- * | `isNumFloat` | Finite non-integer (fractional)   | `!Number.isInteger(value)` |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Positive values
- * isNumP(1);           // => true
- * isNumP(3.14);        // => true
- * isNumP(0.00001);     // => true
- *
- * @example
- * // Zero and negatives
- * isNumP(0);           // => false
- * isNumP(-1);          // => false
- * isNumP(-0.5);        // => false
- *
- * @example
- * // Invalid or non-numeric inputs
- * isNumP('5');         // => false
- * isNumP(NaN);         // => false
- * isNumP(Infinity);    // => false
- * isNumP(null);        // => false
- *
- * @example
- * // Type narrowing
- * const x: unknown = 12;
- * if (isNumP(x)) {
- *   console.log(x.toFixed(1)); // x is number
- * }
- *
- * @see isNum
- * @see isNumN
- * @see isNumNZ
- * @see isNumFloat
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNumP(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **finite number greater than or equal to zero**.
- *
- * @summary
- * A strict type guard that returns `true` if the input is a finite number
- * and its value is **non-negative** (`≥ 0`).
- * Useful for safely validating values such as counters, sizes, durations,
- * and other quantities that cannot be negative.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a finite number greater than or equal to zero; otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses {@link isNum} to ensure the input is a finite number (`NaN`, `Infinity`, `-Infinity` are rejected).
- * - Returns `true` when `value >= 0`.
- * - Returns `false` for negative numbers or non-numeric inputs.
- *
- * ### Comparison with related checks
- * | Function     | Description                      | Condition                  |
- * |--------------|----------------------------------|----------------------------|
- * | `isNum`      | Any finite number                | —                          |
- * | `isNumP`     | Positive numbers only            | `value > 0`                |
- * | `isNumPZ`    | Non-negative numbers (`≥ 0`)     | `value >= 0`               |
- * | `isNumN`     | Negative numbers only            | `value < 0`                |
- * | `isNumNZ`    | Negative or zero numbers         | `value <= 0`               |
- * | `isNumFloat` | Finite non-integer numbers       | `!Number.isInteger(value)` |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Non-negative numbers
- * isNumPZ(0);           // => true
- * isNumPZ(5);           // => true
- * isNumPZ(3.14);        // => true
- *
- * @example
- * // Negative numbers
- * isNumPZ(-1);          // => false
- * isNumPZ(-0.1);        // => false
- *
- * @example
- * // Invalid or non-numeric inputs
- * isNumPZ('10');        // => false
- * isNumPZ(NaN);         // => false
- * isNumPZ(Infinity);    // => false
- * isNumPZ(null);        // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = 7;
- * if (isNumPZ(val)) {
- *   console.log(Math.sqrt(val)); // val is number
- * }
- *
- * @see isNum
- * @see isNumP
- * @see isNumN
- * @see isNumNZ
- * @see isNumFloat
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isNumPZ(value: unknown): value is number;
 
-/**
- * Checks whether a given value is a **plain object** (i.e. `{}`), not `null`, not an array, and not a class instance.
- *
- * @summary
- * A strict type guard that returns `true` only if the input is a plain object
- * created using an object literal (`{}`) or `Object.create(null)`.
- * Excludes arrays, functions, `null`, and instances of custom classes.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a non-null, non-array plain object; otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * The check ensures all of the following:
- * 1. `typeof value === "object"` — confirms the value is object-like.
- * 2. `value !== null` — excludes `null`, since `typeof null === "object"`.
- * 3. `Object.prototype.toString.call(value) === "[object Object]"` — filters out built-ins like `Map`, `Set`, `Date`, etc.
- * 4. `!Array.isArray(value)` — ensures arrays are excluded.
- *
- * ### What counts as a "plain object"
- * `{}`, `{ a: 1 }`, `Object.create(null)`
- * `[]`, `new Date()`, `new Map()`, `null`, class instances.
- *
- * ### Comparison with related concepts
- * | Example value           | Result | Explanation                      |
- * |--------------------------|---------|----------------------------------|
- * | `{}`                     | true | Plain object                     |
- * | `Object.create(null)`    | true | No prototype but still object     |
- * | `[]`                     | false | Array excluded                   |
- * | `null`                   | false | Explicitly filtered              |
- * | `new Date()`             | false | Built-in class instance          |
- * | `class A {}; new A()`    | false | Custom class instance            |
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is Record<string, unknown>
- * ```
- * allowing safe property access and iteration.
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Plain objects
- * isObj({});                   // => true
- * isObj({ key: 'value' });     // => true
- * isObj(Object.create(null));  // => true
- *
- * @example
- * // Non-objects or special cases
- * isObj(null);                 // => false
- * isObj([]);                   // => false
- * isObj(new Date());           // => false
- * isObj(new Map());            // => false
- * isObj(() => {});             // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = { x: 1 };
- * if (isObj(val)) {
- *   console.log(val.x); // safe: val is Record<string, unknown>
- * }
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isObj(value: unknown): value is Record<string, unknown>;
 
-/**
- * Checks whether a given value is a **non-empty plain object**.
- *
- * @summary
- * A strict type guard that returns `true` only if the input is a plain object
- * (validated by {@link isObj}) **and** has at least one own enumerable key.
- * In other words, it must be an object literal like `{ a: 1 }`, not `{}`.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a plain object with at least one own property; otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses {@link isObj} to verify the value is a plain object (not `null`, not an array, not a class instance).
- * - Calls `Object.keys(value).length > 0` to ensure the object has one or more keys.
- * - Returns `false` for empty objects (`{}`), arrays, functions, `null`, and other non-object types.
- *
- * ### Comparison with related checks
- * | Function         | Description                           | Example              |
- * |------------------|---------------------------------------|----------------------|
- * | `isObj`          | Checks if value is a plain object      | `{}` true / `[]` false |
- * | `isObjFilled`    | Checks if plain object is **non-empty** | `{a: 1}` true / `{}` false |
- * | `isArrFilled`    | Checks if array is non-empty           | `[1]` true / `[]` false |
- * | `isStrFilled`    | Checks if string is non-empty          | `'a'` true / `''` false |
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is Record<string, unknown>
- * ```
- * allowing safe property access and iteration.
- *
- * ### Performance
- * - Time complexity: **O(n)** — proportional to the number of object keys.
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Non-empty plain objects
- * isObjFilled({ a: 1 });        // => true
- * isObjFilled({ key: null });   // => true
- * isObjFilled({ nested: {} });  // => true
- *
- * @example
- * // Empty or invalid objects
- * isObjFilled({});              // => false
- * isObjFilled([]);              // => false
- * isObjFilled(null);            // => false
- * isObjFilled(new Date());      // => false
- *
- * @example
- * // Type narrowing
- * const data: unknown = { x: 5 };
- * if (isObjFilled(data)) {
- *   console.log(Object.keys(data)); // safe
- * }
- *
- * @see isObj
- * @see isArrFilled
- * @see isStrFilled
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isObjFilled(value: unknown): value is Record<string, unknown>;
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 declare function isObjFlat(value: unknown): value is Record<string, Primitive>;
 
-/**
- * Validates whether a string meets configurable **password strength requirements**.
- *
- * @summary
- * A flexible password validation helper that checks for length, uppercase and lowercase letters,
- * digits, and special characters.
- * All rules are configurable through the optional {@link PasswordOptions} parameter.
- *
- * @param value - The value to validate as a password.
- * @param options - Optional validation rules (see {@link PasswordOptions}).
- * Defaults ensure strong password requirements:
- * ```ts
- * {
- *   minLength: 8,
- *   maxLength: 256,
- *   requireUppercase: true,
- *   requireLowercase: true,
- *   requireDigit: true,
- *   requireSpecial: true
- * }
- * ```
- *
- * @returns `true` if the value is a valid string matching all configured requirements, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * 1. Ensures `value` is a string using {@link isStr}.
- * 2. Enforces **length limits** (`minLength` ≤ length ≤ `maxLength`).
- * 3. Optionally checks for:
- *    - Uppercase characters (Latin or Cyrillic): `/[A-ZА-Я]/`
- *    - Lowercase characters (Latin or Cyrillic): `/[a-zа-я]/`
- *    - Digits: `/\d/`
- *    - Special characters: `/[~!?@#$%^&*_\-+()\[\]{}><\\\/|"'.,:;=]/`
- * 4. Returns `true` only if all active checks pass.
- *
- * ### Default rule set (strong password)
- * - At least 8 characters long
- * - Contains uppercase and lowercase letters
- * - Contains at least one digit
- * - Contains at least one special symbol
- * - Not longer than 256 characters
- *
- * ### Example configuration
- * ```ts
- * // Minimal check — only length between 6 and 20
- * isPassword('abcdef', { minLength: 6, maxLength: 20, requireSpecial: false });
- *
- * // Strict corporate policy
- * isPassword('Qwerty#123', { minLength: 10, requireSpecial: true });
- *
- * // Simplified mobile app rule
- * isPassword('myPass1', { requireSpecial: false });
- * ```
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * allowing you to safely treat it as a verified password.
- *
- * ### Performance
- * - Time complexity: **O(n)** (depends on string length and regex scans).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Default strong policy (8+ chars, upper, lower, digit, special)
- * isPassword('Aa1@aaaa');        // => true
- * isPassword('Password123!');    // => true
- * isPassword('qwerty');          // => false (no upper/digit/special)
- *
- * @example
- * // Custom rules
- * isPassword('abc123', {
- *   minLength: 6,
- *   requireUppercase: false,
- *   requireSpecial: false
- * }); // => true
- *
- * @example
- * // Invalid inputs
- * isPassword('');                // => false
- * isPassword(null);              // => false
- * isPassword(undefined);         // => false
- * isPassword(123456);            // => false
- *
- * @see isStr
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isPassword(value: unknown, { minLength, maxLength, requireUppercase, requireLowercase, requireDigit, requireSpecial, }?: PasswordOptions): value is string;
 
-/**
- * Checks whether a given value is a **valid phone number** in a generic international format.
- *
- * @summary
- * A flexible, language-neutral phone number validator that accepts both string and numeric inputs.
- * It supports optional leading `"+"`, allows dashes (`"-"`) as separators, and ensures that the
- * number structure is syntactically valid — not necessarily region-specific.
- *
- * @param value - Any value to test (string or number).
- *
- * @returns `true` if the value represents a valid phone-like number, otherwise `false`.
- *
- * @remarks
- * ### Validation logic
- * 1. **Type check:**
- *    Accepts strings and finite numbers (`isStrFilled` or `isNum` must pass).
- * 2. **Normalization:**
- *    Converts to string and trims whitespace.
- * 3. **Negative or misplaced signs:**
- *    Rejects numbers starting with `"-"`.
- * 4. **Plus sign validation:**
- *    - Only one `+` is allowed.
- *    - If present, it must appear **only at the start**.
- * 5. **Character whitelist:**
- *    The number must match the pattern `/^\+?[0-9-]+$/`,
- *    i.e., only digits, dashes, and an optional leading plus sign.
- * 6. **Length check:**
- *    Must be between **3** and **20** characters (inclusive).
- * 7. **Ending rule:**
- *    The last character must be a digit.
- * 8. **Double-dash check:**
- *    Rejects sequences containing `"--"`.
- *
- * ### Behavior
- * - Accepts: `+1234567890`, `380-67-123-4567`, `79001234567`, `12345`.
- * - Rejects: `"--123"`, `"++123"`, `"12a34"`, `"12 34"`, `"-123"`, `"123-"`.
- * - Not region-specific — does **not** check country codes or local dialing rules.
- * - Designed for structural validation only.
- *
- * ### Comparison
- * | Example              | Valid | Reason                          |
- * |----------------------|:------:|--------------------------------|
- * | `+380671234567`      | true | Proper international format      |
- * | `067-123-4567`       | true | Local format with dashes         |
- * | `123`                | true | Minimum valid length             |
- * | `+12-34-56--78`      | false | Contains `"--"`                 |
- * | `+12A345`            | false | Contains letters                |
- * | `123-`               | false | Ends with non-digit             |
- * | `++38050`            | false | Multiple `"+"` symbols          |
- * | `380+501234`         | false | Misplaced plus                  |
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * even if the original value was numeric — ensuring it can be safely stored or formatted as text.
- *
- * ### Performance
- * - Time complexity: **O(n)** — single regex checks and scans.
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Valid international numbers
- * isPhone('+380671234567');     // => true
- * isPhone('380-67-123-4567');   // => true
- * isPhone(380501234567);        // => true
- *
- * @example
- * // Invalid formats
- * isPhone('--12345');            // => false
- * isPhone('+12+34');             // => false
- * isPhone('12A345');             // => false
- * isPhone('123-');               // => false
- * isPhone('');                   // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = '+14155552671';
- * if (isPhone(val)) {
- *   console.log(val.replace(/\D/g, '')); // safe normalization
- * }
- *
- * @see isStrFilled
- * @see isNum
- * @see formatToPhone
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isPhone(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a **string** primitive.
- *
- * @summary
- * A strict type guard that returns `true` only if the provided value
- * has the JavaScript type `"string"`.
- * Rejects all non-string types, including `String` objects created via `new String()`.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a string primitive, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses the `typeof` operator for a strict type check.
- * - Does **not** coerce values — `"123"` is valid, but `123` is not.
- * - Returns `false` for:
- *   - `String` wrapper objects (`new String('abc')`)
- *   - Non-string types (`number`, `boolean`, `object`, `undefined`, etc.)
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * enabling full access to string methods safely.
- *
- * ### Comparison
- * | Input            | Result | Note                              |
- * |------------------|:------:|-----------------------------------|
- * | `'hello'`        | true  | String literal                     |
- * | `new String('x')`| false | Object wrapper, not primitive      |
- * | `123`            | false | Number                             |
- * | `null`           | false | Not a string                       |
- * | `undefined`      | false | Not a string                       |
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Basic usage
- * isStr('Hello');       // => true
- * isStr('');            // => true
- * isStr(123);           // => false
- * isStr(null);          // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = 'abc';
- * if (isStr(val)) {
- *   console.log(val.toUpperCase()); // safe
- * }
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isStr(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a **string representation of a boolean** — `"true"` or `"false"`.
- *
- * @summary
- * A strict type guard that returns `true` if the input is a non-empty string
- * equal to `"true"` or `"false"` (case-insensitive, with whitespace ignored).
- * Commonly used for validating query parameters, environment variables, or serialized booleans.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a string `"true"` or `"false"` (ignoring case and whitespace), otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * 1. Uses {@link isStrFilled} to ensure the input is a non-empty string.
- * 2. Trims whitespace and converts it to lowercase.
- * 3. Returns `true` only if the normalized string equals `"true"` or `"false"`.
- * 4. Returns `false` for other strings, numbers, or non-string types.
- *
- * ### Typical usage
- * This utility is helpful when you need to:
- * - Parse stringified boolean flags (`'true'`, `'false'`)
- * - Validate configuration or query params
- * - Handle environment variables (`process.env.FEATURE_ENABLED`)
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * and you can safely pass it to a boolean converter (e.g. `formatToBool()`).
- *
- * ### Performance
- * - Time complexity: **O(1)**
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Valid boolean strings
- * isStrBool('true');        // => true
- * isStrBool('FALSE');       // => true
- * isStrBool(' True ');      // => true
- *
- * @example
- * // Invalid strings
- * isStrBool('yes');         // => false
- * isStrBool('0');           // => false
- * isStrBool('');            // => false
- *
- * @example
- * // Non-string inputs
- * isStrBool(true);          // => false
- * isStrBool(1);             // => false
- * isStrBool(null);          // => false
- *
- * @example
- * // Combined with formatToBool()
- * import { formatToBool } from '../bool/formatToBool';
- *
- * const val: unknown = 'False';
- * if (isStrBool(val)) {
- *   console.log(formatToBool(val)); // false
- * }
- *
- * @see isStr
- * @see isStrFilled
- * @see isBool
- * @see formatToBool
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isStrBool(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a **non-empty string** (not just whitespace).
- *
- * @summary
- * A strict type guard that returns `true` only if the value is a string
- * containing at least one non-whitespace character.
- * This is an extended form of {@link isStr} that excludes empty (`""`) and
- * whitespace-only strings (`"   "`).
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a string with visible content, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * - Uses {@link isStr} to confirm the value is a string primitive.
- * - Calls `.trim()` to remove whitespace and checks if the resulting length is greater than zero.
- * - Returns `false` for:
- *   - Empty strings (`""`)
- *   - Whitespace-only strings (`"   "`, `"\n"`, `"\t"`)
- *   - Non-string values (`number`, `boolean`, `object`, `null`, etc.)
- *
- * ### Comparison
- * | Function        | Description                       | Example                   |
- * |-----------------|-----------------------------------|---------------------------|
- * | `isStr`         | Any string (including empty)      | `""` true                 |
- * | `isStrFilled`   | Non-empty trimmed string only     | `"  "` false / `"x"` true |
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * ensuring safe use of string operations.
- *
- * ### Performance
- * - Time complexity: **O(n)** (due to `.trim()`).
- * - Space complexity: **O(1)**.
- *
- * ### Examples
- *
- * @example
- * // Valid strings
- * isStrFilled('hello');     // => true
- * isStrFilled('  text  ');  // => true
- *
- * @example
- * // Empty or whitespace-only
- * isStrFilled('');          // => false
- * isStrFilled('   ');       // => false
- *
- * @example
- * // Non-string values
- * isStrFilled(null);        // => false
- * isStrFilled(123);         // => false
- * isStrFilled(undefined);   // => false
- *
- * @example
- * // Type narrowing
- * const val: unknown = '  value ';
- * if (isStrFilled(val)) {
- *   console.log(val.trim().toUpperCase()); // safe
- * }
- *
- * @see isStr
- * @see isArrFilled
- * @see isObjFilled
- *
- * @category Type Guards
- * @public
- * @since 2.0.0
- */
 declare function isStrFilled(value: unknown): value is string;
 
-/**
- * Checks whether a given value is a string equal to **"asc"** or **"desc"** (case-insensitive).
- *
- * @summary
- * A strict type guard that validates sorting direction strings —
- * `"asc"` (ascending) or `"desc"` (descending).
- * Useful for validating API parameters, SQL sort directives, or UI sort controls.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a non-empty string representing `"asc"` or `"desc"`, otherwise `false`.
- *
- * @remarks
- * ### Behavior
- * 1. Uses {@link isStrFilled} to ensure the value is a non-empty string.
- * 2. Trims whitespace and converts it to lowercase.
- * 3. Returns `true` only if the normalized value equals `"asc"` or `"desc"`.
- * 4. Returns `false` for empty strings, other words, or non-string types.
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is 'asc' | 'desc'
- * ```
- * which is ideal for type-safe sort order handling in functions and APIs.
- *
- * ### Performance
- * - Time complexity: **O(1)** (fixed length checks)
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Valid inputs
- * isStrAscDesc('asc');     // => true
- * isStrAscDesc('DESC');    // => true
- * isStrAscDesc(' Asc ');   // => true
- *
- * @example
- * // Invalid inputs
- * isStrAscDesc('ascending'); // => false
- * isStrAscDesc('');          // => false
- * isStrAscDesc(null);        // => false
- * isStrAscDesc('up');        // => false
- *
- * @example
- * // Type narrowing in use
- * function sortData(order: unknown) {
- *   if (isStrAscDesc(order)) {
- *     console.log(`Sorting in ${order} order`);
- *   } else {
- *     console.log('Invalid sort direction');
- *   }
- * }
- *
- * @see isStr
- * @see isStrFilled
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isStrAscDesc(value: unknown): value is 'asc' | 'desc';
 
-/**
- * Checks whether a given value is a **valid variable-like identifier**.
- *
- * @summary
- * A strict type guard that returns `true` only if the value is a string
- * matching the pattern of a valid **programming variable name**:
- * must start with a letter (`A–Z`, `a–z`) or underscore (`_`),
- * and may contain only letters, digits, or underscores afterward.
- *
- * @param value - Any value to test.
- *
- * @returns `true` if the value is a syntactically valid variable name; otherwise `false`.
- *
- * @remarks
- * ### Validation rule
- * Uses the following regular expression:
- * ```regex
- * /^[A-Za-z_][A-Za-z0-9_]*$/
- * ```
- * This enforces:
- * - **First character:** a Latin letter (`A–Z`, `a–z`) or underscore (`_`)
- * - **Subsequent characters:** any combination of letters, digits, or underscores
- * - **No spaces, symbols, or Unicode letters** are allowed
- *
- * ### Typical use cases
- * - Validating variable names in configuration files or templates
- * - Checking safe property keys for code generation
- * - Ensuring identifiers in scripting or parsing logic
- *
- * ### Behavior
- * - Returns `false` for:
- *   - Strings starting with digits (`"1abc"`)
- *   - Strings containing hyphens or spaces (`"my-var"`, `"user name"`)
- *   - Empty strings or non-string values
- * - Returns `true` for:
- *   - `"name"`, `"_value"`, `"myVar1"`, `"SOME_CONSTANT"`
- *
- * ### Type narrowing
- * When this function returns `true`, TypeScript infers:
- * ```ts
- * value is string
- * ```
- * ensuring safe string usage in contexts like symbol tables or identifier maps.
- *
- * ### Performance
- * - Time complexity: **O(n)** — proportional to string length (regex evaluation)
- * - Space complexity: **O(1)**
- *
- * ### Examples
- *
- * @example
- * // Valid identifiers
- * isVar('name');          // => true
- * isVar('_id');           // => true
- * isVar('myVar1');        // => true
- * isVar('SOME_CONSTANT'); // => true
- *
- * @example
- * // Invalid identifiers
- * isVar('');              // => false
- * isVar('1var');          // => false
- * isVar('user-name');     // => false
- * isVar('my var');        // => false
- * isVar('$value');        // => false
- *
- * @example
- * // Non-string values
- * isVar(null);            // => false
- * isVar(123);             // => false
- * isVar({});              // => false
- *
- * @see isStr
- * @see isStrFilled
- *
- * @category Validation
- * @public
- * @since 2.0.0
- */
 declare function isVar(value: unknown): value is string;
 
 declare function isClass(value: unknown): boolean;
 
-/**
- * Structural JSON-like type used throughout decoding.
- *
- * @remarks
- * This mirrors the standard JSON value domain:
- * `null`, booleans, numbers, strings, arrays of JSON-like values,
- * and plain object maps with string keys pointing to JSON-like values.
- *
- * @public
- * @category JSON
- * @since 2.0.0
- */
-type JSONLike = null | boolean | number | string | JSONLike[] | {
-    [k: string]: JSONLike;
-};
-
-/**
- * Parses a string that may represent JSON, quoted scalars, or plain text.
- *
- * @remarks
- * The parsing order is:
- *
- * 1. Try JSON via {@link jsonParse}. If it works, return the parsed value.
- * 2. If not JSON, check if the string is quoted with `'`, `"` or `` ` ``.
- *    If quoted, return the **unquoted** inner text.
- * 3. If not quoted:
- *    - If `allowString === true`, return the **trimmed** string as-is.
- *    - Otherwise return `null`.
- *
- * This helper is used recursively by {@link jsonDecode} to decode string fields
- * found inside arrays/objects.
- *
- * @param s - Source string.
- * @param allowString - Whether to allow returning raw (unquoted) strings.
- * @returns A JSON-like value, or `null` if the string cannot be interpreted
- *          and `allowString` is `false`.
- *
- * @example
- * ```ts
- * jsonStrLike('{"a":1}', false); // -> { a: 1 }
- * jsonStrLike('"hello"', false); // -> "hello"
- * jsonStrLike('hello', false);   // -> null
- * jsonStrLike('hello', true);    // -> "hello"
- * ```
- *
- * @internal
- */
-declare function jsonStrLike(s: string, allowString: boolean): JSONLike | null;
-
-/**
- * Attempts to parse a string using native {@link JSON.parse}.
- *
- * @remarks
- * Returns a discriminated union with `{ ok: true, value }` on success,
- * or `{ ok: false }` on any parsing error. Exceptions are caught and
- * **never thrown** to callers.
- *
- * @param str - The candidate JSON string.
- * @returns A result object indicating parse success/failure.
- *
- * @example
- * ```ts
- * jsonParse('{"a":1}'); // { ok: true, value: { a: 1 } }
- * jsonParse('not json'); // { ok: false }
- * ```
- *
- * @internal
- */
-declare function jsonParse(str: string): {
-    ok: true;
-    value: JSONLike;
-} | {
-    ok: false;
-};
-
-/**
- * Best-effort decoder that normalizes unknown input into a JSON-like value.
- *
- * @remarks
- * `jsonDecode` accepts many shapes of input and produces a `JSONLike` (or `null`)
- * according to the following rules:
- *
- * - **Primitive passthrough**: `null`, numbers, and booleans are returned as-is.
- * - **Arrays/Objects (filled)**: for each string element/property, we attempt to decode
- *   it via {@link jsonStrLike} (JSON → unquoted string → raw string if `allowString`).
- *   Non-string items are passed through unchanged (cast to `JSONLike`).
- * - **Arrays/Objects (empty)**: returned as-is (they’re valid JSON).
- * - **Standalone strings**: decoded via {@link jsonStrLike}.
- * - **Other values**: return `null`.
- *
- * The function is **non-throwing**; any JSON parse errors are swallowed internally
- * and mapped to either unquoted/raw strings (depending on `allowString`) or `null`.
- *
- * - Uses native `JSON.parse` — safe for untrusted strings provided you do not eval the result.
- * - Does **not** perform schema validation; if you need strict shapes, validate after decoding.
- *
- * @typeParam T - Target type to cast the normalized result to.
- * Defaults to `JSONLike`. Use with care — this is a **type cast**, not a runtime check.
- *
- * @param value - The unknown input to decode (can be primitives, arrays, objects, etc.).
- * @param allowString - If `true`, non-JSON, non-quoted strings are returned as trimmed strings.
- *                      If `false`, such strings decode to `null`.
- *
- * @returns The decoded value cast to `T`, or `null` when it cannot be decoded.
- *
- * @example
- * ```ts
- * // 1) Primitives pass through
- * jsonDecode(42);           // 42
- * jsonDecode(true);         // true
- * jsonDecode(null);         // null
- *
- * // 2) JSON string
- * jsonDecode('{"a":[1,"2"]}'); // { a: [1, "2"] }
- *
- * // 3) Quoted string
- * jsonDecode('"hello"'); // "hello"
- *
- * // 4) Raw string with allowString=false (default)
- * jsonDecode('hello');   // null
- *
- * // 5) Raw string with allowString=true
- * jsonDecode('hello', true); // "hello"
- *
- * // 6) Arrays/objects with string fields get per-field decoding
- * jsonDecode({ a: '{"k":1}', b: 'world' }, true);
- * // -> { a: { k: 1 }, b: "world" }
- * ```
- *
- * @throws Never throws; invalid inputs yield `null` or are passed through per rules above.
- *
- * @public
- * @category JSON
- * @since 2.0.0
- */
-declare function jsonDecode<T = JSONLike>(value: unknown, allowString?: boolean): T | null;
-
-/**
- * Safely serializes a plain object or array into a JSON string.
- *
- * @remarks
- * This helper wraps {@link JSON.stringify} and adds two key safety features:
- *
- * 1. It only serializes **objects** and **arrays**, ignoring all other data types
- *    (numbers, strings, booleans, `null`, `undefined`).
- * 2. It catches all potential `JSON.stringify` errors (such as circular references)
- *    and returns an empty string `""` instead of throwing.
- *
- * The function is thus ideal for safe logging, diagnostics, or best-effort
- * serialization where throwing is undesirable.
- *
- * - The output is always a valid JSON string (or empty string on failure).
- * - Use {@link jsonDecode} to reverse the process and safely parse it back.
- * - BigInt values are **not supported** by `JSON.stringify` — they will trigger
- *   a caught error, resulting in an empty string.
- *
- * @param value - Any value to encode. Only arrays or plain objects will be serialized;
- *                other types return an empty string.
- *
- * @returns The JSON-encoded string representation of the input,
- * or an empty string (`""`) if:
- * - The input is not an array or object.
- * - Serialization fails (e.g., circular reference or BigInt values).
- *
- * @example
- * ```ts
- * // Example 1: Basic usage
- * jsonEncode({ a: 1, b: true });
- * // -> '{"a":1,"b":true}'
- *
- * // Example 2: Arrays
- * jsonEncode([1, 2, 3]);
- * // -> '[1,2,3]'
- *
- * // Example 3: Non-serializable input
- * jsonEncode(123);        // -> ''
- * jsonEncode('hello');    // -> ''
- * jsonEncode(undefined);  // -> ''
- *
- * // Example 4: Circular reference
- * const obj: any = {};
- * obj.self = obj;
- * jsonEncode(obj); // -> '' (fails safely)
- * ```
- *
- * @throws Never throws — all exceptions from `JSON.stringify` are caught internally.
- *
- * @see {@link jsonDecode} — performs the inverse operation with safe parsing and normalization.
- * @see {@link JSON.stringify} — the native method used under the hood.
- *
- * @public
- * @category JSON
- * @since 2.0.0
- */
-declare function jsonEncode(value: unknown): string;
-
-/**
- * Converts an arbitrary numeric input to a JavaScript `number`, optionally rounding
- * it to a fixed number of fractional digits using **half-up** rounding.
- *
- * @remarks
- * This function is a convenience wrapper around your fixed-precision helpers:
- *
- * 1. {@link parseToFixedDecimal} — parses the unknown input (`number`/`string`/etc.)
- *    into an exact, lossless fixed-decimal representation.
- * 2. `roundFixedDecimal` — (invoked only when `round > 1`) rounds that fixed-decimal
- *    value to the requested scale using the **half-up** algorithm.
- * 3. {@link fixedDecimalToNum} — converts the (optionally rounded) fixed-decimal
- *    back to a JavaScript `number`.
- *
- * Because rounding is done in fixed-precision space, you avoid common IEEE-754
- * floating-point artifacts (e.g., `0.1 + 0.2 !== 0.3`) during parsing/rounding.
- * Precision is finally limited only at the last step when the value is converted
- * to a JS `number`.
- *
- * @param value - Any value that represents a number. Typical cases:
- * - `number` (e.g., `12`, `-0.034`, `1e6`)
- * - numeric `string` (e.g., `"42"`, `"-123.456"`)
- * - values that your {@link parseToFixedDecimal} knows how to normalize.
- *
- * If the value cannot be parsed by {@link parseToFixedDecimal}, an error will be thrown from there.
- *
- * @param round - Target number of fractional digits for rounding **in fixed-precision**.
- * - If `round > 1`, the function rounds to exactly `round` digits after the decimal point
- *   using **half-up** (i.e., `.5` rounds away from zero) via `roundFixedDecimal`.
- * - If `round <= 1`, no rounding is applied; the parsed value is passed through as-is.
- *
- * @defaultValue `1` (no rounding; passthrough)
- *
- * @returns The resulting numeric value as a JavaScript `number`.
- *
- * @throws {Error}
- * - Re-throws any parsing/normalization errors from {@link parseToFixedDecimal}.
- * - Re-throws any rounding errors from `roundFixedDecimal` (e.g., invalid scale).
- *
- * @example
- * // No rounding (default `round = 1` → passthrough)
- * numNormalize("123.456");         // => 123.456
- * numNormalize(0.034);             // => 0.034
- *
- * @example
- * // Round to 2 fractional digits (half-up)
- * numNormalize("123.456", 2);      // => 123.46  (because .456 → .46)
- * numNormalize("-1.235", 2);       // => -1.24   (half-up away from zero)
- *
- * @example
- * // Large values: parsed and rounded in fixed precision, then converted to number
- * numNormalize("234893249238948.000003432", 6); // precise rounding in fixed space,
- *                                              // final result as JS number
- *
- * @example
- * // Explicit passthrough (any `round <= 1` behaves the same)
- * numNormalize("1000.555", 1);     // => 1000.555 (no rounding step invoked)
- * numNormalize("1000.555", 0);     // => 1000.555 (still no rounding)
- *
- * @see parseToFixedDecimal
- * @see fixedDecimalToNum
- * @see roundFixedDecimal
- *
- * @category Number Formatting
- * @since 2.0.0
- * @public
- */
 declare function numNormalize(value: unknown, round?: number, throwError?: boolean): number;
 
-/**
- * Converts any given string-like value into a lower-cased, trimmed string.
- *
- * @summary
- * Safely transforms an unknown value into a normalized lowercase string.
- * If the input is not a valid non-empty string, the function returns an empty string (`""`).
- *
- * @param value - Any unknown input to convert to lowercase.
- *
- * @returns A lowercase string, or an empty string if the input is not a valid string.
- *
- * @remarks
- * ### Processing steps
- * 1. **Type check** — ensures the input is a string using {@link isStr}.
- * 2. **Trimming** — removes leading and trailing whitespace via {@link strTrim}.
- * 3. **Validation** — ensures the result is non-empty with {@link isStrFilled}.
- * 4. **Lowercasing** — calls `String.prototype.toLowerCase()` on the trimmed text.
- * 5. If the string is empty or not valid at any step, returns `""`.
- *
- * ### Error safety
- * - The function **never throws**, regardless of input type.
- * - Non-string inputs (numbers, booleans, objects, arrays, `null`, `undefined`) all yield `""`.
- *
- * ### Use cases
- * - Case-insensitive string comparison (normalize both sides with `strLowerCase`).
- * - Normalizing user input before storing or indexing.
- * - Simplifying logic where optional strings may be `null` or empty.
- *
- * ### Performance
- * - Time complexity: **O(n)** (where `n` = string length, due to trimming and lowercasing).
- * - Space complexity: **O(n)** (new string created by normalization).
- *
- * ### Examples
- *
- * @example
- * // Basic strings
- * strLowerCase('HELLO');        // => "hello"
- * strLowerCase('  TEST ');      // => "test"
- *
- * @example
- * // Mixed types
- * strLowerCase(123);            // => ""
- * strLowerCase(true);           // => ""
- * strLowerCase(null);           // => ""
- *
- * @example
- * // Empty or whitespace inputs
- * strLowerCase('   ');          // => ""
- * strLowerCase('');             // => ""
- *
- * @example
- * // Already lowercase
- * strLowerCase('data');         // => "data"
- *
- * @see isStr
- * @see isStrFilled
- * @see strTrim
- *
- * @category String
- * @public
- * @since 2.0.0
- */
 declare function strLowerCase(value?: unknown): string;
 
 declare function strNormalCase(value?: unknown): string;
 
-/**
- * Converts `undefined` or empty (whitespace-only) strings into `null`.
- *
- * @summary
- * Safely normalizes optional values by replacing both `undefined` and blank strings
- * with `null`, while preserving all other values as-is.
- * This helps unify "missing" or "empty" values under a single, database-friendly
- * `null` representation.
- *
- * @param value - Any input value that may be a string, `undefined`, or another type.
- *
- * @returns
- * - `null` if:
- *   - The input is `undefined`, or
- *   - The input is a string that becomes empty after trimming (using {@link strTrim}).
- * - Otherwise returns the original `value`.
- *
- * @remarks
- * ### Processing steps
- * 1. If `value` is `undefined`, returns `null`.
- * 2. If `value` is a string:
- *    - Trims it with {@link strTrim}, removing whitespace and invisible characters.
- *    - If the trimmed result is empty (`''`), returns `null`.
- * 3. Otherwise returns the original value unchanged.
- *
- * ### Behavior notes
- * - Non-string, defined values (like `0`, `false`, `{}`, `[]`) are **not modified**.
- * - The function is **pure** (non-mutating) and safe for use in JSON or ORM normalization.
- * - Often used to prepare form data, REST payloads, or DB entities for consistent nullability.
- *
- * ### Comparison with {@link strUndefined}
- * | Case | `strNull` | `strUndefined` |
- * |------|----------------|----------------------|
- * | `undefined` | `null` | `undefined` |
- * | `''` (empty string) | `null` | `undefined` |
- * | `'text'` | `'text'` | `'text'` |
- * | non-string (e.g. `0`) | `0` | `0` |
- *
- * ### Use cases
- * - Unifying “empty” form values before DB insertion (`''` or `undefined` → `null`)
- * - Sanitizing request bodies before persistence or validation
- * - Preventing inconsistent null/undefined states across backend and frontend layers
- *
- * ### Performance
- * - Time complexity: **O(n)** (depends on string length)
- * - Space complexity: **O(n)** (creates a trimmed string copy)
- *
- * ### Examples
- *
- * @example
- * // Empty and whitespace strings
- * strNull('');          // => null
- * strNull('   ');       // => null
- *
- * @example
- * // Undefined also becomes null
- * strNull(undefined);   // => null
- *
- * @example
- * // Non-empty strings remain as-is
- * strNull('Hello');     // => "Hello"
- * strNull('  Data ');   // => "  Data "
- *
- * @example
- * // Non-string types are preserved
- * strNull(0);           // => 0
- * strNull(false);       // => false
- * strNull([]);          // => []
- * strNull({});          // => {}
- *
- * @see isStr
- * @see strTrim
- * @see strUndefined
- *
- * @category String
- * @public
- * @since 2.0.0
- */
 declare function strNull(value: unknown): {} | null;
 
-/**
- * Normalizes and validates a phone number into international format (`E.164` style).
- *
- * @summary
- * Converts various human-entered phone number formats (with spaces, dashes, parentheses,
- * or local prefixes) into a clean, standardized string beginning with `"+"`
- * and containing 10–15 digits.
- *
- * Returns `null` if the value is not a valid phone number after normalization.
- *
- * @param value - The input value to format. Can be any unknown type; only strings are processed.
- * @param defaultCountry - Optional international prefix to prepend for 10-digit local numbers
- *                         (defaults to `"+7"` — Russia/Kazakhstan).
- *                         Use your target country code (e.g., `"+34"` for Spain, `"+1"` for USA).
- *
- * @returns
- * A normalized phone number in `+XXXXXXXXXX` format if valid, or `null` if the input
- * cannot be interpreted as a valid number.
- *
- * @remarks
- * ### Normalization rules
- * 1. **Input validation:**
- *    If `value` is not a string, returns `null`.
- *
- * 2. **Trimming and cleaning:**
- *    Removes all whitespace, hyphens, parentheses, and dots.
- *    Example:
- *    `" (123) 456-7890 "` → `"1234567890"`.
- *
- * 3. **International formats:**
- *    - `00` prefix (common in Europe) is replaced with `"+"`.
- *      → `"0049123456789"` → `"+49123456789"`.
- *
- * 4. **Local numbers (10 digits):**
- *    Prepends the `defaultCountry` code.
- *    → `"1234567890"` → `"+71234567890"` (default country `+7`).
- *
- * 5. **Generic international numbers (9–15 digits):**
- *    If not starting with `"0"`, adds `"+"` prefix.
- *    → `"380501234567"` → `"+380501234567"`.
- *
- * 6. **Validation check:**
- *    The result must match the pattern `/^\+\d{10,15}$/`
- *    — i.e., plus sign followed by 10–15 digits.
- *    If not, returns `null`.
- *
- * ### Error safety
- * - Never throws — all invalid or unexpected inputs return `null`.
- * - Automatically cleans up common formatting symbols without side effects.
- *
- * ### Performance
- * - Time complexity: **O(n)** (string length).
- * - Space complexity: **O(n)** (new string creation during cleanup).
- *
- * ### Common pitfalls
- * - Numbers starting with `"0"` are **rejected**, since they are ambiguous.
- * - 8-digit local formats are not automatically expanded — use a country-specific parser if needed.
- * - This function performs **basic formatting and validation**, not full ITU-T E.164 compliance.
- *
- * ### Examples
- *
- * @example
- * // International format already valid
- * strPhone('+380501234567');         // => "+380501234567"
- *
- * @example
- * // European "00" prefix
- * strPhone('00442079460729');        // => "+442079460729"
- *
- * @example
- * // Local 10-digit number (default country +7)
- * strPhone('9123456789');            // => "+79123456789"
- *
- * @example
- * // With custom default country
- * strPhone('9876543210', '+34');     // => "+349876543210"
- *
- * @example
- * // Strings with spaces, punctuation, parentheses
- * strPhone('(050) 123-45-67');       // => "+70501234567"
- * strPhone('+1 (202) 555-0183');     // => "+12025550183"
- *
- * @example
- * // Invalid or ambiguous inputs
- * strPhone('');                      // => null
- * strPhone('000123456');             // => null
- * strPhone('abcdefgh');              // => null
- * strPhone(null);                    // => null
- * strPhone(true);                    // => null
- *
- * @see isStr
- * @see strTrim
- *
- * @category String
- * @public
- * @since 2.0.0
- */
 declare function strPhone(value?: unknown, defaultCountry?: string): string | null;
 
-/**
- * Trims, normalizes, and cleans up invisible characters from a string.
- *
- * @summary
- * Safely converts any input into a clean, Unicode-normalized string with all
- * leading/trailing whitespace removed and zero-width characters stripped out.
- *
- * Returns an empty string (`""`) for all non-string inputs.
- *
- * @param value - Any value that may contain text or string-like content.
- *
- * @returns A normalized, trimmed string without invisible Unicode separators.
- * Returns an empty string if `value` is not a string.
- *
- * @remarks
- * ### Processing steps
- * 1. **Type check:**
- *    Uses {@link isStr} to ensure the input is a string.
- *    Non-strings are converted to `""`.
- *
- * 2. **Trimming:**
- *    Removes all leading and trailing whitespace (`String.prototype.trim()`).
- *
- * 3. **Unicode normalization:**
- *    Applies `normalize('NFKC')` — Compatibility Composition — which:
- *    - Converts full-width and compatibility forms into canonical ones.
- *      Example: `"ＡＢＣ"` → `"ABC"`.
- *    - Normalizes composed characters (e.g., `"é"` vs `"é"`).
- *
- * 4. **Invisible character cleanup:**
- *    Removes hidden zero-width Unicode characters commonly introduced by copy/paste:
- *    - `U+200B` ZERO WIDTH SPACE
- *    - `U+200C` ZERO WIDTH NON-JOINER
- *    - `U+200D` ZERO WIDTH JOINER
- *    - `U+FEFF` ZERO WIDTH NO-BREAK SPACE (BOM)
- *
- * 5. **Safe stringification:**
- *    Non-string values are returned as empty string rather than `"undefined"` or `"null"`.
- *
- * ### Benefits
- * - Eliminates subtle text differences that break comparisons or hashing.
- * - Prevents user input issues caused by hidden characters.
- * - Safe to use in both frontend and backend environments.
- *
- * ### Performance
- * - Time complexity: **O(n)** — proportional to the input string length.
- * - Space complexity: **O(n)** — creates a new normalized copy.
- *
- * ### Common use cases
- * - Sanitizing user input before validation or storage.
- * - Cleaning keys, tags, and names from external data sources.
- * - Preparing values for strict equality or hashing.
- *
- * ### Examples
- *
- * @example
- * // Basic trimming
- * strTrim('  Hello  ');            // => "Hello"
- *
- * @example
- * // Removes zero-width characters
- * strTrim('word\u200B');           // => "word"
- *
- * @example
- * // Unicode normalization
- * strTrim('ＡＢＣ');               // => "ABC"
- * strTrim('e\u0301');              // => "é"
- *
- * @example
- * // Non-string inputs
- * strTrim(123);                    // => ""
- * strTrim(null);                   // => ""
- * strTrim(undefined);              // => ""
- * strTrim({ text: 'hi' });         // => ""
- *
- * @see isStr
- * @see String.prototype.normalize
- *
- * @category String
- * @public
- * @since 2.0.0
- */
 declare function strTrim(value: unknown, border?: string): string;
 
-/**
- * Converts `null` or empty (whitespace-only) strings into `undefined`.
- *
- * @summary
- * Normalizes optional values by replacing both `null` and blank strings
- * with `undefined`, while keeping all other values unchanged.
- * This is useful when preparing objects for APIs or serialization,
- * where `undefined` fields are automatically omitted or ignored.
- *
- * @param value - Any value that may be a string, `null`, or another type.
- *
- * @returns
- * - `undefined` if:
- *   - The value is `null`, or
- *   - The value is a string that becomes empty after trimming (via {@link strTrim}).
- * - Otherwise returns the original value.
- *
- * @remarks
- * ### Processing steps
- * 1. If `value` is `null`, return `undefined`.
- * 2. If `value` is a string:
- *    - Trim using {@link strTrim} to remove whitespace and invisible characters.
- *    - If trimmed result is empty, return `undefined`.
- * 3. Otherwise, return the original value unchanged.
- *
- * ### Behavior notes
- * - Non-string, non-null values (`0`, `false`, `{}`, `[]`, etc.) are **not modified**.
- * - The function is **non-mutating** — it never changes the original reference.
- * - It complements {@link strNull}, depending on whether your system
- *   prefers `undefined` (omit field) or `null` (explicit empty value).
- *
- * ### Comparison with {@link strNull}
- * | Case | `strNull` | `strUndefined` |
- * |------|----------------|----------------------|
- * | `null` | `null` | `undefined` |
- * | `undefined` | `null` | `undefined` |
- * | `''` (empty string) | `null` | `undefined` |
- * | `'text'` | `'text'` | `'text'` |
- * | Non-string (e.g. `0`) | `0` | `0` |
- *
- * ### Use cases
- * - Preparing data before sending to REST or GraphQL APIs
- *   (so empty fields are omitted during JSON serialization)
- * - Cleaning form input values before saving or validation
- * - Ensuring `undefined` consistency in optional object properties
- *
- * ### Performance
- * - Time complexity: **O(n)** (depends on string length)
- * - Space complexity: **O(n)** (due to string trimming)
- *
- * ### Examples
- *
- * @example
- * // Empty and whitespace-only strings
- * strUndefined('');        // => undefined
- * strUndefined('   ');     // => undefined
- *
- * @example
- * // null is also normalized
- * strUndefined(null);      // => undefined
- *
- * @example
- * // Non-empty strings remain unchanged
- * strUndefined('Hello');   // => "Hello"
- *
- * @example
- * // Non-string types are preserved
- * strUndefined(0);         // => 0
- * strUndefined(false);     // => false
- * strUndefined([]);        // => []
- * strUndefined({});        // => {}
- *
- * @see isStr
- * @see strTrim
- * @see strNull
- *
- * @category String
- * @public
- * @since 2.0.0
- */
 declare function strUndefined(value: unknown): {} | undefined;
 
 declare const strNormalize: (v: unknown) => unknown;
@@ -3275,4 +130,4 @@ declare function urlObj(value?: string): UrlObj;
 
 declare function urlDecode(input: string): string;
 
-export { type JSONLike, type JsonLike, type PasswordOptions, type TimeParts, type UniqueDeepOptions, arrFuncArgs, arrReplaceTemplate, arrSplitBatches, arrUniqueDeep, boolNormalize, dateFloorMin, datePartsSec, dateSecParts, dateStr, env, ipNumStr, ipStrNum, isArr, isArrFilled, isBool, isBoolOrBoolTree, isClass, isDate, isEmail, isExists, isFunc, isIpAddr, isMacAddr, isNum, isNumFloat, isNumN, isNumNZ, isNumP, isNumPZ, isObj, isObjFilled, isObjFlat, isPassword, isPhone, isStr, isStrAscDesc, isStrBool, isStrFilled, isVar, jsonDecode, jsonEncode, jsonParse, jsonStrLike, numNormalize, strLowerCase, strNormalCase, strNormalize, strNull, strPhone, strTrim, strUndefined, urlDecode, urlObj, wait };
+export { type JsonLike, type PasswordOptions, type TimeParts, type UniqueDeepOptions, arrFuncArgs, arrReplaceTemplate, arrSplitBatches, arrUniqueDeep, boolNormalize, dateFloorMin, datePartsSec, dateSecParts, dateStr, env, ipNumStr, ipStrNum, isArr, isArrFilled, isBool, isBoolOrBoolTree, isClass, isDate, isEmail, isExists, isFunc, isIpAddr, isMacAddr, isNum, isNumFloat, isNumN, isNumNZ, isNumP, isNumPZ, isObj, isObjFilled, isObjFlat, isPassword, isPhone, isStr, isStrAscDesc, isStrBool, isStrFilled, isVar, numNormalize, strLowerCase, strNormalCase, strNormalize, strNull, strPhone, strTrim, strUndefined, urlDecode, urlObj, wait };