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

@evokegroup/ulid

v1.3.1

Published

Library for creating, parsing, and converting universally unique lexicographically sortable identifiers (ULID) in ULID or UUID formats.

Downloads

41

Readme

evokegroup/ulid

Universally unique Lexicographically sortable IDentifier

A ULID is a 26 charater string consisting of a encoded timestamp followed by 16 random characters. This library can also encode a ULID in a UUID format and convert between the 2 formats.

Requires NodeJS 16+

Versions for use in the browser is included in /dist-browser.

Node.js

ulid()

Generates a ULID.

returns string

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | timestamp? | number | Date.now() | The timestamp |

import { ulid } from '@evokegroup/ulid';

const id = ulid(); // 01HDEKBMW3904VB2HYTVWWMSY5

// Use a existing timestamp
const now = Date.now(); // 1698075890563
const id = ulid(now); // 01HDEKBMW3904VB2HYTVWWMSY5

ulid.timestamp()

Gets the timestamp from a ULID

returns number

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The string to parconsose |

import { ulid } from '@evokegroup/ulid';

ulid.timestamp('01HDEKBMW3904VB2HYTVWWMSY5'); // 1698075890563
ulid.timestamp('018B5D35-D383-4809-B58A-3ED6F9CA67C5'); // 1698075890563

ulid.data()

Gets the random data portion of a ULID as a BigInt

returns bigint

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The string to parse |

import { ulid } from '@evokegroup/ulid';

ulid.data('01HDEKBMW3904VB2HYTVWWMSY5'); // 340189488800438527092677n
ulid.data('018B5D35-D383-4809-B58A-3ED6F9CA67C5'); // 340189488800438527092677n

ulid.is()

Determines if the given string is a ULID

returns boolean

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The string to test |

import { ulid } from '@evokegroup/ulid';

ulid.is('01HDEKBMW3904VB2HYTVWWMSY5'); // true
ulid.is('018B5D35-D383-4809-B58A-3ED6F9CA67C5'); // false

ulid.uuid()

Generates a ULID in a UUID v4 format.

returns string

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | timestamp? | number | Date.now() | The timestamp |

import { ulid } from '@evokegroup/ulid';

const id = ulid.uuid(); // 018B5D35-D383-4809-B58A-3ED6F9CA67C5

ulid.fromUUID()

Convert a UUID to a ULID.

returns string

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID to be converted |

import { ulid } from '@evokegroup/ulid';

const id = ulid.fromUUID('018B5D38-9C52-47FB-97AB-09550991A91C'); // 01HDEKH72J8ZXSFAR9AM4S3A8W

ulid.toUUID()

Convert a ULID to a UUID. Conversions of externally generated ULIDs may not result in a valid UUID v4.

returns string

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID to be converted |

import { ulid } from '@evokegroup/ulid';

const uuid = ulid.toUUID('01HDEKH72J8ZXSFAR9AM4S3A8W'); // 018B5D38-9C52-47FB-97AB-09550991A91C

ulid.factory()

Create a ULID factory which will increment the ID with every generation. The ID will increment regardless of which ID format is generated.

returns Factory

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | args | object | | | | args.timestamp? | number | Date.now() | The timestamp | | args.data? | bigint | Randomly generated | The seed data value. If this value is less than FACTORY_DATA_MIN or greater than FACTORY_DATA_MAX it will be set to FACTORY_DATA_MIN. |

import { ulid } from '@evokegroup/ulid';

let factory = ulid.factory();
// with a timestamp
factory = ulid.factory({ timestamp: 1698160540736 });
// with a timestamp and data seed
factory = ulid.factory({ timestamp: 1698160540736, data: 369740473983206468055316n });

const ulid1 = factory.ulid(); // 01HDH42Z209S5TQNW6QK6BEW8M
const uuid2 = factory.uuid(); // 018B6241-7C40-4E4B-ABD7-86BCCCB77115
const ulid3 = factory.ulid(); // 01HDH42Z209S5TQNW6QK6BEW8P
const uuid4 = factory.uuid(); // 018B6241-7C40-4E4B-ABD7-86BCCCB77117

Factory.ulid()

Returns a ULID from the factory.

returns string

import { ulid } from '@evokegroup/ulid';

const factory = ulid.factory();
const ulid1 = factory.ulid(); // 01HDH8AJWQ9X7ABB2P330S362Y
const ulid2 = factory.ulid(); // 01HDH8AJWQ9X7ABB2P330S362Z
const ulid3 = factory.ulid(); // 01HDH8AJWQ9X7ABB2P330S3630

Factory.uuid()

Returns a UUID v4 from the factory.

returns string

import { ulid } from '@evokegroup/ulid';

const factory = ulid.factory();
const uuid1 = factory.uuid(); // 018B6286-CC0B-4F0B-DDEC-B6040D445C4E
const uuid2 = factory.uuid(); // 018B6286-CC0B-4F0B-DDEC-B6040D445C4F
const uuid3 = factory.uuid(); // 018B6286-CC0B-4F0B-DDEC-B6040D445C50

Constants

| Name | Type | Description | | --- | --- | --- | | ULID_CHARS | string | The characters used to encode a ULID | | ULID_TIMESTAMP_LENGTH | number | The length of the timestamp portion of a ULID | | UUID_TIMESTAMP_LENGTH | number | The length of the timestamp portion of a UUID | | FACTORY_DATA_MIN | bigint | The minimum data seed value for the Factory | | FACTORY_DATA_MAX | bigint | The maximum data seed value for the Factory | | TIMESTAMP_MIN | number | The minimum allowed timestamp value | | TIMESTAMP_MAX | number | The maximum allowed timestamp value |

Browser

Versions of the ulid function for use in the browser.

Javascript

The regular javascript browser version will add all exported constants and the ulid function to the window object for global access.

<script src="node_modules/@evokegroup/ulid/dist-browser/index.min.js"></script>
<script>
  const id = ulid();
</script>

Module

<script src="main.mjs" type="module"></script>
// main.mjs
import { ulid } from 'node_modules/@evokegroup/ulid/dist-browser/index.min.mjs';
const id = ulid();