sequential-ids

sequential ids

A Node.js module that allows centralized generation of sequential, unique and human-readable ids.

Sample Id: ACB - 00423

Aspect	Detail
version	0.0.0-alpha.2.0
dependencies	none
last updated	4th Sept, 2014

installation

From npmjs:

$ npm install sequential-ids --save

usage

        // assuming `db` is a variable holding a database object
        // with the method `.store(key, value)`
        // and `.read(key)`

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

        var generator = new sequential.Generator({
            digits: 6,
            letters: 3,
            store: function (ids) {
                db.store("last-id", ids[ids.length - 1]);
            },
            restore: (function () {
                return db.read("last-id");
            })()
        });

        var accessor = new sequential.Accessor()
        accessor.next(function (id) {
            console.log("First ID: " + id);
        });
        accessor.next(function (id) {
            console.log("Second ID: " + id);
        });

notes

1. new Generator([options])

   • you only require to create a single generator instance

   • 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, or a function called that returns a string as in example above.
       • Defaults to null.
     • port:
       • port at which the generator serves IDs.
       • Defaults to 9876.

   • 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});
     
     

• 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 has the following methods:

    • .next(callback):
      • requests generator for a new ID.
      • The new ID is passed to the callback.
    • .session(callback):
      • passes to callback, the total number of IDs generated in the session.

  • All methods are asynchronous, the Node.js way

TODO

• Robust Error handling
• Implement these features:
  • .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.

license

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

Copyright (c) 2014 Gocho Mugo [e-mail]