jgloo

Description

jgloo is a local HTTP server useful to mock your backend API and speed up the client development.
This project is based on the Node framework Express. The highlights are:

• Create a ReST API with two rows of code
• Create custom API easily
• Create custom middleware easily (e.g. auth check)
• Store data in accessible JSON files
• Reload the live changes of your mocks automatically (thanks to nodemon package)
• Expose a dedicated folder for the static files (images, assets etc...)
• Support to multipart/form-data requests

Installation

npm i -D jgloo

After the installation create a folder "mock" in your project root (you can use another path and folder name if you want).
The only requirement is to create a subfolder "api" in your chosen path (e.g. "mock/api").
Now you are ready to create your first API.

Guide

• Create a simple API
• Create a default ReST API
• Create a custom ReST API
• Create a middleware
• Where data are stored
• Expose the static files
• Handle requests with file uploads
• Simulate network delay
• Manage path conflicts
• Run the server

Create a simple API

To setup your first API create a new file "hello.js" in the "api" folder. The name of the file does not matter. Then insert the following snippet:

module.exports = {
  path: '/hello',
  method: 'get',
  callback: (req, res) => {
    res.json({ message: 'Hello World!' });
  },
};

This code define the GET route http://localhost:3000/hello that returns a JSON with data "{ message: 'Hello World!' }".
You are ready to run the server now.

Create a default ReST API

To setup a ReST API, you have to create a new file in the "api" folder with the name you prefer and the following snippet:

module.exports = {
  path: '/user',
  method: 'resource',
};

With these few rows of code will be created 6 routes:

• GET /user : return the list of users;
• GET /user/:id : return the specific user;
• POST /user : allow to store the full request body as new user and return it as response;
• PUT /user/:id : allow to replace an existent user with the full request body and return it as response;
• PATCH /user/:id : allow to merge an existent user data with the request body values and return it as response;
• DELETE /user/:id : allow to delete an existent user and return the deleted id.

If you want to skip any of the previous routes, you can add the "not" property:

module.exports = {
  path: '/user',
  method: 'resource',
  not: ['LIST']
};

The available values of the "not" property are ['LIST', 'READ', 'CREATE', 'UPDATE', 'PATCH', 'DELETE']

Create a custom ReST API

If you need to control the logic of your resources, you can create a custom API that read and/or write the data in the JSON database.
To achieve it create a new file in the "api" folder with the name you prefer and the following snippet:

const { getResource, setResource } = require('jgloo');

module.exports = {
  path: '/user',
  method: 'post',
  callback: (req, res) => {
    // Get the existent resource list or instantiate it
    const list = getResource('user') || [];

    // Get the data of the request and add a new field
    const user = req.body;
    user.extraField = 'value';

    // Push the new model to the list
    list.push(user);

    // Store the updated list in the "user.json" file
    setResource('user', list);

    // Return the model as JSON
    res.json(user);
  },
};

Create a middleware

To add a middleware, you have to create a folder "middlewares" in your chosen root path (e.g. "mock/middlewares").
Then create a new file inside with the name you prefer and the following sample snippet:

module.exports = (req, res, next) => {
  const isAuthorized = req.get('Authorization') === 'my-token';
  isAuthorized ? next() : res.sendStatus(401);
};

This sample code check for all routes if the "Authorization" header is set and it has the value "my-token".

Where data are stored

The resources are stored in JSON files placed in the subfolder "db" of your chosen root path (e.g. "mock/db").
The default ReST API store the JSON file with the name generated by resource path replacing the slashes with the minus sign (e.g. "/auth/user" will be stored as "auth-user.json").
If you want to specify the file name of the resources, you can set it as the "name" property of the API:

module.exports = {
  path: '/my/long/path',
  method: 'resource',
  name: 'user',
};

With this code, the JSON file will be stored as "user.json".

Expose the static files

To expose any static files you have to create the subfolder "static" in your chosen root path (e.g. "mock/static") and put all the resources inside it.
The static content is reachable by "http://localhost:3000/static/...". That's it.

Handle requests with file uploads

The multipart/form-data requests are supported by default. The req.body will be filled with the right data.
The data of the uploaded files are placed in the req.files property and the files are saved in the static folder with a temporary name.
It's recommended to add the static folder in the .gitignore file.

Simulate network delay

If you want to simulate a network delay, you can add the delay property to your API configuration:

module.exports = {
  ...
  delay: 3 // Seconds
};

Manage path conflicts

If you have a scenario where two or more paths have conflicting values, e.g.:

• /my-path/:id
• /my-path/my-sub-path

you can add the priority property to your API configuration:

module.exports = {
  ...
  priority: 2
};

The default value is 0. The api with the higher value will be used.

Run the server

To run the server execute the following command in your project root:

npx jgloo

The full optional parameters are:

npx jgloo -f [FOLDER] -p [PORT] -s [STATIC_URL]

For example:

npx jgloo -f 'mock' -p 3000 -s 'static'

• "-f" or "--folder": the folder where your mocks are placed. It's optional, by default it's the folder "mock".
• "-p" or "--port": the port of running server. It's optional, by default it's "3000".
• "-s" or "--static": the url prefix of the static resources. It's optional, by default it's "static".