Home

Awesome

<h1 align="center"> <br> <br> <img width="360" src="logo.png" alt="ulid"> <br> <br> <br> </h1>

Build Status codecov npm

Universally Unique Lexicographically Sortable Identifier

UUID can be suboptimal for many uses-cases because:

Instead, herein is proposed ULID:

Install with a script tag

<script src="https://unpkg.com/ulid@{{VERSION_NUMBER}}/dist/index.umd.js"></script>
<script>
    ULID.ulid()
</script>

Install with NPM

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()
});

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 (cryptographically-secure) PRNG. In the browser it will use crypto.getRandomValues and on node it will use crypto.randomBytes.

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 = monotonicFactory(prng)

ulid() // 01BXAVRG61YJ5YSBRM51702F6M

Implementations in other languages

Refer to ulid/spec

Specification

Refer to ulid/spec

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