ulid

What is ulid?

The ulid npm package is a library for generating Universally Unique Lexicographically Sortable Identifiers (ULIDs). ULIDs are a type of unique identifier that are lexicographically sortable, making them useful for databases and other systems where ordering by time is important.

What are ulid's main functionalities?

Generate a ULID

This feature allows you to generate a new ULID. The generated ULID is a 26-character string that is lexicographically sortable and unique.

const { ulid } = require('ulid');
const id = ulid();
console.log(id);

Monotonic ULID

This feature allows you to generate ULIDs in a monotonic manner, ensuring that they are always increasing even if generated in the same millisecond.

const { monotonicFactory } = require('ulid');
const ulid = monotonicFactory();
const id1 = ulid();
const id2 = ulid();
console.log(id1, id2);

Other packages similar to ulid

uuid

The uuid package is a popular library for generating UUIDs (Universally Unique Identifiers). Unlike ULIDs, UUIDs are not lexicographically sortable but are widely used for their simplicity and uniqueness. UUIDs are typically used in distributed systems where uniqueness is critical.

nanoid

The nanoid package is a library for generating unique IDs with a focus on performance and small size. Nanoid IDs are not lexicographically sortable but are very fast to generate and have a smaller footprint compared to ULIDs.

shortid

The shortid package is a library for generating short, unique, non-sequential IDs. While shortid IDs are not lexicographically sortable, they are useful for cases where a shorter ID is preferred and uniqueness is still required.

README

Universally Unique Lexicographically Sortable Identifier

UUID can be suboptimal for many uses-cases because:

• It isn't the most character efficient way of encoding 128 bits of randomness
• UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
• UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
• UUID v4 provides no other information than randomness which can cause fragmentation in many data structures

Instead, herein is proposed ULID:

• 128-bit compatibility with UUID
• 1.21e+24 unique ULIDs per millisecond
• Lexicographically sortable!
• Canonically encoded as a 26 character string, as opposed to the 36 character UUID
• Uses Crockford's base32 for better efficiency and readability (5 bits per character)
• Case insensitive
• No special characters (URL safe)
• Monotonic sort order (correctly detects and handles the same millisecond)

Installation

npm install --save ulid

Import

TypeScript, ES6+, Babel, Webpack, Rollup, etc.. environments

import { ulid } from 'ulid'

ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV

CommonJS environments

const ULID = require('ulid')

ULID.ulid()

AMD (RequireJS) environments

define(['ULID'] , function (ULID) {
  ULID.ulid()
});

Browser

<script src="/path/to/ulid.js"></script>
<script>
    ULID.ulid()
</script>

Usage

To generate a ULID, simply run the function!

import { ulid } from 'ulid'

ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV

Seed Time

You can also input a seed time which will consistently give you the same string for the time component. This is useful for migrating to ulid.

ulid(1469918176385) // 01ARYZ6S41TSV4RRFFQ69G5FAV

Monotonic ULIDs

To generate monotonically increasing ULIDs, create a monotonic counter.

Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond

import { monotonicFactory } from 'ulid'

const ulid = monotonicFactory()

// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR8
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR9
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRA
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRB
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRC

// Even if a lower timestamp is passed (or generated), it will preserve sort order
ulid(100000) // 000XAL6S41ACTAV9WEVGEMMVRD

Pseudo-Random Number Generators

ulid automatically detects a suitable PRNG.

Allowing the insecure Math.random

By default, ulid will not use Math.random, because that is insecure. To allow the use of Math.random, you'll have to use factory and detectPrng.

import { factory, detectPrng } from 'ulid'

const prng = detectPrng(true) // pass `true` to allow insecure
const ulid = factory(prng)

ulid() // 01BXAVRG61YJ5YSBRM51702F6M

Use your own PRNG

To use your own pseudo-random number generator, import the factory, and pass it your generator function.

import { factory } from 'ulid'
import prng from 'somewhere'

const ulid = factory(prng)

ulid() // 01BXAVRG61YJ5YSBRM51702F6M

You can also pass in a prng to the monotonicFactory function.

import { monotonicFactory } from 'ulid'
import prng from 'somewhere'

const ulid = factory(prng)

ulid() // 01BXAVRG61YJ5YSBRM51702F6M

Implementations in other languages

From the community!

Language	Author	Binary Implementation
C++	suyash	✓
Clojure	theikkila
Objective-C	ricardopereira
Crystal	SuperPaintman
Dart	isoos	✓
Delphi	matinusso
D	enckse
D (dub)	extrawurst
Erlang	savonarola
Elixir	merongivian
F#	lucasschejtman
Go	imdario
Go	oklog	✓
Haskell	steven777400	✓
Java	huxi	✓
Java	azam
Java	Lewiscowles1986
Julia	ararslan
Lua	Tieske
.NET	RobThree	✓
.NET	fvilers
Nim	adelq
Perl 5	bk	✓
PHP	Lewiscowles1986
PHP	robinvdvleuten
PowerShell	PetterBomban
Python	mdipierro
Python	ahawker	✓
Python	mdomke	✓
Ruby	rafaelsales
Rust	mmacedoeu	✓
Rust	dylanhart	✓
SQL-Microsoft	rmalayter	✓
Swift	simonwhitehouse
Tcl	dbohdan

Specification

Below is the current specification of ULID as implemented in this repository.

Note: the binary format has not been implemented in JavaScript as of yet.

 01AN4Z07BY      79KA1307SR9X4MV3

|----------|    |----------------|
 Timestamp          Randomness
   48bits             80bits

Components

Timestamp

• 48 bit integer
• UNIX-time in milliseconds
• Won't run out of space till the year 10895 AD.

Randomness

• 80 bits
• Cryptographically secure source of randomness, if possible

Sorting

The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed

Canonical String Representation

ttttttttttrrrrrrrrrrrrrrrr

where
t is Timestamp (10 characters)
r is Randomness (16 characters)

Encoding

Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.

0123456789ABCDEFGHJKMNPQRSTVWXYZ

Monotonicity

When generating a ULID within the same millisecond, we can provide some guarantees regarding sort order. Namely, if the same millisecond is detected, the random component is incremented by 1 bit in the least significant bit position (with carrying). For example:

import { monotonicFactory } from 'ulid'

const ulid = monotonicFactory()

// Assume that these calls occur within the same millisecond
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0

If, in the extremely unlikely event that, you manage to generate at most 80 ^ 2 ULIDs within the same millisecond, or cause the random component to overflow with less, the generation will fail.

import { monotonicFactory } from 'ulid'

const ulid = monotonicFactory()

// Assume that these calls occur within the same millisecond
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRY
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS1
...
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZX
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZY
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZZ
ulid() // throw new Error()!

Overflow Errors when Parsing Base32 Strings

Technically, a 26 character Base32 encoded string can contain 130 bits of information, whereas a ULID must only contain 128 bits. Therefore, the largest valid ULID encoded in Base32 is 7ZZZZZZZZZZZZZZZZZZZZZZZZZ, which corresponds to an epoch time of 281474976710655 or 2 ^ 48 - 1.

Any attempt to decode or encode a ULID larger than this should be rejected by all implementations, to prevent overflow bugs.

Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Prior Art

Partly inspired by:

• http://instagram-engineering.tumblr.com/post/10853187575/sharding-ids-at-instagram
• https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html

Test Suite

npm test

Performance

npm run perf

ulid
336,331,131 op/s » encodeTime
102,041,736 op/s » encodeRandom
17,408 op/s » generate


Suites:  1
Benches: 3
Elapsed: 7,285.75 ms