jimpex 7.0.1 → 8.0.0

package/src/controllers/utils/index.ts

@@ -0,0 +1 @@
+export * from './gateway';

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './app';
+export * from './types';
+export * from './controllers';
+export * from './middlewares';
+export * from './services';
+export * from './utils';

package/src/middlewares/common/errorHandler.ts

@@ -0,0 +1,203 @@
+import { deepAssignWithOverwrite } from '@homer0/deep-assign';
+import { middlewareCreator, type Statuses } from '../../utils';
+import type { DeepPartial, Logger, ExpressErrorHandler } from '../../types';
+import { AppError, type HTTPErrorClass, type ResponsesBuilder } from '../../services';
+/**
+ * The options for the responses the middleware will create.
+ *
+ * @group Middlewares/ErrorHandler
+ */
+export type ErrorHandlerResponseOptions = {
+  /**
+   * The message to show in case `showErrors` is set to `false`.
+   *
+   * @default 'Oops! Something went wrong, please try again'
+   * @prettierignore
+   */
+  message: string;
+  /**
+   * The default status code for the responses.
+   *
+   * @default 500
+   */
+  status: number;
+};
+/**
+ * The customization options for the middleware.
+ *
+ * @group Middlewares/ErrorHandler
+ */
+export type ErrorHandlerOptions = {
+  /**
+   * If `false`, unknown errors will show a generic message instead of real message. And
+   * if `true`, it will not only show all kind of errors but it will also show the error
+   * stack.
+   *
+   * By "uknown errors", it means that are not `AppError` nor `HTTPError`.
+   */
+  showErrors: boolean;
+  /**
+   * The options for the default response the middleware will create.
+   */
+  response: ErrorHandlerResponseOptions;
+};
+/**
+ * A partial version of the {@link ErrorHandlerOptions}, to be used in the constructor and
+ * the middleware creator.
+ *
+ * @group Middlewares/ErrorHandler
+ */
+export type ErrorHandlerPartialOptions = DeepPartial<ErrorHandlerOptions>;
+/**
+ * The options to construct a {@link ErrorHandler}.
+ *
+ * @group Middlewares/ErrorHandler
+ */
+export type ErrorHandlerConstructorOptions = ErrorHandlerPartialOptions & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    logger: Logger;
+    responsesBuilder: ResponsesBuilder;
+    statuses: Statuses;
+    HTTPError: HTTPErrorClass;
+  };
+};
+/**
+ * Creates a middleware that handles errors and generates the responses.
+ *
+ * @group Middleware Classes
+ * @group Middlewares/ErrorHandler
+ * @prettierignore
+ */
+export class ErrorHandler {
+  /**
+   * The service that will log the messages in the console.
+   */
+  protected readonly _logger: Logger;
+  /**
+   * The service to generate the responses.
+   */
+  protected readonly _responsesBuilder: ResponsesBuilder;
+  /**
+   * The uility service to get HTTP status codes.
+   */
+  protected readonly _statuses: Statuses;
+  /**
+   * The Error class used by the "known errors".
+   */
+  protected readonly _HTTPError: HTTPErrorClass;
+  /**
+   * The customization options.
+   */
+  protected readonly _options: ErrorHandlerOptions;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor({
+    inject: { logger, responsesBuilder, statuses, HTTPError },
+    ...options
+  }: ErrorHandlerConstructorOptions) {
+    this._logger = logger;
+    this._responsesBuilder = responsesBuilder;
+    this._statuses = statuses;
+    this._HTTPError = HTTPError;
+    this._options = deepAssignWithOverwrite(
+      {
+        showErrors: false,
+        response: {
+          message: 'Unexpected error',
+          status: this._statuses('internal server error'),
+        },
+      },
+      options,
+    );
+  }
+  /**
+   * Generates the middleware that handles the errors.
+   */
+  getMiddleware(): ExpressErrorHandler {
+    return (err, _, res, next) => {
+      // If there wasn't any error, continue the execution.
+      if (!err) {
+        next();
+        return;
+      }
+
+      const { response, showErrors } = this._options;
+
+      // Define the base status and response.
+      let { status } = response;
+      let data: {
+        error: boolean;
+        message: string;
+        stack?: string[];
+      } & Record<string, unknown> = {
+        error: true,
+        message: response.message,
+      };
+
+      const knownError = err instanceof AppError;
+      // If it's a "known error" or the `showErrors` flag is set to `true`...
+      if (showErrors || knownError) {
+        // Get the real message.
+        data.message = err.message;
+        // If it's a "known error"...
+        if (knownError) {
+          // Try to extract information for the response.
+          data = {
+            ...data,
+            ...err.getResponse(),
+          };
+          status = err.status || (this._statuses('bad request') as number);
+        }
+        /**
+         * If the flag is set to `true`, and it's a "valid error", try to extract the
+         * stack, format it, and include it in the response.
+         */
+        if (showErrors && err instanceof Error && err.stack) {
+          const stack = err.stack.split('\n').map((line) => line.trim());
+          data.stack = stack;
+          stack.splice(0, 1);
+          this._logger.error(`ERROR: ${err.message}`);
+          this._logger.info(stack);
+        }
+      }
+
+      this._responsesBuilder.json({
+        res,
+        data,
+        status,
+      });
+    };
+  }
+  /**
+   * The handler customization options.
+   */
+  get options(): Readonly<ErrorHandlerOptions> {
+    return deepAssignWithOverwrite({}, this._options);
+  }
+}
+/**
+ * Creates the middleware that handles errors.
+ *
+ * @group Middlewares
+ * @group Middlewares/ErrorHandler
+ */
+export const errorHandlerMiddleware = middlewareCreator(
+  (options: ErrorHandlerPartialOptions = {}) =>
+    (app) => {
+      const showErrors = app.getConfig<boolean | undefined>('debug.showErrors') === true;
+      return new ErrorHandler({
+        inject: {
+          logger: app.get('logger'),
+          responsesBuilder: app.get('responsesBuilder'),
+          statuses: app.get('statuses'),
+          HTTPError: app.get('HTTPError'),
+        },
+        showErrors,
+        ...options,
+      }).getMiddleware();
+    },
+);

package/src/middlewares/common/forceHTTPS.ts

@@ -0,0 +1,83 @@
+import { middlewareCreator } from '../../utils';
+import { ExpressMiddleware } from '../../types';
+/**
+ * The customization options for the middleware.
+ *
+ * @group Middlewares/ForceHTTPS
+ */
+export type ForceHTTPSOptions = {
+  /**
+   * A list of regular expressions to match routes that should be ignored.
+   *
+   * @default [/^\/service\//]
+   */
+  ignoredRoutes: RegExp[];
+};
+/**
+ * A partial version of the {@link ForceHTTPSOptions}, to be used in the constructor and
+ * the middleware creator.
+ *
+ * @group Middlewares/ForceHTTPS
+ */
+export type ForceHTTPSPartialOptions = Partial<ForceHTTPSOptions>;
+/**
+ * Creates a middleware that forces all the traffic to be through HTTPS.
+ *
+ * @group Middleware Classes
+ * @group Middlewares/ForceHTTPS
+ * @prettierignore
+ */
+export class ForceHTTPS {
+  /**
+   * The customization options.
+   */
+  protected readonly _options: ForceHTTPSOptions;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor(options: ForceHTTPSPartialOptions = {}) {
+    this._options = {
+      ignoredRoutes: [/^\/service\//],
+      ...options,
+    };
+  }
+  /**
+   * Generates the middleware that redirects the traffic.
+   */
+  getMiddleware(): ExpressMiddleware {
+    return (req, res, next) => {
+      if (
+        !req.secure &&
+        req.get('X-Forwarded-Proto') !== 'https' &&
+        !this._options.ignoredRoutes.some((expression) =>
+          expression.test(req.originalUrl),
+        )
+      ) {
+        const host = req.get('Host');
+        res.redirect(`https://${host}${req.url}`);
+      } else {
+        next();
+      }
+    };
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<ForceHTTPSOptions> {
+    return { ...this._options };
+  }
+}
+/**
+ * Creates the middleware that redirects the traffic to HTTPS.
+ *
+ * @group Middlewares
+ * @group Middlewares/ForceHTTPS
+ */
+export const forceHTTPSMiddleware = middlewareCreator(
+  (options: ForceHTTPSPartialOptions = {}) =>
+    (app) => {
+      const enabled = app.getConfig<boolean | undefined>('forceHTTPS');
+      if (!enabled) return undefined;
+      return new ForceHTTPS(options).getMiddleware();
+    },
+);

package/src/middlewares/common/hsts.ts

@@ -0,0 +1,135 @@
+import { middlewareCreator } from '../../utils';
+import { ExpressMiddleware } from '../../types';
+/**
+ * The options to customize the HSTS header value.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security}
+ * @group Middlewares/HSTS
+ */
+export type HSTSMiddlewareOptions = {
+  /**
+   * The time, in seconds, that the browser should remember that a site is only to be
+   * accessed using HTTPS.
+   *
+   * @default 31536000
+   */
+  maxAge: number;
+  /**
+   * Whether or not the rule should apply to all sub domains.
+   *
+   * @default true
+   */
+  includeSubDomains: boolean;
+  /**
+   * Whether or not to include on the major browsers'
+   * preload list. This directive is not part of the specification, for more information
+   * about it, you should check the MDN documentation for the header.
+   *
+   * @default false
+   */
+  preload: boolean;
+};
+/**
+ * A partial version of the {@link HSTSMiddlewareOptions}, to be used in the constructor
+ * and the middleware creator.
+ *
+ * @group Middlewares/HSTS
+ */
+export type HSTSMiddlewarePartialOptions = Partial<HSTSMiddlewareOptions>;
+/**
+ * The options for the middleware creator that will create the middleware, or not,
+ * depending on the `enabled` option.
+ *
+ * @group Middlewares/HSTS
+ */
+export type HSTSMiddlewareSettings = HSTSMiddlewarePartialOptions & {
+  /**
+   * If it's not `true`, it won't return the middleware.
+   */
+  enabled?: boolean;
+};
+/**
+ * Generates a middleware that includes the HSTS header on the responses.
+ *
+ * @see {@link https://tools.ietf.org/html/rfc6797}
+ * @group Middleware Classes
+ * @group Middlewares/HSTS
+ * @prettierignore
+ */
+export class HSTS {
+  /**
+   * The customization options for the header.
+   */
+  protected readonly _options: HSTSMiddlewareOptions;
+  /**
+   * The value of the header that will be included in the responses.
+   */
+  protected readonly _header: string;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor(options: HSTSMiddlewarePartialOptions = {}) {
+    this._options = {
+      maxAge: 31536000,
+      includeSubDomains: true,
+      preload: false,
+      ...options,
+    };
+    this._header = this._buildHeader();
+  }
+  /**
+   * Generates the middleware that includes the HSTS header on the responses.
+   */
+  getMiddleware(): ExpressMiddleware {
+    return (_, res, next) => {
+      res.setHeader('Strict-Transport-Security', this._header);
+      next();
+    };
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<HSTSMiddlewareOptions> {
+    return { ...this._options };
+  }
+  /**
+   * The value of the header that will be included in the responses.
+   */
+  get header(): string {
+    return this._header;
+  }
+  /**
+   * Creates the header value based on the customization options.
+   */
+  protected _buildHeader(): string {
+    const { maxAge, includeSubDomains, preload } = this._options;
+    const directives = [`max-age=${maxAge}`];
+    if (includeSubDomains) {
+      directives.push('includeSubDomains');
+    }
+
+    if (preload) {
+      directives.push('preload');
+    }
+
+    return directives.join('; ');
+  }
+}
+/**
+ * Creates the middleware that includes the HSTS header on the responses.
+ *
+ * @group Middlewares
+ * @group Middlewares/HSTS
+ */
+export const hstsMiddleware = middlewareCreator(
+  (options: HSTSMiddlewareSettings = {}) =>
+    (app) => {
+      const setting = app.getConfig<HSTSMiddlewareSettings | undefined>('hsts');
+      if (
+        !setting?.enabled ||
+        (typeof options.enabled !== 'undefined' && !options.enabled)
+      )
+        return undefined;
+      return new HSTS(options).getMiddleware();
+    },
+);

package/src/middlewares/common/index.ts

@@ -0,0 +1,3 @@
+export * from './errorHandler';
+export * from './forceHTTPS';
+export * from './hsts';

package/src/middlewares/html/fastHTML.ts

@@ -0,0 +1,255 @@
+import { createRouteExpression, middlewareCreator, removeSlashes } from '../../utils';
+import type { HTMLGenerator, SendFile } from '../../services';
+import type { AsyncExpressMiddleware, Response, NextFunction, Events } from '../../types';
+/**
+ * The options to customize the behavior of the middleware.
+ *
+ * @group Middlewares/FastHTML
+ */
+export type FastHTMLOptions = {
+  /**
+   * The name of the file the middleware will serve. If the {@link HTMLGenerator} service
+   * is available, it will be overriden by the service.
+   *
+   * @default 'index.html'
+   */
+  file: string;
+  /**
+   * A list of regular expressions to match request paths that should be ignored by the
+   * middleware.
+   *
+   * @default [/\.ico$/i]
+   */
+  ignoredRoutes: RegExp[];
+  /**
+   * If `true`, {@link FastHTML} will get the list of all the routes controlled by the
+   * application, and will use them to validate the incoming requests (in addition to the
+   * `ignore` list): If a request URL doesn't match with any of the "controlled routes",
+   * it will serve the HTML file.
+   *
+   * @default true
+   */
+  useAppRoutes: boolean;
+};
+/**
+ * The options to construct a {@link FastHTML}.
+ *
+ * @group Middlewares/FastHTML
+ */
+export type FastHTMLConstructorOptions = Partial<FastHTMLOptions> & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    sendFile: SendFile;
+    events: Events;
+    /**
+     * A function to get a possible {@link HTMLGenerator}. This is injected as a "getter"
+     * to not interrupt the DIC "lifecycle": middlewares are initialized right when the
+     * app starts, and injecting a reference would force the service to be initialized
+     * too, even if a request is not being made.
+     */
+    getHTMLGenerator?: () => HTMLGenerator | undefined;
+  };
+};
+/**
+ * The options for the middleware creator that will mount an instance of {@link FastHTML}.
+ *
+ * @group Middlewares/FastHTML
+ */
+export type FastHTMLMiddlewareOptions = Partial<FastHTMLOptions> & {
+  /**
+   * The name of an {@link HTMLGenerator} service already available in the application.
+   *
+   * @default 'htmlGenerator'
+   */
+  htmlGeneratorServiceName?: string;
+};
+/**
+ * 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.
+ *
+ * @group Middleware Classes
+ * @group Middlewares/FastHTML
+ * @prettierignore
+ */
+export class FastHTML {
+  /**
+   * The service that serves a file.
+   */
+  protected readonly _sendFile: SendFile;
+  /**
+   * The application envent bus, to listen and get the list of "controlled routes" after
+   * the application is started.
+   */
+  protected readonly _events: Events;
+  /**
+   * A function to get a possible {@link HTMLGenerator}. This is injected as a "getter"
+   * to not interrupt the DIC "lifecycle": middlewares are initialized right when the
+   * app starts, and injecting a reference would force the service to be initialized
+   * too, even if a request is not being made.
+   */
+  protected readonly _getHTMLGenerator: () => HTMLGenerator | undefined;
+  /**
+   * The customization options for the middleware.
+   */
+  protected _options: FastHTMLOptions;
+  /**
+   * Whether or not the file is ready to be served. In case the middleware uses an
+   * {@link HTMLGenerator} service, the file needs to be generated before being available,
+   * and that's why this flag exists.
+   */
+  protected _fileReady: boolean = false;
+  /**
+   * A list of regular expression that match the routes controlled by the application.
+   * This is in case the `useAppRoutes` option is set to `true`; when the application gets
+   * started, an event listener will obtain all the top controlled routes, create regular
+   * expressions, and save them on this property.
+   */
+  protected _routeExpressions: RegExp[] = [];
+  /**
+   * @param options  The options to construct the class.
+   * @throws If `ignoredRoutes` is empty and `useAppRoutes` is set to `false`.
+   */
+  constructor({ inject, ...options }: FastHTMLConstructorOptions) {
+    this._sendFile = inject.sendFile;
+    this._events = inject.events;
+    this._getHTMLGenerator = inject.getHTMLGenerator || (() => undefined);
+    this._options = {
+      file: 'index.html',
+      ignoredRoutes: [/\.ico$/i],
+      useAppRoutes: true,
+      ...options,
+    };
+
+    if (!this._options.ignoredRoutes.length && !this._options.useAppRoutes) {
+      throw new Error('You must provide either `ignoredRoutes` or `useAppRoutes`');
+    }
+
+    if (this._options.useAppRoutes) {
+      this._setupEvents();
+    }
+  }
+  /**
+   * Generates the middleware that serves the HTML file.
+   */
+  getMiddleware(): AsyncExpressMiddleware {
+    return async (req, res, next) => {
+      // If the route should be ignored, move to the next middleware.
+      if (this._shouldIgnoreRoute(req.originalUrl)) {
+        next();
+        return;
+      }
+
+      // If the file is ready to be served, serve it.
+      if (this._fileReady) {
+        this._sendResponse(res, next);
+        return;
+      }
+
+      const htmlGenerator = this._getHTMLGenerator();
+      // If there's no generator, switch the flag and just serve the file.
+      if (!htmlGenerator) {
+        this._fileReady = true;
+        this._sendResponse(res, next);
+        return;
+      }
+
+      try {
+        // Wait for the HTML to be generated.
+        await htmlGenerator.whenReady();
+        // Update the local option.
+        this._options.file = htmlGenerator.options.file;
+        // Switch the flag and serve the file.
+        this._fileReady = true;
+        this._sendResponse(res, next);
+      } catch (error) {
+        next(error);
+      }
+    };
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<FastHTMLOptions> {
+    return { ...this._options };
+  }
+  /**
+   * Serves the HTML file to the response.
+   *
+   * @param res   The response object generated by the application.
+   * @param next  The function to call the next middleware.
+   */
+  protected _sendResponse(res: Response, next: NextFunction): void {
+    res.setHeader('Content-Type', 'text/html');
+    this._sendFile({
+      res,
+      next,
+      filepath: this._options.file,
+    });
+  }
+  /**
+   * Adds the event listener that obtains the list of "controlled routes" when
+   * `useAppRoutes` is set to `true`.
+   */
+  protected _setupEvents() {
+    this._events.once('afterStart', ({ app }) => {
+      const [routeExpressions] = app.routes.reduce<[RegExp[], string[]]>(
+        (acc, route) => {
+          const [expressions, processed] = acc;
+          const clean = removeSlashes(route).trim();
+          if (!clean || processed.includes(clean)) return acc;
+          expressions.push(createRouteExpression(clean));
+          processed.push(clean);
+          return acc;
+        },
+        [[], []],
+      );
+      this._routeExpressions.push(...routeExpressions);
+    });
+  }
+  /**
+   * Validates whether a route should be ignored or not. The method checks first against
+   * the `ignore` option, and then against the list of "controlled routes" if
+   * `useAppRoutes` is set to `true`.
+   *
+   * @param route  The route to validate.
+   */
+  protected _shouldIgnoreRoute(route: string): boolean {
+    return (
+      this._options.ignoredRoutes.some((expression) => route.match(expression)) ||
+      this._routeExpressions.some((expression) => route.match(expression))
+    );
+  }
+}
+/**
+ * Creates the middleware that filters the routes and serves an HTML before the
+ * application gets to evaluate whether there's a controller for the request or not.
+ *
+ * @group Middlewares
+ * @group Middlewares/FastHTML
+ */
+export const fastHTMLMiddleware = middlewareCreator(
+  (options: FastHTMLMiddlewareOptions = {}) =>
+    (app) => {
+      const { htmlGeneratorServiceName = 'htmlGenerator', ...rest } = options;
+      return new FastHTML({
+        inject: {
+          events: app.get('events'),
+          sendFile: app.get('sendFile'),
+          getHTMLGenerator: () => app.try(htmlGeneratorServiceName),
+        },
+        ...rest,
+      }).getMiddleware();
+    },
+);

package/src/middlewares/html/index.ts

@@ -0,0 +1,2 @@
+export * from './fastHTML';
+export * from './showHTML';