Skip to content
Switch branches/tags


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.


$ npm install ksuid


Require the module:

const KSUID = require('ksuid')


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 = - 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)


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 // 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)


You can compare KSUIDs: // 1 // 0 // -1

And check for equality:

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


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

KSUID.isValid(buffer) // Boolean