stringzy 4.1.0 → 4.2.0

package/dist/analyzing/checkMultiplePatterns.d.ts

@@ -1,9 +1,9 @@
 /**
- * Finds occurrences of multiple patterns within a given text using Rabin–Karp algorithm.
+ * Finds occurrences of multiple patterns within a given text using Aho–Corasick algorithm.
  *
  * - Accepts an array of patterns.
  * - Returns all matches of each pattern along with starting indices.
- * - Handles hash collisions by verifying actual substrings.
+ * - Handles overlapping matches.
  * - Is case sensitive
  *
  * @param {string} text - The text to search within.

package/dist/analyzing/checkMultiplePatterns.js

@@ -1,10 +1,10 @@
 "use strict";
 /**
- * Finds occurrences of multiple patterns within a given text using Rabin–Karp algorithm.
+ * Finds occurrences of multiple patterns within a given text using Aho–Corasick algorithm.
  *
  * - Accepts an array of patterns.
  * - Returns all matches of each pattern along with starting indices.
- * - Handles hash collisions by verifying actual substrings.
+ * - Handles overlapping matches.
  * - Is case sensitive
  *
  * @param {string} text - The text to search within.
@@ -25,38 +25,50 @@ function checkMultiplePatterns(text, patterns) {
     if (text.length === 0 || patterns.length === 0) {
         return result;
     }
-    const prime = 101; // A prime base for hashing
-    const getHash = (str, m) => {
-        let h = 0;
-        for (let i = 0; i < m; i++) {
-            h = (h * 256 + str.charCodeAt(i)) % prime;
-        }
-        return h;
-    };
-    const recomputeHash = (oldHash, dropped, added, m) => {
-        let h = (oldHash - dropped.charCodeAt(0) * Math.pow(256, m - 1)) % prime;
-        h = (h * 256 + added.charCodeAt(0)) % prime;
-        if (h < 0)
-            h += prime;
-        return h;
-    };
+    const root = { next: {}, fail: null, output: [] };
     for (const pattern of patterns) {
-        const m = pattern.length;
+        let node = root;
+        for (const ch of pattern) {
+            if (!node.next[ch])
+                node.next[ch] = { next: {}, fail: null, output: [] };
+            node = node.next[ch];
+        }
+        node.output.push(pattern);
         result[pattern] = [];
-        if (m === 0 || m > text.length)
-            continue;
-        const patternHash = getHash(pattern, m);
-        let windowHash = getHash(text, m);
-        for (let i = 0; i <= text.length - m; i++) {
-            if (patternHash === windowHash) {
-                // Verify to avoid collision false positives
-                if (text.slice(i, i + m) === pattern) {
-                    result[pattern].push(i);
-                }
-            }
-            if (i < text.length - m) {
-                windowHash = recomputeHash(windowHash, text[i], text[i + m], m);
+    }
+    const queue = [];
+    for (const ch in root.next) {
+        const node = root.next[ch];
+        node.fail = root;
+        queue.push(node);
+    }
+    while (queue.length) {
+        const current = queue.shift();
+        for (const ch in current.next) {
+            const child = current.next[ch];
+            let fail = current.fail;
+            // Find deepest fail link with the same transition
+            while (fail && !fail.next[ch]) {
+                fail = fail.fail;
             }
+            child.fail = fail ? fail.next[ch] : root;
+            child.output = child.output.concat(child.fail.output);
+            queue.push(child);
+        }
+    }
+    let node = root;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        while (node && !node.next[ch]) {
+            node = node.fail;
+        }
+        if (!node) {
+            node = root;
+            continue;
+        }
+        node = node.next[ch];
+        for (const pattern of node.output) {
+            result[pattern].push(i - pattern.length + 1);
         }
     }
     return result;

package/dist/analyzing/index.d.ts

@@ -11,6 +11,7 @@ export { checkSubsequence } from './checkSubsequence';
 export { functionWordCount } from './functionWordCount';
 export { contentWordCount } from './contentWordCount';
 export { checkStringRotations } from './stringRotation';
+export { lexicographicalRank } from './lexicographicalRank';
 import { characterCount } from './characterCount';
 import { characterFrequency } from './characterFrequency';
 import { complexity } from './complexity';
@@ -22,6 +23,7 @@ import { vowelConsonantCount } from './vowelConsonantCount';
 import { checkMultiplePatterns } from './checkMultiplePatterns';
 import { checkSubsequence } from './checkSubsequence';
 import { checkStringRotations } from './stringRotation';
+import { lexicographicalRank } from './lexicographicalRank';
 export declare const analyzing: {
     characterCount: typeof characterCount;
     characterFrequency: typeof characterFrequency;
@@ -34,4 +36,5 @@ export declare const analyzing: {
     checkMultiplePatterns: typeof checkMultiplePatterns;
     checkSubsequence: typeof checkSubsequence;
     checkStringRotations: typeof checkStringRotations;
+    lexicographicalRank: typeof lexicographicalRank;
 };

package/dist/analyzing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analyzing = exports.checkStringRotations = exports.contentWordCount = exports.functionWordCount = exports.checkSubsequence = exports.checkMultiplePatterns = exports.vowelConsonantCount = exports.patternCount = exports.stringSimilarity = exports.wordCount = exports.readingDuration = exports.complexity = exports.characterFrequency = exports.characterCount = void 0;
+exports.analyzing = exports.lexicographicalRank = exports.checkStringRotations = exports.contentWordCount = exports.functionWordCount = exports.checkSubsequence = exports.checkMultiplePatterns = exports.vowelConsonantCount = exports.patternCount = exports.stringSimilarity = exports.wordCount = exports.readingDuration = exports.complexity = exports.characterFrequency = exports.characterCount = void 0;
 var characterCount_1 = require("./characterCount");
 Object.defineProperty(exports, "characterCount", { enumerable: true, get: function () { return characterCount_1.characterCount; } });
 var characterFrequency_1 = require("./characterFrequency");
@@ -27,6 +27,8 @@ var contentWordCount_1 = require("./contentWordCount");
 Object.defineProperty(exports, "contentWordCount", { enumerable: true, get: function () { return contentWordCount_1.contentWordCount; } });
 var stringRotation_1 = require("./stringRotation");
 Object.defineProperty(exports, "checkStringRotations", { enumerable: true, get: function () { return stringRotation_1.checkStringRotations; } });
+var lexicographicalRank_1 = require("./lexicographicalRank");
+Object.defineProperty(exports, "lexicographicalRank", { enumerable: true, get: function () { return lexicographicalRank_1.lexicographicalRank; } });
 const characterCount_2 = require("./characterCount");
 const characterFrequency_2 = require("./characterFrequency");
 const complexity_2 = require("./complexity");
@@ -38,6 +40,7 @@ const vowelConsonantCount_2 = require("./vowelConsonantCount");
 const checkMultiplePatterns_2 = require("./checkMultiplePatterns");
 const checkSubsequence_2 = require("./checkSubsequence");
 const stringRotation_2 = require("./stringRotation");
+const lexicographicalRank_2 = require("./lexicographicalRank");
 exports.analyzing = {
     characterCount: characterCount_2.characterCount,
     characterFrequency: characterFrequency_2.characterFrequency,
@@ -49,5 +52,6 @@ exports.analyzing = {
     vowelConsonantCount: vowelConsonantCount_2.vowelConsonantCount,
     checkMultiplePatterns: checkMultiplePatterns_2.checkMultiplePatterns,
     checkSubsequence: checkSubsequence_2.checkSubsequence,
-    checkStringRotations: stringRotation_2.checkStringRotations
+    checkStringRotations: stringRotation_2.checkStringRotations,
+    lexicographicalRank: lexicographicalRank_2.lexicographicalRank
 };

package/dist/analyzing/lexicographicalRank.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Calculates the lexicographic rank of a string among all its unique permutations.
+ *
+ * The rank is 1-based (i.e., the first permutation has rank 1).
+ * Handles strings with duplicate characters correctly by adjusting for repetition.
+ *
+ * @param {string} str - The input string.
+ * @returns {number} The 1-based lexicographic rank of the string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * lexicographicRank("acb"); // 2
+ *
+ * @example
+ * lexicographicRank("string"); // 598
+ *
+ * @example
+ * lexicographicRank("cba"); // 6
+ *
+ * @example
+ * lexicographicRank("aba"); // 2
+ *
+ * @example
+ * lexicographicRank("a"); // 1
+ */
+export declare function lexicographicalRank(str: string): number;

package/dist/analyzing/lexicographicalRank.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lexicographicalRank = lexicographicalRank;
+/**
+ * Calculates the lexicographic rank of a string among all its unique permutations.
+ *
+ * The rank is 1-based (i.e., the first permutation has rank 1).
+ * Handles strings with duplicate characters correctly by adjusting for repetition.
+ *
+ * @param {string} str - The input string.
+ * @returns {number} The 1-based lexicographic rank of the string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * lexicographicRank("acb"); // 2
+ *
+ * @example
+ * lexicographicRank("string"); // 598
+ *
+ * @example
+ * lexicographicRank("cba"); // 6
+ *
+ * @example
+ * lexicographicRank("aba"); // 2
+ *
+ * @example
+ * lexicographicRank("a"); // 1
+ */
+function lexicographicalRank(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    if (str.length === 0)
+        return 1;
+    const factorial = (n) => (n <= 1 ? 1 : n * factorial(n - 1));
+    const charCount = {};
+    for (const ch of str) {
+        charCount[ch] = (charCount[ch] || 0) + 1;
+    }
+    const chars = Object.keys(charCount).sort();
+    let rank = 1;
+    for (let i = 0; i < str.length; i++) {
+        const ch = str[i];
+        for (const smaller of chars) {
+            if (smaller >= ch)
+                break;
+            if (charCount[smaller] > 0) {
+                charCount[smaller]--;
+                let denom = 1;
+                const remaining = str.length - i - 1;
+                for (const count of Object.values(charCount)) {
+                    denom *= factorial(count);
+                }
+                rank += factorial(remaining) / denom;
+                charCount[smaller]++;
+            }
+        }
+        if (charCount[ch] > 0) {
+            charCount[ch]--;
+        }
+        else {
+            break; // shouldn't happen unless str has invalid chars
+        }
+    }
+    return rank;
+}

package/dist/formatting/binary.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Converts a decimal integer to its binary (base-2) string representation.
+ *
+ * - Supports negative numbers (prefixed with '-')
+ * - Optional grouping from the least significant bit for readability
+ *
+ * Examples:
+ * 5   → "101"
+ * 10  → "1010"
+ * 255 → "11111111"
+ * 0   → "0"
+ *
+ * Grouping examples (from right to left):
+ * formatToBinary(255, { group: 4 }) → "1111 1111"
+ * formatToBinary(10, { group: 2 })  → "10 10"
+ *
+ * @param {number} num - The decimal integer to convert.
+ * @param {{ group?: number }} [options] - Optional grouping configuration.
+ * @returns {string} The binary string representation.
+ * @throws {TypeError} If input is not a number, is NaN, or not an integer.
+ */
+export declare function formatToBinary(num: number, options?: {
+    group?: number;
+}): string;

package/dist/formatting/binary.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToBinary = formatToBinary;
+/**
+ * Converts a decimal integer to its binary (base-2) string representation.
+ *
+ * - Supports negative numbers (prefixed with '-')
+ * - Optional grouping from the least significant bit for readability
+ *
+ * Examples:
+ * 5   → "101"
+ * 10  → "1010"
+ * 255 → "11111111"
+ * 0   → "0"
+ *
+ * Grouping examples (from right to left):
+ * formatToBinary(255, { group: 4 }) → "1111 1111"
+ * formatToBinary(10, { group: 2 })  → "10 10"
+ *
+ * @param {number} num - The decimal integer to convert.
+ * @param {{ group?: number }} [options] - Optional grouping configuration.
+ * @returns {string} The binary string representation.
+ * @throws {TypeError} If input is not a number, is NaN, or not an integer.
+ */
+function formatToBinary(num, options) {
+    if (typeof num !== 'number' || Number.isNaN(num)) {
+        throw new TypeError('Input must be a number');
+    }
+    if (!Number.isInteger(num)) {
+        throw new TypeError('Input must be an integer');
+    }
+    const isNegative = num < 0;
+    const absoluteValue = Math.abs(num);
+    // Handle zero explicitly to avoid "-0" or empty strings
+    const core = absoluteValue.toString(2);
+    const groupSize = options === null || options === void 0 ? void 0 : options.group;
+    if (groupSize !== undefined) {
+        if (typeof groupSize !== 'number' ||
+            Number.isNaN(groupSize) ||
+            !Number.isInteger(groupSize) ||
+            groupSize <= 0) {
+            throw new TypeError('Group size must be a positive integer');
+        }
+    }
+    const grouped = groupSize && core.length > groupSize
+        ? core.replace(new RegExp(`\\B(?=(\\d{${groupSize}})+(?!\\d))`, 'g'), ' ')
+        : core;
+    return isNegative ? `-${grouped}` : grouped;
+}

package/dist/formatting/creditCard.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a credit card number by grouping digits into readable parts.
+ *
+ * @param {string} cardNumber - The credit card number to format.
+ * @returns {string} The formatted credit card number.
+ * @throws {TypeError} If the input is not a string.
+ */
+export declare function formatCreditCard(cardNumber: string): string;

package/dist/formatting/creditCard.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCreditCard = formatCreditCard;
+/**
+ * Formats a credit card number by grouping digits into readable parts.
+ *
+ * @param {string} cardNumber - The credit card number to format.
+ * @returns {string} The formatted credit card number.
+ * @throws {TypeError} If the input is not a string.
+ */
+function formatCreditCard(cardNumber) {
+    if (typeof cardNumber !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    // Remove all non-digit characters
+    const cleaned = cardNumber.replace(/\D/g, '');
+    // Only accept 15 or 16 digit card numbers
+    if (cleaned.length !== 15 && cleaned.length !== 16) {
+        return '';
+    }
+    // Format based on length:
+    // 16 digits → 4-4-4-4 (Visa, MasterCard)
+    if (cleaned.length === 16) {
+        return cleaned.replace(/(\d{4})(?=\d)/g, '$1 ').trim();
+    }
+    // 15 digits → 4-6-5 (AmEx)
+    return cleaned.replace(/(\d{4})(\d{6})(\d{5})/, '$1 $2 $3');
+}

package/dist/formatting/decimal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Converts a string in base 2, 8, or 16 to its decimal (base-10) number.
+ *
+ * - Supports optional standard prefixes: 0b, 0o, 0x (case-insensitive)
+ * - Trims leading/trailing whitespace
+ * - Supports uppercase and lowercase characters for hexadecimal
+ *
+ * Examples:
+ * formatToDecimal('1010', { base: 2 }) → 10
+ * formatToDecimal('12', { base: 8 })   → 10
+ * formatToDecimal('FF', { base: 16 })  → 255
+ * formatToDecimal('0xFF', { base: 16 })→ 255
+ *
+ * @param {string} value - The input string representing a number in the given base.
+ * @param {{ base: 2 | 8 | 16 }} options - Options containing the base of the input string.
+ * @returns {number} The decimal (base-10) representation.
+ * @throws {TypeError} For non-string inputs, unsupported bases, or malformed values.
+ */
+export declare function formatToDecimal(value: string, options: {
+    base: 2 | 8 | 16;
+}): number;

package/dist/formatting/decimal.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToDecimal = formatToDecimal;
+/**
+ * Converts a string in base 2, 8, or 16 to its decimal (base-10) number.
+ *
+ * - Supports optional standard prefixes: 0b, 0o, 0x (case-insensitive)
+ * - Trims leading/trailing whitespace
+ * - Supports uppercase and lowercase characters for hexadecimal
+ *
+ * Examples:
+ * formatToDecimal('1010', { base: 2 }) → 10
+ * formatToDecimal('12', { base: 8 })   → 10
+ * formatToDecimal('FF', { base: 16 })  → 255
+ * formatToDecimal('0xFF', { base: 16 })→ 255
+ *
+ * @param {string} value - The input string representing a number in the given base.
+ * @param {{ base: 2 | 8 | 16 }} options - Options containing the base of the input string.
+ * @returns {number} The decimal (base-10) representation.
+ * @throws {TypeError} For non-string inputs, unsupported bases, or malformed values.
+ */
+function formatToDecimal(value, options) {
+    if (typeof value !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const base = options === null || options === void 0 ? void 0 : options.base;
+    if (base !== 2 && base !== 8 && base !== 16) {
+        throw new TypeError('Base must be one of 2, 8, or 16');
+    }
+    let trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new TypeError('Input must be a non-empty string');
+    }
+    // Optional sign support; not required by spec but harmless and intuitive
+    let isNegative = false;
+    if (trimmed.startsWith('+') || trimmed.startsWith('-')) {
+        isNegative = trimmed[0] === '-';
+        trimmed = trimmed.slice(1);
+        if (trimmed.length === 0) {
+            throw new TypeError('Malformed numeric string');
+        }
+    }
+    // Strip standard prefixes if present and base matches
+    const prefix = trimmed.slice(0, 2).toLowerCase();
+    if (prefix === '0b' && base === 2) {
+        trimmed = trimmed.slice(2);
+    }
+    else if (prefix === '0o' && base === 8) {
+        trimmed = trimmed.slice(2);
+    }
+    else if (prefix === '0x' && base === 16) {
+        trimmed = trimmed.slice(2);
+    }
+    if (trimmed.length === 0) {
+        throw new TypeError('Malformed numeric string');
+    }
+    // Validate characters for the specified base
+    let pattern;
+    if (base === 2) {
+        pattern = /^[01]+$/;
+    }
+    else if (base === 8) {
+        pattern = /^[0-7]+$/;
+    }
+    else {
+        pattern = /^[0-9a-fA-F]+$/;
+    }
+    if (!pattern.test(trimmed)) {
+        throw new TypeError('Input contains invalid characters for the specified base');
+    }
+    const parsed = parseInt(trimmed, base);
+    return isNegative ? -parsed : parsed;
+}

package/dist/formatting/duration.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a duration in seconds or milliseconds into a human-readable string.
+ * Intelligently displays hours, minutes, seconds, and optionally milliseconds,
+ * while skipping zero-value units unless the entire duration is zero.
+ *
+ * @param {number} input - The duration in seconds or milliseconds.
+ * @param {object} [options] - Configuration options.
+ * @param {string} [options.unit='seconds'] - The input unit: 'seconds' or 'milliseconds'.
+ * @param {string} [options.format='short'] - Output format: 'short', 'medium', or 'long'.
+ * @param {boolean} [options.includeMs=false] - Whether to include milliseconds in the output.
+ * @param {string} [options.delimiter=' '] - The delimiter between time units.
+ * @returns {string} The formatted duration string.
+ * @throws {TypeError} If input is not a number or is negative.
+ *
+ * @example
+ * formatDuration(60);        // "1m"
+ * formatDuration(61);        // "1m 1s"
+ * formatDuration(3661);      // "1h 1m 1s"
+ * formatDuration(1234567, { unit: 'milliseconds', includeMs: true }); // "20m 34s 567ms"
+ * formatDuration(3600, { format: 'long' }); // "1 hour"
+ */
+export declare function formatDuration(input: number, options?: {
+    unit?: 'seconds' | 'milliseconds';
+    format?: 'short' | 'medium' | 'long';
+    includeMs?: boolean;
+    delimiter?: string;
+}): string;

package/dist/formatting/duration.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDuration = formatDuration;
+/**
+ * Converts a duration in seconds or milliseconds into a human-readable string.
+ * Intelligently displays hours, minutes, seconds, and optionally milliseconds,
+ * while skipping zero-value units unless the entire duration is zero.
+ *
+ * @param {number} input - The duration in seconds or milliseconds.
+ * @param {object} [options] - Configuration options.
+ * @param {string} [options.unit='seconds'] - The input unit: 'seconds' or 'milliseconds'.
+ * @param {string} [options.format='short'] - Output format: 'short', 'medium', or 'long'.
+ * @param {boolean} [options.includeMs=false] - Whether to include milliseconds in the output.
+ * @param {string} [options.delimiter=' '] - The delimiter between time units.
+ * @returns {string} The formatted duration string.
+ * @throws {TypeError} If input is not a number or is negative.
+ *
+ * @example
+ * formatDuration(60);        // "1m"
+ * formatDuration(61);        // "1m 1s"
+ * formatDuration(3661);      // "1h 1m 1s"
+ * formatDuration(1234567, { unit: 'milliseconds', includeMs: true }); // "20m 34s 567ms"
+ * formatDuration(3600, { format: 'long' }); // "1 hour"
+ */
+function formatDuration(input, options) {
+    // Validate input
+    if (typeof input !== 'number' || isNaN(input)) {
+        throw new TypeError('Input must be a number');
+    }
+    if (input < 0) {
+        throw new TypeError('Input must be non-negative');
+    }
+    // Default options
+    const opts = {
+        unit: (options === null || options === void 0 ? void 0 : options.unit) || 'seconds',
+        format: (options === null || options === void 0 ? void 0 : options.format) || 'short',
+        includeMs: (options === null || options === void 0 ? void 0 : options.includeMs) || false,
+        delimiter: (options === null || options === void 0 ? void 0 : options.delimiter) || ' '
+    };
+    // Convert to milliseconds
+    const totalMs = opts.unit === 'seconds' ? input * 1000 : input;
+    // Handle zero case
+    if (totalMs === 0) {
+        return '0s';
+    }
+    // Calculate time components
+    let remaining = Math.floor(totalMs);
+    const ms = remaining % 1000;
+    remaining = Math.floor(remaining / 1000);
+    const seconds = remaining % 60;
+    remaining = Math.floor(remaining / 60);
+    const minutes = remaining % 60;
+    const hours = Math.floor(remaining / 60);
+    // Build the output parts
+    const parts = [];
+    // Add non-zero units
+    if (hours > 0) {
+        parts.push(formatTimeUnit(hours, 'h', opts.format));
+    }
+    if (minutes > 0) {
+        parts.push(formatTimeUnit(minutes, 'm', opts.format));
+    }
+    if (seconds > 0 || (parts.length === 0 && !opts.includeMs)) {
+        parts.push(formatTimeUnit(seconds, 's', opts.format));
+    }
+    if (opts.includeMs && ms > 0) {
+        parts.push(formatTimeUnit(ms, 'ms', opts.format));
+    }
+    return parts.join(opts.delimiter);
+}
+/**
+ * Formats a single time unit according to the specified format.
+ * @private
+ */
+function formatTimeUnit(value, unit, format) {
+    switch (format) {
+        case 'long':
+            const unitNames = {
+                'h': ['hour', 'hours'],
+                'm': ['minute', 'minutes'],
+                's': ['second', 'seconds'],
+                'ms': ['millisecond', 'milliseconds']
+            };
+            const [singular, plural] = unitNames[unit];
+            return `${value} ${value === 1 ? singular : plural}`;
+        case 'medium':
+            const paddedValue = unit === 'h' ? value : value.toString().padStart(2, '0');
+            return `${paddedValue}${unit}`;
+        default: // 'short'
+            return `${value}${unit}`;
+    }
+}

package/dist/formatting/fileSize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a number of bytes into a human-readable file size string (B, KB, MB, GB, TB).
+ *
+ * Supports values from bytes up to terabytes, with automatic unit scaling and correct rounding.
+ *
+ * Examples:
+ * 123 → "123 B"
+ * 1024 → "1 KB"
+ * 1048576 → "1 MB"
+ * 1073741824 → "1 GB"
+ * 1572864 → "1.5 MB"
+ *
+ * @param {number} bytes - The number of bytes to convert.
+ * @param {number} [precision=2] - The number of decimal places to include for non-integer conversions.
+ * @returns {string} The formatted file size string with units.
+ * @throws {TypeError} If the input is not a number or precision is not a valid number.
+ */
+export declare function formatFileSize(bytes: number, precision?: number): string;

package/dist/formatting/fileSize.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFileSize = formatFileSize;
+/**
+ * Converts a number of bytes into a human-readable file size string (B, KB, MB, GB, TB).
+ *
+ * Supports values from bytes up to terabytes, with automatic unit scaling and correct rounding.
+ *
+ * Examples:
+ * 123 → "123 B"
+ * 1024 → "1 KB"
+ * 1048576 → "1 MB"
+ * 1073741824 → "1 GB"
+ * 1572864 → "1.5 MB"
+ *
+ * @param {number} bytes - The number of bytes to convert.
+ * @param {number} [precision=2] - The number of decimal places to include for non-integer conversions.
+ * @returns {string} The formatted file size string with units.
+ * @throws {TypeError} If the input is not a number or precision is not a valid number.
+ */
+function formatFileSize(bytes, precision = 2) {
+    if (typeof bytes !== 'number' || Number.isNaN(bytes)) {
+        throw new TypeError('Input must be a number');
+    }
+    if (typeof precision !== 'number' || Number.isNaN(precision) || precision < 0) {
+        throw new TypeError('Precision must be a non-negative number');
+    }
+    if (bytes < 0) {
+        throw new RangeError('File size cannot be negative');
+    }
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    if (bytes === 0)
+        return `0 B`;
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    // ✅ Fix: trim trailing zeros by converting to number before string
+    const rounded = value % 1 === 0 ? value.toString() : parseFloat(value.toFixed(precision)).toString();
+    return `${rounded} ${units[i]}`;
+}

package/dist/formatting/hexadecimal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts a decimal number to its hexadecimal (base-16) representation.
+ *
+ * @param {number} num - The decimal number to convert.
+ * @param {object} [options] - Optional formatting options.
+ * @param {boolean} [options.prefix=false] - Whether to add "0x" before the result.
+ * @param {boolean} [options.lowercase=false] - Whether to return hexadecimal in lowercase.
+ * @returns {string} The hexadecimal representation of the number.
+ * @throws {TypeError} If the input is not a valid number.
+ */
+export declare function formatToHexadecimal(num: number, options?: {
+    prefix?: boolean;
+    lowercase?: boolean;
+}): string;