@mutant-ws/blocks v3.11.0

blocks

REST API framework for Node.js. request |> think hard |> response.

• Features
  • Validate input
  • Permissions
  • Promises
  • Other
• Install
• Example
• Configuration
• Routes
  • Default "/ping" route
  • Custom route
  • Custom JSON schema
• Plugins
  • Custom plugin
• Develop
• Changelog

Features

Validate input

Pass request data (headers, body, query parameters, URL parameters) through custom JSON Schemas defined for each route. Make sure no unwanted data gets in, de-clutter the route logic and make the API behave more consistent.
If validation fails, an automatic 409 Conflict response will be sent.

See ajv and JSON Schema docs for more on data validation.

Permissions

Simple function outside of main route logic.
If it returns false, an automatic 403 Forbidden response will be sent.

Promises

async/await in Plugins and Routes

Other

• File upload and form parsing for multipart/form-data - busboy
• Middleware support of existing package - connect
• JSON Web Token - jsonwebtoken
• Query string parsing - qs
• Route param parsing - path-to-regexp
• Cross-origin resource sharing - cors
• Secure your API with various HTTP headers - helmet

Install

npm install @mutant-ws/blocks

Example

src/index.js

import http from "http"
import glob from "glob"
import { block } from "@mutant-ws/blocks"

// Initialize `block` app
const app = block({
  plugins: glob.sync("./plugins/*.js", { cwd: __dirname, absolute: true }),
  routes: glob.sync("./**/*.route.js", { cwd: __dirname, absolute: true }),
})


// After plugins successfully initialize, start http server
app.then(([middleware, plugins]) => {
    const server = http.createServer(middleware)

    server.listen({
      port: process.env.PORT,
    })

    server.on("error", error => {
      console.log("Server error", error)
    })

    server.on("listening", () => {
      console.log(`Server started on port ${process.env.PORT}`)
    })
  })
  .catch(error => {
    console.log("Application could not initialize", error)
  })

Configuration

blocks uses a set of process.env variables for configuration. See _env file for all available options and defaults.

Use dotenv for easy local development.

Routes

Default "/ping" route

GET: /ping

{
  "name": "foo",
  "ping": "pong",
  "aliveFor": {
    "days": 2, "hours": 1, "minutes": 47, "seconds": 46
  }
}

Custom route

src/something.route.js

module.exports = {
  method: "GET",
  path: "/something/:id",

  // 409 if invalid req.query, req.headers, req.params or req.body
  schema: require("./something.schema"),

  // 401 if returns false or throws
  authenticate: (/* plugins */) => (/* req */) => true,

  // 403 if returns false or throws
  authorize: (/* plugins */) => (/* req */) => true,

  /**
   * After schema validation and permission checking
   *
   * @param  {Object}  plugins  Plugins
   * @param  {Object}  req      Node request
   *
   * @return {mixed}
   */
  action: (/* plugins */) => req => {
    return {
      message: req.ctx.params.id
    }
  },
}

Custom JSON schema

A schema can contain only 4 (optional) keys:

• headers validates req.headers
• params validates req.ctx.params parsed from URL with path-to-regexp
• query: validates req.ctx.query parsed from URL with qs
• body validates req.ctx.body parsed from req with JSON.parse

See src/plugins/route-default.schema.js for default values.

Each key needs to be a ajv compatible schema object.

src/something.schema.js

module.exports = {
  headers: {
    type: "object",
    required: ["authorization"],
    properties: {
      authorization: {
        type: "string",
      },
    },
  },

  params: {
    type: "object",
    additionalProperties: false,
    required: ["id"],
    properties: {
      id: {
        type: "string",
        pattern: "^[a-z0-9-]+$",
        maxLength: 25,
        minLength: 25,
      }
    }
  },

  query: {
    type: "object",
    additionalProperties: false,
    properties: {
      offset: {
        type: "integer",
        minimum: 0,
        default: 0,
      },
      limit: {
        type: "integer",
        minimum: 1,
        maximum: 100,
        default: 20,
      },
    },
  },
}

Plugins

Separate code interfacing with 3rd party libraries or services. pluginus dependency injection library is used.

Plugins are accesible in other plugins, middleware and routes.

Custom plugin

A plugin consists of a constructor function and a list of other plugins that is dependent on.

Whatever the create function returns will be considered as the plugin's content and is what will be exposed to the routes, middleware and other plugins.

src/plugins/database.js

const Sequelize = require("sequelize")

module.exports = {
  /**
   * Array of plugins to wait for before running `create`.
   * Name is constructed from the filename by removing the extension and
   * turning it into CammelCase.
   *
   * Ex. "test__name--BEM.plugin.js" => "TestNameBemPlugin"
   */
  depend: ["Lorem"],

  /**
   * Constructor, return value will be considered the plugin's content exposed
   * to routes, middleware and other plugins.
   *
   * @returns  {Promise<any>}  Plugin content
   */
  create: => Lorem => {
    console.log("Checking DB connection")

    // Database connection, model loading etc
    ...
    return {
      Todos: ...,
      Comments: ...,
    }
  }
}

Develop

git clone git@github.com:mutant-ws/blocks.git && \
  cd blocks && \
  npm run setup

Run all *.test.js in tests folder

npm test

Watch src and tests folders and re-run tests

npm run tdd

Changelog

See the releases section for details.