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

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

This package provides a generator of opaque numeric identifiers with optional support for ID versioning and efficient re-use via an implicit list of free IDs after previously generated IDs have been discarded. The 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 (also 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).

yarn add @thi.ng/idgen

• @thi.ng/api

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

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

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

ids.free(a);
// true

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

ids.id(b);
// 0

ids.version(b)
// 1

ids.has(b);
// true

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

const ids = ig.idgen(8);

ids.next();
ids.next();
ids.next();
ids.next();

ids.free(2);

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

ids.next();
// [3, 258, 1, 0]

• Karsten Schmidt

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