jimpex 7.0.1 → 8.0.0

package/src/middlewares/utils/versionValidator.js

@@ -1,261 +0,0 @@
-const ObjectUtils = require('wootils/shared/objectUtils');
-const { code: statuses } = require('statuses');
-const { middlewareCreator } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressRequest} ExpressRequest
- * @typedef {import('../../services/http/responsesBuilder').ResponsesBuilder} ResponsesBuilder
- * @prettierignore
- */
-
-/**
- * @typedef {import('../../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-
-/**
- * The options for how the middleware should behave if the requested version is `latest`.
- *
- * @typedef {Object} VersionValidatorLatestOptions
- * @property {boolean} allow  Whether or not the middleware should validate the _"latest
- *                            version"_.
- *                            Default `true`.
- * @property {string}  name   The name of the _"latest version"_. Basically,
- *                            `req.params.version`
- *                            must match with this property in order to be consider
- *                            "latest".
- *                            Default `'latest'`.
- * @parent module:middlewares
- */
-
-/**
- * The options for how to detect if the request comes from a popup and how to compose the
- * post message the middleware will use to respond.
- *
- * @typedef {Object} VersionValidatorPopupOptions
- * @property {string} variable  The name of the query string variable the middleware will
- *                              check in order to indentify whether the request comes from
- *                              a popup or not.
- *                              The variable must have `'true'` as its value. Default
- *                              `'popup'`.
- * @property {string} title     The title of the page that will be generated to respond in
- *                              case the versions don't match. Default `'Conflict'`.
- * @property {string} message   The contents of the post message the generated page will
- *                              send if the versions don't match. Default
- *                              `'vesion:conflict'`.
- * @parent module:middlewares
- */
-
-/**
- * The options used to customize a {@link VersionValidator} instance.
- *
- * @typedef {Object} VersionValidatorOptions
- * @property {string}                        error    The error message to show when the
- *                                                    version is invalid.
- * @property {VersionValidatorLatestOptions} latest   The options for how the middleware
- *                                                    should behave if the requested
- *                                                    version is `latest`.
- * @property {VersionValidatorPopupOptions}  popup    The options for how to detect if the
- *                                                    request comes from a popup and how
- *                                                    to compose the post message the
- *                                                    middleware will use to respond.
- * @property {string | number}               version  The version used to validate the
- *                                                    requests.
- *                                                    On the {@link VersionValidator}
- *                                                    constructor, if specified via
- *                                                    parameter,
- *                                                    the class will take care of
- *                                                    automatically add it to the options.
- * @parent module:middlewares
- */
-
-/**
- * This is the handler for the middleware/controller that validates the app version.
- * This is useful in cases where you want to restrict the access to the app to specific
- * versions,
- * for example: you have a frontend app which needs to be aligned with the "current"
- * version of the app, since the frontend won't realize a new version was released, the
- * validator can be used to let the frontend know.
- * Also, it can be configured to handle requests from popups, in which case, instead of
- * generating an error message, it will send a post message.
- *
- * @parent module:middlewares
- */
-class VersionValidator {
-  /**
-   * @param {?(string | ?number)} version
-   * The current version of the app. The reason this is nullable is because this comes
-   * directly from the app configuration, but you may want to re use this to validate
-   * "another version", so you can use the custom shorthand and send the version using the
-   * `options` parameter.
-   * @param {ResponsesBuilder} responsesBuilder
-   * To generate post message responses for popups.
-   * @param {ClassAppError} AppError
-   * To generate the error in case the version is invalid.
-   * @param {Partial<VersionValidatorOptions>} [options={}]
-   * Custom options to modify the middleware behavior.
-   * @throws {Error}
-   * If the version is `null` and the `options` don't include one either.
-   */
-  constructor(version, responsesBuilder, AppError, options = {}) {
-    /**
-     * A local reference for the `responsesBuilder` service.
-     *
-     * @type {ResponsesBuilder}
-     * @access protected
-     * @ignore
-     */
-    this._responsesBuilder = responsesBuilder;
-    /**
-     * A local reference for the class the app uses to generate errors.
-     *
-     * @type {ClassAppError}
-     * @access protected
-     * @ignore
-     */
-    this._AppError = AppError;
-    /**
-     * These are the "settings" the middleware will use in order to validate the requests.
-     *
-     * @type {VersionValidatorOptions}
-     * @access protected
-     * @ignore
-     */
-    this._options = ObjectUtils.merge(
-      {
-        error: "The application version doesn't match",
-        latest: {
-          allow: true,
-          name: 'latest',
-        },
-        popup: {
-          variable: 'popup',
-          title: 'Conflict',
-          message: 'vesion:conflict',
-        },
-        version,
-      },
-      options,
-    );
-
-    if (!this._options.version) {
-      throw new Error('You need to supply a version');
-    }
-  }
-  /**
-   * Returns the Express middleware that will validate the `version` parameter.
-   *
-   * @returns {ExpressMiddleware}
-   */
-  middleware() {
-    return (req, res, next) => {
-      // Get the `version` parameter from the request.
-      const { version } = req.params;
-      if (!version) {
-        // If no version is present, move on to the next middleware.
-        next();
-      } else if (version === this._options.version || this._validateLatest(version)) {
-        /**
-         * If the version matches the one on the options, or the requested version is "latest"
-         * (and the option is enabled), move on to the next middleware.
-         */
-        next();
-      } else if (this._isPopup(req)) {
-        /**
-         * If it doesn't match and the request is comming from a popup, send a response with a
-         * post message.
-         */
-        this._responsesBuilder.htmlPostMessage(
-          res,
-          this._options.popup.title,
-          this._options.popup.message,
-          statuses.conflict,
-        );
-      } else {
-        // Finally, if it doesn't match and is not from a popup, move to the error handler.
-        next(
-          new this._AppError(this._options.error, {
-            status: statuses.conflict,
-            response: {
-              validation: true,
-            },
-          }),
-        );
-      }
-    };
-  }
-  /**
-   * The options used to customize the middleware behavior.
-   *
-   * @returns {VersionValidatorOptions}
-   */
-  get options() {
-    return this._options;
-  }
-  /**
-   * Helper method that checks if the incoming request is from a popup.
-   *
-   * @param {ExpressRequest} req  The request information.
-   * @returns {boolean}
-   * @access protected
-   * @ignore
-   */
-  _isPopup(req) {
-    const popup = req.query[this._options.popup.variable];
-    return !!(popup && popup.toLowerCase() === 'true');
-  }
-  /**
-   * Helper method that checks if the "latest version" is enabled and if the given version
-   * is "the latest" (comparing it with the option name).
-   *
-   * @param {string | number} version  The version to validate.
-   * @returns {boolean}
-   * @access protected
-   * @ignore
-   */
-  _validateLatest(version) {
-    return this._options.latest.allow && version === this._options.latest.name;
-  }
-}
-/**
- * A middleware that will validate a `version` request parameter against the app version
- * and generate an error if they don't match.
- * This is a "middleware/controller" is because the wrappers for both are the same, the
- * difference is that, for controllers, Jimpex sends a second parameter with the route
- * where they are mounted.
- * By validating the route parameter, the function can know whether the implementation is
- * going to use the middleware by itself or as a route middleware.
- * If used as middleware, it will just return the result of
- * {@link VersionValidator#middleware};
- * but if used as controller, it will mount it on `[route]/:version/*`.
- *
- * @type {MiddlewareCreator<VersionValidatorOptions>}
- * @parent module:middlewares
- */
-const versionValidator = middlewareCreator((options = {}) => (app, route) => {
-  // Get the middleware function.
-  const middlewareValidator = new VersionValidator(
-    app.get('appConfiguration').get('version'),
-    app.get('responsesBuilder'),
-    app.get('AppError'),
-    options,
-  ).middleware();
-  // Set the variable to be returned.
-  let result;
-  if (route) {
-    // If the implementation will use it as a router, get the `router` service and mount it.
-    const router = app.get('router');
-    // Set the array of "routes" as the return value.
-    result = [router.all('/:version/*', middlewareValidator)];
-  } else {
-    // If the implementation will use it stand alone, just set the function to be returned.
-    result = middlewareValidator;
-  }
-
-  // Return the route or the middleware.
-  return result;
-});
-
-module.exports.VersionValidator = VersionValidator;
-module.exports.versionValidator = versionValidator;

package/src/services/common/appError.js

@@ -1,136 +0,0 @@
-const { code: statuses } = require('statuses');
-const { provider } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-
-/**
- * A simple subclass of `Error` but with support for context information.
- *
- * @augments Error
- * @parent module:services
- */
-class AppError extends Error {
-  /**
-   * @param {string} message       The error message.
-   * @param {Object} [context={}]  Context information related to the error.
-   */
-  constructor(message, context = {}) {
-    super(message);
-
-    // Limit the stack trace if possible.
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-    /**
-     * Context information related to the error.
-     *
-     * @type {Object}
-     * @access protected
-     * @todo Remove Object.freeze.
-     */
-    this._context = Object.freeze(this._parseContext(context));
-    /**
-     * The date of when the error was generated.
-     *
-     * @type {Date}
-     * @access protected
-     */
-    this._date = new Date();
-    /**
-     * Overwrite the name of the `Error` with the one from the class.
-     *
-     * @type {string}
-     * @ignore
-     */
-    this.name = this.constructor.name;
-  }
-  /**
-   * Context information related to the error.
-   *
-   * @type {Object}
-   */
-  get context() {
-    return this._context;
-  }
-  /**
-   * The date of when the error was generated.
-   *
-   * @type {Date}
-   */
-  get date() {
-    return this._date;
-  }
-  /**
-   * Information about the error that can be shown on an app response. This is set using
-   * the `response` key on the `context`. The idea is that the error handler will read it
-   * and use it on the response.
-   *
-   * @returns {Object}
-   */
-  get response() {
-    return this._context.response || {};
-  }
-  /**
-   * An HTTP status code related to the error. This is set using the `status` key on the
-   * `context`. If the error handler finds it, it will use it as the response status,
-   * and use it if necessary.
-   *
-   * @type {?number}
-   */
-  get status() {
-    return this._context.status || null;
-  }
-  /**
-   * Utility method that formats the context before saving it in the instance:
-   * - If the context includes a `status` as a `string`, it will try to replace it with
-   * its status code from the `statuses` package.
-   *
-   * @param {Object} original  The original context to format.
-   * @returns {Object}
-   * @access protected
-   * @ignore
-   */
-  _parseContext(original) {
-    const result = { ...original };
-    if (typeof result.status === 'string') {
-      result.status = statuses[result.status.toLowerCase()] || result.status;
-    }
-
-    return result;
-  }
-}
-/**
- * A generator function to create {@link AppError} instances.
- *
- * @param {string} message    The error message.
- * @param {Object} [context]  Context information related to the error.
- * @returns {AppError}
- * @parent module:services
- */
-const appErrorGenerator = (message, context) => new AppError(message, context);
-/**
- * A service provider that will register both the {@link AppError} and a generator
- * function on the container. `AppError` will be the key for class, and `appError` will be
- * for the generator function.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(appError);
- *   // Getting access to the class.
- *   const AppError = container.get('AppError');
- *   // Getting access to the function.
- *   const appError = container.get('appError');
- *
- * @parent module:services
- */
-const appError = provider((app) => {
-  app.set('AppError', () => AppError);
-  app.set('appError', () => appErrorGenerator);
-});
-
-module.exports.AppError = AppError;
-module.exports.appError = appError;

package/src/services/common/httpError.js

@@ -1,60 +0,0 @@
-const { code: statuses } = require('statuses');
-const ObjectUtils = require('wootils/shared/objectUtils');
-const { provider } = require('../../utils/wrappers');
-const { AppError } = require('./appError');
-
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-
-/**
- * A type of error to be used on HTTP requests.
- *
- * @augments AppError
- * @parent module:services
- */
-class HTTPError extends AppError {
-  /**
-   * @param {string} message       The error message.
-   * @param {number} [status=200]  The HTTP status code of the request response.
-   * @param {Object} [context={}]  Context information related to the error.
-   */
-  constructor(message, status = statuses.ok, context = {}) {
-    super(message, ObjectUtils.merge({ status }, context));
-  }
-}
-/**
- * A generator function to create {@link HTTPError} instances.
- *
- * @param {string} message    The error message.
- * @param {number} [status]   The HTTP status code of the request response.
- * @param {Object} [context]  Context information related to the error.
- * @returns {HTTPError}
- * @parent module:services
- */
-const httpErrorGenerator = (message, status, context) =>
-  new HTTPError(message, status, context);
-/**
- * A service provider that will register both the {@link HTTPError} and a generator
- * function on the container. `HTTPError` will be the key for class, and `httpError` will
- * be for the generator function.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(httpError);
- *   // Getting access to the class.
- *   const HTTPError = container.get('HTTPError');
- *   // Getting access to the function.
- *   const httpError = container.get('httpError');
- *
- * @parent module:services
- */
-const httpError = provider((app) => {
-  app.set('HTTPError', () => HTTPError);
-  app.set('httpError', () => httpErrorGenerator);
-});
-
-module.exports.HTTPError = HTTPError;
-module.exports.httpError = httpError;

package/src/services/common/index.js

@@ -1,25 +0,0 @@
-const { appError } = require('./appError');
-const { httpError } = require('./httpError');
-const { sendFileProvider } = require('./sendFile');
-const { providers } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-
-/**
- * The providers collection for the common services.
- *
- * @type {Provider}
- * @property {Provider} appError   The provider for {@link AppError}.
- * @property {Provider} httpError  The provider for {@link HTTPError}.
- * @property {Provider} sendFile   The provider for {@link SendFile}.
- * @parent module:services
- */
-const commonServices = providers({
-  appError,
-  httpError,
-  sendFile: sendFileProvider,
-});
-
-module.exports = commonServices;

package/src/services/common/sendFile.js

@@ -1,68 +0,0 @@
-const { provider } = require('../../utils/wrappers');
-
-/**
- * @typedef {import('../../types').PathUtils} PathUtils
- * @typedef {import('../../types').Provider} Provider
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').ExpressNext} ExpressNext
- */
-
-/**
- * @callback SendFile
- * @param {ExpressResponse} res           Necessary to write the file.
- * @param {string}          filepath      The path to the file relative to where the app
- *                                        executable is located.
- * @param {ExpressNext}     next          To call the send out the error if anything
- *                                        happens.
- * @param {string}          [from='app']  The location it uses to build the relative path.
- *                                        It can be `app` for the directory where the app
- *                                        executable is located, or `home` for the project
- *                                        root directory.
- * @parent module:services
- */
-
-/**
- * Generates a function to send files with path relatives to the app executable file is
- * located.
- *
- * @example
- *
- *   // Let's say this is inside an Express middleware.
- *   // Get the function
- *   const send = sendFile(pathUtils);
- *   send(res, 'some-file.html', next);
- *   // If your app is on `/app/index.js`, this will send `/app/some-file.html`.
- *
- * @param {PathUtils} pathUtils  To generate the relative paths.
- * @returns {SendFile}
- * @parent module:services
- */
-const sendFile = (pathUtils) => (res, filepath, next = () => {}, from = 'app') => {
-  res.sendFile(pathUtils.joinFrom(from, filepath), (error) => {
-    if (error) {
-      next(error);
-    } else {
-      res.end();
-    }
-  });
-};
-/**
- * The service provider that once registered on the app container will set the result of
- * `sendFile(pathUtils)` as the `sendFile` service.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(sendFileProvider);
- *   // Getting access to the service instance
- *   const sendFile = container.get('sendFile');
- *
- * @parent module:services
- */
-const sendFileProvider = provider((app) => {
-  app.set('sendFile', () => sendFile(app.get('pathUtils')));
-});
-
-module.exports.sendFile = sendFile;
-module.exports.sendFileProvider = sendFileProvider;

package/src/services/frontend/frontendFs.js

@@ -1,85 +0,0 @@
-const fs = require('fs-extra');
-const { provider } = require('../../utils/wrappers');
-/**
- * @typedef {import('../../types').PathUtils} PathUtils
- * @typedef {import('../../types').Provider} Provider
- */
-
-/**
- * This service allows the app to easily read static files. The idea behind centralizing
- * this functionalities into a service is that is pretty common to have bundling tools to
- * generate the frontend, and on that process files can have different paths or not even
- * be generated all, that's why this service exists. The service can be
- * extended/overwritten to accommodate any requirements and avoid having to update or add
- * `if`s to every `fs` call the app does.
- * Another _'feature'_ of this service is that all the paths are relative to the directory
- * where the app executable is located, so you don't have to remember the relative path
- * from the place you are accessing a file to the place where it's located.
- *
- * @parent module:services
- */
-class FrontendFs {
-  /**
-   * @param {PathUtils} pathUtils  To generate the relative paths.
-   */
-  constructor(pathUtils) {
-    /**
-     * A local reference for the `pathUtils` service.
-     *
-     * @type {PathUtils}
-     * @access protected
-     * @ignore
-     */
-    this._pathUtils = pathUtils;
-  }
-  /**
-   * Delete a file from the file system.
-   *
-   * @param {string} filepath  The path to the file.
-   * @returns {Promise}
-   */
-  delete(filepath) {
-    return fs.unlink(this._pathUtils.joinFrom('app', filepath));
-  }
-  /**
-   * Read a file from the file system.
-   *
-   * @param {string} filepath            The path to the file.
-   * @param {string} [encoding='utf-8']  The text encoding in which the file should be
-   *                                     read.
-   * @returns {Promise<string>}
-   */
-  read(filepath, encoding = 'utf-8') {
-    return fs.readFile(this._pathUtils.joinFrom('app', filepath), encoding);
-  }
-  /**
-   * Write a file on the file system.
-   *
-   * @param {string} filepath  The path to the file.
-   * @param {string} data      The contents of the file.
-   * @returns {Promise}
-   */
-  write(filepath, data) {
-    return fs.writeFile(this._pathUtils.joinFrom('app', filepath), data);
-  }
-}
-/**
- * The service provider that once registered on the app container will set an instance of
- * `FrontendFs` as the `frontendFs` service.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(frontendFs);
- *   // Getting access to the service instance
- *   const frontendFs = container.get('frontendFs');
- *
- * @parent module:services
- */
-const frontendFs = provider((app) => {
-  app.set('frontendFs', () => new FrontendFs(app.get('pathUtils')));
-});
-
-module.exports.FrontendFs = FrontendFs;
-module.exports.frontendFs = frontendFs;

package/src/services/frontend/index.js

@@ -1,17 +0,0 @@
-const { providers } = require('../../utils/wrappers');
-const { frontendFs } = require('./frontendFs');
-
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-
-/**
- * The providers collection for the frontend services.
- *
- * @type {Provider}
- * @property {Provider} frontendFs  The default provider for {@link FrontendFs}.
- * @parent module:services
- */
-module.exports = providers({
-  frontendFs,
-});