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