stringzy 4.0.0 → 4.2.0

package/dist/analyzing/checkMultiplePatterns.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 overlapping matches.
+ * - Is case sensitive
+ *
+ * @param {string} text - The text to search within.
+ * @param {string[]} patterns - The array of patterns to search for.
+ * @returns {Record<string, number[]>} An object mapping each pattern to an array of match indices.
+ * @throws {TypeError} If input types are invalid.
+ */
+export declare function checkMultiplePatterns(text: string, patterns: string[]): Record<string, number[]>;

package/dist/analyzing/checkMultiplePatterns.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * 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 overlapping matches.
+ * - Is case sensitive
+ *
+ * @param {string} text - The text to search within.
+ * @param {string[]} patterns - The array of patterns to search for.
+ * @returns {Record<string, number[]>} An object mapping each pattern to an array of match indices.
+ * @throws {TypeError} If input types are invalid.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkMultiplePatterns = checkMultiplePatterns;
+function checkMultiplePatterns(text, patterns) {
+    if (typeof text !== 'string') {
+        throw new TypeError('Text must be a string');
+    }
+    if (!Array.isArray(patterns) || !patterns.every(p => typeof p === 'string')) {
+        throw new TypeError('Patterns must be an array of strings');
+    }
+    const result = {};
+    if (text.length === 0 || patterns.length === 0) {
+        return result;
+    }
+    const root = { next: {}, fail: null, output: [] };
+    for (const pattern of patterns) {
+        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] = [];
+    }
+    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/checkSubsequence.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks whether the second string is a subsequence of the first string.
+ *
+ * A subsequence means all characters of the second string appear in the first string
+ * in the same relative order, but not necessarily consecutively.
+ *
+ * Is case sensitive
+ *
+ * @param {string} str1 - The string to check against.
+ * @param {string} str2 - The candidate subsequence.
+ * @returns {boolean} True if str2 is a subsequence of str1, otherwise false.
+ * @throws {TypeError} If either input is not a string.
+ */
+export declare function checkSubsequence(str1: string, str2: string): boolean;

package/dist/analyzing/checkSubsequence.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSubsequence = checkSubsequence;
+/**
+ * Checks whether the second string is a subsequence of the first string.
+ *
+ * A subsequence means all characters of the second string appear in the first string
+ * in the same relative order, but not necessarily consecutively.
+ *
+ * Is case sensitive
+ *
+ * @param {string} str1 - The string to check against.
+ * @param {string} str2 - The candidate subsequence.
+ * @returns {boolean} True if str2 is a subsequence of str1, otherwise false.
+ * @throws {TypeError} If either input is not a string.
+ */
+function checkSubsequence(str1, str2) {
+    if (typeof str1 !== "string" || typeof str2 !== "string") {
+        throw new TypeError("Both inputs must be strings");
+    }
+    // empty subsequence is always valid
+    if (str2 === "")
+        return true;
+    let i = 0; // pointer for str2 (the subsequence)
+    let j = 0; // pointer for str1 (the main string)
+    while (i < str2.length && j < str1.length) {
+        if (str2[i] === str1[j]) {
+            i++;
+        }
+        j++;
+    }
+    return i === str2.length;
+}

package/dist/analyzing/contentWordCount.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Counts the number of content words in a given text.
+ *
+ * Content words are words that carry lexical meaning (nouns, verbs, adjectives, adverbs),
+ * excluding function words such as prepositions, pronouns, and articles.
+ *
+ * @param {string} text - The text to analyze.
+ * @returns {number} The count of content words in the text.
+ * @throws {TypeError} If the input is not a string.
+ */
+export declare function contentWordCount(text: string): number;

package/dist/analyzing/contentWordCount.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentWordCount = contentWordCount;
+const functionWordCount_1 = require("./functionWordCount");
+const wordCount_1 = require("./wordCount");
+/**
+ * Counts the number of content words in a given text.
+ *
+ * Content words are words that carry lexical meaning (nouns, verbs, adjectives, adverbs),
+ * excluding function words such as prepositions, pronouns, and articles.
+ *
+ * @param {string} text - The text to analyze.
+ * @returns {number} The count of content words in the text.
+ * @throws {TypeError} If the input is not a string.
+ */
+function contentWordCount(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const totalWords = (0, wordCount_1.wordCount)(text);
+    const functionWords = (0, functionWordCount_1.functionWordCount)(text);
+    return totalWords - functionWords;
+}

package/dist/analyzing/functionWordCount.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Counts the number of function words in a given text.
+ *
+ * Function words are common words (e.g., prepositions, pronouns, conjunctions, articles, etc.)
+ * that carry grammatical meaning rather than lexical meaning.
+ *
+ * @param {string} text - The text to analyze.
+ * @returns {number} The count of function words in the text.
+ * @throws {TypeError} If the input is not a string.
+ */
+export declare function functionWordCount(text: string): number;

package/dist/analyzing/functionWordCount.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.functionWordCount = functionWordCount;
+/**
+ * Counts the number of function words in a given text.
+ *
+ * Function words are common words (e.g., prepositions, pronouns, conjunctions, articles, etc.)
+ * that carry grammatical meaning rather than lexical meaning.
+ *
+ * @param {string} text - The text to analyze.
+ * @returns {number} The count of function words in the text.
+ * @throws {TypeError} If the input is not a string.
+ */
+function functionWordCount(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const functionWords = new Set([
+        'a', 'an', 'the', 'and', 'but', 'or', 'nor', 'so', 'yet',
+        'for', 'of', 'in', 'on', 'at', 'by', 'to', 'from', 'with', 'about',
+        'as', 'into', 'like', 'through', 'after', 'over', 'between', 'out',
+        'against', 'during', 'without', 'before', 'under', 'around', 'among',
+        'is', 'am', 'are', 'was', 'were', 'be', 'been', 'being',
+        'he', 'she', 'it', 'they', 'we', 'you', 'i', 'me', 'him', 'her',
+        'them', 'us', 'my', 'your', 'his', 'their', 'our',
+        'this', 'that', 'these', 'those',
+        'who', 'whom', 'which', 'what', 'when', 'where', 'why', 'how'
+    ]);
+    // ✅ Normalize text: lowercase + remove punctuation
+    const cleanedText = text.toLowerCase().replace(/[^\w\s]/g, '');
+    const words = cleanedText.trim().split(/\s+/);
+    return words.filter(word => functionWords.has(word)).length;
+}

package/dist/analyzing/index.d.ts

@@ -6,6 +6,12 @@ export { wordCount } from './wordCount';
 export { stringSimilarity } from './stringSimilarity';
 export { patternCount } from './patternCount';
 export { vowelConsonantCount } from './vowelConsonantCount';
+export { checkMultiplePatterns } from './checkMultiplePatterns';
+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';
@@ -14,6 +20,10 @@ import { wordCount } from './wordCount';
 import { stringSimilarity } from './stringSimilarity';
 import { patternCount } from './patternCount';
 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;
@@ -23,4 +33,8 @@ export declare const analyzing: {
     stringSimilarity: typeof stringSimilarity;
     patternCount: typeof patternCount;
     vowelConsonantCount: typeof vowelConsonantCount;
+    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.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");
@@ -17,6 +17,18 @@ var patternCount_1 = require("./patternCount");
 Object.defineProperty(exports, "patternCount", { enumerable: true, get: function () { return patternCount_1.patternCount; } });
 var vowelConsonantCount_1 = require("./vowelConsonantCount");
 Object.defineProperty(exports, "vowelConsonantCount", { enumerable: true, get: function () { return vowelConsonantCount_1.vowelConsonantCount; } });
+var checkMultiplePatterns_1 = require("./checkMultiplePatterns");
+Object.defineProperty(exports, "checkMultiplePatterns", { enumerable: true, get: function () { return checkMultiplePatterns_1.checkMultiplePatterns; } });
+var checkSubsequence_1 = require("./checkSubsequence");
+Object.defineProperty(exports, "checkSubsequence", { enumerable: true, get: function () { return checkSubsequence_1.checkSubsequence; } });
+var functionWordCount_1 = require("./functionWordCount");
+Object.defineProperty(exports, "functionWordCount", { enumerable: true, get: function () { return functionWordCount_1.functionWordCount; } });
+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");
@@ -25,6 +37,10 @@ const wordCount_2 = require("./wordCount");
 const stringSimilarity_2 = require("./stringSimilarity");
 const patternCount_2 = require("./patternCount");
 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,
@@ -33,5 +49,9 @@ exports.analyzing = {
     wordCount: wordCount_2.wordCount,
     stringSimilarity: stringSimilarity_2.stringSimilarity,
     patternCount: patternCount_2.patternCount,
-    vowelConsonantCount: vowelConsonantCount_2.vowelConsonantCount
+    vowelConsonantCount: vowelConsonantCount_2.vowelConsonantCount,
+    checkMultiplePatterns: checkMultiplePatterns_2.checkMultiplePatterns,
+    checkSubsequence: checkSubsequence_2.checkSubsequence,
+    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/analyzing/patternCount.d.ts

@@ -1,10 +1,11 @@
 /**
- * Calculates the number of times a specific pattern occurs in a given text, including overlapping occurrences
+ * Counts the number of times a specific pattern occurs in a given text,
+ * including overlapping occurrences.
  *
- * The algorithm used here is based on the Knuth-Morris-Pratt (KMP) pattern matching algorithm for better performance
+ * Uses the Knuth-Morris-Pratt (KMP) pattern matching algorithm for efficient searching.
  *
- * @param {string} text - The text for which we want to count the occurrences of a specific pattern.
- * @param {string} pattern - The pattern to search for within the text.
- * @returns {number} - The number of times the pattern occurs in the text (overlapping).
+ * @param text - The text to search within
+ * @param pattern - The pattern to count
+ * @returns The number of times the pattern occurs (including overlapping)
  */
 export declare function patternCount(text: string, pattern: string): number;

package/dist/analyzing/patternCount.js

@@ -2,50 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patternCount = patternCount;
 /**
- * Calculates the number of times a specific pattern occurs in a given text, including overlapping occurrences
+ * Counts the number of times a specific pattern occurs in a given text,
+ * including overlapping occurrences.
  *
- * The algorithm used here is based on the Knuth-Morris-Pratt (KMP) pattern matching algorithm for better performance
+ * Uses the Knuth-Morris-Pratt (KMP) pattern matching algorithm for efficient searching.
  *
- * @param {string} text - The text for which we want to count the occurrences of a specific pattern.
- * @param {string} pattern - The pattern to search for within the text.
- * @returns {number} - The number of times the pattern occurs in the text (overlapping).
+ * @param text - The text to search within
+ * @param pattern - The pattern to count
+ * @returns The number of times the pattern occurs (including overlapping)
  */
 function patternCount(text, pattern) {
-    if (pattern.length === 0) {
-        return 0; // No pattern to search for
-    }
+    if (!pattern)
+        return 0; // Return 0 for empty pattern
     const prefixFunction = computePrefixFunction(pattern);
     let count = 0;
     let j = 0; // Index for pattern
     for (let i = 0; i < text.length; i++) {
         while (j > 0 && text[i] !== pattern[j]) {
-            j = prefixFunction[j - 1];
+            j = prefixFunction[j - 1]; // fallback in pattern
         }
-        if (text[i] === pattern[j]) {
+        if (text[i] === pattern[j])
             j++;
-        }
         if (j === pattern.length) {
             count++;
-            j = prefixFunction[j - 1]; // Allow for overlapping matches
+            j = prefixFunction[j - 1]; // allow overlapping matches
         }
     }
     return count;
 }
 /**
  * Computes the prefix function (partial match table) for KMP algorithm.
- * @param {string} pattern - The pattern string.
- * @returns {number[]} - The prefix function array.
+ *
+ * The prefix function stores the length of the longest proper prefix
+ * which is also a suffix for each prefix of the pattern.
+ *
+ * @param pattern - Pattern string
+ * @returns Array of prefix lengths
  */
 function computePrefixFunction(pattern) {
     const prefixFunction = new Array(pattern.length).fill(0);
     let j = 0;
     for (let i = 1; i < pattern.length; i++) {
         while (j > 0 && pattern[i] !== pattern[j]) {
-            j = prefixFunction[j - 1];
+            j = prefixFunction[j - 1]; // fallback
         }
-        if (pattern[i] === pattern[j]) {
+        if (pattern[i] === pattern[j])
             j++;
-        }
         prefixFunction[i] = j;
     }
     return prefixFunction;

package/dist/analyzing/stringRotation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Checks if one string is a rotation of another.
+ *
+ * A string `str2` is a rotation of `str1` if it can be obtained by shifting
+ * the characters of `str1` in a circular fashion.
+ *
+ * The check is case-sensitive and supports special characters and numbers.
+ *
+ * @param {string} str1 - The original string.
+ * @param {string} str2 - The string to check if it is a rotation of str1.
+ * @returns {boolean} True if str2 is a rotation of str1, otherwise false.
+ * @throws {TypeError} If either input is not a string.
+ *
+ * @example
+ * checkStringRotations("abcd", "cdab"); // true
+ *
+ * @example
+ * checkStringRotations("abc", "acb"); // false
+ *
+ * @example
+ * checkStringRotations("hello", "ohell"); // true
+ *
+ * @example
+ * checkStringRotations("", ""); // true
+ *
+ * @example
+ * checkStringRotations("abc", "ab"); // false
+ */
+export declare function checkStringRotations(str1: string, str2: string): boolean;

package/dist/analyzing/stringRotation.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkStringRotations = checkStringRotations;
+/**
+ * Checks if one string is a rotation of another.
+ *
+ * A string `str2` is a rotation of `str1` if it can be obtained by shifting
+ * the characters of `str1` in a circular fashion.
+ *
+ * The check is case-sensitive and supports special characters and numbers.
+ *
+ * @param {string} str1 - The original string.
+ * @param {string} str2 - The string to check if it is a rotation of str1.
+ * @returns {boolean} True if str2 is a rotation of str1, otherwise false.
+ * @throws {TypeError} If either input is not a string.
+ *
+ * @example
+ * checkStringRotations("abcd", "cdab"); // true
+ *
+ * @example
+ * checkStringRotations("abc", "acb"); // false
+ *
+ * @example
+ * checkStringRotations("hello", "ohell"); // true
+ *
+ * @example
+ * checkStringRotations("", ""); // true
+ *
+ * @example
+ * checkStringRotations("abc", "ab"); // false
+ */
+function checkStringRotations(str1, str2) {
+    if (typeof str1 !== 'string' || typeof str2 !== 'string') {
+        throw new TypeError('Both inputs must be strings');
+    }
+    // Edge case: both empty strings
+    if (str1 === '' && str2 === '')
+        return true;
+    // If lengths differ, they cannot be rotations
+    if (str1.length !== str2.length)
+        return false;
+    // Concatenate str1 with itself and check if str2 is a substring
+    return (str1 + str1).includes(str2);
+}

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;