novemberborn / ksuid Goto Github PK

View Code? Open in Web Editor NEW

241.0 3.0 28.0 405 KB

Node.js implementation of K-Sortable Globally Unique IDs

License: Other

JavaScript 99.53% TypeScript 0.47%

hacktoberfest

ksuid's Introduction

ksuid

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

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

ksuid's People

Contributors

Stargazers

Watchers

ksuid's Issues

Does it store milliseconds?

const v = k.randomSync(new Date('2022-12-17T03:40:29.204Z'))
const v2 = k.randomSync(new Date('2022-12-17T03:40:29.300Z'))

For example: v.date.toISOString() doesn't seem to retain the ms value of 204.

It seems like I can't rely on the sorting because [v,v2].sort() will list v2 as the first one. Is there a way to reliably sort the 27 chars string based on the milliseconds precision or am I missing something here? Thanks!

cc: @novemberborn @amdolan

Using KSUID in angular

Hi there,
I'm using KSUID as id on my Golang API. Now I'm trying to use your package in my angular app, but I'm a bit stumped as to getting it to work.
Somebody got a few minutes to write a tiny example of how to use it in Angular?

I tried:

import ksuid = require('ksuid');

ReferenceError: Can't find variable: ksuid

import * as ksuid from 'ksuid';

Cannot access uninitialized variable.

import ksuid from 'ksuid';

Cannot access uninitialized variable.

Any pointers would be highly appreciated!

Suggestion: Add optional date param to KSUID.random and KSUID.randomSync.

This is an incredibly useful library, thank you!

I often already have a date before generating a KSUID. An example is when I insert multiple related items into the database that I want to all have the same timestamp.

I'd love the option to do pass in a date object or ms-epoch value:

const createdAt = new Date()
// ...
const id = await KSUID.random(createdAt) // or KSUID.random(createdAt.getTime())

I can do this using KSUID.fromParts of course but that requires a little more work to generate the random payload. This would make it slightly easier.

Simple example - doesn't seem ordered

I'm getting results that are out of order:

const TIMESTAMP = Date.now();

const data = [
  TIMESTAMP, // 1quOkfPXJlP8398OOPw3ZAdU1Ud
  TIMESTAMP + 1, // 1quOkbqQvXWaG1jRZJ8gT7SR5TS
  TIMESTAMP + 2 // 1quOkgOFUU6rEapMcojkPREdr7v
].map((timestamp) =>  KSUSID.randomSync(timestamp).string) ;

The sort order looks like this:

1quOkbqQvXWaG1jRZJ8gT7SR5TS <-- TIMESTAMP + 1
1quOkfPXJlP8398OOPw3ZAdU1Ud <-- TIMESTAMP
1quOkgOFUU6rEapMcojkPREdr7v <-- TIMESTAMP + 2

(1, 0, 2)

vs 0, 1, 2 or 2, 1 , 0

Am I doing something wrong here?

Typings out of whack

This works (JavaScript):

const INSTANCE_ID = require('ksuid').randomSync().string;

This transpiles as correct, given your typings, but doesn't work (TypeScript):

import * as ksuid from 'ksuid';

const INSTANCE_ID = ksuid.KSUID.randomSync().string;

→ JavaScript:

const ksuid = require("ksuid");
const INSTANCE_ID = ksuid.KSUID.randomSync().string;

Workaround (TypeScript):

const INSTANCE_ID: string = require('ksuid').randomSync().string;

Thanks for the module, though! Totally saved me having to do it myself.

Re: PR #17

Doesn't seem to work with earlier (or some...) dates ?

For example:

KSUID.randomSync(new Date(2005,11,5))

Error:

RangeError [ERR_OUT_OF_RANGE]: The value of "value" is out of range. It must be >= 0 and <= 4294967295. Received -266241200

cc: @novemberborn @amdolan

strings are not sortable

hi,
I am trying to use this library to generate IDs in MySQL and store it as a sortable string,
I generated 8 IDs, but it is not sortable by creation time?

here is a screenshot of the generated ID's, the name column should have been ordered 1..8 when the ID column is sorted.

Am I missing something in how I'm implementing it?
I'm just using

id: (await KSUID.random()).string,

Convert offset to be compatible with segment's KSUID

Currently this package is not directly comptible with segment's KSUID, as their offset is 14e8, while this package uses and offset of 14e11

I am proposing that it be changed to 14e8 to be completely compatible and make true on it's claim to being an implementation of segment's KSUID.

How to use isValid?

How do we use isValid? When I call it using a buffer generated from a string, it always returns false regardless of whether the ksuid is valid or not.

Example:

import ksuid from 'ksuid';

const id = ksuid.randomSync().string; // 2GZ2KKxYNaHLlhuwOWWGyOhKftp
const isValid = ksuid.isValid(Buffer.from(id, 'utf8')); // false