Installation

Documentation

@munesoft/idx

A high-performance, zero-dependency ID generation library for Node.js and browsers.

npm install @munesoft/idx

Quick Start

import idx from '@munesoft/idx';

idx()              // 'A7gT2kPqWx'   — random 10-char ID
idx(16)            // 'A7gT2kPqWxB3mNvZ' — custom length
idx.time()         // '0Lzk8f3xA7gT2kPq' — sortable, timestamp-prefixed
idx.readable()     // 'blue-fox-42'  — human-readable
idx.batch(5)       // ['A7gT2k...', 'B2mQ3p...', ...] — bulk generation
idx.meta(id)       // { type, timestamp?, segments?, raw, length }

API

idx(length?: number | options?): string

Generates a random, URL-safe ID using cryptographic randomness.

| Argument | Description | |---|---| | (none) | Returns a 10-character ID | | number | Returns an ID of that exact length | | { length: number } | Same as passing a number |

idx()            // 'A7gT2kPqWx'
idx(6)           // 'A7gT2k'
idx({ length: 20 }) // 'A7gT2kPqWxB3mNvZyC8d'

idx.time(options?): string

Generates a lexicographically sortable ID. The first 8 characters encode the current timestamp in base62, followed by a random segment.

idx.time()                    // '0Lzk8f3xA7gT2kPq'
idx.time({ randomLength: 4 }) // '0Lzk8f3xA7gT'

IDs generated later will always sort after IDs generated earlier:

const a = idx.time();
// wait...
const b = idx.time();
a < b // true — always

Options:

| Option | Type | Default | Description | |---|---|---|---| | randomLength | number | 8 | Length of the random suffix |

idx.readable(options?): string

Generates a human-readable ID in adjective-noun-number format.

idx.readable()  // 'blue-fox-42'
idx.readable()  // 'fast-cloud-7'
idx.readable({ separator: '_' })       // 'cold_river_18'
idx.readable({ maxNumber: 9 })         // 'bold-hawk-3'
idx.readable({
  adjectives: ['happy', 'sad'],
  nouns: ['cat', 'dog'],
})  // 'happy-dog-71'

Options:

| Option | Type | Default | Description | |---|---|---|---| | adjectives | string[] | built-in 50 | Custom adjective list | | nouns | string[] | built-in 50 | Custom noun list | | maxNumber | number | 99 | Max numeric suffix (inclusive) | | separator | string | '-' | Word separator |

idx.batch(count: number, options?): string[]

Generates multiple IDs efficiently in a single call.

idx.batch(10)       // ['A7gT2k...', 'B2mQ3p...', ...] — 10 random IDs
idx.batch(5, 16)    // five 16-char IDs

idx.meta(id: string): MetaResult

Extracts metadata from an ID. Detects the ID type automatically.

idx.meta(idx())
// { type: 'random', raw: 'A7gT2kPqWx', length: 10 }

idx.meta(idx.time())
// { type: 'time', timestamp: 1719000000000, segments: ['0Lzk8f3x', 'A7gT2kPq'], raw: '...', length: 16 }

idx.meta(idx.readable())
// { type: 'readable', segments: ['blue', 'fox', '42'], raw: 'blue-fox-42', length: 11 }

Performance

Benchmarked on Node.js 22, Apple M-class equivalent (1M iterations):

| Method | Throughput | Output | |---|---|---| | idx() | ~1.07M ops/sec | 10 chars | | idx.time() | ~0.77M ops/sec | 16 chars | | idx.readable() | ~2.44M ops/sec | word-word-N | | crypto.randomUUID() | ~1.75M ops/sec | 36 chars (UUID) |

idx() outputs 3.6× shorter IDs than UUID while maintaining collision safety. idx.readable() is the fastest path since it only needs 3 random bytes.

Encoding

All IDs use base62 (0-9A-Za-z) by default — fully URL-safe, no +, /, or = characters. No encoding/escaping needed in URLs, JSON, or databases.

Security

| Use case | Recommendation | |---|---| | Session tokens, API keys | ✅ idx(32) or idx(64) | | Database primary keys | ✅ idx() or idx.time() | | Short links, slugs | ✅ idx(8) | | Human-friendly IDs | ✅ idx.readable() | | Cryptographic secrets | ⚠️ Use crypto.randomBytes() directly |

idx uses crypto.getRandomValues (browser) or crypto.randomBytes (Node.js). It falls back to Math.random only in environments without Web Crypto — this is logged as a warning and should not occur in modern runtimes.

ESM + CJS

@munesoft/idx ships both ESM and CommonJS builds with full TypeScript types.

// ESM
import idx from '@munesoft/idx';

// CJS
const idx = require('@munesoft/idx');

Tree-shaking

Import only what you need:

import { randomId } from '@munesoft/idx';       // just the random generator
import { timeId } from '@munesoft/idx';         // just time-based IDs
import { readableId } from '@munesoft/idx';     // just readable IDs

Project Structure

src/
├── index.ts      — Main API surface
├── random.ts     — Crypto random pool
├── encode.ts     — Base62 encoding with lookup table
├── time.ts       — Timestamp + random ID generation
├── readable.ts   — Human-readable ID generation
└── utils.ts      — Type detection helpers
tests/
benchmarks/