@develia/commons 0.4.7 → 0.4.9

package/src/cancellable-promise.ts

@@ -0,0 +1,77 @@
+type CancellablePromiseExecutor<T> = (
+    resolve: (value: T | PromiseLike<T>) => void,
+    reject: (reason?: unknown) => void,
+    signal: AbortSignal
+) => void;
+
+export default class CancellablePromise<T> extends Promise<T> {
+
+    private _controller: AbortController;
+
+    static get [Symbol.species]() {
+        return Promise;
+    }
+
+    constructor(executor: CancellablePromiseExecutor<T>) {
+        const controller = new AbortController();
+
+        super((resolve, reject) => {
+            controller.signal.addEventListener("abort", () => {
+                reject(controller.signal.reason);
+            });
+
+            executor(resolve, reject, controller.signal);
+        });
+
+        this._controller = controller;
+    }
+
+    get cancelled(): boolean {
+        return this._controller.signal.aborted;
+    }
+
+    cancel(reason: unknown = new Error("Promesa cancelada")): void {
+        if (!this.cancelled) {
+            this._controller.abort(reason);
+        }
+    }
+
+    static async compete<T>(promises: CancellablePromise<T>[]): Promise<T> {
+        return await Promise.race(promises).then(
+            (resultado) => {
+                for (const p of promises) {
+                    p.cancel();
+                }
+                return resultado;
+            },
+            (error) => {
+                for (const p of promises) {
+                    p.cancel();
+                }
+                throw error;
+            }
+        );
+    }
+
+    static async cooperate<T>(promises: CancellablePromise<T>[]): Promise<T[]> {
+        try {
+            return await Promise.all(promises);
+        } catch (error) {
+            for (const p of promises) {
+                p.cancel();
+            }
+            throw error;
+        }
+    }
+
+    static withTimeout<T>(executor: CancellablePromiseExecutor<T>, ms: number): CancellablePromise<T> {
+        return new CancellablePromise<T>((resolve, reject, signal) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Timeout: ${ms}ms`));
+            }, ms);
+
+            signal.addEventListener("abort", () => clearTimeout(timer));
+            executor(resolve, reject, signal);
+        });
+    }
+}

package/src/index.ts

@@ -9,6 +9,7 @@ export {default as TypeCode} from './type-code.js';
 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';
@@ -27,7 +28,7 @@ export {default as from, From} from './from.js';
 // ─── Web ─────────────────────────────────────────────
 export {default as CleanURLSearchParams} from './clean-url-search-params.js';
 /** @deprecated  */
-export * from './browser/index.js';
+export {ajaxSubmit, ajaxSubmission, submitForm, formToObject} from './browser/index.js';
 
 // ─── Deprecated ──────────────────────────────────────
 /** @deprecated  */

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/dist/cjs/browser/gps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"gps.js","sourceRoot":"","sources":["../../../src/browser/gps.ts"],"names":[],"mappings":";;AAqBA,wCA0DC;AA1DM,KAAK,UAAU,cAAc,CAAC,UAA8B,EAAE;IAGjE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAChE,CAAC;IAGD,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;QACN,CAAC;IACL,CAAC;IAGD,MAAM,cAAc,GAAoB;QACpC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI;QACtD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;QACjC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;KACtC,CAAC;IAEF,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChD,SAAS,CAAC,WAAW,CAAC,kBAAkB,CACpC,CAAC,QAAQ,EAAE,EAAE;YACT,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC;YACvC,OAAO,CAAC;gBACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS;aACZ,CAAC,CAAC;QACP,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACN,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACjB,KAAK,KAAK,CAAC,iBAAiB;oBACxB,MAAM,CAAC,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC,CAAC;oBAC3D,MAAM;gBACV,KAAK,KAAK,CAAC,oBAAoB;oBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC;oBACzD,MAAM;gBACV,KAAK,KAAK,CAAC,OAAO;oBACd,MAAM,CAAC,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC,CAAC;oBACvE,MAAM;gBACV;oBACI,MAAM,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;YACxE,CAAC;QACL,CAAC,EACD,cAAc,CACjB,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/esm/browser/gps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"gps.js","sourceRoot":"","sources":["../../../src/browser/gps.ts"],"names":[],"mappings":"AAqBA,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAA8B,EAAE;IAGjE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAChE,CAAC;IAGD,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;QACN,CAAC;IACL,CAAC;IAGD,MAAM,cAAc,GAAoB;QACpC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI;QACtD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;QACjC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;KACtC,CAAC;IAEF,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChD,SAAS,CAAC,WAAW,CAAC,kBAAkB,CACpC,CAAC,QAAQ,EAAE,EAAE;YACT,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC;YACvC,OAAO,CAAC;gBACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS;aACZ,CAAC,CAAC;QACP,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACN,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACjB,KAAK,KAAK,CAAC,iBAAiB;oBACxB,MAAM,CAAC,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC,CAAC;oBAC3D,MAAM;gBACV,KAAK,KAAK,CAAC,oBAAoB;oBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC;oBACzD,MAAM;gBACV,KAAK,KAAK,CAAC,OAAO;oBACd,MAAM,CAAC,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC,CAAC;oBACvE,MAAM;gBACV;oBACI,MAAM,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;YACxE,CAAC;QACL,CAAC,EACD,cAAc,CACjB,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/types/browser/gps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"gps.d.ts","sourceRoot":"","sources":["../../../src/browser/gps.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,wBAAsB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0D3F"}

package/dist/web/browser/gps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"gps.js","sourceRoot":"","sources":["../../../src/browser/gps.ts"],"names":[],"mappings":"AAqBA,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAA8B,EAAE;IAGjE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAChE,CAAC;IAGD,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;QACN,CAAC;IACL,CAAC;IAGD,MAAM,cAAc,GAAoB;QACpC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI;QACtD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;QACjC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;KACtC,CAAC;IAEF,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChD,SAAS,CAAC,WAAW,CAAC,kBAAkB,CACpC,CAAC,QAAQ,EAAE,EAAE;YACT,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC;YACvC,OAAO,CAAC;gBACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS;aACZ,CAAC,CAAC;QACP,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACN,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACjB,KAAK,KAAK,CAAC,iBAAiB;oBACxB,MAAM,CAAC,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC,CAAC;oBAC3D,MAAM;gBACV,KAAK,KAAK,CAAC,oBAAoB;oBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC;oBACzD,MAAM;gBACV,KAAK,KAAK,CAAC,OAAO;oBACd,MAAM,CAAC,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC,CAAC;oBACvE,MAAM;gBACV;oBACI,MAAM,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;YACxE,CAAC;QACL,CAAC,EACD,cAAc,CACjB,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC"}