@philiprehberger/cuid-ts

v0.2.0

Published

5 months ago

Collision-resistant sortable unique IDs

0High
0Medium
0Low

reverendphilip

scopeforged

cuid id unique sortable collision-resistant uuid-alternative short-id timestamp

@philiprehberger/cuid-ts

Collision-resistant sortable unique IDs for TypeScript

Installation

npm install @philiprehberger/cuid-ts

Usage

import { createId } from '@philiprehberger/cuid-ts';

const id = createId();
// => "c<timestamp><counter><hash><random>"

Custom Prefix and Length

import { createId } from '@philiprehberger/cuid-ts';

const userId = createId({ prefix: 'user', length: 32 });
const orderId = createId({ prefix: 'ord', length: 28 });

Pre-configured Factory

import { createIdFactory } from '@philiprehberger/cuid-ts';

const generateOrderId = createIdFactory({ prefix: 'ord', length: 28 });
const a = generateOrderId();
const b = generateOrderId();

Type Guard

import { isCuid } from '@philiprehberger/cuid-ts';

if (isCuid(someValue)) {
  // someValue is typed as Cuid
}

Short URL-Friendly IDs

import { shortCuid } from '@philiprehberger/cuid-ts';

const id = shortCuid();
// => 12-character base36 ID, e.g. "ll7kx2a3b9zd"

const longer = shortCuid({ length: 16 });
// => 16-character ID

// length is configurable from 8 to 24
shortCuid({ length: 8 });
shortCuid({ length: 24 });

Extract Embedded Timestamp

import { createId, shortCuid, extractTimestamp } from '@philiprehberger/cuid-ts';

const id = createId();
const ts = extractTimestamp(id);
// => unix-millisecond timestamp, or null if it cannot be parsed

const short = shortCuid();
extractTimestamp(short); // works on short IDs too

extractTimestamp('not-an-id'); // => null

API

| Method | Description | |--------|-------------| | createId(options?) | Generate a collision-resistant sortable unique ID. Options: prefix (default 'c'), length (default 24), fingerprint. | | createIdFactory(options) | Return a zero-argument function that generates IDs with the given options baked in. | | shortCuid(options?) | Generate a short, URL-friendly base36 ID. Options: length (8-24, default 12). Throws RangeError on invalid length. | | extractTimestamp(id) | Recover the unix-millisecond timestamp embedded in a CUID or short CUID. Returns null if the id cannot be parsed. | | isCuid(value) | Type guard that returns true if value matches the CUID format (starts with a lowercase letter, lowercase alphanumeric). | | Cuid | Branded string type representing a valid CUID. | | CreateIdOptions | Options interface: prefix?: string, length?: number, fingerprint?: string. | | ShortCuidOptions | Options interface: length?: number (8-24, default 12). |