branch-tea-utils
v1.0.3
Published
This a util to fasten up development of Express
Downloads
2
Maintainers
Readme
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: "[email protected]"}
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