middle-run

Run a series of async middleware functions on both client and server.

middle-run is a simple library to compose and run ES7 async functions in order. This allows you to build out a process in a manner similar to Connect, only not necessarily specific to fulfilling a request on a server. middle-run can be used on both client and server.

Quick Example

npm install middle-run --save

import run from 'middle-run'
 
run([
  // middleware can be synchronous
  function (step) {
    // the namespace object is always passed as the first argument
    // the context property is shared across all middleware functions
    step.context.foo = 'bar'
    // the next middleware is automatically run after this completes
  },
  // async functions can be used for a "true" middleware
  async function ({ context, next }) {
    let start = Date.now()
    // next causes the next middleware to begin
    await next()
    // after awaiting next() to resolve, all downstream middleware are done
    context.duration = Date.now() - start
  },
  // since run returns a function with the same signature of middleware
  // you can compose multiple together if needed
  run([
    ({ resolve }) => {
      // all info is passed in the first argument, no need for `this`
      // resolve() prevents further downstream middleware from running
      // you can optionally resolve to a particular value,
      // the top-level promise will resolve to this value
      resolve('someValue')
    }
  ]),
  () => {
    // this won't run because `resolve()` was called
  }
 
// run returns a function with the same signature as a middleware function
// to start the series, pass in the desired context object
// you can optionally pass in functions that are called when the series completes
// and when the series is stopped
])({ context: {}, next() {}, resolve() {} })

API

run

import run from 'middle-run'
// or var run = require('middle-run')
 
run(middleware)({ context: {}, extra: 'stuff' })
  .then(function (value) {})

run is a function that takes an array of middleware functions, and returns a middleware function. Run the series of middleware by calling the function, and optionally pass in an object with properties to add to the argument given to each middleware.

middleware function

run([
  async ({ context, next, resolve }) => {
    let v1 = await next()
    let v2 = await resolve('foo')
    v1 === 'foo' // true
    v2 === 'foo' // true
  }
])

Each middleware function recieves a single object argument containing a context object, a next function, and a resolve function. Properties of the object passed to the function returned from run will also be added to the object passed.

context

By default, the context is an object that is part of the middleware argument. The same object will be passed to each and every middleware that runs.

You can replace the default object with whatever you like by passing a context property to the top-level middleware returned by run.

Any properties added to the root argument object will not be carried to next middleware, so if you need something shared, context is the place to put it.

next

Calling next() will immediately start the next middleware, and return a promise that will resolve to the value passed to resolve in a downstream middleware. When the promise resolves, all downstream middleware have completely finished running.

Control will continue upstream when this middleware returns (or resolves if it is an async function or returns a promise), or as soon as resolve is called.

next should only be called once, but if you do call next again in the same middleware function, it will simply return the same promise it did initially.

resolve

Calling resolve() will allow control to flow back to the previous middleware, even if this middleware function hasn't completed. A value can be passed as the first argument, and will set the value to resolve the whole series with.

resolve returns a promise that will resolve to the final value, which may have been changed by upstream middleware.

Calling resolve will prevent any downstream middleware from running if called before this middleware has completed or next is called. If next is called after resolve, it will not trigger the next middleware, but will return a promise that resolves to the current value (last passed to resolve).

Async Middleware

middle-run can work with any promised-based async middleware, but it was designed specifically for ES7 async functions. Inspired by koa's yield next, middle-run allows you to await next() so you can next() "downstream" and the await for control to flow back "upstream".

This is a barebones middleware runner, and has no use() methods or other ways to build out the list of middlewares, nor any url routing logic. Expanding the argument object with properties passed in the object to the function returned by run hopefully is enough to make middle-run useful in building a router or app framework.

License

This software is free to use under the MIT license. See the LICENSE-MIT file for license text and copyright information.