reference.md

Modules

routing

This is main module. By Default its only the thing you should use working with fe-routing-js

Classes

Router

Manipulates existing routeHandlers, global middlewares and processes the requests

RouteHandler

Represents handler for a given string route. When request occurs and request path matches handlres's route pattern then all registered middlewares beeing invoked.

RequestContext

Represents request state.

ResponseContext

Represents response state.

Objects

configuration : object

Routing configuration. You can provide your own versions of internal classes and setup some behavior.

Typedefs

startOptions : Object

routingOptions : Object

routing

This is main module. By Default its only the thing you should use working with fe-routing-js

• routing
  • .config
  • .createRouter([options]) ⇒ Router
  • .get() ⇒ Router
  • .use() ⇒ Router
  • .start([options]) ⇒ Router
  • .stop() ⇒ Router
  • .remove() ⇒ RouteHandler | void
  • .navigate()
  • .isStarted() ⇒ boolean

routing.config

routing Configuration

Kind: static property of routing
See: configuration

routing.createRouter([options]) ⇒ Router

Creates instance of Router with config.routingOptions.

Kind: static method of routing
Returns: Router - Router instance

Param	Type
[options]	routingOptions

routing.get() ⇒ Router

Registers routeHandler. Alias for routing.instance.get.

Kind: static method of routing
See: Router.get
Example

routing.get('some/page', (req, res) => { ... })

routing.use() ⇒ Router

Adds global middleware, router or route middleware. Alias for routing.instance.use.

Kind: static method of routing
See: Router.use
Example

// adding global middleware to the end of array
routing.use((req, res, next) => { next(); });

// adding nested router
routing.use('acc', accountRouter);

// adding route middleware to the begining of route's middlewares array
routing.use('some/page', (req, res, next) => { next(); });

routing.start([options]) ⇒ Router

Starts routing

Kind: static method of routing

Param	Type
[options]	startOptions

routing.stop() ⇒ Router

Stops routing

Kind: static method of routing
See: Router.stop

routing.remove() ⇒ RouteHandler | void

Removes middleware or routeHandler. Alias for routing.instance.remove.

Kind: static method of routing
See: Router.remove

routing.navigate()

Initiates the request. Proxy method for Router instance's navigate.

Kind: static method of routing
See: Router.navigate

routing.isStarted() ⇒ boolean

Returns routing state. True if started

Kind: static method of routing

Router

Manipulates existing routeHandlers, global middlewares and processes the requests

Kind: global class
Properties

Name	Type	Description
routes	RoutesManager	Holds all registered routeHandlers

• Router
  • new Router([options])
  • .isRoutingStarted() ⇒ boolean
  • .isNested() ⇒ boolean
  • .use(path, [middleware]) ⇒ Router
  • .get(path, ...middlewares) ⇒ Router
  • .add(path, middlewares, unshift) ⇒ RouteHandler
  • .getRouteHandler(path, traverse) ⇒ RouteHandler | Void
  • .remove(path, [middleware], [traverse]) ⇒ function | void
  • .hasMiddleware(middleware) ⇒ boolean
  • .createRequestContext(url, options) ⇒
  • .createResponseContext(req) ⇒
  • .hasNestedRouter(router) ⇒ boolean
  • .handleError(error, req, res)
  • .getErrorHandlerName(error) ⇒ string
  • .navigate(url, [options]) ⇒ Promise
  • .isCurrentUrl(url) ⇒ boolean
  • .setCurrentUrl(url)
  • .browserPushState(url)
  • .getCurrentState() ⇒ object

new Router([options])

Creates an instance of Router.

Param	Type	Default
[options]	routingOptions	{}

router.isRoutingStarted() ⇒ boolean

Returns routing state. True if started

Kind: instance method of Router

router.isNested() ⇒ boolean

Returns true if router is registered as subrouter

Kind: instance method of Router

router.use(path, [middleware]) ⇒ Router

Unshift middleware for a given route. If path is a function then adds given middleware to global middlewares

Kind: instance method of Router
Returns: Router - routing instance

Param	Type
path	string | function
[middleware]	function

router.get(path, ...middlewares) ⇒ Router

Adds given handlers to the routehandler Alias for add

Kind: instance method of Router

Param	Type
path	string
...middlewares	function

router.add(path, middlewares, unshift) ⇒ RouteHandler

Adds middlewares to a routeHandler by given path If routeHandler does not exists it will be created

Kind: instance method of Router

Param	Type	Description
path	string
middlewares	Array.<function()>	array of handlers
unshift	boolean	indicates should middlewares be added in the begining

router.getRouteHandler(path, traverse) ⇒ RouteHandler | Void

Returns registered routeHandler

Kind: instance method of Router

Param	Type	Default	Description
path	string
traverse	boolean	true	if True will look up in nested routers too. default is true

router.remove(path, [middleware], [traverse]) ⇒ function | void

Removes registered routeHandler if path param is a string and middleware param is undefined. Removes registered routehandler's middleware if path param is a string and middleware param is a function Removes global middleware if path param is a function

Kind: instance method of Router
Returns: function | void - removed middleware

Param	Type	Default	Description
path	string | function
[middleware]	function
[traverse]	boolean	true	Indicates should look up beeing applied to the nested routers, default is true

router.hasMiddleware(middleware) ⇒ boolean

Returns true if provided middleware is in globalMiddleares array

Kind: instance method of Router

Param	Type
middleware	function

router.createRequestContext(url, options) ⇒

Creates RequestContext instance

Kind: instance method of Router
Returns: RequestContext instance

Param	Type	Description
url	string | URL
options	*	request options

router.createResponseContext(req) ⇒

Creates ResponseContext instance

Kind: instance method of Router
Returns: ResponseContext instance

Param	Type
req	RequestContext

router.hasNestedRouter(router) ⇒ boolean

Checks if given router is nested somewhere in route contexts

Kind: instance method of Router

Param	Type
router	*

router.handleError(error, req, res)

Handles request errors. Converts error to a handler name and tries to execute it. By default there is no any handlers, so you have to define it by yourself.

Kind: instance method of Router

Param	Type
error	string | Error
req	RequestContext
res	ResponseContext

router.getErrorHandlerName(error) ⇒ string

Converts response error to errorHandler name. If error instance of Error then exception name will be used. If error is a string then error value will be used as handler name. Otherwise default.

Kind: instance method of Router
Returns: string - errorHandler name

Param	Type
error	*

router.navigate(url, [options]) ⇒ Promise

Tries to find registered routeHandler by path and execute its middlewares. If there is no such routeHandler then notfound errorHandler will be invoked.

Kind: instance method of Router

Param	Type	Default
url	*
[options]	*	{}

router.isCurrentUrl(url) ⇒ boolean

Checks if a given url is current or a new one

Kind: instance method of Router

Param	Type
url	string | URL

router.setCurrentUrl(url)

Stores given url as current. Method internally used by navigate

Kind: instance method of Router

Param	Type
url	string | URL

router.browserPushState(url)

Pushes state to browser's history Method internally used by navigate

Kind: instance method of Router

Param	Type
url	string | URL

router.getCurrentState() ⇒ object

Returns current state object, by default return empty object. feel free to override. method internaly used by browserPushState

Kind: instance method of Router

RouteHandler

Represents handler for a given string route. When request occurs and request path matches handlres's route pattern then all registered middlewares beeing invoked.

Kind: global class
Properties

Name	Type	Description
url	URL	the URL instance of route
path	string	string path of route
pattern	RegExp	route's RegExp pattern
regexPatterns	Object.<string, RegExp>	default RegExp patterns for maintaining routes and routes parameters
middlewares	Array.<function()>	registerd route's middlewares

• RouteHandler
  • new RouteHandler(url, [router])
  • .isRouter() ⇒ boolean
  • .addMiddlewares(middlewares)
  • .addMiddleware(middleware)
  • .removeMiddleware(middleware) ⇒ function | void
  • .hasNestedRouter(router) ⇒ boolean
  • .removeMiddlewares(middlewares) ⇒ void
  • .hasMiddleware(middleware) ⇒ boolean
  • .extractRouteArguments(req) ⇒ Object.<string, *>

new RouteHandler(url, [router])

Creates an instance of RouteHandler.

Param	Type
url	string | URL
[router]	Router

routeHandler.isRouter() ⇒ boolean

Returns true if this handler is Router based

Kind: instance method of RouteHandler

routeHandler.addMiddlewares(middlewares)

Adds middlewares to middlewares array's

Kind: instance method of RouteHandler

Param	Type
middlewares	Array.<function()>

routeHandler.addMiddleware(middleware)

Adds middleware to middlewares array. Throws if given argument is not a function.

Kind: instance method of RouteHandler

Param	Type
middleware	function

routeHandler.removeMiddleware(middleware) ⇒ function | void

Removes given middleware from middlewares array

Kind: instance method of RouteHandler
Returns: function | void - Returns nothing if given middleware was not found in an array

Param	Type
middleware	function

routeHandler.hasNestedRouter(router) ⇒ boolean

Checks if given router is nested somewhere in route contexts

Kind: instance method of RouteHandler

Param	Type
router	*

routeHandler.removeMiddlewares(middlewares) ⇒ void

Removes all middlewares if called without arguments or if passed middlewares is null or undefined. Otherwise will remove passed middlewares from middlewares array

Kind: instance method of RouteHandler

Param	Type
middlewares	Array.<function()> | void

routeHandler.hasMiddleware(middleware) ⇒ boolean

Returns true if given middleware is present in middlewares array

Kind: instance method of RouteHandler

Param	Type
middleware	function

routeHandler.extractRouteArguments(req) ⇒ Object.<string, *>

Extracts route arguments into key-value object. path/:foo/:bar vs path/oof/rab = { foo: 'oof', bar: 'rab'}. repeated names will be overriden so, DONT do this: path/:foo/:foo

Kind: instance method of RouteHandler

Param	Type
req	RequestContext

RequestContext

Represents request state.

Kind: global class
Properties

Name	Type	Description
args	Object.<string, string>	holds route arguments
path	string	route path
url	URL	route URL instance
query	Object.<string, (string|Array.<string>)>	search query parameters
options	object	initialization options

• RequestContext
  • new RequestContext(url, options)
  • .setRouteArguments(args)

new RequestContext(url, options)

Creates an instance of RequestContext.

Param	Type
url	string | URL
options	*

requestContext.setRouteArguments(args)

Merges route arguments with given object

Kind: instance method of RequestContext

Param	Type
args	Object.<string, *>

ResponseContext

Represents response state.

Kind: global class
Properties

Name	Type	Description
error	*	if not falsy will be passed to errorHandler
request	RequestContext	processing request's requestContext instance.
locals	*	the legal way to pass data between middlewares

• ResponseContext
  • new ResponseContext(req)
  • .isOk() ⇒ boolean
  • .setError(error) ⇒ ResponseContext
  • .notFound() ⇒ ResponseContext
  • .notAllowed() ⇒ ResponseContext

new ResponseContext(req)

Creates an instance of ResponseContext.

Param	Type
req	RequestContext

responseContext.isOk() ⇒ boolean

Returns true if there is no error, otherwise false

Kind: instance method of ResponseContext

responseContext.setError(error) ⇒ ResponseContext

Sets response error

Kind: instance method of ResponseContext

Param	Type
error	*

responseContext.notFound() ⇒ ResponseContext

Sets 'notfound' error, shorthand for setError('notfound')

Kind: instance method of ResponseContext

responseContext.notAllowed() ⇒ ResponseContext

Sets 'notallowed' error, shorthand for setError('notallowed')

Kind: instance method of ResponseContext

configuration : object

Routing configuration. You can provide your own versions of internal classes and setup some behavior.

Kind: global namespace

startOptions : Object

Kind: global typedef
Properties

Name	Type	Default	Description
[trigger]	boolean	true	If true, will try to invoke handlers for current location
[errorHandlers]	Object.<string, function()>		Error handlers to set into Router instance
[replaceErrorHandlers]	boolean	false	Indicates how errorHandlers should be applied. default behavior is merge
[useHashes]	boolean	false	Enables old school hash based routing

routingOptions : Object

Kind: global typedef
Properties

Name	Type	Description
[errorHandlers]	Object.<string, function()>	Error handlers to set into Router instance