Fast, timestamp-based, collision-safe unique ID generator with variable Base62 length (21–36 chars)
npm install 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.
---
- 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
---
| 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
---
``bash`
npm install chronoid
Requires Node.js v18+.
---
`ts
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
`
---
ChronoID generates the ID using:
`
Base62(timestamp) + Base62(machineId) + Base62(counter) + random padding (optional)
| 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)
---
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+
---
`ts`
createChronoId(1, 21); // dWx9BoCbE11pxKRUg7v
createChronoId(1, 36); // dWx9BoCbE11pxKRUg7vXREMu12Gp0skCFTL
---
`bash`
npm install
npm test
---
`bash`
npm install
`bash`
npm run build
`bash`
npm run test
> Uses Jest and ts-jest for testing
`bash`
npm run lint
---
`
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
---
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.
---
Pull requests are welcome! To contribute:
1. Fork the repo
2. Create your feature branch (git checkout -b feature/my-feature)git commit -am 'Add feature'
3. Commit your changes ()git push origin feature/my-feature`)
4. Push to the branch (
5. Open a pull request
---
EUPL-1.2 © 2025 [Tenforward AB]
---
Feel free to open an issue or drop me a message.