branch-tea-utils

Branch Tea Utils

Branch Tea Utils is a utility package for faster development with db configuration and error handlers

FEATURES

What is in this package This package comes with some features

• configuration
  • Error Logger
  • Application configuration e.g environment variables
  • Database configuration for postgres and mysql databases
  • More configuration will be added in the future
• Decorators
  • Decorator for creating http endpoint such as GET, POST, PUT, DELETE and PATCH methods
• Error handlers
  • Simple base error handler
• Authentication
  • JWT authentication fully implement but can be elevated for your specific needs
• Response handlers
  • Rest Response handler for FAILED, SUCCESS, INTERNAL_SERVER_ERROR, BAD_REQUEST
• Miscellaneous
  • Function wrapper
  • Otp code generator
  • Time calculation
  • Generating uuid
• Package installation

[!NOTE] Contribution and bug reports is welcome.

#Installation

Installing using npm

npm install branch-tea-utils

Installing using yarn

yarn add branch-tea-utils

#Error Handling and Logger

Error logging create a file name log.txt where it logs all the internal server errors with time stamp

Handling Error Setup Inside your index.ts file

import {IHandleErrorAnd404} from 'branch-tea-utils';
import express from 'express' 

const app = express();
const handleError = new IHandleErrorAnd404()

// ... your own routes

// this must be after your routes are loaded    
app.use(handleError.handleError)
app.use(handleError.notFound404)
...

USAGE:

@GetRequest(AuthController.router, "/test/:id")
test(req:Request, res: Response, next: NextFunction){
    throw new Error("some error from abse") // This line will be recorded in the log.txt file with a nice error response to the client
}

[!NOTE] Is improvement needed in the future. YES

#Application configuration

List of already configured environment variables
You can copy below to your .env file

config files
#database configures 
MAX_URL_ENCODINGS="5MB"
PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=
DB_NAME=ktr_db
#if set the synchronization on the db connection settings be set to true 
SYNC=true

# production or development
NODE_PRODUCTION=false

#smtp configuration
SMTP_HOST=smtp_host
SMTP_PORT=465
SMTP_USER=smtp_user
SMTP_PASSWORD=smtp_password
SMTP_FROM=smtp_email

#sercret keys
JWT_SECRET_KEY=verystrongkey
REFRESH_JWT_SECRET_KEY=verystrongkey

MAX_FILE_UPLOAD=5

You cann access any of the application configuration or extends them

export const applicationConfig: IAppConfig = {
    port: process.env.PORT as unknown as number,
    maxUrlEncoding: process.env.MAX_URL_ENCODINGS ?? "5MB",
    dbHost: process.env.DB_HOST,
    dbPort: process.env.DB_PORT as unknown as number,
    dbUser: process.env.DB_USER,
    dbPass: process.env.DB_PASS,
    dbName: process.env.DB_NAME,
    sync: process.env.SYNC as unknown as boolean,
    isProduction: process.env.IS_PRODUCTION as unknown as boolean,
    smtpHost: process.env.SMTP_HOST,
    smtpPort: process.env.SMTP_PORT,
    smtpUser: process.env.SMTP_USER,
    smtpPassword: process.env.SMTP_PASSWORD,
    smtpFrom: process.env.SMTP_FROM,
    jwtSecrete: process.env.JWT_SECRET_KEY,
    jwtRefreshSecret: process.env.REFRESH_JWT_SECRET_KEY,
    maxFileUpload: process.env.MAX_FILE_UPLOAD as unknown as number,
};

#Database configuration

There are two database configuration presently configure to be used in this package Postgress and MySql

[!NOTE] Make sure that the .env is correctly configured as specified above. More database configuration support will be available in the future

How to configure and connect to the database

Inside your index.ts file

import {IDatabase, DbTypes} from 'branch-tea-utils'; 

// initialize the database class
const iDatabase = IDatabase.getInstance()
// connect to db
const connection = iDatabase.initializeDB(DbTypes.MySQL)

// ... your own routes

...

#Decorators

Using Decorators to create endpoints

This one my most favorable utils

Using Decorators to create a api endpoint This decorators help you create a rest endpoint with just a decorator of any of the http methods

Example

GET REQUEST this create a get endpoint using the path specified as the second argument Inside your controller.ts file

import { IRoute, GetRequest } from 'branch-tea-utils';

class Controller {
    // the router must be a class member so that it can be accessed be the decorator
    static const router = Router.getInstance('myRoute'); // my route could be anything.

    // without adding an optional parameter it will add the base path from the endpoint e.g http://localhost:3000/myRoute/test
    @GetRequest(Controller.router, "/test-one") 
    test(req:Request, res: Response, next: NextFunction){
        // ...
    }

    // adding an optional parameter to it will remove the base path from the endpoint e.g http://localhost:3000/test
    @GetRequest(Controller.router, "/test-two", false) 
    test(req:Request, res: Response, next: NextFunction){
        // ...
    }
}

export default Controller

Create route file where all your route will be initialized:: This is optional but recommended to keep everything simple and clean Inside your routes.ts file

import {Router} from 'express'
import Controller from './controller' 

const main_route = new Router();

// do same for all your controllers

main_route.use('/', Controller.router.getRoutes())

export default main_route;
...

Inside your index.ts file

import express from 'express' 
import main_route from './routes'
// import Controller from './Controller'

const app = express();

const handleError = new IHandleErrorAnd404()

app.use('/', main_routes)
// app.use('/', Controller.router.getAllRoutes()); // without creating the routes file;

...

Using Decorator with middlewares

Using Decorators to with middleware This decorators help you pass a middleware function to the endpoint created

Examples

We have a special decorator to validate JWT token embedded in the package called UseJWTPipe UseJWTPipe takes only one optional parameter: failedMessage using UseJWTPipe will decode your JWT token into an object and add it to the req data and can be accessed using req.body.decode

JWT Validation

Inside your controller.ts file

import { IRoute, GetRequest } from 'branch-tea-utils';

class Controller {
    // the router must be a class member so that it can be accessed be the decorator
    static const router = Router.getInstance('myRoute'); // my route could be anything.

    // without adding an optional parameter it will add the base path from the endpoint e.g http://localhost:3000/myRoute/test
    @GetRequest(Controller.router, "/test-one") 
    @UseJWTPipe('Your error message')
    test(req:Request, res: Response, next: NextFunction){
        // ...
    }
}
export default Controller

Using with other MiddleWare

Using decoration for other middleware functions, use UsePipe instead

Inside your controller.ts file

import { IRoute, GetRequest } from 'branch-tea-utils';

class Controller {
    // the router must be a class member so that it can be accessed be the decorator
    static const router = Router.getInstance('myRoute'); // my route could be anything.

    static simpleMiddleware () {
        console.log('simple middleware is available')
    }

    // without adding an optional parameter it will add the base path from the endpoint e.g http://localhost:3000/myRoute/test
    @GetRequest(Controller.router, "/test-one") 
    @UsePipe(Controller.simpleMiddleware)
    test(req:Request, res: Response, next: NextFunction){
        // ...
    }
}

export default Controller

#JWT Generation

Generating of JWT token made easy.

Examples

Inside your controller.ts file

import { IToken } from 'branch-tea-utils';

// ...
const token = new IToken();

const userData = {name: "user doe", email: "[e-mail]"}
const userToken = token.generateAccessToken(userData)

console.log(userToken)

[!NOTE] Generating of access token method can also generate refresh token by passing the second optional parameter token.generateAccessToken(userData, {generateRefreshAccessTeken: userRefreshData, validity: '1d'})

[!NOTE] By default the token expires after 1hour.

Verifying refresh token Example Inside your controller.ts file

import { IToken } from 'branch-tea-utils';

const token = new IToken();

const decode = token.verifyRefreshJWTToken(refreshToken)

console.log(decode)
}

export default Controller

#Responses

There three default responses in this package SuccessResponse, ErrorFailedResponse, ServerErrorResponse

Usage Inside your controller.ts file

import { IToken, GetRequest } from 'branch-tea-utils';

class Controller {
    // the router must be a class member so that it can be accessed be the decorator
    static const router = Router.getInstance('myRoute'); // my route could be anything.
    static iResponse = new IResponse();

    @GetRequest(Controller.router, "/test-one") 
    test(req:Request, res: Response, next: NextFunction){
       return Controller.iResponse.SuccessResponse(res, { name: 'john'}, 'successful', 200);
    }
   
    @GetRequest(Controller.router, "/test-one") 
    test(req:Request, res: Response, next: NextFunction){
       return Controller.iResponse.ErrorFailedResponse(res, null, 'Failed', 400);
    }

    @GetRequest(Controller.router, "/test-one") 
    test(req:Request, res: Response, next: NextFunction){
       return Controller.iResponse.ServerErrorResponse(res, null, 'Internal Server Error', 500);
    }
}

export default Controller

#Miscellaneous

Function wrapper This is useful for situation you dont want to keep adding try/catch to your code

Example Usage Inside your controller.ts file

import { IToken, GetRequest, IUtils} from 'branch-tea-utils';

class Controller {
    // the router must be a class member so that it can be accessed be the decorator
    static const router = Router.getInstance('myRoute'); // my route could be anything.
    static iResponse = new IResponse();
    static const iUtils = new IUtils()

    static abcFunction(a: string) {
        // ...
    }

    @GetRequest(Controller.router, "/test-one") 
    test(req:Request, res: Response, next: NextFunction){
        Controller.iUtils.wrapper(res, function() {
            // function detial here ...
        }, "Response message", {a: 'foo'})
    }
    
    @GetRequest(Controller.router, "/test-two") 
    test(req:Request, res: Response, next: NextFunction){
        Controller.iUtils.wrapper(res, abcFunction, "Response message")
    }
    
    @GetRequest(Controller.router, "/test-three") 
    test(req:Request, res: Response, next: NextFunction){
        Controller.iUtils.wrapper(res, abcFunction, "Response message", {a: "foo"})
    }
}

export default Controller

Time calculaor wrapper This is useful calculating time to the future

Example Inside your controller.ts file

import { IToken } from 'branch-tea-utils';

static const iUtils = new IUtils()

iUtils.afterTimeInMilliseconds(10, true) // this return the time 10 minute from now in milliseconds

Generate Code This is useful to generate code between 100000-999999

Example Inside your controller.ts file

import { IToken, IUtils} from 'branch-tea-utils';

static const iUtils = new IUtils()
iUtils.generateCode() // generate random code between 100000 - 999999 which can be user for otp 

export default Controller

Generate uuid This is useful to generate uuid in string

Example Inside your controller.ts file

import { IToken, IUtils} from 'branch-tea-utils';

static const iUtils = new IUtils()
iUtils.generateUUID() // generate random uuid and remove all hyphens(-) from the generated string 

export default Controller

Future support

• Email Sending feature: future support
• And many more features