full-utils 1.0.11 → 2.0.1

package/dist/index.d.cts

@@ -0,0 +1,4495 @@
+/**
+ * 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 formatToBool} (e.g., `"true"`,
+ *      `"False"`, `"yes"`, `"0"` depending on your implementation).
+ *    - **Numbers**: Using {@link formatToNum}. 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 formatToNum}. Extremely large or high-precision
+ *   decimals may still be subject to JavaScript `number` precision limits unless your
+ *   `formatToNum` 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
+ * formatStrToFuncArgs('1, true, "hello"'); // => [1, true, "hello"]
+ *
+ * @example
+ * // Bracket-wrapped list
+ * formatStrToFuncArgs('[1, 2, 3]'); // => [1, 2, 3]
+ *
+ * @example
+ * // Nested structures and quoting
+ * formatStrToFuncArgs('{"a":1,"b":[2,3]}, "te,xt", (x,y)'); // => [ {a:1,b:[2,3]}, "te,xt", "(x,y)" ]
+ *
+ * @example
+ * // Booleans, null/undefined, and Infinity
+ * formatStrToFuncArgs('yes, NO, null, undefined, Infinity, -Infinity');
+ * // => [true, false, null, undefined, Infinity, -Infinity]
+ *
+ * @example
+ * // Macro-like token (returned as-is)
+ * formatStrToFuncArgs('$env(PATH)'); // => ["$env(PATH)"]
+ *
+ * @example
+ * // Escapes inside quotes
+ * formatStrToFuncArgs('"He said: \\"Hi\\"", \'It\\\'s ok\', "\\\\path"');
+ * // => ['He said: "Hi"', "It's ok", "\\path"]
+ *
+ * @example
+ * // Empty and whitespace inputs
+ * formatStrToFuncArgs('   ');          // => []
+ * formatStrToFuncArgs('[]');           // => []
+ * formatStrToFuncArgs('[   ]');        // => []
+ * formatStrToFuncArgs('  [ 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 formatToBool
+ * @see formatToNum
+ * @see jsonDecode
+ *
+ * @public
+ * @since 2.0.0
+ */
+declare function formatStrToFuncArgs(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
+ * splitArrToPortions([1, 2, 3, 4, 5, 6, 7], 3);
+ * // => [[1, 2, 3], [4, 5, 6], [7]]
+ *
+ * @example
+ * // Portion length larger than array
+ * splitArrToPortions(['a', 'b'], 5);
+ * // => [['a', 'b']]
+ *
+ * @example
+ * // Non-integer or invalid sizes
+ * splitArrToPortions([1, 2, 3], 0);   // => []
+ * splitArrToPortions([1, 2, 3], -2);  // => []
+ * splitArrToPortions([1, 2, 3], NaN); // => []
+ *
+ * @example
+ * // Works with readonly arrays
+ * const input = [10, 20, 30, 40] as const;
+ * const result = splitArrToPortions(input, 2);
+ * // result: [[10, 20], [30, 40]]
+ *
+ * @category Array
+ * @public
+ * @since 2.0.0
+ */
+declare function splitArrToPortions<T>(arr: readonly T[], portionLength: number): 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
+ * formatToBool(true);            // => true
+ * formatToBool(false);           // => false
+ *
+ * @example
+ * // Numeric values
+ * formatToBool(1);               // => true
+ * formatToBool(0);               // => false
+ * formatToBool(-5);              // => false
+ *
+ * @example
+ * // String values
+ * formatToBool('yes');           // => true
+ * formatToBool('No');            // => false
+ * formatToBool('TRUE');          // => true
+ * formatToBool('false');         // => false
+ * formatToBool('on');            // => true
+ * formatToBool('off');           // => false
+ *
+ * @example
+ * // Mixed and invalid inputs
+ * formatToBool(null);            // => false
+ * formatToBool(undefined);       // => false
+ * formatToBool([]);              // => false
+ * formatToBool({});              // => false
+ * formatToBool('maybe');         // => false
+ *
+ * @see isBool
+ * @see isNumP
+ * @see isNumNZ
+ * @see isStrFilled
+ *
+ * @category Conversion
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToBool(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>;
+
+/**
+ * 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 secondsToParts} and {@link partsToSeconds} 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 secondsToParts}:
+ *
+ * ```
+ * 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 = partsToSeconds(t);   // -> 95445
+ * const back  = secondsToParts(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 secondsToParts} — converts total seconds into this structure.
+ * @see {@link partsToSeconds} — converts this structure back into total seconds.
+ *
+ * @public
+ * @category Date & Time
+ * @since 2.0.0
+ */
+interface TimeParts {
+    days: number;
+    hours: number;
+    minutes: number;
+    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');
+ * floorDateToMinutes(15, d);
+ * // -> 2025-10-18T10:30:00.000Z
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 2: Using default date (current time)
+ * const nowFloored = floorDateToMinutes(10);
+ * // -> e.g. 2025-10-18T09:20:00.000Z
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 3: Clamp behavior
+ * floorDateToMinutes(-5, new Date());  // treated as 1 minute
+ * floorDateToMinutes(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 floorDateToMinutes(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');
+ * formatDateToString(d);
+ * // -> "2025-10-18 10:43:27"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 2: Default (current) date
+ * formatDateToString();
+ * // -> e.g. "2025-10-18 12:07:55"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 3: Padding behavior
+ * const d = new Date('2025-03-07T09:04:02');
+ * formatDateToString(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 formatDateToString(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
+ * partsToSeconds({ hours: 1, minutes: 30 }); // -> 5400
+ *
+ * // Example 2: Full time span
+ * partsToSeconds({ days: 2, hours: 3, minutes: 5, seconds: 10 });
+ * // -> 183910
+ *
+ * // Example 3: Partial / missing fields
+ * partsToSeconds({}); // -> 0
+ * partsToSeconds({ minutes: 5 }); // -> 300
+ * ```
+ *
+ * @throws Never throws.
+ *
+ * @see {@link secondsToParts} — the inverse operation that expands seconds back into components.
+ *
+ * @public
+ * @category Date & Time
+ * @since 2.0.0
+ */
+declare function partsToSeconds(parts: {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}): number;
+
+/**
+ * Decomposes a total number of seconds into discrete time components:
+ * **days**, **hours**, **minutes**, and **seconds**.
+ *
+ * @remarks
+ * This is the inverse operation of {@link partsToSeconds}.
+ * 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
+ * secondsToParts(3661);
+ * // -> { days: 0, hours: 1, minutes: 1, seconds: 1 }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 2: Multi-day value
+ * secondsToParts(90061);
+ * // -> { days: 1, hours: 1, minutes: 1, seconds: 1 }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 3: Invalid input
+ * secondsToParts(-10); // throws Error("Invalid total seconds")
+ * secondsToParts(NaN); // throws Error("Invalid total seconds")
+ * ```
+ *
+ * @throws {Error}
+ * Thrown when `total` is not a finite, non-negative number.
+ *
+ * @see {@link partsToSeconds} — 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 secondsToParts(total: number): TimeParts;
+
+/**
+ * Options that control how IPv4 ranges are iterated and materialized.
+ *
+ * @remarks
+ * These options are primarily consumed by {@link rangeIPv4} and {@link rangeIPv4ToArr}.
+ * They let you include/exclude the network and broadcast addresses when the input
+ * is a CIDR block, and limit the maximum number of items when materializing to an array.
+ *
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+interface RangeIPv4Options {
+    /**
+     * Hard cap on the number of elements to materialize into a returned array.
+     *
+     * @remarks
+     * This option is **only** consulted by {@link rangeIPv4ToArr}. It prevents
+     * accidentally allocating huge arrays when the supplied range is very large
+     * (e.g. `0.0.0.0/0` contains 4,294,967,296 addresses).
+     *
+     * If the computed range size exceeds this limit, an error will be thrown.
+     *
+     * @defaultValue `1_000_000`
+     * @example
+     * ```ts
+     * // Will throw because /16 has 65,536 addresses (> 10_000)
+     * rangeIPv4ToArr('10.0.0.0/16', undefined, { limit: 10_000 })
+     * ```
+     */
+    limit?: number;
+    /**
+     * Whether to include the *network* address when iterating a CIDR range.
+     *
+     * @remarks
+     * This flag is only applied when the input is a CIDR (e.g. `"192.168.0.0/24"`).
+     * For non-CIDR, ad-hoc ranges, network/broadcast semantics are not inferred.
+     *
+     * For `/31` and `/32` specifically, there is no distinct network/broadcast
+     * address to exclude, so this flag has no effect.
+     *
+     * @defaultValue `true`
+     * @example
+     * ```ts
+     * // Exclude 192.168.1.0 from a /24 network
+     * [...rangeIPv4('192.168.1.0/24', undefined, { includeNetwork: false })];
+     * ```
+     */
+    includeNetwork?: boolean;
+    /**
+     * Whether to include the *broadcast* address when iterating a CIDR range.
+     *
+     * @remarks
+     * This flag is only applied when the input is a CIDR (e.g. `"192.168.0.0/24"`).
+     * For `/31` and `/32`, there is no broadcast in the traditional sense,
+     * so this flag has no effect.
+     *
+     * @defaultValue `true`
+     * @example
+     * ```ts
+     * // Exclude 192.168.1.255 from a /24 network
+     * [...rangeIPv4('192.168.1.0/24', undefined, { includeBroadcast: false })];
+     * ```
+     */
+    includeBroadcast?: boolean;
+}
+
+/**
+ * Converts a CIDR block into its inclusive start/end IPv4 addresses.
+ *
+ * @remarks
+ * The function validates the CIDR notation and returns a tuple of dotted-quad
+ * IPv4 strings representing the first and last addresses in the block.
+ * For `/0` the range spans the entire IPv4 address space. For `/32` the start
+ * and end are the same single address.
+ *
+ * @param cidr - CIDR notation string, e.g. `"192.168.1.0/24"` or `"10.0.0.1/32"`.
+ * @returns A tuple `[start, end]` in dotted-quad form, or `null` if input is invalid.
+ *
+ * @example
+ * ```ts
+ * cidrToRange('192.168.1.0/24'); // ['192.168.1.0','192.168.1.255']
+ * cidrToRange('10.0.0.1/32');    // ['10.0.0.1','10.0.0.1']
+ * cidrToRange('bad');            // null
+ * ```
+ *
+ * @throws Never throws; returns `null` on invalid input.
+ * @see {@link parseIPv4} to parse an IPv4 string to a 32-bit number.
+ * @see {@link toIPv4} to convert a number back to dotted-quad.
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+declare function cidrToRange(cidr: string): [string, string] | null;
+
+/**
+ * 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
+ * ipAddrToNum("192.168.0.1");
+ * // -> 3232235521
+ *
+ * // Example 2: Edge values
+ * ipAddrToNum("0.0.0.0");       // -> 0
+ * ipAddrToNum("255.255.255.255"); // -> 4294967295
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 3: Invalid input
+ * ipAddrToNum("192.168.1");      // throws Error("Invalid IPv4 address")
+ * ipAddrToNum("256.0.0.1");      // throws Error("Invalid IPv4 address")
+ * ipAddrToNum("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 ipAddrToNum(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 ipAddrToNum}.
+ * 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 ipAddrToNum}.
+ *
+ * @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
+ * numToIpAddr(3232235521);
+ * // -> "192.168.0.1"
+ *
+ * // Example 2: Edge values
+ * numToIpAddr(0);          // -> "0.0.0.0"
+ * numToIpAddr(4294967295); // -> "255.255.255.255"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 3: Invalid inputs
+ * numToIpAddr(NaN);         // -> ""
+ * numToIpAddr(Infinity);    // -> ""
+ * numToIpAddr(-5);          // -> ""
+ * ```
+ *
+ * @throws Never throws; invalid inputs simply return an empty string.
+ *
+ * @see {@link ipAddrToNum} — 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 numToIpAddr(num: number): string;
+
+/**
+ * Parses a dotted-quad IPv4 string (e.g. `"192.168.0.1"`) into a 32-bit unsigned integer.
+ *
+ * @remarks
+ * The returned number is in the range `0..0xFFFFFFFF` and represents the IPv4 address
+ * in big-endian order (i.e. the usual network order).
+ *
+ * The function is strict about format:
+ * - Exactly 4 decimal octets separated by dots.
+ * - Each octet must be `0..255`.
+ * - Only digits are allowed in each octet.
+ *
+ * Leading zeros in octets are permitted (e.g. `"001.002.003.004"`), but you may
+ * choose to forbid them in a custom variant to avoid legacy octal confusions.
+ *
+ * @param ip - Dotted-quad IPv4 string to parse.
+ * @returns The IPv4 as an unsigned 32-bit number, or `null` if invalid.
+ *
+ * @example
+ * ```ts
+ * parseIPv4('127.0.0.1'); // 2130706433
+ * parseIPv4('256.0.0.1'); // null
+ * parseIPv4('1.2.3');     // null
+ * ```
+ *
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+declare function parseIPv4(ip: string): number | null;
+
+declare function rangeIPv4(from: string, to?: string): Generator<string>;
+/**
+ * Creates a lazy generator over an inclusive IPv4 range.
+ *
+ * @remarks
+ * The function supports two input modes:
+ *
+ * 1. **CIDR mode** — when `from` contains a slash and `to` is `undefined`:
+ *    ```ts
+ *    for (const ip of rangeIPv4('192.168.1.0/30')) { ... }
+ *    ```
+ *    In this mode, {@link RangeIPv4Options.includeNetwork} and
+ *    {@link RangeIPv4Options.includeBroadcast} are honored for masks `<= /30`.
+ *    For `/31` and `/32` there is no traditional network/broadcast to exclude.
+ *
+ * 2. **Ad-hoc range mode** — when `from` is an IPv4 and `to` is either an IPv4
+ *    or empty/omitted:
+ *    - If `to` is provided, the range is `[min(from,to) .. max(from,to)]`.
+ *    - If `to` is omitted or blank, the range spans to the end of the `/24`
+ *      block: `A.B.C.D .. A.B.C.255`.
+ *
+ * The iteration is inclusive of both endpoints and is safe around the upper
+ * bound: if the current value is `0xFFFFFFFF`, the generator yields it once and terminates.
+ *
+ * This is a lazy generator: it does **not** allocate the entire range up-front,
+ * making it suitable for very large ranges (iterate/stream/process on the fly).
+ * If you need a materialized array, consider {@link rangeIPv4ToArr} but mind its `limit`.
+ *
+ * @overload
+ * @param from - A CIDR string (e.g. `"10.0.0.0/8"`). If this overload is used, `to` must be `undefined`.
+ *
+ * @overload
+ * @param from - Starting IPv4 address in dotted-quad form.
+ * @param to - Optional ending IPv4 address in dotted-quad form. If omitted or empty, the range ends at `A.B.C.255`.
+ * @param opts - Iteration options.
+ * @returns A generator of dotted-quad IPv4 strings.
+ *
+ * @param from - See overloads.
+ * @param to - See overloads.
+ * @param opts - See overloads.
+ *
+ * @example
+ * ```ts
+ * // 1) CIDR iteration (include all)
+ * [...rangeIPv4('192.168.1.0/30')];
+ * // -> ['192.168.1.0','192.168.1.1','192.168.1.2','192.168.1.3']
+ *
+ * // 2) CIDR iteration without network/broadcast
+ * [...rangeIPv4('192.168.1.0/30', undefined, { includeNetwork: false, includeBroadcast: false })];
+ * // -> ['192.168.1.1','192.168.1.2']
+ *
+ * // 3) Ad-hoc range (explicit end)
+ * [...rangeIPv4('10.0.0.1', '10.0.0.4')];
+ * // -> ['10.0.0.1','10.0.0.2','10.0.0.3','10.0.0.4']
+ *
+ * // 4) Single address ⇒ to end of /24
+ * [...rangeIPv4('10.1.2.3')].at(-1); // '10.1.2.255'
+ * ```
+ *
+ * @throws {Error}
+ * - If `from` is not a valid IPv4 (in non-CIDR mode).
+ * - If `to` is supplied and is not a valid IPv4 (in non-CIDR mode).
+ * - If `from` is not a valid CIDR in CIDR mode.
+ *
+ * @see {@link cidrToRange} to convert a CIDR to `[ start, end ]`.
+ * @see {@link rangeIPv4ToArr} to materialize a range into an array with a safe limit.
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+declare function rangeIPv4(from: string, to: string | undefined, opts?: RangeIPv4Options): Generator<string>;
+
+/**
+ * Materializes an IPv4 range into an array of dotted-quad strings.
+ *
+ * @remarks
+ * This is a convenience wrapper around the lazy {@link rangeIPv4} generator that
+ * collects the yielded addresses into a new array. To protect against excessive
+ * memory usage, a hard {@link RangeIPv4Options.limit | limit} is enforced
+ * (default `1_000_000`). If the range exceeds the limit, an error is thrown and
+ * **no** partial array is returned.
+ *
+ * Prefer using the generator for very large ranges, streaming the results into
+ * your processing pipeline (e.g. writing to a file or socket).
+ *
+ * @param from - See {@link rangeIPv4} for accepted forms (CIDR or IPv4).
+ * @param to - Optional end address (non-CIDR mode). Ignored for CIDR input.
+ * @param opts - Options including the array size `limit`. See {@link RangeIPv4Options}.
+ * @returns A new array with all IPv4 addresses in the range (inclusive).
+ *
+ * @example
+ * ```ts
+ * // Small range OK
+ * rangeIPv4ToArray('192.168.1.10', '192.168.1.13');
+ * // -> ['192.168.1.10','192.168.1.11','192.168.1.12','192.168.1.13']
+ *
+ * // Will throw if exceeds the limit
+ * rangeIPv4ToArray('10.0.0.0/16', undefined, { limit: 10_000 }); // Error
+ * ```
+ *
+ * @throws {Error} If the realized array would exceed `opts.limit`.
+ * @see {@link rangeIPv4} for lazy iteration without materialization.
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+declare function rangeIPv4ToArr(from: string, to?: string, opts?: RangeIPv4Options): string[];
+
+/**
+ * Converts an unsigned 32-bit integer into a dotted-quad IPv4 string.
+ *
+ * @remarks
+ * This is the inverse of {@link parseIPv4}. The function validates that the input
+ * is a finite integer within `0..0xFFFFFFFF` and then formats it as `A.B.C.D`.
+ *
+ * @param n - Unsigned 32-bit IPv4 value (`0..0xFFFFFFFF`).
+ * @returns A dotted-quad string such as `"192.168.0.1"`.
+ *
+ * @example
+ * ```ts
+ * toIPv4(0);            // "0.0.0.0"
+ * toIPv4(0xFFFFFFFF);   // "255.255.255.255"
+ * ```
+ *
+ * @throws {Error} If `n` is not an integer in `0..0xFFFFFFFF`.
+ * @see {@link parseIPv4}
+ * @public
+ * @category IPv4
+ * @since 2.0.0
+ */
+declare function toIPv4(n: 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;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+
+/**
+ * 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 tryParseJSON}. 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
+ * parseStringLike('{"a":1}', false); // -> { a: 1 }
+ * parseStringLike('"hello"', false); // -> "hello"
+ * parseStringLike('hello', false);   // -> null
+ * parseStringLike('hello', true);    // -> "hello"
+ * ```
+ *
+ * @internal
+ */
+declare function parseStringLike(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
+ * tryParseJSON('{"a":1}'); // { ok: true, value: { a: 1 } }
+ * tryParseJSON('not json'); // { ok: false }
+ * ```
+ *
+ * @internal
+ */
+declare function tryParseJSON(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 parseStringLike} (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 parseStringLike}.
+ * - **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;
+
+/**
+ * Represents a **fixed-precision decimal number** using exact integer arithmetic.
+ *
+ * @remarks
+ * JavaScript’s native `number` type uses 64-bit IEEE-754 floating-point representation,
+ * which introduces rounding errors for many decimal values
+ * (for example, `0.1 + 0.2 !== 0.3`).
+ *
+ * `FixedDecimal` provides a lossless, predictable alternative by separating
+ * the number into three explicit components:
+ *
+ * - **`sign`** → numeric sign (`1` for positive values, `-1` for negative ones)
+ * - **`digitsInteger`** → all digits of the number stored as a `BigInt`
+ *   (the decimal point is removed)
+ * - **`scale`** → number of digits that were originally after the decimal point
+ *
+ * Together, these three parts allow precise decimal math, rounding,
+ * and string/number conversions without losing accuracy.
+ *
+ * ---
+ * **Conceptual example**
+ *
+ * The decimal value:
+ * ```
+ * -123.456
+ * ```
+ * would be represented as:
+ * ```ts
+ * {
+ *   sign: -1,
+ *   digitsInteger: 123456n,
+ *   scale: 3
+ * }
+ * ```
+ *
+ * which mathematically equals:
+ * ```
+ * sign × (digitsInteger / 10^scale)
+ * = -1 × (123456 / 10^3)
+ * = -123.456
+ * ```
+ *
+ * ---
+ * **Usage**
+ *
+ * Instances of `FixedDecimal` are typically produced and consumed by utility functions:
+ * - {@link parseToFixedDecimal} — converts arbitrary input (`string`/`number`/`bigint`) to `FixedDecimal`
+ * - {@link roundFixedDecimal} — rounds to a target number of fractional digits
+ * - {@link fixedDecimalToStr} — converts back to a human-readable string
+ * - {@link fixedDecimalToNum} — converts to a JavaScript `number` (with possible precision loss)
+ *
+ * ---
+ * @property sign - Numeric sign of the value.
+ * `1` for positive and zero values, `-1` for negative ones.
+ *
+ * @property digitsInteger - A `BigInt` holding all digits of the number
+ * without any decimal separator.
+ * Example: `"123.45"` → `digitsInteger = 12345n`.
+ *
+ * @property scale - Number of digits that appear after the decimal point
+ * in the original value.
+ * Example: `"123.45"` → `scale = 2`.
+ *
+ * ---
+ * @example
+ * // Example: 0.034 represented as FixedDecimal
+ * const fd: FixedDecimal = {
+ *   sign: 1,
+ *   digitsInteger: 34n,
+ *   scale: 3
+ * };
+ * // mathematically:  1 × (34 / 10³) = 0.034
+ *
+ * @example
+ * // Example: -987000.00 → same magnitude, different scale
+ * const fd2: FixedDecimal = {
+ *   sign: -1,
+ *   digitsInteger: 98700000n,
+ *   scale: 2
+ * };
+ * // -987000.00
+ *
+ * @example
+ * // Zero value representation
+ * const zero: FixedDecimal = {
+ *   sign: 1,
+ *   digitsInteger: 0n,
+ *   scale: 0
+ * };
+ *
+ * @see parseToFixedDecimal
+ * @see roundFixedDecimal
+ * @see fixedDecimalToStr
+ * @see fixedDecimalToNum
+ *
+ * @category Types
+ * @since 2.0.0
+ * @public
+ */
+interface FixedDecimal {
+    /**
+     * The numeric sign of the value:
+     * `1` for positive or zero, `-1` for negative.
+     */
+    sign: 1 | -1;
+    /**
+     * All digits of the number stored as a `BigInt`,
+     * with the decimal point removed.
+     */
+    digitsInteger: bigint;
+    /**
+     * The number of digits that originally appeared
+     * after the decimal point.
+     */
+    scale: number;
+}
+
+/**
+ * Adjusts the **scale** (i.e., number of fractional digits) of a {@link FixedDecimal}
+ * by a given offset without altering its numeric meaning.
+ *
+ * @remarks
+ * A `FixedDecimal` represents a decimal number as:
+ * ```ts
+ * { sign: 1 | -1, digitsInteger: bigint, scale: number }
+ * ```
+ * where `digitsInteger × 10^(-scale)` yields the real value.
+ *
+ * This helper changes the `scale` while keeping the numerical value consistent.
+ * When `scaleDelta > 0`, the function *increases* the scale (adds more fractional
+ * digits of precision) **without changing** `digitsInteger`.
+ * When `scaleDelta < 0`, it *reduces* the scale by multiplying `digitsInteger`
+ * to preserve the same actual numeric value.
+ *
+ * O(1) time and space, except for the BigInt multiplication when `scaleDelta < 0`.
+ *
+ * @param value - The {@link FixedDecimal} to adjust.
+ * Should contain:
+ * - `sign`: either `1` (positive) or `-1` (negative),
+ * - `digitsInteger`: the integer form of all digits without a decimal point,
+ * - `scale`: the number of fractional digits currently represented.
+ *
+ * @param scaleDelta - The number of fractional places to add or remove.
+ * Positive values mean **increase precision** (more digits after the decimal point);
+ * negative values mean **reduce precision**, scaling the integer part accordingly.
+ *
+ * @returns A new {@link FixedDecimal} with the adjusted `scale` and appropriately
+ * modified `digitsInteger` if needed.
+ *
+ * @throws {RangeError} If the operation would cause an invalid scale
+ * (e.g., non-integer `scaleDelta`), though `Math.trunc` is used to normalize inputs.
+ *
+ * @example
+ * ```ts
+ * const num: FixedDecimal = { sign: 1, digitsInteger: 12345n, scale: 2 };
+ * // Represents 123.45
+ *
+ * // Increase scale by +2 → same numeric value but more fractional digits
+ * const up = changeFixedDecimalScale(num, +2);
+ * // up = { sign: 1, digitsInteger: 12345n, scale: 4 } → 1.2345 × 10^2 = 123.45
+ *
+ * // Decrease scale by -2 → multiply digitsInteger to preserve value
+ * const down = changeFixedDecimalScale(num, -2);
+ * // down = { sign: 1, digitsInteger: 1234500n, scale: 0 } → 1234500 × 10^0 = 123.45
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No change when delta = 0
+ * const same = changeFixedDecimalScale(num, 0);
+ * // same === { sign: 1, digitsInteger: 12345n, scale: 2 }
+ * ```
+ *
+ * @since 2.0.0
+ */
+declare function changeFixedDecimalScale(value: FixedDecimal, scaleDelta: number): FixedDecimal;
+
+/**
+ * Converts a number expressed in normalized exponential/scientific notation
+ * (e.g., `"1.23e+5"`, `"4e-7"`, `"0009.500e2"`) into its **sign**, **integer**,
+ * and **fractional** parts as plain decimal digit strings — **without** any
+ * decimal point or leading `+`/`-` characters.
+ *
+ * @remarks
+ * - This function does **not** perform numeric arithmetic; instead it does a
+ *   textual normalization that preserves all significant digits exactly.
+ * - It accepts the `sign` separately so that callers can pre-parse signs from
+ *   inputs like `"-1.23e3"` and pass `sign = -1` with `exponentialString = "1.23e3"`.
+ *   (If you already have a positive string, pass `sign = 1`.)
+ * - The function normalizes the coefficient and exponent first, then uses a
+ *   single regex match to validate the shape:
+ *   - Coefficient: `([0-9]+)(?:\.([0-9]*))?`
+ *   - Exponent: `e([+\-]?[0-9]+)`
+ * - Trailing zeros are added to the **integer** side for positive net exponents,
+ *   while leading zeros are added to the **fractional** side for negative net exponents.
+ * - All returned parts (`integerPart`, `fractionalPart`) contain only ASCII digits.
+ *   The decimal point is **not** returned; you can re-insert it if needed by
+ *   placing it between `integerPart` and `fractionalPart`.
+ *
+ * Time O(n) and space O(n), where n is the number of digits in the coefficient,
+ * due to string concatenation and slicing.
+ *
+ * @param sign - The pre-parsed sign of the number: `1` for positive, `-1` for negative.
+ * @param exponentialString - A string in exponential notation.
+ *   Examples: `"1e3"`, `"1.23e+5"`, `"4.560e-2"`, `"0009.500e2"`.
+ *   The function is case-insensitive for the `'e'` and tolerates leading zeros in the coefficient.
+ *
+ * @returns An object with three properties:
+ * - `sign`: Echo of the input sign (`1` | `-1`).
+ * - `integerPart`: All digits to the left of the decimal point after expansion.
+ * - `fractionalPart`: All digits to the right of the decimal point after expansion.
+ *
+ * @throws {Error} If `exponentialString` cannot be parsed as scientific notation.
+ *
+ * @example
+ * ```ts
+ * // 1.23 × 10^5 = 123000
+ * convertExponentialToParts(1, "1.23e5");
+ * // => { sign: 1, integerPart: "123000", fractionalPart: "" }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 4.5 × 10^-3 = 0.0045
+ * convertExponentialToParts(1, "4.5e-3");
+ * // => { sign: 1, integerPart: "0", fractionalPart: "0045" }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // -7.00e+0 = -7
+ * convertExponentialToParts(-1, "7.00e0");
+ * // => { sign: -1, integerPart: "7", fractionalPart: "" }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Leading zeros in coefficient are handled; fractional length adjusts exponent
+ * convertExponentialToParts(1, "0009.500e2"); // 9.500 × 10^2 = 950
+ * // => { sign: 1, integerPart: "950", fractionalPart: "" }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // You can reconstruct a normalized decimal string yourself:
+ * const { sign, integerPart, fractionalPart } = convertExponentialToParts(-1, "1.234e-2");
+ * const signChar = sign < 0 ? "-" : "";
+ * const plain = fractionalPart ? `${integerPart}.${fractionalPart}` : integerPart;
+ * // plain == "0.01234"
+ * const result = signChar + plain; // "-0.01234"
+ * ```
+ *
+ * @see isNumPZ — utility used here to detect non-negative integers (exponent ≥ 0).
+ *
+ * @since 2.0.0
+ */
+declare function convertExponentialToParts(sign: 1 | -1, exponentialString: string): {
+    sign: 1 | -1;
+    integerPart: string;
+    fractionalPart: string;
+};
+
+/**
+ * Converts a {@link FixedDecimal} — an exact decimal representation —
+ * into a native JavaScript `number` (IEEE 754 double precision).
+ *
+ * @remarks
+ * This function is a **lossy** conversion when `value` contains
+ * more precision than JavaScript’s floating-point format can represent.
+ * It internally calls {@link fixedDecimalToStr} to produce a normalized
+ * string such as `"-123.4567"` and then passes it to the built-in
+ * `Number()` constructor.
+ *
+ * O(n) relative to the number of digits in `digitsInteger`
+ * (due to string creation in {@link fixedDecimalToStr}).
+ *
+ * @param value - The {@link FixedDecimal} instance to convert.
+ * Must contain:
+ * - `sign`: either `1` or `-1`;
+ * - `digitsInteger`: a `bigint` representing all digits without any decimal point;
+ * - `scale`: how many digits belong after the decimal point.
+ *
+ * @returns The approximate numeric value as a JavaScript `number`.
+ * If the string form is too large or too precise, the result may be
+ * rounded or become `Infinity`.
+ *
+ * @example
+ * ```ts
+ * const fd: FixedDecimal = { sign: 1, digitsInteger: 12345n, scale: 2 };
+ * // Represents exactly 123.45
+ * const num = fixedDecimalToNum(fd); // 123.45 (Number)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Handles negative numbers as well
+ * const neg: FixedDecimal = { sign: -1, digitsInteger: 987n, scale: 3 };
+ * const n = fixedDecimalToNum(neg); // -0.987
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Extreme precision may lose digits beyond ~15–17 significant figures
+ * const big: FixedDecimal = { sign: 1, digitsInteger: 12345678901234567890n, scale: 10 };
+ * const approx = fixedDecimalToNum(big);
+ * console.log(approx); // ~1234567890.1234567  (rounded)
+ * ```
+ *
+ * @see fixedDecimalToStr — for the exact string representation
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number#precision JavaScript number precision
+ *
+ * @since 2.0.0
+ */
+declare function fixedDecimalToNum(value: FixedDecimal): number;
+
+/**
+ * Converts a {@link FixedDecimal} — an exact, integer-based decimal structure —
+ * into its canonical string representation (e.g. `"-123.456"`).
+ *
+ * @remarks
+ * This function is **exact and reversible**: no precision loss occurs because it
+ * operates on the raw digit string (`digitsInteger`) and inserts the decimal point
+ * purely by string manipulation.
+ *
+ * The algorithm:
+ * 1. Converts the `digitsInteger` `BigInt` to a string of digits.
+ * 2. If `scale` is `0`, returns the signed integer directly.
+ * 3. If `scale` is positive:
+ *    - Pads with leading zeros when the number of digits is smaller than `scale`.
+ *    - Otherwise, splits at the appropriate boundary between integer and fractional parts.
+ *
+ * O(n) where `n` is the number of digits in `digitsInteger.toString()`.
+ *
+ * @param value - The {@link FixedDecimal} object:
+ *   - `sign`: `1` for positive or `-1` for negative numbers.
+ *   - `digitsInteger`: All digits as a `BigInt` without a decimal point.
+ *   - `scale`: The number of digits after the decimal point.
+ *
+ * @returns A string representation of the number, including a `-` sign if negative.
+ * If the number is fractional, a single `.` separates integer and fractional parts.
+ *
+ * @example
+ * ```ts
+ * const fd: FixedDecimal = { sign: 1, digitsInteger: 12345n, scale: 2 };
+ * fixedDecimalToStr(fd); // "123.45"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Negative number
+ * const neg: FixedDecimal = { sign: -1, digitsInteger: 987n, scale: 3 };
+ * fixedDecimalToStr(neg); // "-0.987"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Small fractional with fewer digits than scale
+ * const tiny: FixedDecimal = { sign: 1, digitsInteger: 12n, scale: 5 };
+ * fixedDecimalToStr(tiny); // "0.00012"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Whole number (scale = 0)
+ * const whole: FixedDecimal = { sign: 1, digitsInteger: 42n, scale: 0 };
+ * fixedDecimalToStr(whole); // "42"
+ * ```
+ *
+ * @see changeFixedDecimalScale — for adjusting the scale value safely
+ * @see fixedDecimalToNum — for converting to a JavaScript number
+ *
+ * @since 2.0.0
+ */
+declare function fixedDecimalToStr(value: FixedDecimal): 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)
+ * formatToNum("123.456");         // => 123.456
+ * formatToNum(0.034);             // => 0.034
+ *
+ * @example
+ * // Round to 2 fractional digits (half-up)
+ * formatToNum("123.456", 2);      // => 123.46  (because .456 → .46)
+ * formatToNum("-1.235", 2);       // => -1.24   (half-up away from zero)
+ *
+ * @example
+ * // Large values: parsed and rounded in fixed precision, then converted to number
+ * formatToNum("234893249238948.000003432", 6); // precise rounding in fixed space,
+ *                                              // final result as JS number
+ *
+ * @example
+ * // Explicit passthrough (any `round <= 1` behaves the same)
+ * formatToNum("1000.555", 1);     // => 1000.555 (no rounding step invoked)
+ * formatToNum("1000.555", 0);     // => 1000.555 (still no rounding)
+ *
+ * @see parseToFixedDecimal
+ * @see fixedDecimalToNum
+ * @see roundFixedDecimal
+ *
+ * @category Number Formatting
+ * @since 2.0.0
+ * @public
+ */
+declare function formatToNum(value: unknown, round?: number): number;
+
+/**
+ * Normalizes an arbitrary numeric input into sign, integer, and fractional string parts
+ * without losing precision, preparing it for exact fixed-decimal processing.
+ *
+ * @remarks
+ * This utility accepts `bigint`, `number`, and `string` inputs and returns a tuple-like
+ * object with three fields:
+ *
+ * - `sign`: `1` for non-negative values, `-1` for negative values.
+ * - `integerPart`: the digits before the decimal point as a string (no sign, no separators).
+ * - `fractionalPart`: the digits after the decimal point as a string (no sign, no separators).
+ *
+ * For JavaScript `number`s, the function first checks finiteness and then converts the
+ * absolute value to an exponential string (via `toExponential(30)`) to avoid
+ * floating-point artifacts when extracting digits. It delegates parsing of that exponential
+ * form to {@link convertExponentialToParts}.
+ *
+ * For `string`s, the function:
+ * - Trims whitespace and replaces a comma `,` decimal separator with a dot `.`.
+ * - Parses and removes a leading `+`/`-` sign (if present).
+ * - Validates the remaining characters with a permissive numeric pattern that allows:
+ *   - optional integer digits,
+ *   - an optional decimal point with digits,
+ *   - an optional scientific exponent (`e` or `E` with optional `+`/`-` and digits).
+ * - If an exponent is present, it delegates to {@link convertExponentialToParts};
+ *   otherwise it splits on the decimal point.
+ *
+ * **Important:** This function does not strip leading zeros in `integerPart` or trailing
+ * zeros in `fractionalPart`. If you need canonicalized output (e.g., remove leading/trailing
+ * zeros), do that in a later step (e.g., when building your fixed-decimal representation).
+ *
+ * @param input - The numeric input to normalize. Supported types:
+ * - `bigint` (e.g., `123n`, `-9007199254740993n`)
+ * - `number` (finite only; `NaN`, `Infinity`, `-Infinity` will throw)
+ * - `string` (e.g., `"42"`, `"-0.034"`, `"1.2e-5"`, with optional leading sign, optional
+ *   decimal part, optional exponent; commas are allowed as decimal separators and are
+ *   converted to dots)
+ *
+ * @returns An object with the normalized components:
+ * ```ts
+ * {
+ *   sign: 1 | -1;
+ *   integerPart: string;
+ *   fractionalPart: string;
+ * }
+ * ```
+ * The `integerPart` and `fractionalPart` contain only ASCII digits (`0`–`9`) and
+ * **never** include sign or exponent markers.
+ *
+ * @throws {Error}
+ * - If `input` is a `number` but not finite (`NaN`, `Infinity`, `-Infinity`).
+ * - If `input` is a `string` that is empty after trimming/replacement.
+ * - If `input` is a `string` that fails the numeric validation regex.
+ * - If `input` is of an unsupported type (not `bigint`, `number`, or `string`).
+ * - Any errors propagated from {@link convertExponentialToParts} when parsing exponential forms.
+ *
+ * @example
+ * // bigint input → fractional part is empty
+ * normalizeToDecimalComponents(123n);
+ * // => { sign: 1, integerPart: "123", fractionalPart: "" }
+ *
+ * @example
+ * // negative bigint
+ * normalizeToDecimalComponents(-987654321n);
+ * // => { sign: -1, integerPart: "987654321", fractionalPart: "" }
+ *
+ * @example
+ * // finite number input; uses exponential internally to avoid FP artifacts
+ * normalizeToDecimalComponents(0.0000034);
+ * // => { sign: 1, integerPart: "0", fractionalPart: "0000034" }  // exact digits
+ *
+ * @example
+ * // string with decimal comma and explicit sign
+ * normalizeToDecimalComponents("+1,250");
+ * // => { sign: 1, integerPart: "1", fractionalPart: "250" }
+ *
+ * @example
+ * // scientific notation string
+ * normalizeToDecimalComponents("-1.234e+3");
+ * // => { sign: -1, integerPart: "1234", fractionalPart: "" }
+ *
+ * @example
+ * // invalid string (throws)
+ * normalizeToDecimalComponents("12.34.56"); // Error: Invalid numeric string.
+ *
+ * @see convertExponentialToParts
+ * @category Parsing
+ * @since 2.0.0
+ * @public
+ */
+declare function normalizeToDecimalComponents(input: unknown): {
+    sign: 1 | -1;
+    integerPart: string;
+    fractionalPart: string;
+};
+
+/**
+ * Parses any numeric input (`number`, `bigint`, or `string`) into an exact {@link FixedDecimal}
+ * representation, preserving all digits without floating-point rounding errors.
+ *
+ * @remarks
+ * This function transforms arbitrary numeric input into a **fixed-precision decimal structure**
+ * that can safely represent extremely large or small values without losing information.
+ * It achieves this by first decomposing the input using {@link normalizeToDecimalComponents}
+ * and then constructing a `FixedDecimal` object consisting of:
+ *
+ * - `sign` → `1` for positive values, `-1` for negative values.
+ * - `digitsInteger` → a `BigInt` that encodes *all digits* of the number as if
+ *   the decimal point were removed.
+ * - `scale` → the count of digits that were originally after the decimal point.
+ *
+ * The resulting value can later be precisely converted back to a string or to a
+ * JavaScript `number` using helpers like `fixedDecimalToStr` or `fixedDecimalToNum`.
+ *
+ * This process **avoids IEEE-754 floating-point artifacts**, ensuring mathematically
+ * exact handling of decimal fractions (e.g. `"0.1" + "0.2" → 0.3` instead of `0.30000000000000004`).
+ *
+ * @param input - Any numeric source value. Supported types:
+ * - `number` — finite only (`NaN`, `Infinity`, `-Infinity` will throw).
+ * - `bigint` — directly converted without fractional digits.
+ * - `string` — may contain optional sign, decimal point, or exponential notation (`1.23e-5`).
+ *   Commas `,` as decimal separators are also supported and converted to dots `.`.
+ *
+ * @returns A normalized {@link FixedDecimal} object:
+ * ```ts
+ * {
+ *   sign: 1 | -1;           // the numeric sign
+ *   digitsInteger: bigint;   // all digits as a BigInt, no decimal point
+ *   scale: number;           // number of digits after the decimal
+ * }
+ * ```
+ *
+ * @throws {Error}
+ * - If the input is not a supported type (`number`, `bigint`, or `string`).
+ * - If the string cannot be parsed as a valid numeric representation.
+ * - If the number is not finite.
+ * - Any error propagated from {@link normalizeToDecimalComponents}.
+ *
+ * @example
+ * // Simple integer number
+ * parseToFixedDecimal(42);
+ * // => { sign: 1, digitsInteger: 42n, scale: 0 }
+ *
+ * @example
+ * // Decimal fraction
+ * parseToFixedDecimal("123.456");
+ * // => { sign: 1, digitsInteger: 123456n, scale: 3 }
+ *
+ * @example
+ * // Number in exponential notation
+ * parseToFixedDecimal("-1.23e-4");
+ * // => { sign: -1, digitsInteger: 123n, scale: 6 } // represents -0.000123
+ *
+ * @example
+ * // Leading zeros and trailing fractional zeros are trimmed internally
+ * parseToFixedDecimal("00045.67000");
+ * // => { sign: 1, digitsInteger: 4567n, scale: 2 } // "45.67"
+ *
+ * @example
+ * // Very large integer input using bigint
+ * parseToFixedDecimal(123456789012345678901234567890n);
+ * // => { sign: 1, digitsInteger: 123456789012345678901234567890n, scale: 0 }
+ *
+ * @example
+ * // Negative value with high precision fraction
+ * parseToFixedDecimal("-0.00000003432");
+ * // => { sign: -1, digitsInteger: 3432n, scale: 11 }
+ *
+ * @see normalizeToDecimalComponents
+ * @see FixedDecimal
+ * @see fixedDecimalToNum
+ * @see fixedDecimalToStr
+ *
+ * @category Parsing
+ * @since 2.0.0
+ * @public
+ */
+declare function parseToFixedDecimal(input: unknown): FixedDecimal;
+
+/**
+ * Rounds a {@link FixedDecimal} value to the specified number of fractional digits,
+ * using either **half-up** (standard rounding) or **truncation** (cut-off without rounding).
+ *
+ * @remarks
+ * This function operates entirely in fixed-precision integer space (`BigInt` arithmetic),
+ * so rounding is mathematically exact — it never suffers from floating-point errors.
+ *
+ * Internally, it determines how many fractional digits must be removed from
+ * `source.digitsInteger` to reach the desired precision (`decimalPlaces`), divides
+ * by `10 ** digitsToRemove`, and conditionally increments the result depending on
+ * the remainder and rounding mode.
+ *
+ * It preserves the original `sign` and returns a new {@link FixedDecimal} object
+ * with an updated `scale` (number of digits after the decimal point).
+ *
+ * ---
+ * **Rounding modes:**
+ * - `'half-up'` — standard rounding to nearest neighbor; `.5` rounds **away from zero**.
+ *   Example: `1.235 → 1.24`, `-1.235 → -1.24`.
+ * - `'trunc'` — truncates digits beyond the target precision (rounds **toward zero**).
+ *   Example: `1.239 → 1.23`, `-1.239 → -1.23`.
+ *
+ * ---
+ * @param source - The input {@link FixedDecimal} to round.
+ * Must contain a valid combination of:
+ * - `sign`: `1` or `-1`
+ * - `digitsInteger`: a `BigInt` representing all digits (no decimal point)
+ * - `scale`: number of digits after the decimal
+ *
+ * @param decimalPlaces - Target number of digits to keep **after the decimal point**.
+ * Values less than 0 are treated as 0.
+ * For example, rounding to `2` means "keep two digits after the decimal".
+ *
+ * @param roundMode - Rounding algorithm to use:
+ * - `'half-up'` (default) → rounds 0.5 and higher up.
+ * - `'trunc'` → simply removes extra digits without rounding up.
+ *
+ * @defaultValue `'half-up'`
+ *
+ * @returns A **new** {@link FixedDecimal} with the adjusted `digitsInteger`
+ * and `scale` equal to `decimalPlaces`.
+ * If the requested precision is greater than or equal to `source.scale`,
+ * the source value is returned unchanged (shallow copy).
+ *
+ * @throws {Error}
+ * - Never throws directly in normal use, but may propagate errors if invalid
+ *   numeric parameters are passed (e.g., non-integer `decimalPlaces`).
+ *
+ * ---
+ * @example
+ * // Half-up rounding
+ * const value: FixedDecimal = { sign: 1, digitsInteger: 123456n, scale: 3 }; // 123.456
+ * roundFixedDecimal(value, 2, 'half-up');
+ * // => { sign: 1, digitsInteger: 12346n, scale: 2 }  // 123.46
+ *
+ * @example
+ * // Truncation (cut-off)
+ * const value: FixedDecimal = { sign: 1, digitsInteger: 123456n, scale: 3 };
+ * roundFixedDecimal(value, 2, 'trunc');
+ * // => { sign: 1, digitsInteger: 12345n, scale: 2 }  // 123.45
+ *
+ * @example
+ * // No rounding needed (scale already smaller)
+ * const v: FixedDecimal = { sign: -1, digitsInteger: 1234n, scale: 1 }; // -123.4
+ * roundFixedDecimal(v, 3);
+ * // => identical copy: { sign: -1, digitsInteger: 1234n, scale: 1 }
+ *
+ * @example
+ * // Rounding very small values
+ * const v: FixedDecimal = { sign: 1, digitsInteger: 123n, scale: 6 }; // 0.000123
+ * roundFixedDecimal(v, 4);
+ * // => { sign: 1, digitsInteger: 1n, scale: 4 }  // 0.0001
+ *
+ * @example
+ * // Rounding negative numbers (half-up → away from zero)
+ * const v: FixedDecimal = { sign: -1, digitsInteger: 125n, scale: 2 }; // -1.25
+ * roundFixedDecimal(v, 1, 'half-up');
+ * // => { sign: -1, digitsInteger: 13n, scale: 1 }  // -1.3
+ *
+ * @see FixedDecimal
+ * @see parseToFixedDecimal
+ * @see fixedDecimalToNum
+ * @see fixedDecimalToStr
+ * @see formatToNum
+ *
+ * @category Math
+ * @since 2.0.0
+ * @public
+ */
+declare function roundFixedDecimal(source: FixedDecimal, decimalPlaces: number, roundMode?: 'half-up' | 'trunc'): FixedDecimal;
+
+/**
+ * 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 formatToTrim}.
+ * 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 `formatToLowerCase`).
+ * - 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
+ * formatToLowerCase('HELLO');        // => "hello"
+ * formatToLowerCase('  TEST ');      // => "test"
+ *
+ * @example
+ * // Mixed types
+ * formatToLowerCase(123);            // => ""
+ * formatToLowerCase(true);           // => ""
+ * formatToLowerCase(null);           // => ""
+ *
+ * @example
+ * // Empty or whitespace inputs
+ * formatToLowerCase('   ');          // => ""
+ * formatToLowerCase('');             // => ""
+ *
+ * @example
+ * // Already lowercase
+ * formatToLowerCase('data');         // => "data"
+ *
+ * @see isStr
+ * @see isStrFilled
+ * @see formatToTrim
+ *
+ * @category String
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToLowerCase(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 formatToTrim}).
+ * - 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 formatToTrim}, 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 formatToUndefined}
+ * | Case | `formatToNull` | `formatToUndefined` |
+ * |------|----------------|----------------------|
+ * | `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
+ * formatToNull('');          // => null
+ * formatToNull('   ');       // => null
+ *
+ * @example
+ * // Undefined also becomes null
+ * formatToNull(undefined);   // => null
+ *
+ * @example
+ * // Non-empty strings remain as-is
+ * formatToNull('Hello');     // => "Hello"
+ * formatToNull('  Data ');   // => "  Data "
+ *
+ * @example
+ * // Non-string types are preserved
+ * formatToNull(0);           // => 0
+ * formatToNull(false);       // => false
+ * formatToNull([]);          // => []
+ * formatToNull({});          // => {}
+ *
+ * @see isStr
+ * @see formatToTrim
+ * @see formatToUndefined
+ *
+ * @category String
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToNull(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
+ * formatToPhone('+380501234567');         // => "+380501234567"
+ *
+ * @example
+ * // European "00" prefix
+ * formatToPhone('00442079460729');        // => "+442079460729"
+ *
+ * @example
+ * // Local 10-digit number (default country +7)
+ * formatToPhone('9123456789');            // => "+79123456789"
+ *
+ * @example
+ * // With custom default country
+ * formatToPhone('9876543210', '+34');     // => "+349876543210"
+ *
+ * @example
+ * // Strings with spaces, punctuation, parentheses
+ * formatToPhone('(050) 123-45-67');       // => "+70501234567"
+ * formatToPhone('+1 (202) 555-0183');     // => "+12025550183"
+ *
+ * @example
+ * // Invalid or ambiguous inputs
+ * formatToPhone('');                      // => null
+ * formatToPhone('000123456');             // => null
+ * formatToPhone('abcdefgh');              // => null
+ * formatToPhone(null);                    // => null
+ * formatToPhone(true);                    // => null
+ *
+ * @see isStr
+ * @see formatToTrim
+ *
+ * @category String
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToPhone(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
+ * formatToTrim('  Hello  ');            // => "Hello"
+ *
+ * @example
+ * // Removes zero-width characters
+ * formatToTrim('word\u200B');           // => "word"
+ *
+ * @example
+ * // Unicode normalization
+ * formatToTrim('ＡＢＣ');               // => "ABC"
+ * formatToTrim('e\u0301');              // => "é"
+ *
+ * @example
+ * // Non-string inputs
+ * formatToTrim(123);                    // => ""
+ * formatToTrim(null);                   // => ""
+ * formatToTrim(undefined);              // => ""
+ * formatToTrim({ text: 'hi' });         // => ""
+ *
+ * @see isStr
+ * @see String.prototype.normalize
+ *
+ * @category String
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToTrim(value: unknown): 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 formatToTrim}).
+ * - Otherwise returns the original value.
+ *
+ * @remarks
+ * ### Processing steps
+ * 1. If `value` is `null`, return `undefined`.
+ * 2. If `value` is a string:
+ *    - Trim using {@link formatToTrim} 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 formatToNull}, depending on whether your system
+ *   prefers `undefined` (omit field) or `null` (explicit empty value).
+ *
+ * ### Comparison with {@link formatToNull}
+ * | Case | `formatToNull` | `formatToUndefined` |
+ * |------|----------------|----------------------|
+ * | `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
+ * formatToUndefined('');        // => undefined
+ * formatToUndefined('   ');     // => undefined
+ *
+ * @example
+ * // null is also normalized
+ * formatToUndefined(null);      // => undefined
+ *
+ * @example
+ * // Non-empty strings remain unchanged
+ * formatToUndefined('Hello');   // => "Hello"
+ *
+ * @example
+ * // Non-string types are preserved
+ * formatToUndefined(0);         // => 0
+ * formatToUndefined(false);     // => false
+ * formatToUndefined([]);        // => []
+ * formatToUndefined({});        // => {}
+ *
+ * @see isStr
+ * @see formatToTrim
+ * @see formatToNull
+ *
+ * @category String
+ * @public
+ * @since 2.0.0
+ */
+declare function formatToUndefined(value: unknown): {} | undefined;
+
+/**
+ * Converts a numeric value with a given unit (bytes, KB, MB, GB, TB, PB)
+ * into gigabytes (`GB`).
+ *
+ * @summary
+ * Safely normalizes a size value of any supported unit into **gigabytes**,
+ * using binary multiples (`1 KB = 1024 bytes`, `1 MB = 1024 KB`, etc.).
+ *
+ * @param value - Numeric value to convert (e.g., `512`, `"1.5"`, `"2048MB"`).
+ * @param unit - Optional unit string indicating the scale of `value`.
+ *               Case-insensitive. Supported prefixes:
+ *               `"B"`, `"KB"`, `"MB"`, `"GB"`, `"TB"`, `"PB"`.
+ *
+ * @returns The value converted to gigabytes (`number`).
+ *
+ * @throws {Error}
+ * Throws an error if the input value cannot be parsed as a finite number,
+ * or if the computed result is `NaN` or `Infinity`.
+ *
+ * @remarks
+ * ### Supported units
+ * | Unit | Interpreted as | Conversion formula |
+ * |------|----------------|--------------------|
+ * | `b`, `B`, `bytes`     | bytes              | `v / GB` |
+ * | `k`, `kb`, `kilobyte` | kilobytes          | `v / MB` |
+ * | `m`, `mb`, `megabyte` | megabytes          | `v / GB` |
+ * | `g`, `gb`, `gigabyte` | gigabytes          | `v` |
+ * | `t`, `tb`, `terabyte` | terabytes          | `v * 1024` |
+ * | `p`, `pb`, `petabyte` | petabytes          | `v * (1024²)` |
+ *
+ * If no unit is provided, gigabytes (`GB`) are assumed by default.
+ *
+ * ### Normalization steps
+ * 1. Convert `value` to a numeric value using {@link formatToNum}.
+ * 2. Validate via {@link isNum} — must be finite.
+ * 3. Normalize `unit`:
+ *    - Trim whitespace.
+ *    - Convert to lowercase.
+ *    - Extract first character (e.g., `'k'` for `"KB"`).
+ * 4. Compute conversion factor depending on the first letter.
+ * 5. Normalize `-0` to `0` before returning.
+ *
+ * ### Behavior notes
+ * - Throws descriptive errors on invalid inputs.
+ * - Supports string-based numeric inputs (`"2048"`, `"1.5"`, etc.).
+ * - Ignores case and trailing spaces in the unit name.
+ * - Uses binary (IEC-style) 1024-based units — not SI 1000-based.
+ *
+ * ### Performance
+ * - Time complexity: **O(1)**.
+ * - Space complexity: **O(1)**.
+ *
+ * ### Examples
+ *
+ * @example
+ * // Basic conversions
+ * toGB(1024, 'MB');   // => 1
+ * toGB(1, 'GB');      // => 1
+ * toGB(1, 'TB');      // => 1024
+ * toGB(0.5, 'TB');    // => 512
+ *
+ * @example
+ * // From bytes
+ * toGB(1073741824, 'B'); // => 1
+ * toGB('2147483648', 'b'); // => 2
+ *
+ * @example
+ * // From petabytes
+ * toGB(1, 'PB'); // => 1048576
+ *
+ * @example
+ * // Auto-handling and normalization
+ * toGB(' 1.5 ', ' mb ');   // => 0.00146484375
+ * toGB('2', '');           // => 2  (default is GB)
+ *
+ * @example
+ * // Invalid inputs
+ * toGB('abc', 'GB');       // throws Error("toGB: value "abc" is not numeric")
+ * toGB(NaN, 'MB');         // throws Error("toGB: result is not finite...")
+ *
+ * @see isNum
+ * @see formatToNum
+ *
+ * @category Conversion
+ * @public
+ * @since 2.0.0
+ */
+declare function toGB(value: unknown, unit?: string): number;
+
+/**
+ * Converts a hashrate (or similar magnitude value) into **gigahashes per second** (`GH/s`).
+ *
+ * @summary
+ * Normalizes a numeric value expressed in various hash rate units (e.g., `kH/s`, `MH/s`, `TH/s`)
+ * to **gigahashes (GH)**, using standard decimal scaling (`×1000` between adjacent prefixes).
+ *
+ * @param value - Input numeric value or string representing a number (e.g. `"1200"`, `3.5`).
+ * @param unit - Optional unit string representing the magnitude (`H`, `kH`, `MH`, `GH`, `TH`, `PH`, `EH`).
+ *               Case-insensitive and automatically normalized via {@link normalizeUnit}.
+ *
+ * @returns The normalized value expressed in **gigahashes per second (GH/s)**.
+ * Returns `0` if the input is invalid or non-numeric.
+ *
+ * @remarks
+ * ### Conversion logic
+ * 1. **Parsing:**
+ *    Uses {@link formatToNum} to safely convert `value` into a number.
+ *
+ * 2. **Validation:**
+ *    If the parsed number is not finite (`NaN`, `Infinity`, etc.), returns `0`.
+ *
+ * 3. **Unit normalization:**
+ *    Calls {@link normalizeUnit} to clean up and simplify the unit name (e.g. `" MH/s "` → `"mh"`).
+ *    Then takes the first character (`m`, `g`, `t`, etc.) to determine scale.
+ *
+ * 4. **Factor lookup:**
+ *    Applies the following conversion factors relative to gigahashes:
+ *
+ *    | Prefix | Unit      | Factor (to GH) | Example conversion             |
+ *    |---------|-----------|----------------|--------------------------------|
+ *    | `h`     | hashes/s  | `1e-9`         | `1e9 H/s` = `1 GH/s`           |
+ *    | `k`     | kilohash  | `1e-6`         | `1e6 kH/s` = `1 GH/s`          |
+ *    | `m`     | megahash  | `1e-3`         | `1e3 MH/s` = `1 GH/s`          |
+ *    | `g`     | gigahash  | `1`            | identity                       |
+ *    | `t`     | terahash  | `1e3`          | `1 TH/s` = `1000 GH/s`         |
+ *    | `p`     | petahash  | `1e6`          | `1 PH/s` = `1,000,000 GH/s`    |
+ *    | `e`     | exahash   | `1e9`          | `1 EH/s` = `1,000,000,000 GH/s`|
+ *
+ * 5. **Result validation:**
+ *    If the final result is not a finite number, throws an error.
+ *    Otherwise returns the computed gigahashes value (with `-0` normalized to `0`).
+ *
+ * ### Behavior notes
+ * - Returns `0` instead of throwing when the input cannot be parsed as a number.
+ * - Uses **decimal scaling** (`×1000`), not binary (`×1024`).
+ * - Handles both numeric and string inputs seamlessly.
+ * - Automatically ignores plural or rate suffixes (like `/s`, `hashes`).
+ *
+ * ### Performance
+ * - Time complexity: **O(1)**.
+ * - Space complexity: **O(1)**.
+ *
+ * ### Examples
+ *
+ * @example
+ * // Basic conversions
+ * toGH(1, 'GH');     // => 1
+ * toGH(1, 'TH');     // => 1000
+ * toGH(1, 'MH');     // => 0.001
+ * toGH(1, 'kH');     // => 0.000001
+ * toGH(1, 'PH');     // => 1_000_000
+ * toGH(1, 'EH');     // => 1_000_000_000
+ *
+ * @example
+ * // String inputs and normalization
+ * toGH('1200', 'mh/s');   // => 1.2
+ * toGH('3.5', 'TH/s');    // => 3500
+ *
+ * @example
+ * // Invalid or edge inputs
+ * toGH('', 'GH');         // => 0
+ * toGH(null, 'GH');       // => 0
+ * toGH(NaN, 'MH');        // => 0
+ *
+ * @example
+ * // Custom normalization of unit formatting
+ * toGH(5, ' khash / s '); // => 0.000005
+ * toGH(2, 'T');           // => 2000
+ *
+ * @see formatToNum
+ * @see isNum
+ * @see normalizeUnit
+ *
+ * @category Conversion
+ * @public
+ * @since 2.0.0
+ */
+declare function toGH(value: any, unit?: string): number;
+
+/**
+ * Converts a rate value expressed with SI hash-rate prefixes into **hashes per second** (`H/s`).
+ *
+ * @summary
+ * Normalizes a numeric value given in `kH/s`, `MH/s`, `GH/s`, `TH/s`, `PH/s`, or `EH/s`
+ * to plain **hashes per second** using **decimal scaling** (×1000 between adjacent prefixes).
+ * Units are case-insensitive and sanitized via {@link normalizeUnit}.
+ *
+ * @param value - Input value to convert (number or number-like string, e.g. `3.5`, `"1200"`).
+ * @param unit - Optional unit string (e.g. `"kH/s"`, `"MH"`, `"ghashes"`).
+ *               If omitted or empty, the function assumes **`h`** (hashes).
+ *
+ * @returns The value converted to **H/s** (`number`). Returns `0` if `value` is not numeric.
+ *
+ * @remarks
+ * ### Unit handling
+ * `unit` is first cleaned by {@link normalizeUnit} (trim, lowercase, remove spaces and `"/s"`, `"hash(es)"`),
+ * then the **first character** determines the scale:
+ *
+ * | Prefix | Interpreted as | Multiplier to H/s |
+ * |:------:|-----------------|-------------------|
+ * | `h`    | hashes          | `1`               |
+ * | `k`    | kilohashes      | `1e3`             |
+ * | `m`    | megahashes      | `1e6`             |
+ * | `g`    | gigahashes      | `1e9`             |
+ * | `t`    | terahashes      | `1e12`            |
+ * | `p`    | petahashes      | `1e15`            |
+ * | `e`    | exahashes       | `1e18`            |
+ *
+ * Unknown or empty prefixes default to `h` (no scaling).
+ *
+ * ### Parsing & validation
+ * - Uses {@link formatToNum} to parse `value`.
+ * - If parsed value is not a finite number, returns `0`.
+ * - After conversion, if the result is not finite, throws an error with details.
+ * - Normalizes `-0` to `0` before returning.
+ *
+ * ### Decimal vs binary
+ * This function uses **decimal** (SI) steps (×1000) common for hashrates.
+ * For byte/size conversions use binary (×1024) helpers like `toGB`.
+ *
+ * ### Performance
+ * - Time complexity: **O(1)**
+ * - Space complexity: **O(1)**
+ *
+ * ### Examples
+ *
+ * @example
+ * // Identity and basic scales
+ * toH(1, 'H');     // => 1
+ * toH(1, 'kH');    // => 1_000
+ * toH(1, 'MH');    // => 1_000_000
+ * toH(1, 'GH');    // => 1_000_000_000
+ * toH(2.5, 'TH');  // => 2_500_000_000_000
+ *
+ * @example
+ * // Large magnitudes
+ * toH(1, 'PH');    // => 1_000_000_000_000_000
+ * toH(0.01, 'EH'); // => 10_000_000_000_000_000
+ *
+ * @example
+ * // Flexible, noisy units and strings
+ * toH('1200', ' mh/s ');     // => 1_200_000
+ * toH(3.2, 'khashes');       // => 3_200
+ * toH('5', '');              // => 5   (defaults to hashes)
+ *
+ * @example
+ * // Invalid inputs
+ * toH('', 'GH');             // => 0
+ * toH(null, 'MH');           // => 0
+ * toH(NaN, 'kH');            // => 0
+ *
+ * @see normalizeUnit
+ * @see formatToNum
+ * @see isNum
+ *
+ * @category Conversion
+ * @public
+ * @since 2.0.0
+ */
+declare function toH(value: any, unit?: string): number;
+
+/**
+ * Extracts the **hostname** (IPv4, IPv6, or domain) from a URL-like string.
+ *
+ * @summary
+ * Parses a given string as a URL or host reference and returns the **host component**
+ * (without protocol, port, path, query, or credentials).
+ * Handles both valid URLs (via {@link URL}) and malformed or scheme-less inputs using fallback parsing.
+ *
+ * @param value - Any string that may represent a URL, host, or address.
+ *
+ * @returns
+ * The hostname (domain or IP address) as a plain string.
+ * Returns an empty string (`""`) if the input is blank or cannot be parsed.
+ *
+ * @remarks
+ * ### Parsing strategy
+ * 1. **Scheme detection:**
+ *    - If the input starts with a protocol scheme (e.g., `http:`, `ftp:`), it is parsed directly.
+ *    - Otherwise, a default `http://` prefix is prepended so the built-in {@link URL} parser can process it.
+ *
+ * 2. **Primary parsing:**
+ *    - Uses the native {@link URL} class to extract `hostname`.
+ *    - Automatically handles IPv6 literals, punycode domains, and IDNs.
+ *
+ * 3. **Fallback parsing (for invalid URLs):**
+ *    - Strips credentials (`user:pass@`).
+ *    - Extracts the first segment before `/`, `?`, or `#`.
+ *    - If the result looks like `[::1]` or `[2001:db8::1]`, returns the IPv6 address inside brackets.
+ *    - Otherwise, takes everything before the first colon (`:`) as the hostname.
+ *
+ * ### Supported formats
+ * - Full URLs:
+ *   `"https://user:pass@sub.example.com:8080/path"` → `"sub.example.com"`
+ * - Host with port:
+ *   `"example.com:3000"` → `"example.com"`
+ * - IPv4:
+ *   `"192.168.1.1:4028"` → `"192.168.1.1"`
+ * - IPv6 (with or without brackets):
+ *   `"[2001:db8::1]:4028"` → `"2001:db8::1"`
+ * - Without scheme:
+ *   `"example.com/test?q=1"` → `"example.com"`
+ *
+ * ### Behavior notes
+ * - Returns an empty string if `value` is empty, blank, or unparsable.
+ * - Never throws — all exceptions are caught and handled gracefully.
+ * - Does **not** include port numbers or authentication info.
+ * - Automatically trims whitespace before parsing.
+ *
+ * ### Performance
+ * - Time complexity: **O(n)** (linear in string length).
+ * - Space complexity: **O(n)** (creates trimmed and split substrings).
+ *
+ * ### Examples
+ *
+ * @example
+ * // Standard URLs
+ * extractHost('https://example.com/path');         // => "example.com"
+ * extractHost('http://user:pass@site.org:8080');   // => "site.org"
+ *
+ * @example
+ * // Without scheme
+ * extractHost('example.com/foo/bar');              // => "example.com"
+ * extractHost('sub.domain.net:3000');              // => "sub.domain.net"
+ *
+ * @example
+ * // IP addresses
+ * extractHost('192.168.0.10:4028');                // => "192.168.0.10"
+ * extractHost('[2001:db8::1]:80');                 // => "2001:db8::1"
+ *
+ * @example
+ * // Invalid or blank input
+ * extractHost('');                                 // => ""
+ * extractHost('not a valid host');                 // => "not"
+ *
+ * @see URL
+ * @see isStrFilled
+ *
+ * @category Network
+ * @public
+ * @since 2.0.0
+ */
+declare function extractHost(value?: string): string;
+
+export { type FixedDecimal, type JSONLike, type PasswordOptions, type RangeIPv4Options, type TimeParts, changeFixedDecimalScale, cidrToRange, convertExponentialToParts, extractHost, fixedDecimalToNum, fixedDecimalToStr, floorDateToMinutes, formatDateToString, formatStrToFuncArgs, formatToBool, formatToLowerCase, formatToNull, formatToNum, formatToPhone, formatToTrim, formatToUndefined, ipAddrToNum, isArr, isArrFilled, isBool, isDate, isEmail, isExists, isFunc, isIpAddr, isMacAddr, isNum, isNumFloat, isNumN, isNumNZ, isNumP, isNumPZ, isObj, isObjFilled, isPassword, isPhone, isStr, isStrAscDesc, isStrBool, isStrFilled, isVar, jsonDecode, jsonEncode, normalizeToDecimalComponents, numToIpAddr, parseIPv4, parseStringLike, parseToFixedDecimal, partsToSeconds, rangeIPv4, rangeIPv4ToArr, roundFixedDecimal, secondsToParts, splitArrToPortions, toGB, toGH, toH, toIPv4, tryParseJSON, wait };