sequential-ids
v0.0.0
Published
centralized generation of sequential, human-readable ids
Downloads
128
Readme
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
ifkey
had already been added to the generator; otherwise, returnstrue
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
andletters
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, ornull
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, returnsnull
. IfautoAddKeys
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.
- callback signature:
Accessor#ping(callback)
- callback signature:
function(err)
- pings the generator to see if it is online
- callback signature:
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:
license
Copyright (c) 2014 Forfuture LLC
Sequential Ids and its source code are licensed under the MIT license. See LICENSE file accompanying this text.