node-sequential-ids

A Node.js 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

installation

From Npm:

$ npm install sequential-ids --save

usage

// 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) {
    db.store(key, ids[ids.length - 1]);
  },
  restore: "AAB - 000"
});

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

generator.start();
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();
accessor.next(function(err, id) {
  console.log("new id: %s", id); // => AAB - 003
});

accessor.next('otherKey',function(err, id) {
  console.log("new id (otherKey): %s", id); // => A - 03
});

notes

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.

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 persistence.
      - the function is passed an array of IDs that have been generated.
      - 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 Generator
      - 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 returned.
      - 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 ID.
- Generator#stop()
  - stops the generator. No more IDs will be given to Accessors.

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

TODO

Robust Error handling
Implement these features:
- session(callback) - passes the number of IDs generated in the session.
- .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.

contribution

Source Code is hosted on Github
Pull requests be accompanied with tests as in the /tests directory
Issues may be filed here

A list of contributors:

GochoMugo

André Santos

license

Sequential Ids and its source code are licensed under the MIT license. See LICENSE file accompanying this text.

chaddjohnson / node-sequential-ids