scru128

SCRU128: Sortable, Clock and Random number-based Unique identifier

SCRU128 ID is yet another attempt to supersede UUID for the users who need decentralized, globally unique time-ordered identifiers. SCRU128 is inspired by ULID and KSUID and has the following features:

• 128-bit unsigned integer type
• Sortable by generation time (as integer and as text)
• 25-digit case-insensitive textual representation (Base36)
• 48-bit millisecond Unix timestamp that ensures useful life until year 10889
• Up to 281 trillion time-ordered but unpredictable unique IDs per millisecond
• 80-bit three-layer randomness for global uniqueness

import { scru128, scru128String } from "scru128";
// or on browsers:
// import { scru128, scru128String } from "https://unpkg.com/scru128@^2";

// generate a new identifier object
const x = scru128();
console.log(String(x)); // e.g. "036Z951MHJIKZIK2GSL81GR7L"
console.log(BigInt(x.toHex())); // as a 128-bit unsigned integer

// generate a textual representation directly
console.log(scru128String()); // e.g. "036Z951MHZX67T63MQ9XE6Q0J"

See SCRU128 Specification for details.

License

Licensed under the Apache License, Version 2.0.

See also

• API Documentation
• Run tests on your browser

Changelog

v2.0.0 - 2022-05-01

Changed

• Textual representation: 26-digit Base32 -> 25-digit Base36
• Field structure: { timestamp: 44 bits, counter: 28 bits, per_sec_random: 24 bits, per_gen_random: 32 bits } -> { timestamp: 48 bits, counter_hi: 24 bits, counter_lo: 24 bits, entropy: 32 bits }
• Timestamp epoch: 2020-01-01 00:00:00.000 UTC -> 1970-01-01 00:00:00.000 UTC
• Counter overflow handling: stall generator -> increment timestamp
• Dual packaging method: CommonJS + ESM wrapper -> native ESM + isolate CommonJS

Removed

• setLogger() as counter overflow is no longer likely to occur
• TIMESTAMP_BIAS
• Scru128Id#counter, Scru128Id#perSecRandom, Scru128Id#perGenRandom

Added

• Scru128Id#counterHi, Scru128Id#counterLo, Scru128Id#entropy

Deprecated

• CommonJS entry points