ember-setup-middleware-reporter

Utilities to setup server middleware for Ember apps and addons.

Ember apps and addons include a mechanism to setup server middleware in order to inject additional work into the ember-cli pipeline. The process of setting up server middleware is repetitive, so this package provides a few utilities to make it easier.

Installation

npm install @scalvert/ember-setup-middleware-reporter --save-dev

Usage

This package's functions are provided in small, composable pieces. Each allow you to succesively build up a middleware pipeline.

In most cases, using the setupMiddlewareHooks function will be the easiest way to get started. By providing only the name option, this value will be used for both the url and reportDir options. This means that any output generated as the result of this middleware running will be stored in the reportDir directory.

'use strict';

const { setupMiddlewareHooks } = require('ember-setup-middleware-reporter');

module.exports = {
  name: require('./package').name,

  ...setupMiddlewareHooks({
    name: 'deprecation-workflow',
  }),
};

You can additionally provide the following options:

'use strict';

const { setupMiddlewareHooks } = require('ember-setup-middleware-reporter');

module.exports = {
  name: require('./package').name,

  ...setupMiddlewareHooks({
    name: 'deprecation-workflow',
    urlPath: 'deprecations',
    reportDir: 'deprecation-reports',
  }),

This will create a middleware that will listen for requests to the deprecations path. Any requests to this path will be passed through to the deprecation-workflow middleware. The output of this middleware will be stored in the deprecation-reports directory.

It's also possible to provide your own handlers to the middleware. This is useful if you want to add additional functionality not provided out-of-the-box by this package, such as posting data to an API endpoint.

'use strict';

const { setupMiddlewareHooks } = require('ember-setup-middleware-reporter');

module.exports = {
  name: require('./package').name,

  ...setupMiddlewareHooks({
    name: 'deprecation-workflow',
    buildMiddleware: (app, options) => {
      // build and return an array of handlers
      return [
        async (req: Request, res: Response) => {
          await fetch('http://some-domain/some-reporting-endpoint', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
            },
            body: JSON.stringify(req.body),
          });

          res.send({
            success: true,
          });
        },
      ]
    }
  }),

API

setupMiddlewareHooks(options) ⇒

Sets up the middleware hooks that are required by the ember-cli addon. The return value of this function should be merged into the object returned from an ember app or addon's index.js file.

Kind: global function Returns: An object containing a serverMiddleware and testemMiddleware functions that setup the middleware.

| Param | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. | | [options.buildHandlers] | A function that takes the options object and returns an array of handlers. |

Example

'use strict';

const { setupMiddlewareHooks } = require('ember-setup-middleware-reporter');

module.exports = {
  name: require('./package').name,

  ...setupMiddlewareHooks({
    name: 'deprecations',
    reportDir: 'deprecation-reports',
  }),
};

setupMiddleware(app, options) ⇒

A utility function that sets up posting to a specific middleware endpoint for the ember-cli addon.

Kind: global function Returns: An object containing a serverMiddleware and testemMiddleware functions that setup the middleware.

| Param | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | app | The express application. | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. | | [options.buildHandlers] | A function that takes the options object and returns an array of handlers. |

buildDefaultHandlers(app, options) ⇒

Builds an array of default handlers that can be leveraged out of the box by the ember-cli addon. The default handlers include one that writes the response to a file.

Kind: global function Returns: An array of default handlers.

| Param | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | app | The express application. | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. |

buildRootFromOptions(options) ⇒

Builds the root directory for the middleware report.

Kind: global function Returns: A string containing the root directory for the middleware report.

| Param | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. |

buildUrlPathFromOptions(options) ⇒

Builds the URL for the middleware report.

Kind: global function Returns: A string containing the url for the middleware report.

| Param | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. |

buildReportDirFromOptions(options) ⇒

Builds the report directory for the middleware report.

Kind: global function Returns: A string containing the report directory for the middleware report.

| Param | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | options | An options object that contains necessary information for the middleware to run. | | options.name | The name of the middleware. | | [options.urlPath] | The url that the middleware should respond to. If url is not provided, options.name will be used. | | [options.reportDir] | The directory where the reports should be written to. If reportDir is not provided, options.name will be used. |