jimpex 7.0.1 → 8.0.0

package/README.md

@@ -2,148 +2,229 @@
 
 [![GitHub Workflow Status (main)](https://img.shields.io/github/workflow/status/homer0/jimpex/Test/main?style=flat-square)](https://github.com/homer0/jimpex/actions?query=workflow%3ATest)
 [![Coveralls GitHub](https://img.shields.io/coveralls/github/homer0/jimpex.svg?style=flat-square)](https://coveralls.io/github/homer0/jimpex?branch=main)
-[![David](https://img.shields.io/david/homer0/jimpex.svg?style=flat-square)](https://david-dm.org/homer0/jimpex)
-[![David](https://img.shields.io/david/dev/homer0/jimpex.svg?style=flat-square)](https://david-dm.org/homer0/jimpex)
+![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/jimpex)
 
 Express as dependency injection container.
 
-Jimpex is an implementation of [Express](https://expressjs.com), one of the most popular web frameworks for Node, using [Jimple](https://github.com/fjorgemota/jimple), a Javascript port of [Pimple](https://pimple.symfony.com) dependency injection container.
+Jimpex is an implementation of [Express](https://expressjs.com), one of the most popular web frameworks for Node, using [Jimple](https://github.com/fjorgemota/jimple), a Javascript port of [Pimple](https://github.com/silexphp/Pimple) dependency injection container.
+
+> ⚠️ If you want to upgrade to v8, please read the [migration guide](https://github.com/homer0/jimpex/blob/main/documents/migration-v8.md).
+
+- [🍿 Usage](#🍿-usage)
+  - [🎨 Creating your app](#🎨-creating-your-app)
+  - [🤖 Boot](#🤖-boot)
+  - [⚙️ Options and configuration](#⚙️-options-and-configuration)
+    - [Options](#options)
+    - [Configuration](#configuration)
+  - [🚀 Starting your app](#🚀-starting-the-app)
+  - [✅ HTTPS](#✅-https)
+    - [HTTP2](#http2)
+  - [🛠 Services](#🛠-services)
+    - [Configurable services](#configurable-services)
+  - [🚦 Controllers](#🚦-controller)
+    - [Configurable controllers](#configurable-controllers)
+    - [Controllers with services](#controllers-with-services)
+  - [⚡️ Middlewares](#⚡️-middlewares)
+    - [Configurable middlewares](#configurable-middlewares)
+    - [Middlewares with services](#middlewares-with-services)
+- [💪 TypeScript](#💪-typescript)
+- [🤞 Examples](#🤞-examples)
+- [🤘 Development](#development)
+  - [NPM scripts](#npm-scripts)
+  - [Repository hooks](#repository-hooks)
+  - [Commits conventions](#commits-conventions)
+  - [Releases](#releases)
+  - [Testing](#testing)
+  - [Code linting and formatting](#code-linting-and-formatting)
+  - [Documentation](#documentation)
+- [👀 Motivation](#👀-motivation)
+
+## 🍿 Usage
+
+### 🎨 Creating your app
+
+```ts
+import { jimpex } from 'jimpex';
 
-## Usage
-
-### Creating your app
+const app = jimpex();
+app.set('something', () => new Something());
+app.mount('/hello', (req, res) => res.send('Hello World!'));
+app.listen(2509, () => {
+  console.log('The app is running!');
+});
+```
 
-You have two ways of creating an app: by defining a class and using the `boot` method to add all your services and customizations; or with the `jimpex` function:
+That's all: you create the app, register/set your dependencies, and mount your routes.
 
-#### Class
+Alternatively, you could import the class, subclass it, and make use of the "life cycle" methods to configure it:
 
-```js
-const { Jimpex } = require('jimpex');
-// OR import { Jimpex } from 'jimpex/esm';
+```ts
+import { Jimpex } from 'jimpex';
 
 class MyApp extends Jimpex {
   boot() {
-    // Do all your custom stuff...
-    this.register(...);
-    this.mount(...);
+    this.set('something', () => new Something());
+    app.mount('/hello', (req, res) => res.send('Hello World!'));
   }
 }
-```
-
-The class constructor has two parameters:
 
-```js
-(options = {}, configuration = null) => Jimpex
+const app = new MyApp();
+app.listen(2509, () => {
+  console.log('The app is running!');
+});
 ```
 
-1. The options to customize the application. You can read about them on the [Jimpex Options documentation](./documents/options.md).
-2. The default configuration, in case you don't want Jimpex to try loading an external configuration file.
+### 🤖 Boot
 
-When definining the application as a class, there are two _protected_ (helper) methods that you can use to overwrite the options and even define priority resources that the implementation could access/overwrite if they manually handle the "boot":
+The `boot` method gets called right from the constructor, when the `boot` option is set to `true` (its default value), and the idea is for you to use it to add all your customizations (as seen in the example above).
 
-##### Adding resources that can be overriden
+Like `boot`, there's another "helper method" that you can use to register your dependencies: `_init`; the difference is that `_init` gets called from the constructor before the `boot` options gets validated. This allows you to create scenarios in which you could register some resources on `_init`, disable the call to `boot`, overwrite what you set on `_init`, and manually call `boot`:
 
-```js
+```ts
 class MyApp extends Jimpex {
   _init() {
-    this.set('env', 'PROD');
+    this.set('message', 'Hello Charo!');
+  }
+
+  boot() {
+    app.mount('/hello', (req, res) => res.send(this.get('message')));
   }
 }
+
+const app = new MyApp({ boot: false });
+app.set('message', 'Hello Pili!');
+app.boot();
 ```
 
-The `_init` method is called before `boot` gets validated, so even if the constructor option `boot` is set to `false`, `_init` will be called.
+Now, this may look like an unnecessary feature, but if you consider the possiblity of different entry points based on environment, maybe to enable debugging tools on dev, this becomes really useful.
 
-Now, let's say you want to execute the application on a development environment; instead of adding `if`s to check the environment, you could do something like this on your development file:
+### ⚙️ Options and configuration
 
-```js
-const MyApp = require('...');
+On Jimpex, you have two sets of "settings": the options, which are in the code when you create the application; and the configuration, which may be related to the environment in which the application is running.
 
-const app = new MyApp({ boot: false });
-app.set('env', 'DEV');
-app.boot();
-...
+#### Options
+
+You can read all about the different options in [its own documentation](https://github.com/homer0/jimpex/blob/main/documents/options.md), but they're more related to the application capabilities. For example:
+
+- Whether or not to call `boot`.
+- Whether or not Express should remove the `x-powered-by` header.
+- Which env var to check for the environment configuration (you'll see more about this in a sec).
+
+And depending on how you defined your application, you have two ways to customize the options.
+
+First, if you used the function, you can just send them as a parameter:
+
+```ts
+import { jimpex } from 'jimpex';
+
+const app = jimpex({
+  boot: false,
+  express: {
+    disableXPoweredBy: true,
+  },
+  config: {
+    environmentVariable: 'NODE_ENV',
+  },
+});
 ```
 
-##### Modifying the options
+And yes, you could also use this approach with the class, as both the function and the class constructor share the same parameters, but if you want to already define your options inside your subclass, there's a _protected_ helper for it: `_initOptions`.
+
+```ts
+import { Jimpex } from 'jimpex';
 
-```js
 class MyApp extends Jimpex {
   _initOptions() {
     return {
-      configuration: {
-        loadFromEnvironment: false,
+      boot: false,
+      express: {
+        disableXPoweredBy: true,
+      },
+      config: {
+        environmentVariable: 'NODE_ENV',
       },
     };
   }
 }
 ```
 
-If you are subclassing `Jimpex`, it highly probable that if the default options need to be changed, you would want to do it from within the class, rather than forcing all implementations to do it.
+The advantage of `_initOptions` is not only that you don't need to overwrite the constructor, but that you can still receive the options from the constructor, and Jimpex will automatically deep merge the ones on `_initOptions` on top of them.
 
-One way would be to overwrite the constructor and call `super` with the customizations, the other would be using this method: The constructor automatically merges the result of `_initOptions` on top of the defaults so you won't have to override anything.
+#### Configuration
 
-There are a lot of different options, so I would recommend reading the [Jimpex Options documentation](./documents/options.md).
+These are the settings that are more related to the runtime, and that can change depending on the environment. The most basic example of a "configuration setting" would be the port in which the application runs: you could run it on local env in 3000, and on production in 80 (or 443).
 
-#### Function
+While the configuration is more easily managed with external (config) files, you could also send it in the options:
 
-```js
-const { jimpex } = require('jimpex');
-// OR import { jimpex } from 'jimpex/esm';
+```ts
+import { jimpex } from 'jimpex';
 
-const app = jimpex();
-app.register(...);
-app.mount(...);
-```
-
-The idea of the function is to be used on scenarios where a class may be too much or you have a single implementation, like on a lamda serverless.
+const app = jimpex({
+  config: {
+    default: {
+      port: 3000,
+    },
+  },
+});
 
-The function has almost the same signature as the class constructor:
+// or
 
-```js
-(options = {}, configuration = null) => Jimpex
+const app2 = jimpex(
+  { someOption: false },
+  {
+    port: 3000,
+  },
+);
 ```
 
-1. The options to customize the application. You can read about them on the [Jimpex Options documentation](./documents/options.md).
-2. The default configuration. The big difference here is that, even if you send `null`, Jimpex won't try to load an external configuration file.
+You can use the option `config.default`, or just the second parameter of both the function and the class.
 
-#### App configuration
+> ⚠️ If you don't configure the `port` and call `start()`, the application will throw an error.
 
-Jimpex, by default, depends on external configuration files and, as a base configuration, it will try to load `./config/app/app.config.js`. Of course this is extremely configurable through the [Jimpex Options](./documents/options.md).
+That's the basic usage, but as mentioned before, the configuration is more easily managed with external files: when loading the configuration, which happens when the server starts, it will try to look for a file `config/app.config.js`, and if it exists, it will set whatever it (default) exports as the configuration.
 
-A configuration file is just a Javascript file that exports an Object, for example:
+So, we could write the configuration from the example above and use it like this:
 
-```js
-module.exports = {
-  port: 2509,
+```ts
+// config/app.config.js
+export default {
+  port: 3000,
 };
-```
 
-> If that's how you default configuration file looks like, the app will run on the port `2509`.
+// src/index.js
+import { jimpex } from 'jimpex';
 
-If you don't want the application to load an external file, you could use the second parameter of either the class or the function:
-
-```js
-new MyApp({ ... }, { port: 2509 });
-// OR
-jimpex({ ... }, { port: 2509 });
+const app = jimpex();
+app.start();
 ```
 
-Now, to access the configuration service, you just call `appConfiguration`:
+Now, the really great feature about the config files, is that you could extend them and manage which one gets loaded depending on the environment: When loading the configuration, Jimpex will check the value of the environment variable `CONFIG` and try to load a config file `config/app.config.${CONFIG}.js`. For example:
 
-```js
-const config = app.get('appConfiguration');
+You could have the default configuration with the port set to `3000`, and a "staging" configuration with the port set to `80`.
+
+```ts
+// config/app.config.js
+export default {
+  port: 3000,
+};
+
+// config/app.config.staging.js
+export default {
+  port: 80,
+};
 ```
 
-Then you can read its settings using `.get(setting)`:
+And if `CONFIG` is set to `staging` when the application starts, the staging configuration will be loaded.
 
-```js
-console.log(config.get('port'));
-// Will log 2509
+Finally, you can access the configuration settings with the `config` service:
+
+```ts
+const port = app.get('config').get('port');
 ```
 
-To get more information about how the `appConfiguration` service works, you can check [its documentation on the wootils repository](https://github.com/homer0/wootils/blob/main/documents/node/appConfiguration.md).
+> You can read more about the options for the configuration service in the [options documentation](https://github.com/homer0/jimpex/blob/main/documents/options.md), but it's basically an implementation of [`@homer0/simple-config`](https://www.npmjs.com/package/@homer0/simple-config).
 
-#### Starting the application
+### 🚀 Starting the app
 
 ```js
 app.listen(2509, () => {
@@ -168,46 +249,39 @@ app.stop();
 // Done, the app is not longer running.
 ```
 
-### HTTPS && HTTP2
+### ✅ HTTPS
 
-To enable HTTPS on your application, just like for the `port`, you need to create a `https` key on your configuration, "enable it" and provide the paths for the credentials:
+HTTPS is enabled via configuration, not options, just like the application port:
 
-```js
-module.exports = {
+```ts
+// config/app.config.js
+export default {
   port: 2509,
   https: {
     enabled: true,
     credentials: {
-      cert: 'cert-file',
-      key: 'key-file',
+      cert: '...cert-file',
+      key: '...key-file',
     },
   },
 };
 ```
 
-By default, Jimpex will look for those files relative to the project root directory, but you can change so it will look on a path relative to the directory where the application executable is located:
+By default, Jimpex will look for those files relative to the project root directory, but you can change so it will look on a path relative to the directory where the application executable is located by setting `https.credentials.onHome` to `false`.
 
-```js
-{
-  // ...
-  credentials: {
-    onHome: false,
-    cert: 'cert-file',
-    key: 'key-file',
-  },
-}
-```
+#### HTTP2
 
-Also, once you have HTTPS enabled, you can also enable [HTTP/2](https://en.wikipedia.org/wiki/HTTP/2):
+To enable [HTTP/2](https://en.wikipedia.org/wiki/HTTP/2), you MUST enable HTTPS first, and then just add a flag in the configuration:
 
-```js
-module.exports = {
+```ts
+// config/app.config.js
+export default {
   port: 2509,
   https: {
     enabled: true,
     credentials: {
-      cert: 'cert-file',
-      key: 'key-file',
+      cert: '...cert-file',
+      key: '...key-file',
     },
   },
   http2: {
@@ -216,543 +290,481 @@ module.exports = {
 };
 ```
 
-> **Important:** HTTPS MUST BE enabled in order to use HTTP/2.
-
-Under the hood, Jimpex uses [Spdy](https://yarnpkg.com/package/spdy) for the HTTP/2 support, and Spdy has custom options you can send in order to define how it will work; you can send options to Spdy by adding a `spdy` key inside the `http2` object:
+Under the hood, Jimpex uses [Spdy](https://npmjs.com/package/spdy) for the HTTP/2 support, and Spdy has custom options you can send in order to define how it will work; you can send options to Spdy by adding a `spdy` key inside the `http2` object:
 
-```js
-{
-  // ...
+```ts
+// config/app.config.js
+export default {
+  port: 2509,
+  https: {
+    enabled: true,
+    credentials: {
+      cert: '...cert-file',
+      key: '...key-file',
+    },
+  },
   http2: {
     enabled: true,
     spdy: {
       'x-forwarded-for': '127.0.0.1',
     },
   },
-}
+};
 ```
 
-### Defining a service
+### 🛠 Services
 
-To define a service and its provider, you would write your service as a `class` or a `function` and then wrap it on the `provider` function Jimpex exports:
+This is the most-core functionality that Jimple, and Jimpex, provide. You can easily create providers for services/resources that you want to use in your application:
 
-```js
-const { provider } = require('jimpex');
+```ts
+// src/my-service.js
+import { provider } from 'jimpex';
 
-// Create your service
-class MyService {
-  constructor(depOne, depTwo);
+export class MyService {
+  constructor(config) {
+    this.config = config;
+  }
+
+  getMeThePort() {
+    return this.config.get('port');
+  }
 }
 
-// Define the provider
-const myService = provider((app) => {
-  app.set('myService', () => new MyService(
-    app.get('depOne'),
-    app.get('depTwo')
-  ));
+export const myService = provider((app) => {
+  app.set('myService', () => new MyService(app.get('config')));
 });
-
-// Export the service and its provider
-module.exports.MyService = MyService;
-module.exports.myService = myService;
 ```
 
-> 1. You could just export the provider, but I believe is a good practice to export both in case another part of your app wants to extend the class and overwrite the service on the container.
-> 2. That why of using `module.expots` is so the class can be imported on JSDoc comments.
+> You could just export the provider, but I believe is a good practice to export both, in case another part of your app wants to extend the class and overwrite the service on the container.
 
-Then, on you app, you would simple `register` the provider:
+The, on the app, you would simple `register` the provider:
 
-```js
-const { Jimpex } = require('jimpex');
-const { myService } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { myService } from './my-service';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.register(myService);
   }
 }
 ```
 
-Done, your service is now available.
+Done, your service is now available in the container.
 
-#### Defining a configurable service
+Jimpex already comes with a few built-in service providers ready to be used, and you can read about them on the [services document](https://github.com/homer0/jimpex/blob/main/documents/services.md).
 
-In case you want to create a service that could accept custom setting when instantiated, you can use a _"provider creator"_:
+##### Configurable services
 
-```js
-const { providerCreator } = require('jimpex');
+Since the version of Jimple that Jimpex uses under the hood is [`@homer0/jimple`](https://www.npmjs.com/package/@homer0/jimple), my custom "fork", you can also create "configureable providers":
+
+```ts
+// src/my-service.js
+import { providerCreator } from 'jimpex';
+
+export class MyService {
+  constructor(config) {
+    this.config = config;
+  }
 
-// Create your service
-class MyService {
-  constructor(depOne, depTwo, options = {});
+  getMeThePort() {
+    return this.config.get('port');
+  }
 }
 
-// Define the provider
-const myService = providerCreator((options) => (app) => {
-  app.set('myService', () => new MyService(
-    app.get('depOne'),
-    app.get('depTwo'),
-    settings
-  ));
+export const myService = providerCreator((options = {}) => (app) => {
+  const { serviceName = 'myService' } = options;
+  app.set(serviceName, () => new MyService(app.get('config')));
 });
-
-// Export the service and its provider
-module.exports = {
-  MyService,
-  myService,
-};
 ```
 
-The special behavior the creators have, is that you can call them as a function, sending the settings, or just use them on the `register`, so **it's very important that the settings must be optional**:
+If you are thinking this is just a HOF, you are wrong. The "magic" of the creator version is that it can be used as a provider and/or as a function:
 
-```js
-const { Jimpex } = require('jimpex');
-const { myService } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { myService } from './my-service';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.register(myService);
-    // or
-    this.register(myService({ ... }));
+    this.register(
+      myService({
+        serviceName: 'myService2',
+      }),
+    );
   }
 }
 ```
 
-### Adding a controller
+Check the README of [`@homer0/jimple`](https://www.npmjs.com/package/@homer0/jimple) for more information about providers.
 
-To add controller you need to use the `controller` function and return a list of routes:
+### 🚦 Controllers
 
-```js
-const { controller } = require('jimpex');
+To define a controller, you just need to use the `controller` wrapper (like `provider`), modify a router, and return it:
+
+```ts
+// src/health-controller.js
+import { controller } from 'jimpex';
 
 // (Optional) Define a class to organize your route handlers.
-class HealthController {
+export class HealthController {
   health() {
     return (req, res) => {
       res.write('Everything works!');
+      res.end();
     };
   }
 }
 
 // Define the controller
-const healthController = controller((app) => {
+export const healthController = controller((app) => {
   const ctrl = new HealthController();
-  // Get the router service
+  // Get an instance of the router service
   const router = app.get('router');
   // Return the router with all the routes
-  return router
-  .get('/', ctrl.health())
-  .get(...);
+  return router.get('/', ctrl.health()).get('/health', (req, res) => {
+    res.write('Everything works!');
+    res.end();
+  });
 });
-
-// Export the controller class and the controller itself
-module.exports.HealthController = HealthController;
-module.exports.healthController = healthController;
 ```
 
-> 1. You could just export the controller, but I believe is a good practice to export both in case another part of your app wants to extend the class and mount a new route withs its inherit functionalities.
-> 2. That why of using `module.expots` is so the class can be imported on JSDoc comments.
-> 3. The function inside the `controller` wrapper won't be called until the app is started. In case you are wondering about the lazy loading of the services that you may inject.
+> 1. You could just export the controller, but I believe is a good practice to export both, in case another part of your app wants to extend the class and mount a new route with its inherited functionalities.
+> 2. In case you are wondering about the lazy loading of the services that you may inject, the function inside the `controller` wrapper won't be called until the app is started.
 
 Then, on you app, you would `mount` the controller:
 
-```js
-const { Jimpex } = require('jimpex');
-const { healthController } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { healthController } from './health-controller';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.mount('/health', healthController);
   }
 }
 ```
 
-#### Defining a configurable controller
+Jimpex already comes with a few built-in controllers ready to be used, and you can read about them on the [controllers document](https://github.com/homer0/jimpex/blob/main/documents/controllers.md).
 
-Like with _"providers creators", you can define controllers that accept custom settings when
-instantiated, using a _"controller creator"_:
+#### Configurable controllers
 
-```js
-const { controllerCreator } = require('jimpex');
+The same as with the services, you can define controllers that accept custom options for the moment they are mounted:
 
-// (Optional) Define a class to organize your route handlers.
-class HealthController {
-  constructor(settings = {});
+```ts
+// src/health-controller.js
+import { controllerCreator } from 'jimpex';
 
+// (Optional) Define a class to organize your route handlers.
+export class HealthController {
   health() {
     return (req, res) => {
       res.write('Everything works!');
+      res.end();
     };
   }
 }
 
 // Define the controller
-const healthController = controllerCreator((settings) => (app) => {
-  const ctrl = new HealthController(settings);
-  // Get the router service
+export const healthController = controllerCreator((options = {}) => (app) => {
+  const ctrl = new HealthController();
+  // Get an instance of the router service
   const router = app.get('router');
+  // Read the custom options
+  const { altRoute = '/health' } = options;
+
   // Return the router with all the routes
-  return router
-  .get('/', ctrl.health())
-  .get(...);
+  return router.get('/', ctrl.health()).get(altRoute, (req, res) => {
+    res.write('Everything works!');
+    res.end();
+  });
 });
-
-// Export the controller class and the controller itself
-module.exports.HealthController = HealthController;
-module.exports.healthController = healthController;
 ```
 
-The special behavior the creators have, is that you can call them as a function, sending the settings, or just use them with `mount` as regular controllers; and since they can be used as regular controllers, **it's very important that the settings are optional**:
+And like with the provider creators, these can be used as a controller, or as a function:
 
-```js
-const { Jimpex } = require('jimpex');
-const { healthController } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { healthController } from './health-controller';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.mount('/health', healthController);
-    // or
-    this.mount('/health', healthController({ ... }));
+    this.mount(
+      '/hp',
+      healthController({
+        altRoute: '/status',
+      }),
+    );
   }
 }
 ```
 
-#### Defining a controller that registers a service
-
-If for some reason, your controller needs to register a service the rest of the container needs to have access to and you plan to do it on the `controller`/`controllerCreator` callback, you could end up messing with the _lazyness_ of the container: If a middleware or another controller tries to access the service and the controller that registers it is mounter after it, it will get an error as the service doesn't exist yet.
+#### Controllers with services
 
-To solve this issue, you can use a "controller provider":
+If for some reason, your controller needs to register a service that the rest of the container needs to have access to, and you plan to do it on the `controller`/`controllerCreator` callback, you could end up messing with the _lazyness_ of the container: If a middleware or another controller tries to access the service and the controller that registers it is mounted after it, it will get an error as the service _doesn't exist yet_.
 
-```js
-const { provider, controller } = require('jimpex');
+A way to solve this issue would be with a `provider`/`providerCreator`, mounting the controller:
 
-// (Optional) Define a class to organize your route handlers.
-class HealthController {
-  health() {
-    return (req, res) => {
-      res.write('Everything works!');
-    };
-  }
-}
+```ts
+// dont-do-this.js
+import { provider, controller } from 'jimpex';
 
-// Define the controller
-const healthController = provider(app) => {
-  // Register the controller as a service (or any other resource)
-  app.set('health', () => new HealthController());
-  return controller(() => {
-    // Get the controller as a service
-    const ctrl = app.get('health');
-    // Get the router service
-    const router = app.get('router');
-    // Return the router with all the routes
-    return router
-    .get('/', ctrl.health())
-    .get(...);
-  });
+export const wrong = provider((app) => {
+  app.set('wrong', () => new WrongService());
+  app.mount(
+    '/',
+    controller((app) => {
+      const wrong = app.get('wrong');
+      return router.get('/', wrong.doSomething());
+    }),
+  );
 });
-
-// Export the controller class and the controller itself
-module.exports.HealthController = HealthController;
-module.exports.healthController = healthController;
 ```
 
-And you would mount it just like any other contorller:
+The main problem with that approach is that you would have to `register` it as a provider, so the route for the controller would need to be defined inside the callback.
 
-```js
-const { Jimpex } = require('jimpex');
-const { healthController } = require('...');
+So, for this case, Jimpex has a special wrapper, which is very similar, but that it allows you to `mount` it:
 
-class MyApp extends Jimpex {
-  boot() {
-    ...
-    this.mount('/health', healthController);
-  }
-}
-```
+```ts
+// controller-provider.js
+import { controllerProvider, controller } from 'jimpex';
 
-And in the case you need a "creator", you could use a "provider creator" and return a controller:
+export const good = controllerProvider((app) => {
+  app.set('good', () => new GoodService());
 
-```js
-const healthController = providerCreator((settings) => (app) => {
-  // Register the controller as a service (or any other resource) and send the settings
-  app.set('health', () => new HealthController(settings));
-  return controller(() => {
-    // Get the controller as a service
-    const ctrl = app.get('health');
-    // Get the router service
-    const router = app.get('router');
-    // Return the router with all the routes
-    return router
-    .get('/', ctrl.health())
-    .get(...);
+  return controller((app) => {
+    const good = app.get('good');
+    return router.get('/', good.doSomething());
   });
 });
 ```
 
-### Adding a middleware
+The `controllerProvider` wrapper allows you to register something in the callback, and expects a wrapped `controller` to be returned. That way, you can `mount` it, and specify the root outside.
 
-To add a new middleware you need to use the `middleware` function and return a function:
+And like `provider`, and `controller`, there's also a `controllerProviderCreator`.
 
-```js
-const { middlware } = require('jimpex');
+### ⚡️ Middlewares
+
+To create a new middleware, you just need to use the `middleware` wrapper and return it:
+
+```ts
+// my-middleware.js
+import { middleware } from 'jimpex';
 
 // Define your middleware function (or class if it gets more complex)
-const greetingsMiddleware = () => (req, res, next) => {
-  console.log('Hello!');
+export const greetingsMiddleware = () => (req, res, next) => {
+  try {
+    res.write('Hello World!');
+    res.end();
+  } catch (err) {
+    next(err);
+  }
 };
 
 // Define the middleware
-const greetings = middleware(() => greetingsMiddleware());
-
-// Export the function and the middleware
-module.exports.greetingsMiddleware = greetingsMiddleware;
-module.exports.greetings = greetings;
+export const greetings = middleware(() => greetingsMiddleware());
 ```
 
-> 1. You could just export the provider, but I believe is a good practice to export both in case another part of your app wants to extend the class or use the function.
-> 2. That why of using `module.expots` is so the function can be imported on JSDoc comments.
+Then, on the app, you would `use` it:
 
-Then, on you app, you would `use` the controller:
-
-```js
-const { Jimpex } = require('jimpex');
-const { greetings } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { greetings } from './my-middleware';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.use(greetings);
   }
 }
 ```
 
-#### Defining a configurable middleware
+Now, middlewares can also be `mount`ed in specific routes:
 
-Like with controllers and providers, you can also create a middleware that can accept settings when instantiated, with a _"middleware creator"_:
+```ts
+import { Jimpex } from 'jimpex';
+import { greetings } from './my-middleware';
 
-```js
-const { middlwareCreator } = require('jimpex');
-
-// Define your middleware function (or class if it gets more complex)
-const greetingsMiddleware = (message = 'Hello!') => (req, res, next) => {
-  console.log(message);
-};
-
-// Define the middleware
-const greetings = middlewareCreator((message) => greetingsMiddleware(message));
-
-// Export the function and the middleware
-module.exports.greetingsMiddleware = greetingsMiddleware;
-module.exports.greetings = greetings;
+class MyApp extends Jimpex {
+  boot() {
+    this.mount('/greetings', greetings);
+  }
+}
 ```
 
-The special behavior the creators have, is that you can call them as a function, sending the settings, or just register them with `use` as regular middlewares, so **it's very important that the settings must be optional**:
+And, if you don't need access to the container in the middleware definition, you could also `mount`/`use` it as a _raw_ Express' middleware:
 
-```js
-const { Jimpex } = require('jimpex');
-const { greetings } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+
+const greetingsMiddleware = (req, res, next) => {
+  try {
+    res.write('Hello World!');
+    res.end();
+  } catch (err) {
+    next(err);
+  }
+};
 
 class MyApp extends Jimpex {
   boot() {
-    ...
-    this.use(greetings);
+    this.use(greetingsMiddleware);
     // or
-    this.use(greetings('Howdy!'));
+    this.mount('/greetings', greetingsMiddleware);
   }
 }
 ```
 
-#### Defining a middleware that registers a service
+Jimpex already comes with a few built-in middlewares ready to be used, and you can read about them on the [middlewares document](https://github.com/homer0/jimpex/blob/main/documents/middlewares.md).
 
-Just like the "controller provider", you can also create a "middleware provider", a middleware that also registers something on the contianer without messing with the _lazyness_ of the container:
+#### Configurable middlewares
 
-```js
-const { provider, middleware } = require('jimpex');
-// Define the class that will work as a service
-class Greeter {
-  // Add a method that could be used on its "service role"
-  greet() {
-    return 'Hello!';
-  }
-  // Add a method for the actual middleware
-  middleware() {
-    return (req, res, next) => {
-      console.log(this.greet());
-    };
+Just like the `controllerCreator` wrapper, you can also use the `middlewareCreator` wrapper to define middlewares that accept custom options:
+
+```ts
+// my-middleware.js
+import { middlwareCreator } from 'jimpex';
+
+// Define your middleware function (or class if it gets more complex)
+export const greetingsMiddleware = (message) => (req, res, next) => {
+  try {
+    res.write(message);
+    res.end();
+  } catch (err) {
+    next(err);
   }
-}
-// Define the provider
-const greetings = provider((app) => {
-  // Register the class as a service
-  app.set('greeter', () => new Greeter());
-  // Return the actual middleware
-  return middleware(() => app.get('greeter').middleware());
-})
+};
 
-// Export the class and the provider
-module.exports.greetingsMiddleware = greetingsMiddleware;
-module.exports.greetings = greetings;
+// Define the middleware
+export const greetings = middleware((options) => {
+  const { message = 'Hello Charo!' } = options;
+  return greetingsMiddleware(message);
+});
 ```
 
-And you would mount it just like any other contorller:
+And now you can use it as a middleware, or as a function that returns a middleware:
 
-```js
-const { Jimpex } = require('jimpex');
-const { greetings } = require('...');
+```ts
+import { Jimpex } from 'jimpex';
+import { greetings } from './my-middleware';
 
 class MyApp extends Jimpex {
   boot() {
-    ...
     this.use(greetings);
+    // or
+    this.mount(
+      '/greetings',
+      greetings({
+        message: 'Hello Pili!',
+      }),
+    );
   }
 }
 ```
 
-And in the case you need a "creator", you could use a "provider creator" and return a controller:
-
-```js
-const greetings = providerCreator((settings) => (app) => {
-  // Register the class as a service and send the settings
-  app.set('greeter', () => new Greeter(settings));
-  // Return the actual middleware
-  return middleware(() => app.get('greeter').middleware());
-});
-```
-
-### Proxy mode
-
-You can enable the "proxy mode" by setting the `proxy` option to `true` on either the function or the class and it allows you to access and register resources using dot notation:
-
-```js
-// Set the option
-const app = jimpex({ proxy: true });
+#### Middlewares with services
 
-app.myService = () => new MyService();
-// = app.set('myService', () => new MyService();
+If, for some reason, your middleware needs to register a service before being mounted, just like the `controllerProvider`, you have the `middlewareProvider` wrapper:
 
-app.myService.doSomething();
-// = app.get('myService').doSomething();
+```ts
+// middleware-provider.js
+import { middlewareProvider, middleware } from 'jimpex';
 
-doSomething(app.$myService);
-// = doSomething(app.try('myService'));
-```
+class MiddlewareService {
+  getMiddleware() {
+    return (req, res) => {
+      res.write('Everything works!');
+      res.end();
+    };
+  }
+}
 
-When using the class, as you would expect, the constructor would give you the original instance and then you would have to call `.ref()` to get either the proxy or the original (depending on the setting):
+export const middlewareService = middlewareProvider((app) => {
+  app.set('middlewareService', () => new MiddlewareService());
 
-```js
-const original = new Jimpex({ proxy: true });
-const app = original.ref();
+  return middleware((app) => {
+    const service = app.get('middlewareService');
+    return service.getMiddleware();
+  });
+});
 ```
 
-But for the function, what you get as return value is actually the call for `.ref()`, that's why the first example could use the proxy mode without calling it.
-
-Internally, when `proxy` is enabled, all providers, controllers and middlewares will receive the proxy instead of the original.
-
-## Built-in features
-
-Jimpex comes with a few services, middlewares and controllers that you can import and use on your app, some of them [are activated by default on the options](./documents/options.md), but others you have to implement manually:
+And finally, you also have `middlewareProviderCreator` to create a middleware that can register a service, with custom options.
 
-### Controllers
+## 💪 TypeScript
 
-- **Configuration:** Allows you to see and switch the current configuration. It can be enabled or disabled by using a setting on the configuration.
-- **Health:** Shows the version and name of the configuration, just to check the app is running.
-- **Statics:** It allows your app to server specific files from any directory, without having to use the `static` middleware.
-- **Gateway:** It allows you to automatically generate a set of routes that will make gateway requests to an specific API.
+After v8, Jimpex was completely rewritten in TypeScript, so you can use it with no problems in your TypeScript projects. For more information, please refer to the [TypeScript document](https://github.com/homer0/jimpex/blob/main/documents/typescript.md).
 
-[Read more about the built-in controllers](./documents/controllers.md)
+## 🤞 Examples
 
-### Middlewares
+You can find the example projects in the `example` directory. To run them, you can use the `npm run example` command. By default, it runs the `basic` example, but you can also specify the name of the example you want to run:
 
-- **Error handler:** Allows you to generate responses for errors and potentially hide uncaught exceptions under a generic message, unless it's disabled via configuration settings.
-- **Force HTTPS:** Redirect all incoming traffic from HTTP to HTTPS. It also allows you to set routes to ignore the redirection.
-- **HSTS header:** It configures a `Strict-Transport-Security` header and includes it on every response.
-- **Fast HTML:** Allows your app to skip unnecessary processing by showing an specific HTML when a requested route doesn't have a controller for it or is not on a "whitelist".
-- **Show HTML:** A really simple middleware to serve an HTML file. Its true feature is that it can be hooked up to the **HTML Generator** service.
-- **Version validator:** If you mount it on a route it will generate a `409` error if the request doesn't have a version parameter with the same version as the one on the configuration.
-
-[Read more about the built-in controllers](./documents/middlewares.md)
-
-### Services
-
-- **API client:** An implementation of the [wootils API Client](https://github.com/homer0/wootils/blob/main/documents/shared/APIClient.md) but that is connected to the HTTP service, to allow logging and forwarding of the headers.
-- **App Error:** A very simple subclass of `Error` but with support for context information. It can be used to customize the error handler responses.
-- **Ensure bearer token:** A service-middleware that allows you to validate and retrieve a bearer token from the incoming requests `Authorization` header.
-- **HTTP Error:** Another type of error, but specific for the HTTP requests the app does with the API client.
-- **Send File:** It allows you to send a file on a response with a path relative to the app executable.
-- **Frontend Fs:** Useful for when your app has a bundled frontend, it allows you to read, write and delete files with paths relative to the app executable.
-- **HTML Generator:** A service that allows you to generate an HTML file when the app gets started and inject contents of the configuration as a `window` variable.
-- **HTTP:** A set of utilities to work with HTTP requests and responses.
-- **Responses builder:** A service that generates JSON and HTML responses.
-
-[Read more about the built-in services](./documents/services.md)
-
-The service also implements a few other services from the [wootils](https://github.com/homer0/wootils) as core utilities:
-
-- [`appLogger`](https://github.com/homer0/wootils/blob/main/documents/node/logger.md): The logger service.
-- [`environmentUtils`](https://github.com/homer0/wootils/blob/main/documents/node/environmentUtils.md): The service that reads the environment variables.
-- [`packageInfo`](https://github.com/homer0/wootils/blob/main/documents/node/packageInfo.md): The app package.json information.
-- [`pathUtils`](https://github.com/homer0/wootils/blob/main/documents/node/pathUtils.md): The service to build paths relative to the project root directory.
-- [`rootRequire`](https://github.com/homer0/wootils/blob/main/documents/node/rootRequire.md): The service to make requires relatives to the project root directory.
-- [`events`](https://github.com/homer0/wootils/blob/main/documents/shared/eventsHub.md): To handle the app events.
+```bash
+npm run example [name-of-the-directory]
+```
 
-## Development
+## 🤘 Development
 
-### NPM/Yarn Tasks
+### NPM scripts
 
-| Task       | Description                          |
-|------------|--------------------------------------|
-| `docs`     | Generates the project documentation. |
-| `lint`     | Lints the staged files.              |
-| `lint:all` | Lints the entire project code.       |
-| `test`     | Runs the project unit tests.         |
-| `todo`     | Lists all the pending to-do's.       |
+| Script        | Description                          |
+| ------------- | ------------------------------------ |
+| `build`       | Transpiles the TypeScript code.      |
+| `docs`        | Generates the project documentation. |
+| `lint`        | Lints and formats the staged files.  |
+| `lint:all`    | Lints the entire project code.       |
+| `types:check` | Validates the types definitions.     |
+| `test`        | Runs the project unit tests.         |
+| `todo`        | Lists all the pending to-do's.       |
+| `example`     | Runs an example project.             |
 
 ### Repository hooks
 
-I use [`husky`](https://yarnpkg.com/package/husky) to automatically install the repository hooks so the code will be tested and linted before any commit, and the dependencies updated after every merge.
+I use [`husky`](https://npmjs.com/package/husky) to automatically install the repository hooks:
+
+| Hook         | Description                              |
+| ------------ | ---------------------------------------- |
+| `commit-msg` | Ensures the use of conventional commits. |
+| `pre-commit` | Lints and formats the staged files.      |
+| `pre-push`   | Validates the types and run the tests.   |
+| `post-merge` | Updates the dependencies (`npm i`).      |
 
-#### Commits convention
+### Commits conventions
 
-I use [conventional commits](https://www.conventionalcommits.org) with [`commitlint`](https://commitlint.js.org) in order to support semantic releases. The one that sets it up is actually husky, that installs a script that runs `commitlint` on the `git commit` command.
+I use [conventional commits](https://www.conventionalcommits.org) with [`commitlint`](https://commitlint.js.org) in order to support semantic releases. The one that sets it up is actually `husky`, since it installs a script that runs `commitlint` on the commit message validation.
 
 The configuration is on the `commitlint` property of the `package.json`.
 
 ### Releases
 
-I use [`semantic-release`](https://yarnpkg.com/package/semantic-release) and a GitHub action to automatically release on NPM everything that gets merged to main.
+I use [`semantic-release`](https://npmjs.com/package/semantic-release) and a GitHub action to automatically release on NPM everything that gets merged to main.
 
 The configuration for `semantic-release` is on `./releaserc` and the workflow for the release is on `./.github/workflow/release.yml`.
 
 ### Testing
 
-I use [Jest](https://facebook.github.io/jest/) to test the project.
+I use [Jest](https://jestjs.io) to test the project.
 
 The configuration file is on `./.jestrc.js`, the tests are on `./tests` and the script that runs it is on `./utils/scripts/test`.
 
 ### Code linting and formatting
 
-For linting, I use [ESlint](https://eslint.org) with [my own custom configuration](https://yarnpkg.com/package/@homer0/eslint-plugin); there are two configuration files, `./.eslintrc` for the source and the tooling, and `./tests/.eslintrc`, and there's also a `./.eslintignore` to exclude some files.
+For linting, I use [ESlint](https://eslint.org) with [my own custom configuration](https://npmjs.com/package/@homer0/eslint-plugin).
+
+There are two configuration files, `./.eslintrc` for the source and the tooling, and `./tests/.eslintrc`, and there's also a `./.eslintignore` to exclude some files.
 
-And for formatting, I use [Prettier](https://prettier.io) with [my JSDoc plugin](https://yarnpkg.com/package/@homer0/prettier-plugin-jsdoc) and [my own custom configuration](https://yarnpkg.com/package/@homer0/prettier-config). The configuration file is `./.prettierrc`.
+For formatting, I use [Prettier](https://prettier.io) with [my JSDoc plugin](https://npmjs.com/package/@homer0/prettier-plugin-jsdoc) and [my own custom configuration](https://npmjs.com/package/@homer0/prettier-config). The configuration file is `./.prettierrc`.
 
 The script that runs them is `./utils/scripts/lint`; the script `lint-all` only runs ESLint, and runs it for the entire project.
 
 ### Documentation
 
-I use [JSDoc](https://jsdoc.app) to generate an HTML documentation site for the project.
-
-The configuration file is `./.jsdoc.js` and the script that runs it is on `./utils/scripts/docs`.
-
-### To-Dos
+I use [TypeDoc](https://typedoc.org) to generate an HTML documentation site for the project.
 
-I use `@todo` comments to write all the pending improvements and fixes, and [Leasot](https://yarnpkg.com/en/package/leasot) to generate a report. The script that runs it is on `./utils/scripts/todo`.
+The configuration file is `./.typedoc.json` and the script that runs it is on `./utils/scripts/docs`.
 
-## Motivation/Introduction
+## 👀 Motivation
 
-A friend who's also web developer brought the idea of start using a dependency injection container on Node, and how Jimple was a great tool for it, and from that moment on I can't think of starting an app without using it. It not only allows you to implement dependency injection on a simple and clean way but it also kind of forces you to have a really good organization of your code.
+A friend, who's also web developer, brought the idea of start using a dependency injection container on Node, and how Jimple was a great tool for it; from the moment I tried Jimple, I could never think of starting another project without it: It not only allows you to implement dependency injection on a simple and clean way, but it also kind of forces you to have a really good organization of your code.
 
-A couple of months after that, the same friend told me that we should do something similar to [Silex](https://silex.symfony.com/), which is based on Pimple, with Express. I ran with the idea and... this project is what I think a mix of Jimple and Express would look like. To be clear, **this is not a port of Silex**.
+A couple of months after that, the same friend told me that we should do something similar to [Silex](https://github.com/silexphp/Silex), which is based on Pimple, butwith Express. I ran with the idea and... this project is what I think a mix of Jimple and Express would look like. To be clear, **this is not a port of Silex**.