Single File Router (SFR)

Overview

SFR allows the declaration of services including its controllers, handlers and validators in one single file.

Featuring a configurable Inversion of Control pattern for dependency libraries, It allows developers to easily inject dependencies on either handlers or controllers for convenient and easy access.

Due to it's self-contained and structured format, The SFR has allowed for the development of several extensions such as:

• OpenAPI Service Translator

  A plugin which also uses API-Bundler's ability to extract metadata from individual SFRs It's main purpose is to translate and create service-level documentation which follows the OpenAPI Standard, this essentially opens up doors to extensive tooling support, instrumentation, automated endpoint testing, automated documentation generation, just to name a few.

• UAC - ACM Self-Registration Scheme

  The in-house API-Bundler was designed to extract useful information from individual SFRs, termed service-artifacts, they are reported to a centralized authority through the well-documented UAC - ACM Self-Registration Scheme, this is prerogative to the grand scheme of Resource Administration.

Structure

A regular SFR is composed of the following objects

|Object Name|Description| |-|-| |CFG| configuration information relayed to the API-bundler (service-parser).| |Validators|POJO representation of what values are allowed for each endpoint.| |Handlers| Express middlewares which acts as the main logic block for each endpoint.| |Controllers|Functions that execute calls to the database.|

Usage

import sfr from "@hawkstow/sfr";
import express from "express";

const api_path = "api";
const doc_path = "docs";

const app = express();

/*
	Note: 
	SFR Bundler will look for two folders, named "rest" and "ws" inside the "path". 
	The placement of SFRs define the protocol that they'll use. 
	`
	i.e:rest SFRs reside within "rest", websocket SFRs reside in "ws".
*/

sfr({
  root : "dist",   //Specifies the working directory
  path : api_path, //Specifies the API directory i.e: where SFR files reside
  out  : doc_path  //Specifies the directory for the resulting OAS documents
}, app);

Error-Handling

The library automatically handles errors on both handlers and controllers, however, care must be taken on how error-handling is done by the developer, the following table illustrates what error-handling styles are allowed for both cases.

|Handlers|Controllers| |-|-| |Exception Throws|Promise.resolve/reject returns| |Passing Exceptions to Next fn||

Bug Reporting

If you've found a bug, please file it in our Github Issues Page so we can have a look at it, perhaps fix it XD

TODO:

• Multer Upload Validation
• Built-in Logging