@develia/commons 0.4.25 → 0.5.0

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/string.ts

@@ -26,14 +26,20 @@ export function ensureSuffix(str: string, suffix: string): string {
     return str
 }
 
+/**
+ * Null for an empty string, as `Str::nullIfEmpty()` of develia/commons for PHP; any other string as it is. Compose it
+ * with `trim()` to turn a blank string into null: `nullIfEmpty(value.trim())`.
+ */
+export function nullIfEmpty(str: string | null | undefined): string | null {
+    return str === undefined || str === null || str === '' ? null : str;
+}
+
 /**
  * Normalizes Unicode whitespaces into single ASCII spaces and removes leading
  * and trailing whitespace.
  */
 export function normalizeWhitespaces(str: string): string {
-    return str.normalize('NFKC')
-              .replace(/[\s\u200B\uFEFF]+/gu, ' ')
-              .trim()
+    return str.replace(/[\s\u200B\uFEFF]+/gu, ' ').trim();
 }
 
 /**

package/src/timespan.ts

@@ -13,7 +13,7 @@ export default class TimeSpan {
      * Gets the time interval in seconds.
      * @returns {number} The duration in seconds.
      */
-    seconds(): number {
+    getTotalSeconds(): number {
         return this.milliseconds / 1000;
     }
 
@@ -21,7 +21,7 @@ export default class TimeSpan {
      * Gets the time interval in minutes.
      * @returns {number} The duration in minutes.
      */
-    minutes(): number {
+    getTotalMinutes(): number {
         return this.milliseconds / (1000 * 60);
     }
 
@@ -29,7 +29,7 @@ export default class TimeSpan {
      * Gets the time interval in hours.
      * @returns {number} The duration in hours.
      */
-    hours(): number {
+    getTotalHours(): number {
         return this.milliseconds / (1000 * 60 * 60);
     }
 
@@ -37,7 +37,7 @@ export default class TimeSpan {
      * Gets the time interval in days.
      * @returns {number} The duration in days.
      */
-    days(): number {
+    getTotalDays(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24);
     }
 
@@ -45,7 +45,7 @@ export default class TimeSpan {
      * Gets the time interval in weeks.
      * @returns {number} The duration in weeks.
      */
-    weeks(): number {
+    getTotalWeeks(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24 * 7);
     }
 

package/src/types.ts

@@ -12,7 +12,6 @@ export type Nullable<T> = T | null;
 
 export type Nullish = null | undefined;
 
-export type Resolvable<T> = T | Promise<T> | Supplier<T>;
 
 export type UnaryFunction<T, R> = (arg: T) => R;
 

package/src/utilities.ts

@@ -2,7 +2,7 @@
 
 
 import KeyValuePair from "./key-value-pair.js";
-import type {Resolvable, Constructor} from "./types.js";
+import type {Constructor} from "./types.js";
 import Type from "./type.js";
 
 export function lazy<T extends object>(factory: () => T): T {
@@ -185,8 +185,8 @@ function _deepEqual(
     }
 
     const objB = b as object;
-    const keysA = _deepEqualKeys(objA, includeInherited);
-    const keysB = _deepEqualKeys(objB, includeInherited);
+    const keysA = _collectComparableKeys(objA, includeInherited);
+    const keysB = _collectComparableKeys(objB, includeInherited);
     if (keysA.length !== keysB.length) return false;
 
     for (const key of keysA) {
@@ -265,7 +265,7 @@ function _deepEqualSet(
     return true;
 }
 
-function _deepEqualKeys(value: object, includeInherited: boolean): PropertyKey[] {
+function _collectComparableKeys(value: object, includeInherited: boolean): PropertyKey[] {
     const keys: PropertyKey[] = [];
     const seen = new Set<PropertyKey>();
     const addKey = (key: PropertyKey) => {
@@ -491,12 +491,13 @@ export function isEmptyOrWhitespace(value: any): boolean {
 /**
  * Converts an object into an array of key-value pairs.
  *
- * @param {Record<string, any>} obj - The object to convert.
- * @return {KeyValuePair<string, any>[]} - The array of key-value pairs.
+ * @template TValue - The type of the property values.
+ * @param {Record<string, TValue>} obj - The object to convert.
+ * @return {KeyValuePair<string, TValue>[]} - The array of key-value pairs.
  */
-export function toPairs(obj: Record<string, any>): KeyValuePair<string, any>[] {
+export function toPairs<TValue>(obj: Record<string, TValue>): KeyValuePair<string, TValue>[] {
 
-    let output = [];
+    const output: KeyValuePair<string, TValue>[] = [];
     for (const key in obj) {
         output.push(new KeyValuePair(key, obj[key]));
     }
@@ -528,29 +529,26 @@ export function pick<T extends object, K extends keyof T>(obj: T, props: K[]): P
 }
 
 /**
- * Converts a given thing into a Promise.
- * @template T
- * @param {any} thing - The thing to be converted into a Promise.
- * @returns {Promise<T>} - A Promise representing the given thing.
+ * Turns a function that takes a Node-style callback as its last argument (`(error, result) => void`) into one that
+ * returns a promise, as Node's `util.promisify`: it resolves with the result, or rejects with the error the callback
+ * receives. The function keeps the `this` it is called with.
+ * @param fn - The function to wrap.
+ * @returns The function that returns a promise.
  */
-export function promisify<T>(thing: Resolvable<T>): Promise<T> {
-
-    if (thing instanceof Promise)
-        return thing;
-
-
-    if (isFunction(thing)) {
-        return new Promise<T>((resolve, reject) => {
-            try {
-                const result = thing();
-                resolve(result);
-            } catch (error) {
-                reject(error);
-            }
+export function promisify<TArgs extends unknown[], TResult>(
+    fn: (...args: [...TArgs, (error: unknown, result: TResult) => void]) => void,
+): (...args: TArgs) => Promise<TResult> {
+    return function (this: unknown, ...args: TArgs): Promise<TResult> {
+        return new Promise<TResult>((resolve, reject) => {
+            fn.call(this, ...args, (error: unknown, result: TResult) => {
+                if (error !== null && error !== undefined) {
+                    reject(error);
+                } else {
+                    resolve(result);
+                }
+            });
         });
-    }
-
-    return Promise.resolve(thing);
+    };
 }
 
 

package/src/uuid.ts

@@ -0,0 +1,153 @@
+import {Nullable} from './types.js';
+
+/** Versions 1 to 8 with the RFC variant, plus the Nil and Max UUIDs of RFC 9562 sections 5.9 and 5.10. */
+const PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$/i;
+
+/** Largest Unix timestamp in milliseconds that fits in the 48 bits of a version 7 UUID. */
+const MAX_V7_MILLISECONDS = 0xffffffffffff;
+
+/**
+ * Immutable universally unique identifier (RFC 9562), kept in lowercase canonical form,
+ * such as `019a4f8b-4bae-7d2e-9f10-4a5b6c7d8e9f`.
+ *
+ * It serializes to its string with `JSON.stringify`, so DTOs carry it as text; read those
+ * strings back with {@link Uuid.parse} or {@link Uuid.parseOrThrow}.
+ */
+export default class Uuid {
+    private readonly value: string;
+
+    private constructor(value: string) {
+        this.value = value;
+    }
+
+    /**
+     * Generates a version 4 UUID from 122 random bits of a cryptographically secure source.
+     *
+     * Unlike `crypto.randomUUID()`, it also works in browser contexts that are not secure, such as
+     * a development site served over HTTP.
+     */
+    static generateV4(): Uuid {
+        const bytes = new Uint8Array(16);
+        globalThis.crypto.getRandomValues(bytes);
+
+        return Uuid.createWithVersion(bytes, 4);
+    }
+
+    /**
+     * Generates a version 7 UUID: a 48-bit Unix timestamp in milliseconds followed by 74 random bits
+     * from a cryptographically secure source, so identifiers sort by creation time.
+     *
+     * Identifiers generated within the same millisecond keep no particular order among themselves.
+     *
+     * @param date Moment the UUID encodes; the current time when omitted.
+     * @throws {RangeError} If the date is invalid, before the Unix epoch or beyond the 48-bit range.
+     */
+    static generateV7(date: Date = new Date()): Uuid {
+        const milliseconds = date.getTime();
+        if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > MAX_V7_MILLISECONDS) {
+            throw new RangeError('A version 7 UUID can only encode a valid date from the Unix epoch on.');
+        }
+
+        const bytes = new Uint8Array(16);
+        globalThis.crypto.getRandomValues(bytes);
+        let remaining = milliseconds;
+        for (let index = 5; index >= 0; index--) {
+            bytes[index] = remaining % 256;
+            remaining = Math.floor(remaining / 256);
+        }
+
+        return Uuid.createWithVersion(bytes, 7);
+    }
+
+    /**
+     * Checks if a value is a UUID in canonical form, in any letter case: one of RFC 9562 versions 1 to 8,
+     * or its Nil UUID (all zeros) or Max UUID (all ones).
+     *
+     * It returns a plain boolean rather than a type guard: a string that is not a UUID is still a
+     * string, which a guard would narrow to `never`.
+     */
+    static isValid(value: unknown): boolean {
+        return typeof value === 'string' && PATTERN.test(value);
+    }
+
+    /**
+     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.
+     *
+     * @returns The UUID, or `null` when the value is not one.
+     */
+    static parse(value: unknown): Nullable<Uuid> {
+        if (typeof value !== 'string' || !Uuid.isValid(value)) {
+            return null;
+        }
+
+        return new Uuid(value.toLowerCase());
+    }
+
+    /**
+     * Reads a UUID in canonical form, in any letter case.
+     *
+     * @throws {SyntaxError} If the value is not a UUID.
+     */
+    static parseOrThrow(value: string): Uuid {
+        const uuid = Uuid.parse(value);
+        if (uuid === null) {
+            throw new SyntaxError(`Invalid UUID "${value}".`);
+        }
+
+        return uuid;
+    }
+
+    /**
+     * Returns the RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.
+     */
+    getVersion(): number {
+        return Number.parseInt(this.value.charAt(14), 16);
+    }
+
+    /**
+     * Returns the moment a version 7 UUID encodes, with millisecond precision.
+     *
+     * @returns The moment, or `null` for other versions.
+     */
+    getDate(): Nullable<Date> {
+        if (this.getVersion() !== 7) {
+            return null;
+        }
+
+        const milliseconds = Number.parseInt(this.value.slice(0, 8) + this.value.slice(9, 13), 16);
+        return new Date(milliseconds);
+    }
+
+    equals(other: Uuid): boolean {
+        return this.value === other.value;
+    }
+
+    /**
+     * Returns the UUID in lowercase canonical form.
+     */
+    toString(): string {
+        return this.value;
+    }
+
+    toJSON(): string {
+        return this.value;
+    }
+
+    /**
+     * Sets the version and the RFC 9562 variant bits of 16 bytes and wraps them as a UUID.
+     *
+     * @param bytes Exactly 16 bytes; only the version and variant bits are overwritten.
+     * @param version From 1 to 8.
+     */
+    private static createWithVersion(bytes: Uint8Array, version: number): Uuid {
+        bytes[6] = (bytes[6] & 0x0f) | (version << 4);
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+        let hex = '';
+        for (const byte of bytes) {
+            hex += byte.toString(16).padStart(2, '0');
+        }
+
+        return new Uuid(`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`);
+    }
+}