@ingestkorea/util-sortable-id

A lightweight, distributed, zero-dependency and sortable 64-bit ID generator for Node.js.

Installing

npm install @ingestkorea/util-sortable-id

Getting Started

import { SortableIDClient } from "../index.js";

// 재사용 가능
const client = new SortableIDClient({
  shardId: 1000, // (optional) 기본값: 1,000
  randomSequence: true, // (optional) 기본값: true / 동일 밀리초 내에서는 순서 보장
});

// 테스트
const delay = (ms: number) => new Promise((res) => setTimeout(res, ms));

(async () => {
  for (let i = 0; i < 5; i++) {
    const uuid = client.generate();

    const parsed = client.parse(uuid);

    console.log(JSON.stringify({ try: i, uuid, ...parsed }));

    await delay(500); // (optional)
  }
})();

# 500ms 딜레이 포함 (랜덤성 위해 무작위 시작 시퀀스 활성화 / 기본적으로 정렬 순서 보장됨)
{"try":0,"uuid":"024ee4ebe90fa0b7","timestamp":"2026-08-18T11:32:00.082Z","shardId":1000,"sequence":183}
{"try":1,"uuid":"024ee4ece58fa017","timestamp":"2026-08-18T11:32:00.587Z","shardId":1000,"sequence":23}
{"try":2,"uuid":"024ee4ede00fa29d","timestamp":"2026-08-18T11:32:01.088Z","shardId":1000,"sequence":669}
{"try":3,"uuid":"024ee4eeda8fa2f8","timestamp":"2026-08-18T11:32:01.589Z","shardId":1000,"sequence":760}
{"try":4,"uuid":"024ee4efd58fa11c","timestamp":"2026-08-18T11:32:02.091Z","shardId":1000,"sequence":284}

# 딜레이 미포함 (랜덤성 위해 무작위 시작 시퀀스 활성화 / 동일 밀리초 내에서도 정렬 순서 보장됨)
{"try":0,"uuid":"024ee803470fa1bd","timestamp":"2026-08-18T11:38:45.262Z","shardId":1000,"sequence":445}
{"try":1,"uuid":"024ee803488fa06f","timestamp":"2026-08-18T11:38:45.265Z","shardId":1000,"sequence":111}
{"try":2,"uuid":"024ee803488fa070","timestamp":"2026-08-18T11:38:45.265Z","shardId":1000,"sequence":112}
{"try":3,"uuid":"024ee803488fa071","timestamp":"2026-08-18T11:38:45.265Z","shardId":1000,"sequence":113}
{"try":4,"uuid":"024ee803488fa072","timestamp":"2026-08-18T11:38:45.265Z","shardId":1000,"sequence":114}

License

This Utility is distributed under the MIT License, see LICENSE for more information.