houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
1 lines • 9.6 kB
Source Map (JSON)
{"version":3,"file":"NumberUtils.mjs","sources":["../src/NumberUtils.ts"],"sourcesContent":["/**\n * @module NumberUtils\n * @description A comprehensive collection of utility functions for number manipulation, formatting, and mathematical operations.\n * @example\n * ```typescript\n * import { NumberUtils } from 'houser-js-utils';\n *\n * // Format currency\n * const price = NumberUtils.formatCurrency(1234.56); // \"$1,234.56\"\n *\n * // Check if number is prime\n * const isPrime = NumberUtils.isPrime(17); // true\n *\n * // Round to decimal places\n * const rounded = NumberUtils.round(3.14159, 2); // 3.14\n * ```\n */\n\nexport const NumberUtils = {\n /**\n * Clamps a number between a minimum and maximum value (inclusive).\n * @param value - The number to clamp\n * @param min - The minimum allowed value\n * @param max - The maximum allowed value\n * @returns The clamped number within the specified range\n * @example\n * ```typescript\n * NumberUtils.clamp(10, 0, 5); // Returns 5\n * NumberUtils.clamp(-10, 0, 5); // Returns 0\n * NumberUtils.clamp(3, 0, 5); // Returns 3\n * ```\n */\n clamp(value: number, min: number, max: number): number {\n return Math.min(Math.max(value, min), max);\n },\n\n /**\n * Formats a number as currency using Intl.NumberFormat.\n * @param value - The number to format as currency\n * @param locale - The locale to use for formatting (default: 'en-US')\n * @param currency - The currency code (default: 'USD')\n * @returns The formatted currency string\n * @example\n * ```typescript\n * NumberUtils.formatCurrency(1234.56); // Returns \"$1,234.56\"\n * NumberUtils.formatCurrency(1000, 'de-DE', 'EUR'); // Returns \"1.000,00 €\"\n * NumberUtils.formatCurrency(500, 'ja-JP', 'JPY'); // Returns \"¥500\"\n * ```\n */\n formatCurrency(\n value: number,\n locale: string = \"en-US\",\n currency: string = \"USD\"\n ): string {\n return new Intl.NumberFormat(locale, {\n style: \"currency\",\n currency,\n }).format(value);\n },\n\n /**\n * Formats a number with locale-appropriate thousands separators.\n * @param value - The number to format\n * @param locale - The locale to use for formatting (default: 'en-US')\n * @returns The formatted number string with thousands separators\n * @example\n * ```typescript\n * NumberUtils.formatWithThousandsSeparator(1234567); // Returns \"1,234,567\"\n * NumberUtils.formatWithThousandsSeparator(1234567, 'de-DE'); // Returns \"1.234.567\"\n * NumberUtils.formatWithThousandsSeparator(1234567, 'fr-FR'); // Returns \"1 234 567\"\n * ```\n */\n formatWithThousandsSeparator(\n value: number,\n locale: string = \"en-US\"\n ): string {\n return new Intl.NumberFormat(locale).format(value);\n },\n\n /**\n * Checks if a number is between two values (inclusive).\n * @param value - The number to check\n * @param min - The minimum value (inclusive)\n * @param max - The maximum value (inclusive)\n * @returns True if the number is between min and max (inclusive), false otherwise\n * @example\n * ```typescript\n * NumberUtils.isBetween(5, 1, 10); // Returns true\n * NumberUtils.isBetween(0, 1, 10); // Returns false\n * NumberUtils.isBetween(10, 1, 10); // Returns true\n * ```\n */\n isBetween(value: number, min: number, max: number): boolean {\n return value >= min && value <= max;\n },\n\n /**\n * Checks if a number is even.\n * @param value - The number to check\n * @returns True if the number is even, false otherwise\n * @example\n * ```typescript\n * NumberUtils.isEven(4); // Returns true\n * NumberUtils.isEven(5); // Returns false\n * NumberUtils.isEven(0); // Returns true\n * ```\n */\n isEven(value: number): boolean {\n return value % 2 === 0;\n },\n\n /**\n * Checks if a number is odd.\n * @param value - The number to check\n * @returns True if the number is odd, false otherwise\n * @example\n * ```typescript\n * NumberUtils.isOdd(5); // Returns true\n * NumberUtils.isOdd(4); // Returns false\n * NumberUtils.isOdd(1); // Returns true\n * ```\n */\n isOdd(value: number): boolean {\n return value % 2 !== 0;\n },\n\n /**\n * Checks if a number is prime using an optimized algorithm.\n * @param value - The number to check for primality\n * @returns True if the number is prime, false otherwise\n * @example\n * ```typescript\n * NumberUtils.isPrime(17); // Returns true\n * NumberUtils.isPrime(4); // Returns false\n * NumberUtils.isPrime(2); // Returns true\n * NumberUtils.isPrime(1); // Returns false\n * ```\n */\n isPrime(value: number): boolean {\n if (value <= 1) return false;\n if (value <= 3) return true;\n if (value % 2 === 0 || value % 3 === 0) return false;\n\n for (let i = 5; i * i <= value; i += 6) {\n if (value % i === 0 || value % (i + 2) === 0) return false;\n }\n return true;\n },\n\n /**\n * Generates a random integer between min and max (inclusive).\n * @param min - The minimum value (inclusive)\n * @param max - The maximum value (inclusive)\n * @returns A random integer between min and max\n * @example\n * ```typescript\n * NumberUtils.randomInt(1, 6); // Returns a random number between 1 and 6 (like a dice roll)\n * NumberUtils.randomInt(10, 20); // Returns a random number between 10 and 20\n * ```\n */\n randomInt(min: number, max: number): number {\n return Math.floor(Math.random() * (max - min + 1)) + min;\n },\n\n /**\n * Rounds a number to a specified number of decimal places.\n * @param value - The number to round\n * @param decimals - The number of decimal places (default: 0)\n * @returns The rounded number\n * @example\n * ```typescript\n * NumberUtils.round(3.14159, 2); // Returns 3.14\n * NumberUtils.round(2.7); // Returns 3\n * NumberUtils.round(1.005, 2); // Returns 1.01\n * ```\n */\n round(value: number, decimals: number = 0): number {\n const factor = Math.pow(10, decimals);\n // Add a small epsilon to handle floating-point precision issues\n const epsilon = 1e-10;\n return Math.round((value + epsilon) * factor) / factor;\n },\n\n /**\n * Formats a number with a fixed number of decimal places.\n * @param value - The number or string to format\n * @param decimals - The number of decimal places to display\n * @returns The formatted number as a string with fixed decimal places\n * @example\n * ```typescript\n * NumberUtils.formatWithDecimals(3.14159, 2); // Returns \"3.14\"\n * NumberUtils.formatWithDecimals(5, 3); // Returns \"5.000\"\n * NumberUtils.formatWithDecimals(\"invalid\", 2); // Returns \"0.00\"\n * ```\n */\n formatWithDecimals(value: number | string, decimals: number): string {\n const num = typeof value === \"string\" ? parseFloat(value) : value;\n\n if (isNaN(num)) {\n return `0.${\"0\".repeat(decimals)}`;\n }\n\n return num.toFixed(decimals);\n },\n\n /**\n * Truncates a number to a specified number of decimal places (no rounding).\n * @param value - The number to truncate\n * @param decimals - The number of decimal places to keep (default: 0)\n * @returns The truncated number\n * @example\n * ```typescript\n * NumberUtils.truncate(3.14159, 2); // Returns 3.14\n * NumberUtils.truncate(2.99, 1); // Returns 2.9\n * NumberUtils.truncate(5.999); // Returns 5\n * ```\n */\n truncate(value: number, decimals: number = 0): number {\n const factor = Math.pow(10, decimals);\n return Math.trunc(value * factor) / factor;\n },\n};\n"],"names":[],"mappings":"AAkBO,MAAM,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAczB,MAAM,OAAe,KAAa,KAAqB;AACrD,WAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,eACE,OACA,SAAiB,SACjB,WAAmB,OACX;AACR,WAAO,IAAI,KAAK,aAAa,QAAQ;AAAA,MACnC,OAAO;AAAA,MACP;AAAA,IAAA,CACD,EAAE,OAAO,KAAK;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,6BACE,OACA,SAAiB,SACT;AACR,WAAO,IAAI,KAAK,aAAa,MAAM,EAAE,OAAO,KAAK;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,UAAU,OAAe,KAAa,KAAsB;AAC1D,WAAO,SAAS,OAAO,SAAS;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,OAAO,OAAwB;AAC7B,WAAO,QAAQ,MAAM;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,OAAwB;AAC5B,WAAO,QAAQ,MAAM;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,QAAQ,OAAwB;AAC9B,QAAI,SAAS,EAAG,QAAO;AACvB,QAAI,SAAS,EAAG,QAAO;AACvB,QAAI,QAAQ,MAAM,KAAK,QAAQ,MAAM,EAAG,QAAO;AAE/C,aAAS,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK,GAAG;AACtC,UAAI,QAAQ,MAAM,KAAK,SAAS,IAAI,OAAO,EAAG,QAAO;AAAA,IACvD;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,UAAU,KAAa,KAAqB;AAC1C,WAAO,KAAK,MAAM,KAAK,OAAA,KAAY,MAAM,MAAM,EAAE,IAAI;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,MAAM,OAAe,WAAmB,GAAW;AACjD,UAAM,SAAS,KAAK,IAAI,IAAI,QAAQ;AAEpC,UAAM,UAAU;AAChB,WAAO,KAAK,OAAO,QAAQ,WAAW,MAAM,IAAI;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,mBAAmB,OAAwB,UAA0B;AACnE,UAAM,MAAM,OAAO,UAAU,WAAW,WAAW,KAAK,IAAI;AAE5D,QAAI,MAAM,GAAG,GAAG;AACd,aAAO,KAAK,IAAI,OAAO,QAAQ,CAAC;AAAA,IAClC;AAEA,WAAO,IAAI,QAAQ,QAAQ;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,SAAS,OAAe,WAAmB,GAAW;AACpD,UAAM,SAAS,KAAK,IAAI,IAAI,QAAQ;AACpC,WAAO,KAAK,MAAM,QAAQ,MAAM,IAAI;AAAA,EACtC;AACF;"}