jimpex 7.0.2 → 8.0.0

package/src/constants/eventNames.js

@@ -1,48 +0,0 @@
-/**
- * The name of all the events {@link Jimpex} can trigger.
- *
- * @typedef {Object} JimpexEvents
- * @property {string} beforeStop               Called before closing the instance of the
- *                                             app.
- * @property {string} start                    Called from the `listen` callback, when the
- *                                             app is ready to be used.
- * @property {string} afterStart               Called from the `listen` callback, when all
- *                                             controllers and middlewares have been
- *                                             mounted.
- * @property {string} afterStartCallback       Called right after the callback sent to
- *                                             `start`
- *                                             gets executed.
- * @property {string} beforeStart              Called before `listen` is executed on the
- *                                             Express app.
- * @property {string} afterStop                Called after the app instance has been
- *                                             closed and deleted.
- * @property {string} routeAdded               Called every time a new route is added to
- *                                             the app.
- * @property {string} controllerWillBeMounted  This is for a reducer event. It gets called
- *                                             before mounting a router or a set of routes
- *                                             to the app in order to "reduce it".
- * @property {string} middlewareWillBeUsed     This is for a reducer event. It gets called
- *                                             before using a middleware in order to
- *                                             "reduce it".
- * @parent module:constants
- */
-
-/**
- * The name of all the events {@link Jimpex} can trigger.
- *
- * @type {JimpexEvents}
- * @parent module:constants
- */
-const eventNames = {
-  beforeStart: 'before-start',
-  start: 'start',
-  afterStart: 'after-start',
-  afterStartCallback: 'after-start-callback',
-  beforeStop: 'before-stop',
-  afterStop: 'after-stop',
-  controllerWillBeMounted: 'controller-will-be-mounted',
-  routeAdded: 'route-added',
-  middlewareWillBeUsed: 'middleware-will-be-used',
-};
-
-module.exports = eventNames;

package/src/constants/index.js

@@ -1,7 +0,0 @@
-const eventNames = require('./eventNames');
-
-/**
- * @module constants
- */
-
-module.exports.eventNames = eventNames;

package/src/controllers/common/configuration.js

@@ -1,116 +0,0 @@
-const { controller } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').AppConfiguration} AppConfiguration
- * @typedef {import('../../services/http/responsesBuilder').ResponsesBuilder} ResponsesBuilder
- * @typedef {import('../../types').Controller} Controller
- * @prettierignore
- */
-
-/**
- * Provides the handlers and middlwares to show and switch configurations.
- *
- * @parent module:controllers
- */
-class ConfigurationController {
-  /**
-   * @param {AppConfiguration} appConfiguration  To read the app configuration.
-   * @param {ResponsesBuilder} responsesBuilder  To generate the JSON responses.
-   */
-  constructor(appConfiguration, responsesBuilder) {
-    /**
-     * A local reference for the `appConfiguration` service.
-     *
-     * @type {AppConfiguration}
-     * @access protected
-     * @ignore
-     */
-    this._appConfiguration = appConfiguration;
-    /**
-     * A local reference for the `responsesBuilder` service.
-     *
-     * @type {ResponsesBuilder}
-     * @access protected
-     * @ignore
-     */
-    this._responsesBuilder = responsesBuilder;
-  }
-  /**
-   * Send a response with the current app configuration as a body.
-   *
-   * @param {ExpressResponse} res  The server response.
-   */
-  getConfigurationResponse(res) {
-    const name = this._appConfiguration.get('name');
-    const data = {
-      name,
-      ...this._appConfiguration.getConfig(),
-    };
-
-    this._responsesBuilder.json(res, data);
-  }
-  /**
-   * Returns the middleware to show the current configuration.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  showConfiguration() {
-    return (req, res) => {
-      this.getConfigurationResponse(res);
-    };
-  }
-  /**
-   * Returns the middleware to switch the current configuration.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  switchConfiguration() {
-    return (req, res, next) => {
-      if (this._appConfiguration.canSwitch()) {
-        try {
-          this._appConfiguration.switch(req.params.name);
-          this.getConfigurationResponse(res);
-        } catch (error) {
-          next(error);
-        }
-      } else {
-        next();
-      }
-    };
-  }
-}
-/**
- * This controller is kind of special as it will only mount the routes if the
- * `debug.configurationController` setting of the app configuration is `true`.
- * It provides routes for:
- * - Showing the current configuration.
- * - Switching the configuration, but only if the service allows it.
- *
- * @type {Controller}
- * @parent module:controllers
- * @todo Don't use an array to return the routes.
- */
-const configurationController = controller((app) => {
-  const routes = [];
-  const appConfiguration = app.get('appConfiguration');
-  if (appConfiguration.get('debug.configurationController') === true) {
-    const router = app.get('router');
-    const ctrl = new ConfigurationController(
-      appConfiguration,
-      app.get('responsesBuilder'),
-    );
-    routes.push(
-      ...[
-        router.get('/', ctrl.showConfiguration()),
-        router.get('/switch/:name', ctrl.switchConfiguration()),
-      ],
-    );
-  }
-
-  return routes;
-});
-
-module.exports.ConfigurationController = ConfigurationController;
-module.exports.configurationController = configurationController;

package/src/controllers/common/health.js

@@ -1,79 +0,0 @@
-const { code: statuses } = require('statuses');
-const { controller } = require('../../utils/wrappers');
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').AppConfiguration} AppConfiguration
- * @typedef {import('../../types').Controller} Controller
- * @typedef {import('../../services/http/responsesBuilder').ResponsesBuilder} ResponsesBuilder
- * @prettierignore
- */
-
-/**
- * Provides the handler to show a some minimal health information about the app:
- * - app version.
- * - configuration name.
- *
- * @parent module:controllers
- */
-class HealthController {
-  /**
-   * @param {AppConfiguration} appConfiguration  To read the app version and the
-   *                                             configuration name.
-   * @param {ResponsesBuilder} responsesBuilder  To generate the JSON response.
-   */
-  constructor(appConfiguration, responsesBuilder) {
-    /**
-     * A local reference for the `appConfiguration` service.
-     *
-     * @type {AppConfiguration}
-     * @access protected
-     * @ignore
-     */
-    this._appConfiguration = appConfiguration;
-    /**
-     * A local reference for the `responsesBuilder` service.
-     *
-     * @type {ResponsesBuilder}
-     * @access protected
-     * @ignore
-     */
-    this._responsesBuilder = responsesBuilder;
-  }
-  /**
-   * Returns the middleware that shows the health information.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  health() {
-    return (req, res) => {
-      const { name: configuration, version } = this._appConfiguration.get([
-        'name',
-        'version',
-      ]);
-      this._responsesBuilder.json(res, {
-        isHealthy: true,
-        status: statuses.ok,
-        configuration,
-        version,
-      });
-    };
-  }
-}
-/**
- * Mounts the health route.
- *
- * @type {Controller}
- * @parent module:controllers
- */
-const healthController = controller((app) => {
-  const router = app.get('router');
-  const ctrl = new HealthController(
-    app.get('appConfiguration'),
-    app.get('responsesBuilder'),
-  );
-
-  return [router.get('/', ctrl.health())];
-});
-
-module.exports.HealthController = HealthController;
-module.exports.healthController = healthController;

package/src/controllers/common/index.js

@@ -1,7 +0,0 @@
-const { configurationController } = require('./configuration');
-const { healthController } = require('./health');
-const { staticsController } = require('./statics');
-
-module.exports.configurationController = configurationController;
-module.exports.healthController = healthController;
-module.exports.staticsController = staticsController;

package/src/controllers/common/statics.js

@@ -1,336 +0,0 @@
-const path = require('path');
-const ObjectUtils = require('wootils/shared/objectUtils');
-const mime = require('mime');
-const { controllerCreator } = require('../../utils/wrappers');
-const { removeSlashes } = require('../../utils/functions');
-
-/**
- * @typedef {import('../../app').Jimpex} Jimpex
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressRouter} ExpressRouter
- * @typedef {import('../../types').Controller} Controller
- * @typedef {import('../../types').MiddlewareLike} MiddlewareLike
- * @typedef {import('../../services/common/sendFile').SendFile} SendFile
- */
-
-/**
- * @typedef {import('../../types').ControllerCreator<O>} ControllerCreator<O>
- * @template O
- */
-
-/**
- * If you wan to customize how, to, and from where files are served, instead of just
- * sending a list of strings, you can use an object with these properties.
- *
- * @typedef {Object} StaticsControllerFile
- * @property {string}                  route    The route the controller will use for the
- *                                              file.
- * @property {string}                  path     The path for the file, relative to the
- *                                              root of the app.
- * @property {Object.<string, string>} headers  A dictionary of custom headers to send on
- *                                              the file response.
- * @parent module:controllers
- */
-
-/**
- * They are like "master paths" that get prepended to all the file paths and routes the
- * controller use.
- *
- * @typedef {Object} StaticsControllerPathsOptions
- * @property {string} route   A custom route to prefix all the file routes.
- * @property {string} source  A custom path to prefix all the file paths.
- * @parent module:controllers
- */
-
-/**
- * @typedef {string | StaticsControllerFile} StaticsControllerFileLike
- * @parent module:controllers
- */
-
-/**
- * These are the options that allow you to customize the controller, how, to and from
- * where the files are served.
- *
- * @typedef {Object} StaticsControllerOptions
- * @property {StaticsControllerFileLike[]}   files    A list of filenames or
- *                                                    {@link StaticsControllerFile}
- *                                                    definitions.
- * @property {Object.<string, boolean>}      methods  A dictionary of all the HTTP methods
- *                                                    the controller will use in order to
- *                                                    serve the files. If `all` is set to
- *                                                    true, all the other flags will be
- *                                                    ignored.
- * @property {StaticsControllerPathsOptions} paths    The "master paths" the controller
- *                                                    uses to prefix all file routes and
- *                                                    paths.
- * @parent module:controllers
- */
-
-/**
- * @typedef {StaticsControllerOptions & StaticsControllerWrapperOptionsProperties} StaticsControllerWrapperOptions
- * @parent module:controllers
- * @prettierignore
- */
-
-/**
- * @typedef {Object} StaticsControllerWrapperOptionsProperties
- * @property {StaticsControllerMiddlewaresFn} middlewares
- * Function can be used to add custom middlewares on the file routes. If implemented, it
- * must return a list of middlewares when executed.
- * @parent module:controllers
- */
-
-/**
- * @callback StaticsControllerMiddlewaresFn
- * @param {Jimpex} app  A reference for the container.
- * @returns {MiddlewareLike[]}
- * @parent module:controllers
- */
-
-/**
- * This controller allows you to serve specific files from any folder to any route without
- * the need of mounting directories as "static".
- *
- * @parent module:controllers
- */
-class StaticsController {
-  /**
-   * @param {SendFile} sendFile
-   * To send the responses for the files.
-   * @param {Partial<StaticsControllerOptions>} options
-   * The options to customize the controller.
-   */
-  constructor(sendFile, options = {}) {
-    /**
-     * A local reference for the `sendFile` service.
-     *
-     * @type {SendFile}
-     * @access protected
-     * @ignore
-     */
-    this._sendFile = sendFile;
-    /**
-     * The controller configuration options.
-     *
-     * @type {StaticsControllerOptions}
-     * @access protected
-     * @ignore
-     */
-    this._options = this._normalizeOptions(
-      ObjectUtils.merge(
-        {
-          files: options.files || ['favicon.ico', 'index.html'],
-          methods: {
-            all: false,
-            get: true,
-          },
-          paths: {
-            route: '',
-            source: './',
-          },
-        },
-        options,
-      ),
-    );
-    /**
-     * A dictionary of all the formatted files ({@link StaticsControllerFile}). It uses
-     * the files routes as keys.
-     *
-     * @type {Object.<string, StaticsControllerFile>}
-     * @access protected
-     * @ignore
-     */
-    this._files = this._createFiles();
-  }
-  /**
-   * Defines all the needed routes to serve the files.
-   *
-   * @param {ExpressRouter}       router            To generate the routes.
-   * @param {ExpressMiddleware[]} [middlewares=[]]  A list of custom middlewares that will
-   *                                                be added before the one that serves a
-   *                                                file.
-   * @returns {ExpressRouter}
-   */
-  addRoutes(router, middlewares = []) {
-    const { methods } = this._options;
-    const use = methods.all
-      ? ['all']
-      : Object.keys(methods).reduce(
-          (acc, name) => (methods[name] ? [...acc, name] : acc),
-          [],
-        );
-
-    Object.keys(this._files).forEach((route) => {
-      const file = this._files[route];
-      const fileMiddleware = this._getMiddleware(file);
-      use.forEach((method) =>
-        this._addRoute(router, method, file, fileMiddleware, middlewares),
-      );
-    });
-
-    return router;
-  }
-  /**
-   * The controller configuration options.
-   *
-   * @type {StaticsControllerOptions}
-   * @todo Remove Object.freeze.
-   */
-  get options() {
-    return Object.freeze(this._options);
-  }
-  /**
-   * Generates a route for an specific file.
-   *
-   * @param {ExpressRouter}         router          To create the actual route.
-   * @param {string}                method          The HTTP method for the route.
-   * @param {StaticsControllerFile} file            The file information.
-   * @param {ExpressMiddleware}     fileMiddleware  The middleware that serves the file.
-   * @param {ExpressMiddleware[]}   middlewares     A list of custom middlewares to add
-   *                                                before the one that serves the file.
-   * @returns {ExpressRouter}
-   * @access protected
-   * @ignore
-   */
-  _addRoute(router, method, file, fileMiddleware, middlewares) {
-    return router[method](file.route, [...middlewares, fileMiddleware]);
-  }
-  /**
-   * Parses each of the received files in order to create a {@link StaticsControllerFile}.
-   *
-   * @returns {Object.<string, StaticsControllerFile>}
-   * @access protected
-   * @ignore
-   */
-  _createFiles() {
-    const { files, paths } = this._options;
-    const routePath = removeSlashes(paths.route, false, true);
-    return files.reduce((formatted, file) => {
-      let source;
-      let route;
-      let headers;
-      if (typeof file === 'object') {
-        ({ route, source, headers } = file);
-      } else {
-        source = file;
-        route = file;
-      }
-
-      source = path.join(paths.source, source);
-      route = removeSlashes(route, true, false);
-      route = `${routePath}/${route}`;
-
-      return {
-        ...formatted,
-        [route]: {
-          source,
-          route,
-          headers: headers || {},
-        },
-      };
-    }, {});
-  }
-  /**
-   * Generates the middleware to serve a specific file.
-   *
-   * @param {StaticsControllerFile} file  The file information.
-   * @returns {ExpressMiddleware}
-   * @access protected
-   * @ignore
-   */
-  _getMiddleware(file) {
-    return (req, res, next) => {
-      const extension = path.parse(file.source).ext.substr(1);
-      const headers = ObjectUtils.merge(
-        { 'Content-Type': mime.getType(extension) },
-        file.headers,
-      );
-
-      Object.keys(headers).forEach((headerName) => {
-        res.setHeader(headerName, headers[headerName]);
-      });
-
-      this._sendFile(res, file.source, next);
-    };
-  }
-  /**
-   * Helper method that validates and normalizes the options received by the controller.
-   *
-   * @param {StaticsControllerOptions} options  The options to validate.
-   * @returns {StaticsControllerOptions}
-   * @throws {Error} If no files are specified.
-   * @throws {Error} If methods is not defined.
-   * @throws {Error} If no methods are enabled.
-   * @throws {Error} If there's an invalid HTTP method.
-   * @access protected
-   * @ignore
-   */
-  _normalizeOptions(options) {
-    if (!options.files || !options.files.length) {
-      throw new Error('You need to specify a list of files');
-    } else if (!options.methods) {
-      throw new Error('You need to specify which HTTP methods are allowed for the files');
-    }
-
-    const methods = Object.keys(options.methods);
-
-    const atLeastOne = methods.some((method) => options.methods[method]);
-    if (!atLeastOne) {
-      throw new Error('You need to enable at least one HTTP method to serve the files');
-    }
-
-    const allowedMethods = [
-      'all',
-      'get',
-      'head',
-      'post',
-      'put',
-      'delete',
-      'connect',
-      'options',
-      'trace',
-    ];
-
-    const invalid = methods.find(
-      (method) => !allowedMethods.includes(method.toLowerCase()),
-    );
-    if (invalid) {
-      throw new Error(`${invalid} is not a valid HTTP method`);
-    }
-
-    const newMethods = methods.reduce(
-      (acc, method) => ({
-        ...acc,
-        [method.toLowerCase()]: options.methods[method],
-      }),
-      {},
-    );
-
-    return {
-      ...options,
-      methods: newMethods,
-    };
-  }
-}
-/**
- * This controller allows you to serve specific files from any folder to any route without
- * the need of mounting directories as "static".
- *
- * @type {ControllerCreator<StaticsControllerWrapperOptions>}
- * @parent module:controllers
- */
-const staticsController = controllerCreator((options = {}) => (app) => {
-  const router = app.get('router');
-  const ctrl = new StaticsController(app.get('sendFile'), options);
-  let useMiddlewares;
-  if (options.middlewares) {
-    useMiddlewares = options
-      .middlewares(app)
-      .map((middleware) => (middleware.connect ? middleware.connect(app) : middleware));
-  }
-
-  return ctrl.addRoutes(router, useMiddlewares);
-});
-
-module.exports.StaticsController = StaticsController;
-module.exports.staticsController = staticsController;

package/src/controllers/index.js

@@ -1,9 +0,0 @@
-const common = require('./common');
-const utils = require('./utils');
-
-/**
- * @module module:controllers
- */
-
-module.exports.common = common;
-module.exports.utils = utils;