cuid

What is cuid?

The 'cuid' npm package is a library for generating collision-resistant unique identifiers optimized for horizontal scaling and performance. It is designed to be simple, fast, and reliable, making it suitable for use in distributed systems and databases.

What are cuid's main functionalities?

Generate a CUID

This feature allows you to generate a new CUID. The generated ID is a string that is guaranteed to be unique, making it ideal for use as a primary key in databases or as a unique identifier in distributed systems.

const cuid = require('cuid');
const id = cuid();
console.log(id);

Generate a Slug

This feature generates a shorter, URL-friendly version of a CUID, known as a slug. Slugs are useful for creating human-readable URLs or identifiers that need to be shorter than a full CUID.

const cuid = require('cuid');
const slug = cuid.slug();
console.log(slug);

Check if a String is a CUID

This feature allows you to check if a given string is a valid CUID. It returns a boolean value indicating whether the string conforms to the CUID format.

const cuid = require('cuid');
const isCuid = cuid.isCuid('cixl4bq9k0000mh3ea0000001');
console.log(isCuid);

Check if a String is a Slug

This feature allows you to check if a given string is a valid CUID slug. It returns a boolean value indicating whether the string conforms to the slug format.

const cuid = require('cuid');
const isSlug = cuid.isSlug('cixl4bq');
console.log(isSlug);

Other packages similar to cuid

uuid

The 'uuid' package is a popular library for generating universally unique identifiers (UUIDs). Unlike CUIDs, UUIDs are standardized and widely used across different systems and platforms. UUIDs are typically longer than CUIDs and are not as human-readable.

nanoid

The 'nanoid' package is a library for generating unique, URL-friendly IDs. It is similar to CUID in that it focuses on performance and collision resistance, but it generates shorter IDs by default. Nanoid is also highly customizable, allowing you to specify the alphabet and length of the generated IDs.

shortid

The 'shortid' package is another library for generating short, unique IDs. It is designed to be simple and fast, similar to CUID. However, 'shortid' is no longer maintained and has been deprecated in favor of 'nanoid'.

README

CUID

Collission-resistant ids optimized for horizontal scaling and sequential lookup performance.

For node and browsers.

.cuid() returns a short random string with some collision-busting measures. Safe to use as HTML element ID's, and unique server-side record lookups.

Example

ch72gsb320000udocl363eofy

Broken down

** c - h72gsb32 - 0000 - udoc - l363eofy **

The groups, in order, are:

• 'c' - identifies this as a cuid, and allows you to use it in html entity ids. The fixed value helps keep the ids sequential.
• timestamp
• counter - a single process might generate the same random string. The weaker the pseudo-random source, the higher the probability. That problem gets worse as processors get faster. The counter will roll over if the value gets too big.
• Client fingerprint
• Math.random()

Fingerprints

In browsers, the first chars are obtained from the user agent string (which is fairly unique), and the supported mimeTypes (which is also fairly unique, except for IE, which always returns 0). That string is concatenated with a count of variables in the global scope (which is also fairly unique), and the result is trimmed to 4 chars.

In node, the first two chars are extracted from the process.pid. The next two chars are extracted from the hostname.

Motivation

Modern web applications have different requirements than applications from just a few years ago. Our modern unique identifiers have a stricter list of requirements that cannot all be satisfied by any existing version of the GUID/UUID specifications:

Horizontal scalability

Today's applications don't run on any single machine.

Applications might need to support online / offline capability, which means we need a way for clients on different hosts to generate ids that won't collide with ids generated by other hosts -- even if they're not connected to the network.

Purely random IDs, even very large ones like the uuid v4 specification lack sufficient entropy when running in separate processes on cloned virtual machines (or in browsers in the wild) to guarantee against collisions. Application developers report v4 UUID collisions causing problems in their applications when the ID generation is distributed between lots of machines such that lots of IDs are generated in the same millisecond (most pseudo-random algorithms use time in ms as a random seed).

Performance

Because entities might need to be generated in high-performance loops, id generation should be fast. That means no waiting around for asynchronous entropy pool requests, or cross-process/cross-network communication. It would be hard to use pseudo-random generators that rely on filling an entropy pool before it can generate another string. Performance slows to impracticality in the browser. All sources of entropy need to be fast enough for synchronous access.

Sequential

Sequential ids can enhance performance for database transactions for a variety of reasons.

Security

All client-visible ids need to have sufficient random data that it becomes practically impossible to try to guess IDs. Since cuids have multiple moving parts (time, counter, and several characters of pseudo-random data), trying to guess an id based on a previous ID would be a challenge.

Portability

Stronger forms of the UUID / GUID algorithms require access to OS services that are not available in browsers, meaning that they are impossible to implement in the browser.