- [define](#define)
- [wrap](#wrap)
- [render](#render)
- [not_found](#not_found)
- [resources](#resources)


-------------------------------------------


# define

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](routes.md).

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:
```js
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)](../../src/router.js#L147)

#### Arguments
* named {string} optional, URL prefix to match on
* routes {array} uncompiled Routes, or routing functions

#### Return
{function} compatible spirit handler, and also a `spirit-router` routing function


-------------------------------------------


# wrap

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](https://github.com/spirit-js/spirit).

`route` can be a [Route](routes.md) or a routing function (created through [define](#define)) with `middlewares`. So `wrap` can be used in both situations.

Example:
```js
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. 

[Source: src/router.js (wrap)](../../src/router.js#L196)

#### Arguments
* route {string} a Route or a routing function
* middlewares {array} an array of spirit middlewares

#### Return
{function} compatible spirit handler, and also a `spirit-router` routing function


-------------------------------------------


# render

`render` is an extendable object with properties that describe how to render return values from a [Route's](routes.md) 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:
```js
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:
```js
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)](../../src/render.js#L17)


-------------------------------------------


# not_found

`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)](../../src/resource.js#L47)

#### Arguments
* method {string} optional, restricts not_found to a certain http method, otherwise matches all
* body {*} the body of not_found's Response

#### Return
{function} a routing function that always returns a 404 Response with `body`


-------------------------------------------


# resources

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:
```js
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](https://www.npmjs.com/package/mime) module.

[Source: src/resource.js (resources)](../../src/resource.js#L6)

#### Arguments
* mount_path {string} optional, virtual URL path to serve file resources from
* options {object} A map (object literal) of options to set

#### Return
{function} a routing function that always matches any request and runs (cannot be wrapped with middlewares)