https://github.com/harshdev1809/http-reply
A lightweight Node.js utility for sending consistent, standardized HTTP responses across your API endpoints
https://github.com/harshdev1809/http-reply
api api-rest http http-requests https javascript rest-api
Last synced: 5 months ago
JSON representation
A lightweight Node.js utility for sending consistent, standardized HTTP responses across your API endpoints
- Host: GitHub
- URL: https://github.com/harshdev1809/http-reply
- Owner: HarshDev1809
- License: mit
- Created: 2025-05-27T08:36:13.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-06-13T17:42:08.000Z (7 months ago)
- Last Synced: 2025-08-16T20:15:35.853Z (5 months ago)
- Topics: api, api-rest, http, http-requests, https, javascript, rest-api
- Language: TypeScript
- Homepage:
- Size: 56.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HttpReply
A lightweight, flexible Node.js utility for standardizing HTTP responses in Express, Fastify, or custom server frameworks. `HttpReply` provides a consistent, customizable way to format and send HTTP responses, with support for timestamps, error logging, and custom adapters. Available as both ES6 modules and CommonJS, with no need for `.default` in ES module imports.
## Features
- **Framework Agnostic**: Compatible with Express, Fastify, or custom frameworks via adapters.
- **Standardized Responses**: Ensures consistent response structure across your API.
- **Configurable Options**: Customize response fields, timestamps, logging, and more.
- **Static Methods**: Send responses without instantiating the class.
- **Error Handling**: Built-in validation and logging for invalid configurations or response objects.
- **TypeScript Support**: Fully typed with included TypeScript declarations.
- **ES6 and CommonJS Support**: Use with `import` or `require`, no `.default` required for ES modules.
## Installation
Install the package via npm:
```bash
npm install http-reply
```
## Usage
### Importing the Package
The package supports both ES6 modules and CommonJS:
```javascript
// ES6 Module
import { HttpReply } from 'http-reply';
// CommonJS
const { HttpReply } = require('http-reply');
```
### Basic Example (Express)
Use `HttpReply` to send standardized responses in your Express or Fastify application.
```javascript
import { HttpReply } from 'http-reply';
import express from 'express';
const app = express();
app.get('/example', (req, res) => {
HttpReply.success(res, {
message: 'Operation successful',
data: { user: 'John Doe' },
metaData: { requestId: '12345' },
});
});
app.listen(3000, () => console.log('Server running on port 3000'));
```
### Centralized Configuration
Create a centralized `HttpReply` instance for consistent configuration across your application.
Create a file (e.g., `responder.js`):
```javascript
import { HttpReply } from 'http-reply';
const reply = new HttpReply({
includeTimestamp: true,
dateFormat: 'iso',
enableLogging: true,
customFields: { apiVersion: '1.0.0' },
});
export default reply;
```
Use it in your routes:
```javascript
import reply from './responder';
import express from 'express';
const app = express();
app.get('/example', (req, res) => {
reply.success(res, {
message: 'Custom response',
data: { id: 1 },
});
});
app.listen(3000, () => console.log('Server running on port 3000'));
```
### Static Methods
Use static methods for quick responses without instantiation:
```javascript
import { HttpReply } from 'http-reply';
HttpReply.created(res, {
message: 'User created',
data: { id: 123, name: 'Jane Doe' },
});
HttpReply.notFound(res, {
message: 'Resource not found',
error: 'Invalid ID',
});
```
### Supported Response Methods
`HttpReply` provides methods for common HTTP status codes:
| Method | Status Code | Description |
|----------------------|-------------|------------------------------------------|
| `success` | 200 | Successful request |
| `created` | 201 | Resource created successfully |
| `accepted` | 202 | Request accepted for processing |
| `noContent` | 204 | No content to return |
| `badRequest` | 400 | Invalid request |
| `unauthorized` | 401 | Authentication required |
| `forbidden` | 403 | Access denied |
| `notFound` | 404 | Resource not found |
| `conflict` | 409 | Resource conflict |
| `tooManyRequests` | 429 | Rate limit exceeded |
| `error` | 500 | Internal server error |
| `notImplemented` | 501 | Feature not implemented |
| `serviceUnavailable` | 503 | Service temporarily unavailable |
| `response` | Custom | Generic response with custom status code |
### Configuration Options
Customize `HttpReply` with the following options when creating an instance:
| Option | Type | Default | Description |
|--------------------|----------|----------|--------------------------------------------------------------------------|
| `includeTimestamp` | Boolean | `false` | Include a timestamp in the response (`iso` or `unix` format). |
| `includeCode` | Boolean | `true` | Include the status code in the response body. |
| `includeMessage` | Boolean | `true` | Include the message in the response body. |
| `includeError` | Boolean | `true` | Include error details in the response body. |
| `includeMetaData` | Boolean | `true` | Include metadata in the response body. |
| `enableLogging` | Boolean | `true` | Enable error logging for invalid configurations or response objects. |
| `stringify` | Boolean | `false` | Stringify the response body before sending (useful for custom adapters). |
| `customFields` | Object | `{}` | Additional fields to include in every response. |
| `dateFormat` | String | `'unix'` | Format for timestamps (`'iso'` or `'unix'`). |
| `adapter` | Function | `null` | Custom adapter for non-Express/Fastify frameworks. |
### Custom Adapter Example
For non-Express/Fastify frameworks, provide a custom adapter:
```javascript
import { HttpReply } from 'http-reply';
const reply = new HttpReply({
adapter: (res, statusCode, payload) => {
res.setStatusCode(statusCode);
res.setBody(payload);
return res;
},
});
reply.success(res, {
message: 'Custom adapter response',
data: { key: 'value' },
});
```
### Example Response Output
Using the `success` method with default configuration:
```javascript
HttpReply.success(res, {
message: 'User fetched',
data: { id: 1, name: 'John' },
metaData: { total: 1 },
});
```
Output:
```json
{
"message": "User fetched",
"data": { "id": 1, "name": "John" },
"metaData": { "total": 1 },
"code": 200
}
```
With `includeTimestamp: true` and `dateFormat: 'iso'`:
```json
{
"message": "User fetched",
"data": { "id": 1, "name": "John" },
"metaData": { "total": 1 },
"code": 200,
"timestamp": "2025-06-13T17:25:00.000Z"
}
```
## Dependencies
- Node.js >= 12.x
- Express or Fastify (optional, depending on your framework)
## Contributing
We welcome contributions! To contribute:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m 'Add your feature'`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a Pull Request.
Please ensure your code follows the project's coding standards and includes tests where applicable.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Contact
For questions or support, open an issue on the [GitHub repository](https://github.com/HarshDev1809/http-reply/issues) or contact the maintainer at [dev182000@gmail.com](mailto:dev182000@gmail.com).