@thi.ng/idgen

[!NOTE] This is one of 200 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Status
• Related packages
• Installation
• Dependencies
• Usage examples
• API
  • ID generator with 16 bit range and no versioning
  • ID generator w/ 24 bit range & 8 bit version range
  • IDGen is iterable
• Authors
• License

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.

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

Related packages

• @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

ESM import:

import * as idgen from "@thi.ng/idgen";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/idgen"></script>

JSDelivr documentation

For Node.js REPL:

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

Package sizes (brotli'd, pre-treeshake): ESM: 1.18 KB

Dependencies

• @thi.ng/api
• @thi.ng/errors
• tslib

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

Usage examples

One project in this repo's /examples directory is using this package:

Screenshot	Description	Live demo	Source
	Fiber-based cooperative multitasking basics	Demo	Source

API

Generated API docs

ID generator with 16 bit range and no versioning

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

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

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

// 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

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

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 - 2024 Karsten Schmidt // Apache License 2.0