[ALPHA] Drop-in, ORM agnostic serializer support for Express/Connect Node apps.
Note: this is alpha software, and still undergoing changes. Contributions welcome, consumers beware 😉
$ npm install --save blackburn
Blackburn hooks into your app as an Express/Connect middleware. To use it, you need to supply two things: an adapter, and serializers. Here's a simple example:
// app.js;;let app = ;app;app;// serializers/books.js;;
This sets up blackburn to use the
raw adapter and supplies it with a
books serializer (more on adapters and serializers below).
res.render() by default (although this is customizable). It accepts two arguments:
payload- the data you want to respond with. It can also be a promise which resolves with the intended payload.
options- allows you to pass options through to the renderer. For example, the JSON-API renderer accepts an
includedoption to add sideloaded records to the response.
You can customize the name of blackburn's render method by passing in the "renderMethodName" option:
The blackburn middleware constructor takes several options, show below with their default values:
The goal of blackburn is to give your middleware code a consistent interface to render a JSON response without being concerned about the details of how that response is structured. This lets you separate the presentation of your responses from the work of building them.
There are two main concepts you'll deal with:
- Adapters allow blackburn to understand your ORM (or lack thereof - see the RawAdapter). Because blackburn isn't tied to a specific ORM, it needs to know how to ask your models what type they are, what their relationships are, etc.
- Serializers represent the different output structures and formats. For example, the JSONAPI serializer will send JSONAPI 1.0 compliant responses. Serializers can also let you customize the response, i.e. whitelisting attributes to be included or renaming underscored_keys to camelCased).
For adapters, you'll typically either choose a pre-built, bundled class (i.e. the
MongooseAdapter if you are using Mongoose), or supply your own if your ORM isn't supported out of the box.
For serializers, you'll typically choose a format for your API (i.e. flat JSON, JSONAPI 1.0, etc) and choose a base serializer for that format (i.e. the
JSONAPISerializer). Then each model type will extend from that base serializer and customize which of its attributes and relationships are sent over the wire (i.e. BooksSerializer extends JSONAPISerializer).
Serializers allow you to customize what data is returned the response, and apply simple transformations to it.
By default, you must define a whitelist of all attributes that will be sent back with the response:
If your User model also includes an
hashed_password field, then the serializer above would strip that from the response. One of the benefits here is that the UserSerializer will run whenever a user is serialized, even if it's a related record. This way, you don't need to remember to strip the
hashed_password on every possible route in your app.
You can also customize how the data from your records is serialized, and apply basic transformations to it:
You can also customize how related data is serialized with your records. Serializing relationships is typically much more complex than basic attributes, so you can provide your own config for each relationship to decide how it is serialized.
Only three options are supported by all the built-in serializers:
strategy (required), and
Similar to attributes, you can also perform basic transformations to the relationship and it's properties:
Finally, some serializers may provide more options for serializing relationships. For example, the JSONAPI serializer supports adding relationship links to the payload:
See the documentation for each serializer for available options.
Adapters let the blackburn "speak the same language" as your models, regardless of what ORM you are using. If blackburn doesn't have a built-in adapter for your ORM yet, fear not - they are relatively simple to implement: just 4 methods.
The interface that an adapter must implement:
let CustomAdapter = blackburnAdapter;
That's it! Notice that each method accepts a final argument that is an
options hash. This is the options hash you pass into
res.render(payload, options) from your route handler, so if you need to customize functionality beyond what blackburn allows, that's an easy "escape valve" to handle that.
MIT © Dave Wasmer