npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ulidx

v2.4.1

Published

ULID generator for NodeJS and the browser

Downloads

370,278

Readme

ulidx

ULID generator for NodeJS and the browser

ulidx Tests status GitHub Dependents (via libraries.io) monthly downloads total downloads

ULID generator library, based off of the original ulid for NodeJS and the browser. ULIDs are Universally Unique Lexicographically Sortable Identifiers. This library adheres to this specification.

The original ulid is no longer maintained, and has several outstanding compatibility-related issues that were never addressed. This library aims to address those and remain compatible in a larger range of environments.

Installation

Install using npm by running: npm install ulidx --save.

ulidx provides types and is written entirely in Typescript. It provides both ESM and CommonJS outputs.

Usage

Import ulid to generate new ULIDs:

import { ulid } from "ulidx";

ulid(); // 01F7DKCVCVDZN1Z5Q4FWANHHCC

Time seed

You can also provide a time seed which will consistently give you the same string for the time component.

This is useful for migrating to ulid.

ulid(1469918176385); // 01ARYZ6S41TSV4RRFFQ69G5FAV

Monotonic ULID factory

To generate monotonically increasing ULIDs, create a monotonic counter using the factory:

import { monotonicFactory } from "ulidx";

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

Decode ULID Time

Import decodeTime to extract the timestamp embedded in a ULID:

import { decodeTime } from "ulidx";

// Extract milliseconds since UNIX Epoch from ULID
decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV"); // 1469918176385

Validate ULID

Import isValid to check if a string is a valid ULID:

import { isValid } from "ulidx";

isValid("01ARYZ6S41TSV4RRFFQ69G5FAV"); // true
isValid("01ARYZ6S41TSV4RRFFQ69G5FA"); // false

Crockford's Base32 (Typos tolerance and Hyphened ULIDs)

Import fixULIDBase32 to fix typos and remove hyphens in a ULID:

import { fixULIDBase32 } from "ulidx";

fixULIDBase32("oLARYZ6-S41TSV4RRF-FQ69G5FAV"); // 01ARYZ6S41TSV4RRFFQ69G5FAV

Pseudo-Random Number Generation (PRNG)

ulidx will attempt to locate a suitable cryptographically-secure random number generator in the environment where it's loaded. On NodeJS this will be crypto.randomBytes and in the browser it will be crypto.getRandomValues.

Math.random() is not supported: The environment must have a suitable crypto random number generator.

Compatibility

ulidx is compatible with the following environments:

  • NodeJS 16 and up
    • Node REPL
  • Browsers with working crypto / msCrypto libraries
    • Web workers
  • React-Native ¹
  • Edge compute
    • Cloudflare Workers ²
    • Vercel Edge

¹ React-Native is supported if crypto.getRandomValues() is polyfilled. react-native-get-random-values is one such library that should work well with ulidx. It should be imported before ulidx is used.

² ulidx is not fully compatible with Cloudflare Workers due to their problematic stance on getting the current time. It is recommended to only use monotonic factories in this runtime.

Browser

ulidx provides browser bundles in both ESM and CommonJS varieties. Importing should be automatic, but you can import them directly:

  • dist/browser/index.js - Browser ESM build
  • dist/browser/index.cjs - Browser CommonJS build

Unlike version 1.x, these browser builds cannot simply be injected into the browser. They must be included in a build system of some kind, like Rollup or Webpack.

Note that you can use the Node-based builds in the browser if you use such an aforementioned tool, but you will need to stub node:crypto to do so. Consider the following example in Webpack using a plugin:

{
    // ...

    plugins: [
        new NormalModuleReplacementPlugin(/node:/, (resource) => {
            resource.request = resource.request.replace(/^node:/, "");
        })
    ]

    // ...
}