jimpex 8.0.0 → 9.0.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [9.0.0](https://github.com/homer0/jimpex/compare/8.0.0...9.0.0) (2023-10-02)
+
+
+### Bug Fixes
+
+* drop Node 16 support ([5e81112](https://github.com/homer0/jimpex/commit/5e81112bacea1f74f5250c6b12c6f1f94badee7f))
+* update dependencies ([543e232](https://github.com/homer0/jimpex/commit/543e232bad8a13f67f380997209140c65b6292c4))
+
+
+### BREAKING CHANGES
+
+* Node 16 is not longer supported. Node 18.17 is the minimum required version now.
+
 # [8.0.0](https://github.com/homer0/jimpex/compare/7.0.2...8.0.0) (2022-12-28)
 
 

package/README.md

@@ -1,8 +1,8 @@
 # Jimpex
 
-[![GitHub Workflow Status (main)](https://img.shields.io/github/workflow/status/homer0/jimpex/Test/main?style=flat-square)](https://github.com/homer0/jimpex/actions?query=workflow%3ATest)
+[![GitHub Workflow Status (main)](https://img.shields.io/github/actions/workflow/status/homer0/jimpex/test.yml?branch=main&style=flat-square)](https://github.com/homer0/jimpex/actions/workflows/test.yml?query=branch%3Amain)
 [![Coveralls GitHub](https://img.shields.io/coveralls/github/homer0/jimpex.svg?style=flat-square)](https://coveralls.io/github/homer0/jimpex?branch=main)
-![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/jimpex)
+![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/jimpex?style=flat-square)
 
 Express as dependency injection container.
 

package/dist/app/index.d.mts

@@ -0,0 +1,14 @@
+export { J as Jimpex, j as jimpex } from '../index-efeb437e.js';
+import '../types/express.mjs';
+import 'express';
+import '../types/http.mjs';
+import 'https';
+import 'http';
+import 'spdy';
+import 'node-fetch';
+import '../types/utils.mjs';
+import '@homer0/path-utils';
+import '@homer0/simple-logger';
+import '@homer0/simple-config';
+import '@homer0/events-hub';
+import '@homer0/jimple';

package/dist/app/index.d.ts

@@ -1,6 +1,4 @@
-export { J as Jimpex, j as jimpex } from '../jimpex-7eaee271.js';
-import '@homer0/jimple';
-import '@homer0/events-hub';
+export { J as Jimpex, j as jimpex } from '../index-b2a04c78.js';
 import '../types/express.js';
 import 'express';
 import '../types/http.js';
@@ -8,6 +6,9 @@ import 'https';
 import 'http';
 import 'spdy';
 import 'node-fetch';
-import '@homer0/simple-config';
 import '../types/utils.js';
+import '@homer0/path-utils';
 import '@homer0/simple-logger';
+import '@homer0/simple-config';
+import '@homer0/events-hub';
+import '@homer0/jimple';

package/dist/app/index.js

@@ -16,4 +16,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var app_exports = {};
 module.exports = __toCommonJS(app_exports);
 __reExport(app_exports, require("./jimpex"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./jimpex")
+});
 //# sourceMappingURL=index.js.map

package/dist/app/jimpex.d.mts

@@ -0,0 +1,14 @@
+import '@homer0/jimple';
+import '@homer0/events-hub';
+export { J as Jimpex, j as jimpex } from '../index-efeb437e.js';
+import 'express';
+import '../types/http.mjs';
+import '../types/utils.mjs';
+import '@homer0/simple-logger';
+import '@homer0/simple-config';
+import '../types/express.mjs';
+import '@homer0/path-utils';
+import 'node-fetch';
+import 'https';
+import 'http';
+import 'spdy';

package/dist/app/jimpex.d.ts

@@ -1,13 +1,14 @@
 import '@homer0/jimple';
 import '@homer0/events-hub';
-export { J as Jimpex, j as jimpex } from '../jimpex-7eaee271.js';
+export { J as Jimpex, j as jimpex } from '../index-b2a04c78.js';
 import 'express';
 import '../types/http.js';
 import '../types/utils.js';
 import '@homer0/simple-logger';
 import '@homer0/simple-config';
 import '../types/express.js';
+import '@homer0/path-utils';
+import 'node-fetch';
 import 'https';
 import 'http';
 import 'spdy';
-import 'node-fetch';

package/dist/app/jimpex.js

@@ -19,6 +19,10 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
@@ -53,14 +57,50 @@ var import_express = __toESM(require("express"));
 var import_services = require("../services");
 var import_utils = require("../utils");
 class Jimpex extends import_jimple.Jimple {
+  /**
+   * @param options  Preferences to customize the application.
+   * @param config   The default settings for the configuration service. It's a
+   *                 shortcuit for `options.config.default`
+   */
   constructor(options = {}, config = {}) {
     super();
+    /**
+     * The customization settings for the application.
+     */
     __publicField(this, "_options");
+    /**
+     * The Express application Jimpex uses under the hood.
+     */
     __publicField(this, "_express");
+    /**
+     * Since the configuration service has an async initialization, the class uses this flag
+     * internally to validate if the configuration has been initialized or not.
+     */
     __publicField(this, "_configReady", false);
+    /**
+     * A reference to the actuall HTTP the application will use. This can vary depending on
+     * whether HTTPS, or HTTP2 are enabled. If HTTPS is not enabled, it will be the same as
+     * the `express` property; if HTTPS is enabled, it will be an `https` server; and if
+     * HTTP2 is enabled, it will be an `spdy` server.
+     */
     __publicField(this, "_server");
+    /**
+     * The instance of the server that is listening for requests.
+     */
     __publicField(this, "_instance");
+    /**
+     * A list of functions that implement controllers and middlewares. When the application
+     * starts, the queue will be processed and those controllers and middlewares will be
+     * added to the server instance. The reason they are not added directly like with a
+     * regular Express implementation is that services on Jimple use lazy loading, and
+     * adding middlewares and controllers as they come could cause errors if they depend on
+     * services that are not yet registered.
+     */
     __publicField(this, "_mountQueue", []);
+    /**
+     * A list with all the top routes controlled by the application. Every time a controller
+     * is mounted, its route will be added here.
+     */
     __publicField(this, "_controlledRoutes", []);
     this._options = (0, import_deep_assign.deepAssignWithOverwrite)(
       {
@@ -111,12 +151,24 @@ class Jimpex extends import_jimple.Jimple {
       this.boot();
     }
   }
+  /**
+   * This is where the app would register all its specific services, middlewares and controllers.
+   */
   boot() {
   }
+  /**
+   * Disables the server TLS validation. Meant to be used for development purposes.
+   */
   disableTLSValidation() {
     process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
     this.logger.warn("TLS validation has been disabled");
   }
+  /**
+   * Starts the app server.
+   *
+   * @param onStart  A callback function to be called when the server actually starts.
+   * @returns The server instance.
+   */
   async start(onStart) {
     await this._setupConfig();
     const config = this.getConfig();
@@ -138,6 +190,17 @@ class Jimpex extends import_jimple.Jimple {
     });
     return this._instance;
   }
+  /**
+   * This is an alias of `start`. The idea is for it to be used on serverless platforms,
+   * where you don't get to start your app, you just have export it.
+   *
+   * @param port     In case the configuration doesn't already have it,
+   *                 this is the port where the application will use to run. If this
+   *                 parameter is used, the method will overwrite the `port`
+   *                 setting on the configuration service.
+   * @param onStart  A callback function to be called when the server starts.
+   * @returns The server instance.
+   */
   async listen(port, onStart) {
     if (port) {
       await this._setupConfig();
@@ -146,6 +209,9 @@ class Jimpex extends import_jimple.Jimple {
     }
     return this.start(onStart);
   }
+  /**
+   * Stops the server instance.
+   */
   stop() {
     if (!this._instance)
       return;
@@ -154,6 +220,12 @@ class Jimpex extends import_jimple.Jimple {
     this._instance = void 0;
     this._emitEvent("afterStop", { app: this });
   }
+  /**
+   * Mounts a route controller or a middleware into a server routes.
+   *
+   * @param route       The route for the controller/middleware.
+   * @param controller  The controller/middleware resource to be mounted.
+   */
   mount(route, controller) {
     let useController;
     if ("register" in controller && typeof controller.register === "function" && controller.provider === true) {
@@ -180,6 +252,11 @@ class Jimpex extends import_jimple.Jimple {
       this._controlledRoutes.push(route);
     });
   }
+  /**
+   * Adds a global middleware to the application.
+   *
+   * @param middleware  The middleware resource to be added.
+   */
   use(middleware) {
     const useMiddleware = "register" in middleware && typeof middleware.register === "function" ? middleware.register(this) : middleware;
     this._mountQueue.push((server) => {
@@ -201,6 +278,15 @@ class Jimpex extends import_jimple.Jimple {
       );
     });
   }
+  /**
+   * Gets a setting from the configuration, or the configuration itself.
+   *
+   * @param setting  The setting or settings to be retrieved. If is not specified, it
+   *                 will return the entire configuration.
+   * @param asArray  If `true` and `setting` is an array, it will return the values as
+   *                 an array instead of an object.
+   * @template T  The type of the setting to be retrieved.
+   */
   getConfig(setting, asArray = false) {
     const config = this.try("config");
     if (!config) {
@@ -211,41 +297,107 @@ class Jimpex extends import_jimple.Jimple {
     }
     return config.get(setting, asArray);
   }
+  /**
+   * Creates a new router instance.
+   */
   getRouter() {
     return this.get("router");
   }
+  /**
+   * The logger service.
+   */
   get logger() {
     return this.get("logger");
   }
+  /**
+   * The Express application Jimpex uses under the hood.
+   */
   get express() {
     return this._express;
   }
+  /**
+   * The server instance that gets created when the app is started.
+   */
   get instance() {
     return this._instance;
   }
+  /**
+   * The application customization options.
+   */
   get options() {
     return (0, import_deep_assign.deepAssignWithOverwrite)({}, this._options);
   }
+  /**
+   * Gets the events service.
+   */
   get eventsHub() {
     return this.get("events");
   }
+  /**
+   * A list of the routes that have controllers mounted on them.
+   */
   get routes() {
     return this._controlledRoutes.slice();
   }
+  /**
+   * Adds a listener for an application event.
+   *
+   * @param eventName  The name of the event to listen for.
+   * @param listener   The listener function.
+   * @returns A function to unsubscribe the listener.
+   * @template EventName  The name of the event, to match the type of the listener
+   *                      function.
+   */
   on(eventName, listener) {
     return this.eventsHub.on(eventName, listener);
   }
+  /**
+   * Adds a listener for an application event that will only be execuded once: the first
+   * time the event is triggered.
+   *
+   * @param eventName  The name of the event to listen for.
+   * @param listener   The listener function.
+   * @returns A function to unsubscribe the listener.
+   * @template EventName  The name of the event, to match the type of the listener
+   *                      function.
+   */
   once(eventName, listener) {
     return this.eventsHub.once(eventName, listener);
   }
+  /**
+   * Based on the application options, it returns wheter the application is healthy or
+   * not.
+   */
   isHealthy() {
     return this._options.healthCheck(this);
   }
+  /**
+   * This method is like a "lifecycle method", it gets executed on the constructor right
+   * before the "boot step". The idea is for the method to be a helper when the
+   * application is defined by subclassing {@link Jimpex}: the application could register
+   * all important services here and the routes on boot, then, if the implementation needs
+   * to access or overwrite a something, it can send `boot: false`, access/register what
+   * it needs, and then call `boot()`. That would be impossible for an application without
+   * overwriting the constructor and the boot functionality.
+   */
   _init() {
   }
+  /**
+   * It generates overwrites for the application options when it gets created. This method
+   * is a helper for when the application is defined by subclassing {@link Jimpex}: It's
+   * highly probable that if the application needs to change the default options, it would
+   * want to do it right from the class, instead of having to do it on every
+   * implementation. A way to do it would be overwriting the constructor and calling
+   * `super` with the custom overwrites, but this method exists so that won't be
+   * necessary: when creating the `options`, the constructor will merge the result of this
+   * method on top of the default ones.
+   */
   _initOptions() {
     return {};
   }
+  /**
+   * Registers the "core services" on the container: logger, events, utils, etc.
+   */
   _setupCoreServices() {
     this.register(
       (0, import_simple_logger.appLoggerProvider)({
@@ -266,6 +418,9 @@ class Jimpex extends import_jimple.Jimple {
     this.set("events", () => new import_events_hub.EventsHub());
     this.set("statuses", () => import_utils.statuses);
   }
+  /**
+   * Configures the Express application based on the class options.
+   */
   _setupExpress() {
     const { statics, filesizeLimit, express: expressOptions } = this._options;
     if (expressOptions.trustProxy) {
@@ -301,6 +456,18 @@ class Jimpex extends import_jimple.Jimple {
       this.factory(() => import_express.default.Router())
     );
   }
+  /**
+   * Adds a static folder to the application.
+   *
+   * @param route   The route to add the folder to.
+   * @param folder  The path to the folder in the file system. If not defined, it will
+   *                be use the same value as `route`. The path could be relative to the
+   *                project root, or where the application executable is located,
+   *                depending on the value of the `onHome` parameter.
+   * @param onHome  If `true`, the path to the folder will be relative to the project
+   *                root. If `false`, it will be relative to where the application
+   *                executable is located.
+   */
   _addStaticsFolder(route, folder = "", onHome = false) {
     const location = onHome ? "home" : "app";
     const staticRoute = route.replace(/^\/+/, "");
@@ -311,6 +478,16 @@ class Jimpex extends import_jimple.Jimple {
       controller: true
     });
   }
+  /**
+   * This helper method validates the `path` options in order to register the `app`
+   * location in the `pathUtils` service. The `app` location should be the path to where
+   * the application executable is located, but due to how ESM works, we can't infer it
+   * from the `module` object, so we need either recieved as the `appPath` setting, or try
+   * to get it from the parent module.
+   *
+   * @throws If the method should use the path from the parent module, but can't find
+   *         it.
+   */
   _configurePath() {
     const pathUtils = this.get("pathUtils");
     const {
@@ -340,6 +517,12 @@ class Jimpex extends import_jimple.Jimple {
       );
     }
   }
+  /**
+   * Setups the configuration service. The new configuration service requires async calls
+   * in order to load the configuration files (as it uses `import` instead of `require`),
+   * so it can't be instantiated as the other services.
+   * This method is called just before starting the application.
+   */
   async _setupConfig() {
     if (this._configReady)
       return;
@@ -370,16 +553,46 @@ class Jimpex extends import_jimple.Jimple {
       await config.loadFromEnv();
     }
   }
+  /**
+   * Processes the resources from the mount queue (added with {@link Jimpex.mount} and
+   * {@link Jimpex.use}), and adds them to the Express application.
+   */
   _mountResources() {
     this._mountQueue.forEach((mount) => mount(this._express));
     this._mountQueue.length = 0;
   }
+  /**
+   * Emits an event using the `events` service.
+   *
+   * @param name     The name of the event to emit.
+   * @param payload  The event payload.
+   * @template EventName  The literal name of the event, to type the event payload.
+   */
   _emitEvent(name, payload) {
     this.eventsHub.emit(name, payload);
   }
+  /**
+   * Sends a target object to a list of reducer events so they can modify or replace it.
+   *
+   * @param name     The name of the event to use.
+   * @param target   The object to reduce with the event.
+   * @param payload  Extra context for the listeners.
+   */
   _reduceWithEvent(name, target, payload) {
     return this.eventsHub.reduceSync(name, target, payload);
   }
+  /**
+   * Loads the contents of a dictionary of credentials files that need to be used to
+   * configure HTTPS.
+   *
+   * @param credentialsInfo  The dictionary where the keys are the type of credentials
+   *                         (`ca`, `cert`, `key`) and the values are the paths to the
+   *                         files.
+   * @param onHome           If this is `true`, the path of the files will be relative
+   *                         to the project root. If it is `false`, it will be relative
+   *                         to where the application executable is located.
+   * @returns
+   */
   async _loadCredentials(credentialsInfo, onHome = true) {
     const location = onHome ? "home" : "app";
     const pathUtils = this.get("pathUtils");
@@ -403,6 +616,18 @@ class Jimpex extends import_jimple.Jimple {
       return acc;
     }, {});
   }
+  /**
+   * Validates the configuration and chooses the server the application needs to use: If
+   * HTTP2 is enabled, it will use Spdy; if HTTPS is enabled but HTTP is not, it will use
+   * the native HTTPS server; otherwise, it will be just the Express instance.
+   *
+   * @returns {Server}
+   * @throws {Error} If HTTP2 is enabled but HTTPS is not.
+   * @throws {Error} If HTTPS is enabled but there's no `https.credentials` object.
+   * @throws {Error} If HTTPS is enabled and no creadentials are found.
+   * @access protected
+   * @ignore
+   */
   async _createServer() {
     const [http2Config = {}, httpsConfig = {}] = this.getConfig(["http2", "https"], true);
     if (!http2Config.enabled && !httpsConfig.enabled) {