Nutrient Packed Morsels

    ulid
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.0 • Public • Published



    ulid


    Build Status codecov npm

    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 (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
    

    Keywords

    none

    Install

    npm i ulid

    DownloadsWeekly Downloads

    465,967

    Version

    2.3.0

    License

    MIT

    Last publish

    Collaborators

    • alizain