Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@thi.ng/idgen

Package Overview
Dependencies
Maintainers
1
Versions
143
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@thi.ng/idgen

Generator of opaque numeric identifiers with optional support for ID versioning and efficient re-use

  • 2.0.8
  • Source
  • npm
  • Socket score

Version published
Maintainers
1
Created
Source

idgen

npm version npm downloads Twitter Follow

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

About

Generator of opaque numeric identifiers with optional support for ID versioning and efficient re-use.

Previously generated IDs that have been discarded are stored in a memory-efficient implicit list of free IDs and will be re-used. The overall range of IDs can be specified/limited at construction time and is based on a given bit width. The largest range currently supported is 32 bits, less if versioning is enabled (configurable).

If versioning is used, the produced IDs are composite values, i.e. the lowest bits contain the actual ID (e.g for indexing purposes) and other bits contain the version information.

composite ID

Both parts can be extracted via the generator's .id() and .version() methods. Each time a valid versioned ID is being discarded via .free(id), its version is being increased and, depending on use case and usage frequency, will eventually overflow back to 0. Once an ID's version has been updated, the old version is considered invalid. IDs can be checked for validity via .has(id) (in constant time).

Status

STABLE - used in production

Search or submit any issues for this package

  • @thi.ng/ecs - Entity Component System based around typed arrays & sparse sets
  • @thi.ng/ksuid - Configurable K-sortable unique IDs, ULIDs, binary & base-N encoded, 32/48/64bit time resolutions

Installation

yarn add @thi.ng/idgen

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/idgen"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const idgen = await import("@thi.ng/idgen");

Package sizes (gzipped, pre-treeshake): ESM: 871 bytes

Dependencies

API

Generated API docs

import { idgen } from "@thi.ng/idgen";

ID generator with 16 bit range and no versioning

const ids = idgen(16, 0);

ids.next();
// 0

ids.next();
// 1

ids.next(2);
// 2

// discard ID 0
ids.free(0);
// true

ids.has(0);
// false

// reuse
ids.next()
// 0

ids.has(0);
// true

ids.next()
// 3

ID generator w/ 24 bit range & 8 bit version range

// the 8bit version range is being deduced automatically (32-24 = 8),
// but can also be overwritten
const ids = idgen(24);

const a = ids.next();
// 0

ids.free(a);
// true

const b = ids.next();
// 16777216

// b is the re-used new version of a
ids.id(b);
// 0

ids.version(b)
// 1

ids.has(b);
// true

// a is invalid at this point
// (even though a's .id() part is the same as b's)
ids.has(a);
// false

IDGen is iterable

const ids = ig.idgen(8);

ids.next();
// 0
ids.next();
// 1
ids.next();
// 2
ids.next();
// 3

ids.free(2);
// true

// only currently used IDs are returned
// NO ordering guarantee!
[...ids]
// [ 3, 1, 0 ]

ids.next();
// 258

[...ids]
// [3, 258, 1, 0]

Authors

Karsten Schmidt

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

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

License

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

Keywords

FAQs

Package last updated on 10 Nov 2021

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc