@shgysk8zer0/suid NPM

`@shgysk8zer0/suid`

Simple/Sortable Unique IDentifiers

node-current npm bundle size gzipped

What/Why

This library generates simple/sortable, deterministic, and reversible unique identifiers (SUIDs).

Sortable: SUIDs are designed to be easily sorted chronologically based on their embedded timestamp.
Deterministic: Given the same input options, the getSUID() function will always generate the same SUID.
Reversible: The parseSUID() function allows you to recover the original date and random data used to generate a given SUID.
Customizable: Generating options allow varying entropy in the random bits, and supports base64 or base64 URL encoding.
Lighweight: After minifying and tree-shaking and gzip compression, can be as small as 460B.
Standards-based and modern: Uses new Uint8Array methods for converting to/from base64 and hexadecimal.

Installation/importing

Via npm

npm i @shgysk8zer0/suid

Via unpkg & importmap

`<script type="importmap">`

<script type="importmap">
  {
    "imports": {
      "@shgysk8zer0/suid": "https://unpkg.com/@shgysk8zer0/suid[@:version]/suid.min.js"
    }
  }
</script>

Example Usage

import { getSUID, parseSUID } from '@shgysk8zer0/suid';

const suid = getSUID();
const { date, randomBits, alphabet, separator } = parseSUID(suid);

Advanced Usage

import { getSUID, parseSUID, BASE64_URL } from '@shgysk8zer0/suid';

const suid = getSUID({
  date: 1734076800000, // 2024-12-13T08:00:00.000Z
  randomBits: new Uint8Array([236, 229, 72, 197, 74, 155, 111, 0, 144, 245, 43, 1]),
  alphabet: BASE64_URL, // "base64url"
  separator: ':',
});

console.log(suid); // "AZO_CBwA:7OVIxUqb:bwCQ9SsB"
console.log(parseSUID(suid, { alphabet: BASE64_URL, separator: ':' }));
/* Object {
  date: Date Fri Dec 13 2024 00:00:00 GMT-0800 (Pacific Standard Time),
  randomBits: Uint8Array(12),
  alphabet: "base64url",
  separator: ":"
}*/

SUID Generating Options

Option Name	Type	Default	Description
`date`	`Date` \| `number`	`Date.now()`	The timestamp to use in the SUID. If a `Date` object is provided, its timestamp will be used.
`randomBits`	`Uint8Array`	`crypto.getRandomValues(new Uint8Array(12))`	Random data for the SUID. Must be at least 2 bytes.
`alphabet`	`string`	`'base64'`	Base64 alphabet to use for encoding. Allowed values: 'base64', 'base64url'.
`separator`	`string`	`'.'`	Separator character between SUID parts. Be careful to not use a char that may be used in the encoding.

Requirements

This library requires the new Uint8Array methods for converting to/from base64 & hexadecimal. For the time being, you will probably want a polyfill such as found in core-js.

uuid suid random identifier guid crypto cryptography

1.0.0

7 months ago