configurator.md

Configurator

The Configurator class is the main resource of this project and serves as the entry point to setup the Express server.

const server = new Configurator();

Properties

Configurator.METHODS

object - A static enum of strings that has all the supported HTTP methods names, which are GET, POST, PUT, DELETE, HEAD, PATCH and OPTIONS

Examples

You can use it with the API configurator to add a route middleware:

server.api
   .add(Configurator.METHODS.GET, '/some-route', someMiddlewareFunction);

This will register a middleware for a GET request on '/some-route'.

---

Configurator.HOOKS

object - A static enum of all the available hooks events names, which are (in the order they're executed):

• BEFORE_SETUP - It'll be emitted when the internal Expressjs instance is created, but before it gets configured
• BEFORE_API_SETUP - It'll be emitted right before the API resources are set
• AFTER_API_SETUP - It'll be emitted when all the API resources have been set
• BEFORE_STATIC_SETUP - It'll be emitted right before the static resources are set
• AFTER_STATIC_SETUP - It'll be emitted when all the static resources have been set
• AFTER_SETUP - It'll be emitted when all the configurations were applied and the server is about to get initialized

Note: All the hook functions will receive the express instance, and the express module as arguments.

Note: You can also use the hook event name itself, they are: 'before-setup', 'before-api-setup', 'after-api-setup', 'before-static-setup', 'after-static-setup' and 'after-setup'.

Examples

Using with the Configurator.prototype.on(event, listener) to register hook functions:

server
   .on(Configurator.HOOKS.BEFORE_API_SETUP, (app, express) => {
      // *Do something cool...
   })
   .on('before-api-setup', (app, express) => {
      // *Do something cool here...
   });

---

Configurator.prototype.server_port

number|string - The server port

Note: readonly, use the port() method to assign a new value.

---

Configurator.prototype.static

StaticConfigurator - The inner configurator for static resources

---

Configurator.prototype.api

APIConfigurator - The inner configurator for API routes

---

Methods

Configurator.prototype.port(port_number)

Sets the port number of the server.

Note: by default, the initial server port is 80.

Parameters

• port_number number|string - The port number

Returns

Configurator - This same configurator (for method chaining)

Examples

console.log(server.server_port);   // Will print 80 (default port)

server.port(3000);                 // Will set the port to 3000
server.port('8080');               // Will set the port to '8080'
server.port(process.env.PORT);     // Will use the PORT environment variable

---

Configurator.prototype.notFound(middleware)

Registers middlewares to handle 404 responses.

Note: it can be used to send custom 404 pages or API responses.

Note: you can call this method multiple times to add more middlewares, but you can also simply pass an array of middlewares.

Parameters

• middleware function|function[] - A valid Expressjs middleware function

Returns

Configurator - This same configurator (for method chaining)

Examples

server
   .notFound((req, res, next) => {
      // *Do something cool here...
   });

---

Configurator.prototype.https(options, is_file)

Switches the server to use HTTPS.

Note: calling this method will make the default server port to be 443 instead of 80.

Parameters

• options object - The HTTPS options object
• options.cert string - The HTTPS certificate
• options.key string - The HTTPS key
• options.pfx string - The HTTPS pfx
• options.passphrase string - The HTTPS pfx password
• is_file boolean - Whether the options values are filenames, and should be retrieved from disk

Returns

Configurator - This same configurator (for method chaining)

Examples

Using key and certificate files:

server
   .https({
      key: './my-key.key',
      cert: './my-cert.crt'
   }, true)
   // ...

Using a PFX file:

server
   .https({
      pfx: './my-pfx.pfx',
      passphrase: './my-pass.txt'
   }, true)
   // ...

---

Configurator.prototype.locals(key, value)

Sets a new property in the Express locals (or the entire locals object).

Note: if an object is passed, it will override the locals object. Otherwise, the arguments will be processed as a key and a value, and they will be merged into the locals object.

Parameters

• key object|string - The key of the value, or the entire locals object
• value * - The value for the given key

Returns

Configurator - This same configurator (for method chaining)

Examples

Setting the entire locals object:

server
   .locals({
      prop1: 'val1',
      prop2: 'val2'
   })
   // other calls to 'locals()' method passing an object will override it

Using key-value pairs:

server
   .locals('prop1', 'val1')
   .locals('prop2', 'val2')
   // calls to 'locals()' method passing an object will override it

---

Configurator.prototype.on(event, listener)

Registers a handler for a given event.

Note: it can be used to configure hook functions.

See: Configurator.HOOKS for all the hooks events available.

Parameters

• event string - The event name
• listener function - The handler function

Returns

Configurator - This same configurator (for method chaining)

Examples

server
   .on('before-api-setup', (app, express) => {
      // *Do something cool here...
   });

---

Configurator.prototype.start()

Starts the server instance.

Note: It will apply the settings and start the server, so it should be called after the configurations have been done.

Note: These are the actions done in order to start the web server:

• For each API resource:

• Set parsers

• Set preflight headers (in an OPTIONS middleware)

• Set other headers

• Set the middlewares

• For each static resource:

• Set a static GET middleware

• Set the index page on the root route (/)

• Set an auto 404 response middleware

Returns

Promise<{ server, address }> - The promise resolves into an { server, address } object, or it rejects with a Error if the server could not be started:

• server http.Server - The started HTTP server
• address URL - The server address information

Examples

server
   .port(3000)
   .start()    // It will commit all settings and start the server
   .then(output => console.log('Server started at ' + output.address.href))
   .catch(err => console.error(err));

---

Configurator.prototype.stop()

Stops the current server instance.

Note: It will end all connection sockets remaining in the current server, and release the listened port.

Returns

Promise - The promise resolves if everything goes ok, or it rejects with a Error if the server could not be stopped