n a r w a l

alpha - do not use (yet)

narwal (NodeJS) is a loosely coupled structure-data architecture for modeling and moving around your MySQL data.

Install

npm install narwal

Use

var narwal = require('narwal');

Overview

narwal gives you model abstraction so you manipulate your MySQL data and structure easier.

// Create a model representation of a table called players
// This table must exists with a matching structure as the one modelized
 
var Player = new narwal.Model('Player', { name: String, score: Number, joined: Date });

SELECT name FROM players WHERE score > 100 LIMIT 10 ORDER BY joined DESC

Player // SELECT
 
  // column selection
  
  .select('name')
  
  // WHERE score > 100
  
  .above({ 'score': 100 })
  
  // LIMIT 10
  
  .filter(10)
  
  // ORDER BY joined DESC
  
  .sort({ 'joined': false })
  
  // Do something with the results
  
  .forEach(function (player) {
    console.log(player);
  });

INSERT INTO players (name) VALUES('Lara')

Player
 
  // INSERT INTO players (name) VALUES('Lara')
  .push({ name: 'Lara' })
  
  // Do something with results
  .pushed(function (player) {
    console.log('New player created', player);
  });

UPDATE players SET score=100 WHERE name='Lara'

Player
  
  .update({ name: 'Lara' }, { score: 100 })
  
  .updated(function (players) {
    console.log

DELETE FROM players WHERE score > 100

Player
  // DELETE FROM players WHERE score = 100
  .remove({ score: 100 })
  
  .removed(function () {});

Model

Model constructor

Creates a new Narwal Model.

{Model} new narwal.Model(String name, Object? structure, Object? options);

Argument	Type	Required	Default	Description
name	String	✔		The name of the model
structure	Object	✖	{}	The structure
options	Object	✖	{}	Model options

new narwal.Model('Player', { name: String }, { prefix: 'test_' });

Model connect()

MySQL thread setter. Narwal models are connexion-agnostic. We use node-mysql default connection method for the moment. Future implementations to come.

{Model} Model.connect(String | Object);

 
var Player = require('./models/Player');
 
Player.forEach(fn);
 
Player.connect('mysql://user@localost/db');
  
// You can also a Narwal client
 
var Client = require('narwal').Client;
 
var client = new Client('mysql://user@localost/db');
 
Player.connect(client).stream().limit(100000).rows(1000);

Events:

• error Error
• connected
• disconnected

Helpers:

Name	Example	Description
connected	client().connected(Function connected)	Listens on "connected"
disconnected	client().disconnected(Function disconnected)	Listens on "disconnected"

Model create()

Create a table stucture from Model. Returns Query.

{Query} Model.create(Object? options, Function? callback)

CREATE TABLE players (
  id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
  name VARCHAR NOT NULL,
  score INT NOT NULL DEFAULT 500)
  ENGINE=INNODB DEFAULT CHARSET utf-8

new narwal
 
  .Model('Player', {
    'name': String,
    'score': {
      'type': Number,
      'default': 500
    }
  })
  
  .create();

Events:

• error Error
• success

Helpers:

Name	Example	Description
created	create().created(Function success)	Listens on "success"

Model filter()

Performs a filter query. Returns Query.

{Query} Model.filter(Object filter)

SELECT FROM models WHERE field='value'

Model.filter({ field: 'value' });

Events:

• error Error
• success [Row]

Helpers:

Name	Example	Description
found	find().found(Function success)	Listens on "success" and [Row].length
notFound	find().notFound(Function success)	Listens on "success" and ! [Row].length
forEach	find().forEach(function (model) { //... }})	Listens on "success" and for each [Row]

Model find()

Performs a find query. Returns Find.

{Query} Model.find(Mixed? filter)

 
// Find all
 
Model.find();
 
// Sugar for Model.find().filter(Object);
 
Model.find({ field: 'value' });
 
// Sugar for Model.find().limit(Number);
 
Model.find(10);

Events:

• error Error
• success [Row]

Helpers:

Name	Example	Description
found	find().found(Function success)	Listens on "success" and [Row].length
notFound	find().notFound(Function success)	Listens on "success" and ! [Row].length
forEach	find().forEach(function (model) { //... }})	Listens on "success" and for each [Row]

Model findById()

Performs a find query with a filter by id. Returns Query.

Model.findById(Number)

 
// Find by id
 
Model.findById(3837283);

Events:

• error Error
• success [Row]

Helpers:

Name	Example	Description
found	findById().found(Function success)	Listens on "success" and [Row].length
notFound	findById().notFound(Function success)	Listens on "success" and ! [Row].length

Model findOne()

Performs a find query and returns first found. Returns Query. Success emits a Row object.

Model.findOne(Mixed? filter)

 
// Find one with no filter
 
Model.findOne();
 
// Sugar for Model.findOne().filter(Object);
 
Model.findOne({ field: 'value' });

Events:

• error Error
• success Row

Helpers:

Name	Example	Description
found	findOne().found(Function success)	Listens on "success" and Row
notFound	findOne().notFound(Function success)	Listens on "success" and ! Row

Model limit()

Apply a limit filter. Returns Query. Success emits [Row].

{Query} Model.limit(Number limit).success([Row])

 
// Find 10
 
Model.limit(10);
 
// Find one (will return an array, even if it has only one row in it)
 
Model.limit(1);

Events:

• error Error
• success [Row]

Helpers:

Name	Example	Description
found	limit().found(Function success)	Listens on "success" and [Row].length
notFound	limit().notFound(Function success)	Listens on "success" and ! [Row].length
forEach	find().forEach(function (model) { //... }})	Listens on "success" and for each [Row]