jimpex 7.0.2 → 9.0.0

package/src/types.js

@@ -1,377 +0,0 @@
-/**
- * @typedef {import('jimple')} Jimple
- * @external Jimple
- * @see https://yarnpkg.com/en/package/jimple
- */
-
-// ==============================================
-// Externals - Wootils
-// ==============================================
-
-/**
- * @typedef {import('wootils/esm/node/appConfiguration').AppConfiguration} AppConfiguration
- * @external AppConfiguration
- * @see https://homer0.github.io/wootils/module-node_appConfiguration.AppConfiguration.html
- * @prettierignore
- */
-
-/**
- * @typedef {import('wootils/esm/shared/apiClient')} APIClientBase
- * @external APIClientBase
- * @see https://homer0.github.io/wootils/module-shared_apiClient.APIClient.html
- */
-
-/**
- * @typedef {import('wootils/esm/shared/apiClient').APIClientEndpoints} APIClientEndpoints
- * @external APIClientEndpoints
- * @see https://homer0.github.io/wootils/module-shared_apiClient.html#.APIClientEndpoints
- */
-
-/**
- * @typedef {import('wootils/esm/node/pathUtils').PathUtils} PathUtils
- * @external PathUtils
- * @see https://homer0.github.io/wootils/module-node_pathUtils.PathUtils.html
- */
-
-/**
- * @typedef {import('wootils/esm/node/logger').Logger} Logger
- * @external Logger
- * @see https://homer0.github.io/wootils/module-node_logger.Logger.html
- */
-
-/**
- * @typedef {import('wootils/esm/node/environmentUtils').EnvironmentUtils} EnvironmentUtils
- * @external EnvironmentUtils
- * @see https://homer0.github.io/wootils/module-node_environmentUtils.EnvironmentUtils.html
- * @prettierignore
- */
-
-/**
- * @typedef {import('wootils/esm/shared/eventsHub')} EventsHub
- * @external EventsHub
- * @see https://homer0.github.io/wootils/module-shared_eventsHub.html
- */
-
-/**
- * @typedef {import('wootils/esm/shared/jimpleFns').Provider} Provider
- * @external Provider
- * @see https://homer0.github.io/wootils/module-shared_jimpleFns.html#.Provider
- */
-
-/**
- * @typedef {import('wootils/esm/shared/jimpleFns').Providers} Providers
- * @external Providers
- * @see https://homer0.github.io/wootils/module-shared_jimpleFns.html#.Providers
- */
-
-/**
- * @typedef {import('wootils/esm/shared/jimpleFns').ProviderCreator<O>} ProviderCreator<O>
- * @template O
- * @external ProviderCreator
- * @see https://homer0.github.io/wootils/module-shared_jimpleFns.html#~providerCreator
- */
-
-// ==============================================
-// Externals - Express/Server
-// ==============================================
-
-/**
- * @typedef {import('express').Express} Express
- * @external Express
- * @see https://expressjs.com/en/4x/api.html
- */
-
-/**
- * @typedef {import('http').Server} HTTPServer
- * @external HTTPServer
- * @see https://nodejs.org/docs/latest-v12.x/api/http.html#http_class_http_server
- */
-
-/**
- * @typedef {import('spdy').Server} SpdyServer
- * @external SpdyServer
- * @see https://github.com/spdy-http2/node-spdy
- */
-/**
- * @typedef {import('spdy').ServerOptions} SpdyOptions
- * @external SpdyOptions
- * @see https://github.com/spdy-http2/node-spdy#options
- */
-
-/**
- * @typedef {HTTPServer | SpdyServer} Server
- */
-
-/**
- * @typedef {import('express').RequestHandler} RequestHandler
- * @typedef {import('express').ErrorRequestHandler} ErrorRequestHandler
- */
-
-/**
- * @typedef {RequestHandler | ErrorRequestHandler} ExpressMiddleware
- * @external ExpressMiddleware
- * @see http://expressjs.com/en/guide/using-middleware.html
- */
-
-/**
- * @typedef {import('express').Request} ExpressRequest
- * @external ExpressRequest
- * @see https://expressjs.com/en/4x/api.html#req
- */
-
-/**
- * @typedef {import('express').Response} ExpressResponse
- * @external ExpressResponse
- * @see https://expressjs.com/en/4x/api.html#res
- */
-/**
- * @typedef {import('express').NextFunction} ExpressNext
- * @external ExpressNext
- * @see https://expressjs.com/en/guide/writing-middleware.html
- */
-
-/**
- * @typedef {import('express').Router} ExpressRouter
- * @external Router
- * @see https://expressjs.com/en/4x/api.html#router
- */
-
-// ==============================================
-// Jimpex - Global classes
-// ==============================================
-
-/* eslint-disable jsdoc/valid-types */
-/**
- * @typedef {import('./services/common/httpError')['HTTPError']} ClassHTTPError
- * @typedef {import('./services/common/appError')['AppError']} ClassAppError
- */
-/* eslint-enable jsdoc/valid-types */
-
-/**
- * @typedef {import('./app').Jimpex} Jimpex
- */
-
-// ==============================================
-// Jimpex
-// ==============================================
-
-/**
- * @callback JimpexStartCallback
- * @param {AppConfiguration} appConfiguration  The service that handles the application
- *                                             configuration.
- */
-
-/**
- * @typedef {Object} JimpexConfigurationOptions
- * @property {?Object} default                       The app default configuration.
- *                                                   Default `null`.
- * @property {string}  name                          The name of the app, used for the
- *                                                   configuration files. Default `'app'`.
- * @property {string}  path                          The path to the configuration files
- *                                                   directory,
- *                                                   relative to the project root
- *                                                   directory. Default `'config/'`.
- * @property {boolean} hasFolder                     Whether the configurations are inside
- *                                                   a sub directory or not. If `true`, a
- *                                                   configuration path would be
- *                                                   `config/[app-name]/[file]`.
- *                                                   Default `true`.
- * @property {string}  environmentVariable           The name of the environment variable
- *                                                   that will be used to set the active
- *                                                   configuration.
- *                                                   Default `'CONFIG'`.
- * @property {boolean} loadFromEnvironment           Whether or not to check for the
- *                                                   environment variable and load a
- *                                                   configuration based on its value.
- *                                                   Default `true`.
- * @property {boolean} loadVersionFromConfiguration  If `true`, the app `version` will be
- *                                                   taken from the loaded configuration,
- *                                                   otherwise, when a configuration is
- *                                                   loaded, the app will copy the version
- *                                                   it has into the configuration.
- *                                                   Default `true`.
- * @property {string}  filenameFormat                The name format the configuration
- *                                                   files have.
- *                                                   Default:
- *
- *
- *                                                   `[app-name].[configuration-name].config.js`.
- */
-
-/**
- * @typedef {Object} JimpexStaticsOptions
- * @property {boolean} enabled  Whether or not to include the middleware for static files.
- *                              Default `true`.
- * @property {boolean} onHome   If `true`, the path to the statics folder will be relative
- *                              to the project root directory, otherwise, it will be
- *                              relative to the directory where the app executable file is
- *                              located. Default `false`.
- * @property {string}  route    The name of both the route and the folder, relative to
- *                              whatever you defined with the `onHome` option. Default
- *                              `'static'`.
- * @property {string}  folder   By default, the folder will be the same as the `route`,
- *                              but you can use this option to define a relative path that
- *                              won't affect the route. Default `''`.
- */
-
-/**
- * @typedef {Object} JimpexExpressOptions
- * @property {boolean} trustProxy         Whether or not to enable the `trust proxy`
- *                                        option.
- *                                        Default `true`.
- * @property {boolean} disableXPoweredBy  Whether or not to remove the `x-powered-by`
- *                                        header.
- *                                        Default `true`.
- * @property {boolean} compression        Whether or not to add the `compression`
- *                                        middleware.
- *                                        Default `true`.
- * @property {boolean} bodyParser         Whether or not to add the `body-parser`
- *                                        middleware.
- *                                        Default `true`.
- * @property {boolean} multer             Whether or not to add the `multer` middleware.
- *                                        Default `true`.
- */
-
-/**
- * @typedef {Object} JimpexDefaultServicesOptions
- * @property {boolean} common  Whether or not to register all the `common` service
- *                             providers.
- *                             Default `true`.
- * @property {boolean} http    Whether or not to register all the `http` service
- *                             providers.
- *                             Default `true`.
- * @property {boolean} utils   Whether or not to register all the `utils` service
- *                             providers.
- *                             Default `true`.
- */
-
-/**
- * @typedef {Object} JimpexOptions
- * @property {string} version
- * The app version. To be used on the configuration. Default `'0.0.0'`.
- * @property {string} filesizeLimit
- * The size limit for the requests payload. Default `'15MB'`.
- * @property {boolean} boot
- * Whether or not to automatically call the `boot` method after initialization.
- * Default `true`.
- * @property {boolean} proxy
- * Whether or not to enable the proxy mode, so all providers, controllers and middlewares
- * will receive a proxied reference of the container, in which they can set and get
- * resources using dot notation.
- * @property {JimpexConfigurationOptions} configuration
- * The options for the app configuration service.
- * @property {JimpexStaticsOptions} statics
- * The options for the app static `middleware`.
- * @property {JimpexExpressOptions} express
- * The options for the Express app.
- * @property {JimpexDefaultServicesOptions} defaultServices
- * To tell the app which services should be registered when instantiated.
- */
-
-// ==============================================
-// Jimpex - Custom wrappers
-// ==============================================
-
-/**
- * An object that when mounted on Jimpex will take care of handling a list of specific
- * routes. The method Jimpex uses to mount a controller is {@link Jimpex#mount}.
- *
- * @typedef {Object} Controller
- * @property {ControllerConnectFn} connect     The function Jimpex calls when mounting the
- *                                             controller.
- * @property {boolean}             controller  A flag set to `true` to identify the
- *                                             resource as a routes controller.
- */
-
-/**
- * @callback ControllerProviderRegisterFn
- * @param {Jimpex} app    The instance of the application container.
- * @param {string} route  The route where the controller will be mounted.
- * @returns {Controller}
- */
-
-/**
- * This is a special kind of controller that not only registers routes but also adds
- * resources to the container, and to avoid doing it during the mount process, it
- * registers the resources first and then returns the actuall controller.
- *
- * @typedef {Object} ControllerProvider
- * @property {ControllerProviderRegisterFn} register  The function Jimpex calls when
- *                                                    registering the provider and the one
- *                                                    that has to generate the controller.
- */
-
-/**
- * The function called by the application container in order to mount a routes controller.
- *
- * @callback ControllerConnectFn
- * @param {Jimpex} app    The instance of the application container.
- * @param {string} route  The route where the controller will be mounted.
- * @returns {Router} The controller router.
- */
-
-/**
- * A function called in order to generate a {@link Controller}. They usually have
- * different options that will be sent to the controller creation.
- *
- * @callback ControllerCreatorFn
- * @returns {ControllerConnectFn}
- */
-
-/**
- * A special kind of {@link Controller} that can be used with {@link Jimpex#mount} as a
- * regular controller, or it can be called as a function with custom parameters in order
- * to obtain a "configured {@link Controller}".
- *
- * @callback ControllerCreator
- * @param {Partial<O>} [options={}]  The options to create the controller.
- * @returns {Controller | ControllerProvider}
- * @template O
- */
-
-/**
- * An object that when mounted on Jimpex add an {@link ExpressMiddleware} to the app. The
- * method Jimpex uses to mount a middleware is {@link Jimpex#use}.
- *
- * @typedef {Object} Middleware
- * @property {MiddlewareConnectFn} connect     The function Jimpex calls when mounting the
- *                                             middleware.
- * @property {boolean}             middleware  A flag set to `true` to identify the
- *                                             resource as a middleware.
- */
-
-/**
- * The function called by the application container in order to use a middleware.
- *
- * @callback MiddlewareConnectFn
- * @param {Jimpex} app  The instance of the application container.
- * @returns {?ExpressMiddleware} A middleware for Express to use. It can also return
- *                               `null` in case there's a reason for the middleware not to
- *                               be active.
- */
-
-/**
- * A function called in order to generate a {@link Middleware}. They usually have
- * different options that will be sent to the middleware creation.
- *
- * @callback MiddlewareCreatorFn
- * @returns {MiddlewareConnectFn}
- */
-
-/**
- * A special kind of {@link Middleware} that can be used with {@link Jimpex#use} as a
- * regular middleware, or it can be called as a function with custom parameters in order
- * to obtain a "configured {@link Middleware}".
- *
- * @callback MiddlewareCreator
- * @param {Partial<O>} [options={}]  The options to create the controller.
- * @returns {Middleware}
- * @template O
- */
-
-/**
- * @typedef {Middleware | ExpressMiddleware} MiddlewareLike
- */
-
-// eslint-disable-next-line
-export {};

package/src/utils/functions.js

@@ -1,78 +0,0 @@
-/**
- * @module functions
- */
-
-/**
- * Removes any leading slash from a URL.
- *
- * @param {string} url  The URL to format.
- * @returns {string}
- * @parent module:functions
- */
-const removeLeadingSlash = (url) => url.replace(/^\/+/, '');
-/**
- * Removes any trailing slash from a URL.
- *
- * @param {string} url  The URL to format.
- * @returns {string}
- * @parent module:functions
- */
-const removeTrailingSlash = (url) => url.replace(/\/+$/, '');
-/**
- * Remove any leading and trailing slash from a URL.
- *
- * @param {string}  url              The URL to format.
- * @param {boolean} [leading=true]   Whether or not to remove any leading slash.
- * @param {boolean} [trailing=true]  Whether or not to remove the trailing slash.
- * @returns {string}
- * @parent module:functions
- */
-const removeSlashes = (url, leading = true, trailing = true) => {
-  const newUrl = leading ? removeLeadingSlash(url) : url;
-  return trailing ? removeTrailingSlash(newUrl) : newUrl;
-};
-/**
- * Escapes a string to be used on `new RegExp(...)`.
- *
- * @param {string} text  The text to escape.
- * @returns {string}
- * @parent module:functions
- */
-const escapeForRegExp = (text) => text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
-/**
- * Given a server route definition, this function creates a regular expression to match
- * it: The expression replaces the routes parameters with placeholders so it can be
- * compared with real routes.
- *
- * @param {string}  route                  The route from which the expression will be
- *                                         created.
- * @param {boolean} [leadingSlash=true]    Whether or not the expression should match a
- *                                         leading slash.
- * @param {boolean} [trailingSlash=false]  Whether or not the expression should match a
- *                                         trailing slash. The reason this is `false` by
- *                                         default is because these expressions are often
- *                                         used to match against incoming requests, and
- *                                         they don't have a trailing slash.
- * @returns {RegExp}
- * @parent module:functions
- */
-const createRouteExpression = (route, leadingSlash = true, trailingSlash = false) => {
-  let expression = removeSlashes(route)
-    .split('/')
-    .map((part) => (part.startsWith(':') ? '(?:([^\\/]+?))' : escapeForRegExp(part)))
-    .join('\\/');
-  if (leadingSlash) {
-    expression = `\\/${expression}`;
-  }
-  if (trailingSlash) {
-    expression = `${expression}\\/`;
-  }
-
-  return new RegExp(expression);
-};
-
-module.exports.createRouteExpression = createRouteExpression;
-module.exports.escapeForRegExp = escapeForRegExp;
-module.exports.removeLeadingSlash = removeLeadingSlash;
-module.exports.removeSlashes = removeSlashes;
-module.exports.removeTrailingSlash = removeTrailingSlash;

package/src/utils/wrappers.js

@@ -1,131 +0,0 @@
-const {
-  provider,
-  providerCreator,
-  providers,
-  resource,
-  resourceCreator,
-} = require('wootils/shared/jimpleFns');
-
-/**
- * @typedef {import('../types').Controller} Controller
- * @typedef {import('../types').Middleware} Middleware
- * @typedef {import('../types').ControllerConnectFn} ControllerConnectFn
- * @typedef {import('../types').ControllerCreatorFn} ControllerCreatorFn
- * @typedef {import('../types').MiddlewareConnectFn} MiddlewareConnectFn
- * @typedef {import('../types').MiddlewareCreatorFn} MiddlewareCreatorFn
- */
-
-/**
- * @typedef {import('../types').ControllerCreator<O>} ControllerCreator<O>
- * @template O
- */
-
-/**
- * @typedef {import('../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-
-/**
- * @module wrappers
- */
-
-/**
- * Generates a routes controller for the application container to mount.
- *
- * @example
- *
- *   const myController = controller((app) => {
- *     const router = app.get('router');
- *     const ctrl = new MyController();
- *     return router.get('...', ctrl.doSomething()).post('...', ctrl.doSomethingElse());
- *   });
- *
- * @param {ControllerConnectFn} connectFn  A function that will be called the moment the
- *                                         app mounts the controller.
- * @returns {Controller}
- * @parent module:wrappers
- */
-const controller = (connectFn) => resource('controller', 'connect', connectFn);
-/**
- * Generates a configurable routes controller for the application to mount. It's
- * configurable because the creator, instead of just being sent to the container to mount,
- * it can also be called as a function with custom parameters the controller can receive.
- *
- * @example
- *
- *   const myController = controllerCreator((options = {}) => (app) => {
- *     const router = app.get('router');
- *     const ctrl = new MyController(options);
- *     return router.get('...', ctrl.doSomething()).post('...', ctrl.doSomethingElse());
- *   });
- *
- * @param {ControllerCreatorFn} creatorFn  The function that generates the controller.
- * @returns {ControllerCreator<any>}
- * @parent module:wrappers
- */
-const controllerCreator = (creatorFn) =>
-  resourceCreator('controller', 'connect', creatorFn);
-/**
- * Generates a middleware for the app to use.
- *
- * @example
- *
- *   const myMiddleware = middleware((app) => (req, res, next) => {
- *     if (req.query.greet !== 'true') {
- *       return next();
- *     }
- *
- *     app.get('responsesBuilder').json(res, {
- *       hello: 'world',
- *     });
- *   });
- *
- * @example
- *
- * <caption>Disable the middleware base on a configuration option</caption>
- *
- *   const myMiddleware = middleware((app) => {
- *     if (app.get('appConfiguration').get('someOption') !== true) {
- *       return null;
- *     }
- *
- *     return (req, res, next) => {
- *       if (req.query.hello !== 'world') return next();
- *       app.get('responsesBuilder').json(res, {
- *         hello: 'world',
- *       });
- *     };
- *   });
- *
- * @param {MiddlewareConnectFn} connectFn  A function that will be called the moment the
- *                                         app mounts the middleware.
- * @returns {Middleware}
- * @parent module:wrappers
- */
-const middleware = (connectFn) => resource('middleware', 'connect', connectFn);
-/**
- * Generates a configurable middleware for the app to use. It's configurable because the
- * creator,
- * instead of just being sent to the container to use, it can also be called as a function
- * with custom parameters the middleware can receive.
- *
- * @example
- *
- *   const myMiddleware = middlewareCreator((options = {}) => (app) =>
- *     options.enabled ? (req, res, next) => {} : null,
- *   );
- *
- * @param {MiddlewareCreatorFn} creatorFn  The function that generates the middleware.
- * @returns {MiddlewareCreator<any>}
- * @parent module:wrappers
- */
-const middlewareCreator = (creatorFn) =>
-  resourceCreator('middleware', 'connect', creatorFn);
-
-module.exports.provider = provider;
-module.exports.providerCreator = providerCreator;
-module.exports.providers = providers;
-module.exports.controller = controller;
-module.exports.controllerCreator = controllerCreator;
-module.exports.middleware = middleware;
-module.exports.middlewareCreator = middlewareCreator;