cruid

1.0.0 • Public • Published

cruid

Collision-resistant distributed ids, optimized for Cockroach DB PKs

CI Status Coverage Status JavaScript Style Guide Conventional Commits

cruid is cuid for applications generating primary keys for Cockroach DB. Instead of generating monotonically-increasing IDs (which are good for older relational databases but not great for Cockroach), cruid generates IDs that can be equally distributed amongst multiple Cockroach nodes.

cruid is modeled after scuid to achieve the same performance improvements over the legacy cuid package.

So why not use a UUID instead?

With cruid, you get the best of both worlds - the benefits of cuid (shorter values, HTML-friendly IDs, collision-resistance in a tight loop and across different hosts) and the benefits of UUID (randomly distributed).

Let's compare:

Feature cruid cuid scuid crypto.randomUUID()
Collision resistance
Default ID length 25 chars 25 chars 25 chars 36 chars
HTML-friendly IDs
Random distribution
Performance (approx) 5-10x 1x 5-10x 20-25x
Configurable
Client fingerprinting
Supports short slugs

Install

npm i --save cruid

Usage

Basic examples:

// ESM
import cruid from 'cruid'
// CommonJS
const cruid = require('cruid')

// generate id (using default config)
const id = cruid()
//=> 'cdfzrzm72l611rbr50000gunp'

// generate a shorter slug
const slug = cruid.slug()
//=> '20r01hp'

Advanced examples:

// ESM
import { Cruid } from 'cruid'
// CommonJS
const { Cruid } = require('cruid')

// configure your own instance
// values shown are default but you can customize
const cruid = Cruid.get({
  prefix: 'c',             // static first char
  base: 36,                // radix for converting random integers to blocks
  blockSize: 4,            // num chars for each random block (2 random blocks per id)
  timestampSize: 8,        // num chars for timestamp block
  pid: process.pid,        // number for fingerprinting
  hostname: os.hostname(), // string for fingerprinting
  fill: '0',               // char for left-padding
  rng: Math                // needs `random()` function to generate value b/w 0 and 1
})

// generate id
const id = cruid.id()
//=> 'cc52tir8fl6122bhw0000ulnp'

// generate a shorter slug
const slug = cruid.slug()
//=> 'f5lf1gp'

Structure

ID

This is the value you should use as an application-generated primary key.

Prefix Random Block Timestamp Counter Fingerprint
c dfzrzm72 l611rbr5 0000 gunp

The prefix is static for a given cruid instance.

The random block is 2 random values converted to base, sliced, and concatenated.

The timestamp is epoch time converted to base and sliced.

The counter allows for different IDs if the same client happens to generate the same random block and timestamp for multiple calls, however unlikely, depending on processor speed. The counter will roll over if the value gets too big.

The client fingerprint is a combination of "host id" (based on hostname) and process pid.

Slug

A slug is a smaller (7-10 character) URL-friendly generated value. It should not be used as a primary key.

Random Block Timestamp Counter Fingerprint
20 r0 1 hp

The counter may be 1 to 4 characters.

License

MIT © 2016-2022 Jonas Hermsmeier and Andrew Goode

Related

See Eric Elliott's original writeup on the Motiviation for cuid. The same rationale applies to cruid.

Read about Cockroach best practices for generated IDs. To allow your application to scale, consider generating IDs in your application code via cruid instead of depending on the database to generate them.

Package Sidebar

Install

npm i cruid

Weekly Downloads

26

Version

1.0.0

License

MIT

Unpacked Size

12.4 kB

Total Files

5

Last publish

Collaborators

  • nexdrew