@shgysk8zer0/suid
Version:
Simple/Sortable Unique IDentifiers
106 lines (80 loc) • 5 kB
Markdown
# `@shgysk8zer0/suid`
Simple/Sortable Unique IDentifiers
[](https://github.com/shgysk8zer0/suid/actions/workflows/codeql-analysis.yml)
[](https://github.com/shgysk8zer0/suid/blob/master/LICENSE)
[](https://github.com/shgysk8zer0/suid/commits/master)
[](https://github.com/shgysk8zer0/suid/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@shgysk8zer0/suid)
[](https://www.npmjs.com/package/@shgysk8zer0/suid)
[](https://github.com/shgysk8zer0)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
<!-- - [Security Policy](./.github/SECURITY.md) -->
## 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
```bash
npm i @shgysk8zer0/suid
```
### Via unpkg & [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
#### `<script type="importmap">`
```html
<script type="importmap">
{
"imports": {
"@shgysk8zer0/suid": "https://unpkg.com/@shgysk8zer0/suid[@:version]/suid.min.js"
}
}
</script>
```
## Example Usage
```js
import { getSUID, parseSUID } from '@shgysk8zer0/suid';
const suid = getSUID();
const { date, randomBits, alphabet, separator } = parseSUID(suid);
```
### Advanced Usage
```js
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64)
for converting to/from base64 & hexadecimal. For the time being, you will probably want a polyfill such as found in [core-js](https://github.com/zloirock/core-js#uint8array-to--from-base64-and-hex).