full-utils 2.0.5 → 3.0.0

package/dist/index.d.cts

@@ -27,9 +27,9 @@
  *    - **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"`,
+ *    - **Booleans**: Using {@link isStrBool} + {@link boolNormalize} (e.g., `"true"`,
  *      `"False"`, `"yes"`, `"0"` depending on your implementation).
- *    - **Numbers**: Using {@link formatToNum}. If the result is finite, it is returned.
+ *    - **Numbers**: Using {@link numNormalize}. If the result is finite, it is returned.
  *      Explicit `"Infinity"` and `"-Infinity"` are also supported.
  *    - **Quoted strings**: `'text'` or `"text"` → inner text with escapes processed
  *      (`\\` → `\`, `\'` → `'`, `\"` → `"`).
@@ -54,44 +54,44 @@
  *   do so in a sandbox with explicit allow-lists.
  *
  * ### Limitations
- * - Numerical parsing relies on {@link formatToNum}. Extremely large or high-precision
+ * - Numerical parsing relies on {@link numNormalize}. Extremely large or high-precision
  *   decimals may still be subject to JavaScript `number` precision limits unless your
- *   `formatToNum` converts to a safer representation.
+ *   `numNormalize` converts to a safer representation.
  * - Only basic backslash escapes are handled in quoted strings (no `\uXXXX` decoding here).
  * - Whitespace outside quotes is trimmed from each token; internal whitespace is preserved.
  *
  * @example
  * // Basic values
- * formatStrToFuncArgsArr('1, true, "hello"'); // => [1, true, "hello"]
+ * arrFuncArgs('1, true, "hello"'); // => [1, true, "hello"]
  *
  * @example
  * // Bracket-wrapped list
- * formatStrToFuncArgsArr('[1, 2, 3]'); // => [1, 2, 3]
+ * arrFuncArgs('[1, 2, 3]'); // => [1, 2, 3]
  *
  * @example
  * // Nested structures and quoting
- * formatStrToFuncArgsArr('{"a":1,"b":[2,3]}, "te,xt", (x,y)'); // => [ {a:1,b:[2,3]}, "te,xt", "(x,y)" ]
+ * arrFuncArgs('{"a":1,"b":[2,3]}, "te,xt", (x,y)'); // => [ {a:1,b:[2,3]}, "te,xt", "(x,y)" ]
  *
  * @example
  * // Booleans, null/undefined, and Infinity
- * formatStrToFuncArgsArr('yes, NO, null, undefined, Infinity, -Infinity');
+ * arrFuncArgs('yes, NO, null, undefined, Infinity, -Infinity');
  * // => [true, false, null, undefined, Infinity, -Infinity]
  *
  * @example
  * // Macro-like token (returned as-is)
- * formatStrToFuncArgsArr('$env(PATH)'); // => ["$env(PATH)"]
+ * arrFuncArgs('$env(PATH)'); // => ["$env(PATH)"]
  *
  * @example
  * // Escapes inside quotes
- * formatStrToFuncArgsArr('"He said: \\"Hi\\"", \'It\\\'s ok\', "\\\\path"');
+ * arrFuncArgs('"He said: \\"Hi\\"", \'It\\\'s ok\', "\\\\path"');
  * // => ['He said: "Hi"', "It's ok", "\\path"]
  *
  * @example
  * // Empty and whitespace inputs
- * formatStrToFuncArgsArr('   ');          // => []
- * formatStrToFuncArgsArr('[]');           // => []
- * formatStrToFuncArgsArr('[   ]');        // => []
- * formatStrToFuncArgsArr('  [ a , b ] '); // => ["a", "b"]
+ * arrFuncArgs('   ');          // => []
+ * arrFuncArgs('[]');           // => []
+ * arrFuncArgs('[   ]');        // => []
+ * arrFuncArgs('  [ a , b ] '); // => ["a", "b"]
  *
  * @param value - Raw string containing comma-separated arguments.
  * If `value` is **not** a string, the function returns `[value]` unchanged.
@@ -99,14 +99,14 @@
  * @returns An array of coerced values (`unknown[]`). Each item is one parsed token.
  *
  * @see isStrBool
- * @see formatToBool
- * @see formatToNum
+ * @see boolNormalize
+ * @see numNormalize
  * @see jsonDecode
  *
  * @public
  * @since 2.0.0
  */
-declare function formatStrToFuncArgsArr(value: string): unknown[];
+declare function arrFuncArgs(value: string): unknown[];
 
 /**
  * Splits an input array into smaller subarrays (portions) of a given fixed size.
@@ -145,31 +145,31 @@ declare function formatStrToFuncArgsArr(value: string): unknown[];
  *
  * @example
  * // Split an array into groups of 3
- * splitArrToPortions([1, 2, 3, 4, 5, 6, 7], 3);
+ * arrSplitPortions([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);
+ * arrSplitPortions(['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); // => []
+ * arrSplitPortions([1, 2, 3], 0);   // => []
+ * arrSplitPortions([1, 2, 3], -2);  // => []
+ * arrSplitPortions([1, 2, 3], NaN); // => []
  *
  * @example
  * // Works with readonly arrays
  * const input = [10, 20, 30, 40] as const;
- * const result = splitArrToPortions(input, 2);
+ * const result = arrSplitPortions(input, 2);
  * // result: [[10, 20], [30, 40]]
  *
  * @category Array
  * @public
  * @since 2.0.0
  */
-declare function splitArrToPortions<T>(arr: readonly T[], portionLength: number): T[][];
+declare function arrSplitPortions<T>(arr: readonly T[], portionLength: number): T[][];
 
 /**
  * Converts any given value into a normalized boolean (`true` / `false`).
@@ -228,31 +228,31 @@ declare function splitArrToPortions<T>(arr: readonly T[], portionLength: number)
  *
  * @example
  * // Native booleans
- * formatToBool(true);            // => true
- * formatToBool(false);           // => false
+ * boolNormalize(true);            // => true
+ * boolNormalize(false);           // => false
  *
  * @example
  * // Numeric values
- * formatToBool(1);               // => true
- * formatToBool(0);               // => false
- * formatToBool(-5);              // => false
+ * boolNormalize(1);               // => true
+ * boolNormalize(0);               // => false
+ * boolNormalize(-5);              // => false
  *
  * @example
  * // String values
- * formatToBool('yes');           // => true
- * formatToBool('No');            // => false
- * formatToBool('TRUE');          // => true
- * formatToBool('false');         // => false
- * formatToBool('on');            // => true
- * formatToBool('off');           // => false
+ * boolNormalize('yes');           // => true
+ * boolNormalize('No');            // => false
+ * boolNormalize('TRUE');          // => true
+ * boolNormalize('false');         // => false
+ * boolNormalize('on');            // => true
+ * boolNormalize('off');           // => false
  *
  * @example
  * // Mixed and invalid inputs
- * formatToBool(null);            // => false
- * formatToBool(undefined);       // => false
- * formatToBool([]);              // => false
- * formatToBool({});              // => false
- * formatToBool('maybe');         // => false
+ * boolNormalize(null);            // => false
+ * boolNormalize(undefined);       // => false
+ * boolNormalize([]);              // => false
+ * boolNormalize({});              // => false
+ * boolNormalize('maybe');         // => false
  *
  * @see isBool
  * @see isNumP
@@ -263,7 +263,7 @@ declare function splitArrToPortions<T>(arr: readonly T[], portionLength: number)
  * @public
  * @since 2.0.0
  */
-declare function formatToBool(value: unknown): boolean;
+declare function boolNormalize(value: unknown): boolean;
 
 /**
  * Waits asynchronously for the specified amount of time.
@@ -353,12 +353,12 @@ declare function wait(timeout?: number): Promise<void>;
  *
  * @remarks
  * This interface is used by time utility functions such as
- * {@link secondsToParts} and {@link partsToSeconds} to represent durations
+ * {@link dateSecParts} and {@link datePartsSec} to represent durations
  * in a normalized structure that is easy to read, format, or serialize.
  *
  * Each field is an **integer number** representing the whole count of that unit.
  * None of the fields are fractional, and they are expected to follow
- * these conventional bounds when generated by {@link secondsToParts}:
+ * these conventional bounds when generated by {@link dateSecParts}:
  *
  * ```
  * days    ≥ 0
@@ -376,8 +376,8 @@ declare function wait(timeout?: number): Promise<void>;
  * 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
+ * const total = datePartsSec(t);   // -> 95445
+ * const back  = dateSecParts(total); // -> same structure again
  * ```
  *
  * @example
@@ -393,8 +393,8 @@ declare function wait(timeout?: number): Promise<void>;
  * @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.
+ * @see {@link dateSecParts} — converts total seconds into this structure.
+ * @see {@link datePartsSec} — converts this structure back into total seconds.
  *
  * @public
  * @category Date & Time
@@ -441,22 +441,22 @@ interface TimeParts {
  * ```ts
  * // Example 1: Floor to the nearest 15-minute mark
  * const d = new Date('2025-10-18T10:43:27');
- * floorDateToMinutes(15, d);
+ * dateFloorMin(15, d);
  * // -> 2025-10-18T10:30:00.000Z
  * ```
  *
  * @example
  * ```ts
  * // Example 2: Using default date (current time)
- * const nowFloored = floorDateToMinutes(10);
+ * const nowFloored = dateFloorMin(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
+ * dateFloorMin(-5, new Date());  // treated as 1 minute
+ * dateFloorMin(999, new Date()); // treated as 60 minutes
  * ```
  *
  * @throws Never throws — invalid step values are automatically normalized.
@@ -468,7 +468,7 @@ interface TimeParts {
  * @category Date & Time
  * @since 2.0.0
  */
-declare function floorDateToMinutes(everyMinutes?: number, date?: Date): Date;
+declare function dateFloorMin(everyMinutes?: number, date?: Date): Date;
 
 /**
  * Formats a {@link Date} object into a human-readable timestamp string
@@ -502,14 +502,14 @@ declare function floorDateToMinutes(everyMinutes?: number, date?: Date): Date;
  * ```ts
  * // Example 1: Specific date
  * const d = new Date('2025-10-18T10:43:27Z');
- * formatDateToString(d);
+ * dateStr(d);
  * // -> "2025-10-18 10:43:27"
  * ```
  *
  * @example
  * ```ts
  * // Example 2: Default (current) date
- * formatDateToString();
+ * dateStr();
  * // -> e.g. "2025-10-18 12:07:55"
  * ```
  *
@@ -517,7 +517,7 @@ declare function floorDateToMinutes(everyMinutes?: number, date?: Date): Date;
  * ```ts
  * // Example 3: Padding behavior
  * const d = new Date('2025-03-07T09:04:02');
- * formatDateToString(d);
+ * dateStr(d);
  * // -> "2025-03-07 09:04:02"
  * ```
  *
@@ -530,7 +530,7 @@ declare function floorDateToMinutes(everyMinutes?: number, date?: Date): Date;
  * @category Date & Time
  * @since 2.0.0
  */
-declare function formatDateToString(date?: Date): string;
+declare function dateStr(date?: Date): string;
 
 /**
  * Converts a partial {@link TimeParts} structure (days, hours, minutes, seconds)
@@ -564,38 +564,33 @@ declare function formatDateToString(date?: Date): string;
  * @example
  * ```ts
  * // Example 1: Simple conversion
- * partsToSeconds({ hours: 1, minutes: 30 }); // -> 5400
+ * datePartsSec({ hours: 1, minutes: 30 }); // -> 5400
  *
  * // Example 2: Full time span
- * partsToSeconds({ days: 2, hours: 3, minutes: 5, seconds: 10 });
+ * datePartsSec({ days: 2, hours: 3, minutes: 5, seconds: 10 });
  * // -> 183910
  *
  * // Example 3: Partial / missing fields
- * partsToSeconds({}); // -> 0
- * partsToSeconds({ minutes: 5 }); // -> 300
+ * datePartsSec({}); // -> 0
+ * datePartsSec({ minutes: 5 }); // -> 300
  * ```
  *
  * @throws Never throws.
  *
- * @see {@link secondsToParts} — the inverse operation that expands seconds back into components.
+ * @see {@link dateSecParts} — 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;
+declare function datePartsSec(parts: TimeParts): number;
 
 /**
  * Decomposes a total number of seconds into discrete time components:
  * **days**, **hours**, **minutes**, and **seconds**.
  *
  * @remarks
- * This is the inverse operation of {@link partsToSeconds}.
+ * This is the inverse operation of {@link datePartsSec}.
  * It converts a flat duration (in seconds) into a more human-readable structure
  * suitable for display, logging, or formatting.
  *
@@ -627,130 +622,35 @@ declare function partsToSeconds(parts: {
  * @example
  * ```ts
  * // Example 1: Basic conversion
- * secondsToParts(3661);
+ * dateSecParts(3661);
  * // -> { days: 0, hours: 1, minutes: 1, seconds: 1 }
  * ```
  *
  * @example
  * ```ts
  * // Example 2: Multi-day value
- * secondsToParts(90061);
+ * dateSecParts(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")
+ * dateSecParts(-10); // throws Error("Invalid total seconds")
+ * dateSecParts(NaN); // throws Error("Invalid total seconds")
  * ```
  *
  * @throws {Error}
  * Thrown when `total` is not a finite, non-negative number.
  *
- * @see {@link partsToSeconds} — the complementary function that aggregates components into seconds.
+ * @see {@link datePartsSec} — the complementary function that aggregates components into seconds.
  * @see {@link TimeParts} — the return type describing the breakdown of time.
  *
  * @public
  * @category Date & Time
  * @since 2.0.0
  */
-declare function 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;
+declare function dateSecParts(total: number): TimeParts;
 
 /**
  * Converts a dotted-decimal IPv4 address string (e.g. `"192.168.0.1"`)
@@ -783,20 +683,20 @@ declare function cidrToRange(cidr: string): [string, string] | null;
  * @example
  * ```ts
  * // Example 1: Simple conversion
- * ipAddrToNum("192.168.0.1");
+ * ipStrNum("192.168.0.1");
  * // -> 3232235521
  *
  * // Example 2: Edge values
- * ipAddrToNum("0.0.0.0");       // -> 0
- * ipAddrToNum("255.255.255.255"); // -> 4294967295
+ * ipStrNum("0.0.0.0");       // -> 0
+ * ipStrNum("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")
+ * ipStrNum("192.168.1");      // throws Error("Invalid IPv4 address")
+ * ipStrNum("256.0.0.1");      // throws Error("Invalid IPv4 address")
+ * ipStrNum("abc.def.ghi.jkl"); // throws Error("Invalid IPv4 address")
  * ```
  *
  * @throws {Error}
@@ -811,14 +711,14 @@ declare function cidrToRange(cidr: string): [string, string] | null;
  * @category Network & IP
  * @since 2.0.0
  */
-declare function ipAddrToNum(ip: string): number;
+declare function ipStrNum(ip: string): number;
 
 /**
  * Converts a 32-bit unsigned integer (numeric IPv4 representation)
  * back into its dotted-decimal string form (e.g. `"192.168.0.1"`).
  *
  * @remarks
- * This is the inverse of {@link ipAddrToNum}.
+ * This is the inverse of {@link ipStrNum}.
  * It interprets the input number as a **big-endian (network-byte-order)**
  * IPv4 value, extracting each of the four octets and joining them into
  * the standard dotted-quad notation.
@@ -832,7 +732,7 @@ declare function ipAddrToNum(ip: string): number;
  * - 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}.
+ * - For the forward direction (string → number), see {@link ipStrNum}.
  *
  * @param num - The 32-bit unsigned integer representing an IPv4 address.
  *
@@ -842,195 +742,32 @@ declare function ipAddrToNum(ip: string): number;
  * @example
  * ```ts
  * // Example 1: Basic conversion
- * numToIpAddr(3232235521);
+ * ipNumStr(3232235521);
  * // -> "192.168.0.1"
  *
  * // Example 2: Edge values
- * numToIpAddr(0);          // -> "0.0.0.0"
- * numToIpAddr(4294967295); // -> "255.255.255.255"
+ * ipNumStr(0);          // -> "0.0.0.0"
+ * ipNumStr(4294967295); // -> "255.255.255.255"
  * ```
  *
  * @example
  * ```ts
  * // Example 3: Invalid inputs
- * numToIpAddr(NaN);         // -> ""
- * numToIpAddr(Infinity);    // -> ""
- * numToIpAddr(-5);          // -> ""
+ * ipNumStr(NaN);         // -> ""
+ * ipNumStr(Infinity);    // -> ""
+ * ipNumStr(-5);          // -> ""
  * ```
  *
  * @throws Never throws; invalid inputs simply return an empty string.
  *
- * @see {@link ipAddrToNum} — converts dotted IPv4 strings to numeric form.
+ * @see {@link ipStrNum} — converts dotted IPv4 strings to numeric form.
  * @see {@link parseIPv4} — alternative parser using bitwise arithmetic.
  *
  * @public
  * @category Network & IP
  * @since 2.0.0
  */
-declare function 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;
+declare function ipNumStr(num: number): string;
 
 /**
  * Configuration options that define password validation rules.
@@ -2852,7 +2589,7 @@ type JSONLike = null | boolean | number | string | JSONLike[] | {
  * @remarks
  * The parsing order is:
  *
- * 1. Try JSON via {@link tryParseJSON}. If it works, return the parsed value.
+ * 1. Try JSON via {@link jsonParse}. If it works, return the parsed value.
  * 2. If not JSON, check if the string is quoted with `'`, `"` or `` ` ``.
  *    If quoted, return the **unquoted** inner text.
  * 3. If not quoted:
@@ -2869,15 +2606,15 @@ type JSONLike = null | boolean | number | string | JSONLike[] | {
  *
  * @example
  * ```ts
- * parseStringLike('{"a":1}', false); // -> { a: 1 }
- * parseStringLike('"hello"', false); // -> "hello"
- * parseStringLike('hello', false);   // -> null
- * parseStringLike('hello', true);    // -> "hello"
+ * jsonStrLike('{"a":1}', false); // -> { a: 1 }
+ * jsonStrLike('"hello"', false); // -> "hello"
+ * jsonStrLike('hello', false);   // -> null
+ * jsonStrLike('hello', true);    // -> "hello"
  * ```
  *
  * @internal
  */
-declare function parseStringLike(s: string, allowString: boolean): JSONLike | null;
+declare function jsonStrLike(s: string, allowString: boolean): JSONLike | null;
 
 /**
  * Attempts to parse a string using native {@link JSON.parse}.
@@ -2892,13 +2629,13 @@ declare function parseStringLike(s: string, allowString: boolean): JSONLike | nu
  *
  * @example
  * ```ts
- * tryParseJSON('{"a":1}'); // { ok: true, value: { a: 1 } }
- * tryParseJSON('not json'); // { ok: false }
+ * jsonParse('{"a":1}'); // { ok: true, value: { a: 1 } }
+ * jsonParse('not json'); // { ok: false }
  * ```
  *
  * @internal
  */
-declare function tryParseJSON(str: string): {
+declare function jsonParse(str: string): {
     ok: true;
     value: JSONLike;
 } | {
@@ -2914,10 +2651,10 @@ declare function tryParseJSON(str: string): {
  *
  * - **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`).
+ *   it via {@link jsonStrLike} (JSON → unquoted string → raw string if `allowString`).
  *   Non-string items are passed through unchanged (cast to `JSONLike`).
  * - **Arrays/Objects (empty)**: returned as-is (they’re valid JSON).
- * - **Standalone strings**: decoded via {@link parseStringLike}.
+ * - **Standalone strings**: decoded via {@link jsonStrLike}.
  * - **Other values**: return `null`.
  *
  * The function is **non-throwing**; any JSON parse errors are swallowed internally
@@ -3026,381 +2763,6 @@ declare function jsonDecode<T = JSONLike>(value: unknown, allowString?: boolean)
  */
 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.
@@ -3442,23 +2804,23 @@ declare function fixedDecimalToStr(value: FixedDecimal): string;
  *
  * @example
  * // No rounding (default `round = 1` → passthrough)
- * formatToNum("123.456");         // => 123.456
- * formatToNum(0.034);             // => 0.034
+ * numNormalize("123.456");         // => 123.456
+ * numNormalize(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)
+ * numNormalize("123.456", 2);      // => 123.46  (because .456 → .46)
+ * numNormalize("-1.235", 2);       // => -1.24   (half-up away from zero)
  *
  * @example
  * // Large values: parsed and rounded in fixed precision, then converted to number
- * formatToNum("234893249238948.000003432", 6); // precise rounding in fixed space,
+ * numNormalize("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)
+ * numNormalize("1000.555", 1);     // => 1000.555 (no rounding step invoked)
+ * numNormalize("1000.555", 0);     // => 1000.555 (still no rounding)
  *
  * @see parseToFixedDecimal
  * @see fixedDecimalToNum
@@ -3468,278 +2830,7 @@ declare function fixedDecimalToStr(value: FixedDecimal): string;
  * @since 2.0.0
  * @public
  */
-declare function formatToNum(value: unknown, round?: number, throwError?: boolean): 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;
+declare function numNormalize(value: unknown, round?: number, throwError?: boolean): number;
 
 /**
  * Converts any given string-like value into a lower-cased, trimmed string.
@@ -3755,7 +2846,7 @@ declare function roundFixedDecimal(source: FixedDecimal, decimalPlaces: number,
  * @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}.
+ * 2. **Trimming** — removes leading and trailing whitespace via {@link strTrim}.
  * 3. **Validation** — ensures the result is non-empty with {@link isStrFilled}.
  * 4. **Lowercasing** — calls `String.prototype.toLowerCase()` on the trimmed text.
  * 5. If the string is empty or not valid at any step, returns `""`.
@@ -3765,7 +2856,7 @@ declare function roundFixedDecimal(source: FixedDecimal, decimalPlaces: number,
  * - Non-string inputs (numbers, booleans, objects, arrays, `null`, `undefined`) all yield `""`.
  *
  * ### Use cases
- * - Case-insensitive string comparison (normalize both sides with `formatToLowerCase`).
+ * - Case-insensitive string comparison (normalize both sides with `strLowerCase`).
  * - Normalizing user input before storing or indexing.
  * - Simplifying logic where optional strings may be `null` or empty.
  *
@@ -3777,35 +2868,35 @@ declare function roundFixedDecimal(source: FixedDecimal, decimalPlaces: number,
  *
  * @example
  * // Basic strings
- * formatToLowerCase('HELLO');        // => "hello"
- * formatToLowerCase('  TEST ');      // => "test"
+ * strLowerCase('HELLO');        // => "hello"
+ * strLowerCase('  TEST ');      // => "test"
  *
  * @example
  * // Mixed types
- * formatToLowerCase(123);            // => ""
- * formatToLowerCase(true);           // => ""
- * formatToLowerCase(null);           // => ""
+ * strLowerCase(123);            // => ""
+ * strLowerCase(true);           // => ""
+ * strLowerCase(null);           // => ""
  *
  * @example
  * // Empty or whitespace inputs
- * formatToLowerCase('   ');          // => ""
- * formatToLowerCase('');             // => ""
+ * strLowerCase('   ');          // => ""
+ * strLowerCase('');             // => ""
  *
  * @example
  * // Already lowercase
- * formatToLowerCase('data');         // => "data"
+ * strLowerCase('data');         // => "data"
  *
  * @see isStr
  * @see isStrFilled
- * @see formatToTrim
+ * @see strTrim
  *
  * @category String
  * @public
  * @since 2.0.0
  */
-declare function formatToLowerCase(value?: unknown): string;
+declare function strLowerCase(value?: unknown): string;
 
-declare function formatToNormalCase(value?: unknown): string;
+declare function strNormalCase(value?: unknown): string;
 
 /**
  * Converts `undefined` or empty (whitespace-only) strings into `null`.
@@ -3821,14 +2912,14 @@ declare function formatToNormalCase(value?: unknown): string;
  * @returns
  * - `null` if:
  *   - The input is `undefined`, or
- *   - The input is a string that becomes empty after trimming (using {@link formatToTrim}).
+ *   - The input is a string that becomes empty after trimming (using {@link strTrim}).
  * - Otherwise returns the original `value`.
  *
  * @remarks
  * ### Processing steps
  * 1. If `value` is `undefined`, returns `null`.
  * 2. If `value` is a string:
- *    - Trims it with {@link formatToTrim}, removing whitespace and invisible characters.
+ *    - Trims it with {@link strTrim}, removing whitespace and invisible characters.
  *    - If the trimmed result is empty (`''`), returns `null`.
  * 3. Otherwise returns the original value unchanged.
  *
@@ -3837,8 +2928,8 @@ declare function formatToNormalCase(value?: unknown): string;
  * - 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` |
+ * ### Comparison with {@link strUndefined}
+ * | Case | `strNull` | `strUndefined` |
  * |------|----------------|----------------------|
  * | `undefined` | `null` | `undefined` |
  * | `''` (empty string) | `null` | `undefined` |
@@ -3858,34 +2949,34 @@ declare function formatToNormalCase(value?: unknown): string;
  *
  * @example
  * // Empty and whitespace strings
- * formatToNull('');          // => null
- * formatToNull('   ');       // => null
+ * strNull('');          // => null
+ * strNull('   ');       // => null
  *
  * @example
  * // Undefined also becomes null
- * formatToNull(undefined);   // => null
+ * strNull(undefined);   // => null
  *
  * @example
  * // Non-empty strings remain as-is
- * formatToNull('Hello');     // => "Hello"
- * formatToNull('  Data ');   // => "  Data "
+ * strNull('Hello');     // => "Hello"
+ * strNull('  Data ');   // => "  Data "
  *
  * @example
  * // Non-string types are preserved
- * formatToNull(0);           // => 0
- * formatToNull(false);       // => false
- * formatToNull([]);          // => []
- * formatToNull({});          // => {}
+ * strNull(0);           // => 0
+ * strNull(false);       // => false
+ * strNull([]);          // => []
+ * strNull({});          // => {}
  *
  * @see isStr
- * @see formatToTrim
- * @see formatToUndefined
+ * @see strTrim
+ * @see strUndefined
  *
  * @category String
  * @public
  * @since 2.0.0
  */
-declare function formatToNull(value: unknown): {} | null;
+declare function strNull(value: unknown): {} | null;
 
 /**
  * Normalizes and validates a phone number into international format (`E.164` style).
@@ -3978,7 +3069,7 @@ declare function formatToNull(value: unknown): {} | null;
  * formatToPhone(true);                    // => null
  *
  * @see isStr
- * @see formatToTrim
+ * @see strTrim
  *
  * @category String
  * @public
@@ -4043,23 +3134,23 @@ declare function formatToPhone(value?: unknown, defaultCountry?: string): string
  *
  * @example
  * // Basic trimming
- * formatToTrim('  Hello  ');            // => "Hello"
+ * strTrim('  Hello  ');            // => "Hello"
  *
  * @example
  * // Removes zero-width characters
- * formatToTrim('word\u200B');           // => "word"
+ * strTrim('word\u200B');           // => "word"
  *
  * @example
  * // Unicode normalization
- * formatToTrim('ＡＢＣ');               // => "ABC"
- * formatToTrim('e\u0301');              // => "é"
+ * strTrim('ＡＢＣ');               // => "ABC"
+ * strTrim('e\u0301');              // => "é"
  *
  * @example
  * // Non-string inputs
- * formatToTrim(123);                    // => ""
- * formatToTrim(null);                   // => ""
- * formatToTrim(undefined);              // => ""
- * formatToTrim({ text: 'hi' });         // => ""
+ * strTrim(123);                    // => ""
+ * strTrim(null);                   // => ""
+ * strTrim(undefined);              // => ""
+ * strTrim({ text: 'hi' });         // => ""
  *
  * @see isStr
  * @see String.prototype.normalize
@@ -4068,7 +3159,7 @@ declare function formatToPhone(value?: unknown, defaultCountry?: string): string
  * @public
  * @since 2.0.0
  */
-declare function formatToTrim(value: unknown): string;
+declare function strTrim(value: unknown): string;
 
 /**
  * Converts `null` or empty (whitespace-only) strings into `undefined`.
@@ -4084,25 +3175,25 @@ declare function formatToTrim(value: unknown): string;
  * @returns
  * - `undefined` if:
  *   - The value is `null`, or
- *   - The value is a string that becomes empty after trimming (via {@link formatToTrim}).
+ *   - The value is a string that becomes empty after trimming (via {@link strTrim}).
  * - Otherwise returns the original value.
  *
  * @remarks
  * ### Processing steps
  * 1. If `value` is `null`, return `undefined`.
  * 2. If `value` is a string:
- *    - Trim using {@link formatToTrim} to remove whitespace and invisible characters.
+ *    - Trim using {@link strTrim} to remove whitespace and invisible characters.
  *    - If trimmed result is empty, return `undefined`.
  * 3. Otherwise, return the original value unchanged.
  *
  * ### Behavior notes
  * - Non-string, non-null values (`0`, `false`, `{}`, `[]`, etc.) are **not modified**.
  * - The function is **non-mutating** — it never changes the original reference.
- * - It complements {@link formatToNull}, depending on whether your system
+ * - It complements {@link strNull}, depending on whether your system
  *   prefers `undefined` (omit field) or `null` (explicit empty value).
  *
- * ### Comparison with {@link formatToNull}
- * | Case | `formatToNull` | `formatToUndefined` |
+ * ### Comparison with {@link strNull}
+ * | Case | `strNull` | `strUndefined` |
  * |------|----------------|----------------------|
  * | `null` | `null` | `undefined` |
  * | `undefined` | `null` | `undefined` |
@@ -4124,376 +3215,42 @@ declare function formatToTrim(value: unknown): string;
  *
  * @example
  * // Empty and whitespace-only strings
- * formatToUndefined('');        // => undefined
- * formatToUndefined('   ');     // => undefined
+ * strUndefined('');        // => undefined
+ * strUndefined('   ');     // => undefined
  *
  * @example
  * // null is also normalized
- * formatToUndefined(null);      // => undefined
+ * strUndefined(null);      // => undefined
  *
  * @example
  * // Non-empty strings remain unchanged
- * formatToUndefined('Hello');   // => "Hello"
+ * strUndefined('Hello');   // => "Hello"
  *
  * @example
  * // Non-string types are preserved
- * formatToUndefined(0);         // => 0
- * formatToUndefined(false);     // => false
- * formatToUndefined([]);        // => []
- * formatToUndefined({});        // => {}
+ * strUndefined(0);         // => 0
+ * strUndefined(false);     // => false
+ * strUndefined([]);        // => []
+ * strUndefined({});        // => {}
  *
  * @see isStr
- * @see formatToTrim
- * @see formatToNull
+ * @see strTrim
+ * @see strNull
  *
  * @category String
  * @public
  * @since 2.0.0
  */
-declare function formatToUndefined(value: unknown): {} | undefined;
+declare function strUndefined(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;
+type UrlObj = {
+    protocol: string;
+    user: string;
+    url: string;
+    port: number;
+    path: string;
+};
 
-/**
- * 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;
+declare function urlObj(value?: string): UrlObj;
 
-export { type FixedDecimal, type JSONLike, type PasswordOptions, type RangeIPv4Options, type TimeParts, changeFixedDecimalScale, cidrToRange, convertExponentialToParts, extractHost, fixedDecimalToNum, fixedDecimalToStr, floorDateToMinutes, formatDateToString, formatStrToFuncArgsArr, formatToBool, formatToLowerCase, formatToNormalCase, formatToNull, formatToNum, formatToPhone, formatToTrim, formatToUndefined, ipAddrToNum, isArr, isArrFilled, isBool, isClass, 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 };
+export { type JSONLike, type PasswordOptions, type TimeParts, arrFuncArgs, arrSplitPortions, boolNormalize, dateFloorMin, datePartsSec, dateSecParts, dateStr, formatToPhone, ipNumStr, ipStrNum, isArr, isArrFilled, isBool, isClass, isDate, isEmail, isExists, isFunc, isIpAddr, isMacAddr, isNum, isNumFloat, isNumN, isNumNZ, isNumP, isNumPZ, isObj, isObjFilled, isPassword, isPhone, isStr, isStrAscDesc, isStrBool, isStrFilled, isVar, jsonDecode, jsonEncode, jsonParse, jsonStrLike, numNormalize, strLowerCase, strNormalCase, strNull, strTrim, strUndefined, urlObj, wait };