@qnx/response is a library designed to simplify handling HTTP responses within Express.js applications. It offers standardized formatting and transmission of responses, including built-in support for error management and validation.
Standardized response formatting: @qnx/response provides a consistent way of formatting responses, with a common structure for all responses that includes data, metadata, and errors.
Validation Support: @qnx/response integrates with popular validation libraries like Zod and express-validator, making it easy to handle validation errors in a consistent It automatically returns error responses if validation fails.
No try-catch blocks: @qnx/response eliminates the need for manual try-catch blocks by automatically handling errors and exceptions. This reduces boilerplate code, enhancing code readability and cleanliness.
Error handling: @qnx/response makes it easy to handle errors in a consistent way, with built-in support for common error types like 400 (Bad Request) and 500 (Internal Server Error).
Type Strong: @qnx/response offers full TypeScript typings support, enhancing developer experience and leveraging the benefits of static typing.
Customization: @qnx/response is highly customizable with options for configuring response formats, error handling, and more.
In summary, @qnx/response streamlines HTTP response handling in Express.js applications, minimizing boilerplate code for error handling and validation while enhancing overall maintainability.
Install @qnx/response via npm, yarn, pnpm, or bun:
Use the package manager npm to install @qnx/response.
# Using npm
npm install @qnx/response
# Using yarn
yarn add @qnx/response
# Using pnpm
pnpm install @qnx/response
# Using bun
bun install @qnx/response@qnx/response requires @qnx/errors as a peer dependency:
npm install @qnx/errorsimport { asyncValidatorHandler } from '@qnx/response'
express.get(
'/',
asyncValidatorHandler(async (req, res, next) => {
return await Model.findAll()
})
)Without @qnx/response
express.get('/', async (req, res, next) => {
try {
const data = await Model.findAll()
res.send({ data })
} catch (error) {
// handle error response
}
})To utilize @qnx/response, import it into your Node.js application:
import { ApiResponse, asyncValidatorHandler } from '@qnx/response'Create an API response using the ApiResponse class. Set response properties using available methods:
express.get(
'/',
asyncValidatorHandler(async (req, res) => {
return new ApiResponse().setData({ user: { name: 'Foo' } }).setMessage('Success')
})
)
/*
{
data: {
user: { name: 'Foo' }
},
message: 'Success'
}
*/The above code creates a new ApiResponse instance, sets data to an object with a message property, and sends the response.
@qnx/response provides error handling mechanisms for API responses. Define error responses using the invalidValueApiResponse function.
express.get(
'/',
asyncValidatorHandler(async (req, res) => {
const errorKey = 'foo'
const errorMessage = 'Foo is required.'
return invalidValueApiResponse(res, errorKey, errorMessage)
})
)
/*
{
errors: {
foo: ['Foo is required.']
},
error: 'Foo is required.'
}
*/Use the ApiResponseErrors interface to define an object containing errors.
import { asyncValidatorHandler, invalidApiResponse, ApiResponseErrorsValue } from '@qnx/response'
express.get(
'/',
asyncValidatorHandler(async (req, res) => {
const errors = ApiResponseErrorsValue.getInstance()
.addError('foo', 'Foo is required.')
.addError('bar', 'Bar is required.')
.getErrors()
return invalidApiResponse(res, errors)
})
)
/*
{
errors: {
foo: ['Foo is required.'],
bar: ['Bar is required.']
},
error: 'Foo is required.'
}
*/Utilize @qnx/error with @qnx/response to throw exceptions and pass data to end-users.
Define error responses using the ValidationError class:
import { asyncValidatorHandler, ValidationError, ApiResponseErrorsValue } from '@qnx/response'
express.get(
'/',
asyncValidatorHandler(async (req, res) => {
const errors = ApiResponseErrorsValue.getInstance()
.addError('foo', 'Foo is required.')
.addError('bar', 'Bar is required.')
.getErrors()
throw new ValidationError('Errors', { errRes: { errors } })
})
)
/*
{
errors: {
foo: ['Foo is required.'],
bar: ['Bar is required.']
},
error: 'Foo is required.'
}
*/Define error responses using the InvalidValueError class for single error responses:
import { asyncValidatorHandler, InvalidValueError } from '@qnx/response'
express.get(
'/',
asyncValidatorHandler(async (req, res) => {
throw new InvalidValueError('Foo is required.', { key: 'foo' })
})
)
/*
{
errors: {
foo: ['Foo is required.']
},
error: 'Foo is required.'
}
*/Example demonstrating @qnx/response handling Zod errors in an API response:
import { asyncValidatorHandler, ApiResponse } from '@qnx/response'
import { z } from 'zod'
express.post(
'/create-user',
asyncValidatorHandler(async (req, res) => {
export const UserSchema = z.object({
name: z.string(),
email: z.string()
})
const userData = UserSchema.parse(this.req.body)
const user = UserModel.create(userData)
return ApiResponse.getInstance().setData(user).setMessage('User created successfully.')
})
)
/*
=> { name: 'foo', email:'foo@abc.com' }
{
data: {
user: { name: 'foo', email: 'foo@abc.com' }
},
message: 'User created successfully.'
}
=> { email:'foo@abc.com' }
{
errors: {
name: ['Name is required.'],
},
error: 'Name is required.'
}
*/getInstance(): Retrieves a new instance of ApiResponse.
ApiResponse.getInstance()setData(data: any): Sets the response data to the specified value.
ApiResponse.getInstance().setData({ user: { name: 'John' } })setErrorCode(errorCode: string): Sets a specific error code for the response.
ApiResponse.getInstance().setErrorCode('E123')setError(error: string): Sets a general error message for the response.
ApiResponse.getInstance().setError('Internal Server Error')setErrors(errors: ApiResponseErrors): Sets multiple errors for the response using an ApiResponseErrors object.
const customErrors = { field1: ['Error 1'], field2: ['Error 2'] }
ApiResponse.getInstance().setErrors(customErrors)setMessage(message: string): Sets a custom message for the response.
ApiResponse.getInstance().setMessage('Operation successful')setStatusCode(statusCode: number): Sets the HTTP status code for the response.
ApiResponse.getInstance().setStatusCode(200)setAdditional(data: { [key: string]: unknown }): Sets additional custom data for the response.
ApiResponse.getInstance().setAdditional({ key1: 'value1', key2: 'value2' })setError(errorKey: string, errorMessage: string): Set a single error message for a specific type of error.
ApiResponseErrorsValue.getInstance().setError('email', 'Invalid email format')addError(errorKey: string, errorMessage: string): Add a new error message to the existing errors collection.
ApiResponseErrorsValue.getInstance().addError('password', 'Password must be at least 8 characters')getErrorResponse(): Retrieve all collected errors as a response object.
const errorResponse = ApiResponseErrorsValue.getInstance().addError('foo', 'bar').getErrorResponse()
console.log(errorResponse)
/*
{
errors: {
foo: ['bar'],
},
}
*/getErrors():
Returns the collection of errors stored within the ApiResponseErrorsValue instance.
const errors = ApiResponseErrorsValue.getInstance().addError('foo', 'bar').getErrors()
console.log(errors)
/*
{
foo: ['bar'],
}
*/These methods offer flexibility in tailoring responses to specific requirements. Utilize them in combination to construct responses that align with your application's needs.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.
MIT License © 2023-PRESENT Yatendra Kushwaha