@develia/commons 0.4.8 → 0.4.12

package/src/parse.ts

@@ -0,0 +1,241 @@
+// parse.ts
+/**
+ * Options for {@link parseBoolean}.
+ */
+export interface ParseBooleanOptions {
+    /**
+     * Additional strings to consider as `true`.
+     * These are matched case-insensitively.
+     * @example ["oui", "ja"]
+     */
+    extraTruthy?: string[];
+
+    /**
+     * Additional strings to consider as `false`.
+     * These are matched case-insensitively.
+     * @example ["non", "nein"]
+     */
+    extraFalsy?: string[];
+}
+
+/**
+ * Options for {@link parseInteger}.
+ */
+export interface ParseIntegerOptions {
+    /**
+     * Numeric base for conversion.
+     * @default 10
+     */
+    radix?: number;
+
+    /**
+     * Thousands separator to strip before parsing.
+     * @example "." for "1.234.567" → 1234567
+     * @example "," for "1,234,567" → 1234567
+     */
+    thousandsSeparator?: string;
+}
+
+/**
+ * Options for {@link parseDecimal}.
+ */
+export interface ParseDecimalOptions {
+    /**
+     * Character used as decimal point.
+     * @default "."
+     */
+    decimalSeparator?: "." | ",";
+
+    /**
+     * Thousands separator to strip before parsing.
+     * @example "." for "1.234,56" (EU format)
+     * @example "," for "1,234.56" (US format)
+     */
+    thousandsSeparator?: string;
+}
+
+// ============================================
+// HELPERS
+// ============================================
+
+function stripThousands(value: string, separator?: string): string {
+    if (!separator) return value;
+    return value.split(separator).join("");
+}
+
+// ============================================
+// parseInteger
+// ============================================
+
+/**
+ * Safely parses a value into an integer.
+ * Returns `null` if the value cannot be parsed.
+ *
+ * - `null` or `undefined` → `null`
+ * - `number` → returned as-is (floats are truncated)
+ * - `string` → parsed with the given options
+ *
+ * @param value - The value to parse.
+ * @param options - Optional parsing configuration.
+ * @returns The parsed integer, or `null` on failure.
+ *
+ * @example
+ * ```ts
+ * parseInteger(42)                                        // 42
+ * parseInteger(3.7)                                       // 3
+ * parseInteger(null)                                      // null
+ * parseInteger(undefined)                                 // null
+ * parseInteger("42")                                      // 42
+ * parseInteger("1.234.567", { thousandsSeparator: "." })  // 1234567
+ * parseInteger("FF", { radix: 16 })                       // 255
+ * parseInteger("abc")                                     // null
+ * ```
+ */
+export function parseInteger(
+    value: string | number | null | undefined,
+    options: ParseIntegerOptions = {}
+): number | null {
+    if (value === null || value === undefined) return null;
+
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? Math.trunc(value) : null;
+    }
+
+    const { radix = 10, thousandsSeparator } = options;
+
+    const cleaned = stripThousands(value.trim(), thousandsSeparator);
+
+    if (cleaned === "") return null;
+    if (radix === 10 && !/^[+-]?\d+$/.test(cleaned)) return null;
+
+    const parsed = Number.parseInt(cleaned, radix);
+
+    return Number.isNaN(parsed) ? null : parsed;
+}
+
+// ============================================
+// parseDecimal
+// ============================================
+
+/**
+ * Safely parses a value into a floating-point number.
+ * Returns `null` if the value cannot be parsed.
+ *
+ * - `null` or `undefined` → `null`
+ * - `number` → returned as-is (if finite)
+ * - `string` → parsed with the given options
+ *
+ * Supports custom decimal and thousands separators, making it suitable
+ * for both US (`1,234.56`) and EU (`1.234,56`) number formats.
+ *
+ * @param value - The value to parse.
+ * @param options - Optional parsing configuration.
+ * @returns The parsed float, or `null` on failure.
+ *
+ * @example
+ * ```ts
+ * parseDecimal(3.14)                                                       // 3.14
+ * parseDecimal(null)                                                       // null
+ * parseDecimal(undefined)                                                  // null
+ * parseDecimal("3.14")                                                     // 3.14
+ * parseDecimal("3,14", { decimalSeparator: "," })                          // 3.14
+ * parseDecimal("1.234,56", { decimalSeparator: ",", thousandsSeparator: "." }) // 1234.56
+ * parseDecimal("abc")                                                      // null
+ * ```
+ */
+export function parseDecimal(
+    value: string | number | null | undefined,
+    options: ParseDecimalOptions = {}
+): number | null {
+    if (value === null || value === undefined) return null;
+
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+
+    const { decimalSeparator = ".", thousandsSeparator } = options;
+
+    let cleaned = stripThousands(value.trim(), thousandsSeparator);
+
+    if (cleaned === "") return null;
+
+    if (decimalSeparator === ",") {
+        const commaCount = (cleaned.match(/,/g) || []).length;
+        if (commaCount > 1) return null;
+        cleaned = cleaned.replace(",", ".");
+    }
+
+    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return null;
+
+    const parsed = Number.parseFloat(cleaned);
+
+    return Number.isNaN(parsed) || !Number.isFinite(parsed) ? null : parsed;
+}
+
+// ============================================
+// parseBoolean
+// ============================================
+
+const DEFAULT_TRUTHY = ["true", "1", "yes", "si", "sí", "on"];
+const DEFAULT_FALSY = ["false", "0", "no", "off"];
+
+/**
+ * Safely parses a value into a boolean.
+ * Returns `null` if the value cannot be interpreted as boolean.
+ *
+ * - `null` or `undefined` → `null`
+ * - `boolean` → returned as-is
+ * - `number` → `0` is `false`, any other finite number is `true`
+ * - `string` → matched case-insensitively against known truthy/falsy values
+ *
+ * Default truthy: `"true"`, `"1"`, `"yes"`, `"si"`, `"sí"`, `"on"`
+ * Default falsy:  `"false"`, `"0"`, `"no"`, `"off"`
+ *
+ * @param value - The value to parse.
+ * @param options - Optional parsing configuration.
+ * @returns The parsed boolean, or `null` on failure.
+ *
+ * @example
+ * ```ts
+ * parseBoolean(true)                                    // true
+ * parseBoolean(false)                                   // false
+ * parseBoolean(1)                                       // true
+ * parseBoolean(0)                                       // false
+ * parseBoolean(null)                                    // null
+ * parseBoolean(undefined)                               // null
+ * parseBoolean("yes")                                   // true
+ * parseBoolean("no")                                    // false
+ * parseBoolean("sí")                                    // true
+ * parseBoolean("TRUE")                                  // true
+ * parseBoolean("oui")                                   // null
+ * parseBoolean("oui", { extraTruthy: ["oui"] })         // true
+ * parseBoolean("nein", { extraFalsy: ["nein"] })        // false
+ * parseBoolean("whatever")                              // null
+ * ```
+ */
+export function parseBoolean(
+    value: string | number | boolean | null | undefined,
+    options: ParseBooleanOptions = {}
+): boolean | null {
+    if (value === null || value === undefined) return null;
+
+    if (typeof value === "boolean") return value;
+
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value !== 0 : null;
+    }
+
+    const { extraTruthy = [], extraFalsy = [] } = options;
+
+    const normalized = value.trim().toLowerCase();
+
+    if (normalized === "") return null;
+
+    const truthy = [...DEFAULT_TRUTHY, ...extraTruthy.map((s) => s.toLowerCase())];
+    const falsy = [...DEFAULT_FALSY, ...extraFalsy.map((s) => s.toLowerCase())];
+
+    if (truthy.includes(normalized)) return true;
+    if (falsy.includes(normalized)) return false;
+
+    return null;
+}

package/src/string.ts

@@ -6,7 +6,7 @@
  * @param {string} prefix - The prefix to ensure on the string.
  * @return {string} - The resulting string with the ensured prefix.
  */
-export function ensurePrefix(str: string, prefix: string) {
+export function ensurePrefix(str: string, prefix: string): string {
     if (!str.startsWith(prefix))
         return prefix + str
     return str
@@ -20,7 +20,7 @@ export function ensurePrefix(str: string, prefix: string) {
  * @param {string} suffix - The suffix to ensure.
  * @return {string} - The modified string with the suffix added if it was not already present.
  */
-export function ensureSuffix(str: string, suffix: string) {
+export function ensureSuffix(str: string, suffix: string): string {
     if (!str.endsWith(suffix))
         return str + suffix
     return str
@@ -46,4 +46,84 @@ export function format(template: string, ...args: any[]): string {
     return template.replace(regex, (match, key) => {
         return typeof args[key] !== 'undefined' ? args[key] : "";
     });
+}
+
+/**
+ * Splits a string into its constituent words, regardless of the original case
+ * style (camelCase, PascalCase, snake_case, kebab-case, CONSTANT_CASE,
+ * space-separated, etc.).
+ *
+ * @param {string} str - The string to split into words.
+ * @return {string[]} - The list of lowercase words extracted from the input.
+ */
+function toWords(str: string): string[] {
+    if (!str) return [];
+
+    return str
+        // Insert a space between a lowercase/digit and an uppercase letter (camelCase -> camel Case)
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        // Insert a space between consecutive uppercase letters followed by a lowercase letter (XMLParser -> XML Parser)
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        // Replace any non-alphanumeric character with a space
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+
+/**
+ * Converts a string to snake_case.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to snake_case.
+ */
+export function toSnakeCase(str: string): string {
+    return toWords(str).join('_');
+}
+
+/**
+ * Converts a string to kebab-case.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to kebab-case.
+ */
+export function toKebabCase(str: string): string {
+    return toWords(str).join('-');
+}
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to camelCase.
+ */
+export function toCamelCase(str: string): string {
+    const words = toWords(str);
+    if (words.length === 0) return '';
+    return words
+        .map((word, i) => i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+
+/**
+ * Converts a string to PascalCase.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to PascalCase.
+ */
+export function toPascalCase(str: string): string {
+    return toWords(str)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+
+/**
+ * Converts a string to CONSTANT_CASE (a.k.a. SCREAMING_SNAKE_CASE).
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to CONSTANT_CASE.
+ */
+export function toConstantCase(str: string): string {
+    return toWords(str).join('_').toUpperCase();
 }

package/src/type-code.ts

@@ -1,16 +1,16 @@
-enum TypeCode {
-    String    = 'string',
-    Number    = 'number',
-    Boolean   = 'boolean',
-    Symbol    = 'symbol',
-    BigInt    = 'bigint',
-    Null      = 'null',
-    Undefined = 'undefined',
-    Object    = 'object',
-    Function  = 'function',
-    Array     = 'array',
-    Unknown   = 'unknown',
-}
-
-
+enum TypeCode {
+    String    = 'string',
+    Number    = 'number',
+    Boolean   = 'boolean',
+    Symbol    = 'symbol',
+    BigInt    = 'bigint',
+    Null      = 'null',
+    Undefined = 'undefined',
+    Object    = 'object',
+    Function  = 'function',
+    Array     = 'array',
+    Unknown   = 'unknown',
+}
+
+
 export default TypeCode;