This class provides Ravel, a lightweight but powerful framework for the rapid creation of enterprise Node.js applications which scale horizontally with ease and support the latest in web technology.

Extends AsyncEventEmitter

const Ravel = require('ravel');
const app = new Ravel();

const Ravel = require('ravel');
class NotFoundError extends Ravel.Error {
  constructor (msg) {
    super(msg, Ravel.httpCodes.NOT_FOUND);
  }
}

const DatabaseProvider = require('ravel').DatabaseProvider;
class MySQLProvider extends DatabaseProvider {
  // ...
}

const AuthenticationProvider = require('ravel').AuthenticationProvider;
class GoogleOAuth2Provider extends AuthenticationProvider {
  // ...
}

const Ravel = require('ravel');
console.log(Ravel.httpCodes.NOT_FOUND);

const Module = require('ravel').Module;

class MyModule {
  // ...
}
module.exports = MyModule;

const Routes = require('ravel').Routes;
@Routes('/')
class MyRoutes {
  // ...
}
module.exports = MyRoutes;

const Resource = require('ravel').Resource;
@Resource('/')
class MyResource {
  // ...
}
module.exports = MyResource;

app.$log.error('Something terrible happened!');

await app.init();

await app.listen();

await app.start();

await app.close();

const inject = require('ravel').inject;
const Module = require('ravel').Module;

@Module('test')
class MyModule {
  aMethod () {
    //...
  }
}
app.load(MyModule);
await app.init();

// recursively load all `Module`s, `Resource`s and `Routes` in a directory
app.scan('./modules');
// a Module 'modules/test.js' in ./modules can be injected as `@inject('test')`
// a Module 'modules/stuff/test.js' in ./modules can be injected as `@inject('stuff.test')`

Modules are plain old node.js modules exporting a single class which encapsulates application logic and middleware. Modules support dependency injection of core Ravel services and other Modules alongside npm dependencies (no relative require's!). Modules are instantiated safely in dependency-order, and cyclical dependencies are detected automatically.

const inject = require('ravel').inject;
const Module = require('ravel').Module;

@Module
@inject('path', 'fs', 'custom-module', '$log')
class MyModule {
  constructor (path, fs, custom, $log) {
    this.path = path;
    this.fs = fs;
    this.custom = custom;
    this.$log = $log;
  }

  aMethod () {
    this.$log.info('In aMethod!');
    //...
  }
}

module.exports = MyModule

Provides Ravel with a simple mechanism for registering routes, which should generally only be used for serving templated pages or static content (not for building RESTful APIs, for which Ravel.Resource is more applicable). Clients decorate a class with this decorator to create a Routes module.

Route paths are the concatenation of the basePath provided to @Routes(basePath), with the subpath passed to @mapping(method, subpath). Route paths may incorporate complex patterns, such as:

• Parameters: '/foo/:id' (:id is captured as ctx.params.id, and matches any chars but / by default)
• Multiple parameters: '/:foo/:bar' (ctx.params.foo and ctx.params.bar are both available)
• Mixed parameters: '/foo/bar-:id' (:id, without bar-, is captured as ctx.params.id)
• Regex parameters: '/foo/:id(\\d+)'
• Compound parameters: '/foo/:id-:name' (ctx.params.id and ctx.params.name are both available)
• Optional parameters: '/foo/:id{-:name}?' (matches /foo/12 and /foo/12-john)
• "Catch all" routes, which match their own pattern, as well as any path components beneath them. In catchAll mode, /foo/:bar matches /foo/bar and /foo/bar/something/else. This is a flag configured outside of the route pattern. See @mapping for configuration details.

The routing tree is constructed to ensure predictability at runtime, according to the following rules:

• Route components without parameters are visited first
• Route components with mixed parameters are visited before ones with non-mixed parameters
• Route components with required parameters are visited before ones with optional parameters
• "Catch all" routes are visited last, only if nothing else has matched a path
• Declaring two functionally identical routes is not permitted (i.e. /foo/:bar and /foo/:car)

const inject = require('ravel').inject;
const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
const before = Routes.before;

// you can inject your own Modules and npm dependencies into Routes
@Routes('/') // base path for all routes in this class
@inject('koa-bodyparser', 'fs', 'custom-module')
class MyRoutes {
  constructor (bodyParser, fs, custom) {
    this.bodyParser = bodyParser(); // make bodyParser middleware available
    this.fs = fs;
    this.custom = custom;
  }

  // will map to /app
  @mapping(Routes.GET, 'app')
  @before('bodyParser') // use bodyParser middleware before handler
  async appHandler (ctx) {
    // ctx is a koa context object.
    // await on Promises, and set ctx.body to create a body for response
    // "OK" status code will be chosen automatically unless configured via ctx.status
    // Extend and throw a Ravel.Error to send an error status code
  }
}

module.exports = MyRoutes;

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.HEAD, '/something')
  async handler (ctx) {
    //...
  }
}

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.GET, '/something')
  async handler (ctx) {
    //...
  }
}

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.POST, '/something')
  async handler (ctx) {
    //...
  }
}

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.PUT, '/something')
  async handler (ctx) {
    //...
  }
}

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.PATCH, '/something')
  async handler (ctx) {
    //...
  }
}

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
@Routes('/')
class MyRoutes {
  @mapping(Routes.DELETE, '/something')
  async handler (ctx) {
    //...
  }
}

What might be referred to as a controller in other frameworks, a Resource module defines HTTP methods on an endpoint, supporting the session-per-request transaction pattern via Ravel middleware. Resources also support dependency injection, allowing for the easy creation of RESTful interfaces to your Module-based application logic. Resources are really just a thin wrapper around Routes, using specially-named handler functions (get, getAll, head, headAll, post, put, putAll, patch, patchAll, delete, deleteAll) instead of @mapping. This convention-over-configuration approach makes it easier to write proper REST APIs with less code, and is recommended over "carefully chosen" @mappings in a Routes class.

Omitting any or all of the specially-named handler functions is fine, and will result in a 501 NOT IMPLEMENTED status when that particular method/endpoint is requested.

Resources inherit all the properties, methods and decorators of Routes. See Routes for more information. Note that @mapping does not apply to Resources.

For details concerning path construction, including how to employ parameters and regular expressions, see Routes.

const inject = require('ravel').inject;
const Resource = require('ravel').Resource;
const before = Resource.before;

// you can inject your own Modules and npm dependencies into Resources
@Resource('/person')
@inject(koa-bodyparser', 'fs', 'custom-module')
class PersonResource {
  constructor (bodyParser, fs, custom) {
    this.bodyParser = bodyParser(); // make bodyParser middleware available
    this.fs = fs;
    this.custom = custom;
  }

  // will map to GET /person
  @before('bodyParser') // use bodyParser middleware before handler
  async getAll (ctx) {
    // ctx is a koa context object.
    // await on Promises, and set ctx.body to create a body for response
    // "OK" status code will be chosen automatically unless configured via ctx.status
    // Extend and throw a Ravel.Error to send an error status code
  }

  // will map to GET /person/:id
  async get (ctx) {
    // can use ctx.params.id in here automatically
  }

  // will map to HEAD /person
  async headAll (ctx) {}

  // will map to HEAD /person/:id
  async head (ctx) {}

  // will map to POST /person
  async post (ctx) {}

  // will map to PUT /person
  async putAll (ctx) {}

  // will map to PUT /person/:id
  async put (ctx) {}

  // will map to PATCH /person
  async patchAll (ctx) {}

  // will map to PATCH /person/:id
  async patch (ctx) {}

  // will map to DELETE /person
  async deleteAll (ctx) {}

  // will map to DELETE /person/:id
  async delete (ctx) {}
}

module.exports = PersonResource;

Dependency injection decorator for Ravel Modules, Resources and Routes. Since eliminating relative require()s has always been one of the core goals of the Ravel framework, this decorator takes strings instead of actual references to require()d modules. This string is either the name of the module to require, or the registered name of a client Ravel Module. Ravel Modules override npm modules.

This decorator simply annotates the class with modules which should be injected when Ravel initializes. See util/injector for the actual DI implementation.

// @inject works the same way on Modules, Resources and Routes
const inject = require('ravel').inject;
const Module = require('ravel').Module;

@@Module('mymodule')
@inject('path', 'fs', 'custom-module')
class MyModule {
  constructor (path, fs, custom) {
    super();
    this.path = path;
    this.fs = fs;
    this.custom = custom;
  }

  aMethod() {
    // can access this.fs, this.path or this.custom
  }
}

Dependency injection decorator for Ravel Modules, Resources and Routes. Extremely similar to @inject, but will automatmically assign the injected components to values on the current scope, based on name, after construction (this means that these values will not be available in the construtor). Injected modules can be locally renamed by supplying an alias.

This decorator simply annotates the class with modules which should be injected when Ravel initializes. See util/injector for the actual DI implementation.

// @autoinject works the same way on Modules, Resources and Routes
const autoinject = require('ravel').autoinject;
const postinject = require('ravel').postinject;
const Module = require('ravel').Module;

@@Module('mymodule')
@autoinject('path', {'fs': 'myfs'}, 'custom-module')
class MyModule {
  constructor () {
    // this.myfs, this.path and this['custom-module']
    // are not available in the constructor, and will
    // will be populated after construction time.
    // If you set any properties on this with identical
    // names, they will be overriden.
  }

  aMethod() {
    // can access this.myfs, this.path or this['custom-module']
  }

  @postinject
  init () {
    // Since autoinjected modules are not present in the constructor,
    // @postinject-decorated methods provide an alternative way to
    // consume injectables for initialization immediately
    // after instantiation.
  }
}

Core Ravel services available for injection by name into any @Modules, @Resources or @Routes.

@Module
@inject('$log')
class MyModule {
  constructor ($log) {
    this.$log = $log;
  }

  aMethod () {
    this.$log.info('In aMethod!');
    //...
  }
}

this.$log.trace('A trace message');
this.$log.verbose('A verbose message');
this.$log.debug('A debug message');
this.$log.info('A info message');
this.$log.warn('A warn message');
this.$log.error('A error message');
this.$log.critical('A critical message');

// string interpolation is supported
this.$log.info('Created record with id=%s', '42');

// Errors are supported
this.$log.error('Something bad happened!', new Error('Ahh!'));

this.$params.get('some ravel parameter');

const Ravel = require('ravel');
const inject = Ravel.inject;
const Module = Ravel.Module;
const prelisten = Module.prelisten;
@Module
@inject('$db')
class MyModule {
  constructor($db) { this.$db = $db; }
  // in this example, database initialization is
  // performed at application start-time via
  // the // @prelisten decorator
  @prelisten
  doInitDb () {
    // open connections to specific, named database providers.
    // like // @transaction, you can also supply no names (just
    // the async function) to open connections to ALL registered
    // DatabaseProviders
    this.$db.scoped('mysql', 'rethinkdb', async function (ctx) {
      // can use ctx.transaction.mysql (an open connection)
      // can use ctx.transaction.rethinkdb
    });
  }
}

this.$ws.subscibe('my.topic', ctx); // ctx is a context object in a Routes or Resource handler
this.$ws.unsubscribe('my.topic', ctx); // ctx is a context object in a Routes or Resource handler
this.$ws.publish('my.topic', messageBuffer); // messages are binary buffers

Hash of HTTP Response Codes, available as require('ravel').httpCodes. Useful for creating custom error types.

The @mapping decorator for Routes classes. Indicates that the decorated method should be mapped as a route handler using koa.

Can also be applied at the class-level to indicate routes which do nothing except return a particular status code.

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;

@Routes('/')
class MyRoutes {
  // will map to /projects
  @mapping(Routes.GET, 'projects')
  async handler (ctx) {
    // ctx is a koa context object
  }
}

const Ravel = require('ravel');
const Routes = Ravel.Routes;
const mapping = Routes.mapping;

// class-level version will create a route 'DELETE /' which responds with 501 in this case
@mapping(Routes.DELETE, 'projects', { status: Ravel.httpCodes.NOT_IMPLEMENTED })
@Routes('/')
class MyRoutes {
}

The @before decorator for Routes and Resource classes. Indicates that certain middleware should be placed on the given route before the method which is decorated.

Can also be applied at the class-level to place middleware before all @mapping handlers.

References any middleware AsyncFunctions available on this.

// Note: decorator works the same way on Routes or Resource classes

const inject = require('ravel').inject;
const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
const before = Routes.before;

@Routes('/')
@inject('koa-bodyparser')
class MyRoutes {
  constructor (bodyParser) {
    this.bodyParser = bodyParser();
  }

  @mapping(Routes.GET, '/projects/:id')
  @before('bodyParser') // method-level version only applies to this route
  async handler (ctx) {
    // in here, bodyParser will already have run,
    // and ctx.request.body will be populated
  }
}

// Note: decorator works the same way on Routes or Resource classes
const inject = require('ravel').inject;
const Routes = require('ravel').Resource;
const before = Resource.before;

@Resource('/')
@inject('koa-bodyparser')
@before('bodyParser') // class-level version applies to all routes in class.
class MyResource {
  constructor (bodyParser) {
    this.bodyParser = bodyParser();
  }

  async get(ctx) {
    // in here, bodyParser will already have run,
    // and ctx.request.body will be populated
  }
}

The @cache decorator for Routes and Resource classes. Indicates that response caching middleware should be placed on the given route before the method which is decorated.

Can also be applied at the class-level to place caching middleware before all @mapping handlers.

References any middleware AsyncFunctions available on this.

See cache for more information.

// Note: decorator works the same way on Routes or Resource classes

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
const cache = Routes.cache;

@Routes('/')
class MyRoutes {
  @cache // method-level version only applies to this route
  @mapping(Routes.GET, '/projects/:id')
  async handler (ctx) {
    // The response will automatically be cached when this handler is run
    // for the first time, and then will be served instead of running the
    // handler for as long as the cached response is available.
  }
}

// Note: decorator works the same way on Routes or Resource classes
const Resource = require('ravel').Resource;
const cache = Resource.cache;

// class-level version applies to all routes in class, overriding any
// method-level instances of the decorator.
@cache({expire:60, maxLength: 100}) // expire is measured in seconds. maxLength in bytes.
@Resource('/')
@inject(koa-bodyparser')
class MyResource {
  constructor (bodyParser) {
    this.bodyParser = bodyParser();
  }

  async get(ctx) {
    // The response will automatically be cached when this handler is run
    // for the first time, and then will be served instead of running the
    // handler for as long as the cached response is available (60 seconds).
  }
}

The @transaction decorator for opening a transaction on a Routes or Resource handler method. Facilitates transaction-per-request. Can also be applied at the class-level to open connections for all handlers in that Route or Resource class.

Connections are available within the handler as an object ctx.transaction, which contains connections as values and DatabaseProvider names as keys. Connections will be closed automatically when the endpoint responds (do not close them yourself), and will automatically roll-back changes if a DatabaseProvider supports it (generally a SQL-only feature).

// Note: decorator works the same way on Routes or Resource classes
const Routes = require('ravel').Routes;
const mapping = Routes.mapping;

@Routes('/')
class MyRoutes {
  @mapping(Routes.GET, 'app')
  @transaction // open all connections within this handler
  async appHandler (ctx) {
    // ctx.transaction is an object containing
    // keys for DatabaseProviders and values
    // for their open connections
  }

  @mapping(Routes.GET, 'something')
  @transaction('mysql', 'rethinkdb') // open one or more specific connections within this handler
  async somethingHandler (ctx) {
    // can use ctx.transaction.mysql
    // can use ctx.transaction.rethinkdb
  }
}

// Note: decorator works the same way on Routes or Resource classes
const Resource = require('ravel').Resource;

@transaction('mysql') // all handlers will have ctx.transaction.mysql
@Resource('/')
class MyResource {
  async post (ctx) {
    // can use ctx.transaction.mysql
  }
}

Defines an abstract DatabaseProvider - a mechanism by which connections can be obtained and transactions can be entered and exited for a particular database provider such as MySQL (see ravel-mysql-provider for an example implementation). Override this class to create your own DatabaseProvider.

The @authenticated decorator adds authentication middleware before an endpoint within a Routes or Resource class, requiring that a user have valid credentials before they can access the decorated endpoint(s).

Assumes that you've require'd an AuthenticationProvider, and that you have set up an @authconfig Module.

If an object is passed as an argument to the decorator, it is used for configuration purposes, and supports the following keys:

• boolean config.redirect true iff should automatically redirect to app.get('login route') if user is not signed in.
• boolean config.register register user automatically if they are not registered. (rather than failing and throwing an $err.Authentication).

See authconfig and AuthenticationProvider for more information.

// Note: decorator works the same way on Routes or Resource classes

const Routes = require('ravel').Routes;
const mapping = Routes.mapping;
const authenticated = Routes.authenticated;
@Routes('/')
class MyRoutes {
  @authenticated({redirect: true}) // works at the method-level, with or without arguments
  @mapping(Routes.GET, 'app')
  async handler (ctx) {
    // will redirect to this.$params.get('login route') if not signed in
  }
}

// Note: decorator works the same way on Routes or Resource classes

const Resource = require('ravel').Resource;
const authenticated = Resource.authenticated;

@authenticated // works at the class-level as well (with or without arguments)
@Resource('/')
class MyResource {
  async handler (ctx) {
    // will respond with a 401 if not signed in
  }
}

A decorator for a Module, indicating that it will offer specific functions which encapsulate the configuration of passport.js. For more information on how to implement an @authconfig module, please see the README for an existing Ravel AuthenticationProvider.

The abstract superclass of AuthenticationProviders - modules which are capable of initializing Passport.js with a particular strategy, and seamlessly verifying requests issued by mobile clients via header tokens instead of sessions. Extend this class to implement a custom AuthenticationProvider.

An abstraction for a logging service which wraps around intel.

Built-in error types for Ravel. When thrown within (or up to) a Routes or Resource handler, the response to that request will automatically use the associated error status code (rather than a developer needing to catch their own errors and set status codes manually).

You can create your own Error types associated with status codes by extending Ravel.Error.