node-hilo

NHibernate-style hi/lo ID generator for node.js

How to Use It

Requiring & Configuring

node-hilo exports a factory function that takes an instance of seriate, and a configuration object:

/*
	The configuration argument can contain the following:
	{
		hilo: {
			maxLo: 10 // an integer value for maxLo
		},
		// sql is a config object that seriate would understand
		sql: {
			user: "you_me_anyone",
			password: "superseekret",
			server: "some.server.com",
			database: "meh_databass"
		}
	}
*/
var hilo = require( "node-hilo" )( seriate, configuration );

How to Use

node-hilo exports two module members: a nextId method and a read-only property called hival. You will likely never need to care about the hival value - it's there for diagnostics and testing. The nextId method returns a promise, with the newly generated ID being passed to the success callback:

hilo.nextId(
	function( id ){
		// Now you can use the id on your object, etc.
		api.saveNewThing( id, newThing );
	},
	function( err) {
		console.log( "O NOES!", err );
	}
);

The More You Know...

JavaScript doesn't natively support 64 bit integers - we're using a helper lib (big-integer) to allow us to properly represent them. Because of this, the generated IDs are passed back as strings (even though they're long values). You will need to ensure your DB server converts/casts them to long (which SQL will normally implicitly do for you).

If you'd like to learn more about the hi/lo algorithm:

Tests, etc

If you plan to run the integration tests, you will need access to an MS SQL server. Create a test database that can be used (the integration tests create two tables), and save a configuration file called intTestDbCfg.json under the spec/integration folder. Your configuration file will look similar to this:

{
	"sql": {
		"user": "dbuser",
		"password": "dbuserpwd",
		"server": "localhost",
		"database": "nhutil"
	},
	"hilo": {
		"maxLo": 100
	},
	"test" : {
		"recordsToCreate" : 15000,
		"startingHiVal" : "314159265"
	}
}

I recommend copying the following into a local file by that name and updating the sql information, leaving the rest alone.