jimpex 7.0.1 → 8.0.0

package/types/middlewares/html/showHTML.d.ts

@@ -1,128 +0,0 @@
-export type ExpressMiddleware = import('../../types').ExpressMiddleware;
-export type ExpressResponse = import('../../types').ExpressResponse;
-export type ExpressNext = import('../../types').ExpressNext;
-export type SendFile = import('../../services/common/sendFile').SendFile;
-export type HTMLGenerator = import('../../services/html/htmlGenerator').HTMLGenerator;
-/**
- * <O>
- */
-export type MiddlewareCreator<O> = import('../../types').MiddlewareCreator<O>;
-/**
- * A set options to customize the middleware behavior.
- */
-export type ShowHTMLMiddlewareOptions = {
-    /**
-     * The name of the file the middleware will serve.
-     * Default `'index.html'`.
-     */
-    file: string;
-    /**
-     * The name of a {@link HTMLGenerator } service for the
-     * middleware to use. If the service is available, the
-     * value of `file` will be overwritten for the file
-     * generated by the service. Default `'htmlGenerator'`.
-     */
-    htmlGenerator: string;
-};
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').ExpressNext} ExpressNext
- * @typedef {import('../../services/common/sendFile').SendFile} SendFile
- * @typedef {import('../../services/html/htmlGenerator').HTMLGenerator} HTMLGenerator
- */
-/**
- * @typedef {import('../../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-/**
- * A set options to customize the middleware behavior.
- *
- * @typedef {Object} ShowHTMLMiddlewareOptions
- * @property {string} file           The name of the file the middleware will serve.
- *                                   Default `'index.html'`.
- * @property {string} htmlGenerator  The name of a {@link HTMLGenerator} service for the
- *                                   middleware to use. If the service is available, the
- *                                   value of `file` will be overwritten for the file
- *                                   generated by the service. Default `'htmlGenerator'`.
- * @parent module:middlewares
- */
-/**
- * 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 `HTMLGenerator` service
- * and it will automatically server the file generated by it.
- *
- * @parent module:middlewares
- */
-export class ShowHTML {
-    /**
-     * @param {SendFile}      sendFile              Necessary to server the HTML file.
-     * @param {string}        [file='index.html']   The name of the file it will serve. If
-     *                                              `htmlGenerator` is specified, this will
-     *                                              be overwritten with the name of the file
-     *                                              generated by that service.
-     * @param {HTMLGenerator} [htmlGenerator=null]  If used, the file to server will be the
-     *                                              one generated by that service.
-     */
-    constructor(sendFile: SendFile, file?: string, htmlGenerator?: HTMLGenerator);
-    /**
-     * A local reference for the `sendFile` service.
-     *
-     * @type {SendFile}
-     * @access protected
-     * @ignore
-     */
-    _sendFile: SendFile;
-    /**
-     * The name of the file to serve.
-     *
-     * @type {string}
-     * @access protected
-     * @ignore
-     */
-    _file: string;
-    /**
-     * If specified, a reference for a service that generates HTML files.
-     *
-     * @type {HTMLGenerator}
-     * @access protected
-     * @ignore
-     */
-    _htmlGenerator: HTMLGenerator;
-    /**
-     * Whether or not the file is ready to be served.
-     *
-     * @type {boolean}
-     * @access protected
-     * @ignore
-     */
-    _ready: boolean;
-    /**
-     * Returns the Express middleware that serves the HTML file.
-     *
-     * @returns {ExpressMiddleware}
-     */
-    middleware(): ExpressMiddleware;
-    /**
-     * The name of the file to serve.
-     *
-     * @type {string}
-     */
-    get file(): string;
-    /**
-     * Serves the file on the response.
-     *
-     * @param {ExpressResponse} res   The server response.
-     * @param {ExpressNext}     next  The functino to call the next middleware.
-     * @access protected
-     * @ignore
-     */
-    _sendHTML(res: ExpressResponse, next: ExpressNext): void;
-}
-/**
- * A middleware for showing an `index.html` file.
- *
- * @type {MiddlewareCreator<ShowHTMLMiddlewareOptions>}
- * @parent module:middlewares
- */
-export const showHTML: MiddlewareCreator<ShowHTMLMiddlewareOptions>;

package/types/middlewares/index.d.ts

@@ -1,4 +0,0 @@
-import common = require("./common");
-import html = require("./html");
-import utils = require("./utils");
-export { common, html, utils };

package/types/middlewares/utils/index.d.ts

@@ -1,2 +0,0 @@
-export { versionValidator };
-import { versionValidator } from "./versionValidator";

package/types/middlewares/utils/versionValidator.d.ts

@@ -1,247 +0,0 @@
-export type ExpressMiddleware = import('../../types').ExpressMiddleware;
-export type ExpressRequest = import('../../types').ExpressRequest;
-export type ResponsesBuilder = import('../../services/http/responsesBuilder').ResponsesBuilder;
-/**
- * <O>
- */
-export type MiddlewareCreator<O> = import('../../types').MiddlewareCreator<O>;
-/**
- * The options for how the middleware should behave if the requested version is `latest`.
- */
-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.
- */
-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
-     * `'vesion:conflict'`.
-     */
-    message: string;
-};
-/**
- * The options used to customize a {@link VersionValidator } instance.
- */
-export type VersionValidatorOptions = {
-    /**
-     * The error message to show when the
-     * version is invalid.
-     */
-    error: 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 version used to validate the
-     * requests.
-     * On the {@link VersionValidator }constructor, if specified via
-     * parameter,
-     * the class will take care of
-     * automatically add it to the options.
-     */
-    version: string | number;
-};
-/**
- * @typedef {import('../../types').ExpressMiddleware} ExpressMiddleware
- * @typedef {import('../../types').ExpressRequest} ExpressRequest
- * @typedef {import('../../services/http/responsesBuilder').ResponsesBuilder} ResponsesBuilder
- * @prettierignore
- */
-/**
- * @typedef {import('../../types').MiddlewareCreator<O>} MiddlewareCreator<O>
- * @template O
- */
-/**
- * The options for how the middleware should behave if the requested version is `latest`.
- *
- * @typedef {Object} VersionValidatorLatestOptions
- * @property {boolean} allow  Whether or not the middleware should validate the _"latest
- *                            version"_.
- *                            Default `true`.
- * @property {string}  name   The name of the _"latest version"_. Basically,
- *                            `req.params.version`
- *                            must match with this property in order to be consider
- *                            "latest".
- *                            Default `'latest'`.
- * @parent module:middlewares
- */
-/**
- * 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.
- *
- * @typedef {Object} VersionValidatorPopupOptions
- * @property {string} variable  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'`.
- * @property {string} title     The title of the page that will be generated to respond in
- *                              case the versions don't match. Default `'Conflict'`.
- * @property {string} message   The contents of the post message the generated page will
- *                              send if the versions don't match. Default
- *                              `'vesion:conflict'`.
- * @parent module:middlewares
- */
-/**
- * The options used to customize a {@link VersionValidator} instance.
- *
- * @typedef {Object} VersionValidatorOptions
- * @property {string}                        error    The error message to show when the
- *                                                    version is invalid.
- * @property {VersionValidatorLatestOptions} latest   The options for how the middleware
- *                                                    should behave if the requested
- *                                                    version is `latest`.
- * @property {VersionValidatorPopupOptions}  popup    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.
- * @property {string | number}               version  The version used to validate the
- *                                                    requests.
- *                                                    On the {@link VersionValidator}
- *                                                    constructor, if specified via
- *                                                    parameter,
- *                                                    the class will take care of
- *                                                    automatically add it to the options.
- * @parent module:middlewares
- */
-/**
- * This is the handler for the middleware/controller that validates the app version.
- * This is useful in cases where you want to restrict the access to the app to specific
- * versions,
- * for example: you have a frontend app which needs to be aligned with the "current"
- * version of the app, 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.
- *
- * @parent module:middlewares
- */
-export class VersionValidator {
-    /**
-     * @param {?(string | ?number)} version
-     * The current version of the app. The reason this is nullable is because this comes
-     * directly from the app configuration, but you may want to re use this to validate
-     * "another version", so you can use the custom shorthand and send the version using the
-     * `options` parameter.
-     * @param {ResponsesBuilder} responsesBuilder
-     * To generate post message responses for popups.
-     * @param {ClassAppError} AppError
-     * To generate the error in case the version is invalid.
-     * @param {Partial<VersionValidatorOptions>} [options={}]
-     * Custom options to modify the middleware behavior.
-     * @throws {Error}
-     * If the version is `null` and the `options` don't include one either.
-     */
-    constructor(version: (string | (number | null)) | null, responsesBuilder: ResponsesBuilder, AppError: any, options?: Partial<VersionValidatorOptions>);
-    /**
-     * A local reference for the `responsesBuilder` service.
-     *
-     * @type {ResponsesBuilder}
-     * @access protected
-     * @ignore
-     */
-    _responsesBuilder: ResponsesBuilder;
-    /**
-     * A local reference for the class the app uses to generate errors.
-     *
-     * @type {ClassAppError}
-     * @access protected
-     * @ignore
-     */
-    _AppError: any;
-    /**
-     * These are the "settings" the middleware will use in order to validate the requests.
-     *
-     * @type {VersionValidatorOptions}
-     * @access protected
-     * @ignore
-     */
-    _options: VersionValidatorOptions;
-    /**
-     * Returns the Express middleware that will validate the `version` parameter.
-     *
-     * @returns {ExpressMiddleware}
-     */
-    middleware(): ExpressMiddleware;
-    /**
-     * The options used to customize the middleware behavior.
-     *
-     * @returns {VersionValidatorOptions}
-     */
-    get options(): VersionValidatorOptions;
-    /**
-     * Helper method that checks if the incoming request is from a popup.
-     *
-     * @param {ExpressRequest} req  The request information.
-     * @returns {boolean}
-     * @access protected
-     * @ignore
-     */
-    _isPopup(req: ExpressRequest): boolean;
-    /**
-     * 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 {string | number} version  The version to validate.
-     * @returns {boolean}
-     * @access protected
-     * @ignore
-     */
-    _validateLatest(version: string | number): boolean;
-}
-/**
- * A middleware that will validate a `version` request parameter against the app version
- * and generate an error if they don't match.
- * This is a "middleware/controller" is 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#middleware};
- * but if used as controller, it will mount it on `[route]/:version/*`.
- *
- * @type {MiddlewareCreator<VersionValidatorOptions>}
- * @parent module:middlewares
- */
-export const versionValidator: MiddlewareCreator<VersionValidatorOptions>;

package/types/services/common/appError.d.ts

@@ -1,89 +0,0 @@
-export type Provider = import('../../types').Provider;
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-/**
- * A simple subclass of `Error` but with support for context information.
- *
- * @augments Error
- * @parent module:services
- */
-export class AppError extends Error {
-    /**
-     * @param {string} message       The error message.
-     * @param {Object} [context={}]  Context information related to the error.
-     */
-    constructor(message: string, context?: any);
-    /**
-     * Context information related to the error.
-     *
-     * @type {Object}
-     * @access protected
-     * @todo Remove Object.freeze.
-     */
-    _context: any;
-    /**
-     * The date of when the error was generated.
-     *
-     * @type {Date}
-     * @access protected
-     */
-    _date: Date;
-    /**
-     * Context information related to the error.
-     *
-     * @type {Object}
-     */
-    get context(): any;
-    /**
-     * The date of when the error was generated.
-     *
-     * @type {Date}
-     */
-    get date(): Date;
-    /**
-     * Information about the error that can be shown on an app response. This is set using
-     * the `response` key on the `context`. The idea is that the error handler will read it
-     * and use it on the response.
-     *
-     * @returns {Object}
-     */
-    get response(): any;
-    /**
-     * An HTTP status code related to the error. This is set using the `status` key on the
-     * `context`. If the error handler finds it, it will use it as the response status,
-     * and use it if necessary.
-     *
-     * @type {?number}
-     */
-    get status(): number;
-    /**
-     * 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 status code from the `statuses` package.
-     *
-     * @param {Object} original  The original context to format.
-     * @returns {Object}
-     * @access protected
-     * @ignore
-     */
-    _parseContext(original: any): any;
-}
-/**
- * A service provider that will register both the {@link AppError} and a generator
- * function on the container. `AppError` will be the key for class, and `appError` will be
- * for the generator function.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(appError);
- *   // Getting access to the class.
- *   const AppError = container.get('AppError');
- *   // Getting access to the function.
- *   const appError = container.get('appError');
- *
- * @parent module:services
- */
-export const appError: Provider;

package/types/services/common/httpError.d.ts

@@ -1,37 +0,0 @@
-export type Provider = import('../../types').Provider;
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-/**
- * A type of error to be used on HTTP requests.
- *
- * @augments AppError
- * @parent module:services
- */
-export class HTTPError extends AppError {
-    /**
-     * @param {string} message       The error message.
-     * @param {number} [status=200]  The HTTP status code of the request response.
-     * @param {Object} [context={}]  Context information related to the error.
-     */
-    constructor(message: string, status?: number, context?: any);
-}
-/**
- * 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.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(httpError);
- *   // Getting access to the class.
- *   const HTTPError = container.get('HTTPError');
- *   // Getting access to the function.
- *   const httpError = container.get('httpError');
- *
- * @parent module:services
- */
-export const httpError: Provider;
-import { AppError } from "./appError";

package/types/services/common/index.d.ts

@@ -1,18 +0,0 @@
-export = commonServices;
-/**
- * @typedef {import('../../types').Provider} Provider
- */
-/**
- * The providers collection for the common services.
- *
- * @type {Provider}
- * @property {Provider} appError   The provider for {@link AppError}.
- * @property {Provider} httpError  The provider for {@link HTTPError}.
- * @property {Provider} sendFile   The provider for {@link SendFile}.
- * @parent module:services
- */
-declare const commonServices: Provider;
-declare namespace commonServices {
-    export { Provider };
-}
-type Provider = import('../../types').Provider;

package/types/services/common/sendFile.d.ts

@@ -1,56 +0,0 @@
-export type PathUtils = import('../../types').PathUtils;
-export type Provider = import('../../types').Provider;
-export type ExpressResponse = import('../../types').ExpressResponse;
-export type ExpressNext = import('../../types').ExpressNext;
-export type SendFile = (res: ExpressResponse, filepath: string, next: ExpressNext, from?: string) => any;
-/**
- * @typedef {import('../../types').PathUtils} PathUtils
- * @typedef {import('../../types').Provider} Provider
- * @typedef {import('../../types').ExpressResponse} ExpressResponse
- * @typedef {import('../../types').ExpressNext} ExpressNext
- */
-/**
- * @callback SendFile
- * @param {ExpressResponse} res           Necessary to write the file.
- * @param {string}          filepath      The path to the file relative to where the app
- *                                        executable is located.
- * @param {ExpressNext}     next          To call the send out the error if anything
- *                                        happens.
- * @param {string}          [from='app']  The location it uses to build the relative path.
- *                                        It can be `app` for the directory where the app
- *                                        executable is located, or `home` for the project
- *                                        root directory.
- * @parent module:services
- */
-/**
- * Generates a function to send files with path relatives to the app executable file is
- * located.
- *
- * @example
- *
- *   // Let's say this is inside an Express middleware.
- *   // Get the function
- *   const send = sendFile(pathUtils);
- *   send(res, 'some-file.html', next);
- *   // If your app is on `/app/index.js`, this will send `/app/some-file.html`.
- *
- * @param {PathUtils} pathUtils  To generate the relative paths.
- * @returns {SendFile}
- * @parent module:services
- */
-export function sendFile(pathUtils: PathUtils): SendFile;
-/**
- * The service provider that once registered on the app container will set the result of
- * `sendFile(pathUtils)` as the `sendFile` service.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(sendFileProvider);
- *   // Getting access to the service instance
- *   const sendFile = container.get('sendFile');
- *
- * @parent module:services
- */
-export const sendFileProvider: Provider;

package/types/services/frontend/frontendFs.d.ts

@@ -1,72 +0,0 @@
-export type PathUtils = import('../../types').PathUtils;
-export type Provider = import('../../types').Provider;
-/**
- * @typedef {import('../../types').PathUtils} PathUtils
- * @typedef {import('../../types').Provider} Provider
- */
-/**
- * This service allows the app to easily read static files. The idea behind centralizing
- * this functionalities into a service is that is pretty common to have bundling tools to
- * generate the frontend, and on that process files can have different paths or not even
- * be generated all, that's why this service exists. The service can be
- * extended/overwritten to accommodate any requirements and avoid having to update or add
- * `if`s to every `fs` call the app does.
- * Another _'feature'_ of this service is that all the paths are relative to the directory
- * where the app executable is located, so you don't have to remember the relative path
- * from the place you are accessing a file to the place where it's located.
- *
- * @parent module:services
- */
-export class FrontendFs {
-    /**
-     * @param {PathUtils} pathUtils  To generate the relative paths.
-     */
-    constructor(pathUtils: PathUtils);
-    /**
-     * A local reference for the `pathUtils` service.
-     *
-     * @type {PathUtils}
-     * @access protected
-     * @ignore
-     */
-    _pathUtils: PathUtils;
-    /**
-     * Delete a file from the file system.
-     *
-     * @param {string} filepath  The path to the file.
-     * @returns {Promise}
-     */
-    delete(filepath: string): Promise<any>;
-    /**
-     * Read a file from the file system.
-     *
-     * @param {string} filepath            The path to the file.
-     * @param {string} [encoding='utf-8']  The text encoding in which the file should be
-     *                                     read.
-     * @returns {Promise<string>}
-     */
-    read(filepath: string, encoding?: string): Promise<string>;
-    /**
-     * Write a file on the file system.
-     *
-     * @param {string} filepath  The path to the file.
-     * @param {string} data      The contents of the file.
-     * @returns {Promise}
-     */
-    write(filepath: string, data: string): Promise<any>;
-}
-/**
- * The service provider that once registered on the app container will set an instance of
- * `FrontendFs` as the `frontendFs` service.
- *
- * @type {Provider}
- * @example
- *
- *   // Register it on the container
- *   container.register(frontendFs);
- *   // Getting access to the service instance
- *   const frontendFs = container.get('frontendFs');
- *
- * @parent module:services
- */
-export const frontendFs: Provider;

package/types/services/frontend/index.d.ts

@@ -1,3 +0,0 @@
-declare const _exports: Provider;
-export = _exports;
-export type Provider = import('../../types').Provider;