stringzy 2.2.1 → 4.0.0

package/changelog.txt

@@ -1,111 +1,111 @@
-CHANGELOG
-
-All notable changes to the `stringzy` package will be documented in this file.
-
-=============================================================================
-Version 2.2.1 - 2025-06-04
------------------------------------------------------------------------------
-
-ADDED:
-- Added npmignore file to exclude unnecessary files from the package
-
-
-=============================================================================
-Version 2.2.0 - 2025-06-04
------------------------------------------------------------------------------
-
-ADDED:
-- Added new utility functions:
-  - `removeDuplicates`: Removes duplicate words from a string
-- Added the stringzy banner to the README
-
-=============================================================================
-Version 2.1.0 - 2025-05-31
------------------------------------------------------------------------------
-
-ADDED:
-- Added new utility functions:
-  - `removeWords`:
-  - `isDate`: Validates if a string is a valid date
-- Added contributors section in README
-- Added new badges for open source and PRs
-
-=============================================================================
-Version 2.0.1 - 2025-05-23
------------------------------------------------------------------------------
-
-FIXED:
-- Fixed README.MD table of contents for transformations.
-
-
-
-=============================================================================
-Version 2.0.0 - 2025-05-22
------------------------------------------------------------------------------
-
-ADDED:
-- Added a dynamic list of APIs in README
-- Divided the package into 4 modules-transformations, validations, formatting and analysis
-- Added many new APIs 
-  - `camelCase`: Converts a string to camel case
-  - `kebabCase`: Converts a string to kebab case
-  - `snakeCase`: Converts a string to snake case
-  - `titleCase`: Converts a string to title case
-  - `constantCase`: Converts a string to constant case
-  - `pascalCase`: Converts a string to pascal case
-  - `isURL`: Validates if a string is a valid URL
-  - `isEmail`: Validates if a string is a valid email address
-  - `isEmpty`: Checks if a string is empty or contains only whitespace
-  - `wordCount`: Counts the number of words in a string
-  - `characterCount`: Counts the number of characters in a string
-  - `characterFrequency`: Calculates the frequency of each character in a string
-  - `capitalize`: Capitalizes the entire string
-  - `formatNumber`: Formats a number with commas as thousands separators
-  - `formatPhone`: Formats a phone number to a standard format
-
-=============================================================================
-
-Version 1.1.2 - 2025-05-15
------------------------------------------------------------------------------
-
-ADDED:
-- Improved documentation with comprehensive README
-- Enhanced examples for all utility functions
-
-FIXED:
-- Resolved documentation rendering issues on npm website
-
-=============================================================================
-
-Version 1.1.1 - 2025-05-15
------------------------------------------------------------------------------
-
-CHANGED:
-- Updated package metadata
-
-FIXED:
-- Minor bug fixes in string handling edge cases
-
-=============================================================================
-
-Version 1.1.0 - 2025-05-15
------------------------------------------------------------------------------
-
-ADDED:
-- Added extensive API documentation
-
-CHANGED:
-- Improved performance for `toSlug` function
-- Enhanced error handling across all utility functions
-
-=============================================================================
-
-Version 1.0.0 - 2025-05-14
------------------------------------------------------------------------------
-
-ADDED:
-- Initial release with four core utility functions:
-  - `truncateText`: Truncates text to a specified length with optional suffix
-  - `toSlug`: Converts text to URL-friendly slug format
-  - `capitalizeWords`: Capitalizes the first letter of each word
+CHANGELOG
+
+All notable changes to the `stringzy` package will be documented in this file.
+
+=============================================================================
+Version 2.2.1 - 2025-06-04
+-----------------------------------------------------------------------------
+
+ADDED:
+- Added npmignore file to exclude unnecessary files from the package
+
+
+=============================================================================
+Version 2.2.0 - 2025-06-04
+-----------------------------------------------------------------------------
+
+ADDED:
+- Added new utility functions:
+  - `removeDuplicates`: Removes duplicate words from a string
+- Added the stringzy banner to the README
+
+=============================================================================
+Version 2.1.0 - 2025-05-31
+-----------------------------------------------------------------------------
+
+ADDED:
+- Added new utility functions:
+  - `removeWords`:
+  - `isDate`: Validates if a string is a valid date
+- Added contributors section in README
+- Added new badges for open source and PRs
+
+=============================================================================
+Version 2.0.1 - 2025-05-23
+-----------------------------------------------------------------------------
+
+FIXED:
+- Fixed README.MD table of contents for transformations.
+
+
+
+=============================================================================
+Version 2.0.0 - 2025-05-22
+-----------------------------------------------------------------------------
+
+ADDED:
+- Added a dynamic list of APIs in README
+- Divided the package into 4 modules-transformations, validations, formatting and analysis
+- Added many new APIs 
+  - `camelCase`: Converts a string to camel case
+  - `kebabCase`: Converts a string to kebab case
+  - `snakeCase`: Converts a string to snake case
+  - `titleCase`: Converts a string to title case
+  - `constantCase`: Converts a string to constant case
+  - `pascalCase`: Converts a string to pascal case
+  - `isURL`: Validates if a string is a valid URL
+  - `isEmail`: Validates if a string is a valid email address
+  - `isEmpty`: Checks if a string is empty or contains only whitespace
+  - `wordCount`: Counts the number of words in a string
+  - `characterCount`: Counts the number of characters in a string
+  - `characterFrequency`: Calculates the frequency of each character in a string
+  - `capitalize`: Capitalizes the entire string
+  - `formatNumber`: Formats a number with commas as thousands separators
+  - `formatPhone`: Formats a phone number to a standard format
+
+=============================================================================
+
+Version 1.1.2 - 2025-05-15
+-----------------------------------------------------------------------------
+
+ADDED:
+- Improved documentation with comprehensive README
+- Enhanced examples for all utility functions
+
+FIXED:
+- Resolved documentation rendering issues on npm website
+
+=============================================================================
+
+Version 1.1.1 - 2025-05-15
+-----------------------------------------------------------------------------
+
+CHANGED:
+- Updated package metadata
+
+FIXED:
+- Minor bug fixes in string handling edge cases
+
+=============================================================================
+
+Version 1.1.0 - 2025-05-15
+-----------------------------------------------------------------------------
+
+ADDED:
+- Added extensive API documentation
+
+CHANGED:
+- Improved performance for `toSlug` function
+- Enhanced error handling across all utility functions
+
+=============================================================================
+
+Version 1.0.0 - 2025-05-14
+-----------------------------------------------------------------------------
+
+ADDED:
+- Initial release with four core utility functions:
+  - `truncateText`: Truncates text to a specified length with optional suffix
+  - `toSlug`: Converts text to URL-friendly slug format
+  - `capitalizeWords`: Capitalizes the first letter of each word
   - `removeSpecialChars`: Removes special characters from text with optional replacement

package/dist/analyzing/characterCount.d.ts

@@ -0,0 +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

@@ -0,0 +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');
+    }
+    return str.length;
+}

package/dist/analyzing/characterFrequency.d.ts

@@ -0,0 +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

@@ -0,0 +1,35 @@
+"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');
+    }
+    const frequency = {};
+    for (const char of str.toLowerCase()) {
+        if (char !== ' ') {
+            // Exclude spaces for cleaner analysis
+            frequency[char] = (frequency[char] || 0) + 1;
+        }
+    }
+    return frequency;
+}

package/dist/analyzing/complexity.d.ts

@@ -0,0 +1,39 @@
+export type ComplexityResult = {
+    score: number;
+    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

@@ -0,0 +1,63 @@
+"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');
+    }
+    const length = str.length;
+    const unique = new Set(str).size;
+    const uniqueness = unique / length;
+    let typeScore = 0;
+    if (/[a-z]/.test(str))
+        typeScore += 0.25;
+    if (/[A-Z]/.test(str))
+        typeScore += 0.25;
+    if (/[0-9]/.test(str))
+        typeScore += 0.25;
+    if (/[^a-zA-Z0-9]/.test(str))
+        typeScore += 0.25;
+    // Calculate score based on length and character diversity
+    const lengthScore = Math.min(1, length / 20); // Max score at 20 chars
+    const score = uniqueness * 0.4 + typeScore * 0.4 + lengthScore * 0.2;
+    return {
+        score: parseFloat(score.toFixed(2)),
+        uniqueness: parseFloat(uniqueness.toFixed(2)),
+        length,
+    };
+}

package/dist/analyzing/index.d.ts

@@ -0,0 +1,26 @@
+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;
+    complexity: typeof complexity;
+    readingDuration: typeof readingDuration;
+    wordCount: typeof wordCount;
+    stringSimilarity: typeof stringSimilarity;
+    patternCount: typeof patternCount;
+    vowelConsonantCount: typeof vowelConsonantCount;
+};

package/dist/analyzing/index.js

@@ -0,0 +1,37 @@
+"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;
+var characterCount_1 = require("./characterCount");
+Object.defineProperty(exports, "characterCount", { enumerable: true, get: function () { return characterCount_1.characterCount; } });
+var characterFrequency_1 = require("./characterFrequency");
+Object.defineProperty(exports, "characterFrequency", { enumerable: true, get: function () { return characterFrequency_1.characterFrequency; } });
+var complexity_1 = require("./complexity");
+Object.defineProperty(exports, "complexity", { enumerable: true, get: function () { return complexity_1.complexity; } });
+var readingDuration_1 = require("./readingDuration");
+Object.defineProperty(exports, "readingDuration", { enumerable: true, get: function () { return readingDuration_1.readingDuration; } });
+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,
+    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/readingDuration.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calculates the estimated reading duration for a given text based on an average reading speed.
+ *
+ * The default reading speed is set to 230 words per minute, which is derived from various research studies.
+ *
+ * @param {string} text - The text for which the reading duration is to be calculated.
+ * @param {number} [readingSpeed=230] - The reading speed in words per minute. Defaults to 230.
+ * @returns {number} - The estimated reading duration in minutes.
+ */
+export declare function readingDuration(text: string, readingSpeed?: number): number;

package/dist/analyzing/readingDuration.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readingDuration = readingDuration;
+const wordCount_1 = require("./wordCount");
+/**
+ * Calculates the estimated reading duration for a given text based on an average reading speed.
+ *
+ * The default reading speed is set to 230 words per minute, which is derived from various research studies.
+ *
+ * @param {string} text - The text for which the reading duration is to be calculated.
+ * @param {number} [readingSpeed=230] - The reading speed in words per minute. Defaults to 230.
+ * @returns {number} - The estimated reading duration in minutes.
+ */
+function readingDuration(text, readingSpeed = 230) {
+    const amountOfWords = (0, wordCount_1.wordCount)(text);
+    return Math.round(amountOfWords / readingSpeed);
+}

package/dist/analyzing/stringSimilarity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calculates the percentage similarity between two texts using the selected algorithm.
+ * @param textA The first text to compare.
+ * @param textB The second text to compare.
+ * @param algorithm The algorithm to use: 'Levenshtein' or 'Damerau-Levenshtein'. Default is 'Levenshtein'.
+ * @returns Similarity percentage (0-100).
+ */
+export declare function stringSimilarity(textA: string, textB: string, algorithm?: 'Levenshtein' | 'Damerau-Levenshtein'): number;