@develia/commons 0.4.26 → 0.6.1

package/src/clean-url-search-params.ts

@@ -7,12 +7,12 @@ function isRecordParams(params: unknown): params is Record<string, any> {
         typeof (params as any)[Symbol.iterator] !== 'function';
 }
 
-function appendCleanValue(params: URLSearchParams, key: string, value: any): void {
+function appendNonNullishValues(params: URLSearchParams, key: string, value: any): void {
     if (value === null || value === undefined) return;
 
     if (Array.isArray(value)) {
         for (const item of value) {
-            appendCleanValue(params, key, item);
+            appendNonNullishValues(params, key, item);
         }
         return;
     }
@@ -31,7 +31,7 @@ export default class CleanURLSearchParams extends URLSearchParams {
 
         // Filtrar `null` y `undefined` antes de añadirlos a URLSearchParams
         for (const [key, value] of Object.entries(params)) {
-            appendCleanValue(this, key, value);
+            appendNonNullishValues(this, key, value);
         }
     }
 }

package/src/collections/from.ts

@@ -485,7 +485,7 @@ export class From<T> implements Iterable<T> {
             array.sort((a, b) => {
                 const aValue = mapper(a);
                 const bValue = mapper(b);
-                return aValue > bValue ? 1 : bValue < aValue ? -1 : 0;
+                return aValue > bValue ? -1 : aValue < bValue ? 1 : 0;
             });
         } else {
             throw new Error("invalid order argument");
@@ -713,11 +713,11 @@ export class From<T> implements Iterable<T> {
 
 
     /**
-     * Concatenates two sequences.
+     * The elements of this sequence followed by those of the other, duplicates included, as LINQ's Concat.
      * @param {Iterable<T>} other - The other sequence.
      * @returns {From<T>} A new From instance.
      */
-    public union(other: Iterable<T>): From<T> {
+    public concat(other: Iterable<T>): From<T> {
         const self = this;
         return From.fn<T>(function* () {
             yield* self;
@@ -726,7 +726,19 @@ export class From<T> implements Iterable<T> {
     }
 
     /**
-     * Correlates the elements of two sequences based on matching keys.
+     * The set union, as LINQ's Union: the elements of this sequence and then those of the other, each one once (the
+     * first time it appears), compared as distinct() does.
+     * @param {Iterable<T>} other - The other sequence.
+     * @param {EqualityComparer<T>} [equalityComparer] - Optional equality comparer; shallowEqual when not given.
+     * @returns {From<T>} A new From instance.
+     */
+    public union(other: Iterable<T>, equalityComparer?: EqualityComparer<T>): From<T> {
+        return this.concat(other).distinct(equalityComparer);
+    }
+
+    /**
+     * Correlates the elements of two sequences based on matching keys: one result per matching pair, so an element
+     * that matches several elements of the other sequence gives one result for each.
      * @template T2, R, R2
      * @param {Iterable<T2>} other - The other sequence.
      * @param {UnaryFunction<T, R>} thisKeySelector - Key selector for this sequence.
@@ -738,18 +750,20 @@ export class From<T> implements Iterable<T> {
 
         const self = this;
         return From.fn<R2>(() => {
-            const otherByKey = new Map<R, T2>();
-            for (let item of other) {
-                otherByKey.set(otherKeySelector(item), item);
+            const otherByKey = groupItemsByKey(other, otherKeySelector);
+            const results: R2[] = [];
+            for (const item of self) {
+                for (const otherItem of otherByKey.get(thisKeySelector(item)) ?? []) {
+                    results.push(resultSelector(item, otherItem));
+                }
             }
-            return Array.from(self)
-                        .filter(item => otherByKey.has(thisKeySelector(item)))
-                        .map(item => resultSelector(item, otherByKey.get(thisKeySelector(item))!));
+            return results;
         });
     }
 
     /**
-     * Performs a left join on two sequences.
+     * Performs a left join on two sequences: one result per matching pair, and one with `undefined` for each element of
+     * this sequence that matches none.
      * @template U, K, R
      * @param {Iterable<U>} other - The other sequence.
      * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
@@ -761,11 +775,19 @@ export class From<T> implements Iterable<T> {
 
         const self = this;
         return From.fn<R>(() => {
-            const otherByKey = new Map<K, U>();
-            for (let item of other) {
-                otherByKey.set(otherKeySelector(item), item);
+            const otherByKey = groupItemsByKey(other, otherKeySelector);
+            const results: R[] = [];
+            for (const item of self) {
+                const matches = otherByKey.get(thisKeySelector(item));
+                if (matches === undefined) {
+                    results.push(resultSelector(item, undefined));
+                    continue;
+                }
+                for (const otherItem of matches) {
+                    results.push(resultSelector(item, otherItem));
+                }
             }
-            return Array.from(self).map(item => resultSelector(item, otherByKey.get(thisKeySelector(item))));
+            return results;
         });
     }
 
@@ -783,15 +805,8 @@ export class From<T> implements Iterable<T> {
 
         const self = this;
         return From.fn<R>(() => {
-            const otherByKeys = new Map<K, Array<U>>();
-            for (let item of other) {
-                const key = otherKeySelector(item);
-                if (!otherByKeys.has(key)) {
-                    otherByKeys.set(key, []);
-                }
-                otherByKeys.get(key)!.push(item);
-            }
-            return Array.from(self).map(item => resultSelector(item, otherByKeys.get(thisKeySelector(item)) || []));
+            const otherByKey = groupItemsByKey(other, otherKeySelector);
+            return Array.from(self).map(item => resultSelector(item, otherByKey.get(thisKeySelector(item)) ?? []));
         });
     }
 
@@ -808,21 +823,15 @@ export class From<T> implements Iterable<T> {
 
         const self = this;
         return From.fn<R>(() => {
-            const thisByKeys = new Map<K, Array<T>>();
-            for (let item of self) {
-                const key = thisKeySelector(item);
-                if (!thisByKeys.has(key)) {
-                    thisByKeys.set(key, []);
-                }
-                thisByKeys.get(key)!.push(item);
-            }
-            return Array.from(other).map(item => resultSelector(thisByKeys.get(otherKeySelector(item)) || [], item));
+            const thisByKey = groupItemsByKey(self, thisKeySelector);
+            return Array.from(other).map(item => resultSelector(thisByKey.get(otherKeySelector(item)) ?? [], item));
         });
     }
 
 
     /**
-     * Performs a right join on two sequences.
+     * Performs a right join on two sequences: one result per matching pair, and one with `undefined` for each element of
+     * the other sequence that matches none.
      * @template U, K, R
      * @param {Iterable<U>} other - The other sequence.
      * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
@@ -834,16 +843,39 @@ export class From<T> implements Iterable<T> {
 
         const self = this;
         return From.fn<R>(() => {
-            const thisByKey = new Map<K, T>();
-            for (let item of self) {
-                thisByKey.set(thisKeySelector(item), item);
+            const thisByKey = groupItemsByKey(self, thisKeySelector);
+            const results: R[] = [];
+            for (const otherItem of other) {
+                const matches = thisByKey.get(otherKeySelector(otherItem));
+                if (matches === undefined) {
+                    results.push(resultSelector(undefined, otherItem));
+                    continue;
+                }
+                for (const item of matches) {
+                    results.push(resultSelector(item, otherItem));
+                }
             }
-            return Array.from(other).map(item => resultSelector(thisByKey.get(otherKeySelector(item)), item));
+            return results;
         });
     }
 
 }
 
+/** The items of a sequence in lists by their key, in their order, for the joins. */
+function groupItemsByKey<TItem, TKey>(items: Iterable<TItem>, keySelector: UnaryFunction<TItem, TKey>): Map<TKey, TItem[]> {
+    const itemsByKey = new Map<TKey, TItem[]>();
+    for (const item of items) {
+        const key = keySelector(item);
+        const group = itemsByKey.get(key);
+        if (group === undefined) {
+            itemsByKey.set(key, [item]);
+        } else {
+            group.push(item);
+        }
+    }
+    return itemsByKey;
+}
+
 /**
  * Represents a group of elements that have a common key.
  * @template TKey, T

package/src/draft.ts

@@ -39,7 +39,7 @@ type DraftMethods<T> = {
      *
      * @returns Array of modified property keys (does not recurse into children).
      */
-    modifiedProps(): (keyof T)[];
+    getModifiedProps(): (keyof T)[];
 
     /**
      * Manually mark (or unmark) a property as modified.
@@ -155,7 +155,7 @@ function deepDraft(value: any, parentLink?: ParentLink): any {
 /**
  * Create a draft proxy over `original`. The proxy exposes the same properties
  * as the original (with nested objects wrapped as child drafts) plus the
- * control methods `commit`, `rollback`, `isModified`, `modifiedProps` and
+ * control methods `commit`, `rollback`, `isModified`, `getModifiedProps` and
  * `setModified`.
  *
  * Mutations on the draft do not affect the original until `commit()` is called.
@@ -249,7 +249,7 @@ export default function draft<T extends object>(
             return key === undefined ? touched.size > 0 : touched.has(key);
         },
 
-        modifiedProps() {
+        getModifiedProps() {
             return [...touched] as (keyof T)[];
         },
 

package/src/functions.ts

@@ -17,7 +17,7 @@ export interface ThrottleOptions {
  * const refresh = throttle(loadData, 250);
  * refresh();
  *
- * if (refresh.pending()) {
+ * if (refresh.isPending()) {
  *     refresh.flush();
  * }
  * ```
@@ -31,7 +31,7 @@ export type DeferredFunction<F extends AnyFunction> = ((
     /** Execute the scheduled trailing call immediately, when one exists. */
     flush(): ReturnType<F> | undefined;
     /** Return true while a trailing call is scheduled. */
-    pending(): boolean;
+    isPending(): boolean;
 };
 
 /**
@@ -300,7 +300,7 @@ export function throttle<F extends AnyFunction>(
         return result;
     };
 
-    throttled.pending = (): boolean => timer !== undefined;
+    throttled.isPending = (): boolean => timer !== undefined;
 
     return throttled;
 }

package/src/index.ts

@@ -4,6 +4,7 @@
 export * from './types.js';
 export {default as Type} from './type.js';
 export {default as TypeCode} from './type-code.js';
+export {default as Uuid} from './uuid.js';
 
 // ─── Utilities ───────────────────────────────────────
 export * from './utilities.js';
@@ -41,7 +42,7 @@ export {default as draft} from './draft.js';
 // ─── Web ─────────────────────────────────────────────
 export {default as CleanURLSearchParams} from './clean-url-search-params.js';
 /** @deprecated  */
-export {ajaxSubmit, ajaxSubmission, submitForm, formToObject} from './browser/index.js';
+export {ajaxSubmit, submitForm, formToObject} from './browser/index.js';
 
 
 

package/src/math.ts

@@ -1,15 +1,27 @@
 /**
- * Linearly interpolates a number between two ranges.
+ * Linearly interpolates between two numbers: `a` for `t` 0, `b` for `t` 1, and beyond them outside that range.
  *
- * @param {number} n - The number to interpolate.
+ * @param {number} a - The value at `t` 0.
+ * @param {number} b - The value at `t` 1.
+ * @param {number} t - The interpolation factor.
+ * @return {number} - The interpolated value.
+ */
+export function lerp(a: number, b: number, t: number): number {
+    return a + (b - a) * t;
+}
+
+/**
+ * Maps a number from one range to another, keeping its proportion (`remap(5, 0, 10, 0, 100)` is 50).
+ *
+ * @param {number} n - The number to map.
  * @param {number} inMin - The minimum value of the input range.
  * @param {number} inMax - The maximum value of the input range.
  * @param {number} outMin - The minimum value of the output range.
  * @param {number} outMax - The maximum value of the output range.
- *
- * @return {number} - The interpolated value.
+ * @return {number} - The number in the output range.
+ * @throws {Error} When the input range is empty (`inMin === inMax`).
  */
-export function lerp(n: number, inMin: number, inMax: number, outMin: number, outMax: number): number {
+export function remap(n: number, inMin: number, inMax: number, outMin: number, outMax: number): number {
     if (inMax === inMin) {
         throw new Error("Input range cannot be zero");
     }

package/src/parse.ts

@@ -1,6 +1,6 @@
 // parse.ts
 /**
- * Options for {@link parseBoolean}.
+ * Options for {@link tryParseBoolean} and {@link parseBoolean}.
  */
 export interface ParseBooleanOptions {
     /**
@@ -19,7 +19,7 @@ export interface ParseBooleanOptions {
 }
 
 /**
- * Options for {@link parseInteger}.
+ * Options for {@link tryParseInteger} and {@link parseInteger}.
  */
 export interface ParseIntegerOptions {
     /**
@@ -37,7 +37,7 @@ export interface ParseIntegerOptions {
 }
 
 /**
- * Options for {@link parseDecimal}.
+ * Options for {@link tryParseDecimal} and {@link parseDecimal}.
  */
 export interface ParseDecimalOptions {
     /**
@@ -75,64 +75,78 @@ function isValidInteger(value: string, radix: number): boolean {
 }
 
 // ============================================
-// parseInteger
+// tryParseInteger / parseInteger
 // ============================================
 
 /**
  * Safely parses a value into an integer.
- * Returns `null` if the value cannot be parsed.
+ * Returns `undefined` if the value cannot be parsed.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `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.
+ * @returns The parsed integer, or `undefined` 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
+ * tryParseInteger(42)                                        // 42
+ * tryParseInteger(3.7)                                       // 3
+ * tryParseInteger(null)                                      // undefined
+ * tryParseInteger(undefined)                                 // undefined
+ * tryParseInteger("42")                                      // 42
+ * tryParseInteger("1.234.567", { thousandsSeparator: "." })  // 1234567
+ * tryParseInteger("FF", { radix: 16 })                       // 255
+ * tryParseInteger("abc")                                     // undefined
  * ```
  */
-export function parseInteger(
+export function tryParseInteger(
     value: string | number | null | undefined,
     options: ParseIntegerOptions = {}
-): number | null {
-    if (value === null || value === undefined) return null;
+): number | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? Math.trunc(value) : null;
+        return Number.isFinite(value) ? Math.trunc(value) : undefined;
     }
 
     const { radix = 10, thousandsSeparator } = options;
 
     const cleaned = stripThousands(value.trim(), thousandsSeparator);
 
-    if (cleaned === "") return null;
-    if (!isValidInteger(cleaned, radix)) return null;
+    if (cleaned === "") return undefined;
+    if (!isValidInteger(cleaned, radix)) return undefined;
 
     const parsed = Number.parseInt(cleaned, radix);
 
-    return Number.isNaN(parsed) ? null : parsed;
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/**
+ * Parses a value into an integer as {@link tryParseInteger} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseInteger(value: string | number, options: ParseIntegerOptions = {}): number {
+    const parsed = tryParseInteger(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid integer "${value}".`);
+    }
+
+    return parsed;
 }
 
 // ============================================
-// parseDecimal
+// tryParseDecimal / parseDecimal
 // ============================================
 
 /**
  * Safely parses a value into a floating-point number.
- * Returns `null` if the value cannot be parsed.
+ * Returns `undefined` if the value cannot be parsed.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `number` → returned as-is (if finite)
  * - `string` → parsed with the given options
  *
@@ -141,50 +155,64 @@ export function parseInteger(
  *
  * @param value - The value to parse.
  * @param options - Optional parsing configuration.
- * @returns The parsed float, or `null` on failure.
+ * @returns The parsed float, or `undefined` 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
+ * tryParseDecimal(3.14)                                                       // 3.14
+ * tryParseDecimal(null)                                                       // undefined
+ * tryParseDecimal(undefined)                                                  // undefined
+ * tryParseDecimal("3.14")                                                     // 3.14
+ * tryParseDecimal("3,14", { decimalSeparator: "," })                          // 3.14
+ * tryParseDecimal("1.234,56", { decimalSeparator: ",", thousandsSeparator: "." }) // 1234.56
+ * tryParseDecimal("abc")                                                      // undefined
  * ```
  */
-export function parseDecimal(
+export function tryParseDecimal(
     value: string | number | null | undefined,
     options: ParseDecimalOptions = {}
-): number | null {
-    if (value === null || value === undefined) return null;
+): number | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? value : null;
+        return Number.isFinite(value) ? value : undefined;
     }
 
     const { decimalSeparator = ".", thousandsSeparator } = options;
 
     let cleaned = stripThousands(value.trim(), thousandsSeparator);
 
-    if (cleaned === "") return null;
+    if (cleaned === "") return undefined;
 
     if (decimalSeparator === ",") {
         const commaCount = (cleaned.match(/,/g) || []).length;
-        if (commaCount > 1) return null;
+        if (commaCount > 1) return undefined;
         cleaned = cleaned.replace(",", ".");
     }
 
-    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return null;
+    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return undefined;
 
     const parsed = Number.parseFloat(cleaned);
 
-    return Number.isNaN(parsed) || !Number.isFinite(parsed) ? null : parsed;
+    return Number.isNaN(parsed) || !Number.isFinite(parsed) ? undefined : parsed;
+}
+
+/**
+ * Parses a value into a decimal number as {@link tryParseDecimal} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseDecimal(value: string | number, options: ParseDecimalOptions = {}): number {
+    const parsed = tryParseDecimal(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid decimal number "${value}".`);
+    }
+
+    return parsed;
 }
 
 // ============================================
-// parseBoolean
+// tryParseBoolean / parseBoolean
 // ============================================
 
 const DEFAULT_TRUTHY = ["true", "1", "yes", "si", "sí", "on"];
@@ -192,9 +220,9 @@ const DEFAULT_FALSY = ["false", "0", "no", "off"];
 
 /**
  * Safely parses a value into a boolean.
- * Returns `null` if the value cannot be interpreted as boolean.
+ * Returns `undefined` if the value cannot be interpreted as boolean.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `boolean` → returned as-is
  * - `number` → `0` is `false`, any other finite number is `true`
  * - `string` → matched case-insensitively against known truthy/falsy values
@@ -204,43 +232,43 @@ const 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.
+ * @returns The parsed boolean, or `undefined` 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
+ * tryParseBoolean(true)                                    // true
+ * tryParseBoolean(false)                                   // false
+ * tryParseBoolean(1)                                       // true
+ * tryParseBoolean(0)                                       // false
+ * tryParseBoolean(null)                                    // undefined
+ * tryParseBoolean(undefined)                               // undefined
+ * tryParseBoolean("yes")                                   // true
+ * tryParseBoolean("no")                                    // false
+ * tryParseBoolean("sí")                                    // true
+ * tryParseBoolean("TRUE")                                  // true
+ * tryParseBoolean("oui")                                   // undefined
+ * tryParseBoolean("oui", { extraTruthy: ["oui"] })         // true
+ * tryParseBoolean("nein", { extraFalsy: ["nein"] })        // false
+ * tryParseBoolean("whatever")                              // undefined
  * ```
  */
-export function parseBoolean(
+export function tryParseBoolean(
     value: string | number | boolean | null | undefined,
     options: ParseBooleanOptions = {}
-): boolean | null {
-    if (value === null || value === undefined) return null;
+): boolean | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "boolean") return value;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? value !== 0 : null;
+        return Number.isFinite(value) ? value !== 0 : undefined;
     }
 
     const { extraTruthy = [], extraFalsy = [] } = options;
 
     const normalized = value.trim().toLowerCase();
 
-    if (normalized === "") return null;
+    if (normalized === "") return undefined;
 
     const truthy = [...DEFAULT_TRUTHY, ...extraTruthy.map((s) => s.toLowerCase())];
     const falsy = [...DEFAULT_FALSY, ...extraFalsy.map((s) => s.toLowerCase())];
@@ -248,5 +276,19 @@ export function parseBoolean(
     if (truthy.includes(normalized)) return true;
     if (falsy.includes(normalized)) return false;
 
-    return null;
-}
+    return undefined;
+}
+
+/**
+ * Parses a value into a boolean as {@link tryParseBoolean} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseBoolean(value: string | number | boolean, options: ParseBooleanOptions = {}): boolean {
+    const parsed = tryParseBoolean(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid boolean "${value}".`);
+    }
+
+    return parsed;
+}