@develia/commons 0.4.16 → 0.4.18

package/src/parse.ts

@@ -1,241 +1,252 @@
-// 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("");
+}
+
+function isValidInteger(value: string, radix: number): boolean {
+    if (!Number.isInteger(radix) || radix < 2 || radix > 36) return false;
+
+    const signless = value.replace(/^[+-]/, "");
+    if (signless === "") return false;
+
+    const digits = "0123456789abcdefghijklmnopqrstuvwxyz".slice(0, radix);
+
+    return [...signless.toLowerCase()].every((char) => digits.includes(char));
+}
+
+// ============================================
+// 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 (!isValidInteger(cleaned, radix)) 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/patch.ts

@@ -1,80 +1,80 @@
-import type {Constructor} from "./types.js";
-
-export type PureMethod<T extends object, A extends any[] = any[], R = any> =
-    (obj: T, ...args: A) => R;
-
-export type PatchSpec<T extends object> =
-    | Record<string, PureMethod<T, any[], any>>
-    | Map<PropertyKey, PureMethod<T, any[], any>>;
-
-
-export function patch<C extends Constructor<any>>(
-    targetOrCtor: C,
-    fns: PatchSpec<InstanceType<C>>
-): Map<PropertyKey, PropertyDescriptor | null>;
-
-export function patch<T extends object>(
-    targetOrCtor: T,
-    fns: PatchSpec<T>
-): Map<PropertyKey, PropertyDescriptor | null>;
-
-/**
- * Devuelve un Map donde:
- *  - clave -> null    (método añadido nuevo)
- *  - clave -> descriptorOriginal (método sustituido)
- */
-export function patch(
-    targetOrCtor: any,
-    fns: PatchSpec<any>
-): Map<PropertyKey, PropertyDescriptor | null> {
-    const target = typeof targetOrCtor === "function" ? targetOrCtor.prototype : targetOrCtor;
-
-    const result = new Map<PropertyKey, PropertyDescriptor | null>();
-    const entries: Array<[PropertyKey, PureMethod<any>]> =
-        fns instanceof Map ? [...fns.entries()] : Object.entries(fns) as any;
-
-    for (const [key, fn] of entries) {
-        const prev = Object.getOwnPropertyDescriptor(target, key);
-        const method = function (this: unknown, ...args: unknown[]) {
-            return (fn as any)(this, ...args);
-        };
-        try {
-            Object.defineProperty(target, key, {
-                value: method,
-                writable: true,
-                configurable: true,
-                enumerable: false,
-            });
-            result.set(key, prev ?? null);
-        } catch { /* ignorar */
-        }
-    }
-    return result;
-}
-
-// Overloads unpatch
-export function unpatch<C extends Constructor<any>>(
-    targetOrCtor: C,
-    changes: Map<PropertyKey, PropertyDescriptor | null>
-): void;
-export function unpatch<T extends object>(
-    targetOrCtor: T,
-    changes: Map<PropertyKey, PropertyDescriptor | null>
-): void;
-
-/**
- * Revierte un patch a partir del mapa devuelto por `patch`.
- */
-export function unpatch(targetOrCtor: any, changes: Map<PropertyKey, PropertyDescriptor | null>): void {
-    const target = typeof targetOrCtor === "function" ? targetOrCtor.prototype : targetOrCtor;
-    for (const [key, prev] of changes) {
-        try {
-            if (prev === null) {
-                if (Object.prototype.hasOwnProperty.call(target, key)) delete target[key];
-            } else {
-                Object.defineProperty(target, key, prev);
-            }
-        } catch { /* ignorar */
-        }
-    }
+import type {Constructor} from "./types.js";
+
+export type PureMethod<T extends object, A extends any[] = any[], R = any> =
+    (obj: T, ...args: A) => R;
+
+export type PatchSpec<T extends object> =
+    | Record<string, PureMethod<T, any[], any>>
+    | Map<PropertyKey, PureMethod<T, any[], any>>;
+
+
+export function patch<C extends Constructor<any>>(
+    targetOrCtor: C,
+    fns: PatchSpec<InstanceType<C>>
+): Map<PropertyKey, PropertyDescriptor | null>;
+
+export function patch<T extends object>(
+    targetOrCtor: T,
+    fns: PatchSpec<T>
+): Map<PropertyKey, PropertyDescriptor | null>;
+
+/**
+ * Devuelve un Map donde:
+ *  - clave -> null    (método añadido nuevo)
+ *  - clave -> descriptorOriginal (método sustituido)
+ */
+export function patch(
+    targetOrCtor: any,
+    fns: PatchSpec<any>
+): Map<PropertyKey, PropertyDescriptor | null> {
+    const target = typeof targetOrCtor === "function" ? targetOrCtor.prototype : targetOrCtor;
+
+    const result = new Map<PropertyKey, PropertyDescriptor | null>();
+    const entries: Array<[PropertyKey, PureMethod<any>]> =
+        fns instanceof Map ? [...fns.entries()] : Object.entries(fns) as any;
+
+    for (const [key, fn] of entries) {
+        const prev = Object.getOwnPropertyDescriptor(target, key);
+        const method = function (this: unknown, ...args: unknown[]) {
+            return (fn as any)(this, ...args);
+        };
+        try {
+            Object.defineProperty(target, key, {
+                value: method,
+                writable: true,
+                configurable: true,
+                enumerable: false,
+            });
+            result.set(key, prev ?? null);
+        } catch { /* ignorar */
+        }
+    }
+    return result;
+}
+
+// Overloads unpatch
+export function unpatch<C extends Constructor<any>>(
+    targetOrCtor: C,
+    changes: Map<PropertyKey, PropertyDescriptor | null>
+): void;
+export function unpatch<T extends object>(
+    targetOrCtor: T,
+    changes: Map<PropertyKey, PropertyDescriptor | null>
+): void;
+
+/**
+ * Revierte un patch a partir del mapa devuelto por `patch`.
+ */
+export function unpatch(targetOrCtor: any, changes: Map<PropertyKey, PropertyDescriptor | null>): void {
+    const target = typeof targetOrCtor === "function" ? targetOrCtor.prototype : targetOrCtor;
+    for (const [key, prev] of changes) {
+        try {
+            if (prev === null) {
+                if (Object.prototype.hasOwnProperty.call(target, key)) delete target[key];
+            } else {
+                Object.defineProperty(target, key, prev);
+            }
+        } catch { /* ignorar */
+        }
+    }
 }