jigawatt
Influential's Functional, Promise-based Express Middleware
Table of Contents
Installation
npm install jigawatt --save
Using Jigawatt
First, require the module.
const JW = require('jigawatt')
For this walkthrough, we'll also be using Ramda.
const R = require('ramda')
Basic Usage Example
For this example, we have a poll and poll responses stored in a database.
Jigawatt middleware functions, such as getPollResults
in this case, are created to sanitize, validate, and/or normalize the incoming data (awesomize
), then use that awesomized data to query a database (io
), and lastly, format the results to our liking and return the output (transform
).
const getPollResults = pollId : read : R sanitize : RtoLower validate : vrequired poll : dbPoll responses : dbVote poll : datapolltitle results :
Our Jigawatt middleware can then handle a given Express route. Consider the following endpoint:
... app
Example output:
"poll": "What is your favorite city?" "results": "Juneau": 2 "Vladivostok": 3 "Redding": 1 "Wilmington": 0 "Galveston": 2
This might be a bit overwhelming at first sight, so let's break it down in a bit more detail...
Middleware Structure
Jigawatt Middleware expects at least one of the following three properties:
awesomize
awesomize :: Validator -> Request -> Object
- Normalize/Sanitize/Validate an object
- For more detailed documentation about awesomize, visit the awesomize documentation
Awesomize has four components, all of which are optional: read -> sanitize -> validate -> normalize
The read
component has access to the entire object passed to the awesomize function. Here, we'll use Ramda to target a specific value of the object passed:
id : read : R ...
sanitize
is an awesomize component that can manipulate the data before it is validated.
id : read : R sanitize : R ...
validate
is a validator that is passed to our function as v
. Awesomize's validate
component has a few built-in validator methods such as required
, isInt
, isFunction
, etc...
id : read : R validate : vrequired visInt ...
We can also chain validation methods, as seen above. For more info on awesomize validators, visit the documentation.
As a last note about validate
, we can create our own custom validator functions as well:
const isCorrectLength = R ... pollId : sanitize : RtoLower validate : isCorrectLength ...
normalize
is the last awesomize component, called after the data has been validated.
id : read : R validate : vrequired visInt normalize : Rinc
A complete awesomize function can awesomize more than one value:
id : read : R validate : vrequired visInt product : sanitize : Rtrim customer : validate : vrequired
io
io :: Request -> Data -> Object
io
's primary use is to fetch data using the information passed to it from the awesomize function. In the example below, we have io
making two calls to two separate database tables. Once resolved, io
will pass the data fetched from the database along to the transform
method.
poll : dbPoll responses : dbVote
transform
transform :: Request -> Data -> Object
transform
is used to structure the incoming data in a unique way. Remember that transform
is optional, and if omitted, the Jigawatt middleware simply returns the raw results.
const getAnswer = Rarr const getCity = R const tallyVotes = { // Tally total vote for a specific city return R} ... poll : datapolltitle results :
Summary
Our Jigawatt middleware was used to take an incoming ID, query two separate database tables for that ID, and format the results to our liking. The final output of our Jigawatt middleware looks like this:
"poll": "What is your favorite city?" "results": "Juneau": 2 "Vladivostok": 3 "Redding": 1 "Wilmington": 0 "Galveston": 2
Extras
Promisify
If you would like to use a Jigawatt middleware as a promise, you can use the JW.promisify
method:
const getSingleVote = ... ... ... ... const voteDetails = JW ...
Pipe
JW.pipe
can be used to chain multiple Jigawatt middleware together into a single unit:
const combinedJigawatts = JW app
Branch
JW.branch
should be given a predicate, and two Jigawatt middlewares. If the predicate function returns true, the first Jigawatt middleware is called. If false, the latter is called:
const fetchUserDetails =
Contribute
If you find issues with Jigawatt, we encourage you to open an issue ticket on the issues page. Please open a ticket on the issues page before submitting any pull requests!
License
MIT © Influential, Nathan Sculli