@thi.ng/idgen v2.2.41
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.
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
ES module import:
<script type="module" src="https://cdn.skypack.dev/@thi.ng/idgen"></script>
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: 874 bytes
Dependencies
API
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
2 days ago
17 days ago
20 days ago
29 days ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
9 months ago
9 months ago
9 months ago
9 months ago
5 months ago
9 months ago
9 months ago
6 months ago
7 months ago
6 months ago
9 months ago
6 months ago
6 months ago
7 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago