loco-server

Loco

Loco is a http proxy and/or mockup server.

Features

• forward a request using node-fetch
• mock API response
• supports using .env variables

Changelog

• 4.0.3
  • function files can now have .js or .cjs extenstion
• 4.0.2
  • fix typo in docs
• 4.0.0
  • add an option to load functions on each request so that it is not required to reload the app on a function file change/add/remove. It does require updating the config by adding reloadOnRequest key and setting it to true
  • change require node version to v18.16.0
• 3.2.0
  • make PUT,PATCH and DELETE requests available
  • support wildcard requests like /{function_name}/{id}/{something} - /{id}/{something} will be available as an array [{id}, {something}] in param.paths
• 3.1.0
  • add multer middleware for multipart/form-data support
• 3.0.0
  • change process function to only have one parameter now called 'param'.
  • change config functionsPath to be an array of glob entries instead of just one
• 2.0.0
  • add live reload for function files
  • additional loco helper - loco.requireUncached('path');
  • additional loco helper - loco.chalk;
  • config functionsDir replace with functionsPath which is a glob
• 1.1.1
  • fix loco.corsHeaders() error when no headersOverwrites provided
• 1.1.0
  • pass reqMethod to processFunction to distinguish type of request if required
  • add OPTIONS request support
  • enable ovewriting headers in loco.corsHeaders() helper

Installation

npm install -sD loco-server

Usage

Straight from the command line:

npx loco <config_file>

or if used in package.json scripts:

loco <config_file>

Configuration

Sample config file:

{
  "appPort": 8888,
  "appHost": "127.0.0.1",
  "functionsPath": ["loco_functions/*.js"],
  "envFile": ".env",
  "reloadOnRequest": true,
  "optionsRequestHeaders": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
    "Access-Control-Allow-Headers": "*"
  },
  "optionsRequestStatusCode": 200
}

Field	Description
appPort	Port to run the server on
appHost	Host to run the server on
functionsPath	Glob to where to look for loco functions
envFile	.env file name with path
reloadOnRequest	Flag should funtions be reload on each request which will function as live-reload
optionsRequestHeaders	Response headers for OPTIONS request
optionsRequestStatusCode	OPTIONS request status code

Functions

Functions are understood as JS files specified by functionsPath in the configuration. Each file will be served under a separate webpath in the server. This webpath is equal to the file namie without .js extension.

Function file scaffold:

/**
 * Function description string
 */
const description = 'Blank function scaffold.';

/**
 * Main process function
 * @param {object} param.req entire request object
 * @param {object} param.query GET request query
 * @param {object} param.bodyJSON POST request body
 * @param {string} param.reqMethod request method
 * @param {object} param.loco helper functions object
 * @param {object} param.envVars environment variables
 * @param {array} param.paths array of wildcard paths
 * @returns {object} response object consisting of response statusCode, body and headers object
 */
const processFunction = async (param) => {
    return {
        statusCode: 200,
        headers: param.loco.corsHeaders(),
        body: {mockup: true}
    };
};

// Export
module.exports = {
    processFunction,
    description,
};

The descriptions const is used for providing a short summary of a given function. Main required function in each function file is the processFunction. It has one parameter called param which is an object containing:

Argument	Descriptions
req	full express request object
query	GET query requested represented as JSON, example: {"query":"test"}
bodyJSON	POST body requested as as JSON, example: {"login":"john"}
reqMethod	Request method as a string, example: GET
loco	object containing predefined helper function, described below in the function helpers section
envVars	environment variables from the .env file defined in the config
paths	array of paths that were used when this is a wildcard request

The function must return an object with a given structure:

{
    statusCode: 200,
    headers: param.loco.corsHeaders(),
    body: {mockup: true}
}

Key	Value
statusCode	response status code
headers	object containig response header as key and header value as value
body	response body

Function helpers

Current list of helpers passed as a param.loco argument to the processFunction

• param.loco.fetchJSON(url:string, options:object) - node-fetch module
• param.loco.returnJsonWithDelay(sec, jsonResponse) - usefull when a mocked response is return to fake a time delay. Example usage:

return {
    [...]
    body: await loco.returnJsonWithDelay(3, jsonData),
};

this will return jsonData after 3 seconds.

• loco.corsHeaders(headersOverwrites) - returns headers that can be used when you want to enable cors:

{
    'Content-Type': 'application/json; charset=utf-8',
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Headers': 'Content-type',
    'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
}

Example usage:

return {
    [...]
    headers: param.loco.corsHeaders(),
    [...]
};

You can also overwrite a default header or add a new one:

headers: param.loco.corsHeaders({"Content-Type": "text/html; charset=utf-8"}),

• loco.fetchJSON(url:string, options:object) - utility function to make a fetch request to an endpoint that returns JSON response. Example usage:

const jsonData = await param.loco.fetchJSON('https://api.url/', {
    method: "PATCH",
    headers: {
        "Content-Type": "application/json",
    },
    body: JSON.stringify(param.bodyJSON.payload)
}).catch((err) => {
    return {error: err.message};
});
[...]
return {
    [...]
    body: jsonData,
};

• param.loco.requireUncached(path) - clear cache for path and then require. Usefull when you modify data in processFunction often.

Donate

If you find this piece of code to be useful, please consider a donation :)