@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).

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT