jimpex 8.0.0 → 9.0.0

package/dist/index-efeb437e.d.ts

@@ -0,0 +1,1282 @@
+import { ExpressMiddlewareLike } from './types/express.mjs';
+import { JimpexServer, JimpexServerInstance, JimpexHTTPSCredentials } from './types/http.mjs';
+import { NoStringIndex, DeepPartial, DeepReadonly } from './types/utils.mjs';
+import '@homer0/path-utils';
+import { SimpleLogger } from '@homer0/simple-logger';
+import { SimpleConfig } from '@homer0/simple-config';
+import { EventsHub } from '@homer0/events-hub';
+import { Router, Express } from 'express';
+import 'node-fetch';
+import 'https';
+import 'http';
+import * as _homer0_jimple from '@homer0/jimple';
+import { ProviderRegisterFn as ProviderRegisterFn$1, GenericCurriedFn, Jimple } from '@homer0/jimple';
+
+/**
+ * The base payload the events emitted by the application send.
+ *
+ * @template T  Extra properties beside the reference to the application.
+ * @group Services/Events
+ */
+type EventPayload<T = Record<string, unknown>> = {
+    /**
+     * A reference to the application.
+     */
+    app: Jimpex;
+} & T;
+/**
+ * A dictionary with the events emitted by the application and their payloads.
+ *
+ * @group Services/Events
+ */
+interface JimpexEvents {
+    /**
+     * Called right before creating the server and calling `listen` on it.
+     */
+    beforeStart: EventPayload;
+    /**
+     * Called once the server confirmed that is listening.
+     */
+    start: EventPayload;
+    /**
+     * Called after the controllers and middlewares have been mounted.
+     */
+    afterStart: EventPayload;
+    /**
+     * Called after the `onStart` callback has been called.
+     */
+    afterStartCallback: EventPayload;
+    /**
+     * Called before closing the server instance.
+     */
+    beforeStop: EventPayload;
+    /**
+     * Called after the server instance has been closed.
+     */
+    afterStop: EventPayload;
+    /**
+     * Called every time a new route is mounted in the application.
+     */
+    routeAdded: EventPayload<{
+        route: string;
+    }>;
+}
+/**
+ * The events emitted by the application.
+ *
+ * @group Services/Events
+ */
+type JimpexEventName = keyof JimpexEvents;
+/**
+ * The type of the payload sent by a specific event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      payload.
+ * @group Services/Events
+ */
+type JimpexEventPayload<EventName extends JimpexEventName> = JimpexEvents[EventName];
+/**
+ * A dictionary of the reducer events and their targets.
+ *
+ * @group Services/Events
+ */
+interface JimpexReducerEventTargets {
+    /**
+     * It gets called before mounting a router/middleware for a specific route.
+     */
+    controllerWillBeMounted: Router | ExpressMiddlewareLike;
+    /**
+     * It gets called before using a middleware without route.
+     */
+    middlewareWillBeUsed: ExpressMiddlewareLike;
+}
+/**
+ * A dictionary of the payloads the reducer events the application uses.
+ *
+ * @group Services/Events
+ */
+interface JimpexReducerEventPayloads {
+    /**
+     * It gets called before mounting a router/middleware for a specific route.
+     */
+    controllerWillBeMounted: EventPayload<{
+        /**
+         * The route in which the controller will be mounted.
+         */
+        route: string;
+        /**
+         * A reference for the controller/middleware before being "connected".
+         */
+        controller: Controller | Middleware;
+    }>;
+    /**
+     * It gets called before using a middleware without route.
+     */
+    middlewareWillBeUsed: EventPayload;
+}
+/**
+ * The reducer events used by the application.
+ *
+ * @group Services/Events
+ */
+type JimpexReducerEventName = keyof JimpexReducerEventTargets;
+/**
+ * The type of the target of a specific reducer event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      target.
+ * @group Services/Events
+ */
+type JimpexReducerEventTarget<EventName extends JimpexReducerEventName> = JimpexReducerEventTargets[EventName];
+/**
+ * The type of the payload of a specific reducer event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      payload.
+ * @group Services/Events
+ */
+type JimpexReducerEventPayload<EventName extends JimpexReducerEventName> = JimpexReducerEventPayloads[EventName];
+/**
+ * The name of the events o reducer events emitted/used by the application.
+ * This generic type exists because the listener for both types are added using the same
+ * method.
+ *
+ * @group Services/Events
+ */
+type JimpexEventNameLike = JimpexEventName | JimpexReducerEventName;
+/**
+ * The definition of a listener for an event or a reducer event.
+ *
+ * @template EventName  The literal type of the event, to validate whether the
+ *                      parameters should be for a reducer event or an event.
+ * @group Services/Events
+ */
+type JimpexEventListener<EventName extends JimpexEventNameLike> = EventName extends JimpexEventName ? (payload: JimpexEventPayload<EventName>) => void : EventName extends JimpexReducerEventName ? (target: JimpexReducerEventTarget<EventName>, payload: JimpexReducerEventPayload<EventName>) => JimpexReducerEventTarget<EventName> : never;
+/**
+ * The `events` service Jimpex uses.
+ * This is an alternative declaration of the `EventsHub` class that uses the interfaces
+ * and types from this project.
+ *
+ * @group Services
+ * @group Services/Events
+ */
+type Events = {
+    /**
+     * Adds a new event listener.
+     *
+     * @param event     The name of the event.
+     * @param listener  The listener function.
+     * @returns An unsubscribe function to remove the listener.
+     * @template EventName  The literal type of the event, to generate the type of the
+     *                      listener.
+     * @example
+     *
+     *   const unsubscribe = events.on('afterStart', ({ app }) => {
+     *     app.getLogger().info('Hello world!');
+     *     unsubscribe();
+     *   });
+     *
+     */
+    on: <EventName extends JimpexEventNameLike>(eventName: EventName, listener: JimpexEventListener<EventName>) => () => boolean;
+    /**
+     * Adds an event listener that will only be executed once.
+     *
+     * @param event     The name of the event.
+     * @param listener  The listener function.
+     * @returns An unsubscribe function to remove the listener.
+     * @template EventName  The literal type of the event, to generate the type of the
+     *                      listener.
+     * @example
+     *
+     *   events.once('afterStart', ({ app }) => {
+     *     app.getLogger().info('Hello world!');
+     *     unsubscribe();
+     *   });
+     *
+     */
+    once: <EventName extends JimpexEventNameLike>(eventName: EventName, listener: JimpexEventListener<EventName>) => () => boolean;
+    /**
+     * Emits an event and call all its listeners.
+     *
+     * @param event    The name of the events.
+     * @param payload  Context information for the event.
+     * @template EventName  The literal type of the event, to generate the type of the
+     *                      payload.
+     * @example
+     *
+     *   // Extend the interface to type the payload.
+     *   interface JimpexEvents {
+     *     myEvent: { message: string };
+     *   }
+     *   // Add the listener.
+     *   events.on('myEvent', ({ message }) => {
+     *     console.log('Event received:', message);
+     *   });
+     *   // Trigger the event.
+     *   events.emit('myEvent', { message: 'Hello' });
+     *   // prints "Event received: Hello"
+     *
+     */
+    emit: <EventName extends JimpexEventName>(event: JimpexEventName, payload: JimpexEventPayload<EventName>) => void;
+    /**
+     * Asynchronously reduces a target using an event. It's like emit, but the event
+     * listeners return a modified (or not) version of the `target`.
+     *
+     * @param event    The name of the event.
+     * @param target   The variable to reduce with the reducers/listeners.
+     * @param payload  Context information for the event.
+     * @returns A version of the `target` processed by the listeners.
+     * @template EventName  The literal type of the event, to generate the types of the
+     *                      target and the payload.
+     * @example
+     *
+     *   // Extend the interface to type the target.
+     *   interface JimpexReducerEventTargets {
+     *     myReducer: unknown[];
+     *   }
+     *   // Extend the interface to type the payload.
+     *   interface JimpexReducerEventPayloads {
+     *     myReducer: {
+     *       message: string;
+     *     };
+     *   }
+     *   // Add the reducer.
+     *   events.on('myReducer', async (target, { message }) => {
+     *     const data = await fetch('https://api.example.com/' + message);
+     *     target.push(data);
+     *     return target;
+     *   });
+     *   // Trigger the event.
+     *   const result = await events.reduce('myReducer', [], { message: 'Hello' });
+     *   // result would be a list of data fetched from the API.
+     *
+     */
+    reduce: <EventName extends JimpexReducerEventName>(event: JimpexReducerEventName, target: JimpexReducerEventTarget<EventName>, payload: JimpexReducerEventPayload<EventName>) => Promise<JimpexReducerEventTarget<EventName>>;
+    /**
+     * Synchronously reduces a target using an event. It's like emit, but the events
+     * listener return a modified (or not) version of the `target`.
+     *
+     * @param event    The name of the event.
+     * @param target   The variable to reduce with the reducers/listeners.
+     * @param payload  Context information for the event.
+     * @returns A version of the `target` processed by the listeners.
+     * @template EventName  The literal type of the event, to generate the types of the
+     *                      target and the payload.
+     * @example
+     *
+     *   // Extend the interface to type the target.
+     *   interface JimpexReducerEventTargets {
+     *     myReducer: string[];
+     *   }
+     *   // Extend the interface to type the payload.
+     *   interface JimpexReducerEventPayloads {
+     *     myReducer: {
+     *       message: string;
+     *     };
+     *   }
+     *   // Add the reducer.
+     *   events.on('myReducer', (target, { message }) => {
+     *     target.push(message);
+     *     return target;
+     *   });
+     *   // Trigger the event.
+     *   events.reduce('event', [], 'Hello');
+     *   // returns ['Hello']
+     *
+     */
+    reduceSync: <EventName extends JimpexReducerEventName>(event: JimpexReducerEventName, target: JimpexReducerEventTarget<EventName>, payload: JimpexReducerEventPayload<EventName>) => JimpexReducerEventTarget<EventName>;
+};
+
+/**
+ * The options for the application's configuration service.
+ *
+ * @see {@link https://www.npmjs.com/package/@homer0/simple-config}
+ * @group Jimpex
+ */
+type JimpexConfigOptions = {
+    /**
+     * The default settings for the configuration. If no external configuration is used,
+     * this needs to include a `port` property.
+     */
+    default: unknown;
+    /**
+     * The name of the application, used for external configuration files.
+     *
+     * @default 'app'
+     */
+    name: string;
+    /**
+     * The path to where external configuration files are stored. Relative to the project
+     * root.
+     *
+     * @default 'config/'
+     */
+    path: string;
+    /**
+     * Whether the configuration files are inside a sub directory or not. If `true`, a
+     * configuration path would be `config/[app-name]/[file]`.
+     *
+     * @default false
+     */
+    hasFolder: boolean;
+    /**
+     * Whether or not to check for the environment variable and load a configuration file
+     * based on its value.
+     *
+     * @default true
+     */
+    loadFromEnvironment: boolean;
+    /**
+     * The name of the environment variable that will be used to set the active
+     * configuration.
+     *
+     * @default 'CONFIG'
+     */
+    environmentVariable: string;
+    /**
+     * The name of the default configuration file.
+     *
+     * @default '[app-name].config.js'
+     */
+    defaultConfigFilename: string;
+    /**
+     * The name format of other external configuration files.
+     *
+     * @default '[app-name].[config-name].config.js'
+     */
+    filenameFormat: string;
+};
+/**
+ * The options for the middleware that serves static files.
+ *
+ * @group Jimpex
+ */
+type JimpexStaticsOptions = {
+    /**
+     * Whether or not to enable the middleware.
+     *
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * If `true`, the path to the statics folder will be relative to the project root
+     * directory, otherwise, it will be relative to the directory where the app executable
+     * file is located.
+     *
+     * @default false
+     */
+    onHome: boolean;
+    /**
+     * The name of both the route and the folder, relative to whatever you defined with the
+     * `onHome` option.
+     *
+     * @default 'statics'
+     */
+    route: string;
+    /**
+     * By default, the folder will be the same as the `route`,
+     * but you can use this option to define a relative path that won't affect the route.
+     *
+     * @default ''
+     */
+    folder?: string;
+};
+/**
+ * The options for the Express application.
+ *
+ * @group Jimpex
+ */
+type JimpexExpressOptions = {
+    /**
+     * Whether or not to enable the `trust proxy` option.
+     *
+     * @default true
+     */
+    trustProxy: boolean;
+    /**
+     * Whether or not to remove the `x-powered-by` header.
+     *
+     * @default true
+     */
+    disableXPoweredBy: boolean;
+    /**
+     * Whether or not to add the `compression` middleware.
+     *
+     * @default true
+     */
+    compression: boolean;
+    /**
+     * Whether or not to add the `body-parser` middleware.
+     *
+     * @default true
+     */
+    bodyParser: boolean;
+    /**
+     * Whether or not to add the `multer` middleware.
+     *
+     * @see {@link https://www.npmjs.com/package/multer}
+     */
+    multer: boolean;
+};
+/**
+ * The options to configure the application executable path.
+ *
+ * @group Jimpex
+ */
+type JimpexPathOptions = {
+    /**
+     * A "hardcoded" path to the application executable file.
+     *
+     * @default ''
+     */
+    appPath?: string;
+    /**
+     * If `true`, it will try to figure out the parent file path, and use its directory as
+     * the path.
+     *
+     * @default true
+     */
+    useParentPath: boolean;
+};
+/**
+ * The options to enable some of the default services Jimpex comes with.
+ *
+ * @group Jimpex
+ */
+type JimpexServicesOptions = {
+    /**
+     * Whether or not to register all the `common` services: `appError`, `httpError`, and
+     * `sendFile`.
+     *
+     * @default true
+     */
+    common: boolean;
+    /**
+     * Whether or not to register the `http` services: `apiClient`, `http`, and
+     * `responsesBuilder`.
+     *
+     * @default true
+     */
+    http: boolean;
+    /**
+     * Whether or not to register the `utils` services: `ensureBearerToken`.
+     */
+    utils: boolean;
+};
+/**
+ * The format in which the application's health status can be returned.
+ * It's either a simple boolean, or a more detailed object.
+ *
+ * @group Jimpex
+ */
+type JimpexHealthStatus = boolean | {
+    isHealthy?: boolean;
+    services?: Record<string, boolean>;
+};
+/**
+ * Returns the application health status. This is normally used by the `healthController`.
+ *
+ * @group Jimpex
+ */
+type JimpexHealthCheckFn = (app: Jimpex) => Promise<JimpexHealthStatus>;
+/**
+ * The options to create a new instance of Jimpex.
+ *
+ * @group Jimpex
+ */
+type JimpexOptions = {
+    /**
+     * The size limit for the requests payload.
+     *
+     * @default '15MB'
+     */
+    filesizeLimit: string;
+    /**
+     * Whether or not to call the `boot` method after initialization. This is useful if you
+     * want to register/overwrite services only on certain contexts, like a dev environment.
+     *
+     * @default true
+     */
+    boot: boolean;
+    /**
+     * The options to configure the application executable path.
+     */
+    path: JimpexPathOptions;
+    /**
+     * Options for the configuration service.
+     *
+     * @see {@link https://www.npmjs.com/package/@homer0/simple-config}
+     */
+    config: JimpexConfigOptions;
+    /**
+     * Options for the middleware that serves static files.
+     */
+    statics: JimpexStaticsOptions;
+    /**
+     * Options for the Express application.
+     */
+    express: JimpexExpressOptions;
+    /**
+     * Options to manage the default services.
+     */
+    services: JimpexServicesOptions;
+    /**
+     * A function that will be used to check the application health status.
+     */
+    healthCheck: JimpexHealthCheckFn;
+};
+/**
+ * The function called when the application starts listening for requests.
+ *
+ * @group Jimpex
+ */
+type JimpexStartCallback = (config: SimpleConfig) => void;
+
+/**
+ * The function a provider uses to configure a resource in the container.
+ *
+ * @group Wrappers
+ */
+type ProviderRegisterFn = ProviderRegisterFn$1<Jimpex>;
+/**
+ * Creates an object that can configure/extend the container by registering services and
+ * resources.
+ *
+ * @example
+ *
+ *   class APIClient {}
+ *   const apiClientProvider = provider((app) => {
+ *     app.set('apiClient', () => new APIClient());
+ *   });
+ *
+ * @group Wrappers
+ */
+declare const provider: (register: ProviderRegisterFn$1<Jimpex>) => _homer0_jimple.Resource<"provider", "register", ProviderRegisterFn$1<Jimpex>>;
+/**
+ * Creates an object like a provider, but that it can also be used as a function, as it
+ * normally expose options for the resources it will configure.
+ *
+ * @example
+ *
+ * <caption>Registering as a common provider</caption>
+ *
+ *   const apiClientProvider = providerCreator(
+ *     ({ serviceName = 'apiClient' }) =>
+ *       (app) => {
+ *         app.set(serviceName, () => new APIClient());
+ *       },
+ *   );
+ *
+ *   container.register(apiClientProvider);
+ *
+ * @example
+ *
+ * <caption>Registering a created provider</caption>
+ *
+ *   container.register(
+ *     apiClientProvider({
+ *       serviceName: 'myApiClient',
+ *     }),
+ *   );
+ *
+ * @group Wrappers
+ */
+declare const providerCreator: <CreatorFn extends GenericCurriedFn<ProviderRegisterFn$1<Jimpex>>>(creator: CreatorFn) => _homer0_jimple.ResourceCreator<"provider", "register", CreatorFn, ProviderRegisterFn$1<Jimpex>>;
+/**
+ * Creates a collection of providers that can be registered one by one, or all at once.
+ *
+ * @example
+ *
+ * <caption>Registering all the providers at once</caption>
+ *
+ *   const collection = providers({
+ *     apiClient: apiClientProvider,
+ *     http: httpProvider,
+ *   });
+ *
+ *   container.register(collection);
+ *
+ * @example
+ *
+ * <caption>Registering one by one</caption>
+ *
+ *   container.register(collection.http);
+ *
+ * @group Wrappers
+ */
+declare const providers: <ItemsParam>(items: ItemsParam & Record<string, _homer0_jimple.Resource<"provider", "register", ProviderRegisterFn$1<Jimpex>>>) => ItemsParam & Record<string, _homer0_jimple.Resource<"provider", "register", ProviderRegisterFn$1<Jimpex>>> & {
+    provider: true;
+} & {
+    register: ProviderRegisterFn$1<Jimpex>;
+} & Record<string, unknown>;
+/**
+ * An object that can configure/extend the container by registering services and
+ * resources.
+ *
+ * @group Wrappers
+ */
+type Provider = ReturnType<typeof provider>;
+/**
+ * A provider creator is like a provider, but it can also be used as a function, and it
+ * expose options for the resources it will configure.
+ *
+ * @group Wrappers
+ */
+type ProviderCreator = ReturnType<typeof providerCreator>;
+/**
+ * A collection of providers that can be registered one by one, or all at once.
+ *
+ * @group Wrappers
+ */
+type Providers = ReturnType<typeof providers>;
+/**
+ * A union of all types that can be registered in the provider with a `register` function.
+ *
+ * @group Wrappers
+ */
+type ProviderLike = Provider | ProviderCreator | Providers;
+/**
+ * The function a controller uses to mount a controller/middleware in the container.
+ *
+ * @param container  The reference to the Jimpex container.
+ * @param route      The route on which the controller will be mounted on.
+ * @group Wrappers
+ */
+type ControllerConnectFn = <ContainerType extends Jimpex = Jimpex>(container: ContainerType, route: string) => Router | ExpressMiddlewareLike;
+/**
+ * Generates a routes controller for the application container to mount.
+ *
+ * @param connect  A function that will be called the moment the application mounts the
+ *                 controller, and that is in charge of registering routes and
+ *                 middlewares.
+ * @example
+ *
+ *   const myController = controller((app) => {
+ *     const router = app.getRouter();
+ *     const ctrl = new MyController();
+ *     return router.get('...', ctrl.doSomething()).post('...', ctrl.doSomethingElse());
+ *   });
+ *
+ *   // ...
+ *   container.mount('/charo', myController);
+ *
+ * @group Wrappers
+ */
+declare const controller: (connect: ControllerConnectFn) => _homer0_jimple.Resource<"controller", "connect", ControllerConnectFn>;
+/**
+ * A high order function that generates a controller. It's used on the definitions of a
+ * controller creator.
+ *
+ * @group Wrappers
+ */
+type ControllerCreatorFn = GenericCurriedFn<ControllerConnectFn>;
+/**
+ * Generates a configurable routes controller for the application to mount. It's
+ * configurable because the `creator`, instead of just being sent to the container to
+ * mount, it can also be called as a function with custom parameters the controller can
+ * receive.
+ *
+ * @param creator  A function that will generate a controller.
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   const myController = controllerCreator((options = {}) => (app) => {
+ *     const router = app.getRouter();
+ *     const ctrl = new MyController(options);
+ *     return router.get('...', ctrl.doSomething()).post('...', ctrl.doSomethingElse());
+ *   });
+ *
+ *   // ...
+ *   container.mount('/charo', myController);
+ *
+ * @example
+ *
+ * <caption>Custom parameters</caption>
+ *
+ *   container.mount('/pili', myController({ foo: 'bar' }));
+ *
+ * @group Wrappers
+ */
+declare const controllerCreator: <CreatorFn extends ControllerCreatorFn>(creator: CreatorFn) => _homer0_jimple.ResourceCreator<"controller", "connect", CreatorFn, ControllerConnectFn>;
+/**
+ * A resource that will define middlewares for specific routes.
+ *
+ * @group Wrappers
+ */
+type Controller = ReturnType<typeof controller>;
+/**
+ * A controller creator is like a controller, but it can also be used as a function, and
+ * it can receive custom parameters to configure its behavior.
+ *
+ * @group Wrappers
+ */
+type ControllerCreator = ReturnType<typeof controllerCreator>;
+/**
+ * The function a controller provider uses to configure/extend the container before
+ * returning an actual controller.
+ *
+ * @param container  The reference to the Jimpex container.
+ * @param route      The route on which the controller will be mounted on.
+ * @group Wrappers
+ */
+type ControllerProviderRegisterFn = <ContainerType extends Jimpex = Jimpex>(container: ContainerType, route: string) => Controller;
+/**
+ * Creates a "controller provider", which is a controller that can configure/extend the
+ * container before the application mounts it.
+ *
+ * @param register  A function that will be called the moment the application mounts
+ *                  the controller provider.
+ * @example
+ *
+ *   class MyController {}
+ *   const myControllerProvider = controllerProvider((app) => {
+ *     app.set('myController', () => new MyController());
+ *     return controller(() => {
+ *       const ctrl = app.get<MyController>('myController');
+ *       const router = app.getRouter();
+ *       return router.get('/', ctrl.doSomething());
+ *     });
+ *   });
+ *
+ * @group Wrappers
+ */
+declare const controllerProvider: (register: ControllerProviderRegisterFn) => _homer0_jimple.Resource<"provider", "register", ControllerProviderRegisterFn>;
+/**
+ * A high order function that generates a controller provider. It's used on the
+ * definitions of a controller provider creator.
+ *
+ * @group Wrappers
+ */
+type ControllerProviderCreatorFn = GenericCurriedFn<ControllerProviderRegisterFn>;
+/**
+ * Generates a configurable controller provider for the application to mount. This is a
+ * mix of a controller creator and a controller provider: it gives you the flexibility of
+ * the creator, with the resources of the provider.
+ *
+ * @param creator  A function that will generate a controller provider.
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   class MyController {}
+ *   const myControllerProvider = controllerProviderCreator(
+ *     ({ serviceName = 'myController' }) =>
+ *       (app) => {
+ *         app.set(serviceName, () => new MyController());
+ *         return controller(() => {
+ *           const ctrl = app.get<MyController>(serviceName);
+ *           const router = app.getRouter();
+ *           return router.get('/', ctrl.doSomething());
+ *         });
+ *       },
+ *   );
+ *
+ *   // ...
+ *   container.mount('/charo', myControllerProvider);
+ *
+ * @example
+ *
+ * <caption>Custom parameters</caption>
+ *
+ *   container.mount('/pili', myControllerProvider({ serviceName: 'something' }));
+ *
+ * @group Wrappers
+ */
+declare const controllerProviderCreator: <CreatorFn extends ControllerProviderCreatorFn>(creator: CreatorFn) => _homer0_jimple.ResourceCreator<"provider", "register", CreatorFn, ControllerProviderRegisterFn>;
+/**
+ * A special kind of controller that can be used to configure/extend the container before
+ * returning an actual controller.
+ *
+ * @group Wrappers
+ */
+type ControllerProvider = ReturnType<typeof controllerProvider>;
+/**
+ * A "creator version" of a controller provider: a controller that can be used to
+ * configure/extend the container before returning an actual controller, but that can also
+ * be called as a function, and it can receive custom parameters to configure its
+ * behavior.
+ *
+ * @group Wrappers
+ */
+type ControllerProviderCreator = ReturnType<typeof controllerProviderCreator>;
+/**
+ * The function a middleware uses to mount itself in the container.
+ *
+ * @param container  The reference to the Jimpex container.
+ * @param route      This is optional because the implementation can use it as a
+ *                   "global widdleware", or for a specific route.
+ * @returns The resource can choose to be enabled or not by returning the function, or
+ *          `undefined`.
+ * @group Wrappers
+ */
+type MiddlewareConnectFn = <ContainerType extends Jimpex = Jimpex>(app: ContainerType, route?: string) => Router | ExpressMiddlewareLike | undefined;
+/**
+ * Generates a middleware for the application container to mount.
+ *
+ * @param connect  A function that will be called the moment the application tries to
+ *                 mount the middleware.
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   const myMiddleware = controller((app) => {
+ *     const responsesBuilder = app.get<ResponsesBuilder>('responsesBuilder');
+ *     return (_, res) => {
+ *       responsesBuilder.json({ res, data: { hello: 'world' } });
+ *     };
+ *   });
+ *
+ *   // ...
+ *   container.use(myMiddleware);
+ *
+ * @example
+ *
+ * <caption>On a specific route</caption>
+ *
+ *   container.mount('/charo', myMiddleware);
+ *
+ * @group Wrappers
+ */
+declare const middleware: (connect: MiddlewareConnectFn) => _homer0_jimple.Resource<"middleware", "connect", MiddlewareConnectFn>;
+/**
+ * A high order function that generates a middleware. It's used on the definitions of a
+ * middleware creator.
+ *
+ * @group Wrappers
+ */
+type MiddlewareCreatorFn = GenericCurriedFn<MiddlewareConnectFn>;
+/**
+ * Generates a configurable middleware for the application to use. It's configurable
+ * because the `creator`, instead of just being sent to the container to mount, it can
+ * also be called as a function with custom parameters the middleware can receive.
+ *
+ * @param creator  A function that will generate a middleware.
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   const myMiddleware = middlewareCreator((options = {}) => (app) => {
+ *     const message = options.message || 'Hello Charo!';
+ *     const responsesBuilder = app.get<ResponsesBuilder>('responsesBuilder');
+ *     return (_, res) => {
+ *       responsesBuilder.json({ res, data: { message } });
+ *     };
+ *   });
+ *
+ *   // ...
+ *   container.use(myMiddleware);
+ *
+ * @example
+ *
+ * <caption>Custom parameters</caption>
+ *
+ *   container.use(myMiddleware({ message: 'Hello Pili!' }));
+ *
+ * @group Wrappers
+ */
+declare const middlewareCreator: <CreatorFn extends MiddlewareCreatorFn>(creator: CreatorFn) => _homer0_jimple.ResourceCreator<"middleware", "connect", CreatorFn, MiddlewareConnectFn>;
+/**
+ * A resource that will define middlewares the application can use.
+ *
+ * @group Wrappers
+ */
+type Middleware = ReturnType<typeof middleware>;
+/**
+ * A middleware creator is like a middleware, but i can also be used as a function, and it
+ * can receive custom parameters to configure its behavior.
+ *
+ * @group Wrappers
+ */
+type MiddlewareCreator = ReturnType<typeof middlewareCreator>;
+/**
+ * The function a middelware provider uses to configure/extend the container before
+ * returning an actual middleware.
+ *
+ * @param container  The reference to the Jimpex container.
+ * @param route      This is available only in the case the middleware is mounted on a
+ *                   specific route.
+ * @group Wrappers
+ */
+type MiddlewareProviderRegisterFn = <ContainerType extends Jimpex = Jimpex>(container: ContainerType, route?: string) => Middleware;
+/**
+ * Creates a "middleware provider", which is a middleware that can configure/extend the
+ * container before the application uses it.
+ *
+ * @param register  A function that will be called the moment the application uses the
+ *                  middleware provider.
+ * @example
+ *
+ *   class MyServiceWithMiddleware {
+ *     constructor(private readonly responsesBuilder: ResponsesBuilder) {}
+ *     getMiddleware() {
+ *       return (_, res) => {
+ *         this.responsesBuilder.json({ res, data: { message } });
+ *       };
+ *     }
+ *   }
+ *
+ *   const myMiddlewareProvider = middlewareProvider((app) => {
+ *     app.set(
+ *       'myMiddleware',
+ *       () => new MyServiceWithMiddleware(app.get('responsesBuilder')),
+ *     );
+ *     return middleware(() =>
+ *       app.get<MyServiceWithMiddleware>('myMiddleware').getMiddleware(),
+ *     );
+ *   });
+ *
+ * @group Wrappers
+ */
+declare const middlewareProvider: (register: MiddlewareProviderRegisterFn) => _homer0_jimple.Resource<"provider", "register", MiddlewareProviderRegisterFn>;
+/**
+ * A high order function that generates a middleware provider. It's used on the
+ * definitions of a middleware provider creator.
+ *
+ * @group Wrappers
+ */
+type MiddlewareProviderCreatorFn = GenericCurriedFn<MiddlewareProviderRegisterFn>;
+/**
+ * Generates a configurable middleware provider for the application to use. This is a mix
+ * of a middleware creator and a middleware provider: it gives you the flexibility of the
+ * creator, with the resources of the provider.
+ *
+ * @param creator  A function that will generate a middleware provider.
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   class MyServiceWithMiddleware {
+ *     constructor(private readonly responsesBuilder: ResponsesBuilder) {}
+ *     getMiddleware() {
+ *       return (_, res) => {
+ *         this.responsesBuilder.json({ res, data: { message } });
+ *       };
+ *     }
+ *   }
+ *   const myMiddlewareProvider = middlewareProviderCreator(
+ *     ({ serviceName = 'myMiddleware' }) =>
+ *       (app) => {
+ *         app.set(
+ *           serviceName,
+ *           () => new MyServiceWithMiddleware(app.get('responsesBuilder')),
+ *         );
+ *         return middleware(() =>
+ *           app.get<MyServiceWithMiddleware>(serviceName).getMiddleware(),
+ *         );
+ *       },
+ *   );
+ *
+ *   // ...
+ *   container.use(myMiddlewareProvider);
+ *
+ * @example
+ *
+ * <caption>Custom parameters</caption>
+ *
+ *   container.use(myMiddlewareProvider({ serviceName: 'something' }));
+ *
+ * @group Wrappers
+ */
+declare const middlewareProviderCreator: <CreatorFn extends MiddlewareProviderCreatorFn>(creator: CreatorFn) => _homer0_jimple.ResourceCreator<"provider", "register", CreatorFn, MiddlewareProviderRegisterFn>;
+/**
+ * A special kind of middleware that can be used to configure/extend the container before
+ * returning an actual middleware.
+ *
+ * @group Wrappers
+ */
+type MiddlewareProvider = ReturnType<typeof middlewareProvider>;
+/**
+ * A "creator version" of a middleware provider: a middleware that can be used to
+ * configure/extend the container before returning an actual middleware, but that can also
+ * be called as a function, and it can receive custom parameters to configure its
+ * behavior.
+ *
+ * @group Wrappers
+ */
+type MiddlewareProviderCreator = ReturnType<typeof middlewareProviderCreator>;
+/**
+ * A union types of the different kinds of middlewares that can be used by the
+ * application.
+ *
+ * @group Wrappers
+ */
+type MiddlewareLike = NoStringIndex<Middleware> | NoStringIndex<MiddlewareProvider> | ExpressMiddlewareLike;
+/**
+ * A union types of the different kinds of controllers that can be mounted by the
+ * application.
+ *
+ * @group Wrappers
+ */
+type ControllerLike = NoStringIndex<Controller> | NoStringIndex<ControllerProvider> | MiddlewareLike;
+
+/**
+ * Jimpex is a mix of Jimple, a Javascript port of Pimple dependency injection container,
+ * and Express, one of the most popular web frameworks for Node.
+ *
+ * @group Jimpex
+ * @todo Implement `helmet`.
+ */
+declare class Jimpex extends Jimple {
+    /**
+     * The customization settings for the application.
+     */
+    protected _options: JimpexOptions;
+    /**
+     * The Express application Jimpex uses under the hood.
+     */
+    protected _express: Express;
+    /**
+     * Since the configuration service has an async initialization, the class uses this flag
+     * internally to validate if the configuration has been initialized or not.
+     */
+    protected _configReady: boolean;
+    /**
+     * A reference to the actuall HTTP the application will use. This can vary depending on
+     * whether HTTPS, or HTTP2 are enabled. If HTTPS is not enabled, it will be the same as
+     * the `express` property; if HTTPS is enabled, it will be an `https` server; and if
+     * HTTP2 is enabled, it will be an `spdy` server.
+     */
+    protected _server?: JimpexServer;
+    /**
+     * The instance of the server that is listening for requests.
+     */
+    protected _instance?: JimpexServerInstance;
+    /**
+     * A list of functions that implement controllers and middlewares. When the application
+     * starts, the queue will be processed and those controllers and middlewares will be
+     * added to the server instance. The reason they are not added directly like with a
+     * regular Express implementation is that services on Jimple use lazy loading, and
+     * adding middlewares and controllers as they come could cause errors if they depend on
+     * services that are not yet registered.
+     */
+    protected _mountQueue: Array<(server: Express) => void>;
+    /**
+     * A list with all the top routes controlled by the application. Every time a controller
+     * is mounted, its route will be added here.
+     */
+    protected _controlledRoutes: string[];
+    /**
+     * @param options  Preferences to customize the application.
+     * @param config   The default settings for the configuration service. It's a
+     *                 shortcuit for `options.config.default`
+     */
+    constructor(options?: DeepPartial<JimpexOptions>, config?: unknown);
+    /**
+     * This is where the app would register all its specific services, middlewares and controllers.
+     */
+    boot(): void;
+    /**
+     * Disables the server TLS validation. Meant to be used for development purposes.
+     */
+    disableTLSValidation(): void;
+    /**
+     * Starts the app server.
+     *
+     * @param onStart  A callback function to be called when the server actually starts.
+     * @returns The server instance.
+     */
+    start(onStart?: JimpexStartCallback): Promise<JimpexServerInstance>;
+    /**
+     * This is an alias of `start`. The idea is for it to be used on serverless platforms,
+     * where you don't get to start your app, you just have export it.
+     *
+     * @param port     In case the configuration doesn't already have it,
+     *                 this is the port where the application will use to run. If this
+     *                 parameter is used, the method will overwrite the `port`
+     *                 setting on the configuration service.
+     * @param onStart  A callback function to be called when the server starts.
+     * @returns The server instance.
+     */
+    listen(port?: number, onStart?: JimpexStartCallback): Promise<JimpexServerInstance>;
+    /**
+     * Stops the server instance.
+     */
+    stop(): void;
+    /**
+     * Mounts a route controller or a middleware into a server routes.
+     *
+     * @param route       The route for the controller/middleware.
+     * @param controller  The controller/middleware resource to be mounted.
+     */
+    mount(route: string, controller: ControllerLike): void;
+    /**
+     * Adds a global middleware to the application.
+     *
+     * @param middleware  The middleware resource to be added.
+     */
+    use(middleware: MiddlewareLike): void;
+    getConfig(): SimpleConfig;
+    getConfig<T = unknown>(setting: string | string[], asArray?: boolean): T;
+    /**
+     * Creates a new router instance.
+     */
+    getRouter(): Router;
+    /**
+     * The logger service.
+     */
+    get logger(): SimpleLogger;
+    /**
+     * The Express application Jimpex uses under the hood.
+     */
+    get express(): Express;
+    /**
+     * The server instance that gets created when the app is started.
+     */
+    get instance(): JimpexServerInstance | undefined;
+    /**
+     * The application customization options.
+     */
+    get options(): DeepReadonly<JimpexOptions>;
+    /**
+     * Gets the events service.
+     */
+    get eventsHub(): EventsHub;
+    /**
+     * A list of the routes that have controllers mounted on them.
+     */
+    get routes(): string[];
+    /**
+     * Adds a listener for an application event.
+     *
+     * @param eventName  The name of the event to listen for.
+     * @param listener   The listener function.
+     * @returns A function to unsubscribe the listener.
+     * @template EventName  The name of the event, to match the type of the listener
+     *                      function.
+     */
+    on<EventName extends JimpexEventNameLike>(eventName: EventName, listener: JimpexEventListener<EventName>): () => boolean;
+    /**
+     * Adds a listener for an application event that will only be execuded once: the first
+     * time the event is triggered.
+     *
+     * @param eventName  The name of the event to listen for.
+     * @param listener   The listener function.
+     * @returns A function to unsubscribe the listener.
+     * @template EventName  The name of the event, to match the type of the listener
+     *                      function.
+     */
+    once<EventName extends JimpexEventNameLike>(eventName: EventName, listener: JimpexEventListener<EventName>): () => boolean;
+    /**
+     * Based on the application options, it returns wheter the application is healthy or
+     * not.
+     */
+    isHealthy(): ReturnType<JimpexHealthCheckFn>;
+    /**
+     * This method is like a "lifecycle method", it gets executed on the constructor right
+     * before the "boot step". The idea is for the method to be a helper when the
+     * application is defined by subclassing {@link Jimpex}: the application could register
+     * all important services here and the routes on boot, then, if the implementation needs
+     * to access or overwrite a something, it can send `boot: false`, access/register what
+     * it needs, and then call `boot()`. That would be impossible for an application without
+     * overwriting the constructor and the boot functionality.
+     */
+    protected _init(): void;
+    /**
+     * It generates overwrites for the application options when it gets created. This method
+     * is a helper for when the application is defined by subclassing {@link Jimpex}: It's
+     * highly probable that if the application needs to change the default options, it would
+     * want to do it right from the class, instead of having to do it on every
+     * implementation. A way to do it would be overwriting the constructor and calling
+     * `super` with the custom overwrites, but this method exists so that won't be
+     * necessary: when creating the `options`, the constructor will merge the result of this
+     * method on top of the default ones.
+     */
+    protected _initOptions(): DeepPartial<JimpexOptions>;
+    /**
+     * Registers the "core services" on the container: logger, events, utils, etc.
+     */
+    protected _setupCoreServices(): void;
+    /**
+     * Configures the Express application based on the class options.
+     */
+    protected _setupExpress(): void;
+    /**
+     * Adds a static folder to the application.
+     *
+     * @param route   The route to add the folder to.
+     * @param folder  The path to the folder in the file system. If not defined, it will
+     *                be use the same value as `route`. The path could be relative to the
+     *                project root, or where the application executable is located,
+     *                depending on the value of the `onHome` parameter.
+     * @param onHome  If `true`, the path to the folder will be relative to the project
+     *                root. If `false`, it will be relative to where the application
+     *                executable is located.
+     */
+    protected _addStaticsFolder(route: string, folder?: string, onHome?: boolean): void;
+    /**
+     * This helper method validates the `path` options in order to register the `app`
+     * location in the `pathUtils` service. The `app` location should be the path to where
+     * the application executable is located, but due to how ESM works, we can't infer it
+     * from the `module` object, so we need either recieved as the `appPath` setting, or try
+     * to get it from the parent module.
+     *
+     * @throws If the method should use the path from the parent module, but can't find
+     *         it.
+     */
+    protected _configurePath(): void;
+    /**
+     * Setups the configuration service. The new configuration service requires async calls
+     * in order to load the configuration files (as it uses `import` instead of `require`),
+     * so it can't be instantiated as the other services.
+     * This method is called just before starting the application.
+     */
+    protected _setupConfig(): Promise<void>;
+    /**
+     * Processes the resources from the mount queue (added with {@link Jimpex.mount} and
+     * {@link Jimpex.use}), and adds them to the Express application.
+     */
+    protected _mountResources(): void;
+    /**
+     * Emits an event using the `events` service.
+     *
+     * @param name     The name of the event to emit.
+     * @param payload  The event payload.
+     * @template EventName  The literal name of the event, to type the event payload.
+     */
+    protected _emitEvent<EventName extends JimpexEventName>(name: EventName, payload: JimpexEventPayload<EventName>): void;
+    /**
+     * Sends a target object to a list of reducer events so they can modify or replace it.
+     *
+     * @param name     The name of the event to use.
+     * @param target   The object to reduce with the event.
+     * @param payload  Extra context for the listeners.
+     */
+    protected _reduceWithEvent<EventName extends JimpexReducerEventName>(name: EventName, target: JimpexReducerEventTarget<EventName>, payload: JimpexReducerEventPayload<EventName>): JimpexReducerEventTarget<EventName>;
+    /**
+     * Loads the contents of a dictionary of credentials files that need to be used to
+     * configure HTTPS.
+     *
+     * @param credentialsInfo  The dictionary where the keys are the type of credentials
+     *                         (`ca`, `cert`, `key`) and the values are the paths to the
+     *                         files.
+     * @param onHome           If this is `true`, the path of the files will be relative
+     *                         to the project root. If it is `false`, it will be relative
+     *                         to where the application executable is located.
+     * @returns
+     */
+    protected _loadCredentials(credentialsInfo: JimpexHTTPSCredentials, onHome?: boolean): Promise<JimpexHTTPSCredentials>;
+    /**
+     * Validates the configuration and chooses the server the application needs to use: If
+     * HTTP2 is enabled, it will use Spdy; if HTTPS is enabled but HTTP is not, it will use
+     * the native HTTPS server; otherwise, it will be just the Express instance.
+     *
+     * @returns {Server}
+     * @throws {Error} If HTTP2 is enabled but HTTPS is not.
+     * @throws {Error} If HTTPS is enabled but there's no `https.credentials` object.
+     * @throws {Error} If HTTPS is enabled and no creadentials are found.
+     * @access protected
+     * @ignore
+     */
+    protected _createServer(): Promise<JimpexServer>;
+}
+/**
+ * Shorthand for `new Jimpex()`.
+ *
+ * @param args  The same parameters as the {@link Jimpex} constructor.
+ * @returns A new instance of {@link Jimpex}.
+ * @group Jimpex
+ */
+declare const jimpex: (options?: DeepPartial<JimpexOptions> | undefined, config?: unknown) => Jimpex;
+
+export { MiddlewareProvider as $, Providers as A, ProviderLike as B, ControllerConnectFn as C, controller as D, EventPayload as E, ControllerCreatorFn as F, controllerCreator as G, Controller as H, ControllerCreator as I, Jimpex as J, ControllerProviderRegisterFn as K, controllerProvider as L, ControllerProviderCreatorFn as M, controllerProviderCreator as N, ControllerProvider as O, ProviderRegisterFn as P, ControllerProviderCreator as Q, MiddlewareConnectFn as R, middleware as S, MiddlewareCreatorFn as T, middlewareCreator as U, Middleware as V, MiddlewareCreator as W, MiddlewareProviderRegisterFn as X, middlewareProvider as Y, MiddlewareProviderCreatorFn as Z, middlewareProviderCreator as _, JimpexEvents as a, MiddlewareProviderCreator as a0, MiddlewareLike as a1, ControllerLike as a2, JimpexEventName as b, JimpexEventPayload as c, JimpexReducerEventTargets as d, JimpexReducerEventPayloads as e, JimpexReducerEventName as f, JimpexReducerEventTarget as g, JimpexReducerEventPayload as h, JimpexEventNameLike as i, jimpex as j, JimpexEventListener as k, Events as l, JimpexConfigOptions as m, JimpexStaticsOptions as n, JimpexExpressOptions as o, JimpexPathOptions as p, JimpexServicesOptions as q, JimpexHealthStatus as r, JimpexHealthCheckFn as s, JimpexOptions as t, JimpexStartCallback as u, provider as v, providerCreator as w, providers as x, Provider as y, ProviderCreator as z };