README.md

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

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.

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.

2. 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:

1. GochoMugo

• André Santos

license

Copyright (c) 2014 Forfuture LLC

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