ChronoID

A fast, compact, timestamp-based unique ID generator for Node.js and browser.

ChronoID is a secure, collision-resistant, and time-sortable ID generator built for performance and readability. It combines the precision of epoch-based timestamps with compact Base62 encoding and optional randomness to produce globally unique and sortable identifiers — all without relying on UUIDs.

Features

• Timestamp-based: IDs are chronologically sortable
• Globally unique: Includes machine ID and counter
• Secure: Uses crypto.getRandomValues() or crypto.randomBytes() for entropy
• Compact: Encoded using Base62 (a-zA-Z0-9)
• Custom length: Generates IDs from 21–36 characters
• Tested: Comes with full Jest test coverage
• Works in Node.js 18+ and modern browsers

Why ChronoID over UUIDv4?

| Feature | ChronoID | UUIDv4 | |----------------------|-------------------|-------------------| | Sortable | ✅ Yes (timestamp) | ❌ No | | Readable | ✅ Base62 | ❌ Hexadecimal | | Collision-safe | ✅ Yes | ✅ Yes | | Length | ✅ 21–36 chars | ❌ 36 chars fixed | | Traceable timestamp | ✅ Yes | ❌ No | | Deterministic order | ✅ Yes | ❌ No | | Performance | ⚡️ Fast | ⚡️ Very fast |

ChronoID is ideal when you need both uniqueness and order, such as for:

• Database keys
• Logs
• Events
• Message queues
• Globally distributed systems

Installation

npm install chronoid

Requires Node.js v18+.

Usage

import { createChronoId } from 'chronoid';

// Basic usage
const id = createChronoId(); // e.g. 'dWx9BoCbE11pxKRUg7v'

// Custom machine ID (0–1023)
const idWithMachine = createChronoId(42);

// Custom total length
const idLong = createChronoId(0, 36); // Fixed 36-char ID

How It Works

ChronoID generates the ID using:

Base62(timestamp) + Base62(machineId) + Base62(counter) + random padding (optional)

Components:

| Component | Description | |---------------|---------------------------------------------| | timestamp | Epoch milliseconds (Base62 encoded) | | machineId | Developer-assigned ID per instance/machine | | counter | Monotonic counter to avoid same-ms collision | | random | Extra entropy to reach desired length |

This ensures:

• Sortability (timestamp first)
• Uniqueness (machine + counter)
• Safety (fallback to wait if counter overflows)

ID Length Strategy

The function accepts a totalLength parameter (default: 21, max: 36).

• The first part (timestamp + machine + counter) is typically 12–14 characters
• The rest is filled with secure random Base62 characters to reach your desired total length
• For UUIDv4-level randomness, use totalLength = 28+

Example Output

createChronoId(1, 21); // dWx9BoCbE11pxKRUg7v
createChronoId(1, 36); // dWx9BoCbE11pxKRUg7vXREMu12Gp0skCFTL

Run Tests

npm install
npm test

Development

Install dependencies

npm install

Build

npm run build

Test

npm run test

Uses Jest and ts-jest for testing

Linting (optional)

npm run lint

Project Structure

chronoid/
├── src/                 → Source code
│   └── index.ts         → Main export
├── tests/               → Jest test files
│   └── createChronoId.spec.ts
├── dist/                → Build output
├── jest.config.ts       → Jest config
├── tsconfig.json        → TypeScript config
├── package.json
└── README.md

Browser Support

In browser bundlers (like Vite or Rollup), globalThis.crypto.getRandomValues() will work automatically. Just be sure to polyfill or fallback gracefully if targeting older browsers.

Contributing

Pull requests are welcome! To contribute:

1. Fork the repo
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

License

EUPL-1.2 © 2025 [Tenforward AB]

Feedback / Questions?

Feel free to open an issue or drop me a message.