stringzy 2.2.1 → 3.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 @@
+export declare function characterCount(str: string): number;

package/dist/analyzing/characterCount.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.characterCount = characterCount;
+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 @@
+export declare function characterFrequency(str: string): Record<string, number>;

package/dist/analyzing/characterFrequency.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.characterFrequency = characterFrequency;
+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,6 @@
+export type ComplexityResult = {
+    score: number;
+    uniqueness: number;
+    length: number;
+};
+export declare function complexity(str: string): ComplexityResult;

package/dist/analyzing/complexity.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.complexity = complexity;
+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,20 @@
+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 declare const analyzing: {
+    characterCount: typeof characterCount;
+    characterFrequency: typeof characterFrequency;
+    complexity: typeof complexity;
+    readingDuration: typeof readingDuration;
+    wordCount: typeof wordCount;
+    stringSimilarity: typeof stringSimilarity;
+};

package/dist/analyzing/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzing = 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; } });
+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");
+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
+};

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;

package/dist/analyzing/stringSimilarity.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringSimilarity = stringSimilarity;
+/**
+ * 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).
+ */
+function stringSimilarity(textA, textB, algorithm = 'Levenshtein') {
+    validateParams(textA, textB, algorithm);
+    if (textA === textB) {
+        return 100.0;
+    }
+    if (textA.length === 0 && textB.length != 0) {
+        return 0.0;
+    }
+    let distance;
+    if (algorithm === 'Levenshtein') {
+        distance = calculateLevenshteinDistance(textA, textB);
+    }
+    else {
+        distance = calculateDamerauLevenshteinDistance(textA, textB);
+    }
+    return calculateSimilarityScore(distance, textA, textB);
+}
+/**
+ * Converts the edit distance to a percentage similarity score.
+ * @param distance The edit distance between the texts.
+ * @param textA The first text.
+ * @param textB The second text.
+ * @returns Similarity percentage (0-100).
+ */
+function calculateSimilarityScore(distance, textA, textB) {
+    const similarityScore = 1 - (distance / Math.max(textA.length, textB.length));
+    return parseFloat((similarityScore * 100).toFixed(2));
+}
+/**
+ * Calculates the Levenshtein distance between two texts.
+ * @param textA The first text.
+ * @param textB The second text.
+ * @returns The Levenshtein distance.
+ */
+function calculateLevenshteinDistance(textA, textB) {
+    const lenA = textA.length;
+    const lenB = textB.length;
+    if (lenA === 0) {
+        return lenB;
+    }
+    if (lenB === 0) {
+        return lenA;
+    }
+    const distancesMatrix = prepareDistanceMatrix(lenA, lenB);
+    for (let i = 1; i <= lenA; i++) {
+        for (let j = 1; j <= lenB; j++) {
+            distancesMatrix[i][j] = applyBasicEditOperations(i, j, textA, textB, distancesMatrix);
+        }
+    }
+    return distancesMatrix[lenA][lenB];
+}
+/**
+ * Calculates the Damerau-Levenshtein distance between two texts.
+ * @param textA The first text.
+ * @param textB The second text.
+ * @returns The Damerau-Levenshtein distance.
+ */
+function calculateDamerauLevenshteinDistance(textA, textB) {
+    const lenA = textA.length;
+    const lenB = textB.length;
+    if (lenA === 0) {
+        return lenB;
+    }
+    if (lenB === 0) {
+        return lenA;
+    }
+    const distancesMatrix = prepareDistanceMatrix(lenA, lenB);
+    for (let i = 1; i <= lenA; i++) {
+        for (let j = 1; j <= lenB; j++) {
+            distancesMatrix[i][j] = applyBasicEditOperations(i, j, textA, textB, distancesMatrix);
+            if (i > 1 && j > 1 && textA[i - 1] === textB[j - 2] && textA[i - 2] === textB[j - 1]) {
+                distancesMatrix[i][j] = Math.min(distancesMatrix[i][j], distancesMatrix[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return distancesMatrix[lenA][lenB];
+}
+/**
+ * Prepares a distance matrix for edit distance calculations.
+ * @param lenA Length of the first text.
+ * @param lenB Length of the second text.
+ * @returns A 2D array representing the distance matrix.
+ */
+function prepareDistanceMatrix(lenA, lenB) {
+    const distancesMatrix = Array.from({ length: lenA + 1 }, () => Array(lenB + 1).fill(0));
+    for (let i = 0; i <= lenA; i++) {
+        distancesMatrix[i][0] = i;
+    }
+    for (let j = 0; j <= lenB; j++) {
+        distancesMatrix[0][j] = j;
+    }
+    return distancesMatrix;
+}
+/**
+ * Applies basic edit operations (deletion, insertion, substitution) for edit distance algorithms.
+ * @param i Current row index in the matrix.
+ * @param j Current column index in the matrix.
+ * @param textA The first text.
+ * @param textB The second text.
+ * @param matrix The distance matrix.
+ * @returns The minimum cost for the current cell.
+ */
+function applyBasicEditOperations(i, j, textA, textB, matrix) {
+    const cost = textA[i - 1] === textB[j - 1] ? 0 : 1;
+    return Math.min(matrix[i - 1][j] + 1, // Deletion
+    matrix[i][j - 1] + 1, // Insertion
+    matrix[i - 1][j - 1] + cost // Substitution
+    );
+}
+/////////////////////////////////////////
+//// Validation Functions
+/////////////////////////////////////////
+/**
+ * Checks if a value is a string.
+ * @param value The value to check.
+ * @returns True if the value is a string, otherwise false.
+ */
+function isString(value) {
+    return typeof value === 'string';
+}
+/**
+ * Validates the input parameters for the string similarity functions.
+ * @param textA The first text.
+ * @param textB The second text.
+ * @param algorithm The algorithm to use.
+ * @throws Error if parameters are invalid.
+ */
+function validateParams(textA, textB, algorithm) {
+    if (!isString(textA) || !isString(textB)) {
+        throw new Error('Both text arguments must be strings');
+    }
+    if (algorithm !== 'Levenshtein' && algorithm !== 'Damerau-Levenshtein') {
+        throw new Error("Invalid optional algorithm param. Should be 'Levenshtein' or 'Damerau-Levenshtein'");
+    }
+}

package/dist/analyzing/wordCount.d.ts

@@ -0,0 +1 @@
+export declare function wordCount(str: string): number;

package/dist/analyzing/wordCount.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordCount = wordCount;
+function wordCount(str) {
+    if (typeof str !== "string") {
+        throw new TypeError("Input must be a string");
+    }
+    if (!str.trim())
+        return 0;
+    return str.trim().split(/\s+/).length;
+}

package/dist/formatting/capitalize.d.ts

@@ -0,0 +1 @@
+export declare function capitalize(str: string): string;

package/dist/formatting/capitalize.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capitalize = capitalize;
+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())
+        .join(' ');
+}

package/dist/formatting/index.d.ts

@@ -0,0 +1,11 @@
+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;
+    formatPhone: typeof formatPhone;
+};

package/dist/formatting/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatting = exports.formatPhone = exports.formatNumber = exports.capitalize = void 0;
+var capitalize_1 = require("./capitalize");
+Object.defineProperty(exports, "capitalize", { enumerable: true, get: function () { return capitalize_1.capitalize; } });
+var number_1 = require("./number");
+Object.defineProperty(exports, "formatNumber", { enumerable: true, get: function () { return number_1.formatNumber; } });
+var phone_1 = require("./phone");
+Object.defineProperty(exports, "formatPhone", { enumerable: true, get: function () { return phone_1.formatPhone; } });
+const capitalize_2 = require("./capitalize");
+const number_2 = require("./number");
+const phone_2 = require("./phone");
+exports.formatting = {
+    capitalize: capitalize_2.capitalize,
+    formatNumber: number_2.formatNumber,
+    formatPhone: phone_2.formatPhone,
+};

package/dist/formatting/number.d.ts

@@ -0,0 +1 @@
+export declare function formatNumber(num: string | number, thousendsSeperator?: '.' | ','): string;

package/dist/formatting/number.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNumber = formatNumber;
+function formatNumber(num, thousendsSeperator = ",") {
+    const numStr = num.toString();
+    return numStr.replace(/\B(?=(\d{3})+(?!\d))/g, thousendsSeperator);
+}

package/dist/formatting/phone.d.ts

@@ -0,0 +1,2 @@
+export type PhoneFormat = 'us' | 'in' | 'international';
+export declare function formatPhone(phone: string, format?: PhoneFormat): string;

package/dist/formatting/phone.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPhone = formatPhone;
+function formatPhone(phone, format = 'us') {
+    const digits = phone.replace(/\D/g, '');
+    if (format === 'us' && digits.length === 10) {
+        return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+    }
+    else if (format === 'international' && digits.length >= 10) {
+        const countryCode = digits.slice(0, -10);
+        const areaCode = digits.slice(-10, -7);
+        const firstPart = digits.slice(-7, -4);
+        const lastPart = digits.slice(-4);
+        return `+${countryCode} (${areaCode}) ${firstPart}-${lastPart}`;
+    }
+    else if (format === 'in') {
+        if (digits.length === 10) {
+            return `+91-${digits.slice(0, 5)}-${digits.slice(5)}`;
+        }
+        else if (digits.length === 12 && digits.startsWith('91')) {
+            return `+91-${digits.slice(2, 7)}-${digits.slice(7)}`;
+        }
+    }
+    return phone;
+}