@readytools/id
v1.0.6
Published
Ultra-fast, cryptographically secure, zero-dependency ID and token generator for Enterprise use.
Maintainers
Readme
📚 Documentation
Official and comprehensive documentation is available at: 👉 id | ReadyTools Docs
🌟 Why @readytools/id?
The JavaScript ecosystem is fragmented. You use uuid for databases, nanoid for URLs, and cuid2 for distributed systems.
@readytools/id is the all-in-one replacement that solves real-world enterprise problems without bloating your node_modules.
- 🚀 Ultra-Fast & Fully Tree-Shakable: Highly optimized bitwise operations with strict Named Exports (
import { uuidv7 }). Your bundler (Webpack, Vite, Rollup) will only bundle the exact generators you use, keeping your app size tiny. - 🛡️ Enterprise Security: Exclusively uses the Native Web Crypto API (
crypto.randomUUID,crypto.getRandomValues). The vulnerableMath.randomis strictly forbidden. - 📦 Zero Dependencies (The Ultimate Drop-In Replacement): Replaces
uuid,nanoid,cuid, andulidpackages entirely. Protects your project against supply-chain attacks. - 🔋 Batteries Included: UUIDv4, UUIDv7, ULID, CUID2, NanoID, Snowflake, and Smart IDs all in one place.
- 🛠️ Real-World Solutions: Built-in test mocking (no more flaky Jest snapshots), DB binary converters (
BINARY(16)), and mathematical collision risk calculators. - 🌍 Edge Ready: Works out-of-the-box in Node.js (18+), React, Next.js, Deno, Bun, Cloudflare Workers, Vercel Edge, and Browsers.
- 🤖 AI / LLM Friendly Context: Built with strict TypeScript typings, deterministic tests, and predictable naming conventions, making it the perfect ID package for AI-assisted coding (Copilot, ChatGPT, Claude).
📦 Installation
npm install @readytools/id
# or
pnpm add @readytools/id
# or
yarn add @readytools/id🚀 Quick Start & Generators
💾 Database Optimized (UUIDv7 & ULID)
Random UUIDs (v4) cause massive B-Tree index fragmentation in Postgres and MySQL. UUIDv7 and ULID solve this by being chronologically sortable.
import { uuidv7, ulid } from '@readytools/id';
const uid = uuidv7(); // "01917f9b-6b80-71a2-8b9a-1c8f3b2a4d5e"
const u = ulid(); // "01M0PSE3E250JQT8AVKQQ71XDX"🌐 URL-Friendly & Client-Side (NanoID & CUID2)
Need short, secure, and URL-friendly IDs for public links?
import { nanoId, cuid2 } from '@readytools/id';
const nid = nanoId(); // "V1StGXR8_Z5jdHi6B-myT"
const cid = cuid2(); // "oyx0325cv6x4vqlsja5s7yd8"🧠 Smart IDs (Stripe-style Prefixing)
Domain-prefixed IDs make debugging logs and APIs infinitely easier.
import { smart } from '@readytools/id';
const userId = smart('usr');
// "usr_7eto6037Z-N5JDsBKKVYl"
const invoiceId = smart('inv', { date: true });
// "inv_20260823_6mY686gs0CYsJnxzeuG90"🔑 API Keys & Tokens
Generate cryptographically secure secrets.
import { generateToken } from '@readytools/id';
// 32-byte Base64URL string
const token = generateToken(32, 'base64url'); 🛠️ Enterprise Tooling (The "Real-World" Fixes)
1. Deterministic Testing (Mocking)
Stop writing complex Jest/Vitest mocks for random IDs. Seed the generator so your snapshot tests never fail unpredictably.
import { seed, resetMocks, uuidv4 } from '@readytools/id';
seed(12345); // PRNG is now deterministic
const a = uuidv4(); // Will always be the exact same value for this seed
// ... run your tests ...
resetMocks(); // Restores the secure Web Crypto generator2. Database Storage Optimizer (BINARY(16))
Storing a 36-character UUID string is slow and wastes space. Convert it to a 16-byte array for optimal BINARY(16) column storage.
import { uuidv7, toBinary, fromBinary } from '@readytools/id';
const binary = toBinary(uuidv7()); // Returns Uint8Array(16)
const uuidStr = fromBinary(binary, 'uuid'); // Restores the string3. Collision Risk Calculator
Unsure how long your custom ID should be? Calculate the exact mathematical risk of a collision using the Birthday Paradox.
import { collisionRisk } from '@readytools/id';
// (Alphabet Length, ID Length, Expected Generation Count)
const risk = collisionRisk(64, 21, 1000000); 🔎 Validation & Parsing
Validate IDs, extract timestamps, or check UUID versions without complex regex.
import { isValid, getVersion, extractTimestamp } from '@readytools/id';
isValid('01917f9b-...', 'uuid'); // true
getVersion('01917f9b-...'); // 7
extractTimestamp('01M0PSE3E250JQT8AVKQQ71XDX', 'ulid'); // Returns Date object⌨️ CLI Usage
Generate IDs or calculate collision risks directly from your terminal:
npx @readytools/id uuidv7
npx @readytools/id smart usr
npx @readytools/id risk 64 21 1000000⚡ Performance Benchmarks
Tested on Node.js v20 (Ops/sec - Higher is better)
| Generator | Ops/sec | Description |
| :--- | :--- | :--- |
| uuidv4 (native direct) | ~9,180,000 | Native Crypto direct binding (13M+ on Node 24) |
| uuidv1 | ~3,890,000 | Time and MAC-based |
| snowflake | ~3,880,000 | 64-bit integer generation |
| nanoId | ~3,870,000 | Zero-allocation, zero modulo bias URL-friendly |
| uuidv7 | ~3,430,000 | Time-sortable UUID for databases |
| generateToken | ~2,670,000 | Cryptographic secret / API key generator |
| cuid2 | ~2,620,000 | Highly secure, 32-bit hashed ID |
| smart | ~2,570,000 | Domain-prefixed Stripe-style IDs |
| ulid | ~2,040,000 | Time-sortable Base32 |
(Run npm run bench to see metrics for your specific machine).
📄 License
MIT © ReadyTools
