stringzy 3.0.0 → 4.0.0

package/dist/transformations/numberToText/types.js

@@ -0,0 +1,82 @@
+"use strict";
+/////////////////////////////////////////
+//// Type Definitions
+/////////////////////////////////////////
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NUMBERS_PL = exports.NUMBERS_EN = void 0;
+/////////////////////////////////////////
+//// Language Dictionaries
+/////////////////////////////////////////
+exports.NUMBERS_EN = {
+    0: 'zero',
+    1: 'one',
+    2: 'two',
+    3: 'three',
+    4: 'four',
+    5: 'five',
+    6: 'six',
+    7: 'seven',
+    8: 'eight',
+    9: 'nine',
+    10: 'ten',
+    11: 'eleven',
+    12: 'twelve',
+    13: 'thirteen',
+    14: 'fourteen',
+    15: 'fifteen',
+    16: 'sixteen',
+    17: 'seventeen',
+    18: 'eighteen',
+    19: 'nineteen',
+    20: 'twenty',
+    30: 'thirty',
+    40: 'forty',
+    50: 'fifty',
+    60: 'sixty',
+    70: 'seventy',
+    80: 'eighty',
+    90: 'ninety',
+    1000: 'thousand',
+    1000000: 'million',
+    1000000000: 'billion',
+    1000000000000: 'trillion'
+};
+exports.NUMBERS_PL = {
+    0: 'zero',
+    1: 'jeden',
+    2: 'dwa',
+    3: 'trzy',
+    4: 'cztery',
+    5: 'pięć',
+    6: 'sześć',
+    7: 'siedem',
+    8: 'osiem',
+    9: 'dziewięć',
+    10: 'dziesięć',
+    11: 'jedenaście',
+    12: 'dwanaście',
+    13: 'trzynaście',
+    14: 'czternaście',
+    15: 'piętnaście',
+    16: 'szesnaście',
+    17: 'siedemnaście',
+    18: 'osiemnaście',
+    19: 'dziewiętnaście',
+    20: 'dwadzieścia',
+    30: 'trzydzieści',
+    40: 'czterdzieści',
+    50: 'pięćdziesiąt',
+    60: 'sześćdziesiąt',
+    70: 'siedemdziesiąt',
+    80: 'osiemdziesiąt',
+    90: 'dziewięćdziesiąt',
+    100: 'sto',
+    200: 'dwieście',
+    300: 'trzysta',
+    400: 'czterysta',
+    500: 'pięćset',
+    600: 'sześćset',
+    700: 'siedemset',
+    800: 'osiemset',
+    900: 'dziewięćset'
+};

package/dist/transformations/pascalCase.d.ts

@@ -1 +1,26 @@
+/**
+ * Converts a given string to PascalCase format.
+ *
+ * The conversion process includes:
+ * - Trimming whitespace from both ends.
+ * - Converting all characters to lowercase.
+ * - Replacing non-word characters and underscores with spaces.
+ * - Collapsing multiple spaces into a single space.
+ * - Capitalizing the first letter of each word.
+ * - Removing all spaces to produce the PascalCase output.
+ *
+ * If the input is `null` or `undefined`, an empty string is returned.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The PascalCase formatted string.
+ *
+ * @example
+ * pascalCase("hello world"); // "HelloWorld"
+ *
+ * @example
+ * pascalCase("convert_to-pascal.case"); // "ConvertToPascalCase"
+ *
+ * @example
+ * pascalCase("  multiple   spaces  here "); // "MultipleSpacesHere"
+ */
 export declare function pascalCase(text: string): string;

package/dist/transformations/pascalCase.js

@@ -1,6 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pascalCase = pascalCase;
+/**
+ * Converts a given string to PascalCase format.
+ *
+ * The conversion process includes:
+ * - Trimming whitespace from both ends.
+ * - Converting all characters to lowercase.
+ * - Replacing non-word characters and underscores with spaces.
+ * - Collapsing multiple spaces into a single space.
+ * - Capitalizing the first letter of each word.
+ * - Removing all spaces to produce the PascalCase output.
+ *
+ * If the input is `null` or `undefined`, an empty string is returned.
+ *
+ * @param {string} text - The input string to convert.
+ * @returns {string} The PascalCase formatted string.
+ *
+ * @example
+ * pascalCase("hello world"); // "HelloWorld"
+ *
+ * @example
+ * pascalCase("convert_to-pascal.case"); // "ConvertToPascalCase"
+ *
+ * @example
+ * pascalCase("  multiple   spaces  here "); // "MultipleSpacesHere"
+ */
 function pascalCase(text) {
     if (text == null)
         return '';

package/dist/transformations/removeDuplicates.d.ts

@@ -1 +1,22 @@
+/**
+ * Removes duplicate words from a string, preserving the original word order.
+ *
+ * Splits the input string by spaces, filters out duplicate words,
+ * and joins the unique words back into a string separated by spaces.
+ *
+ * Throws an error if the input is not a string.
+ *
+ * @param {string} text - The input string from which duplicate words will be removed.
+ * @returns {string} A string containing only unique words in their original order.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * removeDuplicates("hello world hello"); // "hello world"
+ *
+ * @example
+ * removeDuplicates("this is is a test test"); // "this is a test"
+ *
+ * @example
+ * removeDuplicates(""); // ""
+ */
 export declare function removeDuplicates(text: string): string;

package/dist/transformations/removeDuplicates.js

@@ -1,13 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeDuplicates = removeDuplicates;
+/**
+ * Removes duplicate words from a string, preserving the original word order.
+ *
+ * Splits the input string by spaces, filters out duplicate words,
+ * and joins the unique words back into a string separated by spaces.
+ *
+ * Throws an error if the input is not a string.
+ *
+ * @param {string} text - The input string from which duplicate words will be removed.
+ * @returns {string} A string containing only unique words in their original order.
+ * @throws {TypeError} If the input is not a string.
+ *
+ * @example
+ * removeDuplicates("hello world hello"); // "hello world"
+ *
+ * @example
+ * removeDuplicates("this is is a test test"); // "this is a test"
+ *
+ * @example
+ * removeDuplicates(""); // ""
+ */
 function removeDuplicates(text) {
-    if (typeof text !== "string") {
-        throw new Error("Input must be a string");
+    if (typeof text !== 'string') {
+        throw new TypeError('Input must be a string');
     }
     const wordSet = new Set();
-    text.split(" ").forEach((word) => {
+    text.split(' ').forEach((word) => {
         wordSet.add(word);
     });
-    return Array.from(wordSet).join(" ");
+    return Array.from(wordSet).join(' ');
 }

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/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/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;