Controller #

Description #

ifnode have possibility to build own web-API interfaces.

Controller can be extended by external plugins (example: ifnode-auth, ifnode-permissions etc)

Definition #

JSDoc syntax #

/**
 * @typedef {Express.Request} IFRequest
 * 
 * @property {?Object}  data
 */


/**
 * @typedef {Buffer|Array|String|Object} IFResponseData
 */

/**
 * @callback request_ok
 * @param {IFResponseData}  [data]
 */
/**
 * @callback request_fail
 * @param {IFResponseData}  [data]
 */
/**
 * @callback request_error
 * @param {IFResponseData}  [data]
 */
/**
 * @callback request_unauthorized
 * @param {IFResponseData}  [data]
 */
/**
 * @callback request_forbidden
 * @param {IFResponseData}  [data]
 */
/**
 * @callback request_not_found
 * @param {IFResponseData}  [data]
 */

/**
 * @typedef {Express.Response} IFResponse
 * 
 * @property    {request_ok}            ok
 * @property    {request_fail}          fail
 * @property    {request_fail}          bad_request
 * @property    {request_fail}          badRequest
 * @property    {request_unauthorized}  unauthorized
 * @property    {request_forbidden}     forbidden
 * @property    {request_not_found}     not_found
 * @property    {request_not_found}     notFound
 * @property    {request_error}         error
 * @property    {request_error}         err
 */

/**
 * @callback nextHandler
 * @param {Error}    [error]
 */

/**
 * @callback routeHandler
 * 
 * @param {IFRequset}    request
 * @param {IFResponse}   response
 * @param {nextHandler}  next_handler
 * @param {nextHandler}  next_route
 */

/**
 * @callback errorHandler
 * 
 * @param {Error}        error
 * @param {IFRequset}    request
 * @param {IFResponse}   response
 * @param {nextHandler}  next_handler
 * @param {nextHandler}  next_route
 */

/**
 * @typedef {Object} ControllerOptions
 * 
 * @property {string}   [root]
 * @property {string}   [name]
 * @property {Object}   [router]
 * @property {boolean}  [ajax]
 * @property {Object}   [map]
 */

/**
 * @interface Controller
 */

/**
 * @function Controller#constructor
 * 
 * @param {ControllerOptions}   [options]
 */

/**
 * @function Controller#before
 * 
 * @param {...routeHandler} callbacks
 */

/**
 * @function Controller#param
 * 
 * @param {string}      name
 * @param {function}    expression
 */

/**
 * @function Controller#method
 * 
 * @param   {string|Array.<string>} methods
 * @param   {string}                [path]
 * @param   {Object}                [options]
 * @param   {...routeHandler}       callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#get
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#post
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#put
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#patch
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#delete
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#del
 * 
 * @param   {string}            [path]
 * @param   {Object}            [options]
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#error
 * 
 * @param   {errorHandler}  custom_error_handler
 * @returns {Controller}
 */

/**
 * @function Controller#use
 * 
 * @returns {Controller}
 */

/**
 * @function Controller#use
 * 
 * @param   {...routeHandler}   callbacks
 * @returns {Controller}
 */

/**
 * @function Controller#compile
 */

TypeScript syntax #

interface IFRequest extends Express.Request {
    data: Object|null
}

type IFResponseData = Buffer|Array|String|Object;

interface IFResponse extends Express.Response {
    ok(data?: IFResponseData),
    bad_request(data?: IFResponseData),
    badRequest(data?: IFResponseData),
    fail(data?: IFResponseData),
    unauthorized(data?: IFResponseData),
    forbidden(data?: IFResponseData),
    not_found(data?: IFResponseData),
    notFound(data?: IFResponseData)
    error(data?: IFResponseData),
    err(data?: IFResponseData)
}

interface nextHandler {
    (error?: Error)
}

interface routeHandler {
    (request: IFRequest, response: IFResponse, next_handler: nextHandler, next_route: nextHandler)
}

interface errorHandler {
    (error: Error, request: IFRequest, response: IFResponse, next_handler: nextHandler, next_route: nextHandler)
}

interface ControllerOptions {
    root?: string,
    name?: string,
    router?: Object,
    ajax?: boolean,
    map?: Object
}

type URLPath = string|RegExp|Array<string|RegExp>

interface Controller {
    id: string,
    name: string,
    root: string,
    router: Express.Router,
    map?: Object,
    new (options?: ControllerOptions),
    before(...callbacks: Array<routeHandler>),
    param(name: string, expression: Function),
    method(methods: string|Array<string>, path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    get(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    post(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    put(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    patch(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    delete(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    del(path?: URLPath, options?: Object, ...callbacks: Array<routeHandler>): Controller,
    use(path?: URLPath, ...callbacks: Array<routeHandler>): Controller,
    end(): Controller,
    error(custom_error_handler: errorHandler): Controller,
    compile()
}

Static methods #

Static methods of Controller can be useful for creating controller's plugin. Example of static methods usage you can find here.

Controller.process_config( processors ) #

_Alias: Controller.processConfig_

Controller.populate( populators ) #

Controller.middleware( middlewares ) #

Controller#constructor( [options] ) #

Arguments #

options #

Note: all options are optional

Instance properties #

Instance methods #

Controller#before( callbacks ) #

Controller#param( name, expression ) #

Controller#method( methods, [path, ] [options, ] callbacks ) #

Controller#method build on Express's router.METHOD and extends all possibilities.

Aliases of base HTTP methods: #

• Controller#get([path, ] [options, ] callbacks )
• Controller#post([path, ] [options, ] callbacks )
• Controller#put([path, ] [options, ] callbacks )
• Controller#patch([path, ] [options, ] callbacks )
• Controller#delete([path, ] [options, ] callbacks )
• Controller#del([path, ] [options, ] callbacks ) ^deprecated

Controller#use( [path, ] callbacks ) #

Controller#use build on Express's router.use and extends all possibilities.

Controller#end( ) #

Mark the end of controller route handlers definition - controller will send response.not_found() if cannot find any handler for current request.

By default go to next controller to find request handlers if controller.end() will not be invoked.

Examples #

without .end() #

const controller = app.Controller({
    name: 'controller',
    root: '/'
});
controller.get('/exists', (req, res) => res.ok('response by controller'));

const controller1 = app.Controller({
   name: 'controller1',
   root: '/'
});
controller1.get('/exists1', (req, res) => res.ok('response by controller1'));

curl /exists1   # -> status 200, "response by controller1"

with .end() #

const controller = app.Controller({
    name: 'controller',
    root: '/'
});
controller.get('/exists', (req, res) => res.ok('response by controller'));
controller.end();

const controller1 = app.Controller({
   name: 'controller1',
   root: '/'
});
controller1.get('/exists1', (req, res) => res.ok('response by controller1'));

curl /exists1   # -> status 404

Controller#error( custom_error_handler ) #

Route handler additional properties #

request and response parameters of route handler are populated by useful custom options.

request additional properties #

response additional methods #

response.ok( [data] ) #

response.bad_request( [data] ) #

Aliases:

• response.badRequest
• response.fail

response.unauthorized( [data] ) #

response.forbidden( [data] ) #

response.not_found( [data] ) #

Aliases:

• response.notFound

response.error( [data] ) #

Aliases:

• response.err