yak-orm

Yak is an ORM that maps RESTful resources to JavaScript models/collections.

Inspired by Backbone.js and Her, Yak is designed to build applications that are powered by a RESTful JSON API instead of a database. Yak uses window.fetch on the client, and node-fetch on the server, which makes it really easy for you to write a persistence layer in an isomorphic fashion.

Yak is designed to be extremely lightweight, weighing in at less than 1kb. It's only dependency is the window.fetch API which is gaining native support in most browsers as of writing.

Installation & Requirements

Run npm install yak-orm and then simply require it in your project.

Yak requires Node.js >= 4.0 to run on the server.

To run in a web browser environment you'll need native or polyfilled support for ES6 Promises, Object.assign, Fat Arrow Syntax, and the window.fetch API. It's also recommended that you use Webpack or Browserify to make your build.

Elevator pitch

var Yak = require('yak-orm');
var yak = new Yak({
  host: "http://localhost:8080/"
});

var Fruit = yak.model({
  name: "fruits"
});

// GET http://localhost:8000/fruits?color=red
// returns { fruits: [{ name: "apple", name: "pomegranate"}] }
Fruit.all({
  where: {
    color: 'red'
  }
}).then(collection => {
  collection.fruits.forEach(fruit => {
    console.log(fruit.attrs.name);
  });
});

Yak is a work in progress

Features that are on the roadmap but not yet currently implemented include:

• Events
• Nested models
• Validations
• Caching
• Suggestions...?

API Documentation

Yak (constructor)

Create a new Yak instance

Arguments

• host (String) | Specify your API endpoint here

Example

// Create new Yak instance
var yak = new Yak({
  host: "http://localhost:8080/"
});

yakInstance.model

Create a new model based on a Yak instance

Arguments

• name (String) | The name of the resource specified on API server
• url (String, optional) | Resource URI is generated based on name but can be overridden by passing this argument
• parse (Function(attrs (Object) ), optional) | This method will be called every time a new instance of the model is created. It will receive the model attributes as an argument, allowing you to mutate them before model is created.

Example

// Model defintion
var User = yak.model({
  name: "users",
  parse: function(attrs) {
    attrs.fullName = attrs.firstName + " " + attrs.lastName;
    return attrs;
  }
});

Model (constructor)

Create a new instance of a model

Arguments

• attrs (Object) | An object of attributes that will be assigned to the model
• headers (Object) | Specify HTTP headers to be sent along with any model requests

Example

// Create a new user
var user = new User({
  attrs: {
    name: "John",
    email: "[e-mail]"
  },
  headers: {
    'Accept-Language' : 'en',
    'Authentication-Token': 'abc123'
  }
});

Model.get

Retrieve a model from server

Arguments

• id (String) | An identifier that can be used to fetch a specific resource
• where (Object) | Additional query parameters to be sent in request
• headers (Object) | Specify HTTP headers to be sent along with the request

All arguments are optional

Example

// GET http://localhost:8080/users/1?active=true
var user = User.get({
  id: 5,
  where: {
    active: true
  }
  headers: {
    'Accept-Language' : 'fa',
  }
}).then(user => {
  console.log("Retrieved user:", user.attrs);
}).catch(error => {
  console.log(error);
});

Model.all

Retrieve a collection of models from server

Arguments

• where (Object) | Additional query parameters to be sent in request
• headers (Object) | Specify HTTP headers to be sent along with the request

Example

// GET http://localhost:8080/users
User.all().then(collection => {
  collection.users.forEach(user => {
    console.log(user.attrs.id, user.attrs.name);
  });
});

modelInstance.save

Persist a model to server

If an id attribute is present a PATCH operation will be performed to update an existing record

Otherwise a POST operation will be sent to create the record on the endpoint.

Example

// POST http://localhost:8080/users
var user = new User({ name: "Daniel" });
user.save().then(user => {
  // Update user name
  user.attrs.name = "Yak Yak"
  // PATCH http://localhost:8080/users/(user.attrs.id)
  return user.save()
}).catch(error => {
  console.log(error);
});

modelInstance.destroy

Remove a model from server

Example

var user = new User({ id: "5" });
// DELETE http://localhost:8080/users/5
user.destroy().then(user => {
  console.log("Deleted user:", user.attrs.id);
}).catch(error => {
  console.log(error);
});

Testing

Run tests: npm test

Run tests with code coverage: istanbul cover ./node_modules/mocha/bin/_mocha