parch

parch

Restify + Sequelize

parch is a simple RESTful framework combining the power of restify for routing and sequelize ORM for dao access. Stop rewriting your server code and get parched.

If you'd like to contribute, take a look at the roadmap

Installation

npm install --save parch

Usage

• Application
• Controller
  • hooks
• Model
• Associations
• Authentication
• Logging
• Error handling

Application

For a full list of available options see below

const parch = require("parch");

// define your app
const parch = new parch.Application({
  server: {
    name: "my-app",
    certificate: "/path/to/my.crt",
    key: "/path/to/my.key",
    log: Bunyan.createLogger(),
    middlewares: [
      restify.bodyParser(),
      restify.queryParser(),
      myCustomMiddleware()
    ]
  },
  authentication: {
    secretKey: "ssshhh",
    unauthenticated: [/\/posts[\s\S]*/, "/users/resetPassword"]
  },
  controllers: {
    dir: path.resolve(__dirname, "controllers")
  },
  database: {
    connection: {
      username: "postgres",
      password: "postgres",
      database: "postgres",
      host:  "localhost",
      dialect: "postgres",
      logging: false
    },
    models: {
      dir: path.resolve(__dirname, "models")
    }
  },
  logging: {
    dir: path.resolve(__dirname, 'logs'),
    serializers: {
      req(req) {
        return {
          url: req.url
        }
      },
      res(res) {
        return {
          statusCode: res.statusCode
        }
      }
    }
  }
});

// wire up your routes
parch.map(function () {
  this.resource("user");
  this.route("user/resetPassword", {
    using: "users:resetPassword", // controller:method
    method: "post" // request method
  });
});

parch.start(3000).then(() => {
  console.log("App listening.")
});

The above will create the following route mapping

POST   /users               => UserController.create
GET    /users               => UserController.index
GET    /users/:id           => UserController.show
PUT    /users/:id           => UserController.update
DELETE /users/:id           => UserController.destroy
POST   /users/resetPassword => UserController.resetPassword

Controller

lib/controllers/user_controller.js

const parch = require("parch");

class UserController extends parch.Controller {
  constructor(options) {
    super(options);
  }

  index(req, res, next) {
    this.findAll(req.query).then(records => {
      /**
       * {
       *   users: [{
       *   ...
       *   }]
       * }
       */
       res.send(this.statusCodes.SUCCESS, records);
    }).catch(next);
  }

  show(req, res, next) {
    this.findOne(req.params.id).then(record => {
      /**
       * {
       *   user: {
       *   ...
       *   }
       * }
       */
       res.send(this.statusCodes.SUCCESS, record);
    }).catch(next);
  }

  create(req, res, next) {
    this.createRecord(req.body.user).then(record => {
      /**
       * {
       *   user: {
       *   ...
       *   }
       * }
       */
       res.send(this.statusCodes.CREATED, record);
    }).catch(next);
  }

  update(req, res, next) {
    this.updateRecord(req.params.id, req.body).then(updatedRecord => {
      /**
       * {
       *   user: {
       *   ...
       *   }
       * }
       */
       res.send(this.statusCodes.SUCCESS, record);
    }).catch(next);
  }

  destroy(req, res, next) {
    this.destroyRecord(req.params.id).then(() => {
      res.send(this.statusCodes.NO_CONTENT);
    }).catch(next);
  }

  resetPassword(req, res, next) {
    this.findOne(req.params.id).then(record => {
      record.password = req.body.password;
      return record.save();
    }).then(record => {
      res.send(this.statusCodes.SUCCESS);
    }).catch(next);
  }
}

Controller Hooks

Controller hooks allowing for pre and post processing of requests. Both before and after hooks are supported as well as any additional methods added when using Controller#route. When using the after hook, make sure to call next after sending your response.

class UserController extends parch.Controller {
  constructor(options) {
    super(options);

    this.hooks = {
      // The hook name must match the method
      index: {
        before(req, res, next) {
          return checkPermissions().then(() => {
            next();
          }).catch(next);
        },
        after(req, res, next) {
          req.log.child().info("post processing");
        }
      }
    };
  }

  index(req, res, next) {
    res.send(200);
    next();
  }
}

Model

Models are defined following the sequelize define pattern. Options for the model definition can be passed to the constructor's super call

lib/models/user.js

class UserModel extends parch.Model {
  constructor() {
    super({
      classMethods: {
      },

      getterMethods: {
      },

      hooks: {
      },

      instanceMethods: {
      }
    });
  }

  associate(User, models) {
    User.hasMany(models.Posts);
    User.hasMany(models.User, { as: "Parent" });
  }

  define(DataTypes) {
    const user = {
      email: {
        type: DataTypes.STRING,
        validate: { isEmail: true }
      }
    };

    return user;
  }
}

Associations [WIP]

parch loads associations of a record as an array of ids.

class UserController extends parch.Controller {
  constructor() {
    super();
  }

  show(req, res, next) {
    this.findOne(req.params.id).then(user => {
      /**
       *  {
       *    user: {
       *      firstName: "John",
       *      posts: [1, 2, 3]
       *    }
       *  }
       */
    });
  }
}

Authentication and Authorization

Authorization is handled using jwt, with more options coming in the future. To disable auth for specific routes, use the authentication.unauthenticated array. Empty by default, you can give a string or regex expression to skip your unauthenticated routes

const parch = new parch.Application({
  authentication: {
    unauthenticated: [/\/posts[\s\S]*/, "/users/resetPassword"]
  }
});

In order to authenticate a user, create and sign a JWT token to send back to the client. The authorization middleware will then look for this token in the Authorization header. see jsonwebtoken

const jwt = require("jsonwebtoken");
const app = require("express")();

app.post("/login", function (req, res, next) {
  const token = jwt.sign({ userId: 1 }, "secret");

  res.send({ token });
});

curl http://my-server.com/protectedRoute -H 'Authorization: Bearer <token>'

Logging

Logging is handled automatically for you. All requests and responses will be logged using a custom Bunyan instance.

Error handling and responses

Error handling is done using restify-errors. When using controller helpers (findAll, findOne, etc) errors are handled automatically for you. Just catch your Promise with next and parch will handle the rest.

show(req, res, next) {
  this.findOne(req.params.id).then(user => {
  }).catch(next);
}

/**
 * { code: "NotFound", message: "User with id '1' does not exist" }
 */

Errors handled by parch:

• findOne:
  • NotFound: The record does not exist
• createRecord:
  • BadRequest: Request body was missing or invalid
  • UnprocessableEntity: Model validations failed
• updateRecord:
  • BadRequest: Request body was missing or invalid
  • UnprocessableEntity: Model validations failed
• destroyRecord:
  • NotFound: The record does not exist

Need to handle your own errors? controller.errors contains all of restify-errors' errors

Options

• server All options (with the exception of middlewares) are passed directly to restify
  • log: defaults to parch's bunyan instance but can be overridden
  • middlewares(Array): merged with parch's default middlwares
• authentication
  • secretKey(String): A secret string used to sign JWT tokens
  • unauthenticated(Array): an array of strings or regex patterns to skip authentication.
• controllers
  • dir(String): The path to your controllers directory. Default: _dirname/controllers
• database
  • connection(Object) Sequelize connection options
  • models
    • dir(String): The path to your models directory. Default: __dirname/models
• logging
  • dir(String): Path where logs should be saved
  • serializers(Object):
    • req(Function): your request serializer. takes the request as its only argument
    • res(Function): your response serializer. takes the response as its only argument

Changelog

0.5.0 (2017-01-01)

Features

• router: add support for before and after controller hooks (13d5f7a)

<a name="0.4.0"></a>