handlin

Handlin allows to generate and handle NodeJS API responses. By embracing the router-controller-service API model, handling standardizes the API data return format.

Example of the API response with a help of handlin

{
  "success": true,
  "code": 200,
  "data": {
    "_id": "63dd72562dae3971744d65b1",
    "isActive": false,
    "balance": "$2,693.75",
    "name": "Floyd Kerr",
    "gender": "male",
    "email": "[email protected]"
  },
  "status": "OK",
  "message": "Standard response for successful HTTP requests."
}

Prerequisites

This project requires NodeJS (version 18 or later) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
8.13.2
v18.0.0

Table of contents

• handlin

  • Prerequisites

  • Table of contents

  • Installation

  • RCS

  • Usage

    • Generating responses
    • Handling responses
    • Sample express project using handlin

  • Contributing

  • Authors

  • License

  • Readme template credits

Installation

To install and set up the library, run:

$ npm install handlin

RCS

The handlin package relies on Router Controller Service API design pattern.

In this pattern, a Router component is responsible for mapping incoming requests to the appropriate Controller.

The Controller component then calls the appropriate Service component to execute the requested business logic, and finally returns the result to the Router component, which returns it to the client.

The Service component encapsulates the application's business logic and communicates with data storage or other external systems as necessary.

Usage

Generating responses

To generate response with handlin, you first need to import the generateResponse method to your service:

import { generateResponse } from "handlin";

It takes as a parameter an object with the following fields:

| Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | code | number | Yes | A http response code that should be sent | | status | string | No | By default it attaches statuses correcsponsing to status codes from http-status library | | message | string | No | By default it attaches messages correcsponsing to status codes from http-status library | | redirectUrl | string | No | A url to a destination where the user will be redirected with the response | | data | object | No | Data attached to the response |

return generateResponse({ code: 200, data: sampleObject });

OR more detailed:

return generateResponse({
  code: 200,
  message: "Data retrieved succesfully!",
  success: true,
  data: sampleObject,
});

Full sample of the code from sample.service.ts:

import { generateResponse } from "handlin";

export const getSampleData = async () => {
  const sampleObject = {
    _id: "63dd72562dae3971744d65b1",
    isActive: false,
    balance: "$2,693.75",
    name: "Floyd Kerr",
    gender: "male",
    email: "[email protected]",
  };

  return generateResponse({
    code: 200,
    message: "Data retrieved succesfully!",
    success: true,
    data: sampleObject,
  });
};

Handling responses

To handle response with handlin, you first need to import the handleResponse method to your controller:

import { handleResponse } from "handlin";

Then, use it by providing response from service and request, response from express as parameters:

const response = await SampleService.getSampleData();

return handleResponse(response, req, res);

Full sample of the code from sample.controller.ts:

import { Request, Response } from "express";
import { handleResponse, generateResponse } from "handlin";
import * as SampleService from "../services/sample.service";

export const getSampleData = async (req: Request, res: Response) => {
  try {
    //Retrieve response from the service
    const response = await SampleService.getSampleData();

    //Handle the response - return data to the user
    return handleResponse(response, req, res);
  } catch (e) {
    //In case of a potential error, catch it;
    //generate error response and handle it immediately

    if (e instanceof Error) {
      return handleResponse(
        generateResponse({ code: 500, message: e.message }),
        req,
        res
      );
    }
  }
};

Sample Express Project using handlin

You can check out a demo express project utilizing handlin package here:

MRCS-express-boilerplate

Contributing

As an open source project, handlin depends on the contributions and support of its community. Whether you're a seasoned developer or just starting out, there's a place for you in the handlin project. We welcome bug reports, bug fixes, new features, and documentation improvements.

If you're interested in getting involved, please check out our GitHub repository and read our contribution guidelines.

Authors

• bas0N - Initial work - bas0N

License

MIT License

Readme template credits

Andrea SonnY