Giter Site home page Giter Site logo

dolman's Introduction

Build Status

Dolman

dolman is a very light wrapper around an express app meaning to provide some comfortable utilities for one developing a REST API.

As such, dolman overload express' response object to provide handy methods such as .ok or .notFound and provides a easy way to deploy routers using straightforward configuration.

Summary

Installation

You can easily install dolman using npm:

npm install --save dolman

Usage

Wrapping an express app

var express = require('express'),
    dolman = require('dolman')(express, options);

// Example with a custom typology
var dolman = require(express, {typology: myCustomTypology});

Responses

A wrapped express app will have an enhanced repsonse object:

var app = express();

app.get('/hello', function(req, res) {
  return res.ok({hello: 'world'});
});

// The following methods are available:
res.ok([result]);
res.created([result]);
res.badRequest([reason]);
res.unauthorized();
res.forbidden();
res.notFound([reason]);
res.serverError([error]);

Note that the responses will be sent as JSON and will follow this standard:

// Typical success
{
  status: 'ok',
  code: 200,
  result: {
    hello: 'world'
  }
}

// Typical error
{
  status: 'error',
  code: 400,
  error: {
    message: 'Bad Request',
    reason: {
      source: 'body',
      expecting: {
        id: 'number'
      },
      sent: {
        id: 'whatever'
      }
    }
  }
}

Router

dolman exposes an easy way to create express routers by using lists of configuration objects representing a single route.

var app = express();

// Creating a router with a single route
var router = dolman.router([
  {
    url: '/hello',
    action: function(req, res) {
      return res.ok({hello: req.query.name});
    }
  }
]);

app.use(router);
// or
app.use('/prefix', router);
// or, typically, if you need some kind of auth
app.use('/prefix', authMiddleware, router);

A route can be described likewise:

{
  // [required] - The matching express pattern.
  // Remember that this could even be an array or a regex.
  url: '/hello/:name',

  // [required] - The action to perform.
  action: function(req, res) {
    return res.ok({hello: req.params.name});
  },

  // [optional] - The accepted methods.
  // If not provided, defaults to 'ALL'
  method: 'POST',

  // The following also works:
  methods: ['POST', 'PUT'],

  // [optional] - Validation for params, query and body.
  validate: {
    params: {
      name: 'string'
    },
    query: {
      age: '?number'
    },
    body: {
      title: 'string',
      content: {
        id: '?number',
        text: 'string'
      }
    }
  },

  // [optional] - Cache specifications
  cache: 'hello',

  // Or, if the cached response is relative to the request's parameters:
  cache: {
    key: 'hello',
    hasher: function(req) {
      return req.params.name;
    }
  }
}

Note that the validation specifications are handled by the typology library.

What on earth is a dolman?

A dolman is a loose garment with narrow sleeves, an opening in the front and lavish braids. While originating from Turkey, this garment was mostly worn as a jacket by hussars.

Roadmap

  • Declarative way to transform some params?
  • Default values for data?
  • Object polymorphism for the controller?
  • Ways to clear the cache.

License

MIT

dolman's People

Contributors

yomguithereal avatar

Watchers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.