ksuid

What is ksuid?

The ksuid npm package is used to generate KSUIDs (K-Sortable Unique Identifiers), which are globally unique identifiers that are sortable by time. KSUIDs are useful for distributed systems where unique and time-ordered identifiers are needed.

What are ksuid's main functionalities?

Generate a new KSUID

This feature allows you to generate a new KSUID. The generated KSUID is a 27-character string that is sortable by time.

const KSUID = require('ksuid');
KSUID.random().then(ksuid => console.log(ksuid.string));

Parse an existing KSUID

This feature allows you to parse an existing KSUID string back into a KSUID object. This can be useful for extracting the timestamp or other components from the KSUID.

const KSUID = require('ksuid');
const ksuidString = '1y0108k4h7d8j6k5h7d8j6k5h7d8';
const ksuid = KSUID.parse(ksuidString);
console.log(ksuid);

Extract timestamp from KSUID

This feature allows you to extract the timestamp from a KSUID. The timestamp is the number of seconds since the Unix epoch.

const KSUID = require('ksuid');
KSUID.random().then(ksuid => {
  const timestamp = ksuid.timestamp;
  console.log(timestamp);
});

Other packages similar to ksuid

uuid

The uuid package is used to generate UUIDs (Universally Unique Identifiers). Unlike KSUIDs, UUIDs are not sortable by time, but they are widely used for generating unique identifiers in distributed systems.

cuid

The cuid package generates collision-resistant IDs optimized for horizontal scaling and performance. CUIDs are not sortable by time, but they are designed to be highly unique and performant.

nanoid

The nanoid package generates unique IDs with a focus on performance and small size. NanoIDs are not sortable by time, but they are very fast to generate and have a smaller footprint compared to UUIDs and KSUIDs.

README

ksuid

A Node.js implementation of Segment's KSUID library. Supports Node.js 10, 12, 14 and newer.

You may also be interested in ksuid-cli.

Installation

$ npm install ksuid

Usage

Require the module:

const KSUID = require('ksuid')

Creation

You can create a new instance synchronously:

const ksuidFromSync = KSUID.randomSync()

Or asynchronously:

const ksuidFromAsync = await KSUID.random()

You can also specify a specific time, either in milliseconds or as a Date object:

const ksuidFromDate = KSUID.randomSync(new Date("2014-05-25T16:53:20Z"))
const ksuidFromMillisecondsAsync = await KSUID.random(1401036800000)

Or you can compose it using a timestamp and a 16-byte payload:

const crypto = require('crypto')
const yesterdayInMs = Date.now() - 86400 * 1000
const payload = crypto.randomBytes(16)
const yesterdayKSUID = KSUID.fromParts(yesterdayInMs, payload)

You can parse a valid string-encoded KSUID:

const maxKsuid = KSUID.parse('aWgEPTl1tmebfsQzFP4bxwgy80V')

Finally, you can create a KSUID from a 20-byte buffer:

const fromBuffer = new KSUID(buffer)

Properties

Once the KSUID has been created, use it:

ksuidFromSync.string // The KSUID encoded as a fixed-length string
ksuidFromSync.raw // The KSUID as a 20-byte buffer
ksuidFromSync.date // The timestamp portion of the KSUID, as a `Date` object
ksuidFromSync.timestamp // The raw timestamp portion of the KSUID, as a number
ksuidFromSync.payload // A Buffer containing the 16-byte payload of the KSUID (typically a random value)

Comparisons

You can compare KSUIDs:

todayKSUID.compare(yesterdayKSUID) // 1
todayKSUID.compare(todayKSUID) // 0
yesterdayKSUID.compare(todayKSUID) // -1

And check for equality:

todayKSUID.equals(todayKSUID) // true
todayKSUID.equals(yesterdayKSUID) // false

Validation

You can check whether a particular buffer is a valid KSUID:

KSUID.isValid(buffer) // Boolean