@powfix/core-js 0.19.2 → 0.20.0

package/dist/node/esm/shared/utils/UUID.mjs

@@ -0,0 +1,310 @@
+import { Uint8ArrayUtils } from "../index.mjs";
+/**
+ * Represents a UUID (Universally Unique Identifier) and provides various utility
+ * methods for validation, conversion, comparison and creation.
+ */
+export class UUID {
+    /* --------------------------------------------------------------------
+     * Validation helpers
+     * -------------------------------------------------------------------- */
+    /**
+     * Checks if the supplied value is a valid hex representation of a UUID.
+     * @param hex - The string to validate.
+     * @returns true if the string matches {@link REGEX_HEX}.
+     */
+    static isValidHex(hex) {
+        if (typeof hex !== 'string') {
+            return false;
+        }
+        return UUID.REGEX_HEX.test(hex);
+    }
+    /**
+     * Checks if the supplied value is a valid RFC 4122 UUID string.
+     * @param str - The string to validate.
+     * @returns true if the string matches {@link REGEX_RFC4122}.
+     */
+    static isValidString(str) {
+        if (typeof str !== 'string') {
+            return false;
+        }
+        return UUID.REGEX_RFC4122.test(str);
+    }
+    /**
+     * Checks whether an ArrayBufferView contains exactly {@link BYTE_LENGTH} bytes.
+     * @param bytes - The view to check.
+     * @returns true if the byte length is correct.
+     */
+    static isValidBytes(bytes) {
+        return bytes.byteLength === UUID.BYTE_LENGTH;
+    }
+    /**
+     * Generic validation that accepts either a string (hex or RFC 4122 format)
+     * or an ArrayBufferView containing the raw bytes.
+     * @param input - The value to validate.
+     * @returns true if the input is a valid representation of a UUID.
+     */
+    static isValid(input) {
+        if (typeof input === 'string') {
+            const length = input.length;
+            switch (length) {
+                case UUID.STR_LENGTH:
+                    // RFC 4122 uuid(string)
+                    // 9e472052-a654-4693-9a8b-3ce57ada3d6c
+                    return UUID.isValidString(input);
+                case UUID.HEX_STR_LENGTH:
+                    // RFC 4122 uuid(string) without hyphens
+                    // 9e472052a65446939a8b3ce57ada3d6c
+                    return UUID.isValidHex(input);
+                default:
+                    return false;
+            }
+        }
+        else if (input instanceof UUID) {
+            return UUID.isValidBytes(input.bytes);
+        }
+        else if (ArrayBuffer.isView(input)) {
+            return UUID.isValidBytes(input);
+        }
+        else {
+            return false;
+        }
+    }
+    /* --------------------------------------------------------------------
+     * Parsing / formatting helpers
+     * -------------------------------------------------------------------- */
+    /**
+     * Inserts hyphens into a 32‑character hex string to produce an RFC 4122 string.
+     * @param hex - The plain hexadecimal UUID.
+     * @returns The formatted RFC 4122 string.
+     */
+    static formatHex(hex) {
+        if (hex.length !== UUID.HEX_STR_LENGTH) {
+            throw new Error(`hex length should be ${UUID.HEX_STR_LENGTH}`);
+        }
+        return hex.slice(0, 8) + '-' +
+            hex.slice(8, 12) + '-' +
+            hex.slice(12, 16) + '-' +
+            hex.slice(16, 20) + '-' +
+            hex.slice(20);
+    }
+    /** Removes all hyphens from a UUID string. */
+    static stripHyphens(str) {
+        return str.replace(/-/g, "");
+    }
+    /**
+     * Converts a plain hexadecimal UUID into a Uint8Array.
+     * @param hex - The hex string to parse.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    static parseHex(hex) {
+        if (hex.length !== UUID.HEX_STR_LENGTH) {
+            throw new Error(`Invalid hex string, length should be ${UUID.HEX_STR_LENGTH}`);
+        }
+        return Uint8ArrayUtils.fromHex(hex);
+    }
+    /**
+     * Parses an RFC 4122 string into a Uint8Array.
+     * @param str - The formatted UUID string.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    static parseString(str) {
+        if (str.length !== UUID.STR_LENGTH) {
+            throw new Error(`Invalid UUID string, invalid character length should be ${UUID.STR_LENGTH}`);
+        }
+        if (!UUID.isValid(str)) {
+            throw new Error('Invalid UUID string, should be RFC 4122 format');
+        }
+        const hex = UUID.stripHyphens(str);
+        if (hex.length !== UUID.HEX_STR_LENGTH) {
+            throw new Error('Invalid UUID string, invalid character length after strip hyphens');
+        }
+        return Uint8ArrayUtils.fromHex(hex);
+    }
+    /**
+     * Parses an ArrayBufferView into a Uint8Array ensuring the correct byte length.
+     * @param bytes - The view to parse.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    static parseBytes(bytes) {
+        const view = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        if (view.length !== UUID.BYTE_LENGTH) {
+            throw new Error(`Expected ${UUID.BYTE_LENGTH} bytes`);
+        }
+        return new Uint8Array(view);
+    }
+    /* --------------------------------------------------------------------
+     * Factory methods
+     * -------------------------------------------------------------------- */
+    /**
+     * Creates a UUID instance from a plain hexadecimal string.
+     * @param hex - The hex representation of the UUID.
+     * @returns A new {@link UUID} object.
+     */
+    static fromHex(hex) {
+        return new this(UUID.parseHex(hex));
+    }
+    /**
+     * Creates a UUID instance from an RFC 4122 formatted string.
+     * @param str - The UUID string with hyphens.
+     * @returns A new {@link UUID} object.
+     */
+    static fromString(str) {
+        return new this(UUID.parseString(str));
+    }
+    /**
+     * Creates a UUID instance from raw bytes.
+     * @param bytes - An ArrayBufferView containing 16 bytes.
+     * @returns A new {@link UUID} object.
+     */
+    static fromBytes(bytes) {
+        return new this(UUID.parseBytes(bytes));
+    }
+    /**
+     * Parses any supported input (string or bytes) and returns the raw byte array.
+     * @param input - The value to parse.
+     * @returns A Uint8Array of length {@link BYTE_LENGTH}.
+     */
+    static parse(input) {
+        if (typeof input === 'string') {
+            const length = input.length;
+            switch (length) {
+                case UUID.STR_LENGTH:
+                    // RFC 4122 uuid(string)
+                    return UUID.parseString(input);
+                case UUID.HEX_STR_LENGTH:
+                    // RFC 4122 uuid(string) without hyphens
+                    return UUID.parseHex(input);
+                default:
+                    throw new Error(`Invalid input string, length should be ${UUID.STR_LENGTH} or ${UUID.HEX_STR_LENGTH}`);
+            }
+        }
+        else if (input instanceof UUID) {
+            return input.toBytes();
+        }
+        else if (ArrayBuffer.isView(input)) {
+            return UUID.parseBytes(input);
+        }
+        else {
+            throw new Error("Invalid input, Expected string or ArrayBufferView");
+        }
+    }
+    /**
+     * Creates a UUID from any supported input type.
+     * @param input - The value to parse.
+     * @returns A new {@link UUID} object.
+     */
+    static from(input) {
+        return this.fromBytes(UUID.parse(input));
+    }
+    /** Returns the nil (all zero) UUID. */
+    static nil() {
+        return this.fromBytes(new Uint8Array(UUID.BYTE_LENGTH));
+    }
+    /** Returns a UUID consisting of all 0xFF bytes. */
+    static max() {
+        return this.fromBytes((new Uint8Array(UUID.BYTE_LENGTH)).fill(0xFF));
+    }
+    /* --------------------------------------------------------------------
+     * Equality / comparison
+     * -------------------------------------------------------------------- */
+    /**
+     * Compares multiple UUIDs for strict equality.
+     * @param uuids - The UUIDs to compare (at least two required).
+     * @returns true if all provided UUIDs are identical.
+     */
+    static equals(...uuids) {
+        const n = uuids.length;
+        if (n < 2) {
+            throw new Error('At least two UUIDs required for comparison');
+        }
+        const ref = uuids[0].bytes;
+        for (let i = 1; i < n; ++i) {
+            const b = uuids[i].bytes;
+            for (let j = 0; j < UUID.BYTE_LENGTH; ++j) {
+                if (ref[j] !== b[j])
+                    return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Lexicographically compares two UUIDs.
+     * @param uuid1 - The first UUID.
+     * @param uuid2 - The second UUID.
+     * @returns -1 if uuid1 < uuid2, 1 if uuid1 > uuid2, 0 otherwise.
+     */
+    static compare(uuid1, uuid2) {
+        const a = uuid1.bytes;
+        const b = uuid2.bytes;
+        for (let i = 0; i < UUID.BYTE_LENGTH; i++) {
+            if (a[i] !== b[i])
+                return a[i] < b[i] ? -1 : 1;
+        }
+        return 0;
+    }
+    /**
+     * Constructs a new {@link UUID} instance from any supported input type.
+     * @param input - The value to parse (string or ArrayBufferView).
+     */
+    constructor(input) {
+        this.bytes = UUID.parse(input);
+    }
+    /** Instance wrapper for {@link equals}. */
+    equals(...uuids) {
+        return UUID.equals(this, ...uuids);
+    }
+    /** Instance wrapper for {@link compare}. */
+    compare(other) {
+        return UUID.compare(this, other);
+    }
+    /**
+     * Returns the RFC 4122 string representation of this UUID.
+     * @returns The formatted UUID string.
+     */
+    toString() {
+        if (this._str != null) {
+            return this._str;
+        }
+        const hex = this.toHex();
+        this._str = UUID.formatHex(hex);
+        return this._str;
+    }
+    /**
+     * Returns the plain hexadecimal representation of this UUID.
+     * @returns A 32‑character hex string.
+     */
+    toHex() {
+        if (this._hex != null) {
+            return this._hex;
+        }
+        this._hex = Uint8ArrayUtils.toHex(this.bytes);
+        return this._hex;
+    }
+    /**
+     * Returns a copy of the raw byte array.
+     * @returns A new Uint8Array containing the UUID bytes.
+     */
+    toBytes() {
+        return new Uint8Array(this.bytes);
+    }
+    /** JSON serialization helper – returns the RFC 4122 string. */
+    toJSON() {
+        return this.toString();
+    }
+}
+/* --------------------------------------------------------------------
+ * Regular expressions used to validate UUIDs in different string forms
+ * -------------------------------------------------------------------- */
+/** Matches a 32‑character hexadecimal representation of a UUID without hyphens. */
+UUID.REGEX_HEX = /^[0-9a-fA-F]{8}[0-9a-fA-F]{4}[1-5][0-9a-fA-F]{3}[89abAB][0-9a-fA-F]{3}[0-9a-fA-F]{12}$/;
+/** Matches the RFC 4122 canonical UUID format with hyphens. */
+UUID.REGEX_RFC4122 = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+/* --------------------------------------------------------------------
+ * Constant lengths used throughout the class
+ * -------------------------------------------------------------------- */
+/** Number of bytes that represent a UUID. */
+UUID.BYTE_LENGTH = 16;
+/** Total length of an RFC 4122 UUID string (including hyphens). */
+UUID.STR_LENGTH = 36;
+/** Length of a UUID represented as a plain hexadecimal string. */
+UUID.HEX_STR_LENGTH = 32;

package/dist/node/esm/shared/utils/UUID.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/node/esm/shared/utils/global/{fallbackIfEqual.mjs → fallbackIfMatch.mjs}

@@ -1,4 +1,4 @@
-export function fallbackIfEqual(value, condition, fallback) {
+export function fallbackIfMatch(value, condition, fallback) {
     if (typeof value === typeof condition && value === condition) {
         return fallback;
     }

package/dist/node/esm/shared/utils/global/fallbackIfNull.mjs

@@ -1,4 +1,4 @@
-import { fallbackIfEqual } from "./fallbackIfEqual.mjs";
+import { fallbackIfMatch } from "./fallbackIfMatch.mjs";
 export function fallbackIfNull(value, fallback) {
-    return fallbackIfEqual(value, null, fallback);
+    return fallbackIfMatch(value, null, fallback);
 }

package/dist/node/esm/shared/utils/global/fallbackIfNullish.mjs

@@ -0,0 +1,6 @@
+export function fallbackIfNullish(value, fallback) {
+    if (value == null) {
+        return fallback;
+    }
+    return value;
+}

package/dist/node/esm/shared/utils/global/fallbackIfUndefined.mjs

@@ -1,4 +1,4 @@
-import { fallbackIfEqual } from "./fallbackIfEqual.mjs";
+import { fallbackIfMatch } from "./fallbackIfMatch.mjs";
 export function fallbackIfUndefined(value, fallback) {
-    return fallbackIfEqual(value, undefined, fallback);
+    return fallbackIfMatch(value, undefined, fallback);
 }

package/dist/node/esm/shared/utils/global/index.mjs

@@ -5,8 +5,9 @@ export * from './btoa.mjs';
 export * from './castArray.mjs';
 export * from './circularDistance.mjs';
 export * from './sleep.mjs';
-export * from './fallbackIfEqual.mjs';
+export * from './fallbackIfMatch.mjs';
 export * from './fallbackIfNull.mjs';
+export * from './fallbackIfNullish.mjs';
 export * from './fallbackIfUndefined.mjs';
 export * from './firstNonNullish.mjs';
 export * from './flat.mjs';

package/dist/node/esm/shared/utils/index.mjs

@@ -3,6 +3,8 @@ export * from './ArrayUtils.mjs';
 export * from './AxiosUtils.mjs';
 export * from './StringUtils.mjs';
 export * from './Uint8ArrayUtils.mjs';
+// export * from './UUID';
+export * from './UUID.types.mjs';
 export * from './UuidUtils.mjs';
 export * from './BooleanUtils.mjs';
 export * from './Calc.mjs';

package/dist/node/types/nodejs/utils/UUID.d.ts

@@ -1,4 +1,4 @@
-import { UUID as BaseUUID } from "../../browser/utils/UUID";
+import { UUID as BaseUUID } from "../../shared/utils/UUID";
 export declare class UUID extends BaseUUID {
     toBuffer(): Buffer;
 }

package/dist/node/types/shared/utils/UUID.d.ts

@@ -0,0 +1,145 @@
+import { UuidInput } from "./UUID.types";
+/**
+ * Represents a UUID (Universally Unique Identifier) and provides various utility
+ * methods for validation, conversion, comparison and creation.
+ */
+export declare class UUID {
+    /** Matches a 32‑character hexadecimal representation of a UUID without hyphens. */
+    private static REGEX_HEX;
+    /** Matches the RFC 4122 canonical UUID format with hyphens. */
+    private static REGEX_RFC4122;
+    /** Number of bytes that represent a UUID. */
+    private static BYTE_LENGTH;
+    /** Total length of an RFC 4122 UUID string (including hyphens). */
+    private static STR_LENGTH;
+    /** Length of a UUID represented as a plain hexadecimal string. */
+    private static HEX_STR_LENGTH;
+    /**
+     * Checks if the supplied value is a valid hex representation of a UUID.
+     * @param hex - The string to validate.
+     * @returns true if the string matches {@link REGEX_HEX}.
+     */
+    static isValidHex(hex: string): boolean;
+    /**
+     * Checks if the supplied value is a valid RFC 4122 UUID string.
+     * @param str - The string to validate.
+     * @returns true if the string matches {@link REGEX_RFC4122}.
+     */
+    static isValidString(str: string): boolean;
+    /**
+     * Checks whether an ArrayBufferView contains exactly {@link BYTE_LENGTH} bytes.
+     * @param bytes - The view to check.
+     * @returns true if the byte length is correct.
+     */
+    static isValidBytes(bytes: ArrayBufferView): boolean;
+    /**
+     * Generic validation that accepts either a string (hex or RFC 4122 format)
+     * or an ArrayBufferView containing the raw bytes.
+     * @param input - The value to validate.
+     * @returns true if the input is a valid representation of a UUID.
+     */
+    static isValid(input: UuidInput): boolean;
+    /**
+     * Inserts hyphens into a 32‑character hex string to produce an RFC 4122 string.
+     * @param hex - The plain hexadecimal UUID.
+     * @returns The formatted RFC 4122 string.
+     */
+    private static formatHex;
+    /** Removes all hyphens from a UUID string. */
+    private static stripHyphens;
+    /**
+     * Converts a plain hexadecimal UUID into a Uint8Array.
+     * @param hex - The hex string to parse.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    private static parseHex;
+    /**
+     * Parses an RFC 4122 string into a Uint8Array.
+     * @param str - The formatted UUID string.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    private static parseString;
+    /**
+     * Parses an ArrayBufferView into a Uint8Array ensuring the correct byte length.
+     * @param bytes - The view to parse.
+     * @returns A Uint8Array containing the raw bytes.
+     */
+    private static parseBytes;
+    /**
+     * Creates a UUID instance from a plain hexadecimal string.
+     * @param hex - The hex representation of the UUID.
+     * @returns A new {@link UUID} object.
+     */
+    static fromHex<T extends typeof UUID>(hex: string): InstanceType<T>;
+    /**
+     * Creates a UUID instance from an RFC 4122 formatted string.
+     * @param str - The UUID string with hyphens.
+     * @returns A new {@link UUID} object.
+     */
+    static fromString<T extends typeof UUID>(str: string): InstanceType<T>;
+    /**
+     * Creates a UUID instance from raw bytes.
+     * @param bytes - An ArrayBufferView containing 16 bytes.
+     * @returns A new {@link UUID} object.
+     */
+    static fromBytes<T extends typeof UUID>(bytes: ArrayBufferView): InstanceType<T>;
+    /**
+     * Parses any supported input (string or bytes) and returns the raw byte array.
+     * @param input - The value to parse.
+     * @returns A Uint8Array of length {@link BYTE_LENGTH}.
+     */
+    private static parse;
+    /**
+     * Creates a UUID from any supported input type.
+     * @param input - The value to parse.
+     * @returns A new {@link UUID} object.
+     */
+    static from<T extends typeof UUID>(this: T, input: UuidInput): InstanceType<T>;
+    /** Returns the nil (all zero) UUID. */
+    static nil<T extends typeof UUID>(this: T): InstanceType<T>;
+    /** Returns a UUID consisting of all 0xFF bytes. */
+    static max<T extends typeof UUID>(this: T): InstanceType<T>;
+    /**
+     * Compares multiple UUIDs for strict equality.
+     * @param uuids - The UUIDs to compare (at least two required).
+     * @returns true if all provided UUIDs are identical.
+     */
+    static equals(...uuids: UUID[]): boolean;
+    /**
+     * Lexicographically compares two UUIDs.
+     * @param uuid1 - The first UUID.
+     * @param uuid2 - The second UUID.
+     * @returns -1 if uuid1 < uuid2, 1 if uuid1 > uuid2, 0 otherwise.
+     */
+    static compare(uuid1: UUID, uuid2: UUID): number;
+    /** Raw byte representation of the UUID. */
+    protected readonly bytes: Uint8Array;
+    private _str?;
+    private _hex?;
+    /**
+     * Constructs a new {@link UUID} instance from any supported input type.
+     * @param input - The value to parse (string or ArrayBufferView).
+     */
+    constructor(input: UuidInput);
+    /** Instance wrapper for {@link equals}. */
+    equals(...uuids: UUID[]): boolean;
+    /** Instance wrapper for {@link compare}. */
+    compare(other: UUID): number;
+    /**
+     * Returns the RFC 4122 string representation of this UUID.
+     * @returns The formatted UUID string.
+     */
+    toString(): string;
+    /**
+     * Returns the plain hexadecimal representation of this UUID.
+     * @returns A 32‑character hex string.
+     */
+    toHex(): string;
+    /**
+     * Returns a copy of the raw byte array.
+     * @returns A new Uint8Array containing the UUID bytes.
+     */
+    toBytes(): Uint8Array;
+    /** JSON serialization helper – returns the RFC 4122 string. */
+    toJSON(): string;
+}

package/dist/node/types/shared/utils/UUID.types.d.ts

@@ -0,0 +1,2 @@
+import { UUID } from "./UUID";
+export type UuidInput = string | ArrayBufferView | UUID;

package/dist/node/types/shared/utils/global/fallbackIfMatch.d.ts

@@ -0,0 +1 @@
+export declare function fallbackIfMatch<V, C, F>(value: V, condition: C, fallback: F): V | F;

package/dist/node/types/shared/utils/global/fallbackIfNullish.d.ts

@@ -0,0 +1 @@
+export declare function fallbackIfNullish<T, F>(value: T | null | undefined, fallback: F): T | F;

package/dist/node/types/shared/utils/global/index.d.ts

@@ -5,8 +5,9 @@ export * from './btoa';
 export * from './castArray';
 export * from './circularDistance';
 export * from './sleep';
-export * from './fallbackIfEqual';
+export * from './fallbackIfMatch';
 export * from './fallbackIfNull';
+export * from './fallbackIfNullish';
 export * from './fallbackIfUndefined';
 export * from './firstNonNullish';
 export * from './flat';

package/dist/node/types/shared/utils/index.d.ts

@@ -3,6 +3,7 @@ export * from './ArrayUtils';
 export * from './AxiosUtils';
 export * from './StringUtils';
 export * from './Uint8ArrayUtils';
+export * from './UUID.types';
 export * from './UuidUtils';
 export * from './BooleanUtils';
 export * from './Calc';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@powfix/core-js",
-	"version": "0.19.2",
+	"version": "0.20.0",
 	"description": "core package",
 	"author": "Kwon Kyung-Min <powfix@gmail.com>",
 	"private": false,

package/dist/browser/types/shared/utils/global/fallbackIfEqual.d.ts

@@ -1 +0,0 @@
-export declare function fallbackIfEqual<V, C, F>(value: V, condition: C, fallback: F): V | F;

package/dist/node/types/shared/utils/global/fallbackIfEqual.d.ts

@@ -1 +0,0 @@
-export declare function fallbackIfEqual<V, C, F>(value: V, condition: C, fallback: F): V | F;