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:

npm install distid

Usage

Here's a quick example to get started:

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:

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

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.

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.