npm package: @onurege3467/zero-id
Description: Comprehensive TypeScript ID generation library with 30+ formats
Latest version: 1.0.0

# Zero-ID

A comprehensive TypeScript ID generation library with 30+ formats. Zero dependencies, browser and Node.js compatible, fully typed.

## Features

- **30+ ID Formats**: UUID, NanoID, ULID, KSUID, Snowflake, CUID, and more
- **Zero Dependencies**: Uses native crypto APIs only
- **TypeScript First**: Full type safety with strict mode
- **Tree-Shakeable**: Import only what you need
- **Browser & Node**: Works everywhere
- **Fast**: Optimized for performance
- **Secure**: Cryptographically secure random generation

## Installation

```bash
npm install zero-id
```

## Quick Start

```typescript
import { id } from 'zero-id';

// UUID v4 (random)
id.uuid.v4(); // '550e8400-e29b-41d4-a716-446655440000'

// UUID v7 (time-sortable)
id.uuid.v7(); // '018f1b4e-7b4e-7b4e-7b4e-7b4e7b4e7b4e'

// NanoID (URL-safe)
id.nanoid(); // 'V1StGXR8_Z5jdHi6B-myT'

// ULID (sortable)
id.ulid(); // '01ARZ3NDEKTSV4RRFFQ69G5FAV'

// MongoDB ObjectId
id.objectid(); // '507f1f77bcf86cd799439011'

// Short ID
id.short(); // 'a3fK9z'

// Token
id.token(); // Secure random token
```

## ID Formats

### UUID Family

```typescript
// All UUID versions
id.uuid.v1();  // Time + MAC based
id.uuid.v3('name', id.uuid.namespaces.DNS);  // MD5 namespace
id.uuid.v4();  // Random (most common)
id.uuid.v5('name', id.uuid.namespaces.DNS);  // SHA1 namespace
id.uuid.v6();  // Reordered v1 (sortable)
id.uuid.v7();  // Time-sortable (modern, recommended)

// Validation
id.uuid.validate('550e8400-e29b-41d4-a716-446655440000');
id.uuid.parse('550e8400-e29b-41d4-a716-446655440000'); // Uint8Array
```

### Short & URL-Safe

```typescript
// NanoID (default: 21 chars, URL-safe)
id.nanoid();
id.nanoid(10);  // Custom length
id.nanoid(10, 'abc');  // Custom alphabet

// Short ID (default: 7 chars)
id.short();
id.short(8, 'ABC123');  // Custom length and alphabet

// Base encodings
id.base32();   // Crockford base32
id.base58();   // Bitcoin base58
id.base62();   // 0-9a-zA-Z
id.base64();   // Standard base64
id.base64url(); // URL-safe base64
```

### Sortable / Database IDs

```typescript
// ULID (26 chars, lexicographically sortable)
id.ulid();
id.ulidMonotonic();  // Same-ms ordering guarantee

// KSUID (27 chars, K-sortable)
id.ksuid();

// Twitter Snowflake (distributed)
id.snowflake();

// Sonyflake (Sony's version)
id.sonyflake();

// Discord Snowflake
id.discordflake();

// MongoDB ObjectId
id.objectid();
id.objectidBytes();  // Uint8Array

// Firebase PushID
id.pushid();

// Ordered UUID (database-optimized)
id.ordered();

// COMB GUID (SQL Server optimized)
id.comb();
```

### Secure / Collision-Resistant

```typescript
// CUID (classic)
id.cuid();      // 25 chars
id.cuidSlug();  // Shorter version

// CUID2 (improved)
id.cuid2();           // Default 24 chars
id.cuid2(32);         // Custom length
```

### Platform-Style

```typescript
// Stripe-style IDs
id.stripe('cus');     // cus_xxx
id.stripe('prod');    // prod_xxx
id.stripe('price');   // price_xxx

// Convenience methods
id.stripeCustomer();   // cus_xxx
id.stripeProduct();    // prod_xxx
id.stripePrice();      // price_xxx
```

### Hash-Based

```typescript
// MD5 hash (32 hex chars)
id.md5('data');

// SHA1 hash (40 hex chars)
id.sha1('data');

// SHA256 hash (64 hex chars)
id.sha256('data');
id.sha256('data', 16);  // Truncated to 16 chars

// Generic hash
id.hash('data', 'sha256');
```

### Tokens & Secrets

```typescript
// API token
id.token();           // 32 chars, URL-safe
id.token(64);         // Custom length

// Secret key
id.secret();          // 64 chars, high entropy

// Password
id.password();        // 16 chars, mixed
id.password(20);      // Custom length

// Pronounceable
id.pronounceable();   // Consonant-vowel pattern

// Memorable passphrase
id.memorable();       // 4 words, e.g., 'correct-horse-battery-staple'
id.memorable(3, '_'); // 3 words with underscore

// Character-specific
id.numeric(6);        // Digits only
id.alphabetic(8);     // Letters only
id.safe(10);          // No confusing chars (0, O, 1, I, l)
```

### Timestamp-Based

```typescript
// Timestamp with random suffix
id.timestamp();                              // 1704067200000_a3fK
id.timestamp({ prefix: 'order' });           // order_1704067200000_a3fK
id.timestamp({ format: 'iso' });             // ISO 8601 format

// ISO 8601
id.iso();  // '2024-01-01T00:00:00.000Z'

// Unix epoch
id.epoch();  // '1704067200000'

// Sequential
id.sequence('item');  // item1, item2, item3...
```

### Custom Builder

```typescript
// Create custom ID generator
const orderId = id.custom({
  prefix: 'order',
  separator: '_',
  length: 12,
  timestamp: true,
  format: 'base62',
});

orderId();  // 'order_1704067200000_a3fK9zXqWmP'

// Pre-configured builders
const prefixed = id.customPrefixed('user', 8);
const timestamped = id.customTimestamped('log');
const numeric = id.customNumeric(10);
const safe = id.customSafe(16);
```

## Validation

```typescript
// Validate any format
id.validate.uuid('550e8400-e29b-41d4-a716-446655440000');
id.validate.ulid('01ARZ3NDEKTSV4RRFFQ69G5FAV');
id.validate.nanoid('V1StGXR8_Z5jdHi6B-myT');

// Type checking
id.validate.isUUID(str);
id.validate.isULID(str);
id.validate.isObjectId(str);
id.validate.isCUID(str);
id.validate.isSnowflake(str);
```

## Decoding

```typescript
// Extract information from IDs
id.decode.ulid('01ARZ3NDEKTSV4RRFFQ69G5FAV');
// { timestamp: 1469918176385, random: 'EKTSV4RRFFQ69G5F' }

id.decode.ksuid('0ujtsYcgvSTl8PAuAdqWYSMnLOv');
// { timestamp: 1469918176, payload: Uint8Array }

id.decode.snowflake('1234567890123456789');
// { timestamp, workerId, datacenterId, sequence }

id.decode.objectid('507f1f77bcf86cd799439011');
// { timestamp, machineId, processId, counter }
```

## Utilities

```typescript
// Random bytes
id.randomBytes(16);  // Uint8Array

// Current timestamp
id.now();  // Unix timestamp in ms

// Epochs
id.epochs.UNIX;      // 0
id.epochs.TWITTER;   // 1288834974657
id.epochs.DISCORD;   // 1420070400000

// Hex encoding
id.hex(new Uint8Array([1, 2, 3]));  // '010203'
id.hexDecode('010203');  // Uint8Array
```

## Tree-Shaking

Import only what you need:

```typescript
// Import specific generators
import { uuidv4, nanoid, ulid } from 'zero-id';

uuidv4();
nanoid();
ulid();
```

## Plugins

### Zero-Helper

```typescript
import { useIdGenerator } from 'zero-id/plugins/zero-helper';
import { id } from 'zero-id';

useIdGenerator(zh, {
  table: 'users',
  column: 'id',
  generator: id.uuid.v7,
});
```

### Zero-Queue

```typescript
import { useQueueIdGenerator } from 'zero-id/plugins/zero-queue';
import { id } from 'zero-id';

useQueueIdGenerator(queue, id.ulid);
```

## Benchmarks

```bash
npm run benchmark
```

## License

MIT