@develia/commons 0.4.9 → 0.4.12

package/src/collections/index.ts

@@ -1,3 +1,3 @@
-export {default as DefaultWeakMap} from './default-weak-map.js'
-export {default as DefaultMap} from './default-map.js'
+export {default as DefaultWeakMap} from './default-weak-map.js'
+export {default as DefaultMap} from './default-map.js'
 export {default as CacheDictionary} from './cache-dictionary.js';

package/src/event-bus.ts

@@ -0,0 +1,84 @@
+// event.ts
+
+export abstract class Event {
+    readonly timestamp: Date;
+
+    protected constructor() {
+        this.timestamp = new Date();
+    }
+
+    toString(): string {
+        return `${this.constructor.name}(${this.timestamp.toISOString()})`;
+    }
+}
+
+type EventClass<T extends Event> = new (...args: any[]) => T;
+type Handler<T extends Event> = (event: T) => void;
+
+interface HandlerWrapper {
+    original: Function;
+    wrapped: (event: Event) => void;
+}
+
+export class EventBus {
+    private static _instance: EventBus | null = null;
+
+    static get shared(): EventBus {
+        return this._instance ??= new EventBus();
+    }
+
+    private _handlers = new Map<Function, HandlerWrapper[]>();
+
+    on<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        if (!this._handlers.has(type)) {
+            this._handlers.set(type, []);
+        }
+        this._handlers.get(type)!.push({
+            original: handler,
+            wrapped: (event: Event) => handler(event as T),
+        });
+    }
+
+    off<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        const handlers = this._handlers.get(type);
+        if (!handlers) return;
+
+        let index = handlers.findIndex((h) => h.original === handler);
+        if (index !== -1) {
+            handlers.splice(index, 1);
+        }
+    }
+
+    emit<T extends Event>(event: T): void {
+        const handlers = this._handlers.get(event.constructor);
+        if (!handlers) return;
+
+        for (const handler of [...handlers]) {
+            try {
+                handler.wrapped(event);
+            } catch (e) {
+                console.error(`[EventBus] Error en handler de ${event.constructor.name}:`, e);
+            }
+        }
+    }
+
+    once<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        const wrapper: Handler<T> = (event: T) => {
+            handler(event);
+            this.off(type, wrapper);
+        };
+        this.on(type, wrapper);
+    }
+
+    clear<T extends Event>(type: EventClass<T>): void {
+        this._handlers.delete(type);
+    }
+
+    clearAll(): void {
+        this._handlers.clear();
+    }
+
+    hasListeners<T extends Event>(type: EventClass<T>): boolean {
+        return (this._handlers.get(type)?.length ?? 0) > 0;
+    }
+}

package/src/index.ts

@@ -1,37 +1,38 @@
-// src/index.ts
-
-// ─── Types ───────────────────────────────────────────
-export * from './types.js';
-export {default as Type} from './type.js';
-export {default as TypeCode} from './type-code.js';
-
-// ─── Utilities ───────────────────────────────────────
-export * from './utilities.js';
-export * from './string.js';
-export * from './math.js';
-export {default as CancellablePromise} from "./cancellable-promise.js";
-
-// ─── Data Structures ────────────────────────────────
-export {default as KeyValuePair} from './key-value-pair.js';
-export {default as Order} from './order.js';
-
-// ─── Async & Timing ─────────────────────────────────
-export {default as Timer} from './timer.js';
-export {default as TimeSpan} from './timespan.js';
-export {default as Stopwatch} from './stopwatch.js';
-export {default as AsyncPoolExecutor} from './async-pool-executor.js';
-
-// ─── Patterns ────────────────────────────────────────
-export {default as Lazy} from './lazy.js';
-export {default as from, From} from './from.js';
-
-// ─── Web ─────────────────────────────────────────────
-export {default as CleanURLSearchParams} from './clean-url-search-params.js';
-/** @deprecated  */
-export {ajaxSubmit, ajaxSubmission, submitForm, formToObject} from './browser/index.js';
-
-// ─── Deprecated ──────────────────────────────────────
-/** @deprecated  */
-export * from './array.js';
-/** @deprecated  */
+// src/index.ts
+
+// ─── Types ───────────────────────────────────────────
+export * from './types.js';
+export {default as Type} from './type.js';
+export {default as TypeCode} from './type-code.js';
+
+// ─── Utilities ───────────────────────────────────────
+export * from './utilities.js';
+export * from './string.js';
+export * from './math.js';
+export {default as CancellablePromise} from "./cancellable-promise.js";
+
+// ─── Data Structures ────────────────────────────────
+export {default as KeyValuePair} from './key-value-pair.js';
+export {default as Order} from './order.js';
+
+// ─── Async & Timing ─────────────────────────────────
+export {default as Timer} from './timer.js';
+export {default as TimeSpan} from './timespan.js';
+export {default as Stopwatch} from './stopwatch.js';
+export {default as AsyncPoolExecutor} from './async-pool-executor.js';
+
+// ─── Patterns ────────────────────────────────────────
+export {default as Lazy} from './lazy.js';
+export {default as from, From} from './from.js';
+export {EventBus, Event} from './event-bus.js';
+
+// ─── Web ─────────────────────────────────────────────
+export {default as CleanURLSearchParams} from './clean-url-search-params.js';
+/** @deprecated  */
+export {ajaxSubmit, ajaxSubmission, submitForm, formToObject} from './browser/index.js';
+
+// ─── Deprecated ──────────────────────────────────────
+/** @deprecated  */
+export * from './array.js';
+/** @deprecated  */
 export * from './collections/index.js';

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;
 }