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] |