@develia/commons 0.4.12 → 0.4.14

package/src/parse.ts

@@ -1,241 +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;
+// 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;
 }