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

    2.1.6 • Public • Published

    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

    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>

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

    Install

    npm i @thi.ng/idgen

    DownloadsWeekly Downloads

    131

    Version

    2.1.6

    License

    Apache-2.0

    Unpacked Size

    30.2 kB

    Total Files

    6

    Last publish

    Collaborators

    • thi.ng