It compiles routes being passed in, turning them into functions that are wrapped by an internal router.
routes are functions that have been wrapped by a router or uncompiled Routes.
It reduces over them until a route matches and returns a response.
It optionally takes a named argument which is a string used to match the prefix of a incoming request's URL. If there is a match, then routes will be checked. If the prefix of URL does not match named then all routes are essentially skipped.
named can be considered preprending a string to all passed in Routes path.
Note that named is a string, not a string pattern or regexp.
Example:
define("/greet", [
get("/hello", [], "Hello!")
])This would match URLs "/greet/hello" or "/greet/hello/".
It returns a compatible spirit handler that also takes an additional prefix and middlewares argument. And is also considered a routing function in spirit-router.
Source: src/router.js (define)
- named {string} optional, URL prefix to match on
- routes {array} uncompiled Routes, or routing functions
{function} compatible spirit handler, and also a spirit-router routing function
It wraps route with middlewares. Reducing middlewares in order of first to last and then finally route.
middlewares are spirit middlewares.
It is essentially setting route specific middlewares.
The route must match the request URL first before middlewares or the route itself is ever called.
Note that the return value of route will flow back or rewind through middlewares just like in spirit.
route can be a Route or a routing function (created through define) with middlewares. So wrap can be used in both situations.
Example:
define([
wrap(get("/", [], "Hello World"), middlewares)
])
// or
const app = define([
get("/", [], "Hello World")
])
wrap(app, middlewares)Both examples are functionally equivalent but there are subtle differences.
The first is more specific to a route and will only run middlewares for that route.
The second is wrapping all routes in the define and so middlewares will be ran once but after define() matches but before get() matches, but since there is only one, they would produce the same results.
- route {string} a Route or a routing function
- middlewares {array} an array of spirit middlewares
{function} compatible spirit handler, and also a spirit-router routing function
render is an extendable object with properties that describe how to render return values from a Route's body into a spirit Response.
Usually you won't ever need to use this because a lot of common types are already pre-defined on how to render them into a Response.
However if one is missing or you want to replace the default functionality, you would use this to do so.
Determining the type of a value returned by a Route is done through spirit's type_of API. Which can detect common types as well as array, buffer, stream, file-stream, null.
NOTE: the return type of a Route will never be a Promise, it'll always be resolved to it's true value beforehand. And if the return type is a valid spirit.node response map or Response it'll skip this rendering process as it's already a valid response.
Example:
const spirit = require("spirit")
render.string = (request, body) => {
return spirit.response(body)
}Will produce a Response with the return value of a Route's body set as the Response's body whenever the return value of Route's body is a string.
Or:
render.number = (request, body) => {
body = (body + 100).toString()
return spirit.response(body)
}If a Route's body returns a number, this render function will run. Adding 100 to the number returned and converting it into a string and returning a Response with it set as it's response body.
Source: src/render.js (renderables)
notFound is an alias to not_found
Convience function for creating a route that always returns a 404 Response with body as it's body.
body will go through rendering.
Source: src/resource.js (not_found)
- method {string} optional, restricts not_found to a certain http method, otherwise matches all
- body {*} the body of not_found's Response
{function} a routing function that always returns a 404 Response with body
A GET route that returns resources from options.root as a Response. If the file resource doesn't exist, this route will be skipped.
mount_path is an optional argument for specifying a virtual mount point for resources to match. For example:
resources("/files")Given a GET request for "/files/css/style.css" it will look up the resource at options.root + "css/style.css"
By default options has the following properties:
{ root: "public/", mime: {} }
options.mime can be used to specify a mime type to set for the Response based on the file's extension (the "." should be included). For example: resources({ mime: {".html", "text/html"} }). If no match is found, it'll look up the mime type via mime module.
Source: src/resource.js (resources)
- mount_path {string} optional, virtual URL path to serve file resources from
- options {object} A map (object literal) of options to set
{function} a routing function that always matches any request and runs (cannot be wrapped with middlewares)