sequential-ids
Version:
centralized generation of sequential, human-readable ids
225 lines (172 loc) • 7.17 kB
Markdown
# node-sequential-ids
[](https://travis-ci.org/forfuture-dev/node-sequential-ids)
A [Node.js][nodejs] 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][npmjs]:
```bash
$ npm install sequential-ids --save
```
## usage
```js
// 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.
```js
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][repo]
* Pull requests be accompanied with tests as in the `/tests` directory
* Issues may be filed [here][issues]
A list of contributors:
1. [GochoMugo](https://github.com/GochoMugo)
* [André Santos](https://github.com/andrefs)
## license
Copyright (c) 2014 Forfuture LLC
Sequential Ids and its source code are licensed under the [MIT][mit]
license. See [LICENSE](LICENSE) file accompanying this text.
[issues]:https://github.com/forfuture-dev/node-sequential-ids/issues
[mit]:https://opensource.org/licenses/MIT
[nodejs]:https://nodejs.org
[npmjs]:https://npmjs.org/sequential-ids
[repo]:https://github.com/forfuture-dev/node-sequential-ids