@shgysk8zer0/suid

Simple/Sortable Unique IDentifiers

• Code of Conduct
• Contributing

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.