@digitaldefiance/ecies-lib 4.4.13 → 4.4.14

package/src/lib/guid.d.ts

@@ -0,0 +1,344 @@
+import { GuidBrandType } from '../enumerations/guid-brand-type';
+import { IGuidV4 } from '../interfaces/guid';
+import { Base64Guid, BigIntGuid, FullHexGuid, RawGuidBuffer, ShortHexGuid } from '../types';
+export type { Base64Guid };
+export type GuidInput = string | FullHexGuid | ShortHexGuid | Base64Guid | BigIntGuid | RawGuidBuffer | bigint | Buffer;
+/**
+ * GuidV4 represents a GUID (Globally Unique Identifier) that is compliant with the RFC 4122 standard.
+ * GuidV4 instances can be created from a variety of input types, including:
+ * - FullHexGuid: A 36-character string representation of the GUID, including dashes
+ * - ShortHexGuid: A 32-character string representation of the GUID, excluding dashes
+ * - Base64Guid: A 24-character base64-encoded string representation of the GUID
+ * - BigIntGuid: A bigint representation of the GUID
+ * - RawGuidBuffer: A 16-byte Buffer representation of the GUID
+ * GuidV4 instances can be converted to any of these representations using the appropriate method.
+ */
+export declare class GuidV4 implements IGuidV4 {
+    /**
+     * GUID is stored internally as a raw 16-byte Buffer.
+     */
+    private readonly _value;
+    /**
+     * Boundary value constants for special GUID validation
+     */
+    private static readonly BOUNDARY_VALUES;
+    /**
+     * Maximum valid bigint value for a 128-bit GUID
+     */
+    private static readonly MAX_BIGINT_VALUE;
+    /**
+     * Cached full hex representation for performance
+     */
+    private _cachedFullHex?;
+    /**
+     * Cached short hex representation for performance
+     */
+    private _cachedShortHex?;
+    /**
+     * Cached base64 representation for performance
+     */
+    private _cachedBase64?;
+    /**
+     * Regex for validating hex strings (case insensitive)
+     */
+    private static readonly HEX_PATTERN;
+    /**
+     * Regex for validating full hex GUID format
+     */
+    private static readonly FULL_HEX_PATTERN;
+    /**
+     * Cached empty/nil GUID constant (all zeros)
+     */
+    private static _empty?;
+    /**
+     * Empty/nil GUID constant (all zeros)
+     */
+    static get Empty(): GuidV4;
+    constructor(value: GuidInput);
+    /**
+     * Validates input and converts to raw buffer with comprehensive error handling.
+     * This centralizes all validation logic for better maintainability.
+     * @param value The input value to validate and convert
+     * @returns The validated raw GUID buffer
+     * @throws {GuidError} If validation fails
+     */
+    private static validateAndConvert;
+    static validateUuid(value: string): boolean;
+    serialize(): string;
+    static hydrate(value: string): GuidV4;
+    private static readonly LengthMap;
+    private static readonly ReverseLengthMap;
+    private static readonly VerifyFunctions;
+    /**
+     * Returns the GUID as a raw Buffer.
+     * NOTE: Returns a defensive copy to prevent external mutation.
+     * Use asRawGuidBufferUnsafe() if you need the internal buffer and guarantee no mutation.
+     */
+    get asRawGuidBuffer(): RawGuidBuffer;
+    /**
+     * Returns the internal raw Buffer without copying.
+     * ⚠️ WARNING: Do NOT mutate the returned buffer! This is for performance-critical paths only.
+     * Mutating this buffer will corrupt the GUID instance.
+     * @internal
+     */
+    get asRawGuidBufferUnsafe(): RawGuidBuffer;
+    /**
+     * Generates a new random v4 GUID.
+     * @returns A new GuidV4 instance with a randomly generated value
+     */
+    static generate(): GuidV4;
+    /**
+     * Alias for generate() for backward compatibility.
+     * @deprecated Use generate() instead for clearer intent
+     */
+    static new(): GuidV4;
+    /**
+     * Parses a GUID from any valid format, throwing on invalid input.
+     * This is the primary parsing method for when you expect valid input.
+     * @param value The value to parse
+     * @returns A new GuidV4 instance
+     * @throws {GuidError} If the value is not a valid GUID
+     */
+    static parse(value: GuidInput): GuidV4;
+    /**
+     * Attempts to parse a GUID, returning null on failure instead of throwing.
+     * Use this when you're uncertain if the input is valid.
+     * @param value The value to parse
+     * @returns A new GuidV4 instance or null if parsing fails
+     */
+    static tryParse(value: GuidInput): GuidV4 | null;
+    /**
+     * Validates whether a value is a valid GUID without creating an instance.
+     * More efficient than tryParse when you only need validation.
+     * @param value The value to validate
+     * @returns True if valid, false otherwise
+     */
+    static isValid(value: unknown): boolean;
+    /**
+     * Factory method to create a GUID from a full hex string.
+     * @param fullHex The full hex string (with dashes)
+     * @returns A new GuidV4 instance
+     */
+    static fromFullHex(fullHex: string): GuidV4;
+    /**
+     * Factory method to create a GUID from a short hex string.
+     * @param shortHex The short hex string (without dashes)
+     * @returns A new GuidV4 instance
+     */
+    static fromShortHex(shortHex: string): GuidV4;
+    /**
+     * Factory method to create a GUID from a base64 string.
+     * @param base64 The base64 encoded string
+     * @returns A new GuidV4 instance
+     */
+    static fromBase64(base64: string): GuidV4;
+    /**
+     * Factory method to create a GUID from a bigint.
+     * @param bigint The bigint value
+     * @returns A new GuidV4 instance
+     */
+    static fromBigInt(bigint: bigint): GuidV4;
+    /**
+     * Factory method to create a GUID from a raw buffer.
+     * @param buffer The raw 16-byte buffer
+     * @returns A new GuidV4 instance
+     */
+    static fromBuffer(buffer: Buffer): GuidV4;
+    /**
+     * Creates a namespace-based v3 GUID (MD5 hash).
+     * Use this for deterministic GUIDs based on a namespace and name.
+     * @param namespace The namespace GUID (e.g., uuid.v3.DNS)
+     * @param name The name to hash within the namespace
+     * @returns A new GuidV4 instance containing the v3 GUID
+     * @example
+     * const guid = GuidV4.v3('example.com', uuid.v3.DNS);
+     */
+    static v3(name: string, namespace: string | Buffer): GuidV4;
+    /**
+     * Creates a namespace-based v5 GUID (SHA-1 hash).
+     * Use this for deterministic GUIDs based on a namespace and name.
+     * Preferred over v3 as SHA-1 is stronger than MD5.
+     * @param namespace The namespace GUID (e.g., uuid.v5.DNS)
+     * @param name The name to hash within the namespace
+     * @returns A new GuidV4 instance containing the v5 GUID
+     * @example
+     * const guid = GuidV4.v5('example.com', uuid.v5.DNS);
+     */
+    static v5(name: string, namespace: string | Buffer): GuidV4;
+    /**
+     * Common namespace constants for use with v3/v5 GUIDs.
+     * Re-exported from uuid library for convenience.
+     */
+    static readonly Namespaces: {
+        readonly DNS: string;
+        readonly URL: string;
+    };
+    /**
+     * Returns the GUID as a full hex string.
+     * Result is cached for performance.
+     */
+    get asFullHexGuid(): FullHexGuid;
+    /**
+     * Returns the GUID as a raw Uint8Array.
+     */
+    get asUint8Array(): Uint8Array;
+    /**
+     * Returns the GUID as a short hex string.
+     * Result is cached for performance.
+     */
+    get asShortHexGuid(): ShortHexGuid;
+    /**
+     * Returns the GUID as a base64 string.
+     */
+    toString(): Base64Guid;
+    /**
+     * Returns the GUID as a JSON string.
+     * @returns The GUID as a JSON string.
+     */
+    toJson(): string;
+    /**
+     * Returns the GUID as a bigint.
+     */
+    get asBigIntGuid(): BigIntGuid;
+    /**
+     * Returns the GUID as a base64 string.
+     * Result is cached for performance.
+     */
+    get asBase64Guid(): Base64Guid;
+    /**
+     * Checks if a GUID value is a boundary value (all zeros or all Fs).
+     * @param value The GUID value to check.
+     * @returns True if the value is a boundary value.
+     */
+    private static isBoundaryValue;
+    /**
+     * Verifies if a given GUID is valid for the given brand.
+     * @param guidBrand The brand of the GUID to verify.
+     * @param guid The GUID to verify.
+     * @returns True if the GUID is valid for the given brand, false otherwise.
+     */
+    static verifyGuid(guidBrand: GuidBrandType, guid: GuidInput): boolean;
+    /**
+     * Returns the length of the GUID for the given brand.
+     * @param guidBrand The brand of the GUID to get the length for.
+     * @returns The length of the GUID for the given brand.
+     */
+    static guidBrandToLength(guidBrand: GuidBrandType): number;
+    /**
+     * Returns the brand of the GUID for the given length.
+     * @param length The length of the GUID to get the brand for.
+     * @param isBuffer Whether the GUID is a Buffer.
+     * @returns The brand of the GUID for the given length.
+     */
+    static lengthToGuidBrand(length: number, isBuffer: boolean): GuidBrandType;
+    /**
+     * Verifies if a given GUID is a valid full hex GUID.
+     * @param fullHexGuidValue The full hex GUID to verify.
+     * @returns True if the GUID is a valid full hex GUID, false otherwise.
+     */
+    static isFullHexGuid(fullHexGuidValue: GuidInput): boolean;
+    /**
+     * Verifies if a given GUID is a valid short hex GUID.
+     * @param shortHexGuidValue The short hex GUID to verify.
+     * @returns True if the GUID is a valid short hex GUID, false otherwise.
+     */
+    static isShortHexGuid(shortHexGuidValue: GuidInput): boolean;
+    /**
+     * Verifies if a given GUID is a valid base64 GUID.
+     * @param value The base64 GUID to verify.
+     * @returns True if the GUID is a valid base64 GUID, false otherwise.
+     */
+    static isBase64Guid(value: GuidInput): boolean;
+    /**
+     * Verifies if a given GUID is a valid raw GUID buffer.
+     * @param value The raw GUID buffer to verify.
+     * @returns True if the GUID is a valid raw GUID buffer, false otherwise.
+     */
+    static isRawGuidBuffer(value: GuidInput): boolean;
+    /**
+     * Verifies if a given GUID is a valid bigint GUID.
+     * @param value The bigint GUID to verify.
+     * @returns True if the GUID is a valid bigint GUID, false otherwise.
+     */
+    static isBigIntGuid(value: GuidInput): boolean;
+    /**
+     * Determines the brand of a given GUID value.
+     * @param value The GUID value to determine the brand of.
+     * @returns The brand of the GUID value.
+     */
+    static whichBrand(value: GuidInput): GuidBrandType;
+    /**
+     * Converts a given short hex GUID to a full hex GUID.
+     * @param shortGuid The short hex GUID to convert.
+     * @returns The short hex GUID as a full hex GUID.
+     */
+    private static shortGuidToFullGuid;
+    /**
+     * Converts a given GUID value to a full hex GUID.
+     * @param guid The GUID value to convert.
+     * @returns The GUID value as a full hex GUID.
+     */
+    static toFullHexGuid(guid: RawGuidBuffer | BigIntGuid | Base64Guid | ShortHexGuid | FullHexGuid | string): FullHexGuid;
+    static toShortHexGuid(guid: RawGuidBuffer | BigIntGuid | Base64Guid | ShortHexGuid | FullHexGuid | string): ShortHexGuid;
+    /**
+     * Converts a given bigint to a full hex GUID.
+     * @param bigInt The bigint to convert.
+     * @returns The bigint as a full hex GUID.
+     */
+    static toFullHexFromBigInt(bigInt: bigint): FullHexGuid;
+    /**
+     * Converts a given GUID value to a raw GUID buffer.
+     * @param value The GUID value to convert.
+     * @returns The GUID value as a raw GUID buffer.
+     */
+    static toRawGuidBuffer(value: GuidInput): RawGuidBuffer;
+    /**
+     * Compare two GuidV4 instances for equality.
+     * @param other - The other GuidV4 instance to compare (can be null/undefined)
+     * @param constantTime - Use constant-time comparison to prevent timing attacks (default: false)
+     * @returns True if the two GuidV4 instances are equal, false otherwise
+     */
+    equals(other: IGuidV4 | null | undefined, constantTime?: boolean): boolean;
+    /**
+     * Checks if this GUID is empty (all zeros).
+     * @returns True if the GUID is all zeros, false otherwise
+     */
+    isEmpty(): boolean;
+    /**
+     * Static helper to check if a GUID is null, undefined, or empty.
+     * @param guid The GUID to check
+     * @returns True if the GUID is null, undefined, or empty
+     */
+    static isNilOrEmpty(guid: IGuidV4 | null | undefined): boolean;
+    /**
+     * Creates a new GuidV4 instance with the same value as this one.
+     * @returns A new GuidV4 instance with identical value
+     */
+    clone(): GuidV4;
+    /**
+     * Returns the hash code for this GUID based on its buffer content.
+     * Useful for using GUIDs as Map/Set keys.
+     * @returns A numeric hash code
+     */
+    hashCode(): number;
+    /**
+     * Extracts the RFC 4122 version from the GUID.
+     * Returns undefined for boundary values or invalid GUIDs.
+     * @returns The version number (1-5) or undefined
+     */
+    getVersion(): number | undefined;
+    /**
+     * Validates that this GUID is a proper v4 GUID according to RFC 4122.
+     * Boundary values (all zeros/all Fs) return true as they're mathematically valid.
+     * @returns True if valid v4 GUID or boundary value, false otherwise
+     */
+    isValidV4(): boolean;
+    /**
+     * Compares two GUIDs for ordering.
+     * Useful for sorting GUID arrays.
+     * @param other The other GUID to compare to
+     * @returns -1 if this < other, 0 if equal, 1 if this > other
+     */
+    compareTo(other: IGuidV4): number;
+}
+//# sourceMappingURL=guid.d.ts.map

package/src/lib/guid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guid.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-ecies-lib/src/lib/guid.ts"],"names":[],"mappings":"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"}