Zero-dependency, TypeScript-first, cryptographically secure ID generation toolkit for Node.js (v1)

✨ Features

• randomId for flexible crypto-safe IDs
• shortId for compact base62 IDs
• secureId for high-entropy identifiers
• incrementalId for in-memory counters
• createIncrementalIdGenerator for isolated sequences
• uuidV4 for RFC 4122 v4 UUIDs
• nanoId for NanoID-style IDs
• generateJWTSecret for JWT signing secrets
• withPrefix for consistent prefixes
• Zero runtime dependencies
• Crypto-secure randomness only
• TypeScript-first with strict types
• ESM + CJS builds

📦 Installation

npm install hyperid

🧰 Requirements

• Node.js 18 or newer.

🧭 Full Usage Guide

This section explains how to use every feature, what you get, and when to use it.

1. Install the package and import the functions you need.
2. Choose the generator based on your use-case.
3. Use prefixes to namespace IDs across environments or domains (e.g., ORD_, USR_).
4. Prefer secureId and generateJWTSecret for security-sensitive values (tokens, secrets).
5. incrementalId is in-memory; it resets when the process restarts.

Quick selection guide:

• randomId: general IDs with flexible length/encoding.
• shortId: compact base62 IDs.
• secureId: high-entropy identifiers and secrets.
• incrementalId: in-memory counters in a single process.
• createIncrementalIdGenerator: isolated sequences (multiple counters).
• uuidV4: standard UUIDs.
• nanoId: NanoID-style IDs with a custom alphabet.
• generateJWTSecret: HMAC JWT secrets (base64url).
• withPrefix: consistent prefixes across your IDs.

🔧 Usage

import {
  randomId,
  shortId,
  secureId,
  incrementalId,
  createIncrementalIdGenerator,
  uuidV4,
  nanoId,
  generateJWTSecret,
  withPrefix,
} from 'hyperid';

const id = randomId();
const hexId = randomId({ length: 32, encoding: 'hex' });
const prefixed = randomId({ prefix: 'ID_' });

const compact = shortId();

const secure = secureId();
const secureBase62 = secureId({ encoding: 'base62', length: 48, prefix: 'SEC_' });

const orderId = incrementalId({ prefix: 'ORD_' });
const userIdGenerator = createIncrementalIdGenerator({ prefix: 'USR_', start: 1000 });
const userId = userIdGenerator();

const uuid = uuidV4();

const nano = nanoId();
const nanoCustom = nanoId({ length: 10, alphabet: 'abcXYZ' });

const jwtSecret = generateJWTSecret();
const shortSecret = generateJWTSecret(32);

const tagged = withPrefix('abc123', 'PRE_');

CommonJS example:

const {
  randomId,
  shortId,
  secureId,
  incrementalId,
  createIncrementalIdGenerator,
  uuidV4,
  nanoId,
  generateJWTSecret,
  withPrefix,
} = require('hyperid');

const id = randomId({ prefix: 'CJS_' });

🔤 Encodings

• hex: lowercase hexadecimal with two characters per byte.
• base62: A-Z, a-z, 0-9 for compact IDs.
• alphanumeric: 0-9, A-Z, a-z for sortable-friendly output.

📖 API Reference

Encoding type: Encoding = 'hex' | 'alphanumeric' | 'base62'.

randomId

Signature: randomId(options?: RandomIdOptions): string

Parameters:

• options: RandomIdOptions (optional).
• options.length: number (default: 16). Output length in characters.
• options.encoding: Encoding (default: 'base62'). Output encoding.
• options.prefix: string (default: ''). Prefix to prepend.

Returns: string

Example:

const id = randomId({ length: 24, encoding: 'alphanumeric', prefix: 'ID_' });

shortId

Signature: shortId(options?: { prefix?: string }): string

Parameters:

• options: { prefix?: string } (optional).
• options.prefix: string (default: ''). Prefix to prepend.

Returns: string

Example:

const id = shortId({ prefix: 'S_' });

secureId

Signature: secureId(options?: SecureIdOptions): string

Parameters:

• options: SecureIdOptions (optional).
• options.length: number (default: 32). Output length in characters.
• options.encoding: Encoding (default: 'hex'). Output encoding.
• options.prefix: string (default: ''). Prefix to prepend.

Returns: string

Example:

const token = secureId({ length: 64, encoding: 'hex' });

createIncrementalIdGenerator

Signature: createIncrementalIdGenerator(options?: IncrementalIdOptions): () => string

Parameters:

• options: IncrementalIdOptions (optional).
• options.prefix: string (default: ''). Prefix to prepend.
• options.start: number (default: 1). Starting counter value.

Returns: () => string

Example:

const generator = createIncrementalIdGenerator({ prefix: 'USR_', start: 500 });
const id = generator();

incrementalId

Signature: incrementalId(options?: IncrementalIdOptions): string

Parameters:

• options: IncrementalIdOptions (optional).
• options.prefix: string (default: ''). Prefix to prepend.
• options.start: number (default: 1). Initial counter when a prefix is first seen.

Returns: string

Example:

const first = incrementalId({ prefix: 'ORD_' });
const second = incrementalId({ prefix: 'ORD_' });

uuidV4

Signature: uuidV4(): string

Parameters: none

Returns: string

Example:

const id = uuidV4();

nanoId

Signature: nanoId(options?: NanoIdOptions): string

Parameters:

• options: NanoIdOptions (optional).
• options.length: number (default: 21). Output length.
• options.alphabet: string (default: base62 alphabet). Character set.

Returns: string

Example:

const id = nanoId({ length: 12 });

generateJWTSecret

Signature: generateJWTSecret(length?: number): string

Parameters:

• length: number (default: 64). Number of random bytes.

Returns: string

Example:

const secret = generateJWTSecret(48);

withPrefix

Signature: withPrefix(id: string, prefix: string): string

Parameters:

• id: string. Base identifier.
• prefix: string. Prefix to prepend.

Returns: string

Example:

const tagged = withPrefix('abc123', 'PRE_');

🔒 Security

• All randomness is generated using crypto.randomBytes or crypto.randomUUID.
• No Math.random usage anywhere in the library.
• Suitable for security-sensitive identifiers such as tokens, secrets, and session IDs.

⚡ Performance

• Synchronous APIs for predictable performance and simplicity.
• Benchmarks are coming soon.

✅ Tested Results

Test suite executed with:

npx tsx --test tests/*.test.ts

Summary:

• tests: 38
• suites: 9
• pass: 38
• fail: 0

Excerpt:

✔ createIncrementalIdGenerator
✔ incrementalId
✔ randomId
✔ shortId
✔ secureId
✔ uuidV4
✔ nanoId
✔ generateJWTSecret
✔ withPrefix

Build output:

CJS dist/index.cjs     2.62 KB
ESM dist/index.js      2.03 KB
DTS dist/index.d.ts    4.04 KB

📌 Feature Outputs (What You Get)

• randomId() -> 16-char base62 string (configurable length/encoding/prefix).
• shortId() -> 8-char base62 string (compact IDs).
• secureId() -> 32-char hex string (minimum 32 bytes entropy).
• incrementalId({ prefix: 'ORD_' }) -> ORD_1, ORD_2, ... (per-prefix counters).
• createIncrementalIdGenerator() -> isolated sequence (no shared state).
• uuidV4() -> RFC 4122 v4 UUID string.
• nanoId() -> 21-char base62-style string (custom alphabet supported).
• generateJWTSecret() -> base64url-encoded secret string.
• withPrefix('abc', 'PRE_') -> PRE_abc.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a pull request.