stringzy 3.0.0 → 4.0.0

package/dist/analyzing/characterCount.d.ts

@@ -1 +1,20 @@
+/**
+ * Returns the number of characters in a given string.
+ *
+ * This function counts all characters in the string, including whitespace,
+ * punctuation, and special characters. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string whose characters will be counted.
+ * @returns {number} The number of characters in the input string.
+ * @throws {TypeError} If the input is not of type string.
+ *
+ * @example
+ * characterCount("Hello, world!"); // 13
+ *
+ * @example
+ * characterCount("  ");            // 2
+ *
+ * @example
+ * characterCount("");              // 0
+ */
 export declare function characterCount(str: string): number;

package/dist/analyzing/characterCount.js

@@ -1,9 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.characterCount = characterCount;
+/**
+ * Returns the number of characters in a given string.
+ *
+ * This function counts all characters in the string, including whitespace,
+ * punctuation, and special characters. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string whose characters will be counted.
+ * @returns {number} The number of characters in the input string.
+ * @throws {TypeError} If the input is not of type string.
+ *
+ * @example
+ * characterCount("Hello, world!"); // 13
+ *
+ * @example
+ * characterCount("  ");            // 2
+ *
+ * @example
+ * characterCount("");              // 0
+ */
 function characterCount(str) {
-    if (typeof str !== "string") {
-        throw new TypeError("Input must be a string");
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
     }
     return str.length;
 }

package/dist/analyzing/characterFrequency.d.ts

@@ -1 +1,20 @@
+/**
+ * Calculates the frequency of each non-space character in a string.
+ *
+ * This function returns an object mapping each lowercase character (excluding spaces)
+ * to the number of times it appears in the input string. The input is case-insensitive,
+ * meaning 'A' and 'a' are treated the same. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string to analyze.
+ * @returns {Record<string, number>} An object where keys are characters and values are their counts.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * characterFrequency("Hello World");
+ * // Returns: { h: 1, e: 1, l: 3, o: 2, w: 1, r: 1, d: 1 }
+ *
+ * @example
+ * characterFrequency("AaBb");
+ * // Returns: { a: 2, b: 2 }
+ */
 export declare function characterFrequency(str: string): Record<string, number>;

package/dist/analyzing/characterFrequency.js

@@ -1,13 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.characterFrequency = characterFrequency;
+/**
+ * Calculates the frequency of each non-space character in a string.
+ *
+ * This function returns an object mapping each lowercase character (excluding spaces)
+ * to the number of times it appears in the input string. The input is case-insensitive,
+ * meaning 'A' and 'a' are treated the same. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string to analyze.
+ * @returns {Record<string, number>} An object where keys are characters and values are their counts.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * characterFrequency("Hello World");
+ * // Returns: { h: 1, e: 1, l: 3, o: 2, w: 1, r: 1, d: 1 }
+ *
+ * @example
+ * characterFrequency("AaBb");
+ * // Returns: { a: 2, b: 2 }
+ */
 function characterFrequency(str) {
-    if (typeof str !== "string") {
-        throw new TypeError("Input must be a string");
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
     }
     const frequency = {};
     for (const char of str.toLowerCase()) {
-        if (char !== " ") {
+        if (char !== ' ') {
             // Exclude spaces for cleaner analysis
             frequency[char] = (frequency[char] || 0) + 1;
         }

package/dist/analyzing/complexity.d.ts

@@ -3,4 +3,37 @@ export type ComplexityResult = {
     uniqueness: number;
     length: number;
 };
+/**
+ * Evaluates the complexity of a given string based on length, character uniqueness,
+ * and character type diversity (lowercase, uppercase, numbers, symbols).
+ *
+ * The returned score ranges from 0 to 1, where a higher score indicates greater complexity.
+ * It also returns the raw length of the string and its uniqueness ratio (unique chars / total length).
+ *
+ * - `uniqueness`: Measures how varied the characters are.
+ * - `score`: Combines uniqueness, type diversity, and length into a weighted value.
+ * - `length`: The total number of characters in the input.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The input string to evaluate.
+ * @returns {ComplexityResult} An object containing `score`, `uniqueness`, and `length`.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * complexity("abcABC123!");
+ * // {
+ * //   score: 0.93,
+ * //   uniqueness: 1.00,
+ * //   length: 10
+ * // }
+ *
+ * @example
+ * complexity("aaaa");
+ * // {
+ * //   score: 0.25,
+ * //   uniqueness: 0.25,
+ * //   length: 4
+ * // }
+ */
 export declare function complexity(str: string): ComplexityResult;

package/dist/analyzing/complexity.js

@@ -1,11 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.complexity = complexity;
+/**
+ * Evaluates the complexity of a given string based on length, character uniqueness,
+ * and character type diversity (lowercase, uppercase, numbers, symbols).
+ *
+ * The returned score ranges from 0 to 1, where a higher score indicates greater complexity.
+ * It also returns the raw length of the string and its uniqueness ratio (unique chars / total length).
+ *
+ * - `uniqueness`: Measures how varied the characters are.
+ * - `score`: Combines uniqueness, type diversity, and length into a weighted value.
+ * - `length`: The total number of characters in the input.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The input string to evaluate.
+ * @returns {ComplexityResult} An object containing `score`, `uniqueness`, and `length`.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * complexity("abcABC123!");
+ * // {
+ * //   score: 0.93,
+ * //   uniqueness: 1.00,
+ * //   length: 10
+ * // }
+ *
+ * @example
+ * complexity("aaaa");
+ * // {
+ * //   score: 0.25,
+ * //   uniqueness: 0.25,
+ * //   length: 4
+ * // }
+ */
 function complexity(str) {
     if (!str)
         return { score: 0, uniqueness: 0, length: 0 };
-    if (typeof str !== "string") {
-        throw new TypeError("Input must be a string");
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
     }
     const length = str.length;
     const unique = new Set(str).size;

package/dist/analyzing/index.d.ts

@@ -1,15 +1,19 @@
-export { characterCount } from "./characterCount";
-export { characterFrequency } from "./characterFrequency";
-export { complexity } from "./complexity";
-export { readingDuration } from "./readingDuration";
-export { wordCount } from "./wordCount";
-export { stringSimilarity } from "./stringSimilarity";
-import { characterCount } from "./characterCount";
-import { characterFrequency } from "./characterFrequency";
-import { complexity } from "./complexity";
-import { readingDuration } from "./readingDuration";
-import { wordCount } from "./wordCount";
-import { stringSimilarity } from "./stringSimilarity";
+export { characterCount } from './characterCount';
+export { characterFrequency } from './characterFrequency';
+export { complexity } from './complexity';
+export { readingDuration } from './readingDuration';
+export { wordCount } from './wordCount';
+export { stringSimilarity } from './stringSimilarity';
+export { patternCount } from './patternCount';
+export { vowelConsonantCount } from './vowelConsonantCount';
+import { characterCount } from './characterCount';
+import { characterFrequency } from './characterFrequency';
+import { complexity } from './complexity';
+import { readingDuration } from './readingDuration';
+import { wordCount } from './wordCount';
+import { stringSimilarity } from './stringSimilarity';
+import { patternCount } from './patternCount';
+import { vowelConsonantCount } from './vowelConsonantCount';
 export declare const analyzing: {
     characterCount: typeof characterCount;
     characterFrequency: typeof characterFrequency;
@@ -17,4 +21,6 @@ export declare const analyzing: {
     readingDuration: typeof readingDuration;
     wordCount: typeof wordCount;
     stringSimilarity: typeof stringSimilarity;
+    patternCount: typeof patternCount;
+    vowelConsonantCount: typeof vowelConsonantCount;
 };

package/dist/analyzing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analyzing = exports.stringSimilarity = exports.wordCount = exports.readingDuration = exports.complexity = exports.characterFrequency = exports.characterCount = void 0;
+exports.analyzing = 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");
@@ -13,17 +13,25 @@ var wordCount_1 = require("./wordCount");
 Object.defineProperty(exports, "wordCount", { enumerable: true, get: function () { return wordCount_1.wordCount; } });
 var stringSimilarity_1 = require("./stringSimilarity");
 Object.defineProperty(exports, "stringSimilarity", { enumerable: true, get: function () { return stringSimilarity_1.stringSimilarity; } });
+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; } });
 const characterCount_2 = require("./characterCount");
 const characterFrequency_2 = require("./characterFrequency");
 const complexity_2 = require("./complexity");
 const readingDuration_2 = require("./readingDuration");
 const wordCount_2 = require("./wordCount");
 const stringSimilarity_2 = require("./stringSimilarity");
+const patternCount_2 = require("./patternCount");
+const vowelConsonantCount_2 = require("./vowelConsonantCount");
 exports.analyzing = {
     characterCount: characterCount_2.characterCount,
     characterFrequency: characterFrequency_2.characterFrequency,
     complexity: complexity_2.complexity,
     readingDuration: readingDuration_2.readingDuration,
     wordCount: wordCount_2.wordCount,
-    stringSimilarity: stringSimilarity_2.stringSimilarity
+    stringSimilarity: stringSimilarity_2.stringSimilarity,
+    patternCount: patternCount_2.patternCount,
+    vowelConsonantCount: vowelConsonantCount_2.vowelConsonantCount
 };

package/dist/analyzing/patternCount.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calculates 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
+ *
+ * @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).
+ */
+export declare function patternCount(text: string, pattern: string): number;

package/dist/analyzing/patternCount.js

@@ -0,0 +1,52 @@
+"use strict";
+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
+ *
+ * The algorithm used here is based on the Knuth-Morris-Pratt (KMP) pattern matching algorithm for better performance
+ *
+ * @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).
+ */
+function patternCount(text, pattern) {
+    if (pattern.length === 0) {
+        return 0; // No pattern to search for
+    }
+    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];
+        }
+        if (text[i] === pattern[j]) {
+            j++;
+        }
+        if (j === pattern.length) {
+            count++;
+            j = prefixFunction[j - 1]; // Allow for 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.
+ */
+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];
+        }
+        if (pattern[i] === pattern[j]) {
+            j++;
+        }
+        prefixFunction[i] = j;
+    }
+    return prefixFunction;
+}

package/dist/analyzing/stringSimilarity.js

@@ -33,7 +33,7 @@ function stringSimilarity(textA, textB, algorithm = 'Levenshtein') {
  * @returns Similarity percentage (0-100).
  */
 function calculateSimilarityScore(distance, textA, textB) {
-    const similarityScore = 1 - (distance / Math.max(textA.length, textB.length));
+    const similarityScore = 1 - distance / Math.max(textA.length, textB.length);
     return parseFloat((similarityScore * 100).toFixed(2));
 }
 /**

package/dist/analyzing/vowelConsonantCount.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns the number of vowels and consonants in a given string.
+ *
+ * This function counts the number of vowels and consonants in the string, ignoring whitespace,
+ * punctuation, and special characters. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string whose vowels and consonants will be counted.
+ * @returns {{ vowels: number, consonants: number }} An object containing the counts of vowels and consonants.
+ * @throws {TypeError} If the input is not of type string
+ *
+ * @example
+ * vowelConsonantCount("hello");
+ * // { vowels: 2, consonants: 3 }
+ *
+ * @example
+ * vowelConsonantCount("stringzy");
+ * // { vowels: 1, consonants: 7 }
+ */
+export declare function vowelConsonantCount(str: string): {
+    vowels: number;
+    consonants: number;
+};

package/dist/analyzing/vowelConsonantCount.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vowelConsonantCount = vowelConsonantCount;
+/**
+ * Returns the number of vowels and consonants in a given string.
+ *
+ * This function counts the number of vowels and consonants in the string, ignoring whitespace,
+ * punctuation, and special characters. It throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string whose vowels and consonants will be counted.
+ * @returns {{ vowels: number, consonants: number }} An object containing the counts of vowels and consonants.
+ * @throws {TypeError} If the input is not of type string
+ *
+ * @example
+ * vowelConsonantCount("hello");
+ * // { vowels: 2, consonants: 3 }
+ *
+ * @example
+ * vowelConsonantCount("stringzy");
+ * // { vowels: 1, consonants: 7 }
+ */
+function vowelConsonantCount(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const vowels = 'aeiouAEIOU';
+    let vowelCount = 0;
+    let consonantCount = 0;
+    for (const char of str) {
+        if (vowels.includes(char)) {
+            vowelCount++;
+        }
+        else if (char.toLowerCase() >= 'a' && char.toLowerCase() <= 'z') {
+            consonantCount++;
+        }
+    }
+    return { vowels: vowelCount, consonants: consonantCount };
+}

package/dist/analyzing/wordCount.d.ts

@@ -1 +1,23 @@
+/**
+ * Counts the number of words in a given string.
+ *
+ * Words are defined as sequences of non-whitespace characters separated by one or more
+ * whitespace characters (spaces, tabs, newlines, etc.). Leading and trailing whitespace
+ * is trimmed before counting.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string to analyze.
+ * @returns {number} The number of words in the input string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * wordCount("Hello world"); // 2
+ *
+ * @example
+ * wordCount("  This  is   a test\nwith multiple lines "); // 7
+ *
+ * @example
+ * wordCount("     "); // 0
+ */
 export declare function wordCount(str: string): number;

package/dist/analyzing/wordCount.js

@@ -1,9 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wordCount = wordCount;
+/**
+ * Counts the number of words in a given string.
+ *
+ * Words are defined as sequences of non-whitespace characters separated by one or more
+ * whitespace characters (spaces, tabs, newlines, etc.). Leading and trailing whitespace
+ * is trimmed before counting.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The string to analyze.
+ * @returns {number} The number of words in the input string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * wordCount("Hello world"); // 2
+ *
+ * @example
+ * wordCount("  This  is   a test\nwith multiple lines "); // 7
+ *
+ * @example
+ * wordCount("     "); // 0
+ */
 function wordCount(str) {
-    if (typeof str !== "string") {
-        throw new TypeError("Input must be a string");
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
     }
     if (!str.trim())
         return 0;

package/dist/formatting/capitalize.d.ts

@@ -1 +1,22 @@
+/**
+ * Capitalizes the first letter of each word in a string.
+ *
+ * Converts the first character of each word to uppercase and the remaining characters to lowercase.
+ * Words are assumed to be separated by spaces. Handles multiple words and mixed casing.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The input string to capitalize.
+ * @returns {string} A new string with each word capitalized.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * capitalize("hello world"); // "Hello World"
+ *
+ * @example
+ * capitalize("mIxEd CaSe tExT"); // "Mixed Case Text"
+ *
+ * @example
+ * capitalize("  multiple   spaces "); // "Multiple Spaces"
+ */
 export declare function capitalize(str: string): string;

package/dist/formatting/capitalize.js

@@ -1,12 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.capitalize = capitalize;
+/**
+ * Capitalizes the first letter of each word in a string.
+ *
+ * Converts the first character of each word to uppercase and the remaining characters to lowercase.
+ * Words are assumed to be separated by spaces. Handles multiple words and mixed casing.
+ *
+ * Throws a `TypeError` if the input is not a string.
+ *
+ * @param {string} str - The input string to capitalize.
+ * @returns {string} A new string with each word capitalized.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * capitalize("hello world"); // "Hello World"
+ *
+ * @example
+ * capitalize("mIxEd CaSe tExT"); // "Mixed Case Text"
+ *
+ * @example
+ * capitalize("  multiple   spaces "); // "Multiple Spaces"
+ */
 function capitalize(str) {
     if (typeof str !== 'string') {
         throw new TypeError('Input must be a string');
     }
     return str
         .split(' ')
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
         .join(' ');
 }

package/dist/formatting/index.d.ts

@@ -1,9 +1,9 @@
-export { capitalize } from "./capitalize";
-export { formatNumber } from "./number";
-export { formatPhone } from "./phone";
-import { capitalize } from "./capitalize";
-import { formatNumber } from "./number";
-import { formatPhone } from "./phone";
+export { capitalize } from './capitalize';
+export { formatNumber } from './number';
+export { formatPhone } from './phone';
+import { capitalize } from './capitalize';
+import { formatNumber } from './number';
+import { formatPhone } from './phone';
 export declare const formatting: {
     capitalize: typeof capitalize;
     formatNumber: typeof formatNumber;

package/dist/formatting/number.d.ts

@@ -1 +1,24 @@
+/**
+ * Formats a number with a thousands separator.
+ *
+ * Converts a number or numeric string into a more readable format by inserting the specified
+ * thousands separator (either `','` or `'.'`). This function does not round or localize
+ * decimals — it only adds the separator between every three digits from the right.
+ *
+ * The input is first converted to a string before formatting. If the input is not a valid
+ * number or numeric string, the output may be incorrect.
+ *
+ * @param {string | number} num - The number or numeric string to format.
+ * @param {'.' | ','} [thousendsSeperator=','] - The character to use as the thousands separator.
+ * @returns {string} The formatted string with the separator added.
+ *
+ * @example
+ * formatNumber(1234567); // "1,234,567"
+ *
+ * @example
+ * formatNumber("987654321", '.'); // "987.654.321"
+ *
+ * @example
+ * formatNumber(12345.67); // "12,345.67" (decimals preserved as-is)
+ */
 export declare function formatNumber(num: string | number, thousendsSeperator?: '.' | ','): string;

package/dist/formatting/number.js

@@ -1,7 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatNumber = formatNumber;
-function formatNumber(num, thousendsSeperator = ",") {
+/**
+ * Formats a number with a thousands separator.
+ *
+ * Converts a number or numeric string into a more readable format by inserting the specified
+ * thousands separator (either `','` or `'.'`). This function does not round or localize
+ * decimals — it only adds the separator between every three digits from the right.
+ *
+ * The input is first converted to a string before formatting. If the input is not a valid
+ * number or numeric string, the output may be incorrect.
+ *
+ * @param {string | number} num - The number or numeric string to format.
+ * @param {'.' | ','} [thousendsSeperator=','] - The character to use as the thousands separator.
+ * @returns {string} The formatted string with the separator added.
+ *
+ * @example
+ * formatNumber(1234567); // "1,234,567"
+ *
+ * @example
+ * formatNumber("987654321", '.'); // "987.654.321"
+ *
+ * @example
+ * formatNumber(12345.67); // "12,345.67" (decimals preserved as-is)
+ */
+function formatNumber(num, thousendsSeperator = ',') {
     const numStr = num.toString();
     return numStr.replace(/\B(?=(\d{3})+(?!\d))/g, thousendsSeperator);
 }

package/dist/formatting/phone.d.ts

@@ -1,2 +1,25 @@
 export type PhoneFormat = 'us' | 'in' | 'international';
+/**
+ * Formats a phone number string into a readable format based on the given region.
+ *
+ * Strips all non-digit characters before formatting. Supports formatting for:
+ * - `'us'`: U.S. numbers with 10 digits → `(123) 456-7890`
+ * - `'in'`: Indian numbers with 10 digits or 12 digits starting with '91' → `+91-12345-67890`
+ * - `'international'`: Generic international format assuming last 10 digits are the local number.
+ *
+ * If the number does not match expected formats, it returns the original input.
+ *
+ * @param {string} phone - The phone number string to format.
+ * @param {PhoneFormat} [format='us'] - The desired formatting style: `'us'`, `'in'`, or `'international'`.
+ * @returns {string} The formatted phone number, or the original input if formatting fails.
+ *
+ * @example
+ * formatPhone("1234567890"); // "(123) 456-7890"
+ *
+ * @example
+ * formatPhone("+91 9876543210", "in"); // "+91-98765-43210"
+ *
+ * @example
+ * formatPhone("009199876543210", "international"); // "+0091 (998) 765-43210"
+ */
 export declare function formatPhone(phone: string, format?: PhoneFormat): string;

package/dist/formatting/phone.js

@@ -1,6 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPhone = formatPhone;
+/**
+ * Formats a phone number string into a readable format based on the given region.
+ *
+ * Strips all non-digit characters before formatting. Supports formatting for:
+ * - `'us'`: U.S. numbers with 10 digits → `(123) 456-7890`
+ * - `'in'`: Indian numbers with 10 digits or 12 digits starting with '91' → `+91-12345-67890`
+ * - `'international'`: Generic international format assuming last 10 digits are the local number.
+ *
+ * If the number does not match expected formats, it returns the original input.
+ *
+ * @param {string} phone - The phone number string to format.
+ * @param {PhoneFormat} [format='us'] - The desired formatting style: `'us'`, `'in'`, or `'international'`.
+ * @returns {string} The formatted phone number, or the original input if formatting fails.
+ *
+ * @example
+ * formatPhone("1234567890"); // "(123) 456-7890"
+ *
+ * @example
+ * formatPhone("+91 9876543210", "in"); // "+91-98765-43210"
+ *
+ * @example
+ * formatPhone("009199876543210", "international"); // "+0091 (998) 765-43210"
+ */
 function formatPhone(phone, format = 'us') {
     const digits = phone.replace(/\D/g, '');
     if (format === 'us' && digits.length === 10) {