distid
Version:
Distributed ID generator for large-scale systems
116 lines (78 loc) • 4 kB
Markdown
# DistId
  
A lightweight, distributed ID generator designed for large-scale systems. DistId generates unique 64-bit IDs with built-in timestamp, node identifier, and counter, making it ideal for distributed environments where collision resistance and indexing performance are critical.
## Why DistId?
- **Efficient Indexing**: IDs are time-ordered, reducing fragmentation in database indexes (e.g., B-tree).
- **Scalable**: Supports up to 1024 nodes, generating millions of IDs per second.
- **Compact**: 64-bit IDs (8 bytes), smaller than UUID (16 bytes) or CUID (25+ bytes).
- **Flexible Formats**: Output as `number`, `hex`, `base36`, or `base62`.
- **TypeScript Support**: Fully typed with TypeScript for a better developer experience.
## Features
- Generates 64-bit IDs with timestamp (41 bits), nodeId (10 bits), and counter (12 bits, configurable).
- Collision-resistant across distributed nodes.
- Supports multiple output formats: `number`, `hex`, `base36`, `base62`.
- Customizable epoch, counter bits, and logging.
- Lightweight with zero dependencies.
## Installation
Install DistId via npm:
```bash
npm install distid
```
## Usage
Here's a quick example to get started:
```ts
import { DistIdGenerator } from 'distid';
// Initialize with a nodeId (0-1023)
const gen = new DistIdGenerator({ nodeId: 5 });
// Generate IDs in different formats
console.log(gen.generate('hex')); // e.g., "13a8f5c00050007b"
console.log(gen.generate('base62')); // e.g., "1Qz5X0K"
console.log(gen.generate('number')); // e.g., 1412894000743680005n
```
## Configuration
You can customize the generator with the following options:
|Option |Description |Default |
|:--------------|:---------------------------------------|:-------------|
|`nodeId` |Node identifier (0-1023). |Required |
|`epoch` |Custom epoch timestamp (in ms). |2020-01-01 |
|`counterBits` |Number of bits for the counter (8-20). |12 |
|`logger` |Custom logging function for debugging. |Console logger|
Example with custom configuration:
```ts
const gen = new DistIdGenerator({
nodeId: 5,
epoch: new Date('2023-01-01').getTime(),
counterBits: 10,
logger: (msg) => console.log(`[Custom] ${msg}`),
});
console.log(gen.generate('base36')); // e.g., "1h3k5l0k5"
```
## API Reference
`DistIdGenerator`
#### Constructor
```ts
new DistIdGenerator(config: DistIdConfig)
```
* `config`: Configuration object (see above).
`generate(format?: DistIdFormat): string | bigint`
Generates a unique ID in the specified format.
* `format`: Output format (`'number'`, `'hex'`, `'base36'`, `'base62'`). Default: `'number'`.
* Returns: A unique ID as a `bigint` (for `'number'`) or `string` (for other formats).
`DistIdGenerator.resetNodeIds(): void`
Resets the internal node ID tracking (useful for testing).
## Performance
DistId is designed for high performance in distributed systems. Here's a quick benchmark compared to UUID and CUID (run on Node.js v18):
|Generator|Size (bytes)|IDs/sec (millions)|Index Fragmentation|
|:--------|:-----------|:-----------------|:------------------|
|DistId |8 |4.2 |Low (time-ordered) |
|UUID v4 |16 |3.8 |High (random) |
|CUID |25 |3.5 |Medium |
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/nhanlethanh1198/distid).
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m "Add your feature"`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a pull request.
## License
This project is licensed under the MIT License. See the LICENSE file for details.