Node-handlersocket NPM

node-handlersocket - Pure JavaScript client for HandlerSocket

node-handlersocket is a pure JavaScript client for HandlerSocket.

HandlerSocket is a NoSQL plugin for MySQL. See Matsunobu's blog for more information.

Requirements

Node.js (>= v0.6.0, tested with v0.6.10)
HandlerSocket Plugin for MySQL (>= v1.1.0, tested with v1.1.0)

Installation

npm install node-handlersocket

Examples

find (select)

var hs = require('node-handlersocket');

var con = hs.connect(function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.find('=', [1], function(err, records) {
      console.log(records[0]);
      con.close();
    });
  });
});

find (select) with limit and offset

var hs = require('node-handlersocket');

var con = hs.connect(function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.find('>=', [1], {limit: 10, offset: 0}, function(err, records) {
      records.forEach(function(record) {
        console.log(record);
      });
      con.close();
    });
  });
});

find (select) with IN

var hs = require('node-handlersocket');

var con = hs.connect(function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.find('=', [hs.in(1, 2, 3)], {limit: 10}, function(err, records) {
      records.forEach(function(record) {
        console.log(record);
      });
      con.close();
    });
  });
});

find (select) with filter

var hs = require('node-handlersocket');

var con = hs.connect(function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                ['EMPLOYEE_NO'],
                function(err, index) {
    index.find('>=', [1], {
                 filters: [hs.filter('EMPLOYEE_NO', '<', 7800)],
                 limit: 10
               },
               function(err, records) {
      records.forEach(function(record) {
        console.log(record);
      });
      con.close();
    });
  });
});

insert

var hs = require('node-handlersocket');

var con = hs.connect({port: 9999});
con.on('connect', function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.insert([100, 9999, 'KOICHIK'], function(err) {
      con.close();
    });
  });
});

update

var hs = require('node-handlersocket');

var con = hs.connect({port: 9999});
con.on('connect', function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY',
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.update('=', 100, [100, 9999, 'EBIYURI'], function(err, numRecords) {
      console.log(numRecords);
      con.close();
    });
  });
});

delete

var hs = require('node-handlersocket');

var con = hs.connect({port: 9999});
con.on('connect', function() {
  con.openIndex('test', 'EMPLOYEE', 'PRIMARY', 
                ['EMPLOYEE_ID', 'EMPLOYEE_NO', 'EMPLOYEE_NAME'],
                function(err, index) {
    index.delete('=', 100, function(err, numRecords) {
      console.log(numRecords);
      con.close();
    });
  });
});

API

hs.connect(options, connectListener)

Open a connection to HandlerSocket server.

Parameters
- options: (optional) an object with the following properties:
  - host: a host name or address (default is 'localhost').
  - port: a port number (default is 9998).
  - auth: an authentication key.
    Note, the port 9998 only allows read operations, and the port 9999 allows write operations also. See HandlerSocket installation document for more information.
- connectListener: (optional) It is automatically set as a listener for the 'connect' event.
Returns
- a new Connection object.

hs.in(values...)

Creates and returns an IN criterion object.

Parameters
- values: values of index.
Returns
- a new IN criterion object.

hs.filter(column, op, value)

Creates and returns a filter criterion object.

Parameters
- column: a column name used by this filter. It must be included in filterColumns specified Connection.openIndex().
- op: a filter operation, one of '=', '>', '>=', '<' and '<='.
- value: a value.
Returns
- a new filter object.

hs.while(column, op, value)

Creates and returns a while filter criterion object.

Parameters
- column: a column name used by this filter. It must be included in filterColumns specified Connection.openIndex().
- op: a filter operation, one of '=', '>', '>=', '<' and '<='.
- value: a value.
Returns
- a new while filter object.

Connection

An object representing connection to the HandlerSocket server. It is an instance of EventEmitter.

'connect' event

Emitted when a connection is established.

Callback function: function()

'close' event

Emitted once the connection is fully closed.

Callback function: function()

'error' event

Emitted when an error occurs.

Callback function: function(err)
- Parameters
  - err: an error that occurred.

Connection.prototype.openIndex(database, table, index, columns, filterColumns, callback)

Open an index.

Parameters
- database: a database name.
- table: a table name.
- index: an index name. If 'PRIMARY' is specified, the primary index is open.
- columns: an array of column names.
- filterColumns: (optional) an array of column names used by a filter.
- callback: a function to be called when the response received.
Callback function: function(err, index)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - index: a new Index object.

Connection.prototype.close()

Close the connection.

Index

An object representing MySQL's index.

Index.prototype.find(op, keys, options, callback)

To read records from a table using the index.

Parameters
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filters returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- callback: a function to be called when the response received.
Callback Function: function(err, records)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - records: an array of records. Each record is array of column values which corresponds to columns parameter of Connection.openIndex().

Index.prototype.insert(values, callback)

To add records.

Parametes
- values: an array of new column values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err)
- Parameters
  - err: an Error object when the request failed, otherwise null.

Index.prototype.update(op, keys, options, values, callback)

To update records.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of new column values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, numRecords)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - numRecords: a number of updated records.

Index.prototype.updateAndGet(op, keys, options, values, callback)

To update records and get values before they are updated.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of new column values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, records)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - records: an array of records before modification. Each record is an array of column values which corresponds to columns parameter of Connection.openIndex().

Index.prototype.increment(op, keys, options, values, callback)

To increment records.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of incremental values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, numRecords)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - numRecords: a number of updated records.

Index.prototype.incrementAndGet(op, keys, options, values, callback)

To increment records and get values before they are updated.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of incremental values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, records)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - records: an array of records before modification. Each record is an array of column values which corresponds to columns parameter of Connection.openIndex().

Index.prototype.decrement(op, keys, options, values, callback)

To decrement records.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of decremental values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, numRecords)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - numRecords: a number of updated records.

Index.prototype.decrementAndGet(op, keys, options, values, callback)

To decrement records and get values before they are updated.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- values: an array of decremental values which corresponds to columns parameter of Connection.openIndex().
- callback: a function to be called when the response received.
Callback Function: function(err, records)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - records: an array of records before modification. Each record is an array of column values which corresponds to columns parameter of Connection.openIndex().

Index.prototype.delete(op, keys, options, callback)

To delete records.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optionaal) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- callback: a function to be called when the response received.
Callback Function: function(err, numRecords)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - numRecords: a number of deleted records.

Index.prototype.deleteAndGet(op, keys, options, callback)

To delete records and get values before they are deleted.

Parametes
- op: a search operation, one of '=', '>', '>=', '<' and '<='.
- keys: an array of index values. It can include an IN criterion returned from hs.in().
- options: (optional) an object which specifies several options.
  - filters: an array of filter returned from hs.filter() and/or hs.while().
  - limit: a maximum number of records to be retrieved (defaults to 1).
  - offset: a number of records skipped before retrieving records (defaults to 0)．
- callback: a function to be called when the response received.
Callback Function: function(err, records)
- Parameters
  - err: an Error object when the request failed, otherwise null.
  - records: an array of records before deletion. Each is an array of column values which corresponds to columns parameter of Connection.openIndex().