Class Jimpex

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.

Todo

Implement helmet.

Hierarchy

Jimple
- Jimpex

Constructors

constructor

new Jimpex(options?: DeepPartial<JimpexOptions>, config?: unknown): Jimpex
Parameters
- options: DeepPartial<JimpexOptions> = {}
  Preferences to customize the application.
- config: unknown = {}
  The default settings for the configuration service. It's a short-circuit for options.config.default
Returns Jimpex
Overrides Jimple.constructor
- Defined in src/app/jimpex.ts:109

Properties

`Protected`_configReady

_configReady: boolean = false

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`_controlledRoutes

_controlledRoutes: string[] = []

A list with all the top routes controlled by the application. Every time a controller is mounted, its route will be added here.

`Protected`_express

_express: Express

The Express application Jimpex uses under the hood.

`Protected` `Optional`_instance

_instance?: JimpexServerInstance

The instance of the server that is listening for requests.

`Protected`_mountQueue

_mountQueue: ((server: Express) => void)[] = []

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`_options

_options: JimpexOptions

The customization settings for the application.

`Protected` `Optional`_server

_server?: JimpexServer

A reference to the actual 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.

Accessors

eventsHub

get eventsHub(): EventsHub
Gets the events service.

Returns EventsHub
- Defined in src/app/jimpex.ts:368

express

get express(): Express
The Express application Jimpex uses under the hood.

Returns Express
- Defined in src/app/jimpex.ts:350

instance

get instance(): JimpexServerInstance | undefined
The server instance that gets created when the app is started.

Returns JimpexServerInstance | undefined
- Defined in src/app/jimpex.ts:356

logger

get logger(): SimpleLogger
The logger service.

Returns SimpleLogger
- Defined in src/app/jimpex.ts:344

options

get options(): DeepReadonly<JimpexOptions>
The application customization options.

Returns DeepReadonly<JimpexOptions>
- Defined in src/app/jimpex.ts:362

routes

get routes(): string[]
A list of the routes that have controllers mounted on them.

Returns string[]
- Defined in src/app/jimpex.ts:374

Methods

`Protected`_addStaticsFolder

_addStaticsFolder(route: string, folder?: string, onHome?: boolean): void
Adds a static folder to the application.
Parameters
- route: string
  The route to add the folder to.
- folder: string = ''
  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.
- onHome: boolean = false
  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.
Returns void
- Defined in src/app/jimpex.ts:515

`Protected`_configurePath

_configurePath(): 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 received as the appPath setting, or try to get it from the parent module.

Returns void
Throws
If the method should use the path from the parent module, but can't find it.
- Defined in src/app/jimpex.ts:539

`Protected`_emitEvent

_emitEvent<EventName extends keyof JimpexEvents>(
name: EventName,
payload: JimpexEventPayload<EventName>,
): void
Emits an event using the events service.
Type Parameters
- EventName extends keyof JimpexEvents
  The literal name of the event, to type the event payload.
Parameters
- name: EventName
  The name of the event to emit.
- payload: JimpexEventPayload<EventName>
  The event payload.
Returns void
- Defined in src/app/jimpex.ts:639

`Protected`_init

_init(): void
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 sub-classing 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.

Returns void
- Defined in src/app/jimpex.ts:424

`Protected`_initOptions

_initOptions(): DeepPartial<JimpexOptions>
It generates overwrites for the application options when it gets created. This method is a helper for when the application is defined by sub-classing 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.

Returns DeepPartial<JimpexOptions>
- Defined in src/app/jimpex.ts:435

`Protected`_loadCredentials

_loadCredentials(
credentialsInfo: JimpexHTTPSCredentials,
onHome?: boolean,
): Promise<JimpexHTTPSCredentials>
Loads the contents of a dictionary of credentials files that need to be used to configure HTTPS.
Parameters
- credentialsInfo: JimpexHTTPSCredentials
  The dictionary where the keys are the type of credentials (ca, cert, key) and the values are the paths to the files.
- onHome: boolean = true
  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 Promise<JimpexHTTPSCredentials>
- Defined in src/app/jimpex.ts:671

`Protected`_loadESMModules

_loadESMModules(): Promise<void>
Loads the ESM modules that are needed by Jimpex. This is called just before the starting the application so they'll be available for all the services.

Returns Promise<void>
- Defined in src/app/jimpex.ts:616

`Protected`_mountResources

_mountResources(): void
Processes the resources from the mount queue (added with Jimpex.mount and Jimpex.use), and adds them to the Express application.

Returns void
- Defined in src/app/jimpex.ts:628

`Protected`_reduceWithEvent

_reduceWithEvent<EventName extends keyof JimpexReducerEventTargets>(
    name: EventName,
    target: JimpexReducerEventTarget<EventName>,
    payload: JimpexReducerEventPayload<EventName>,
): JimpexReducerEventTarget<EventName>
Sends a target object to a list of reducer events so they can modify or replace it.
Type Parameters
- EventName extends keyof JimpexReducerEventTargets
Parameters
- name: EventName
  The name of the event to use.
- target: JimpexReducerEventTarget<EventName>
  The object to reduce with the event.
- payload: JimpexReducerEventPayload<EventName>
  Extra context for the listeners.
Returns JimpexReducerEventTarget<EventName>
- Defined in src/app/jimpex.ts:652

`Protected`_setupConfig

_setupConfig(): Promise<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.

Returns Promise<void>
- Defined in src/app/jimpex.ts:577

`Protected`_setupCoreServices

_setupCoreServices(): void
Registers the "core services" on the container: logger, events, utils, etc.

Returns void
- Defined in src/app/jimpex.ts:441

`Protected`_setupExpress

_setupExpress(): void
Configures the Express application based on the class options.

Returns void
- Defined in src/app/jimpex.ts:462

boot

boot(): void
This is where the app would register all its specific services, middlewares and controllers.

Returns void
- Defined in src/app/jimpex.ts:167

disableTLSValidation

disableTLSValidation(): void
Disables the server TLS validation. Meant to be used for development purposes.

Returns void
- Defined in src/app/jimpex.ts:171

getConfig

getConfig(): SimpleConfig
Returns SimpleConfig
- Defined in src/app/jimpex.ts:310
getConfig<T = unknown>(setting: string | string[], asArray?: boolean): T
Type Parameters
- T = unknown
Parameters
- setting: string | string[]
- OptionalasArray: boolean
Returns T
- Defined in src/app/jimpex.ts:311

getRouter

getRouter(): Router
Creates a new router instance.

Returns Router
- Defined in src/app/jimpex.ts:338

isHealthy

isHealthy(): Promise<JimpexHealthStatus>
Based on the application options, it returns whether the application is healthy or not.

Returns Promise<JimpexHealthStatus>
- Defined in src/app/jimpex.ts:412

listen

listen(
port?: number,
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.
Parameters
- Optionalport: number
  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.
- OptionalonStart: JimpexStartCallback
  A callback function to be called when the server starts.
Returns Promise<JimpexServerInstance>
The server instance.
- Defined in src/app/jimpex.ts:215

mount

mount(route: string, controller: ControllerLike): void
Mounts a route controller or a middleware into a server routes.
Parameters
- route: string
  The route for the controller/middleware.
- controller: ControllerLike
  The controller/middleware resource to be mounted.
Returns void
- Defined in src/app/jimpex.ts:243

on

on<EventName extends JimpexEventNameLike>(
eventName: EventName,
listener: JimpexEventListener<EventName>,
): () => boolean
Adds a listener for an application event.
Type Parameters
- EventName extends JimpexEventNameLike
  The name of the event, to match the type of the listener function.
Parameters
- eventName: EventName
  The name of the event to listen for.
- listener: JimpexEventListener<EventName>
  The listener function.
Returns () => boolean
A function to unsubscribe the listener.
- Defined in src/app/jimpex.ts:386

once

once<EventName extends JimpexEventNameLike>(
eventName: EventName,
listener: JimpexEventListener<EventName>,
): () => boolean
Adds a listener for an application event that will only be executed once: the first time the event is triggered.
Type Parameters
- EventName extends JimpexEventNameLike
  The name of the event, to match the type of the listener function.
Parameters
- eventName: EventName
  The name of the event to listen for.
- listener: JimpexEventListener<EventName>
  The listener function.
Returns () => boolean
A function to unsubscribe the listener.
- Defined in src/app/jimpex.ts:402

start

start(onStart?: JimpexStartCallback): Promise<JimpexServerInstance>
Starts the app server.
Parameters
- OptionalonStart: JimpexStartCallback
  A callback function to be called when the server actually starts.
Returns Promise<JimpexServerInstance>
The server instance.
- Defined in src/app/jimpex.ts:182

stop

stop(): void
Stops the server instance.

Returns void
- Defined in src/app/jimpex.ts:230

use

use(middleware: MiddlewareLike): void
Adds a global middleware to the application.
Parameters
- middleware: MiddlewareLike
  The middleware resource to be added.
Returns void
- Defined in src/app/jimpex.ts:283

Class Jimpex

Todo

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Jimpex

Properties

Protected_configReady

Protected_controlledRoutes

Protected_express

Protected Optional_instance

Protected_mountQueue

Protected_options

Protected Optional_server

Accessors

eventsHub

Returns EventsHub

express

Returns Express

instance

Returns JimpexServerInstance | undefined

logger

Returns SimpleLogger

options

Returns DeepReadonly<JimpexOptions>

routes

Returns string[]

Methods

Protected_addStaticsFolder

Parameters

Returns void

Protected_configurePath

Returns void

Throws

Protected_emitEvent

Type Parameters

Parameters

Returns void

Protected_init

Returns void

Protected_initOptions

Returns DeepPartial<JimpexOptions>

Protected_loadCredentials

Parameters

Returns Promise<JimpexHTTPSCredentials>

Protected_loadESMModules

Returns Promise<void>

Protected_mountResources

Returns void

Protected_reduceWithEvent

Type Parameters

Parameters

Returns JimpexReducerEventTarget<EventName>

Protected_setupConfig

Returns Promise<void>

Protected_setupCoreServices

Returns void

Protected_setupExpress

Returns void

boot

Returns void

disableTLSValidation

Returns void

getConfig

Returns SimpleConfig

Type Parameters

Parameters

Returns T

getRouter

Returns Router

isHealthy

Returns Promise<JimpexHealthStatus>

listen

Parameters

`Protected`_configReady

`Protected`_controlledRoutes

`Protected`_express

`Protected` `Optional`_instance

`Protected`_mountQueue

`Protected`_options

`Protected` `Optional`_server

`Protected`_addStaticsFolder

`Protected`_configurePath

`Protected`_emitEvent

`Protected`_init

`Protected`_initOptions

`Protected`_loadCredentials

`Protected`_loadESMModules

`Protected`_mountResources

`Protected`_reduceWithEvent

`Protected`_setupConfig

`Protected`_setupCoreServices

`Protected`_setupExpress