centralized generation of sequential, human-readable ids

Downloads in past


820.0.09 years ago10 years agoMinified + gzip package size for sequential-ids in KB


Build Status
A Node.jsnodejs module that allows centralized generation of sequential and human-readable ids.
Sample Id: ACB - 00423
|aspect|detail| |-------|-----:| |version|0.0.0| |dependencies|none| |node|0.11, 0.10| |last updated|11th December, 2014|


From Npmnpmjs:
$ npm install sequential-ids --save


// assuming `db` is a variable holding a database connection with the
// method `.store(key, value)`
// a '__default' key is created by default

var sequential = require("sequential-ids");

var generator = new sequential.Generator({
  digits: 6, letters: 3,
  store: function(key, ids) {, ids[ids.length - 1]);
  restore: "AAB - 000"

generator.add('otherKey', {
  digits : 3, letters: 1,
  store: function(key, ids) {, ids[ids.length - 1]);
  restore: "A - 00"

var new_id_1   = generator.generate();           // => AAB - 001
var new_id_2   = generator.generate();           // => AAB - 002
// ...
var other_id_1 = generator.generate('otherKey'); // => A - 01
var other_id_2 = generator.generate('otherKey'); // => A - 02
// ...

// possibly in another file
var accessor = new sequential.Accessor();, id) {
  console.log("new id: %s", id); // => AAB - 003
});'otherKey',function(err, id) {
  console.log("new id (otherKey): %s", id); // => A - 03


  1. new Generator(options)

you only require to create a single generator instance options is an object having the following attributes:
* `port`:
    * port at which the generator serves IDs.
    * Defaults to `9876`.

    * and, additionally, the same attributes as the Generator#add
    **options** object
in a case where you may require more than one generator, you
would allocate them to different ports. See ahead on how to target
each of the different generators.
```js var sequential = require("sequential-ids"); var generatorA = new sequential.Generator({port: 8998}); var generatorB = new sequential.Generator({port: 7667}); ```
A generator has the following methods:
* `Generator#start()`
  * starts the generator. If no Error is thrown, the generator will be
    ready for Accessors.

* `Generator#add(key, [options])`
  * adds a new key to the generator. If no Error is thrown, the
    generator will be ready for Accessors.
  * returns `false` if `key` had already been added to the
    generator; otherwise, returns `true`

  * **options** is an object having the following attributes:

    * `digits`:
        * no. of numbers to use in the ID.
        * numbers will be padded with zeros to satisfy this.
        * assigning `0` (zero) lets you ignore the number part
        * Defaults to `6`.
    * `letters`:
        * no. of letters to use.
        * assigning `0` (zero) lets you ignore the letters part
        * Defaults to `3`.
    * `store`:
        * a function that will be called to store the IDs on disk for
        * the function is passed an array of IDs that have been
        * repeatedly storing the last ID is useful to know where to
          start from in the next session.
        * Defaults to `null`.
    * `store_freq`:
        * frequency at which the store function should be called.
        * Defaults to `1`(called every 1 ID is generated)
    * `restore`:
        * last ID that was generated.
        * IDs will be generated from here on.
        * `digits` and `letters` will be ignored so as to follow the
          restore ID style.
        * it **must** be in the same style as IDs generated by the
        * If not specified, generates from start.
        * **MUST** be a string.
        * Overides the `.digits` and `.letters` options.
        * Defaults to `null`.
    * `autoAddKeys`:
        * whether to automatically add keys when IDs are requested
          with a non-existent key.
        * If `true`, such a key is added and an ID returned as though
          the key was already added using the Generator's options.
        * If `false`, an Error is passed to callback, if any, or `null` is
        * Defaults to `false`.

* `Generator#generate(key)`
  * generates a new ID for **key**. If no **key** is given, uses
    the default one. The new ID is returned immediately.

  * if the key does not exist and the option `autoAddKeys` is not
    set,  returns `null`. If `autoAddKeys` is set, the key is
    added on-the-fly with the default options, and returns the new

* `Generator#stop()`
  * stops the generator. No more IDs will be given to Accessors.
  1. new Accessor(port)

used to access IDs. port is the port number of your generator. In case where, you
did not specify a port when creating a Generator instance, you may
leave this out. Defaults to `9876`.
an accessor may be initialized in a separate file. Ensure you got the
port numbers correct.
an accessor has the following methods:
* `Accessor#next(key,callback)`:
  * callback signature: `function(err, id)`
  * asks the generator a new ID for **key**. If no key is
    given, uses the default one.
  * The new ID is passed to the callback, on success.
  * If the key doesn't exist and the generator doesn't have
    `autoAddKeys` set, an error is passed to the callback, and no
    ID is generated.
* `Accessor#ping(callback)`
  * callback signature: `function(err)`
  * pings the generator to see if it is online
All methods are asynchronous, the Node.js way


  • Robust Error handling
  • Implement these features:
* `session(callback)` - passes the number of IDs generated in the
* `.used(callback)` - passes the total number of IDs generated.
* `.semantics(callback)` - passes the remaining no. of IDs to be
  generated before breaking our semantics specified while creating
  the generator.


  • Source Code is hosted on Githubrepo
  • Pull requests be accompanied with tests as in the /tests directory
  • Issues may be filed hereissues

A list of contributors:


Copyright (c) 2014 Forfuture LLC
Sequential Ids and its source code are licensed under the MIT
mit license. See LICENSE file accompanying this text.