jimpex 7.0.2 → 9.0.0

package/dist/esm/app/jimpex.js

@@ -0,0 +1,636 @@
+import {
+  __publicField
+} from "../chunk-2B2CG5KL.js";
+import * as path from "path";
+import fs from "fs/promises";
+import { createServer as createHTTPSServer } from "https";
+import { Jimple } from "@homer0/jimple";
+import { deepAssignWithOverwrite } from "@homer0/deep-assign";
+import { appLoggerProvider } from "@homer0/simple-logger";
+import { envUtilsProvider } from "@homer0/env-utils";
+import { packageInfoProvider } from "@homer0/package-info";
+import { pathUtilsProvider } from "@homer0/path-utils";
+import { rootFileProvider } from "@homer0/root-file";
+import { EventsHub } from "@homer0/events-hub";
+import { simpleConfigProvider } from "@homer0/simple-config";
+import compression from "compression";
+import bodyParser from "body-parser";
+import multer from "multer";
+import {
+  createServer as createSpdyServer
+} from "spdy";
+import express from "express";
+import {
+  commonServicesProvider,
+  httpServicesProvider,
+  utilsServicesProvider
+} from "../services";
+import {
+  statuses
+} from "../utils";
+class Jimpex extends 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 = deepAssignWithOverwrite(
+      {
+        filesizeLimit: "15MB",
+        boot: true,
+        path: {
+          appPath: "",
+          useParentPath: true
+        },
+        config: {
+          default: options?.config?.default || config,
+          name: "app",
+          path: "config/",
+          hasFolder: false,
+          loadFromEnvironment: true,
+          environmentVariable: "CONFIG",
+          defaultConfigFilename: "[app-name].config.js",
+          filenameFormat: "[app-name].[config-name].config.js"
+        },
+        statics: {
+          enabled: true,
+          onHome: false,
+          route: "statics"
+        },
+        express: {
+          trustProxy: true,
+          disableXPoweredBy: true,
+          compression: true,
+          bodyParser: true,
+          multer: true
+        },
+        services: {
+          common: true,
+          http: true,
+          utils: true
+        },
+        healthCheck: () => Promise.resolve(true)
+      },
+      options,
+      this._initOptions()
+    );
+    this._express = express();
+    this._setupCoreServices();
+    this._setupExpress();
+    this._configurePath();
+    this._init();
+    if (this._options.boot) {
+      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();
+    const port = config.get("port");
+    if (!port) {
+      throw new Error("No port configured");
+    }
+    this._emitEvent("beforeStart", { app: this });
+    this._server = await this._createServer();
+    this._instance = this._server.listen(port, () => {
+      this._emitEvent("start", { app: this });
+      this._mountResources();
+      this.logger.success(`Starting on port ${port}`);
+      this._emitEvent("afterStart", { app: this });
+      if (onStart) {
+        onStart(config);
+      }
+      this._emitEvent("afterStartCallback", { app: this });
+    });
+    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();
+      const config = this.getConfig();
+      config.set("port", port);
+    }
+    return this.start(onStart);
+  }
+  /**
+   * Stops the server instance.
+   */
+  stop() {
+    if (!this._instance)
+      return;
+    this._emitEvent("beforeStop", { app: this });
+    this._instance.close();
+    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) {
+      useController = controller.register(this, route);
+    } else if ("connect" in controller && typeof controller.connect === "function" && ("middleware" in controller && controller.middleware === true || "controller" in controller && controller.controller === true)) {
+      useController = controller;
+    } else {
+      useController = {
+        middleware: true,
+        connect: () => controller
+      };
+    }
+    this._mountQueue.push((server) => {
+      const connected = useController.connect(this, route);
+      if (!connected)
+        return;
+      const router = this._reduceWithEvent("controllerWillBeMounted", connected, {
+        route,
+        controller: useController,
+        app: this
+      });
+      server.use(route, router);
+      this._emitEvent("routeAdded", { route, app: this });
+      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) => {
+      if ("connect" in useMiddleware && typeof useMiddleware.connect === "function") {
+        const handler = useMiddleware.connect(this);
+        if (handler) {
+          server.use(
+            this._reduceWithEvent("middlewareWillBeUsed", handler, { app: this })
+          );
+        }
+        return;
+      }
+      server.use(
+        this._reduceWithEvent(
+          "middlewareWillBeUsed",
+          useMiddleware,
+          { app: this }
+        )
+      );
+    });
+  }
+  /**
+   * 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) {
+      throw new Error("The config service is not available until the app starts");
+    }
+    if (typeof setting === "undefined") {
+      return config;
+    }
+    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 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(
+      appLoggerProvider({
+        serviceName: "logger"
+      })
+    );
+    this.register(envUtilsProvider);
+    this.register(packageInfoProvider);
+    this.register(pathUtilsProvider);
+    this.register(rootFileProvider);
+    const { services: enabledServices } = this._options;
+    if (enabledServices.common)
+      this.register(commonServicesProvider);
+    if (enabledServices.http)
+      this.register(httpServicesProvider);
+    if (enabledServices.utils)
+      this.register(utilsServicesProvider);
+    this.set("events", () => new EventsHub());
+    this.set("statuses", () => statuses);
+  }
+  /**
+   * Configures the Express application based on the class options.
+   */
+  _setupExpress() {
+    const { statics, filesizeLimit, express: expressOptions } = this._options;
+    if (expressOptions.trustProxy) {
+      this._express.enable("trust proxy");
+    }
+    if (expressOptions.disableXPoweredBy) {
+      this._express.disable("x-powered-by");
+    }
+    if (expressOptions.compression) {
+      this._express.use(compression());
+    }
+    if (statics.enabled) {
+      this._addStaticsFolder(statics.route, statics.folder, statics.onHome);
+    }
+    if (expressOptions.bodyParser) {
+      this._express.use(
+        bodyParser.json({
+          limit: filesizeLimit
+        })
+      );
+      this._express.use(
+        bodyParser.urlencoded({
+          extended: true,
+          limit: filesizeLimit
+        })
+      );
+    }
+    if (expressOptions.multer) {
+      this._express.use(multer().any());
+    }
+    this.set(
+      "router",
+      this.factory(() => express.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(/^\/+/, "");
+    const pathUtils = this.get("pathUtils");
+    const staticFolder = pathUtils.joinFrom(location, folder || staticRoute);
+    this.mount(`/${staticRoute}`, {
+      connect: () => express.static(staticFolder),
+      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 {
+      path: { appPath, useParentPath }
+    } = this._options;
+    if (appPath) {
+      pathUtils.addLocation("app", appPath);
+      return;
+    }
+    let foundPath = false;
+    if (useParentPath) {
+      const stack = new Error().stack;
+      const stackList = stack.split("\n");
+      stackList.shift();
+      const parentFromStack = stackList.find((line) => !line.includes(__filename));
+      if (parentFromStack) {
+        const parentFile = parentFromStack.replace(/^.*?\s\(([^\s]+):\d+:\d+\)/, "$1");
+        if (parentFile !== parentFromStack) {
+          foundPath = true;
+          pathUtils.addLocation("app", path.dirname(parentFile));
+        }
+      }
+    }
+    if (!foundPath) {
+      throw new Error(
+        "The app location cannot be determined. Please specify the appPath option."
+      );
+    }
+  }
+  /**
+   * 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;
+    this._configReady = true;
+    const { config: options } = this._options;
+    let configsPath = options.path.replace(/\/$/, "");
+    if (options.hasFolder) {
+      configsPath = `${configsPath}${path.sep}${options.name}${path.sep}`;
+    }
+    const filenameFormat = options.filenameFormat.replace(/\[app-name\]/gi, options.name).replace(/\[config-name\]/gi, "[name]");
+    const defaultConfigFilename = options.defaultConfigFilename.replace(
+      /\[app-name\]/gi,
+      options.name
+    );
+    this.register(
+      simpleConfigProvider({
+        name: options.name,
+        defaultConfig: options.default,
+        defaultConfigFilename,
+        envVarName: options.environmentVariable,
+        path: configsPath,
+        filenameFormat
+      })
+    );
+    const config = this.getConfig();
+    await config.loadFromFile("", true, false);
+    if (options.loadFromEnvironment) {
+      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");
+    const keys = ["ca", "cert", "key"];
+    const info = await Promise.all(
+      keys.map(async (key) => {
+        const filepath = credentialsInfo[key];
+        if (!filepath)
+          return void 0;
+        const file = await fs.readFile(pathUtils.joinFrom(location, filepath), "utf8");
+        return {
+          key,
+          file
+        };
+      })
+    );
+    return info.reduce((acc, item) => {
+      if (item) {
+        acc[item.key] = item.file;
+      }
+      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) {
+      return this._express;
+    }
+    if (http2Config.enabled && !httpsConfig.enabled) {
+      throw new Error("HTTP2 requires for HTTPS to be enabled");
+    }
+    if (!httpsConfig.credentials) {
+      throw new Error("The `credentials` object on the HTTPS settings is missing");
+    }
+    const credentials = await this._loadCredentials(
+      httpsConfig.credentials,
+      httpsConfig.credentials.onHome
+    );
+    if (!Object.keys(credentials).length) {
+      throw new Error("No credentials were found for HTTPS");
+    }
+    if (http2Config.enabled) {
+      const serverOptions = {
+        ...credentials,
+        spdy: http2Config.spdy
+      };
+      return createSpdyServer(serverOptions, this._express);
+    }
+    return createHTTPSServer(credentials, this._express);
+  }
+}
+const jimpex = (...args) => new Jimpex(...args);
+export {
+  Jimpex,
+  jimpex
+};
+//# sourceMappingURL=jimpex.js.map