uniqigen

Cryptographically secure unique ID generator — configurable length, multiple formats, zero duplicates.

Better than UUID when you need short, custom-length identifiers that never collide.

Why uniqigen over UUID?

| Feature | UUID v4 | uniqigen | |---------|---------|----------| | Length | Fixed 36 chars | You choose (6, 10, 20...) | | Format | Hex + dashes | Numeric, alphanumeric, hex, base62 | | Sortable | No | Yes (generateSortable) | | Duplicate guarantee | Probabilistic | Built-in registry (createUniqueGenerator) | | Short OTP / order numbers | Awkward | Native (generateNumber(6)) |

Install

npm install uniqigen

Quick Start

import { generateNumber, generate, createUniqueGenerator } from "uniqigen";

// 6-digit random number (OTP, PIN, short code)
const otp = generateNumber(6);        // "482917"

// 10-char alphanumeric ID
const orderId = generate({ length: 10 });  // "kR3mP9xL2n"

// Guaranteed unique — never repeats in your app
const gen = createUniqueGenerator({ length: 8, charset: "numeric" });
const ticket1 = gen.next();  // "38472910"
const ticket2 = gen.next();  // "10293847" — always different

API

generate(options?)

Main generator with full control.

generate({ length: 10 })                          // default alphanumeric
generate({ length: 6, charset: "numeric" })       // "482917"
generate({ length: 12, charset: "hex" })          // hex string
generate({ length: 8, prefix: "USR-" })           // "USR-kR3mP9xL"
generate({ length: 6, customCharset: "ABC123" })  // custom pool

Charsets: "numeric" | "alphanumeric" | "hex" | "base62"

Shortcuts

generateNumber(6)        // "482917"
generateAlphanumeric(10) // "kR3mP9xL2n"
generateHex(32)          // 32-char hex
generateBase62(10)       // URL-safe compact ID
generateSortable(8)      // timestamp + random (sortable)

createUniqueGenerator(options?)

Session-level duplicate prevention — retries automatically if collision detected.

const gen = createUniqueGenerator({ length: 6, charset: "numeric" });

gen.next();    // generate unique ID
gen.count;     // how many generated
gen.has(id);   // check if already used
gen.reset();   // clear registry

Utilities

// How likely is a collision with 1M IDs at length 6?
collisionProbability(6, "numeric", 1_000_000);

// What length do I need for 1M IDs with 1-in-a-billion collision risk?
recommendedLength("alphanumeric", 1_000_000);

Common Use Cases

// E-commerce order number (10 digits)
generateNumber(10);

// Coupon code (8 alphanumeric)
generateAlphanumeric(8);

// Database primary key (URL-safe, 12 chars)
generateBase62(12);

// Sortable log/event ID
generateSortable(6);

// Batch of unique coupon codes
const coupons = createUniqueGenerator({ length: 8, charset: "alphanumeric" });
for (let i = 0; i < 1000; i++) {
  console.log(coupons.next());
}

Security

Uses Node.js crypto.randomBytes — cryptographically secure, not Math.random().

Rejection sampling ensures uniform distribution across all characters (no bias).

License

MIT