@develia/commons 0.4.26 → 0.6.1

package/src/range.ts

@@ -1,7 +1,7 @@
 export default class Range<T> {
 
-    private readonly start: T;
-    private readonly end: T;
+    public readonly start: T;
+    public readonly end: T;
 
     /**
      * Range constructor.
@@ -86,20 +86,6 @@ export default class Range<T> {
             (this.start < obj && this.end > obj);
     }
 
-    /**
-     * @returns T
-     */
-    public getStart(): T {
-        return this.start;
-    }
-
-    /**
-     * @returns T
-     */
-    public getEnd(): T {
-        return this.end;
-    }
-
     /**
      * Finds the intersection between two sets of ranges.
      *

package/src/stopwatch.ts

@@ -2,7 +2,7 @@ import TimeSpan from "./timespan.js";
 
 export default class Stopwatch {
     private startTime: number | null = null;
-    private elapsedTime: number | null = null;
+    private elapsedMilliseconds: number | null = null;
 
     /*static measure<T>(callback: () => T, measure: { value: TimeSpan | null }): T {
         const stopwatch = new Stopwatch();
@@ -11,33 +11,33 @@ export default class Stopwatch {
             return callback();
         } finally {
             stopwatch.stop();
-            measure.value = stopwatch.getElapsedTime();
+            measure.value = stopwatch.elapsedTime;
         }
     }*/
 
     start(): void {
         this.startTime = performance.now();
-        this.elapsedTime = null;
+        this.elapsedMilliseconds = null;
     }
 
     stop(): void {
         if (this.startTime !== null) {
-            this.elapsedTime = performance.now() - this.startTime;
+            this.elapsedMilliseconds = performance.now() - this.startTime;
             this.startTime = null;
         }
     }
 
     resume(): void {
-        if (this.elapsedTime !== null) {
-            this.startTime = performance.now() - this.elapsedTime;
-            this.elapsedTime = null;
+        if (this.elapsedMilliseconds !== null) {
+            this.startTime = performance.now() - this.elapsedMilliseconds;
+            this.elapsedMilliseconds = null;
         }
     }
 
-    getElapsedTime(): TimeSpan {
+    get elapsedTime(): TimeSpan {
         if (this.startTime !== null) {
             return TimeSpan.fromMilliseconds(performance.now() - this.startTime);
         }
-        return TimeSpan.fromMilliseconds(this.elapsedTime ?? 0.0);
+        return TimeSpan.fromMilliseconds(this.elapsedMilliseconds ?? 0.0);
     }
 }

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();
 }
 
 /**
@@ -151,3 +157,27 @@ export function toPascalCase(str: string): string {
 export function toConstantCase(str: string): string {
     return toWords(str).join('_').toUpperCase();
 }
+
+const FILE_SIZE_UNITS: readonly string[] = Object.freeze(['B', 'KB', 'MB', 'GB', 'TB', 'PB']);
+
+/**
+ * Formats a size in bytes with the largest unit it fills, in powers of 1024: `340 B`, `1.2 MB`.
+ *
+ * Bytes are written whole and the larger units with at most one decimal, with the separators of the locale.
+ *
+ * @param {number} bytes - The size in bytes; a negative or non-finite size is formatted as zero.
+ * @param {string} [locale] - The locale of the number, such as `es-ES`; the one of the runtime when omitted.
+ * @return {string} The number, a space and the unit.
+ */
+export function formatFileSize(bytes: number, locale?: string): string {
+    let size = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < FILE_SIZE_UNITS.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+
+    const maximumFractionDigits = unitIndex === 0 ? 0 : 1;
+
+    return `${size.toLocaleString(locale, {maximumFractionDigits})} ${FILE_SIZE_UNITS[unitIndex]}`;
+}

package/src/timespan.ts

@@ -10,42 +10,37 @@ export default class TimeSpan {
 
 
     /**
-     * Gets the time interval in seconds.
-     * @returns {number} The duration in seconds.
+     * The whole duration in seconds.
      */
-    seconds(): number {
+    get totalSeconds(): number {
         return this.milliseconds / 1000;
     }
 
     /**
-     * Gets the time interval in minutes.
-     * @returns {number} The duration in minutes.
+     * The whole duration in minutes.
      */
-    minutes(): number {
+    get totalMinutes(): number {
         return this.milliseconds / (1000 * 60);
     }
 
     /**
-     * Gets the time interval in hours.
-     * @returns {number} The duration in hours.
+     * The whole duration in hours.
      */
-    hours(): number {
+    get totalHours(): number {
         return this.milliseconds / (1000 * 60 * 60);
     }
 
     /**
-     * Gets the time interval in days.
-     * @returns {number} The duration in days.
+     * The whole duration in days.
      */
-    days(): number {
+    get totalDays(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24);
     }
 
     /**
-     * Gets the time interval in weeks.
-     * @returns {number} The duration in weeks.
+     * The whole duration in weeks.
      */
-    weeks(): number {
+    get totalWeeks(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24 * 7);
     }
 

package/src/triggers.ts

@@ -7,7 +7,8 @@ import type {Nullable, Supplier} from './types.js';
  */
 export class TimeTrigger<T> {
     private callback: Supplier<T | Promise<T>>;
-    private interval: TimeSpan;
+    /** Time that must pass between two runs. */
+    public interval: TimeSpan;
     private lastRunTime: Nullable<number>;
 
     public constructor(callback: Supplier<T | Promise<T>>, interval: TimeSpan) {
@@ -46,19 +47,6 @@ export class TimeTrigger<T> {
         this.callback = callback;
     }
 
-    /**
-     * Gets the configured time interval.
-     */
-    public getInterval(): TimeSpan {
-        return this.interval;
-    }
-
-    /**
-     * Replaces the configured time interval.
-     */
-    public setInterval(interval: TimeSpan): void {
-        this.interval = interval;
-    }
 
 
 }
@@ -68,12 +56,12 @@ export class TimeTrigger<T> {
  */
 export class CountTrigger<T> {
     private callback: Supplier<T | Promise<T>>;
-    private interval: number = 1;
+    private _interval: number = 1;
     private checkCount: number = 0;
 
     public constructor(callback: Supplier<T | Promise<T>>, interval: number) {
         this.callback = callback;
-        this.setInterval(interval);
+        this.interval = interval;
     }
 
     /**
@@ -82,7 +70,7 @@ export class CountTrigger<T> {
     public async check(): Promise<Result<T>> {
         this.checkCount++;
 
-        if (this.checkCount >= this.interval) {
+        if (this.checkCount >= this._interval) {
             return {success: true, output: await this.trigger()};
         }
 
@@ -105,22 +93,20 @@ export class CountTrigger<T> {
     }
 
     /**
-     * Gets the configured check interval.
+     * Number of checks after which the callback runs.
      */
-    public getInterval(): number {
-        return this.interval;
+    public get interval(): number {
+        return this._interval;
     }
 
     /**
-     * Replaces the configured check interval.
-     *
      * @throws {RangeError} When the interval is less than one.
      */
-    public setInterval(interval: number): void {
+    public set interval(interval: number) {
         if (interval < 1) {
             throw new RangeError('Interval must be greater than zero.');
         }
 
-        this.interval = interval;
+        this._interval = interval;
     }
 }

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) => {
@@ -529,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.tryParse}.
+ */
+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.
+     *
+     * @throws {SyntaxError} If the value is not a UUID.
+     */
+    static parse(value: string): Uuid {
+        const uuid = Uuid.tryParse(value);
+        if (uuid === undefined) {
+            throw new SyntaxError(`Invalid UUID "${value}".`);
+        }
+
+        return uuid;
+    }
+
+    /**
+     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.
+     *
+     * @returns The UUID, or `undefined` when the value is not one.
+     */
+    static tryParse(value: unknown): Uuid | undefined {
+        if (typeof value !== 'string' || !Uuid.isValid(value)) {
+            return undefined;
+        }
+
+        return new Uuid(value.toLowerCase());
+    }
+
+    /**
+     * The RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.
+     */
+    get version(): number {
+        return Number.parseInt(this.value.charAt(14), 16);
+    }
+
+    /**
+     * The moment a version 7 UUID encodes, with millisecond precision.
+     *
+     * It is `null` for other versions.
+     */
+    get date(): Nullable<Date> {
+        if (this.version !== 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)}`);
+    }
+}