@kakilangit/id-generator

WebAssembly bindings for ID Generator tool - Generate UUID, NULID, and NanoID identifiers.

Overview

This package provides fast ID generation and decoding functionality compiled to WebAssembly from Rust. It supports:

• UUID v1 (time-based) - Time-based with MAC address
• UUID v4 (random) - Randomly generated UUIDs
• UUID v6 (time-ordered) - Time-ordered for better database locality
• UUID v7 (time-based) - Time-ordered UUIDs with millisecond precision
• UUID v8 (custom) - Custom format for experimental use
• NULID (nanosecond ULID) - Lexicographically sortable IDs with nanosecond precision
• NanoID - URL-friendly, cryptographically secure random ID

Installation

npm install @kakilangit/id-generator

Usage

import init, { generate_ids, decode_id, IdFormat, IdCase } from '@kakilangit/id-generator';

// Initialize the WASM module
await init();

// Generate 5 UUID v4 IDs in lowercase
const uuids = generate_ids(IdFormat.UuidV4, 5, IdCase.Lower);
console.log(uuids); // ["a1b2c3d4-...", "e5f6g7h8-...", ...]

// Generate time-based UUID v7
const uuid7s = generate_ids(IdFormat.UuidV7, 1, IdCase.Lower);

// Generate NULIDs (nanosecond precision)
const nulids = generate_ids(IdFormat.Nulid, 3, IdCase.Upper);

// Generate NanoIDs (URL-safe, 21 characters by default)
const nanoids = generate_ids(IdFormat.NanoId, 5, IdCase.Lower);

// Decode an ID to get metadata
const decoded = decode_id("01hny0qzcw8a5v8z...");
console.log(decoded.format);     // "NULID"
console.log(decoded.time);       // "2024-01-15T10:30:45.123456789Z"
console.log(decoded.timestamp);  // { precision: "ns", value: "1705315845123456789" }
console.log(decoded.hex);       // Hex representation
console.log(decoded.bytes);      // Byte representation (colon-separated)

API

Functions

generate_ids(format, count, case)

Generates multiple IDs of the specified format.

• format (IdFormat): The ID format to generate
• count (number): Number of IDs to generate (1-10000)
• case (IdCase): Case format for alphabetic characters (ignored for NanoID)

Returns: string[] - Array of generated IDs

decode_id(id)

Decodes an ID string and returns its metadata.

• id (string): The ID to decode

Returns DecodedId:

• original: The original ID string
• format: Detected format name ("UUID v1", "UUID v4", "UUID v6", "UUID v7", "UUID v8", "NULID")
• time: RFC 3339 formatted time string (if time-based: UUID v1, v6, v7, NULID)
• timestamp: Object with precision ("ms" or "ns") and value
• randomness: Random component as decimal string (if applicable)
• hex: Full ID as hex string
• bytes: Full ID as colon-separated hex bytes

get_available_formats()

Returns all available ID format names.

Enums

IdFormat

• UuidV1 = 0 - UUID version 1 (time-based with MAC address)
• UuidV4 = 1 - UUID version 4 (random)
• UuidV6 = 2 - UUID version 6 (time-ordered for database locality)
• UuidV7 = 3 - UUID version 7 (time-based, millisecond precision)
• UuidV8 = 4 - UUID version 8 (custom/experimental)
• Nulid = 5 - NULID (nanosecond-precision ULID)
• NanoId = 6 - NanoID (URL-friendly, cryptographically secure)

IdCase

• Lower = 0 - Lowercase output
• Upper = 1 - Uppercase output

ID Format Details

UUID v1

• Time-based UUID with MAC address
• 36 characters (with hyphens)
• Includes timestamp and MAC address (privacy concern)
• Example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

UUID v4

• Randomly generated 128-bit UUID
• 36 characters (with hyphens)
• Example: 550e8400-e29b-41d4-a716-446655440000

UUID v6

• Time-ordered UUID for better database index locality
• 36 characters (with hyphens)
• Similar to UUID v1 but with reordered bytes
• Example: 0166e6b8-9dad-7b80-80b4-00c04fd430c8

UUID v7

• Time-ordered UUID with Unix timestamp (milliseconds)
• 36 characters (with hyphens)
• Sortable by generation time
• Example: 018e1234-5678-7abc-8def-0123456789ab

UUID v8

• Custom format for experimental use
• 36 characters (with hyphens)
• No specific structure enforced
• Example: 123e4567-e89b-87c5-d012-3456789abcdef

NULID

• Nanosecond-precision lexicographically sortable ID
• 26 characters (Crockford Base32)
• Sortable by generation time with nanosecond precision
• Example: 01hny0qzcw8a5v8z7g6f4d2b9j

NanoID

• URL-friendly, cryptographically secure random ID
• Uses unreserved URL characters (A-Za-z0-9_-)
• Default length: 21 characters
• Example: NVUp3WKdn2KwW-8S8XYz

License

MIT