@mmbytes/snowgen-id
v1.0.51
Published
# Snowflake ID Generator for TypeScript (snowgen-id)
Downloads
4
Maintainers
Readme
Snowflake ID Generator for TypeScript (snowgen-id)
snowgen-id is a TypeScript library for generating unique IDs based on the Snowflake algorithm. It provides a customizable and efficient way to generate 64-bit IDs using components such as timestamp, worker ID, datacenter ID, and sequence number.
Disclaimer: This library takes heavy inspiration from the rakheyl/snowflake-uuid project, but it has been rewritten to fit specific use cases.
Features
- Customizable bit lengths for worker ID, datacenter ID, and sequence to accommodate various scaling needs.
- Built-in protection against clock going backwards.
- Ability to parse generated IDs to extract timestamp, worker ID, datacenter ID, and sequence number.
- Independent parser function for parsing IDs without creating a worker instance.
Installation
To install snowgen-id, use the following command:
bun add @mmbytes/snowgen-id
You can also use your preferred package manager:
npm i @mmbytes/snowgen-id
pnpm i @mmbytes/snowgen-id
Usage
Import the createWorker
function from the library and initialize it with your worker and datacenter IDs, along with optional configuration options.
import { createWorker } from "@mmbytes/snowgen-id";
// Initialize the worker with worker ID and datacenter ID
const worker = createWorker(0n, 1n);
// Generate a new ID
const newId = worker.nextId();
console.log(`Generated ID: ${newId}`); // Example output: Generated ID: 1617202485447688192n
// Parse an ID
const parsedId = worker.parse(newId);
console.log(`Parsed ID:`, parsedId);
// Example output:
// Parsed ID: {
// timestamp: 1617202485447n,
// workerId: 0n,
// datacenterId: 1n,
// sequence: 0n
// }
You can also use the independent parseId
function to parse IDs without creating a worker instance:
import { parseId } from "@mmbytes/snowgen-id";
const id = user.id // your table row id
console.log(`Parsed ID:`, parseId(id));
// Example output:
// Object: {
// timestamp: 1617202485447n,
// workerId: 0n,
// datacenterId: 1n,
// sequence: 0n
// }
API Reference
Create a new worker instance capable of generating and parsing unique IDs.
createWorker(workerId: bigint, datacenterId: bigint, options?: WorkerOptions)
Parameters:
workerId
: Unique ID of the worker node.datacenterId
: Unique ID of the data center.options
: Optional configuration for ID generation.
Returns
An object with the following methods:
nextId()
: Generates a new unique ID.parse(bigint)
: Parses a given ID into its components.getCurrentSequence()
: Returns the current sequence number.getLastTimestamp()
: Returns the last timestamp used for ID generation.
parseId(id: bigint, options?: WorkerOptions)
Parses a given ID into its components.
Parameters
id
: The ID to parse.options
: Optional configuration for parsing the ID.
Returns
An object representing the parsed ID components:
timestamp
: The timestamp component of the ID.workerId
: The worker ID component of the ID.datacenterId
: The datacenter ID component of the ID.sequence
: The sequence number component of the ID.
WorkerOptions
Configuration options for the ID generator.
epoch
: The epoch start time for the timestamp component of the ID. Default is1609459200000n
(January 1, 2021).workerIdBits
: Number of bits allocated for the worker ID. Default is5
.datacenterIdBits
: Number of bits allocated for the datacenter ID. Default is5
.sequenceBits
: Number of bits allocated for the sequence number. Default is12
.
Contributing
Contributions are welcome! Please feel free to submit a pull request.