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 = ; var generator = digits: 6 letters: 3 { db; } restore: "AAB - 000"; generator; generatorstart;var new_id_1 = generator; // => AAB - 001var new_id_2 = generator; // => AAB - 002// ...var other_id_1 = generator; // => A - 01var other_id_2 = generator; // => A - 02// ... // possibly in another filevar accessor = ;accessornext { console; // => AAB - 003}; accessornext'otherKey' { console; // => 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 = ;var generatorA = port: 8998;var generatorB = 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.