Package Exports

xid-ts
xid-ts/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (xid-ts) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

xid-ts

Globally unique sortable id generator. A Typescript port of https://github.com/rs/xid.

The binary representation is compatible with the Mongo DB 12-byte ObjectId. The value consists of:

a 4-byte timestamp value in seconds since the Unix epoch
a 3-byte value based on the machine identifier
a 2-byte value based on the process id
a 3-byte incrementing counter, initialized to a random value

The string representation is 20 bytes, using a base32 hex variant with characters [0-9a-v] to retain the sortable property of the id.

See the original xid project for more details.

Usage

npm i xid-ts --save

Examples

import { Xid } from 'xid-ts'

const defaultXid = Xid.default()
assert.equal(defaultXid.isZero(), true)

const now = Math.floor(Date.now() / 1000)
const newXid = new Xid()
assert.equal(newXid.isZero(), false)
assert.isTrue(newXid.timestamp() >= now)

const xid = Xid.parse('9m4e2mr0ui3e8a215n4g')
assert.equal(xid.isZero(), false)
console.log(xid.toBytes()) // Uint8Array(12) [77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201]
assert.equal(xid.toString(), '9m4e2mr0ui3e8a215n4g')
assert.equal(xid.timestamp(), 1300816219)
assert.equal(xid.counter(), 4271561)
assert.equal(xid.equals(newXid), false)
assert.equal(xid.equals(Xid.fromValue('9m4e2mr0ui3e8a215n4g')), true)
assert.equal(xid.equals(Xid.fromValue([77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201])), true)
assert.equal(xid.equals(Xid.fromValue(Buffer.from([77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201]))), true)
assert.equal(xid.equals(Xid.fromValue(new Uint8Array([77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201]))), true)

Encode & Decode With JSON and CBOR

https://github.com/yiwen-ai/xid-ts/blob/main/src/index.test.ts#L70

import { decode, encode } from 'cborg'
import { Xid } from 'xid-ts'

const xid = Xid.fromValue('9m4e2mr0ui3e8a215n4g')
const obj = {
  id: xid,
  name: 'yiwen'
}
const json = JSON.stringify(obj)
assert.equal(json, '{"id":"9m4e2mr0ui3e8a215n4g","name":"yiwen"}')
const obj1 = JSON.parse(json)
assert.isTrue(xid.equals(Xid.fromValue(obj1.id)))

const data = encode(obj)
assert.equal(Buffer.from(data).toString('hex'), 'a26269644c4d88e15b60f486e428412dc9646e616d6565796977656e')
// https://cbor.me/
// {"id": h'4D88E15B60F486E428412DC9', "name": "yiwen"}

const obj2 = decode(data)
assert.isTrue(xid.equals(Xid.fromValue(obj2.id)))

License

yiwen-ai/xid-ts is licensed under the MIT License. See LICENSE for the full license text.