Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
October 30, 2021 17:30
August 22, 2020 13:43
August 22, 2020 13:43
August 22, 2020 13:43
October 30, 2021 17:27
August 22, 2020 13:43
October 30, 2021 17:31


A Node.js implementation of Segment's KSUID library.

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