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 = ; var con = hs;
find (select) with limit and offset
var hs = ; var con = hs;
find (select) with IN
var hs = ; var con = hs;
find (select) with filter
var hs = ; var con = hs;
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 is9998
). -
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.
- a new
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 infilterColumns
specifiedConnection.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 infilterColumns
specifiedConnection.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.
- Parameters
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
: anError
object when the request failed, otherwisenull
.index
: a newIndex
object.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filters returned fromhs.filter()
and/orhs.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
: anError
object when the request failed, otherwisenull
.records
: an array of records. Each record is array of column values which corresponds tocolumns
parameter ofConnection.openIndex()
.
- Parameters
Index.prototype.insert(values, callback)
To add records.
- Parametes
- values: an array of new column values which corresponds to
columns
parameter ofConnection.openIndex()
. callback
: a function to be called when the response received.
- values: an array of new column values which corresponds to
- Callback Function:
function(err)
- Parameters
err
: anError
object when the request failed, otherwisenull
.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, numRecords)
- Parameters
err
: anError
object when the request failed, otherwisenull
.numRecords
: a number of updated records.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, records)
- Parameters
err
: anError
object when the request failed, otherwisenull
.records
: an array of records before modification. Each record is an array of column values which corresponds tocolumns
parameter ofConnection.openIndex()
.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, numRecords)
- Parameters
err
: anError
object when the request failed, otherwisenull
.numRecords
: a number of updated records.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, records)
- Parameters
err
: anError
object when the request failed, otherwisenull
.records
: an array of records before modification. Each record is an array of column values which corresponds tocolumns
parameter ofConnection.openIndex()
.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, numRecords)
- Parameters
err
: anError
object when the request failed, otherwisenull
.numRecords
: a number of updated records.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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 ofConnection.openIndex()
. callback
: a function to be called when the response received.
- Callback Function:
function(err, records)
- Parameters
err
: anError
object when the request failed, otherwisenull
.records
: an array of records before modification. Each record is an array of column values which corresponds tocolumns
parameter ofConnection.openIndex()
.
- Parameters
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 fromhs.in()
.options
: (optionaal) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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
: anError
object when the request failed, otherwisenull
.numRecords
: a number of deleted records.
- Parameters
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 fromhs.in()
.options
: (optional) an object which specifies several options.filters
: an array of filter returned fromhs.filter()
and/orhs.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
: anError
object when the request failed, otherwisenull
.records
: an array of records before deletion. Each is an array of column values which corresponds tocolumns
parameter ofConnection.openIndex()
.
- Parameters
Test
node-handlersocket depends on Vows for unit testing.
npm test
Limitations
The encoding of MySQL server (default-character-set
parameter in [mysqld]
section)
which node-handlersocket supports is only UTF-8.
Binary data types are not supported.
License
node-handlersocket is licensed under the MIT license.