model

TOC

• Overview
• Bootstrapping Model
• Defining Models

• Creating instances
• Validations

• Saving items
• Updating items
• Removing items
• Lifecycle events
• Associations

• Querying

• More complex queries
• Options: sort, skip, limit

• Eager loading of associations (SQL adpaters only)

Overview

• Postgres
• MySQL
• SQLite
• Riak
• MongoDB
• LevelDB
• In-memory
• Filesystem

License

Prerequisites

Installing with NPM

NPM install model

Bootstrapping Model

var model = require('model');

// Setup the blueprint of the model. This is where you can
// setup the model properties, defaults, and validations
var Foo = function () {
  this.setAdapter('level', {
    db: './data'
  });

  // Define the whitelisted properties on the model.
  // Properties not listed wont be saved
  this.defineProperties({
    name: { type: 'string', required: true },
    description: { type: 'text' },
    enabled: { type: 'boolean' },
    archived: { type: 'boolean' },
  });
};

// This registers the model with the model package so
// things like associations can work
Foo = model.register('Foo', Foo);

// Now we export Foo to create a reusable model module
module.exports = Foo;

var Foo = require('./foo.js');
Foo.first(1, function (err, model) {
  // Check if there was an error with the DB
  if (err) throw new Error('Uh oh, something broke');

  // If there was no error, but no model was found it must be missing
  if (!err && !model) throw new Error('Foo not found');

  // Update the model's name property
  model.name = "New name!";

  // Once we're done updating properties we can call save on the model.
  // Save will send the current model data to the DB you specified
  model.save(function (err, updatedModel) {
    if (err) throw new Error('Could not save the model');
    console.log("The model was updated!");
  });
});

Defining models

var User = function () {
  this.property('login', 'string', {required: true});
  this.property('password', 'string', {required: true});
  this.property('lastName', 'string');
  this.property('firstName', 'string');

  this.validatesPresent('login');
  this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
  this.validatesLength('login', {min: 3});
  this.validatesConfirmed('password', 'confirmPassword');
  this.validatesWithFunction('password', function (s) {
      if (password.indexOf('login')) {
          // Returning a string indicates that the validation has failed.
          // The string will be used as the message.
          return "Password must not contain your username";
      }
      return true;
  });

  this.someMethod = function () {
    // Do some stuff
  };
};

// prepares the model and adds it as a property on `model`
User = model.register('User', User);

Setting an adapter

var model = require('model');

var Foo = function () {
  this.setAdapter('mongo', {
    "hostname":"localhost",
    "port":27017,
    "username":"",
    "password":"",
    "dbName":"mydatabase"
  });

  this.defineProperties({
    name: { type: 'string', required: true }
  });
};

Foo = model.register('Foo', Foo);

module.exports = Foo;

Defining properties

var User = function () {
  this.defineProperties({
    login: {type: 'string', required: true}
  , password: {type: 'string', required: true}
  , lastName: {type: 'string'}
  , firstName: {type: 'string'}
  });
}

Datatypes

• string
• text
• number
• int
• boolean
• date
• datetime
• time
• object

Custom Methods

var User = function () {
    this.property('email', 'string');
    this.property('sendUpdates', 'boolean');

    // setting a property on `this` in the constructor creates an instance method
    this.sendConfirmation = function (callback) {
        // send confirmation message
    }
}

// setting a property on the prototype creates an instance method
User.prototype.sendNewsletter = function (callback) {
    // send newsletter
}

// setting a property on the constructor creates a class method
User.sendNewsletters = function (callback) {
    // send newsletter to users that opted into updates
}

User = model.register('User', User);

Adapters

How to install adapters

• Postgres: npm install pg --save
• MySQL: npm install mysql --save
• SQLite: npm install sqlite3 --save
• MongoDB: npm install mongodb --save
• LevelDB: npm install level --save

model.createAdapter(name, config)

var adapter = model.createAdapter('postgres', {
, host: 'localhost'
, username: 'user'
, password: 'password'
, database: 'mydb'
});

model.config.defaultAdapter

model.config.defaultAdapter = model.createAdapter('postgres', {
  host: 'localhost',
  username: 'user',
  password: 'password',
  database: 'mydb'
});

adapter.connect(cb)

myAdapter.connect(function (err) {
  if (err) throw new Error('Error: ' + err);
  console.log('Database connection successful');
}

adapter.disconnect(cb)

myAdapter.disconnect(function (err) {
  if (err) throw new Error('Error: ' + err);
  console.log('Database disconnected successfully');
}

adapter.addListener('connect', callback)

myAdapter.addListener('connect', function () {
  console.log('Database connection successful');
});

adapter.addListener('disconnect', callback)

myAdapter.addListener('disconnect', function () {
  console.log('Database disconnected successfully');
});

adapter.addListener('error', callback)

myAdapter.addListener('error', function (err) {
  throw new Error('Error: ' + err);
});

Creating instances

var params = {
  login: 'alex'
, password: 'lerxst'
, lastName: 'Lifeson'
, firstName: 'Alex'
};
var user = User.create(params);

Validations

var User = function () {
  this.property('login', 'string', {required: true});
  this.property('password', 'string', {required: true});
  this.property('lastName', 'string');
  this.property('firstName', 'string');

  this.validatesPresent('login');
  this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
  this.validatesLength('login', {min: 3});
  this.validatesConfirmed('password', 'confirmPassword');
  this.validatesWithFunction('password', function (s) {
      // Something that returns true or false
      return s.length > 0;
  });
  this.validatesAbsent('unconfirmed');
  this.validatesWithFunction('password', function (value, model) {
      // if the function returns false it will use a standard message
      if (typeof value != typeof "") {
      	 return false;
      }

      // if it returns a string the string will be used as an error message
      if  (value.length <= 3) {
      	 return "Your password must be at least 4 characters long ";
      }

      // return true if the validation passed
      return true;
  });

  // methods for instances can be defined in the constructor like this
  this.someMethod = function () {
    // Do some stuff
  };
};

Common validation options

var Zerb = function () {
  this.property('name', 'string');
  this.validatesLength('name', {is: 3, message: 'Try again, gotta be 3!'});
};

var User = function () {
  this.property('name', 'string', {required: false});
  this.property('password', 'string', {required: false});

  this.validatesLength('name', {min: 3, on: ['create', 'update']});
  this.validatesPresent('password', {on: 'create'});
  this.validatesConfirmed('password', 'confirmPassword', {on: 'create'});
};

// Name validation will pass, but password will fail
myUser = User.create({name: 'aaa'});

// Force validation with the `reify` scenario, ignore the too-short name property
myUser = User.create({name: 'aa'}, {scenario: 'reify'});

// You can also specify a scenario with these methods:
// Enforce 'create' validations on a fetch -- may result in invalid instances
User.first(query, {scenario: 'create'}, cb);
// Do some special validations you need for credit-card payment
User.updateProperties(newAttrs, {scenario: 'creditCardPayment'});

Validation errors

// Leaving out the required password field
var params = {
  login: 'alex'
};
var user = User.create(params);

// Prints 'false'
console.log(user.isValid());
// Prints 'Field "password" is required'
console.log(user.errors.password);

Saving items

if (user.isValid()) {
  user.save(function (err, data) {
    if (err) {
      throw err;
    }
    console.log('New item saved!');
  });
}

Updating items

user.updateProperties({
  login: 'alerxst'
});
if (user.isValid()) {
  user.save(function (err, data) {
    if (err) {
      throw err;
    }
    console.log('Item updated!');
  });
}

Removing items

model.User.remove(user.id, function(err) {
  if (err) {
    throw err;
  }
  console.log('Item removed!');
});

Lifecycle events

var User = function () {
  this.property('name', 'string', {required: false});

  // Make sure there's a name in the params before validating
  this.beforeValidate = function (params) {
    params.name = params.name || 'Zerp Derp';
  };
};

var User = function () {
  this.property('login', 'string', {required: true});
  this.property('password', 'string', {required: true});
  this.property('confirmPassword', 'string', {required: true});

  this.hasOne('Profile');
  this.hasMany('Accounts');
};

var Profile = function() {
  // properties

  this.belongsTo('Account');
};

var Account = function() {
  // properties

  this.belongsTo('User');
};

// Names in association methods must match the names that models are registered with.
// The name given to hasMany is pluralized.
User = model.register('User', User);
Profile = model.register('Profile', Profile);
Account = model.register('Account', Account);

var user = User.create({
  login: 'asdf'
, password: 'zerb'
, confirmPassword: 'zerb'
});
user.save(function (err, data) {
  var profile;
  if (err) {
    throw err;
  }
  profile = Profile.create({});
  user.setProfile(profile);
  user.save(function (err, data) {
    if (err) {
      throw err;
    }
    user.getProfile(function (err, data) {
      if (err) {
        throw err;
      }
      console.log(profile.id ' is the same as ' + data.id);
    });
  });
});

var user = User.create({
  login: 'asdf'
, password: 'zerb'
, confirmPassword: 'zerb'
});
user.save(function (err, data) {
  if (err) {
    throw err;
  }
  user.addAccount(Account.create({}));
  user.addAccount(Account.create({}));
  user.save(function (err, data) {
    if (err) {
      throw err;
    }
    user.getAccounts(function (err, data) {
      if (err) {
        throw err;
      }
      console.log('This number should be 2: ' + data.length);
    });
  });
});

var book = Book.create({
  title: 'How to Eat an Entire Ham'
, description: 'Such a poignant book. I cried.'
});
book.save(function (err, data) {
  if (err) {
    throw err;
  }
  book.setAuthor(Author.create({
    familyName: 'Neeble'
  , givenName: 'Leonard'
  }));
  book.save(function (err, data) {
    if (err) {
      throw err;
    }
    book.getAuthor(function (err, data) {
      if (err) {
        throw err;
      }
      console.log('This name should be "Neeble": ' + data.familyName);
    });
  });
});

User.first({login: 'asdf'}, function (err, user) {
  if (err) {
    throw err;
  }
  // Fetch accounts
  user.getAccounts(function (err, accounts) {
    var originalCount;
    if (err) {
      throw err;
    }
    originalCount = accounts.length;

    // Remove the first account
    user.removeAccount(accounts[0]);
    // Save the user
    user.save(function (err) {
      if (err) {
        throw err;
      }
      // Fetch accounts again
      user.getAccounts(function (err, accounts) {
        if (err) {
          throw err;
        }
        Console.log(accounts.length + ' should be one less than ' +
            originalCount);
      });
    });
  });
});

var Player = function () {
  this.property('familyName', 'string', {required: true});
  this.property('givenName', 'string', {required: true});
  this.property('jerseyNumber', 'string', {required: true});

  this.hasMany('Memberships');
  this.hasMany('Teams', {through: 'Memberships'});
};

var Team = function () {
  this.property('name', 'string', {required: true});

  this.hasMany('Memberships');
  this.hasMany('Players', {through: 'Memberships'});
};

var Membership = function () {
  this.belongsTo('User');
  this.belongsTo('Team');
};

var User = function () {
  this.property('familyName', 'string', {required: true});
  this.property('givenName', 'string', {required: true});

  this.hasMany('Kids', {model: 'Users'});
};

var Team = function(){
  this.hasMany('Players');
  this.hasMany('Coaches', {through: 'TeamCoaches', model: 'Players'});
};
var TeamCoaches = function(){
  this.belongsTo('CoachedTeam', {model: 'Team'});
  this.belongsTo('Coach', {model: 'Player'});
}
var Player = function(){
  this.hasMany('Teams');
  this.hasMany('CoachedTeams', {through: 'TeamCoaches', model: 'Team'});
}

var user;
User.first({login: 'alerxst'}, function (err, data) {
  if (err) {
    throw err;
  }
  user = data;
  console.log('Found user');
  console.dir(user);
});

var users
  , dt;

dt = new Date();
dt.setHours(dt.getHours() - 24);

// Find all the users created since yesterday
User.all({createdAt: {gt: dt}, function (err, data) {
  if (err) {
    throw err;
  }
  users = data;
  console.log('Found users');
  console.dir(users);
});

var users
  , dt
  , processor;

dt = new Date();
dt.setHours(dt.getHours() - 24);

// Find all the users created since yesterday
processor = User.all({createdAt: {gt: dt});
processor.on('data', function (user) {
  console.log('Found user');
  console.dir(user);
});
processor.on('error', function (err) {
  console.log('whoops');
  throw err;
});
processor.on('end', function () {
  console.log('No more users');
});

// Where "foo" is 'BAR' and "bar" is not null
{foo: 'BAR', bar: {ne: null}}
// Where "foo" begins with 'B'
{foo: {'like': 'B'}}
// Where foo is less than 2112, and bar is 'BAZ'
{foo: {lt: 2112}, bar: 'BAZ'}

// Zoobies whose "foo" begin with 'b', with no case-sensitivity
Zooby.all({foo: {'like': 'b'}}, {nocase: true}, ...
// Zoobies whose "foo" begin with 'b' and "bar" is 'baz'
// The "bar" comparison will be case-sensitive, and the "foo" will not
Zooby.all({or: [{foo: {'like': 'b'}}, {bar: 'baz'}]}, {nocase: ['foo']},

More complex queries

// Where "foo" is 'BAR' OR "bar" is 'BAZ'
{or: [{foo: 'BAR'}, {bar: 'BAZ'}]}
// Where "foo" is not 'BAR' OR "bar" is null OR "baz" is less than 2112
{or: [{foo {ne: 'BAR'}}, {bar: null}, {baz: {lt: 2112}}]}

// Where NOT ("foo" is 'BAR' and "bar" is 'BAZ')
{not: {foo: 'BAR', bar: 'BAZ'}}
// Where NOT ("foo" is 'BAZ' and "bar" is less than 1001)
{not: {foo: 'BAZ', bar: {lt: 1001}}}

// Where ("foo" is like 'b' OR "foo" is 'foo') and NOT "foo" is 'baz'
{or: [{foo: {'like': 'b'}}, {foo: 'foo'}], not: {foo: 'baz'}}

Options: sort, skip, limit

Sorting

var users
// Find all the users who have ever been updated, and sort by
// creation-date, ascending, then last name, descending
User.all({updatedAt: {ne: null}}, {sort: {createdAt: 'asc', lastName: 'desc'}},
    function (err, data) {
  if (err) {
    throw err;
  }
  users = data;
  console.log('Updated users');
  console.dir(users);
});

Simplified syntax for sorting

// Sort by createdAt, ascending
{sort: 'createdAt'}
// Sort by createdAt, then updatedAt, then lastName,
// then firstName -- all ascending
{sort: ['createdAt', 'updatedAt', 'lastName', 'firstName']}

Skip and limit

// Returns items 501-600
{skip: 500, limit: 100}

Eager loading of associations (SQL adapters only)

var opts = {
  includes: ['players']
, sort: {
    name: 'desc'
  , 'players.familyName': 'desc'
  , 'players.givenName': 'desc'
  }
};
Team.all({}, opts, function (err, data) {
  var teams;
  if (err) {
    throw err;
  }
  teams = data;
  teams.forEach(function (team) {
    console.log(team.name);
    team.players.forEach(function (player) {
      console.log(player.familyName + ', ' + player.givenName);
    });
  });
});

Eager loading of nested associations

Team.all({}, {includes: {players: 'sponsors'}}, function (err, data) {});

Team.all({}, {includes: [{players: 'sponsors'}, 'investors']}, function (err, data) {});

Team.all({}, {includes: {players: 'sponsors', investors: 'spouse'}, function (err, data) {});

Person.all({}, {includes: {friends: {friends: 'friends'}}, function (err, data) {});

Team.all({'players.sponsors.name': 'Daffy Duck'}, {includes: {players: 'sponsors'}}, function (err, data) {});

Sorting results

{sort: 'players.sponsors.id'}

Limitations when eager loading

// Good
Team.all({'players.sponsors.name': 'Daffy Duck'}
        , {includes: {players: 'sponsors'}}
        , function (err, data) {});

// Bad
Team.all({'players.sponsors.name': 'Daffy Duck'}
        , {includes: 'players'}
        , function (err, data) {});

// Bad
Team.all({'players.sponsors.name': 'Daffy Duck'}
        , {includes: {players: 'sponsors'}, limit: 5}
        , function (err, data) {});

// Bad too, since .first is an implicit "limit: 1"
Team.first({'players.sponsors.name': 'Daffy Duck'}
        , {includes: {players: 'sponsors'}, limit: 5}
        , function (err, data) {});

// Streaming API will work, the sort clause will be modified to ['id', 'players.name']
Team.all({'players.sponsors.name': 'Daffy Duck'}
        , {includes: {players: 'sponsors'}, sort: ['players.name']});

// Streaming API will still work, but results will only be sent at the end of the query
Team.all({'players.sponsors.name': 'Daffy Duck'}
        , {includes: {players: 'sponsors'}, sort: ['players.name', 'id']});

if (!someTeam.players) {
  someTeam.getPlayers(function (err, data) {
    console.dir(data);
  });
}

• • -