Paloma NPM | npm.io

Paloma

An angular-like MVC framework, based on:

koa@2: Next generation web framework for node.js.
bottlejs: A powerful dependency injection micro container.

Installation

$ npm i paloma --save

If you use async function as controller, you may need node v7.6.0+ or babel.

Scaffold

see create-paloma-app.

Example

Common function

const Paloma = require('paloma')
const app = new Paloma()

app.controller('indexCtrl', (ctx, next, indexService) => {
  ctx.body = `Hello, ${indexService.getName()}`
})

app.service('indexService', function () {
  this.getName = function () {
    return 'Paloma'
  }
})

app.route({
  method: 'GET',
  path: '/',
  controller: 'indexCtrl'
})

app.listen(3000)

/*
$ curl localhost:3000
Hello, Paloma
*/

When a route is matched, its path is available at ctx._matchedRoute.

Async function

const Paloma = require('paloma')
const app = new Paloma()

app.controller('indexCtrl', async (ctx, next, indexService) => {
  ctx.body = await Promise.resolve(`Hello, ${indexService.getName()}`)
})

app.service('indexService', function () {
  this.getName = function () {
    return 'Paloma'
  }
})

app.route({
  method: 'GET',
  path: '/',
  controller: 'indexCtrl'
})

app.listen(3000)

/*
$ curl localhost:3000
Hello, Paloma
*/

const Paloma = require('paloma')
const app = new Paloma()

app.route({
  method: 'GET',
  path: '/',
  controller: async (ctx, next, indexService) => {
    ctx.body = await Promise.resolve(`Hello, ${indexService.getName()}`)
  }
})

app.service('indexService', function () {
  this.getName = function () {
    return 'Paloma'
  }
})

app.listen(3000)

routerName

const Paloma = require('paloma')
const app = new Paloma()

app.route({
  method: 'GET',
  path: '/',
  routerName: 'getHome',
  controller: (ctx, next) => {
    ctx.body = `routerName: ${ctx.state.routerName}`
  }
})

app.listen(3000)

/*
$ curl localhost:3000
routerName: getHome
*/

Validator

const Paloma = require('paloma')
const app = new Paloma()

app.controller('indexCtrl', (ctx, next) => {
  ctx.body = `Hello, ${ctx.query.name}`
})

app.route({
  method: 'GET',
  path: '/',
  controller: 'indexCtrl',
  validate: {
    query: {
      name: { type: 'string', enum: ['tom', 'xp'], required: true }
    }
  }
})

app.listen(3000)
/*
$ curl localhost:3000
($.query.name: undefined) ✖ (required: true)
$ curl localhost:3000?name=tom
Hello, tom
$ curl localhost:3000?name=nswbmw
($.query.name: "nswbmw") ✖ (enum: tom,xp)
*/

More validators usage see another-json-schema.

Array controllers

const bodyParser = require('koa-bodyparser')
const Paloma = require('paloma')
const app = new Paloma()

app.controller('indexCtrl', (ctx, next) => {
  ctx.body = ctx.request.body
})

app.route({
  method: 'POST',
  path: '/',
  controller: [bodyParser(), 'indexCtrl']
})

app.listen(3000)

More examples see test and paloma-examples.

API

load(dir)

Load all files by require-directory.

Param	Type	Description
dir	String	An absolute path or relative path.

route(route)

Param	Type	Description
route	Object
route.method	String	HTTP request method, eg: `GET`, `post`.
route.path	String	Request path, see path-to-regexp, eg: `/:name`.
route.controller	String\|Function\|String\|Function	Controller functions or names.
route.validate(optional)	Object	Validate Object schemas.

controller(name, fn)

Param	Type	Description
name	String	Controller name.
fn(optional)	Function	Controller handler.
fn->arguments0->ctx	Object	Koa's `ctx`.
fn->arguments1->next	Function	Koa's `next`.
fn->arguments2...	Object	Instances of services.

service(name, fn)

Param	Type	Description
name	String	The name of the service. Must be unique to each service instance.
fn	Function	A constructor function that will be instantiated as a singleton.

factory(name, fn)

Param	Type	Description
name	String	The name of the service. Must be unique to each service instance.
fn	Function	A function that should return the service object. Will only be called once; the Service will be a singleton. Gets passed an instance of the container to allow dependency injection when creating the service.

provider(name, fn)

Param	Type	Details
name	String	The name of the service. Must be unique to each service instance.
fn	Function	A constructor function that will be instantiated as a singleton. Should expose a function called `$get` that will be used as a factory to instantiate the service.

constant(name, value)

Param	Type	Details
name	String	The name of the constant. Must be unique to each service instance.
value	Mixed	A value that will be defined as enumerable, but not writable.

value(name, value)

Param	Type	Details
name	String	The name of the value. Must be unique to each service instance.
value	Mixed	A value that will be defined as enumerable, readable and writable.

decorator(name, fn)

Param	Type	Details
name(optional)	String	The name of the service this decorator will affect. Will run for all services if not passed.
fn	Function	A function that will accept the service as the first parameter. Should return the service, or a new object to be used as the service.

middlewares(name, fn)

Register a middleware function. This function will be executed every time the service is accessed. Distinguish with koa's middleware.

Param	Type	Details
name(optional)	String	The name of the service for which this middleware will be called. Will run for all services if not passed.
fn	Function	A function that will accept the service as the first parameter, and a `next` function as the second parameter. Should execute `next()` to allow other middleware in the stack to execute. Bottle will throw anything passed to the `next` function, i.e. `next(new Error('error msg'))`.