Getting Started with @readytools/id

@readytools/id is a comprehensive, enterprise-grade identification toolkit designed for modern web applications, distributed backend services, and high-throughput database systems. It delivers full implementations of industry-standard identifiers (UUID v1/v4/v5/v7, NanoID, ULID, CUID2, Twitter Snowflake, Stripe-style Smart Prefixes, and cryptographically secure tokens) in a lightweight, tree-shakeable package with zero external dependencies.

Key Advantages

• Zero Dependencies: Pure modern JavaScript / TypeScript without third-party baggage or bloated supply chain risks.
• Web Crypto Powered: Employs the native Web Crypto API (crypto.getRandomValues, crypto.randomUUID) across modern runtimes for cryptographically secure randomness.
• B-Tree Database Optimized: Native support for time-ordered identifiers (UUIDv7, ULID, Snowflake) that eliminate index fragmentation in PostgreSQL, MySQL, SQLite, and MongoDB.
• Universal Runtime Compatibility: Seamlessly runs on Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge Runtime, and modern browsers.
• Complete Toolset: Includes built-in binary conversion (16-byte buffers), validation, timestamp extractors, case formatters, collision probability calculators, and deterministic test mocking.

Installation

Install the package from npm via your package manager of choice:

npm install @readytools/id
# or
pnpm add @readytools/id
# or
yarn add @readytools/id
# or
bun add @readytools/id

Quick Start

All functions are exported as individual named exports to facilitate tree-shaking, alongside a default object containing all utilities:

import { uuidv7, nanoId, ulid, smart, generateToken, cuid2, snowflake } from '@readytools/id';

// Index-friendly time-ordered UUID for database primary keys
const userId = uuidv7(); 
// e.g. "018f6f89-8d2a-7140-9a3b-586b9e248b11"

// Compact, URL-safe ID for public resources
const fileKey = nanoId();
// e.g. "V1StGXR8_Z5jdHi6B-myT"

// Stripe-style prefixed resource ID
const customerId = smart('cus');
// e.g. "cus_9xK1mQpLs2Nv"

// Lexicographically sortable 26-char Crockford Base32 ID
const eventId = ulid();
// e.g. "01ARZ3NDEKTSV4RRFFQ69G5FAV"

// 64-bit time-ordered Snowflake integer string
const tweetId = snowflake(1);
// e.g. "176283920194857216"

// Cryptographically secure 256-bit API key
const apiKey = generateToken(32, 'base64url');
// e.g. "a8F3_k9xL2m-Qp0vR7sT1wX4yZ9bC3dE"

Command Line Interface (CLI)

@readytools/id includes a zero-install CLI that allows developers and DevOps scripts to generate IDs directly in bash or terminal pipelines via npx:

# Generate a time-ordered UUIDv7
npx @readytools/id uuidv7

# Generate a Stripe-style smart ID
npx @readytools/id smart usr

# Generate a standard NanoID
npx @readytools/id nanoid

# Generate a 32-byte secure token
npx @readytools/id token

# Calculate collision risk for 1,000,000 IDs (alphabet: 64, length: 21)
npx @readytools/id risk 64 21 1000000

Identifier Selection Matrix

Use the following decision matrix to choose the ideal identifier format for your specific architecture:

Runtime Compatibility

• Node.js: >= 18.0.0 (Native crypto.webcrypto and globalThis.crypto)
• Browsers: All modern browsers supporting Web Cryptography API (Chrome, Safari, Firefox, Edge)
• Edge Runtimes: Cloudflare Workers, Vercel Edge, Fastly Compute@Edge
• Alternative Runtimes: Bun >= 1.0.0, Deno >= 1.30.0