Wondering what’s next for npm?Check out our public roadmap! »

@thi.ng/ksuid
TypeScript icon, indicating that this package has built-in type declarations

0.1.6 • Public • Published

ksuid

npm version npm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Configurable K-sortable unique identifiers, binary & base-N encoded.

Idea based on segmentio/ksuid, though with added flexibility in terms of configuration & implementation:

  • Configurable bit size (default: 128bits)
  • Base-N encoding scheme (default: base62, see @thi.ng/base-n for alternatives)
  • Epoch start time offset
  • RNG source (default: window.crypto)

KSUIDs generated w/ this package consist of the lower 32bits of an Unix epoch (potentially time shifted to free up bits for future timestamps) and N bits of a random payload (from a configurable source). IDs can be generated as byte arrays or base-N encoded strings. For the latter, the JS runtime MUST support BigInt.

KSUID bit layout diagram

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Related packages

  • @thi.ng/base-n - Arbitrary base-n conversions w/ presets for base16/32/36/58/62/64/85, support for arrays & bigints
  • @thi.ng/random - Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation

Installation

yarn add @thi.ng/ksuid
// ES module
<script type="module" src="https://unpkg.com/@thi.ng/ksuid?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/ksuid/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 447 bytes / CJS: 503 bytes / UMD: 627 bytes

Dependencies

API

Generated API docs

import { defKSUID } from "@thi.ng/ksuid";

// init w/ defaults
const id = defKSUID();

id.next();
// '05XCWbXa3akRqLDBUw4ogCVKGkd'

const a = id.nextBinary()
// Uint8Array(20) [
//     0, 160,  48, 77, 101, 251,
//   244,  17, 155, 97,  24, 101,
//    70,  71, 207, 23,  32,  21,
//   244, 116
// ]

// format a binary KSUID
id.format(a);
// '05XCZ32AaDZfZt0SWE2C22o6cqK'

Creating custom IDs:

import { BASE36 } from "@thi.ng/base-n";

// no time shift, 64bit random
const id36 = defKSUID({ base: BASE36, epoch: 0, bytes: 8 });
// '2VOUKH4K59AG0RXR4XH'

Benchmarks

yarn bench

benchmarking: b62, 128bit, n=10000
        warmup... 659.22ms (10 runs)
        executing...
        total: 6402.18ms, runs: 100
        mean: 64.02ms, median: 63.50ms, range: [59.98..96.15]
        q1: 62.64ms, q3: 64.41ms
        sd: 6.93%
benchmarking: b62, 64bit, n=10000
        warmup... 363.35ms (10 runs)
        executing...
        total: 3469.28ms, runs: 100
        mean: 34.69ms, median: 34.41ms, range: [32.61..56.58]
        q1: 33.35ms, q3: 35.41ms
        sd: 7.47%
benchmarking: b62, 32bit, n=10000
        warmup... 218.78ms (10 runs)
        executing...
        total: 2118.93ms, runs: 100
        mean: 21.19ms, median: 20.95ms, range: [20.20..25.74]
        q1: 20.71ms, q3: 21.30ms
        sd: 4.14%

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-ksuid,
  title = "@thi.ng/ksuid",
  author = "Karsten Schmidt",
  note = "https://thi.ng/ksuid",
  year = 2020
}

License

© 2020 - 2021 Karsten Schmidt // Apache Software License 2.0

Install

npm i @thi.ng/ksuid

DownloadsWeekly Downloads

16

Version

0.1.6

License

Apache-2.0

Unpacked Size

29.8 kB

Total Files

10

Last publish

Collaborators

  • avatar