Express Waterline
Automagic API built from Waterline models and ExpressJS
Getting started
Pass your Waterline config object to the waterline.init
function.
The waterline.init
function returns a middleware that handles all your API routing
;; // Parsers; let app = ; // Required to parse `req.body`app; // Express Waterline middleware configurationapp;
Accessing Waterline models
Any model can be accessed by passing the model name to the default method. The default method returns a promise resolving to the desired model.
; let Person = ; Person;
Extra fanciness
Waterline models are great, but there were a few extra features that we thought would be nifty to have:
Model extension
Waterline by default doesn't support extending models like classes. It's nice, if say, several models share similar ACLs, attributes, or database configuration.
All you have to do is define the property base
and the name of the model you're extending
// models/person.js identity: 'person' connection: 'mongo' autoPK: true autoCreatedAt: false lifecycle: { if !requser throw 'Unauthorized'; } // models/customer.js identity: 'customer' base: 'person' autoPK: false lifecycle: { // Other stuff } // Customer model will look like this: identity: 'customer' connection: 'mongo' autoPK: false autoCreatedAt: false lifecycle: beforeAccess: { if !requser throw 'Unauthorized'; } { // Other stuff }
Multi-tenant support
One frusterating thing about Waterline is that it's a singleton. It makes it difficult to use multiple database connections using the same models. As a workaround, you can add an environment suffix to a clone of each model, and create several DB connections. Managing that can be difficult, especially with foreign keys having to match.
To implement multi-tenancy in Express Waterline, simply pass an array of connection configurations, each with the added key
tenantId
. Express Waterline does the rest!
Configuration
;; ;
tenantKey
Express Waterline will search for the tenantKey in the request headers and query string
Lifecycle Callback Context
Waterline models come with built in lifecycle callbacks, but they don't give much context other than the values of the instances you're modifying.
Express Waterline adds two extra methods beforeAccess
and afterAccess
to give you the ability to modify the query and the response of GET
requests.
Express Waterline models include the Express request a second argument.
The third argument is a node callback, but you can return a synchronous value or a Promise resolving to the value instead.
Because query
and body
are objects, the values defined in them are pass-by-reference, so you can return undefined too!
models/person.js
'use strict'; ;; identity: 'utility-company' tableName: 'Utility_Company__c' attributes: name: type: 'string' columnName: 'Name' state: type: 'string' columnName: 'Service_Address_State__c' password: type: 'string' columnName: 'password' lifecycle: // Happens before all GET requests { ; return query; } // Happens before POST, and PUT requests { if bodypassword let hash = crypto; hash; bodypassword = hash; } // Happens after POST, and PUT requests { delete bodypassword; } ;