nhb-toolbox/dist/dts/hash/uuid.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { DecodedUUID, SupportedVersion, UUID, UUIDOptions } from './types';
/**
 * * Generates UUIDs across all major RFC-compliant versions (1, 3, 4, 5, 6, 7, 8), following standards from `RFC4122`. Default version is `v4`.
 *
 * - **Version behavior:**
 *   - `v1` → Timestamp & node-identifier–based
 *   - `v3` → MD5(namespace + name)
 *   - `v4` → Pure random (correct variant + version injection)
 *   - `v5` → SHA-1(namespace + name)
 *   - `v6` → Re-ordered timestamp variant of `v1` (lexicographically sortable)
 *   - `v7` → Unix-time–based, monotonic-friendly
 *   - `v8` → Custom layout, '“Future'` variant (timestamp + randomness)
 *
 * @param options Controls version, formatting, and required fields for `v3` and `v5`.
 * @returns A 5-parts UUID string formatted with correct version/variant bits.
 *
 * @example
 * // Generate a random UUID v4
 * const id = uuid();
 *
 * @example
 * // Generate uppercase v7
 * const id = uuid({ version: 'v7', uppercase: true });
 *
 * @example
 * // Generate v5 UUID
 * const id = uuid({
 *   version: 'v5',
 *   namespace: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
 *   name: 'example'
 * });
 *
 * @remarks
 * - This utility provides a complete, engine-agnostic UUID generator with full RFC compliance, predictable formatting, and reliable uniqueness characteristics, suitable for browsers, Node.js, and restricted JavaScript runtimes.
 * - **Notes**
 *   - `v1` and `v6` use a generated pseudo-node identifier.
 *   - `v4` and `v8` uses {@link Math.random} when {@link crypto.getRandomValues} is unavailable, ensuring broad compatibility.
 *   - `v3` and `v5` use internal `MD5`/`SHA-1` implementations and remain fully deterministic.
 *   - `v7` **do not rely on crypto APIs**, preserving engine-agnostic behavior.
 *
 * - **Limitations**
 *   - `v1`/`v6`: Node identifier is pseudo-random, not derived from real MAC addresses (for privacy).
 *   - `v3`/`v5`: Hash algorithms (`MD5`/`SHA-1`) follow RFC specs but are not cryptographically secure.
 *   - `v7`: Millisecond precision; extremely high throughput may still cause rare collisions.
 *   - `v8`: Uses a simple timestamp + randomness layout; custom layouts are not supported here.
 *
 * - Use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/generateRandomID generateRandomID} for customized id generation or {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex randomHex} for hex-only random string with custom length.
 */
export declare function uuid<V extends SupportedVersion = 'v4'>(options?: UUIDOptions<V>): UUID<V>;
/**
 * * Decodes a UUID into its internal components, including version, variant, timestamps for time-based UUIDs and other metadata.
 *   - Supports `RFC4122` UUID versions: 1-8.
 *
 * @param uuid The UUID string to decode.
 * @returns A structured `DecodedUUID` object, or `null` for invalid UUIDs.
 *
 * @example
 * const info = decodeUUID("f47ac10b-58cc-4372-a567-0e02b2c3d479");
 *
 * @example
 * const info = decodeUUID(uuid({ version: "v1" }));
 *
 * @remarks
 * - Provides a cross-runtime UUID decoder covering essential metadata and timestamp interpretation for time-ordered UUID versions.
 * - **Notes**
 *   - `v1/v6` timestamps are converted from the UUID epoch (1582-10-15) to standard Unix milliseconds.
 *   - `v6` timestamps are lexicographically sortable and decoded accordingly.
 *   - `v7` timestamps map directly to Unix time (48-bit millisecond precision).
 *   - `v8` decoding is minimal because layouts are intentionally user-defined.
 *
 * - **Limitations**
 *   - `v2` decoding is not implemented specifically.
 *   - `v8` decoding only returns timestamp if it matches a known layout.
 *   - `v3/v5` hash UUIDs contain no timestamp information.
 */
export declare function decodeUUID(uuid: string): DecodedUUID | null;
/** Check if a value is UUID version 1 */
export declare function isUUIDv1(value: unknown): value is UUID<'v1'>;
/** Check if a value is UUID version 2 */
export declare function isUUIDv2(value: unknown): value is UUID<'v2'>;
/** Check if a value is UUID version 3 */
export declare function isUUIDv3(value: unknown): value is UUID<'v3'>;
/** Check if a value is UUID version 4 */
export declare function isUUIDv4(value: unknown): value is UUID<'v4'>;
/** Check if a value is UUID version 5 */
export declare function isUUIDv5(value: unknown): value is UUID<'v5'>;
/** Check if a value is UUID version 6 */
export declare function isUUIDv6(value: unknown): value is UUID<'v6'>;
/** Check if a value is UUID version 7 */
export declare function isUUIDv7(value: unknown): value is UUID<'v7'>;
/** Check if a value is UUID version 8 */
export declare function isUUIDv8(value: unknown): value is UUID<'v8'>;