npm package: @kakilangit/id-generator
Description: WebAssembly bindings for ID Generator tool
Latest version: 0.3.0

# @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

```bash
npm install @kakilangit/id-generator
```

## Usage

```javascript
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