Node-objection NPM

Objection

"node-objection"

A small library for express providing an easy to use API endpoint for storing persistent data in JSON files in express apps. It also provides predefined schemas for simple configuration of normally complex tasks.

This is configured out of the box to work with angular's $resource module, making it easy to get test data to and from your client code.

Installation

npm install node-objection --save

Please be sure to create a /db directory in the root directory of your application or the database will not connect. This is where diskdb will store is JSON files. The JSON files are stored here by the name of the collection ie... objection("users") will create /db/users.json file.

Dependencies

lodash
diskdb
body-parser
express
morgan
bcrypt

Usage

var objection = require("node-objection")();
app.use("/employees", objection.collection("employees"));

This will produce an endpoint at /employees with the following restful methods:

GET /employees - This method returns an array of employees or an empty array if none exist.
GET /employees/:_id - This method returns one employee or an empty object if it is not found.
POST /employees - This method inserts an employee with the data sent in the request body, and returns the new employee.
PUT /employees/:_id - updates a employee with the _id parameter, and request body content, then returns an updated count.
DELETE /employees/:_id - This method deletes a employee with the _id param.

This allows you to configure any collection on the fly just by using the objection("[object]") format. For example... If i wanted to create an todo collection i would simply do the following.

var objection = require("node-objection");
app.use("/todos", objection.collection("todos"));

Filter and Sort

You can also use query parameters with the GET /collection. This makes sorting and filtering possible. To Filter a collection use the following.

GET /users/?lastName=Smith

This will return all users with the last name of Smith

[
	{fisrtName:"Bob", lastName:"Smith"}, 
	{fisrtName:"Nancy", lastName:"Smith"}, 
	{fisrtName:"Jason", lastName:"Smith"}
]

To sort a collection use the orderBy query parameter with the key you want to orderBy. Right now you can only order by asc.

GET /users/?orderBy=firstName

This will return the following.

[
	{fisrtName:"Bob", lastName:"Smith"}, 
	{fisrtName:"Jason", lastName:"Smith"},
	{fisrtName:"Nancy", lastName:"Smith"}
]

Predefined Schemas

Objection includes some predefined schema for common use cases. This allows you get up and running with your client side application without having wrestle with backend logic.

User Schema

The User Schema provides built in password hashing and authentication. To implement a user schema do the following:

var objection = require("node-objection");
app.use("/users", objection.user());

This provides an endpoint at /users with all of the RESTful methods mentioned above, a predefined schema, and some bonus features.

{
	email:[email],					// User Email, must be unique
	password:[hash of password],	// Password hashed
	username:[username],			// Username, must be unique.
	role:[role],					// The role of a user, defaults to "user".
	created:[date created],			// The date this user was created.
	updated:[date updated],			// The date this user was last updated.
	_id:[GUID]						// The unique identifier of this user.
}

If you send a password in the request body @ POST /users request, it will be hashed and stored, but not returned.
Anytime you update a user @ PUT /users/:_id the new password will be hashed and stored, and not returned.
For authentication purposes, the email & username key is set to unique. You will get a 400 status bad request if you try to store duplicate emails or usernames.
An additional route is made for authentication @ /users/login. This is route to post your email and password.
A token validation route is made @ /users/validate. This is route to validate your tokens.
A role key with a default value of "user" is added to each user so you can test roles and permissions in you app.

In addition to the db/user.json, the user schema also creates back end goodies for logging, and testing purposes.

/db/jwt.json If JSON Web Tokens are enable, this logs all json web token issued with the following schema.

	{
		user:[_id], 			// _id of the user the token was issued to.
		token:[access_token], 	// The actual token that was issued to the user.
		date:current_date,		// The date the token was issued
		expires:expires			/ The date the token expires
	};

/db/attempts.json This simply logs login attempts and

		{
			date:[moment date],	// The date a login attempt was made.
			user:[user],		// The user attempting to login. This is the username || email and pass
			allowed:[boolean],	// Did the login attempt succeed.
		};

Model API

Behind the scenes, there is is a model API that wraps the diskdb mongodb-like methods. These methods are mapped to the RESTful request as follows.

GET /collection - model.select(); - db.find();
GET /collection/_id - model.findOne({_id:_id}); - db.findOne({_id:_id});
POST /collection/_id - model.insert({data}); - db.save({data})
PUT /collection/_id - model.update([_id], {data}); - db.update([_id], {data});
DELETE /collection/_id - model.remove({_id:_id}); - db.remove({_id:_id});

The PUT, and DELETE, methods retrieve the _id parameter first from the query parameters. If it does not find it there, it will search the request body for an _id key. The key will be removed from the data before it is updated.

Contributing

Feel free to contribute to the library as you see fit. I have not created any test or error handling yet as this started as a library to help be build test API endpoints for angular's $resource module.