English | 中文

Milkid is a highly customizable distributed unique ID generator written in TypeScript.

JavaScript has many excellent distributed unique ID generators, but they mainly target specific scenarios and cannot be freely customized.

• For database primary keys, we need lexicographically ordered IDs to avoid database fragmentation
• For distributed systems, we need IDs to be as uniform as possible to prevent hotspots
• For news websites, we want completely random IDs in URLs to prevent crawler traversal
• For short URL services, we need IDs in URLs to be as short as possible

Milkid allows high customization to meet different ID requirements across scenarios.

nanoid - A tiny, fast unique string ID generator.
ulid - A lexicographically sortable unique string ID generator.
cuid2 - A more security-considerate unique ID generator.

Python - kawaiior

npm i milkid

const idGenerator = defineIdGenerator({
  length: 24,
  timestamp: true,
  sequential: true,
});

console.log(idGenerator.createId()); // 0UgBwxhJyuWVA9o1YFVxAtaL

When using generated IDs as database primary keys, it's best to have incrementally ordered IDs. Using unordered generators like UUID could cause frequent splitting and merging of database index leaf nodes.

Placing millisecond-level timestamps at the beginning of IDs naturally ensures ordering. The millisecond precision also effectively reduces collision probability - no duplicates will occur unless two IDs are generated within the same millisecond.

Enable this feature by setting the timestamp option to true.

While we can't strictly guarantee insertion order like database auto-increment keys, we can approximate it. With timestamps enabled, we achieve intra-millisecond ordering. Setting sequential: true adds auto-increment within the same millisecond and process to further ensure sequence.

By default, Milkid generates 24-character IDs. With timestamps enabled, there's a 1% probability of collision only after generating 243 trillion IDs within the same millisecond.

Here are recommended configurations for common scenarios:

Enable both timestamp and sequential to ensure ordered IDs and prevent fragmentation.

Note ⚠️ Milkid uses case-sensitive characters. Ensure the database uses case-sensitive collation (e.g., utf8mb4_bin) for primary keys to maintain sort order during bulk inserts.

const idGenerator = defineIdGenerator({
  length: 24,
  timestamp: true,
  sequential: true,
});

Disable both options to ensure uniform ID distribution and avoid hotspots.

const idGenerator = defineIdGenerator({
  length: 24,
  timestamp: false,
  sequential: false,
});

Minimize ID length for compact URLs:

const idGenerator = defineIdGenerator({
  length: 6,
  timestamp: false,
  sequential: false,
});