jimpex 10.0.2 → 11.0.0

package/dist/middlewares/html/showHTML.d.mts

@@ -1,127 +0,0 @@
-import * as _homer0_jimple from '@homer0/jimple';
-import { J as Jimpex, R as MiddlewareConnectFn } from '../../index-Bwf7JHu9.mjs';
-import { AsyncExpressMiddleware } from '../../types/express.mjs';
-import { SendFile } from '../../services/common/sendFile.mjs';
-import { HTMLGenerator } from '../../services/html/htmlGenerator.mjs';
-import { Response, NextFunction } from 'express';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import '../../services/frontend/frontendFs.mjs';
-import 'fs/promises';
-import '@homer0/deferred';
-
-/**
- * The options to customize the behavior of the middleware.
- *
- * @group Middlewares/ShowHTML
- */
-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
- */
-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
- */
-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
- */
-declare 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;
-    /**
-     * @param options  The options to construct the class.
-     */
-    constructor({ inject, ...options }: ShowHTMLConstructorOptions);
-    /**
-     * Generates the middleware that serves the HTML file.
-     */
-    getMiddleware(): AsyncExpressMiddleware;
-    /**
-     * The customization options.
-     */
-    get options(): Readonly<ShowHTMLOptions>;
-    /**
-     * 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;
-}
-/**
- * Creates the middleware that serves an HTML file in the response.
- *
- * @group Middlewares
- * @group Middlewares/ShowHTML
- */
-declare const showHTMLMiddleware: _homer0_jimple.ResourceCreator<"middleware", "connect", (options?: ShowHTMLMiddlewareOptions) => <ContainerType extends Jimpex = Jimpex>(app: ContainerType) => AsyncExpressMiddleware, MiddlewareConnectFn>;
-
-export { ShowHTML, type ShowHTMLConstructorOptions, type ShowHTMLMiddlewareOptions, type ShowHTMLOptions, showHTMLMiddleware };

package/dist/middlewares/index.d.mts

@@ -1,30 +0,0 @@
-export { ErrorHandler, ErrorHandlerConstructorOptions, ErrorHandlerOptions, ErrorHandlerPartialOptions, ErrorHandlerResponseOptions, errorHandlerMiddleware } from './common/errorHandler.mjs';
-export { ForceHTTPS, ForceHTTPSOptions, ForceHTTPSPartialOptions, forceHTTPSMiddleware } from './common/forceHTTPS.mjs';
-export { HSTS, HSTSMiddlewareOptions, HSTSMiddlewarePartialOptions, HSTSMiddlewareSettings, hstsMiddleware } from './common/hsts.mjs';
-export { FastHTML, FastHTMLConstructorOptions, FastHTMLMiddlewareOptions, FastHTMLOptions, fastHTMLMiddleware } from './html/fastHTML.mjs';
-export { ShowHTML, ShowHTMLConstructorOptions, ShowHTMLMiddlewareOptions, ShowHTMLOptions, showHTMLMiddleware } from './html/showHTML.mjs';
-export { VersionValidator, VersionValidatorConstructorOptions, VersionValidatorLatestOptions, VersionValidatorMiddlewareOptions, VersionValidatorOptions, VersionValidatorPartialOptions, VersionValidatorPopupOptions, versionValidatorMiddleware } from './utils/versionValidator.mjs';
-import '@homer0/jimple';
-import '../utils/fns/statuses.mjs';
-import 'statuses';
-import '../index-Bwf7JHu9.mjs';
-import '../types/express.mjs';
-import 'express';
-import '../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import '../services/common/httpError.mjs';
-import '../services/common/appError.mjs';
-import '../services/http/responsesBuilder.mjs';
-import '../services/common/sendFile.mjs';
-import '../services/html/htmlGenerator.mjs';
-import '../services/frontend/frontendFs.mjs';
-import 'fs/promises';
-import '@homer0/deferred';

package/dist/middlewares/utils/index.d.mts

@@ -1,20 +0,0 @@
-export { VersionValidator, VersionValidatorConstructorOptions, VersionValidatorLatestOptions, VersionValidatorMiddlewareOptions, VersionValidatorOptions, VersionValidatorPartialOptions, VersionValidatorPopupOptions, versionValidatorMiddleware } from './versionValidator.mjs';
-import '@homer0/jimple';
-import '../../utils/fns/statuses.mjs';
-import 'statuses';
-import '../../index-Bwf7JHu9.mjs';
-import '../../types/express.mjs';
-import 'express';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import '../../services/common/httpError.mjs';
-import '../../services/common/appError.mjs';
-import '../../services/http/responsesBuilder.mjs';

package/dist/middlewares/utils/versionValidator.d.mts

@@ -1,215 +0,0 @@
-import * as _homer0_jimple from '@homer0/jimple';
-import { Statuses } from '../../utils/fns/statuses.mjs';
-import { J as Jimpex, R as MiddlewareConnectFn } from '../../index-Bwf7JHu9.mjs';
-import { ExpressMiddleware } from '../../types/express.mjs';
-import { DeepPartial } from '../../types/utils.mjs';
-import { HTTPErrorClass } from '../../services/common/httpError.mjs';
-import { ResponsesBuilder } from '../../services/http/responsesBuilder.mjs';
-import { Request } from 'express';
-import 'statuses';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import '../../services/common/appError.mjs';
-
-/**
- * The options for how the middleware should behave if the requested version is `latest`.
- *
- * @group Middlewares/VersionValidator
- */
-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
- */
-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
- */
-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
- */
-type VersionValidatorPartialOptions = DeepPartial<Omit<VersionValidatorOptions, 'version'>>;
-/**
- * The options to construct a {@link VersionValidator}.
- *
- * @group Middlewares/VersionValidator
- */
-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
- */
-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
- */
-declare 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);
-    /**
-     * Generates the middleware that validates the version.
-     */
-    getMiddleware(): ExpressMiddleware;
-    /**
-     * The customization options.
-     */
-    get options(): Readonly<VersionValidatorOptions>;
-    /**
-     * 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;
-    /**
-     * 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;
-}
-/**
- * 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
- */
-declare const versionValidatorMiddleware: _homer0_jimple.ResourceCreator<"middleware", "connect", (options?: VersionValidatorMiddlewareOptions) => <ContainerType extends Jimpex = Jimpex>(app: ContainerType, route: string | undefined) => ExpressMiddleware, MiddlewareConnectFn>;
-
-export { VersionValidator, type VersionValidatorConstructorOptions, type VersionValidatorLatestOptions, type VersionValidatorMiddlewareOptions, type VersionValidatorOptions, type VersionValidatorPartialOptions, type VersionValidatorPopupOptions, versionValidatorMiddleware };

package/dist/services/common/appError.d.mts

@@ -1,139 +0,0 @@
-import * as _homer0_jimple from '@homer0/jimple';
-import { J as Jimpex } from '../../index-Bwf7JHu9.mjs';
-import { Statuses } from '../../utils/fns/statuses.mjs';
-import '../../types/express.mjs';
-import 'express';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import 'statuses';
-
-/**
- * A dictionary with some context information that can be provided to {@link AppError}.
- *
- * @group Services/AppError
- */
-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
- */
-declare 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);
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * An HTTP status code related to the error. This is set using the `status` key on the
-     * `context`.
-     */
-    get status(): number | undefined;
-    /**
-     * Context information related to the error.
-     */
-    get context(): unknown;
-    /**
-     * The date of when the error was generated.
-     */
-    get date(): 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;
-}
-/**
- * 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
- */
-declare const createAppError: (message: string, context?: AppErrorContext | undefined, statuses?: Statuses | undefined) => AppError;
-/**
- * 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
- */
-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
- */
-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
- */
-declare const appErrorProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
-
-export { AppError, type AppErrorClass, type AppErrorContext, type CreateAppErrorFn, appErrorProvider, createAppError };

package/dist/services/common/httpError.d.mts

@@ -1,80 +0,0 @@
-import * as _homer0_jimple from '@homer0/jimple';
-import { J as Jimpex } from '../../index-Bwf7JHu9.mjs';
-import { Statuses } from '../../utils/fns/statuses.mjs';
-import { AppError, AppErrorContext } from './appError.mjs';
-import '../../types/express.mjs';
-import 'express';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import 'statuses';
-
-/**
- * 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
- */
-declare 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, context?: AppErrorContext, statuses?: 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
- */
-declare const createHTTPError: (message: string, status?: string | number | undefined, context?: AppErrorContext | undefined, statuses?: Statuses | undefined) => HTTPError;
-/**
- * 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
- */
-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
- */
-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
- */
-declare const httpErrorProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
-
-export { type CreateHTTPErrorFn, HTTPError, type HTTPErrorClass, createHTTPError, httpErrorProvider };

package/dist/services/common/index.d.mts

@@ -1,47 +0,0 @@
-import * as _homer0_jimple from '@homer0/jimple';
-import { J as Jimpex } from '../../index-Bwf7JHu9.mjs';
-export { AppError, AppErrorClass, AppErrorContext, CreateAppErrorFn, appErrorProvider, createAppError } from './appError.mjs';
-export { CreateHTTPErrorFn, HTTPError, HTTPErrorClass, createHTTPError, httpErrorProvider } from './httpError.mjs';
-export { SendFile, SendFileGeneratorOptions, SendFileOptions, sendFile, sendFileProvider } from './sendFile.mjs';
-import '../../types/express.mjs';
-import 'express';
-import '../../types/http.mjs';
-import 'https';
-import 'http';
-import 'spdy';
-import 'node-fetch';
-import '../../types/utils.mjs';
-import '@homer0/path-utils';
-import '@homer0/simple-logger';
-import '@homer0/simple-config';
-import '@homer0/events-hub';
-import '../../utils/fns/statuses.mjs';
-import 'statuses';
-
-/**
- * Registers all the common services on the container.
- *
- * - {@link AppError | appError}
- * - {@link HTTPError | httpError}
- * - {@link SendFile | sendFile}
- *
- * @example
- *
- *   // Register the collection on the container
- *   container.register(commonServicesProvider);
- *   // Getting access to one the services instance
- *   const sendFile = container.get<SendFile>('sendFile');
- *
- * @group Providers
- */
-declare const commonServicesProvider: {
-    appErrorProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
-    httpErrorProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
-    sendFileProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
-} & Record<string, _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>> & {
-    provider: true;
-} & {
-    register: _homer0_jimple.ProviderRegisterFn<Jimpex>;
-} & Record<string, unknown>;
-
-export { commonServicesProvider };