@digitaldefiance/node-ecies-lib 4.16.20 → 4.16.27

package/src/i18n/node-ecies-i18n-setup.js

@@ -1,48 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeEciesComponentStrings = void 0;
+exports.NodeEciesComponentStrings = exports.EciesComponentId = exports.NodeEciesComponentId = void 0;
+exports.createNodeEciesComponentConfig = createNodeEciesComponentConfig;
 exports.getNodeEciesI18nEngine = getNodeEciesI18nEngine;
 exports.resetNodeEciesI18nEngine = resetNodeEciesI18nEngine;
-exports.createNodeEciesComponentConfig = createNodeEciesComponentConfig;
 exports.getNodeEciesTranslation = getNodeEciesTranslation;
+exports.safeGetNodeEciesTranslation = safeGetNodeEciesTranslation;
 /**
  * Node.js ECIES i18n setup and configuration.
- * Manages i18n engine initialization, component registration, and translation string loading
- * for Node.js-specific ECIES library strings across 8 supported languages.
+ *
+ * This is the single source of truth for i18n in node-ecies-lib.
+ * Uses I18nBuilder pattern for proper engine initialization and registers:
+ * - Core component (for error messages)
+ * - ECIES component (imported from ecies-lib - translations defined there)
+ * - Node ECIES component (translations defined here)
+ *
+ * All components support translateStringKey for direct branded enum translation.
  */
 const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+Object.defineProperty(exports, "EciesComponentId", { enumerable: true, get: function () { return ecies_lib_1.EciesComponentId; } });
 const i18n_lib_1 = require("@digitaldefiance/i18n-lib");
 const node_keys_1 = require("./node-keys");
+Object.defineProperty(exports, "NodeEciesComponentId", { enumerable: true, get: function () { return node_keys_1.NodeEciesComponentId; } });
 const translations_1 = require("./translations");
-// Note: _nodeEciesI18nEngine is used for internal state management
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-let _nodeEciesI18nEngine = null;
-let _componentRegistered = false;
-function getNodeEciesI18nEngine(config) {
-    // Get base ecies engine (uses 'default' key)
-    const baseEngine = (0, ecies_lib_1.getEciesI18nEngine)(config);
-    // Register node-ecies component if not already registered
-    if (!_componentRegistered) {
-        baseEngine.registerIfNotExists(createNodeEciesComponentConfig());
-        _componentRegistered = true;
-    }
-    _nodeEciesI18nEngine = baseEngine;
-    return baseEngine;
-}
-function resetNodeEciesI18nEngine() {
-    _nodeEciesI18nEngine = null;
-    _componentRegistered = false;
-}
-function createNodeEciesComponentConfig() {
-    return {
-        id: node_keys_1.NodeEciesComponentId,
-        strings: exports.NodeEciesComponentStrings,
-        aliases: ['NodeEciesStringKey'],
-    };
-}
 /**
  * Master strings collection for the Node ECIES component.
- * Uses BrandedMasterStringsCollection for type-safe branded enum support.
+ * These are the translations specific to node-ecies-lib.
+ * ECIES translations come from ecies-lib via createEciesComponentConfig().
  */
 exports.NodeEciesComponentStrings = {
     [i18n_lib_1.LanguageCodes.EN_US]: translations_1.englishTranslations,
@@ -55,9 +39,113 @@ exports.NodeEciesComponentStrings = {
     [i18n_lib_1.LanguageCodes.UK]: translations_1.ukrainianTranslations,
 };
 /**
- * Helper to translate Node ECIES strings
+ * Create Node ECIES component configuration
+ */
+function createNodeEciesComponentConfig() {
+    return {
+        id: node_keys_1.NodeEciesComponentId,
+        strings: exports.NodeEciesComponentStrings,
+        aliases: ['NodeEciesStringKey'],
+    };
+}
+let _nodeEciesI18nEngine = null;
+let _componentRegistered = false;
+/**
+ * Register the engine with all required components using I18nBuilder
+ */
+function registerEngine() {
+    const newEngine = i18n_lib_1.I18nBuilder.create()
+        .withLanguages((0, i18n_lib_1.getCoreLanguageDefinitions)())
+        .withDefaultLanguage(i18n_lib_1.LanguageCodes.EN_US)
+        .withInstanceKey('default')
+        .build();
+    // Register Core i18n component (required for error messages)
+    const coreReg = (0, i18n_lib_1.createCoreComponentRegistration)();
+    newEngine.register({
+        id: coreReg.component.id,
+        strings: coreReg.strings,
+    });
+    // Register ECIES component from ecies-lib (translations are defined there)
+    const eciesConfig = (0, ecies_lib_1.createEciesComponentConfig)();
+    newEngine.register({
+        ...eciesConfig,
+        aliases: ['EciesStringKey'],
+    });
+    // Register Node ECIES component (translations defined in this lib)
+    newEngine.register(createNodeEciesComponentConfig());
+    // Register branded string key enums for translateStringKey support
+    // Done after build to avoid issues with jest.resetModules() in tests
+    try {
+        if (!newEngine.hasStringKeyEnum(ecies_lib_1.EciesStringKey)) {
+            newEngine.registerStringKeyEnum(ecies_lib_1.EciesStringKey);
+        }
+    }
+    catch {
+        // Silently ignore if enum registration fails (e.g., in test environments)
+    }
+    try {
+        if (!newEngine.hasStringKeyEnum(node_keys_1.NodeEciesStringKey)) {
+            newEngine.registerStringKeyEnum(node_keys_1.NodeEciesStringKey);
+        }
+    }
+    catch {
+        // Silently ignore if enum registration fails (e.g., in test environments)
+    }
+    return newEngine;
+}
+/**
+ * Get or create the Node ECIES i18n engine.
+ *
+ * This engine has Core, ECIES, and NodeECIES components registered,
+ * allowing translateStringKey to work with both EciesStringKey and NodeEciesStringKey.
+ */
+function getNodeEciesI18nEngine() {
+    if (i18n_lib_1.I18nEngine.hasInstance('default')) {
+        _nodeEciesI18nEngine = i18n_lib_1.I18nEngine.getInstance('default');
+        // Ensure our components are registered on existing instance
+        if (!_componentRegistered) {
+            // Register ECIES component if not present (translations from ecies-lib)
+            const eciesConfig = (0, ecies_lib_1.createEciesComponentConfig)();
+            _nodeEciesI18nEngine.registerIfNotExists({
+                ...eciesConfig,
+                aliases: ['EciesStringKey'],
+            });
+            // Register Node ECIES component if not present
+            _nodeEciesI18nEngine.registerIfNotExists(createNodeEciesComponentConfig());
+            // Register branded string key enums for translateStringKey support
+            if (!_nodeEciesI18nEngine.hasStringKeyEnum(ecies_lib_1.EciesStringKey)) {
+                _nodeEciesI18nEngine.registerStringKeyEnum(ecies_lib_1.EciesStringKey);
+            }
+            if (!_nodeEciesI18nEngine.hasStringKeyEnum(node_keys_1.NodeEciesStringKey)) {
+                _nodeEciesI18nEngine.registerStringKeyEnum(node_keys_1.NodeEciesStringKey);
+            }
+            _componentRegistered = true;
+        }
+    }
+    else {
+        _nodeEciesI18nEngine = registerEngine();
+        _componentRegistered = true;
+    }
+    return _nodeEciesI18nEngine;
+}
+/**
+ * Reset the engine instance (useful for testing)
+ */
+function resetNodeEciesI18nEngine() {
+    _nodeEciesI18nEngine = null;
+    _componentRegistered = false;
+}
+/**
+ * Helper to translate Node ECIES strings.
+ * Uses translateStringKey for automatic component ID resolution from the branded enum.
  */
 function getNodeEciesTranslation(stringKey, variables, language) {
-    return getNodeEciesI18nEngine().translate(node_keys_1.NodeEciesComponentId, stringKey, variables, language);
+    return getNodeEciesI18nEngine().translateStringKey(stringKey, variables, language);
+}
+/**
+ * Safe translation helper that returns a placeholder on failure.
+ */
+function safeGetNodeEciesTranslation(stringKey, variables, language) {
+    return getNodeEciesI18nEngine().safeTranslateStringKey(stringKey, variables, language);
 }
 //# sourceMappingURL=node-ecies-i18n-setup.js.map

package/src/i18n/node-ecies-i18n-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-ecies-i18n-setup.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-ecies-lib/src/i18n/node-ecies-i18n-setup.ts"],"names":[],"mappings":";;;AAiCA,wDAYC;AAED,4DAGC;AAED,wEAMC;AAuBD,0DAWC;AA5FD;;;;GAIG;AACH,0DAAgE;AAChE,wDAOmC;AAEnC,2CAAuE;AAEvE,iDASwB;AAExB,mEAAmE;AACnE,6DAA6D;AAC7D,IAAI,oBAAoB,GAAsB,IAAI,CAAC;AACnD,IAAI,oBAAoB,GAAG,KAAK,CAAC;AAEjC,SAAgB,sBAAsB,CAAC,MAAqB;IAC1D,6CAA6C;IAC7C,MAAM,UAAU,GAAG,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;IAE9C,0DAA0D;IAC1D,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,UAAU,CAAC,mBAAmB,CAAC,8BAA8B,EAAE,CAAC,CAAC;QACjE,oBAAoB,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED,oBAAoB,GAAG,UAAU,CAAC;IAClC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAgB,wBAAwB;IACtC,oBAAoB,GAAG,IAAI,CAAC;IAC5B,oBAAoB,GAAG,KAAK,CAAC;AAC/B,CAAC;AAED,SAAgB,8BAA8B;IAC5C,OAAO;QACL,EAAE,EAAE,gCAAoB;QACxB,OAAO,EAAE,iCAAyB;QAClC,OAAO,EAAE,CAAC,oBAAoB,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACU,QAAA,yBAAyB,GAGlC;IACF,CAAC,wBAAa,CAAC,KAAK,CAAC,EAAE,kCAAmB;IAC1C,CAAC,wBAAa,CAAC,KAAK,CAAC,EAAE,yCAA0B;IACjD,CAAC,wBAAa,CAAC,EAAE,CAAC,EAAE,iCAAkB;IACtC,CAAC,wBAAa,CAAC,EAAE,CAAC,EAAE,kCAAmB;IACvC,CAAC,wBAAa,CAAC,EAAE,CAAC,EAAE,iCAAkB;IACtC,CAAC,wBAAa,CAAC,KAAK,CAAC,EAAE,mCAAoB;IAC3C,CAAC,wBAAa,CAAC,EAAE,CAAC,EAAE,mCAAoB;IACxC,CAAC,wBAAa,CAAC,EAAE,CAAC,EAAE,oCAAqB;CAC1C,CAAC;AAEF;;GAEG;AACH,SAAgB,uBAAuB,CACrC,SAAkC,EAClC,SAA2C,EAC3C,QAAiB;IAEjB,OAAO,sBAAsB,EAAE,CAAC,SAAS,CACvC,gCAAoB,EACpB,SAAS,EACT,SAAS,EACT,QAAQ,CACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"node-ecies-i18n-setup.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-ecies-lib/src/i18n/node-ecies-i18n-setup.ts"],"names":[],"mappings":"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"}

package/src/lib/guid.d.ts

@@ -1,8 +1,8 @@
 /**
  * RFC 4122 compliant GUID implementation for Node.js.
- * Extends GuidUint8Array from ecies-lib to ensure type compatibility while using Buffer internally.
+ * Extends Buffer directly to ensure full Buffer compatibility in Node.js environments.
  */
-import { GuidInput, GuidUint8Array, IGuid } from '@digitaldefiance/ecies-lib';
+import { GuidInput, GuidUint8Array, IGuid, type Base64Guid, type BigIntGuid, type FullHexGuid, type RawGuidPlatformBuffer, type ShortHexGuid } from '@digitaldefiance/ecies-lib';
 import * as uuid from 'uuid';
 import { PlatformBuffer } from '../interfaces';
 /**
@@ -12,55 +12,344 @@ export type VersionedGuidBuffer<V extends 1 | 3 | 4 | 5 | 6 | 7 | undefined = 1
     readonly __version: V;
 };
 /**
- * Node.js GUID implementation that extends GuidUint8Array but uses Buffer internally.
- * This ensures type compatibility with ecies-lib while leveraging Node.js Buffer capabilities.
+ * Node.js GUID implementation that extends Buffer directly.
+ * This ensures full Buffer compatibility while providing GUID-specific functionality.
+ *
+ * Implements IGuid interface for compatibility with ecies-lib.
  */
-export declare class GuidBuffer extends GuidUint8Array implements IGuid {
+export declare class GuidBuffer extends Buffer implements IGuid {
+    /**
+     * Cached full hex representation for performance
+     */
+    private _cachedFullHex?;
+    /**
+     * Cached short hex representation for performance
+     */
+    private _cachedShortHex?;
+    /**
+     * Cached base64 representation for performance
+     */
+    private _cachedBase64?;
+    /**
+     * The RFC 4122 version of this GUID
+     */
+    __version?: 1 | 3 | 4 | 5 | 6 | 7 | undefined;
+    /**
+     * Creates a new GuidBuffer from any valid GUID input.
+     *
+     * Note: Due to Buffer subclassing limitations, this constructor
+     * returns a new instance created via Object.setPrototypeOf.
+     */
     constructor(value: GuidInput);
+    /**
+     * Override species to return Buffer for methods like slice(), map(), etc.
+     */
+    static get [Symbol.species](): typeof Buffer;
+    /**
+     * Internal factory to create a GuidBuffer from validated bytes (no validation).
+     */
+    private static createFromBytes;
+    /**
+     * Static factory method (alternative to constructor).
+     */
+    static create(value: GuidInput): GuidBuffer;
     /**
      * Returns the GUID as a raw Buffer.
+     * Returns itself since GuidBuffer IS a Buffer.
+     * @deprecated Use asRawBuffer for a plain Buffer copy to avoid type mismatches.
      */
     get asBuffer(): Buffer;
+    /**
+     * Returns the GUID as a plain Buffer (defensive copy).
+     * Use this when you need a plain Buffer type rather than GuidBuffer.
+     */
+    get asRawBuffer(): Buffer;
+    /**
+     * Returns the GUID as a raw Uint8Array (defensive copy).
+     */
+    get asRawGuidPlatformBuffer(): RawGuidPlatformBuffer;
+    /**
+     * Returns the internal buffer without copying.
+     * @internal
+     */
+    get asRawGuidPlatformBufferUnsafe(): RawGuidPlatformBuffer;
     /**
      * Returns the GUID as a native Uint8Array (not a Buffer).
      */
     get asUint8Array(): Uint8Array;
+    /**
+     * Returns the GUID as a PlatformBuffer (Buffer in Node.js).
+     * Returns itself since GuidBuffer IS a Buffer.
+     */
     get asPlatformBuffer(): PlatformBuffer;
     /**
-     * Factory method to create a GUID from a raw buffer.
+     * Returns the GUID as a full hex string (with dashes).
+     * Result is cached for performance.
      */
-    static fromBuffer(buffer: Buffer): VersionedGuidBuffer;
+    get asFullHexGuid(): FullHexGuid;
     /**
-     * Factory method to create a GUID from a raw Uint8Array.
+     * Returns the GUID as a short hex string (without dashes).
+     * Result is cached for performance.
      */
-    static fromUint8Array(bytes: Uint8Array): VersionedGuidBuffer;
+    get asShortHexGuid(): ShortHexGuid;
     /**
-     * Alias for isRawGuidPlatformBuffer for backward compatibility
+     * Returns the GUID as a base64 string.
+     * Result is cached for performance.
      */
-    static isRawGuidBuffer: typeof GuidUint8Array.isRawGuidUint8Array;
+    get asBase64Guid(): Base64Guid;
     /**
-     * Converts a GUID input to a raw Buffer (Node.js specific).
+     * Returns the GUID as a bigint.
      */
-    static toRawGuidBuffer(value: GuidInput): Buffer;
+    get asBigIntGuid(): BigIntGuid;
+    /**
+     * Returns a URL-safe base64 representation.
+     */
+    get asUrlSafeBase64(): string;
+    /**
+     * Serializes the GUID to a base64 string.
+     */
+    serialize(): string;
+    /**
+     * Returns the GUID as a JSON string.
+     */
+    toJson(): string;
+    /**
+     * Returns the GUID as a base64 string (default string representation).
+     * Overloaded to support both Buffer encoding and IGuid interface.
+     */
+    toString(): Base64Guid;
+    toString(encoding: BufferEncoding): string;
+    /**
+     * Extracts the RFC 4122 version from the GUID.
+     */
+    getVersion(): number | undefined;
+    /**
+     * Extracts the variant from the GUID.
+     */
+    getVariant(): number | undefined;
+    /**
+     * Returns the timestamp from a v1 GUID.
+     */
+    getTimestamp(): Date | undefined;
+    /**
+     * Checks if this GUID is empty (all zeros).
+     */
+    isEmpty(): boolean;
+    /**
+     * Validates that this GUID is a proper v1 GUID.
+     */
+    isValidV1(): boolean;
+    /**
+     * Validates that this GUID is a proper v3 GUID.
+     */
+    isValidV3(): boolean;
+    /**
+     * Validates that this GUID is a proper v4 GUID.
+     */
+    isValidV4(): boolean;
+    /**
+     * Validates that this GUID is a proper v5 GUID.
+     */
+    isValidV5(): boolean;
+    /**
+     * Validates that this GUID is a proper v6 GUID.
+     */
+    isValidV6(): boolean;
+    /**
+     * Validates that this GUID is a proper v7 GUID.
+     */
+    isValidV7(): boolean;
+    /**
+     * Compare two Guid instances for equality (IGuid interface).
+     * Note: This is named guidEquals to avoid conflict with Buffer.equals()
+     */
+    guidEquals(other: IGuid | null | undefined, constantTime?: boolean): boolean;
+    /**
+     * IGuid.equals implementation - delegates to guidEquals.
+     * Uses method overloading to satisfy both Buffer and IGuid interfaces.
+     */
+    equals(otherBuffer: Uint8Array): boolean;
+    equals(other: IGuid | null | undefined, constantTime?: boolean): boolean;
+    /**
+     * Creates a clone of this GUID.
+     */
+    clone(): VersionedGuidBuffer;
+    /**
+     * Returns a hash code for this GUID.
+     */
+    hashCode(): number;
+    /**
+     * Compares two GUIDs for ordering.
+     */
+    compareTo(other: IGuid): number;
+    /**
+     * Returns a human-readable debug string.
+     */
+    toDebugString(): string;
     /**
      * Attaches the RFC 4122 version to a GuidBuffer instance.
      */
     private static attachVersion;
+    /**
+     * Generates a new random v4 GUID.
+     */
     static v4(): VersionedGuidBuffer<4>;
-    static v5(name: string, namespace: string | Uint8Array): VersionedGuidBuffer<5>;
+    /**
+     * Alias for v4().
+     */
+    static generate(): VersionedGuidBuffer<4>;
+    /**
+     * Alias for v4() for backward compatibility.
+     * @deprecated Use generate() instead
+     */
+    static new(): VersionedGuidBuffer<4>;
+    /**
+     * Creates a v1 (time-based) GUID.
+     */
+    static v1(options?: uuid.Version1Options): VersionedGuidBuffer<1>;
+    /**
+     * Creates a v3 (MD5 namespace) GUID.
+     */
     static v3(name: string, namespace: string | Uint8Array): VersionedGuidBuffer<3>;
+    /**
+     * Creates a v5 (SHA-1 namespace) GUID.
+     */
+    static v5(name: string, namespace: string | Uint8Array): VersionedGuidBuffer<5>;
+    /**
+     * Creates a v6 GUID.
+     */
     static v6(options?: uuid.Version6Options): VersionedGuidBuffer<6>;
+    /**
+     * Creates a v7 GUID.
+     */
     static v7(options?: uuid.Version7Options): VersionedGuidBuffer<7>;
-    static v1(options?: uuid.Version1Options): VersionedGuidBuffer<1>;
+    /**
+     * Parses a GUID from any valid format.
+     */
     static parse(value: GuidInput): VersionedGuidBuffer;
+    /**
+     * Attempts to parse a GUID, returning null on failure.
+     */
     static tryParse(value: GuidInput): VersionedGuidBuffer | null;
-    static generate(): VersionedGuidBuffer<4>;
-    static new(): VersionedGuidBuffer<4>;
+    /**
+     * Hydrates a GuidBuffer from a serialized string.
+     */
+    static hydrate(value: string): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a full hex string.
+     */
     static fromFullHex(fullHex: string): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a short hex string.
+     */
     static fromShortHex(shortHex: string): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a base64 string.
+     */
     static fromBase64(base64: string): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a bigint.
+     */
     static fromBigInt(bigint: bigint): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a raw Buffer.
+     */
+    static fromBuffer(buffer: Buffer): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a raw Uint8Array.
+     */
+    static fromUint8Array(bytes: Uint8Array): VersionedGuidBuffer;
+    /**
+     * Factory method to create a GUID from a platform buffer.
+     */
     static fromPlatformBuffer(bytes: Uint8Array): VersionedGuidBuffer;
-    clone(): VersionedGuidBuffer;
+    /**
+     * Creates a GUID from URL-safe base64.
+     */
+    static fromUrlSafeBase64(urlSafe: string): VersionedGuidBuffer;
+    /**
+     * Converts a GUID input to a raw Buffer.
+     */
+    static toRawGuidBuffer(value: GuidInput): Buffer;
+    /**
+     * Validates a UUID string.
+     */
+    static validateUuid(value: string): boolean;
+    /**
+     * Checks if a value is a valid raw GUID buffer.
+     */
+    static isRawGuidBuffer(value: GuidInput): boolean;
+    /**
+     * Converts a GUID to full hex format.
+     */
+    static toFullHexGuid: typeof GuidUint8Array.toFullHexGuid;
+    /**
+     * Converts a GUID to short hex format.
+     */
+    static toShortHexGuid: typeof GuidUint8Array.toShortHexGuid;
+    /**
+     * Converts a bigint to full hex GUID format.
+     */
+    static toFullHexFromBigInt: typeof GuidUint8Array.toFullHexFromBigInt;
+    /**
+     * Converts a GUID to raw platform buffer.
+     */
+    static toRawGuidPlatformBuffer: typeof GuidUint8Array.toRawGuidPlatformBuffer;
+    /**
+     * Determines the brand/type of a GUID value.
+     */
+    static whichBrand: typeof GuidUint8Array.whichBrand;
+    /**
+     * Verifies if a GUID is valid for a given brand.
+     */
+    static verifyGuid: typeof GuidUint8Array.verifyGuid;
+    /**
+     * Returns the expected length for a GUID brand.
+     */
+    static guidBrandToLength: typeof GuidUint8Array.guidBrandToLength;
+    /**
+     * Returns the GUID brand for a given length.
+     */
+    static lengthToGuidBrand: typeof GuidUint8Array.lengthToGuidBrand;
+    /**
+     * Checks if a value is a valid full hex GUID.
+     */
+    static isFullHexGuid: typeof GuidUint8Array.isFullHexGuid;
+    /**
+     * Checks if a value is a valid short hex GUID.
+     */
+    static isShortHexGuid: typeof GuidUint8Array.isShortHexGuid;
+    /**
+     * Checks if a value is a valid base64 GUID.
+     */
+    static isBase64Guid: typeof GuidUint8Array.isBase64Guid;
+    /**
+     * Checks if a value is a valid bigint GUID.
+     */
+    static isBigIntGuid: typeof GuidUint8Array.isBigIntGuid;
+    /**
+     * Checks if a value is a valid raw GUID Uint8Array.
+     */
+    static isRawGuidUint8Array: typeof GuidUint8Array.isRawGuidUint8Array;
+    /**
+     * Validates whether a value is a valid GUID.
+     */
+    static isValid: typeof GuidUint8Array.isValid;
+    /**
+     * Static helper to check if a GUID is null, undefined, or empty.
+     */
+    static isNilOrEmpty(guid: IGuid | null | undefined): boolean;
+    /**
+     * Common namespace constants for use with v3/v5 GUIDs.
+     */
+    static readonly Namespaces: {
+        readonly DNS: "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+        readonly URL: "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+    };
+    /**
+     * Empty/nil GUID constant (all zeros).
+     */
+    private static _empty?;
+    static get Empty(): GuidBuffer;
 }
 //# sourceMappingURL=guid.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"guid.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-ecies-lib/src/lib/guid.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAC7B,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,GACvC,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,SAAS,IACX,UAAU,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAA;CAAE,CAAC;AAE3C;;;GAGG;AACH,qBAAa,UAAW,SAAQ,cAAe,YAAW,KAAK;gBACjD,KAAK,EAAE,SAAS;IAS5B;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAI5B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,UAAU,CAEpC;IAED,IAAW,gBAAgB,IAAI,cAAc,CAI5C;IAED;;OAEG;WACW,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB;IAI7D;;OAEG;WACW,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB;IAIpE;;OAEG;IACH,OAAc,eAAe,4CAAsC;IAEnE;;OAEG;WACW,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAKvD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;WASL,EAAE,IAAI,mBAAmB,CAAC,CAAC,CAAC;WAM5B,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,UAAU,GAC7B,mBAAmB,CAAC,CAAC,CAAC;WAMF,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,UAAU,GAC7B,mBAAmB,CAAC,CAAC,CAAC;WAMF,EAAE,CACvB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,GAC7B,mBAAmB,CAAC,CAAC,CAAC;WAMF,EAAE,CACvB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,GAC7B,mBAAmB,CAAC,CAAC,CAAC;WAMF,EAAE,CACvB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,GAC7B,mBAAmB,CAAC,CAAC,CAAC;WAMF,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,mBAAmB;WAI5C,QAAQ,CAC7B,KAAK,EAAE,SAAS,GACf,mBAAmB,GAAG,IAAI;WAQN,QAAQ,IAAI,mBAAmB,CAAC,CAAC,CAAC;WAIlC,GAAG,IAAI,mBAAmB,CAAC,CAAC,CAAC;WAI7B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB;WAIjD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB;WAInD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB;WAI/C,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB;WAI/C,kBAAkB,CACvC,KAAK,EAAE,UAAU,GAChB,mBAAmB;IAIN,KAAK,IAAI,mBAAmB;CAG7C"}
+{"version":3,"file":"guid.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-ecies-lib/src/lib/guid.ts"],"names":[],"mappings":"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"}