servaljs
v1.2.0
Published
ServalJS is a toolset for FastifyJS
Downloads
30
Maintainers
Readme
ServalJS
Introduction
ServalJS is not a framework but rather a utility set for FastifyJS, written in TypeScript. It was developed to provide more structured and organized code on the backend.
Table of contents
Installation
npm i --save fastify servaljs @fastify/middie
Creating Serval application
To create Fastify application powered by Serval tool set, createServal
function is used. This is also the main entry point for the application which is used to configure it. Application configuration is pretty simple. There are 4 important properties in configuration object (see Snippet 1):
server.port
- Specify the port on which Express server will be available,controllers
- Array of controller objects which will be mounted in order,middleware
- Array of middleware object which will be mounted in order,modules
- Array of module objects which will be mounted in order,
const app = createServal({
server: {
port: 7000,
},
modules: [
/* List of modules */
],
controllers: [
/* List of controllers */
],
middleware: [
/* Middleware list */
],
});
Snippet 1 - Create a Serval application.
This will be explained in more detail.
- First step is mounting modules. They are mounded in FIFO order and once 1 module is mounted, it will trigger a callback which will mount the next module, and so on.
- Next step is mounting middleware objects.
- In next step, all controller objects will be mounted in FIFO order.
- With all above steps completed successfully,
onReady
function will be called, HTTP server will be started and it will print message like one shown below:
Serval - Started Successfully
-------------------------------------
PORT: 1280
PID: 24720
TTS: 0.007s
Controller
Most important tools for creating REST APIs are tools for connecting HTTP requests with some business logic, doing a required work and creating a response. This is as easy as creating an HTTP route handler for specified method. In pure Fastify application this could be done like shown in Snippet 2.
fastify.get('/user', (request, replay) => {
// Get user from the database
// ...
return user;
});
Snippet 2 - Creating an endpoint using Fastify
This is all very nice but writing a code this way can be messy and organizing it can be a challenge. Because of this, abstracts like Controller, Controller method and Middleware exist in the Serval tool set. In this section, Controller abstract will be covered.
Controller is an abstraction which provides clean and unified way for creating a group of REST endpoints. Controller object is created by calling createController
function which accepts configuration object as an argument. Controller by itself if just a "placeholder" and does not hold any complex logic. To implement a logic, and to add REST endpoints, Controller method is used.
By using the Serval Controller approach, code from Snippet 2 can be rewritten like shown in Snippet 3.
const UserController = createController({
name: 'User',
path: '/user',
methods() {
return {
getUser: createControllerMethod<void, User>({
type: 'get',
async handler() {
// Get user from the database
// ...
return user;
},
}),
};
},
});
Snippet 3 - Create an endpoint using the Serval controller/method approach.
Much more code is written in Snippet 3 compared to 2, so why is this better? Second example provides structure, consistency (which is not easy to spot on such a short example) and unified way to create REST endpoints. This means that navigation in project is much quicker, and it is easier to understand what is the end result of each endpoint. In addition to that, return type of the method can be specified.
Pre request handler
It is a method inside of a Controller Method configuration object. It is executed before each required to specified route and output from it is piped to handler method. For example, you can create a pre request handler which will convert a first letter of a request parameter in upper-case like shown in Snippet 5.
const MyController = createController<{ baseMessage: string }>({
name: 'My controller',
path: '/hello',
methods() {
return {
world: createControllerMethod<{ name: string }, { message: string }>({
path: '/:name',
type: 'get',
async preRequestHandler({ request }) {
const params = request.params as { name: string };
return {
name:
params.name.substring(0, 1).toUpperCase +
params.name.substring(1).toLowerCase(),
};
},
async handler({ name }) {
return {
message: `Hello ${name}!`,
};
},
}),
};
},
});
Snippet 4 - Controller method pre request handler
Again, example from Snippet 4 is trivial but it illustrates how pre request handler is used. As it can be seen, pre request handler functions like a middleware but only for specific route. It is useful when different routes use different mechanisms for security and resource protection.
Middleware
Middleware is similar to a controller, but it is usually used to transform incoming or outgoing data in some shape or form. Because of this, middleware is triggered for all methods on all routes which are starting with a specified path.
Like the createController
function, createMiddleware
function returns the
Middleware object which is used in the Serval configuration object in the
middleware array property. Example for creating a middleware object is shown in
Snippet 6.
createMiddleware({
name: 'Test middleware',
path: '/test',
handler() {
return async () => {
// Middleware logic.
};
},
});
Snippet 5 - Creating a simple middleware object.
It is important to know that handler method can be asynchronous and will be called only once when the middleware is mounted. So before returning a request handler function, setup of the middleware can be done.
Modules
Module is the core abstract in the Serval which allows external code to
access the pipe. Modules are passed to the configuration object in modules
array.