jimpex 7.0.2 → 9.0.0

package/src/middlewares/html/fastHTML.js

@@ -1,298 +0,0 @@
-const mime = require('mime');
-const ObjectUtils = require('wootils/shared/objectUtils');
-const { eventNames } = require('../../constants');
-const { middlewareCreator } = require('../../utils/wrappers');
-const { createRouteExpression, removeSlashes } = require('../../utils/functions');
-
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').ExpressNext} ExpressNext
- * @typedef {import('../../types').EventsHub} EventsHub
- * @typedef {import('../../services/common/sendFile').SendFile} SendFile
- * @typedef {import('../../services/html/htmlGenerator').HTMLGenerator} HTMLGenerator
- */
-
-/**
- * @typedef {import('../../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-
-/**
- * The options to customize the behavior of the middleware.
- *
- * @typedef {Object} FastHTMLOptions
- * @property {string}   file          The name of the file the middleware will serve. It
- *                                    can get overwritten if {@link FastHTML} receives an
- *                                    {@link HTMLGenerator}, in that case, the file will
- *                                    be obtained from that service. Default `index.html`.
- * @property {RegExp[]} ignore        A list of regular expressions to match requests
- *                                    paths that should be ignored.
- * @property {boolean}  useAppRoutes  If `true`, {@link FastHTML} will get the list of all
- *                                    routes controlled by {@link Jimpex} and will use
- *                                    them to validate the incoming requests (in addition
- *                                    to `ignore`): If a request URL doesn't match with
- *                                    any of the controlled routes, it will show the HTML
- *                                    file. Default `true`.
- * @parent module:middlewares
- */
-
-/**
- * @typedef {FastHTMLOptions & FastHTMLMiddlewareOptionsProperties} FastHTMLMiddlewareOptions
- * @prettierignore
- */
-
-/**
- * @typedef {Object} FastHTMLMiddlewareOptionsProperties
- * @property {string} htmlGenerator
- * The name of a {@link HTMLGenerator} service for the middleware to use. Default
- * `htmlGenerator`.
- * @parent module:middlewares
- */
-
-/**
- * It's common for an app to show an HTML view when no route was able to handle a request,
- * so the idea behind this middleware is to avoid going to every middleware and controller
- * and just specify that if the request is not for a route handled by a controller, just
- * serve the HTML and avoid processing unnecessary data.
- *
- * A simple example: The app has a route `/backend` that a frontend uses to get
- * information.
- * This middleware can be used to only allow the execution of middlewares and controllers
- * when the request route is for `/backend`.
- *
- * **Disclaimer**: Managing statics files with Express is not a best practice, but there
- * are scenarios where there is not other choice.
- *
- * @parent module:middlewares
- */
-class FastHTML {
-  /**
-   * @param {EventsHub}       events                To listen for the {@link Jimpex} event
-   *                                                triggered after the app starts. The
-   *                                                event is used to get all the
-   *                                                controlled routes, in case the
-   *                                                `useAppRoutes` option is set to true.
-   * @param {SendFile}        sendFile              To send the HTML file response.
-   * @param {FastHTMLOptions} [options={}]          To customize the middleware behavior.
-   * @param {?HTMLGenerator}  [htmlGenerator=null]  If used, the file to serve will be the
-   *                                                one generated by that service.
-   */
-  constructor(events, sendFile, options = {}, htmlGenerator = null) {
-    /**
-     * A local reference for the `events` service.
-     *
-     * @type {EventsHub}
-     * @access protected
-     * @ignore
-     */
-    this._events = events;
-    /**
-     * A local reference for the `sendFile` service.
-     *
-     * @type {SendFile}
-     * @access protected
-     * @ignore
-     */
-    this._sendFile = sendFile;
-    /**
-     * If specified, a reference for a service that generates HTML files.
-     *
-     * @type {?HTMLGenerator}
-     * @access protected
-     * @ignore
-     */
-    this._htmlGenerator = htmlGenerator;
-    /**
-     * The options that tell the middleware which routes should be ignored and which is
-     * the file to serve.
-     *
-     * @type {FastHTMLOptions}
-     */
-    this._options = this._normalizeOptions(
-      ObjectUtils.merge(
-        {
-          file: 'index.html',
-          ignore: options.ignore || [/\.ico$/i],
-          useAppRoutes: true,
-        },
-        options,
-      ),
-    );
-    /**
-     * Whether or not the file is ready to be served, in case there's an
-     * {@link HTMLGenerator}. If the service is used, the HTML is generated after the app
-     * starts,
-     * so the middleware will have to wait for it to be ready before being able to serve
-     * it.
-     *
-     * @type {boolean}
-     * @access protected
-     * @ignore
-     */
-    this._ready = !this._htmlGenerator;
-    /**
-     * A list of regular expression that match the routes controlled by the app. This is
-     * in case the `useAppRoutes` option is set to `true`; when the app gets started, an
-     * event listener will obtain all the top controlled routes, create regular
-     * expressions and save them on this property.
-     *
-     * @type {RegExp[]}
-     * @access protected
-     * @ignore
-     */
-    this._routeExpressions = [];
-    /**
-     * If the option to use the controlled routes is set to `true`, setup the event listener that
-     * gets all the routes when the app is started.
-     */
-    if (this._options.useAppRoutes) {
-      this._setupEvents();
-    }
-  }
-  /**
-   * Returns the Express middleware that validates the routes and serves the HTML file if
-   * necessary.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  middleware() {
-    return (req, res, next) => {
-      if (this._shouldIgnore(req.originalUrl)) {
-        // If the route should be ignored, move to the next middleware.
-        next();
-      } else if (!this._ready) {
-        // If there's an HTMLGenerator and is not ready, wait for it...
-        this._htmlGenerator
-          .whenReady()
-          .then(() => {
-            // Change the flag to prevent the next execution to enter here.
-            this._ready = true;
-            // Serve the file.
-            this._sendHTML(res, next);
-          })
-          .catch((error) => {
-            // Something went wrong while generating the file, send the error to the error handler.
-            next(error);
-          });
-      } else {
-        // The route is not ignored and the file is ready to be served, so do it.
-        this._sendHTML(res, next);
-      }
-    };
-  }
-  /**
-   * The options that tell the middleware which routes should be ignored and which is the
-   * file to serve.
-   *
-   * @type {FastHTMLOptions}
-   * @todo Remove Object.freeze.
-   */
-  get options() {
-    return Object.freeze(this._options);
-  }
-  /**
-   * Normalizes and validates the options recevied on the constructor.
-   * If the class is using a {@link HTMLGenerator} service, the method will overwrite the
-   * `file`
-   * option with the result of the service's `getFile()` method.
-   *
-   * @param {FastHTMLOptions} options  The received options.
-   * @returns {FastHTMLOptions}
-   * @throws {Error} If no file and no {@link HTMLGenerator} service are specified.
-   * @throws {Error} If no routes to ignore are specified and `useAppRoutes` is set to
-   *                 `false`.
-   * @access protected
-   * @ignore
-   */
-  _normalizeOptions(options) {
-    if (!options.file && !this._htmlGenerator) {
-      throw new Error('You need to either define an HTMLGenerator service or a file');
-    } else if (!options.ignore.length && !options.useAppRoutes) {
-      throw new Error(
-        'You need to either define a list of routes to ignore or use `useAppRoutes`',
-      );
-    }
-
-    return this._htmlGenerator
-      ? { ...options, file: this._htmlGenerator.getFile() }
-      : options;
-  }
-  /**
-   * Serves the file on the response.
-   *
-   * @param {ExpressResponse} res   The server response.
-   * @param {ExpressNext}     next  The function to call the next middleware.
-   * @access protected
-   * @ignore
-   */
-  _sendHTML(res, next) {
-    res.setHeader('Content-Type', mime.getType('html'));
-    this._sendFile(res, this._options.file, next);
-  }
-  /**
-   * Adds the event listener that obtains the controlled routes when `useAppRoutes` is set
-   * to `true`.
-   *
-   * @access protected
-   * @ignore
-   */
-  _setupEvents() {
-    this._events.once(eventNames.afterStart, ({ routes }) => {
-      // Re generate the list of expressions...
-      this._routeExpressions = routes
-        // Remove leading and trailing slashes.
-        .map((route) => removeSlashes(route).trim())
-        // Filter empty routes (in case they were for `/`).
-        .filter((route) => route !== '')
-        // Remove repeated routes.
-        .reduce(
-          (unique, route) => (unique.includes(route) ? unique : [...unique, route]),
-          [],
-        )
-        // Generate regular expressions for each route.
-        .map((route) => createRouteExpression(route));
-    });
-  }
-  /**
-   * Checks whether a route should be ignored or not. The method checks first against the
-   * `ignore`
-   * option, and then against the controlled routes (if `useAppRoutes` is `false`, the
-   * list will be empty).
-   *
-   * @param {string} route  The route to validate.
-   * @returns {boolean}
-   * @access protected
-   * @ignore
-   */
-  _shouldIgnore(route) {
-    return (
-      this._options.ignore.some((expression) => expression.test(route)) ||
-      this._routeExpressions.some((expression) => expression.test(route))
-    );
-  }
-}
-/**
- * A middleware for filtering routes so you can serve an HTML before the app gets to
- * evaluate whether there's a controller for the requested route or not. For more
- * information about the reason of this middleware, please read the description of
- * {@link FastHTML}.
- *
- * @type {MiddlewareCreator<FastHTMLMiddlewareOptions>}
- * @parent module:middlewares
- */
-const fastHTML = middlewareCreator((options = {}) => (app) => {
-  const htmlGeneratorServiceName =
-    typeof options.htmlGenerator === 'undefined'
-      ? 'htmlGenerator'
-      : options.htmlGenerator;
-  return new FastHTML(
-    app.get('events'),
-    app.get('sendFile'),
-    options,
-    htmlGeneratorServiceName ? app.try(htmlGeneratorServiceName) : null,
-  ).middleware();
-});
-
-module.exports.FastHTML = FastHTML;
-module.exports.fastHTML = fastHTML;

package/src/middlewares/html/index.js

@@ -1,5 +0,0 @@
-const { fastHTML } = require('./fastHTML');
-const { showHTML } = require('./showHTML');
-
-module.exports.fastHTML = fastHTML;
-module.exports.showHTML = showHTML;

package/src/middlewares/html/showHTML.js

@@ -1,167 +0,0 @@
-const mime = require('mime');
-const { middlewareCreator } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').ExpressNext} ExpressNext
- * @typedef {import('../../services/common/sendFile').SendFile} SendFile
- * @typedef {import('../../services/html/htmlGenerator').HTMLGenerator} HTMLGenerator
- */
-
-/**
- * @typedef {import('../../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-
-/**
- * A set options to customize the middleware behavior.
- *
- * @typedef {Object} ShowHTMLMiddlewareOptions
- * @property {string} file           The name of the file the middleware will serve.
- *                                   Default `'index.html'`.
- * @property {string} htmlGenerator  The name of a {@link HTMLGenerator} service for the
- *                                   middleware to use. If the service is available, the
- *                                   value of `file` will be overwritten for the file
- *                                   generated by the service. Default `'htmlGenerator'`.
- * @parent module:middlewares
- */
-
-/**
- * A very simple middleware service to send an HTML on a server response. The special
- * _'feature'_ of this service is that it can be hooked up to an `HTMLGenerator` service
- * and it will automatically server the file generated by it.
- *
- * @parent module:middlewares
- */
-class ShowHTML {
-  /**
-   * @param {SendFile}      sendFile              Necessary to server the HTML file.
-   * @param {string}        [file='index.html']   The name of the file it will serve. If
-   *                                              `htmlGenerator` is specified, this will
-   *                                              be overwritten with the name of the file
-   *                                              generated by that service.
-   * @param {HTMLGenerator} [htmlGenerator=null]  If used, the file to server will be the
-   *                                              one generated by that service.
-   */
-  constructor(sendFile, file = 'index.html', htmlGenerator = null) {
-    /**
-     * A local reference for the `sendFile` service.
-     *
-     * @type {SendFile}
-     * @access protected
-     * @ignore
-     */
-    this._sendFile = sendFile;
-    /**
-     * The name of the file to serve.
-     *
-     * @type {string}
-     * @access protected
-     * @ignore
-     */
-    this._file = file;
-    /**
-     * If specified, a reference for a service that generates HTML files.
-     *
-     * @type {HTMLGenerator}
-     * @access protected
-     * @ignore
-     */
-    this._htmlGenerator = htmlGenerator;
-    /**
-     * Whether or not the file is ready to be served.
-     *
-     * @type {boolean}
-     * @access protected
-     * @ignore
-     */
-    this._ready = true;
-    // If an `HTMLGenerator` service was specified...
-    if (this._htmlGenerator) {
-      // ...get the name of the file from that service.
-      this._file = this._htmlGenerator.getFile();
-      /**
-       * Mark the `_ready` flag as `false` as this service needs to wait for the generator to
-       * create the file.
-       */
-      this._ready = false;
-    }
-  }
-  /**
-   * Returns the Express middleware that serves the HTML file.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  middleware() {
-    return (req, res, next) => {
-      // If `_ready` is `false`
-      if (!this._ready) {
-        /**
-         * It means that it's using the `HTMLGenerator` service, so it
-         * calls the method that will notify this service when the file has been created and is
-         * ready to be loaded.
-         */
-        this._htmlGenerator
-          .whenReady()
-          .then(() => {
-            // The file is ready to use, so mark the `_ready` flag as `true`.
-            this._ready = true;
-            // Serve the file.
-            this._sendHTML(res, next);
-          })
-          .catch((error) => {
-            // Something happened while generating the file, send the error the next middlware.
-            next(error);
-          });
-      } else {
-        /**
-         * If `_ready` is `true` it means that the `HTMLGenerator` has already created the file on
-         * a previous request or it was never specified, so just serve the file.
-         */
-        this._sendHTML(res, next);
-      }
-    };
-  }
-  /**
-   * The name of the file to serve.
-   *
-   * @type {string}
-   */
-  get file() {
-    return this._file;
-  }
-  /**
-   * Serves the file on the response.
-   *
-   * @param {ExpressResponse} res   The server response.
-   * @param {ExpressNext}     next  The functino to call the next middleware.
-   * @access protected
-   * @ignore
-   */
-  _sendHTML(res, next) {
-    res.setHeader('Content-Type', mime.getType('html'));
-    this._sendFile(res, this._file, next);
-  }
-}
-/**
- * A middleware for showing an `index.html` file.
- *
- * @type {MiddlewareCreator<ShowHTMLMiddlewareOptions>}
- * @parent module:middlewares
- */
-const showHTML = middlewareCreator((options = {}) => (app) => {
-  const htmlGeneratorServiceName =
-    typeof options.htmlGenerator === 'undefined'
-      ? 'htmlGenerator'
-      : options.htmlGenerator;
-
-  return new ShowHTML(
-    app.get('sendFile'),
-    options.file,
-    htmlGeneratorServiceName ? app.try(htmlGeneratorServiceName) : null,
-  ).middleware();
-});
-
-module.exports.ShowHTML = ShowHTML;
-module.exports.showHTML = showHTML;

package/src/middlewares/index.js

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

package/src/middlewares/utils/index.js

@@ -1,3 +0,0 @@
-const { versionValidator } = require('./versionValidator');
-
-module.exports.versionValidator = versionValidator;