stringzy 3.0.0 → 4.1.0

package/dist/transformations/initials.d.ts

@@ -1 +1,28 @@
+/**
+ * Extracts the initials from a given string.
+ *
+ * Splits the input text by whitespace, takes the first character of each word,
+ * and joins them together. Optionally limits the number of initials returned.
+ *
+ * Throws an error if the input is not a string or if the `limit` parameter
+ * is provided but not a non-negative number.
+ *
+ * @param {string} text - The input string from which to extract initials.
+ * @param {number} [limit] - Optional maximum number of initials to return.
+ * @returns {string} A string containing the initials.
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {Error} If `limit` is provided and is not a non-negative number.
+ *
+ * @example
+ * initials("John Doe"); // "JD"
+ *
+ * @example
+ * initials("John Ronald Reuel Tolkien", 2); // "JR"
+ *
+ * @example
+ * initials(" singleWord "); // "s"
+ *
+ * @example
+ * initials(""); // ""
+ */
 export declare function initials(text: string, limit?: number): string;

package/dist/transformations/initials.js

@@ -1,19 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initials = initials;
+/**
+ * Extracts the initials from a given string.
+ *
+ * Splits the input text by whitespace, takes the first character of each word,
+ * and joins them together. Optionally limits the number of initials returned.
+ *
+ * Throws an error if the input is not a string or if the `limit` parameter
+ * is provided but not a non-negative number.
+ *
+ * @param {string} text - The input string from which to extract initials.
+ * @param {number} [limit] - Optional maximum number of initials to return.
+ * @returns {string} A string containing the initials.
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {Error} If `limit` is provided and is not a non-negative number.
+ *
+ * @example
+ * initials("John Doe"); // "JD"
+ *
+ * @example
+ * initials("John Ronald Reuel Tolkien", 2); // "JR"
+ *
+ * @example
+ * initials(" singleWord "); // "s"
+ *
+ * @example
+ * initials(""); // ""
+ */
 function initials(text, limit) {
-    if (typeof text !== "string") {
-        throw new Error("Input must be a string");
+    if (typeof text !== 'string') {
+        throw new TypeError('Input must be a string');
     }
-    if (limit !== undefined && (typeof limit !== "number" || isNaN(limit))) {
-        throw new Error("Limit must be a valid number");
+    if (limit !== undefined && (typeof limit !== 'number' || isNaN(limit))) {
+        throw new Error('Limit must be a valid number');
     }
     if (limit !== undefined && limit < 0) {
-        throw new Error("Limit must be a non-negative number");
+        throw new Error('Limit must be a non-negative number');
     }
-    const words = text.trim().split(/\s+/).filter((word) => word.length > 0);
+    const words = text
+        .trim()
+        .split(/\s+/)
+        .filter((word) => word.length > 0);
     if (words.length === 0)
-        return "";
+        return '';
     const initialsArray = words.map((word) => word.charAt(0)).slice(0, limit !== null && limit !== void 0 ? limit : words.length);
-    return initialsArray.join("");
+    return initialsArray.join('');
 }

package/dist/transformations/kebabCase.d.ts

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

package/dist/transformations/kebabCase.js

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

package/dist/transformations/maskSegment.js

@@ -9,17 +9,15 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.maskSegment = maskSegment;
-function maskSegment(text, maskStart = 0, maskEnd = text.length, maskChar = "*") {
+function maskSegment(text, maskStart = 0, maskEnd = text.length, maskChar = '*') {
     if (maskStart < 0 || maskEnd > text.length || maskStart >= maskEnd) {
-        throw new Error("Invalid mask segment range");
+        throw new Error('Invalid mask segment range');
     }
     if (maskChar.length !== 1) {
-        throw new Error("Mask character must be a single character");
+        throw new Error('Mask character must be a single character');
     }
     if (maskStart === 0 && maskEnd === text.length) {
         return maskChar.repeat(text.length);
     }
-    return (text.slice(0, maskStart) +
-        maskChar.repeat(maskEnd - maskStart) +
-        text.slice(maskEnd));
+    return text.slice(0, maskStart) + maskChar.repeat(maskEnd - maskStart) + text.slice(maskEnd);
 }

package/dist/transformations/numberToText/helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checks if a number is negative
+ */
+export declare function isNegative(num: number): boolean;
+/**
+ * Gets the highest order of magnitude for a number
+ * @example getOrderOfMagnitude(1234) returns 1000
+ * @example getOrderOfMagnitude(567) returns 100
+ */
+export declare function getOrderOfMagnitude(num: number): number;

package/dist/transformations/numberToText/helpers.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNegative = isNegative;
+exports.getOrderOfMagnitude = getOrderOfMagnitude;
+/**
+ * Checks if a number is negative
+ */
+function isNegative(num) {
+    return num < 0;
+}
+/**
+ * Gets the highest order of magnitude for a number
+ * @example getOrderOfMagnitude(1234) returns 1000
+ * @example getOrderOfMagnitude(567) returns 100
+ */
+function getOrderOfMagnitude(num) {
+    const absNum = Math.abs(num);
+    if (absNum >= 1000000000000)
+        return 1000000000000;
+    if (absNum >= 1000000000)
+        return 1000000000;
+    if (absNum >= 1000000)
+        return 1000000;
+    if (absNum >= 1000)
+        return 1000;
+    if (absNum >= 100)
+        return 100;
+    if (absNum >= 10)
+        return 10;
+    return 1;
+}

package/dist/transformations/numberToText/implementation_EN.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts a number to its English textual representation.
+ *
+ * Handles negative numbers, numbers from 0 to 20, tens, hundreds, thousands, and larger magnitudes.
+ *
+ * @param num The number to convert.
+ * @returns The textual representation of the number in English.
+ */
+declare function numberToTextEn(num: number): string;
+export default numberToTextEn;

package/dist/transformations/numberToText/implementation_EN.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const helpers_1 = require("./helpers");
+/**
+ * Converts a number to its English textual representation.
+ *
+ * Handles negative numbers, numbers from 0 to 20, tens, hundreds, thousands, and larger magnitudes.
+ *
+ * @param num The number to convert.
+ * @returns The textual representation of the number in English.
+ */
+function numberToTextEn(num) {
+    if ((0, helpers_1.isNegative)(num)) {
+        return `minus ${numberToTextEn(Math.abs(num))}`;
+    }
+    // 0-20
+    if (num <= 20 && types_1.NUMBERS_EN[num]) {
+        return types_1.NUMBERS_EN[num];
+    }
+    // 21-99
+    if (num < 100) {
+        const tens = Math.floor(num / 10) * 10;
+        const ones = num % 10;
+        if (ones === 0) {
+            return types_1.NUMBERS_EN[tens];
+        }
+        return `${types_1.NUMBERS_EN[tens]}-${types_1.NUMBERS_EN[ones]}`;
+    }
+    // 100+
+    const magnitude = (0, helpers_1.getOrderOfMagnitude)(num);
+    const quotient = Math.floor(num / magnitude);
+    const remainder = num % magnitude;
+    // Special handling for hundreds
+    if (magnitude === 100) {
+        const result = `${numberToTextEn(quotient)} hundred`;
+        return remainder === 0 ? result : `${result} ${numberToTextEn(remainder)}`;
+    }
+    // 1000+
+    const magnitudeName = types_1.NUMBERS_EN[magnitude];
+    const quotientText = numberToTextEn(quotient);
+    const result = `${quotientText} ${magnitudeName}`;
+    return remainder === 0 ? result : `${result} ${numberToTextEn(remainder)}`;
+}
+exports.default = numberToTextEn;

package/dist/transformations/numberToText/implementation_PL.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts a number to its Polish textual representation.
+ *
+ * Handles negative numbers, numbers from 0 to billions, and applies correct Polish grammatical forms.
+ *
+ * @param num The number to convert.
+ * @returns The textual representation of the number in Polish.
+ */
+declare function numberToTextPl(num: number): string;
+export default numberToTextPl;

package/dist/transformations/numberToText/implementation_PL.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const helpers_1 = require("./helpers");
+/**
+ * Converts a number to its Polish textual representation.
+ *
+ * Handles negative numbers, numbers from 0 to billions, and applies correct Polish grammatical forms.
+ *
+ * @param num The number to convert.
+ * @returns The textual representation of the number in Polish.
+ */
+function numberToTextPl(num) {
+    if ((0, helpers_1.isNegative)(num)) {
+        return `minus ${numberToTextPl(Math.abs(num))}`;
+    }
+    // 0-20
+    if (num <= 20 && types_1.NUMBERS_PL[num]) {
+        return types_1.NUMBERS_PL[num];
+    }
+    // 21-99
+    if (num < 100) {
+        const tens = Math.floor(num / 10) * 10;
+        const ones = num % 10;
+        if (ones === 0) {
+            return types_1.NUMBERS_PL[tens];
+        }
+        return `${types_1.NUMBERS_PL[tens]} ${types_1.NUMBERS_PL[ones]}`;
+    }
+    // 100+
+    const magnitude = (0, helpers_1.getOrderOfMagnitude)(num);
+    const quotient = Math.floor(num / magnitude);
+    const remainder = num % magnitude;
+    // Special handling for hundreds
+    if (magnitude === 100) {
+        const hundredsForm = quotient * 100;
+        const result = types_1.NUMBERS_PL[hundredsForm];
+        return remainder === 0 ? result : `${result} ${numberToTextPl(remainder)}`;
+    }
+    // 1000+
+    let prefix = '';
+    if (quotient !== 1) {
+        prefix = numberToTextPl(quotient) + ' ';
+    }
+    const magnitudeForm = getPolishGrammaticalForm(magnitude, quotient);
+    const result = `${prefix}${magnitudeForm}`.trim();
+    return remainder === 0 ? result : `${result} ${numberToTextPl(remainder)}`;
+}
+/**
+ * Gets the correct grammatical form for Polish magnitude words
+ * based on the number (singular, few, many)
+ */
+function getPolishGrammaticalForm(magnitude, count) {
+    const forms = {
+        1000: ['tysiąc', 'tysiące', 'tysięcy'],
+        1000000: ['milion', 'miliony', 'milionów'],
+        1000000000: ['miliard', 'miliardy', 'miliardów'],
+        1000000000000: ['bilion', 'biliony', 'bilionów']
+    };
+    const formArray = forms[magnitude];
+    if (!formArray) {
+        throw new Error(`No grammatical forms defined for magnitude ${magnitude}`);
+    }
+    const lastTwoDigits = count % 100;
+    const lastDigit = count % 10;
+    if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
+        return formArray[2];
+    }
+    if (lastDigit === 1) {
+        return formArray[0];
+    }
+    else if (lastDigit >= 2 && lastDigit <= 4) {
+        return formArray[1];
+    }
+    else {
+        return formArray[2];
+    }
+}
+exports.default = numberToTextPl;

package/dist/transformations/numberToText/main.d.ts

@@ -0,0 +1,19 @@
+import { NumberToTextLanguage } from "./types";
+/**
+ * Converts a number to its text representation in the specified language.
+ *
+ * @param num - The number to convert (integer between -1,000,000,000,000 and 1,000,000,000,000)
+ * @param lang - The target language ('en' for English, 'pl' for Polish)
+ * @returns The text representation of the number
+ *
+ * @example
+ * numberToText(123) // "one hundred twenty-three"
+ * numberToText(123, 'pl') // "sto dwadzieścia trzy"
+ * numberToText(-45) // "minus forty-five"
+ * numberToText(1000000) // "one million"
+ * numberToText(1000000, 'pl') // "milion"
+ *
+ * @throws {TypeError} If num is not a valid integer or lang is not supported
+ * @throws {RangeError} If num is outside the supported range
+ */
+export declare function numberToText(num: number, lang?: NumberToTextLanguage): string;

package/dist/transformations/numberToText/main.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberToText = numberToText;
+const implementation_PL_1 = __importDefault(require("./implementation_PL"));
+const implementation_EN_1 = __importDefault(require("./implementation_EN"));
+/**
+ * Converts a number to its text representation in the specified language.
+ *
+ * @param num - The number to convert (integer between -1,000,000,000,000 and 1,000,000,000,000)
+ * @param lang - The target language ('en' for English, 'pl' for Polish)
+ * @returns The text representation of the number
+ *
+ * @example
+ * numberToText(123) // "one hundred twenty-three"
+ * numberToText(123, 'pl') // "sto dwadzieścia trzy"
+ * numberToText(-45) // "minus forty-five"
+ * numberToText(1000000) // "one million"
+ * numberToText(1000000, 'pl') // "milion"
+ *
+ * @throws {TypeError} If num is not a valid integer or lang is not supported
+ * @throws {RangeError} If num is outside the supported range
+ */
+function numberToText(num, lang = 'en') {
+    validateNumber(num);
+    validateLanguage(lang);
+    const langMap = {
+        en: implementation_EN_1.default,
+        pl: implementation_PL_1.default,
+    };
+    if (!langMap[lang]) {
+        throw new TypeError('Unsupported language');
+    }
+    return langMap[lang](num);
+}
+/////////////////////////////////////////
+//// Validation
+/////////////////////////////////////////
+/**
+ * Checks if the provided value is an integer within the allowed range.
+ *
+ * @param num - The value to check
+ * @throws {TypeError} If num is not an integer
+ * @throws {RangeError} If num is outside the range -1,000,000,000,000 to 1,000,000,000,000
+ */
+function validateNumber(num) {
+    if (typeof num !== 'number' || !Number.isInteger(num) || isNaN(num)) {
+        throw new TypeError('Num param should be number');
+    }
+    if (num < -1000000000000 || num > 1000000000000) {
+        throw new RangeError('Number must be between -1,000,000,000,000 and 1,000,000,000,000');
+    }
+}
+/**
+ * Checks if the provided language is supported.
+ *
+ * @param lang - The language code to check
+ * @throws {TypeError} If lang is not one of the supported languages
+ */
+function validateLanguage(lang) {
+    const validLanguages = ['en', 'pl'];
+    if (!validLanguages.includes(lang)) {
+        throw new TypeError(`Language must be one of: ${validLanguages.join(', ')}`);
+    }
+}

package/dist/transformations/numberToText/types.d.ts

@@ -0,0 +1,3 @@
+export type NumberToTextLanguage = 'en' | 'pl';
+export declare const NUMBERS_EN: Record<number, string>;
+export declare const NUMBERS_PL: Record<number, string>;

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(' ');
 }