stringzy 3.0.0 → 4.1.0

package/dist/transformations/removeSpecialChars.d.ts

@@ -1 +1,23 @@
+/**
+ * Removes special characters from a string, replacing them with a specified string.
+ *
+ * Special characters are any characters except alphanumeric (`a-z`, `A-Z`, `0-9`) and whitespace.
+ * The default replacement is an empty string, effectively removing these characters.
+ *
+ * Throws an error if the input `text` or `replacement` is not a string.
+ *
+ * @param {string} text - The input string to process.
+ * @param {string} [replacement=''] - The string to replace special characters with.
+ * @returns {string} The processed string with special characters replaced.
+ * @throws {TypeError} If `text` or `replacement` is not a string.
+ *
+ * @example
+ * removeSpecialChars("Hello, World!"); // "Hello World"
+ *
+ * @example
+ * removeSpecialChars("Special #$% chars", '_'); // "Special ___ chars"
+ *
+ * @example
+ * removeSpecialChars("CleanText123"); // "CleanText123"
+ */
 export declare function removeSpecialChars(text: string, replacement?: string): string;

package/dist/transformations/removeSpecialChars.js

@@ -1,12 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeSpecialChars = removeSpecialChars;
+/**
+ * Removes special characters from a string, replacing them with a specified string.
+ *
+ * Special characters are any characters except alphanumeric (`a-z`, `A-Z`, `0-9`) and whitespace.
+ * The default replacement is an empty string, effectively removing these characters.
+ *
+ * Throws an error if the input `text` or `replacement` is not a string.
+ *
+ * @param {string} text - The input string to process.
+ * @param {string} [replacement=''] - The string to replace special characters with.
+ * @returns {string} The processed string with special characters replaced.
+ * @throws {TypeError} If `text` or `replacement` is not a string.
+ *
+ * @example
+ * removeSpecialChars("Hello, World!"); // "Hello World"
+ *
+ * @example
+ * removeSpecialChars("Special #$% chars", '_'); // "Special ___ chars"
+ *
+ * @example
+ * removeSpecialChars("CleanText123"); // "CleanText123"
+ */
 function removeSpecialChars(text, replacement = '') {
-    if (typeof text !== "string") {
-        throw new Error("Invalid argument. Expected a string.");
+    if (typeof text !== 'string') {
+        throw new TypeError('Invalid argument. Expected a string.');
     }
-    if (typeof replacement !== "string") {
-        throw new Error("Replacement must be a string.");
+    if (typeof replacement !== 'string') {
+        throw new TypeError('Replacement must be a string.');
     }
     return text.replace(/[^\w\s]/gi, replacement);
 }

package/dist/transformations/removeWords.d.ts

@@ -1 +1,28 @@
+/**
+ * Removes specified word(s) from a given string.
+ *
+ * The function accepts either a single word as a string or an array of words to remove.
+ * It removes whole word matches case-insensitively, preserving spacing by collapsing
+ * multiple spaces into a single space and trimming the result.
+ *
+ * Throws `TypeError` if inputs are invalid or missing.
+ *
+ * @param {string} str - The input string from which words will be removed.
+ * @param {string | string[]} wordsToRemove - A word or array of words to remove from the input string.
+ * @returns {string} The string after removing the specified words.
+ * @throws {TypeError} If `str` is null, undefined, or not a string.
+ * @throws {TypeError} If `wordsToRemove` is null, undefined, or not a string or array of strings.
+ *
+ * @example
+ * removeWords("The quick brown fox jumps", "quick");
+ * // "The brown fox jumps"
+ *
+ * @example
+ * removeWords("The quick brown fox jumps over the lazy dog", ["quick", "lazy"]);
+ * // "The brown fox jumps over the dog"
+ *
+ * @example
+ * removeWords("Hello world", "world");
+ * // "Hello"
+ */
 export declare function removeWords(str: string, wordsToRemove: string | string[]): string;

package/dist/transformations/removeWords.js

@@ -1,18 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeWords = removeWords;
+/**
+ * Removes specified word(s) from a given string.
+ *
+ * The function accepts either a single word as a string or an array of words to remove.
+ * It removes whole word matches case-insensitively, preserving spacing by collapsing
+ * multiple spaces into a single space and trimming the result.
+ *
+ * Throws `TypeError` if inputs are invalid or missing.
+ *
+ * @param {string} str - The input string from which words will be removed.
+ * @param {string | string[]} wordsToRemove - A word or array of words to remove from the input string.
+ * @returns {string} The string after removing the specified words.
+ * @throws {TypeError} If `str` is null, undefined, or not a string.
+ * @throws {TypeError} If `wordsToRemove` is null, undefined, or not a string or array of strings.
+ *
+ * @example
+ * removeWords("The quick brown fox jumps", "quick");
+ * // "The brown fox jumps"
+ *
+ * @example
+ * removeWords("The quick brown fox jumps over the lazy dog", ["quick", "lazy"]);
+ * // "The brown fox jumps over the dog"
+ *
+ * @example
+ * removeWords("Hello world", "world");
+ * // "Hello"
+ */
 function removeWords(str, wordsToRemove) {
     if (str === null || str === undefined) {
-        throw new Error('Input string cannot be null or undefined');
+        throw new TypeError('Input string cannot be null or undefined');
     }
     if (typeof str !== 'string') {
-        throw new Error('First parameter must be a string');
+        throw new TypeError('First parameter must be a string');
     }
     if (wordsToRemove === null || wordsToRemove === undefined) {
-        throw new Error('Words to remove cannot be null or undefined');
+        throw new TypeError('Words to remove cannot be null or undefined');
     }
     if (typeof wordsToRemove !== 'string' && !Array.isArray(wordsToRemove)) {
-        throw new Error('Second parameter must be a string or an array of strings');
+        throw new TypeError('Second parameter must be a string or an array of strings');
     }
     if (str === '') {
         return '';

package/dist/transformations/reverseWordsInString .d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reverses the order of words in a given string while preserving the
+ * exact spacing (including multiple spaces) between them.
+ *
+ * @param {string} str - The input string whose words are to be reversed.
+ * @returns {string} The string with the order of words reversed and all original spacing intact.
+ * @throws {TypeError} If the input is not a string.
+ */
+export declare function reverseWordsInString(str: string): string;

package/dist/transformations/reverseWordsInString .js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reverseWordsInString = reverseWordsInString;
+/**
+ * Reverses the order of words in a given string while preserving the
+ * exact spacing (including multiple spaces) between them.
+ *
+ * @param {string} str - The input string whose words are to be reversed.
+ * @returns {string} The string with the order of words reversed and all original spacing intact.
+ * @throws {TypeError} If the input is not a string.
+ */
+function reverseWordsInString(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    // 1. Extract all blocks of non-whitespace characters (the words).
+    const words = str.match(/\S+/g) || [];
+    // 2. If there are no words (e.g., empty or whitespace-only string), return the original string.
+    if (words.length === 0) {
+        return str;
+    }
+    // 3. Extract all blocks of whitespace.
+    const spaces = str.match(/\s+/g) || [];
+    // 4. Reverse ONLY the array of words.
+    const reversedWords = words.reverse();
+    // 5. Stitch the reversed words and original spaces back together.
+    let result = '';
+    const startsWithSpace = /^\s/.test(str);
+    if (startsWithSpace) {
+        // If the string starts with a space, the pattern is: space, word, space, word...
+        for (let i = 0; i < reversedWords.length; i++) {
+            result += spaces[i] + reversedWords[i];
+        }
+        // Append any final trailing space block.
+        if (spaces.length > reversedWords.length) {
+            result += spaces[spaces.length - 1];
+        }
+    }
+    else {
+        // If the string starts with a word, the pattern is: word, space, word, space...
+        for (let i = 0; i < reversedWords.length; i++) {
+            result += reversedWords[i];
+            if (spaces[i]) {
+                result += spaces[i];
+            }
+        }
+    }
+    return result;
+}

package/dist/transformations/snakeCase.d.ts

@@ -1 +1,27 @@
+/**
+ * Converts a given string to snake_case format.
+ *
+ * The transformation includes:
+ * - Trimming whitespace from both ends.
+ * - Replacing spaces and hyphens with underscores.
+ * - Inserting underscores between lowercase and uppercase letter boundaries (e.g., `fooBar` → `foo_bar`).
+ * - Replacing all non-word characters (except underscores) with underscores.
+ * - Converting the entire string to lowercase.
+ * - Collapsing multiple consecutive underscores into one.
+ * - Removing leading and trailing underscores.
+ *
+ * If the input is `null` or `undefined`, it returns an empty string.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The snake_case formatted string.
+ *
+ * @example
+ * snakeCase("Hello World"); // "hello_world"
+ *
+ * @example
+ * snakeCase("camelCaseText"); // "camel_case_text"
+ *
+ * @example
+ * snakeCase("  convert-to--snake.case!  "); // "convert_to_snake_case"
+ */
 export declare function snakeCase(text: string): string;

package/dist/transformations/snakeCase.js

@@ -1,6 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.snakeCase = snakeCase;
+/**
+ * Converts a given string to snake_case format.
+ *
+ * The transformation includes:
+ * - Trimming whitespace from both ends.
+ * - Replacing spaces and hyphens with underscores.
+ * - Inserting underscores between lowercase and uppercase letter boundaries (e.g., `fooBar` → `foo_bar`).
+ * - Replacing all non-word characters (except underscores) with underscores.
+ * - Converting the entire string to lowercase.
+ * - Collapsing multiple consecutive underscores into one.
+ * - Removing leading and trailing underscores.
+ *
+ * If the input is `null` or `undefined`, it returns an empty string.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The snake_case formatted string.
+ *
+ * @example
+ * snakeCase("Hello World"); // "hello_world"
+ *
+ * @example
+ * snakeCase("camelCaseText"); // "camel_case_text"
+ *
+ * @example
+ * snakeCase("  convert-to--snake.case!  "); // "convert_to_snake_case"
+ */
 function snakeCase(text) {
     if (text == null)
         return '';

package/dist/transformations/splitChunks.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates chunks of string based on a given chunk size
+ * @param text - Input string
+ * @param Number - Size of the chunk. Must be a positive integer. Defaults to 1.
+ * @returns An array of all the chunks created from the string based on the specified chunk size.
+ * @throws Error if input text is not a string or chunk size is not a positive integer.
+ */
+export declare function splitChunks(text: string, chunkSize?: Number): string[];

package/dist/transformations/splitChunks.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitChunks = splitChunks;
+/**
+ * Creates chunks of string based on a given chunk size
+ * @param text - Input string
+ * @param Number - Size of the chunk. Must be a positive integer. Defaults to 1.
+ * @returns An array of all the chunks created from the string based on the specified chunk size.
+ * @throws Error if input text is not a string or chunk size is not a positive integer.
+ */
+function splitChunks(text, chunkSize = 1) {
+    if (typeof text !== 'string') {
+        throw new Error('Input text must be a string');
+    }
+    if (typeof chunkSize !== 'number' || !Number.isInteger(chunkSize) || chunkSize < 1) {
+        throw new Error('chunkSize must be a natural number (1, 2, 3, ...)');
+    }
+    const len = text.length;
+    const chunks = [];
+    for (let i = 0; i < len; i += chunkSize) {
+        chunks.push(text.slice(i, i + chunkSize));
+    }
+    return chunks;
+}

package/dist/transformations/stringCombinations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generates all unique combinations (subsequences) of a given string,
+ * including the empty string.
+ *
+ * Handles duplicate characters by ensuring only unique combinations are returned.
+ * The order of combinations in the output array is not guaranteed.
+ *
+ * @param {string} str - The input string to generate combinations from.
+ * @returns {string[]} An array containing all unique combinations of the string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * stringCombinations("ab");
+ * // ["", "a", "b", "ab"]
+ *
+ * @example
+ * stringCombinations("abc");
+ * // ["", "a", "b", "c", "ab", "ac", "bc", "abc"]
+ *
+ * @example
+ * stringCombinations("aab");
+ * // ["", "a", "b", "aa", "ab", "aab"]
+ *
+ * @example
+ * stringCombinations("");
+ * // [""]
+ */
+export declare function stringCombinations(str: string): string[];

package/dist/transformations/stringCombinations.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringCombinations = stringCombinations;
+/**
+ * Generates all unique combinations (subsequences) of a given string,
+ * including the empty string.
+ *
+ * Handles duplicate characters by ensuring only unique combinations are returned.
+ * The order of combinations in the output array is not guaranteed.
+ *
+ * @param {string} str - The input string to generate combinations from.
+ * @returns {string[]} An array containing all unique combinations of the string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * stringCombinations("ab");
+ * // ["", "a", "b", "ab"]
+ *
+ * @example
+ * stringCombinations("abc");
+ * // ["", "a", "b", "c", "ab", "ac", "bc", "abc"]
+ *
+ * @example
+ * stringCombinations("aab");
+ * // ["", "a", "b", "aa", "ab", "aab"]
+ *
+ * @example
+ * stringCombinations("");
+ * // [""]
+ */
+function stringCombinations(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const results = new Set();
+    function backtrack(start, path) {
+        results.add(path);
+        for (let i = start; i < str.length; i++) {
+            backtrack(i + 1, path + str[i]);
+        }
+    }
+    backtrack(0, '');
+    return Array.from(results);
+}

package/dist/transformations/stringPermutations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generates all unique permutations of a given string.
+ *
+ * Handles repeated characters by ensuring only unique permutations
+ * are included in the result. The order of permutations is not guaranteed.
+ *
+ * @param {string} str - The input string to generate permutations for.
+ * @returns {string[]} An array of unique permutations of the input string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * stringPermutations("ab");
+ * // ["ab", "ba"]
+ *
+ * @example
+ * stringPermutations("abc");
+ * // ["abc", "acb", "bac", "bca", "cab", "cba"]
+ *
+ * @example
+ * stringPermutations("aab");
+ * // ["aab", "aba", "baa"]
+ *
+ * @example
+ * stringPermutations("");
+ * // [""]
+ *
+ * @example
+ * stringPermutations("a");
+ * // ["a"]
+ */
+export declare function stringPermutations(str: string): string[];

package/dist/transformations/stringPermutations.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringPermutations = stringPermutations;
+/**
+ * Generates all unique permutations of a given string.
+ *
+ * Handles repeated characters by ensuring only unique permutations
+ * are included in the result. The order of permutations is not guaranteed.
+ *
+ * @param {string} str - The input string to generate permutations for.
+ * @returns {string[]} An array of unique permutations of the input string.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * stringPermutations("ab");
+ * // ["ab", "ba"]
+ *
+ * @example
+ * stringPermutations("abc");
+ * // ["abc", "acb", "bac", "bca", "cab", "cba"]
+ *
+ * @example
+ * stringPermutations("aab");
+ * // ["aab", "aba", "baa"]
+ *
+ * @example
+ * stringPermutations("");
+ * // [""]
+ *
+ * @example
+ * stringPermutations("a");
+ * // ["a"]
+ */
+function stringPermutations(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    if (str.length === 0)
+        return [''];
+    const results = new Set();
+    const permute = (prefix, remaining) => {
+        if (remaining.length === 0) {
+            results.add(prefix);
+        }
+        else {
+            for (let i = 0; i < remaining.length; i++) {
+                permute(prefix + remaining[i], remaining.slice(0, i) + remaining.slice(i + 1));
+            }
+        }
+    };
+    permute('', str);
+    return Array.from(results);
+}

package/dist/transformations/titleCase.d.ts

@@ -1 +1,26 @@
+/**
+ * Converts a string to Title Case, capitalizing the first letter of each word.
+ *
+ * The conversion process includes:
+ * - Trimming whitespace from both ends.
+ * - Converting the entire string to lowercase.
+ * - Replacing non-word characters and underscores with spaces.
+ * - Collapsing multiple spaces into a single space.
+ * - Capitalizing the first character of each word.
+ * - Preserving spaces between words.
+ *
+ * If the input is `null` or `undefined`, it returns an empty string.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The Title Case formatted string.
+ *
+ * @example
+ * titleCase("hello world"); // "Hello World"
+ *
+ * @example
+ * titleCase("convert_to-title.case!"); // "Convert To Title Case"
+ *
+ * @example
+ * titleCase("  multiple   spaces here "); // "Multiple Spaces Here"
+ */
 export declare function titleCase(text: string): string;

package/dist/transformations/titleCase.js

@@ -1,6 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.titleCase = titleCase;
+/**
+ * Converts a string to Title Case, capitalizing the first letter of each word.
+ *
+ * The conversion process includes:
+ * - Trimming whitespace from both ends.
+ * - Converting the entire string to lowercase.
+ * - Replacing non-word characters and underscores with spaces.
+ * - Collapsing multiple spaces into a single space.
+ * - Capitalizing the first character of each word.
+ * - Preserving spaces between words.
+ *
+ * If the input is `null` or `undefined`, it returns an empty string.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The Title Case formatted string.
+ *
+ * @example
+ * titleCase("hello world"); // "Hello World"
+ *
+ * @example
+ * titleCase("convert_to-title.case!"); // "Convert To Title Case"
+ *
+ * @example
+ * titleCase("  multiple   spaces here "); // "Multiple Spaces Here"
+ */
 function titleCase(text) {
     if (text == null)
         return '';

package/dist/transformations/toSlug.d.ts

@@ -1 +1,25 @@
+/**
+ * Converts a string into a URL-friendly slug.
+ *
+ * The conversion process includes:
+ * - Converting the string to lowercase.
+ * - Trimming whitespace from both ends.
+ * - Replacing one or more whitespace characters with a single hyphen (`-`).
+ * - Removing all characters except word characters (letters, digits, and underscores) and hyphens.
+ *
+ * Throws an error if the input is not a string.
+ *
+ * @param {string} text - The input string to convert into a slug.
+ * @returns {string} The URL-friendly slug string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * toSlug("Hello World!"); // "hello-world"
+ *
+ * @example
+ * toSlug("  This is a test --- "); // "this-is-a-test"
+ *
+ * @example
+ * toSlug("Clean_URL--Slug123"); // "clean_url--slug123"
+ */
 export declare function toSlug(text: string): string;

package/dist/transformations/toSlug.js

@@ -1,13 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toSlug = toSlug;
+/**
+ * Converts a string into a URL-friendly slug.
+ *
+ * The conversion process includes:
+ * - Converting the string to lowercase.
+ * - Trimming whitespace from both ends.
+ * - Replacing one or more whitespace characters with a single hyphen (`-`).
+ * - Removing all characters except word characters (letters, digits, and underscores) and hyphens.
+ *
+ * Throws an error if the input is not a string.
+ *
+ * @param {string} text - The input string to convert into a slug.
+ * @returns {string} The URL-friendly slug string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * toSlug("Hello World!"); // "hello-world"
+ *
+ * @example
+ * toSlug("  This is a test --- "); // "this-is-a-test"
+ *
+ * @example
+ * toSlug("Clean_URL--Slug123"); // "clean_url--slug123"
+ */
 function toSlug(text) {
-    if (typeof text !== "string") {
-        throw new Error("Invalid argument. Expected a string.");
+    if (typeof text !== 'string') {
+        throw new Error('Invalid argument. Expected a string.');
     }
     return text
         .toLowerCase()
         .trim()
-        .replace(/[\s]+/g, "-")
-        .replace(/[^\w-]+/g, "");
+        .replace(/[\s]+/g, '-')
+        .replace(/[^\w-]+/g, '');
 }

package/dist/transformations/truncateText.d.ts

@@ -1 +1,26 @@
+/**
+ * Truncates a string to a specified maximum length and appends a suffix if truncated.
+ *
+ * If the text length is less than or equal to `maxLength`, the original text is returned.
+ * Otherwise, the text is cut off so that the total length including the suffix does not exceed `maxLength`.
+ *
+ * Throws a `TypeError` if input types are invalid or if `maxLength` is negative.
+ *
+ * @param {string} text - The input string to truncate.
+ * @param {number} maxLength - The maximum allowed length of the returned string including suffix.
+ * @param {string} [suffix='...'] - The string to append if truncation occurs.
+ * @returns {string} The truncated string with suffix if applicable.
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {Error} If `maxLength` is not a non-negative number.
+ * @throws {TypeError} If `suffix` is not a string.
+ *
+ * @example
+ * truncateText("Hello World", 8); // "Hello..."
+ *
+ * @example
+ * truncateText("Short text", 20); // "Short text"
+ *
+ * @example
+ * truncateText("Custom suffix example", 10, "---"); // "Custom---"
+ */
 export declare function truncateText(text: string, maxLength: number, suffix?: string): string;

package/dist/transformations/truncateText.js

@@ -1,15 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.truncateText = truncateText;
+/**
+ * Truncates a string to a specified maximum length and appends a suffix if truncated.
+ *
+ * If the text length is less than or equal to `maxLength`, the original text is returned.
+ * Otherwise, the text is cut off so that the total length including the suffix does not exceed `maxLength`.
+ *
+ * Throws a `TypeError` if input types are invalid or if `maxLength` is negative.
+ *
+ * @param {string} text - The input string to truncate.
+ * @param {number} maxLength - The maximum allowed length of the returned string including suffix.
+ * @param {string} [suffix='...'] - The string to append if truncation occurs.
+ * @returns {string} The truncated string with suffix if applicable.
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {Error} If `maxLength` is not a non-negative number.
+ * @throws {TypeError} If `suffix` is not a string.
+ *
+ * @example
+ * truncateText("Hello World", 8); // "Hello..."
+ *
+ * @example
+ * truncateText("Short text", 20); // "Short text"
+ *
+ * @example
+ * truncateText("Custom suffix example", 10, "---"); // "Custom---"
+ */
 function truncateText(text, maxLength, suffix = '...') {
     if (typeof text !== 'string') {
-        throw new Error("Input text must be a string.");
+        throw new TypeError('Input text must be a string.');
     }
     if (typeof maxLength !== 'number' || maxLength < 0) {
-        throw new Error("maxLength must be a non-negative number.");
+        throw new Error('maxLength must be a non-negative number.');
     }
     if (typeof suffix !== 'string') {
-        throw new Error("Suffix must be a string.");
+        throw new TypeError('Suffix must be a string.');
     }
     if (text.length <= maxLength) {
         return text;