jimpex 7.0.2 → 8.0.0

package/src/middlewares/html/showHTML.ts

@@ -0,0 +1,165 @@
+import { middlewareCreator } from '../../utils';
+import type { HTMLGenerator, SendFile } from '../../services';
+import type { AsyncExpressMiddleware, Response, NextFunction } from '../../types';
+/**
+ * The options to customize the behavior of the middleware.
+ *
+ * @group Middlewares/ShowHTML
+ */
+export type ShowHTMLOptions = {
+  /**
+   * 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;
+};
+/**
+ * The options to construct a {@link ShowHTML}.
+ *
+ * @group Middlewares/ShowHTML
+ */
+export type ShowHTMLConstructorOptions = Partial<ShowHTMLOptions> & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    sendFile: SendFile;
+    /**
+     * 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 ShowHTML}.
+ *
+ * @group Middlewares/ShowHTML
+ */
+export type ShowHTMLMiddlewareOptions = Partial<ShowHTMLOptions> & {
+  /**
+   * The name of an {@link HTMLGenerator} service already available in the application.
+   *
+   * @default 'htmlGenerator'
+   */
+  htmlGeneratorServiceName?: string;
+};
+
+/**
+ * A very simple middleware service to send an HTML on a server response. The special
+ * _'feature'_ of this service is that it can be hooked up to an {@link HTMLGenerator}
+ * service and it will automatically server the file generated by it.
+ *
+ * @group Middleware Classes
+ * @group Middlewares/ShowHTML
+ * @prettierignore
+ */
+export class ShowHTML {
+  /**
+   * The service that serves a file.
+   */
+  protected readonly _sendFile: SendFile;
+  /**
+   * 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: ShowHTMLOptions;
+  /**
+   * 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;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor({ inject, ...options }: ShowHTMLConstructorOptions) {
+    this._sendFile = inject.sendFile;
+    this._getHTMLGenerator = inject.getHTMLGenerator || (() => undefined);
+    this._options = {
+      file: 'index.html',
+      ...options,
+    };
+  }
+  /**
+   * Generates the middleware that serves the HTML file.
+   */
+  getMiddleware(): AsyncExpressMiddleware {
+    return async (_, res, next) => {
+      // 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<ShowHTMLOptions> {
+    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,
+    });
+  }
+}
+/**
+ * Creates the middleware that serves an HTML file in the response.
+ *
+ * @group Middlewares
+ * @group Middlewares/ShowHTML
+ */
+export const showHTMLMiddleware = middlewareCreator(
+  (options: ShowHTMLMiddlewareOptions = {}) =>
+    (app) => {
+      const { htmlGeneratorServiceName = 'htmlGenerator', ...rest } = options;
+      return new ShowHTML({
+        inject: {
+          sendFile: app.get('sendFile'),
+          getHTMLGenerator: () => app.try(htmlGeneratorServiceName),
+        },
+        ...rest,
+      }).getMiddleware();
+    },
+);

package/src/middlewares/index.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './html';
+export * from './utils';

package/src/middlewares/utils/index.ts

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

package/src/middlewares/utils/versionValidator.ts

@@ -0,0 +1,289 @@
+import { deepAssignWithOverwrite } from '@homer0/deep-assign';
+import { middlewareCreator, type Statuses } from '../../utils';
+import { DeepPartial, Request, ExpressMiddleware } from '../../types';
+import type { HTTPErrorClass, ResponsesBuilder } from '../../services';
+/**
+ * The options for how the middleware should behave if the requested version is `latest`.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorLatestOptions = {
+  /**
+   * Whether or not the middleware should validate the _"latest version"_.
+   *
+   * @default true
+   */
+  allow: boolean;
+  /**
+   * The name of the _"latest version"_. Basically, `req.params.version` must match with
+   * this property in order to be consider "latest".
+   *
+   * @default 'latest'
+   */
+  name: string;
+};
+/**
+ * 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.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorPopupOptions = {
+  /**
+   * 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'
+   */
+  variable: string;
+  /**
+   * The title of the page that will be generated to respond in case the versions don't
+   * match.
+   *
+   * @default 'Conflict'
+   */
+  title: string;
+  /**
+   * The contents of the post message the generated page will send if the versions don't
+   * match.
+   *
+   * @default 'version:conflict'
+   */
+  message: string;
+};
+/**
+ * The options used to customize a {@link VersionValidator} instance.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorOptions = {
+  /**
+   * The version used to validate the requests.
+   */
+  version: string;
+  /**
+   * The options for how the middleware should behave if the requested version is
+   * `latest`.
+   */
+  latest: VersionValidatorLatestOptions;
+  /**
+   * 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.
+   */
+  popup: VersionValidatorPopupOptions;
+  /**
+   * The error message to show when the version is invalid.
+   *
+   * @default "The application version doesn't match"
+   * @prettierignore
+   */
+  error: string;
+};
+/**
+ * A partial version of the {@link VersionValidatorOptions}, to be used in the constructor
+ * and the middleware creator. The reason it omits `version` it's because for the
+ * constructor it's required, but for the middleware creator it's not.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorPartialOptions = DeepPartial<
+  Omit<VersionValidatorOptions, 'version'>
+>;
+/**
+ * The options to construct a {@link VersionValidator}.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorConstructorOptions = VersionValidatorPartialOptions & {
+  /**
+   * The version used to validate the requests.
+   */
+  version: string;
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    HTTPError: HTTPErrorClass;
+    responsesBuilder: ResponsesBuilder;
+    statuses: Statuses;
+  };
+};
+/**
+ * The options for the middleware creator that will mount an instance of
+ * {@link VersionValidator}.
+ *
+ * @group Middlewares/VersionValidator
+ */
+export type VersionValidatorMiddlewareOptions = VersionValidatorPartialOptions & {
+  /**
+   * The version used to validate the requests. This is optional in here because if it's
+   * not specified, it will be obtained from the configuration service.
+   */
+  version?: string;
+};
+/**
+ * This is the handler for the middleware/controller that validates the application
+ * version.
+ * This is useful in cases where you want to restrict the access to specific versions; for
+ * example: you have a frontend which needs to be aligned with the "current" version of
+ * the application, 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.
+ *
+ * @group Middleware Classes
+ * @group Middlewares/VersionValidator
+ * @prettierignore
+ */
+export class VersionValidator {
+  /**
+   * To generate the errors in case the validation fails.
+   */
+  protected readonly _HTTPError: HTTPErrorClass;
+  /**
+   * To generate responses for popups.
+   */
+  protected readonly _responsesBuilder: ResponsesBuilder;
+  /**
+   * The uility service to get HTTP status codes.
+   */
+  protected readonly _statuses: Statuses;
+  /**
+   * The customization options.
+   */
+  protected readonly _options: VersionValidatorOptions;
+  /**
+   * @param options  The options to construct the class.
+   * @throws If no `version` is specified in the options.
+   */
+  constructor({ inject, version, ...options }: VersionValidatorConstructorOptions) {
+    this._HTTPError = inject.HTTPError;
+    this._responsesBuilder = inject.responsesBuilder;
+    this._statuses = inject.statuses;
+    this._options = deepAssignWithOverwrite(
+      {
+        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');
+    }
+  }
+  /**
+   * Generates the middleware that validates the version.
+   */
+  getMiddleware(): ExpressMiddleware {
+    return (req, res, next) => {
+      // Get the `version` parameter from the request.
+      const { version } = req.params;
+      // If no version is present, move on to the next middleware.
+      if (!version) {
+        next();
+        return;
+      }
+      // If the version matches, or it's a "latest" version, move on to the next middleware.
+      if (version === this._options.version || this._isTheAllowedLatest(version)) {
+        next();
+        return;
+      }
+
+      const status = this._statuses('conflict');
+      // If the request comes from a popup, send the post message.
+      if (this._isPopup(req)) {
+        const { title, message } = this._options.popup;
+        this._responsesBuilder.htmlPostMessage({
+          res,
+          title,
+          message,
+          status,
+        });
+        return;
+      }
+
+      // Every other validation failed, and it's not a popup, so generate an error.
+      next(
+        new this._HTTPError(this._options.error, status, {
+          response: {
+            validation: true,
+          },
+        }),
+      );
+    };
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<VersionValidatorOptions> {
+    return deepAssignWithOverwrite({}, this._options);
+  }
+  /**
+   * Helper method that checks if the incoming request is from a popup. It will look for
+   * the query string variable defined in the constructor options.
+   *
+   * @param req  The request object sent by the application.
+   */
+  protected _isPopup(req: Request): boolean {
+    const popup = req.query[this._options.popup.variable];
+    return !!(popup && String(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 version  The version received in the request.
+   */
+  protected _isTheAllowedLatest(version: string): boolean {
+    const { allow, name } = this._options.latest;
+    return allow && version === name;
+  }
+}
+/**
+ * A middleware that will validate a `version` request parameter against the application
+ * version, and generate an error if they don't match.
+ * This is a "middleware/controller" 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.getMiddleware}; but if used as controller, it will mount it on
+ * `[route]/:version/*`.
+ *
+ * @group Middlewares
+ * @group Middlewares/VersionValidator
+ */
+export const versionValidatorMiddleware = middlewareCreator(
+  (options: VersionValidatorMiddlewareOptions = {}) =>
+    (app, route) => {
+      const version = app.getConfig<string>('version');
+      const middleware = new VersionValidator({
+        inject: {
+          HTTPError: app.get('HTTPError'),
+          responsesBuilder: app.get('responsesBuilder'),
+          statuses: app.get('statuses'),
+        },
+        version,
+        ...options,
+      }).getMiddleware();
+
+      if (route) {
+        const router = app.getRouter();
+        return router.all('/:version/*', middleware);
+      }
+
+      return middleware;
+    },
+);

package/src/services/common/appError.ts

@@ -0,0 +1,158 @@
+import { provider, statuses as statusesFn, type Statuses } from '../../utils';
+/**
+ * A dictionary with some context information that can be provided to {@link AppError}.
+ *
+ * @group Services/AppError
+ */
+export type AppErrorContext = {
+  /**
+   * Extra information that the error handler can pick and include the response.
+   */
+  response?: unknown;
+  /**
+   * A status code or name for the error handler to set in the response.
+   */
+  status?: string | number;
+} & Record<string, unknown>;
+/**
+ * A simple subclass of `Error` but with support for context information.
+ *
+ * @group Services
+ * @group Services/AppError
+ */
+export class AppError extends Error {
+  /**
+   * The date of when the error was generated.
+   */
+  readonly _date: Date;
+  /**
+   * The context information that can be provided to the error, and picked by the error
+   * handler.
+   */
+  readonly _context: AppErrorContext;
+  /**
+   * The service that generates HTTP status codes.
+   */
+  protected _statuses: Statuses;
+  /**
+   * @param message   The message of the error.
+   * @param context   The context information, for the error handler.
+   * @param statuses  A reference to the service that generates HTTP status codes. This
+   *                  is in case the implementation wants to use a special version from
+   *                  the container; otherwise, it will use the `statuses` library
+   *                  directly.
+   */
+  constructor(
+    message: string,
+    context: AppErrorContext = {},
+    statuses: Statuses = statusesFn,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this._date = new Date();
+    this._statuses = statuses;
+    this._context = this._parseContext(context);
+
+    // Limit the stack trace if possible.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Gets an object that can be included in a response from the application. This method
+   * is a helper for the `response` getter, as it allows for the assertion of the response
+   * type.
+   *
+   * @template T  The type of the response.
+   */
+  getResponse<T>(): T {
+    return this.response as T;
+  }
+  /**
+   * Information about the error that can be included in a response. This is set using the
+   * `response` key in the `context` option.
+   */
+  get response(): unknown {
+    return this._context.response || {};
+  }
+  /**
+   * An HTTP status code related to the error. This is set using the `status` key on the
+   * `context`.
+   */
+  get status(): number | undefined {
+    return this._context.status as number | undefined;
+  }
+  /**
+   * Context information related to the error.
+   */
+  get context(): unknown {
+    return this._context;
+  }
+  /**
+   * The date of when the error was generated.
+   */
+  get date(): Date {
+    return this._date;
+  }
+  /**
+   * 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 actual status code from the `statuses `service.
+   *
+   * @param context  The original context sent to the constructor.
+   */
+  protected _parseContext(context: AppErrorContext): AppErrorContext {
+    const result = { ...context };
+    if (result.status && typeof result.status === 'string') {
+      result.status = this._statuses.code[result.status.toLowerCase()] || result.status;
+    }
+
+    return result;
+  }
+}
+/**
+ * Shorthand for `new AppError()`.
+ *
+ * @param args  The same parameters as the {@link AppError} constructor.
+ * @returns A new instance of {@link AppError}.
+ * @group Services
+ * @group Services/AppError
+ */
+export const createAppError = (
+  ...args: ConstructorParameters<typeof AppError>
+): AppError => new AppError(...args);
+/**
+ * The type of the function that generates a new instance of {@link AppError}.
+ * This is exported to make it easy to type the dependency injection.
+ *
+ * @group Services/AppError
+ */
+export type CreateAppErrorFn = typeof createAppError;
+/**
+ * THe type of the {@link AppError} class.
+ * This is exported to make it easy to type the dependency injection.
+ *
+ * @group Services/AppError
+ */
+export type AppErrorClass = typeof AppError;
+/**
+ * A service provider that will register both, {@link AppError} and
+ * {@link createAppError}, on the container. `AppError` will be the key for class, and
+ * `appError` will be for the generator function.
+ *
+ * @example
+ *
+ *   // Register it on the container
+ *   container.register(appErrorProvider);
+ *   // Getting access to the class.
+ *   const AppError = container.get<AppErrorClass>('AppError');
+ *   // Getting access to the function.
+ *   const appError = container.get<CreateAppErrorFn>('appError');
+ *
+ * @group Providers
+ * @group Services/AppError
+ */
+export const appErrorProvider = provider((app) => {
+  app.set('AppError', () => AppError);
+  app.set('appError', () => createAppError);
+});

package/src/services/common/httpError.ts

@@ -0,0 +1,74 @@
+import { provider, statuses as statusesFn, type Statuses } from '../../utils';
+import { AppError, type AppErrorContext } from './appError';
+/**
+ * A type of error to be used on HTTP requests. This is the most common type of error used
+ * by Jimpex.
+ *
+ * @group Services
+ * @group Services/HTTPError
+ */
+export class HTTPError extends AppError {
+  /**
+   * @param message   The error message.
+   * @param status    The HTTP status code.
+   * @param context   Context information related to the error.
+   * @param statuses  A reference to the service that generates HTTP status codes. This
+   *                  is in case the implementation wants to use a special version from
+   *                  the container; otherwise, it will use the `statuses` library
+   *                  directly.
+   */
+  constructor(
+    message: string,
+    status: number | string = statusesFn('ok'),
+    context: AppErrorContext = {},
+    statuses: Statuses = statusesFn,
+  ) {
+    super(message, { ...context, status }, statuses);
+  }
+}
+/**
+ * Shorthand for `new HTTPError()`.
+ *
+ * @param args  The same parameters as the {@link HTTPError} constructor.
+ * @returns A new instance of {@link HTTPError}.
+ * @group Services
+ * @group Services/HTTPError
+ */
+export const createHTTPError = (
+  ...args: ConstructorParameters<typeof HTTPError>
+): HTTPError => new HTTPError(...args);
+/**
+ * The type of the function that generates a new instance of {@link HTTPError}.
+ * This is exported to make it easy to type the dependency injection.
+ *
+ * @group Services/HTTPError
+ */
+export type CreateHTTPErrorFn = typeof createHTTPError;
+/**
+ * THe type of the {@link HTTPError} class.
+ * This is exported to make it easy to type the dependency injection.
+ *
+ * @group Services/HTTPError
+ */
+export type HTTPErrorClass = typeof HTTPError;
+/**
+ * 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.
+ *
+ * @example
+ *
+ *   // Register it on the container
+ *   container.register(httpErrorProvider);
+ *   // Getting access to the class.
+ *   const HTTPError = container.get<HTTPErrorClass>('HTTPError');
+ *   // Getting access to the function.
+ *   const httpError = container.get<CreateHTTPErrorFn>('httpError');
+ *
+ * @group Providers
+ * @group Services/HTTPError
+ */
+export const httpErrorProvider = provider((app) => {
+  app.set('HTTPError', () => HTTPError);
+  app.set('httpError', () => createHTTPError);
+});