tessl/npm-uuid

RFC9562 UUIDs

—

Pending

Overview

Eval results

Files

UUID Generation

Name: tessl/npm-uuid
Author: tessl

Comprehensive UUID generation functions supporting all RFC9562 versions, each optimized for different use cases from random generation to timestamp-based to namespace-based UUIDs.

Capabilities

Version 4 (Random) UUID

Generates a random UUID using cryptographically secure random values. This is the most commonly used UUID version.

/**
 * Generate a random UUID version 4
 * @param options - Optional configuration for random generation
 * @returns UUID string in canonical format
 */
function v4(options?: Version4Options): string;

/**
 * Generate a random UUID version 4 into a buffer
 * @param options - Optional configuration for random generation
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v4<TBuf extends Uint8Array>(
  options: Version4Options | undefined,
  buf: TBuf,
  offset?: number
): TBuf;

type Version4Options = {
  /** Custom random bytes (must be 16 bytes) */
  random?: Uint8Array;
  /** Custom random number generator function */
  rng?: () => Uint8Array;
};

Usage Examples:

import { v4 } from "uuid";

// Basic random UUID
const id = v4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

// Custom random source
const customId = v4({
  random: crypto.getRandomValues(new Uint8Array(16))
});

// Write to buffer
const buffer = new Uint8Array(16);
v4(undefined, buffer);

Version 1 (Timestamp) UUID

Generates a UUID based on timestamp and MAC address (or random node). Provides temporal ordering but may reveal information about when and where it was generated.

/**
 * Generate a timestamp-based UUID version 1
 * @param options - Optional configuration for timestamp generation
 * @returns UUID string in canonical format
 */
function v1(options?: Version1Options): string;

/**
 * Generate a timestamp-based UUID version 1 into a buffer
 * @param options - Optional configuration for timestamp generation
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v1<TBuf extends Uint8Array>(
  options: Version1Options | undefined,
  buf: TBuf,
  offset?: number
): TBuf;

type Version1Options = {
  /** Node ID as a 6-byte array (defaults to random) */
  node?: Uint8Array;
  /** Custom clock sequence (0-0x3fff) */
  clockseq?: number;
  /** Custom random bytes for node/clock fields */
  random?: Uint8Array;
  /** Custom random number generator */
  rng?: () => Uint8Array;
  /** Custom timestamp in milliseconds since epoch */
  msecs?: number;
  /** Custom nanoseconds (0-9999) */
  nsecs?: number;
};

Usage Examples:

import { v1 } from "uuid";

// Basic timestamp UUID
const timestampId = v1(); // ⇨ '4f20936c-6e8f-11ef-8f2f-d1234567890a'

// Custom node and timestamp
const customId = v1({
  node: new Uint8Array([0x01, 0x23, 0x45, 0x67, 0x89, 0xab]),
  msecs: Date.now(),
  nsecs: 1234
});

Version 6 (Reordered Timestamp) UUID

Similar to v1 but with reordered timestamp fields for better database performance and natural sorting.

/**
 * Generate a reordered timestamp UUID version 6
 * @param options - Optional configuration (same as v1)
 * @returns UUID string in canonical format
 */
function v6(options?: Version6Options): string;

/**
 * Generate a reordered timestamp UUID version 6 into a buffer
 * @param options - Optional configuration (same as v1)
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v6<TBuf extends Uint8Array>(
  options: Version6Options | undefined,
  buf: TBuf,
  offset?: number
): TBuf;

type Version6Options = Version1Options;

Usage Examples:

import { v6 } from "uuid";

// Basic v6 UUID (better for databases)
const sortableId = v6(); // ⇨ '1ef6e8f0-936c-6f20-8f2f-d1234567890a'

// Same options as v1
const customV6 = v6({
  msecs: Date.now(),
  nsecs: 5000
});

Version 7 (Unix Epoch Time) UUID

Generates UUIDs based on Unix Epoch timestamp with millisecond precision, designed for modern applications requiring time-ordered UUIDs.

/**
 * Generate a Unix Epoch time-based UUID version 7
 * @param options - Optional configuration for time-based generation
 * @returns UUID string in canonical format
 */
function v7(options?: Version7Options): string;

/**
 * Generate a Unix Epoch time-based UUID version 7 into a buffer
 * @param options - Optional configuration for time-based generation
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v7<TBuf extends Uint8Array>(
  options: Version7Options | undefined,
  buf: TBuf,
  offset?: number
): TBuf;

type Version7Options = {
  /** Custom random bytes for randomness fields */
  random?: Uint8Array;
  /** Custom timestamp in milliseconds since Unix epoch */
  msecs?: number;
  /** Custom sequence counter for same-millisecond ordering */
  seq?: number;
  /** Custom random number generator */
  rng?: () => Uint8Array;
};

Usage Examples:

import { v7 } from "uuid";

// Basic v7 UUID (time-ordered)
const timeId = v7(); // ⇨ '01912e9a-b123-7456-9abc-def012345678'

// Custom timestamp and sequence
const customV7 = v7({
  msecs: Date.now(),
  seq: 12345
});

Version 3 (Namespace + MD5) UUID

Generates deterministic UUIDs based on a namespace UUID and a name using MD5 hashing.

/**
 * Generate a namespace-based UUID version 3 using MD5
 * @param value - The name to hash (string or bytes)
 * @param namespace - Namespace UUID (string or bytes)
 * @returns UUID string in canonical format
 */
function v3(value: string | Uint8Array, namespace: UUIDTypes): string;

/**
 * Generate a namespace-based UUID version 3 into a buffer
 * @param value - The name to hash (string or bytes)
 * @param namespace - Namespace UUID (string or bytes)
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v3<TBuf extends Uint8Array>(
  value: string | Uint8Array,
  namespace: UUIDTypes,
  buf: TBuf,
  offset?: number
): TBuf;

Namespace Constants:

// Predefined namespace UUIDs
v3.DNS: string;    // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
v3.URL: string;    // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'

Usage Examples:

import { v3 } from "uuid";

// DNS namespace
const dnsId = v3('example.com', v3.DNS);
// ⇨ '9073926b-929f-31c2-abc9-fad77ae3e8eb'

// URL namespace
const urlId = v3('https://example.com/page', v3.URL);
// ⇨ '3d813cbb-47fb-32ba-91df-831e1593ac29'

// Custom namespace
const customNamespace = '550e8400-e29b-41d4-a716-446655440000';
const customId = v3('my-resource', customNamespace);

Version 5 (Namespace + SHA-1) UUID

Similar to v3 but uses SHA-1 instead of MD5 for stronger cryptographic hashing.

/**
 * Generate a namespace-based UUID version 5 using SHA-1
 * @param value - The name to hash (string or bytes)
 * @param namespace - Namespace UUID (string or bytes)
 * @returns UUID string in canonical format
 */
function v5(value: string | Uint8Array, namespace: UUIDTypes): string;

/**
 * Generate a namespace-based UUID version 5 into a buffer
 * @param value - The name to hash (string or bytes)
 * @param namespace - Namespace UUID (string or bytes)
 * @param buf - Buffer to write UUID bytes to
 * @param offset - Starting offset in buffer (default: 0)
 * @returns The buffer with UUID bytes written
 */
function v5<TBuf extends Uint8Array>(
  value: string | Uint8Array,
  namespace: UUIDTypes,
  buf: TBuf,
  offset?: number
): TBuf;

Namespace Constants:

// Predefined namespace UUIDs (same as v3)
v5.DNS: string;    // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
v5.URL: string;    // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'

Usage Examples:

import { v5 } from "uuid";

// DNS namespace (recommended over v3)
const dnsId = v5('example.com', v5.DNS);
// ⇨ '2ed6657d-e927-568b-95e1-2665a8aea6a2'

// URL namespace
const urlId = v5('https://example.com/page', v5.URL);
// ⇨ '3bbcee75-cecc-5b56-8031-b6641c1ed1f1'

// Generate from bytes
const nameBytes = new TextEncoder().encode('my-name');
const bytesId = v5(nameBytes, v5.DNS);

Buffer Operations

All UUID generation functions support writing directly to buffers for performance-critical applications:

import { v4, v1, v7 } from "uuid";

// Pre-allocated buffer
const buffer = new Uint8Array(16);

// Write different UUID versions to the same buffer
v4(undefined, buffer);        // Random UUID
v1(undefined, buffer);        // Timestamp UUID
v7(undefined, buffer);        // Unix Epoch UUID

// Custom buffer types
const nodeBuffer = Buffer.alloc(16);
v4(undefined, nodeBuffer);    // Works with Node.js Buffer

Install with Tessl CLI