API documentation

Exported API

The main export is a function that takes a “builder” function and constructs a LazyApp instance with it:

lazorseApp = require('lazorse') ->
  # Build your app here

Or, if you’d rather get back a connect app ready for more .use() calls:

connectApp = require('lazorse').connect ->
  # Again, build the app here

Finally, if you’d rather start a server automatically after the app is built:

require('lazorse').server port: 1234, host: '0.0.0.0', ->
  # A pattern is emerging...

The rest of the API is made up of the methods on LazyApp which are available on @ (this) to your builder function.

App-building

The builder function is called with it’s @ context set to the partially constructed LazyApp instance, it builds out the app by calling methods and/or modifying properties on @

App-building properties

The following properties on @ can be set to alter default behaviours:

@indexPath, @examplePath and @parameterPath:

Prefixes for the location of the default resources. You can disable any of these resources by setting their path prefix to false.

Defaults: '/', '/examples', '/parameters'

@passErrors

Setting this to true will cause unrecognized errors to be passed to @next() by LazyApp.handleErrors.

Default: false

App-building methods

method LazyApp.resource(specs)

Register one or more resources. The specs object should map URI templates to an object describing the resource. For example:

@resource '/{category}/{thing}':
  shortName: "categorizedThing" # for internal linking and client libs.
  description: "Things that belong to a category" # for documentation.
  GET: -> ...
  POST: -> ...
  PUT: -> ...
  examples: [
    {method: 'GET', vars: {category: 'cats', thing: 'jellybean'}}
  ]

method LazyApp.helper(helpers)

Register one or more helper objects. The helpers parameter should be an object that maps helper names to objects/functions.

The helpers will be made available in the context used by coercions and request handlers (see LazyApp.buildContext). So if you register a helper named ‘fryEgg’ it will be available as @fryEgg. If your helper is a function, it will be bound to the request context.

Lazorse installs 4 default helpers into every app:

• @data - Use this as a callback to asynchronous functions that use the callback(err, result) idiom.
• @ok - Sets @res.data and call @next unconditionally.
• @error - Given a constructor function or a name registered with error, and additional constructor arguments, constructs an error and passes it to @next.
• @link - Return a URL path to a resource given it’s shortName and a template expansion context object.

These are added before the builder function is called, so it’s possible (though not recommended) to over-ride or remove them by modifying @helpers.

method LazyApp.coerce(name, description, coercion)

Register a new template parameter coercion with the app.

Parameters:

• name – The name of the template parameter to be coerced.
• description – A documentation string for the parameter name.
• coercion – a (value, next) -> next(err, coercedValue) function that will be called with this set to the request context. If not given, the value will be passed through unchanged (useful for documentation purposes).

See Coercions in the guide for an example.

method LazyApp.render(contentType, renderer)

Register a new renderer function with the app.

Parameters:

• contentType – The content type this renderer handles
• renderer – A middleware that will render data to this content type.

See Rendering in the guide for an example of a custom renderer.

method LazyApp.error(errType, cb)

Register an error constructor with the app. The callback wlll be called by LazyApp.handleErrors when an error of this type is encountered.

Additionally, errors of this type will be available to the @error helper in handler/coercion callback by it’s stringified name.

See named errors in the guide for an example.

Note

Named functions are required. You must use a class for your errors in CoffeeScript as it’s the only way to generate a named function.

method LazyApp.include(path, obj)

Call obj.include in the context of the app. The (optional) path parameter will be prefixed to all resources defined by the include.

method LazyApp.before(existing, new_middle...)

Insert one or more connect middlewares into this apps internal stack.

Parameters:

• existing – The middleware that new middleware should be inserted in front of.
• new_middle – The new middleware to insert. This can be either one or more middleware functions, or a string name of a connect middleware and additional parameters for that middleware.

Examples:

@before @findResource, (req, res, next) ->
  res.setHeader 'X-Nihilo', ''
  next()

@before @findResource, 'static', __dirname + '/public'

Middleware Methods

These methods act as Connect middleware. They remain bound to the app so you can safely pass them to connects .use() method without wrapping them in a callback function.

method LazyApp.findResource(req, res, next)

Find the first resource with a URI template that matches req.url.

Sets req.resource to the spec passed to LazyApp.resource, and req.vars to the extracted URL parameters.

method LazyApp.coerceParams(req, res, next)

Walk through req.vars and call any registered coercions that apply.

method LazyApp.dispatchHandler(req, res, next)

Calls the handler function for the matched resource if it exists.

method LazyApp.renderResponse(req, res, next)

Renders the data in req.data to the client.

Inspects the accept header and falls back to JSON if it can’t find a type it knows how to render. To install or override the renderer for a given content/type use LazyApp.render

method LazyApp.handleErrors(err, req, res, next)

Intercept known errors types and return an appropriate response. If @passErrors is set to false (the default) any unknown error will send a generic 500 error.

Default Resources

Lazorse adds three default resources to every app (unless they are disabled):

Index (default path /):

Returns metadata for all of the named resources in the app, including URI templates, descriptions, and supported HTTP methods, and links to example requests if any are defined.

Examples (default path /examples/{shortName}):

Responds with an array of all of the example requests for the named resource.

Parameters (default paths /parameters/ and /parameters/{parameterName})

Responds with the documentation string for all, or the specifically named, URL parameter coercions given to LazyApp.coerce.

Request Contexts

Every request has a special request context assigned to it. This context is shared by all of the coercions, helpers, and handlers used in a single request.

The context is made up of 2 objects in a delegation chain:

1. An object containing URI Template variables, which delegates to:

2. A request context object containing:

   • All helpers defined for the app using LazyApp.helper.

   • app: The lazorse app

   • req: The request object from node (via connect)

   • res: The response object from node (via connect)

   • error: A callback that will return an error to the client.

   • next: A callback that will pass this request to the next middleware

     in the chain (via connect).

Because this is a delegation chain, you need to be careful not to mask out helper names with variable names.