Initial commit

Author: numtel

.gitignore

@@ -0,0 +1,5 @@
+*.*~
+*.swp
+*.swo
+.npm
+node_modules

README.md

@@ -0,0 +1,97 @@
+# mysql-live-select
+
+NPM Package to provide events when a MySQL select statement result set changes.
+
+Built using the [`zongji` Binlog Tailer](https://github.com/nevill/zongji) and [`node-mysql`](https://github.com/felixge/node-mysql) projects.
+
+## Installation
+
+* Enable MySQL binlog in `my.cnf`, restart MySQL server after making the changes.
+
+  ```
+  # binlog config
+  server-id        = 1
+  log_bin          = /usr/local/var/log/mysql/mysql-bin.log
+  binlog_do_db     = employees   # optional
+  expire_logs_days = 10          # optional
+  max_binlog_size  = 100M        # optional
+
+  # Very important if you want to receive write, update and delete row events
+  binlog_format    = row
+  ```
+* Create an account with replication privileges:
+
+  ```sql
+  GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user'@'localhost'
+  ```
+
+## LiveMysql Constructor
+
+The `LiveMysql` constructor makes 3 connections to your MySQL database:
+
+* Connection for executing `SELECT` queries
+* Replication slave connection
+* `information_schema` connection for column information
+
+One argument, an object defining the settings. In addition the [`node-mysql` connection settings](#...), the following settings are available:
+
+Setting | Type | Description
+--------|------|------------------------------
+`serverId`  | `integer` | [Unique number (1 - 2<sup>32</sup>)](http://dev.mysql.com/doc/refman/5.0/en/replication-options.html#option_mysqld_server-id) to identify this replication slave instance. Must be specified if running more than one instance.<br>**Default:** `1`
+`minInterval` | `integer` | Pass a number of milliseconds to use as the minimum between result set updates. Omit to refresh results on every update.
+
+### LiveMysql.prototype.select(query, triggers)
+
+Argument | Type | Description
+---------|------|----------------------------------
+`query`  | `string` or `function` | `SELECT` SQL statement. See note below about passing function.
+`triggers` | `[object]` | Array of objects defining which row changes to update result set
+
+Returns `LiveMysqlSelect` object
+
+#### Function as `query`
+
+A function may be passed as the `query` argument that accepts two arguments.
+
+* The first argument, `esc` is a function that escapes values in the query.
+* The second argument, `escId` is a function that escapes identifiers in the query.
+
+#### Trigger options
+
+Name | Type | Description
+-----|------|------------------------------
+`table` | `string` | Name of table (required)
+`database` | `string` | Name of database (optional, default to `database` setting specified on connection)
+`condition` | `function` | Evaluate row values (optional)
+
+#### Condition Function
+
+A condition function accepts one or two arguments:
+
+Argument Name | Description
+--------------|-----------------------------
+`row`         | Table row data
+`newRow`      | New row data (only available on `UPDATE` queries)
+
+Return `true` when the row data meets the condition to update the result set.
+
+#### Example
+
+```javascript
+// Example:
+var table = 'my_table';
+var id = 11;
+
+liveMysqlInstance.select(function(esc, escId){
+  return (
+    'select * from ' + escId(table) +
+    'where `id`=' + esc(id)
+  );
+}, [
+  table: table,
+  condition: function(row, newRow){ return row.id === id; }
+]).on('update', function(data){
+  console.log(data);
+});
+```
+

example.js

@@ -0,0 +1,32 @@
+var LiveMysql = require('./');
+
+var settings = {
+  host        : 'localhost',
+  user        : 'root',
+  password    : 'numtel',
+  database    : 'leaderboard',
+  serverId    : 34,
+  minInterval : 200
+  // debug: true
+};
+
+var liveConnection = new LiveMysql(settings);
+// var result = liveConnection.select(
+//   'select * from players',
+//   [
+//     { table: 'players' }
+//   ]
+// );
+// result.on('update', function(event){
+//   // do something to update the client
+//   console.log(event);
+// });
+
+liveConnection.select('select score from players where id=11', [
+  {
+    table: 'players',
+    condition: function(row, newRow){ return row.id === 11; }
+  }
+]).on('update', function(event){
+  console.log(event);
+});

index.js

@@ -0,0 +1,117 @@
+var ZongJi = require('zongji');
+var mysql = require('mysql');
+var EventEmitter = require('events').EventEmitter;
+var util = require('util');
+
+function LiveMysql(settings){
+  var self = this;
+  var zongji = new ZongJi(settings);
+  var db = mysql.createConnection(settings);
+
+  self.settings = settings;
+  self.zongji = zongji;
+  self.db = db;
+  self._select = [];
+
+  db.connect();
+
+  zongji.on('binlog', function(event) {
+    if(event.getEventName() === 'tablemap') return;
+
+    self._select.forEach(function(select){
+      if(select.matchRowEvent(event))
+        select.update();
+    });
+  });
+
+  zongji.start({
+    serverId: settings.serverId,
+    startAtEnd: true,
+    includeEvents: [ 'tablemap', 'writerows', 'updaterows', 'deleterows' ]
+  });
+}
+
+LiveMysql.prototype.select = function(query, triggers){
+  var self = this;
+  var newSelect = new LiveMysqlSelect(query, triggers, this);
+  self._select.push(newSelect);
+  return newSelect;
+};
+
+function LiveMysqlSelect(query, triggers, base){
+  if(!query)
+    throw new Error('query required');
+  if(!(triggers instanceof Array))
+    throw new Error('triggers array required');
+  if(!(base instanceof LiveMysql))
+    throw new Error('base LiveMysql instance required');
+
+  var self = this;
+  EventEmitter.call(self);
+  self.query = self._escapeQueryFun(query);
+  self.triggers = triggers;
+  self.base = base;
+  self.lastUpdate = 0;
+
+  self.update();
+}
+
+util.inherits(LiveMysqlSelect, EventEmitter);
+// util.inherits(LiveMysqlSelect, Array);
+
+
+LiveMysqlSelect.prototype._escapeQueryFun: function(query){
+  var self = this;
+  if(typeof query === 'function'){
+    var escId = self.base.db.escapeId;
+    var esc = self.base.db.escape.bind(self.base.db);
+    return query(esc, escId);
+  }
+  return query;
+};
+
+LiveMysqlSelect.prototype.matchRowEvent = function(event){
+  var self = this;
+  var tableMap = event.tableMap[event.tableId];
+  var eventName = event.getEventName();
+  var trigger, row;
+  for(var i = 0; i < self.triggers.length; i++){
+    trigger = self.triggers[i];
+    triggerDatabase = trigger.database ||
+      self.base.settings.database;
+    if(triggerDatabase === tableMap.parentSchema &&
+       trigger.table === tableMap.tableName){
+      if(trigger.condition === undefined){
+        return true;
+      }else{
+        for(var r = 0; r < event.rows.length; r++){
+          row = event.rows[r];
+          if(eventName === 'updaterows'){
+            return trigger.condition.call(self, row.before, row.after);
+          }else{
+            // writerows or deleterows
+            return trigger.condition.call(self, row);
+          }
+        }
+      }
+    }
+  }
+  return false;
+};
+
+LiveMysqlSelect.prototype.update = function(){
+  var self = this;
+  if(self.base.settings.minInterval === undefined ||
+     self.lastUpdate + self.base.settings.minInterval < Date.now()){
+    self.base.db.query(self.query, function(error, rows){
+      if(error){
+        self.emit('error', error);
+      }else{
+        self.lastUpdate = Date.now();
+        self.emit('update', rows);
+      }
+    });
+  }
+};
+
+module.exports = LiveMysql;

package.json

@@ -0,0 +1,18 @@
+{
+  "name": "mysql-live-select",
+  "version": "0.0.1",
+  "description": "Live updating MySQL SELECT statements",
+  "main": "index.js",
+  "scripts": {
+    "test": "nodeunit --reporter=minimal test"
+  },
+  "keywords": [
+    "mysql",
+    "binlog",
+    "select",
+    "live",
+    "update"
+  ],
+  "author": "Ben Green <ben@latenightsketches.com> (http://github.com/numtel)",
+  "license": "MIT"
+}