TypeScript utilities for standardized API responses
npm install @naman_deep_singh/http-responseVersion: 3.3.4
A flexible, framework-agnostic TypeScript response utility library for building consistent, typed, and configurable API responses.
Designed with a clean core + adapter architecture.
First-class support for Express.js, pagination, and standardized HTTP status handling.
---
| Feature | Status |
|---------------------------------------------|:------:|
| Fully typesafe response envelopes | ā
|
| Framework-agnostic core | ā
|
| Express.js responder adapter | ā
|
| Express middleware injection | ā
|
| Pagination helpers | ā
|
| Centralized responder configuration | ā
|
| HTTP status constants | ā
|
---
```sh
npm install @naman_deep_singh/http-response
š Response Envelope (Default Shape)
interface ResponseEnvelope
> {
success: boolean
message?: string
data?: P
error: {
message: string
code?: string
details?: unknown
} | null
meta: M | null
}
š ļø Usage
ā Framework-Agnostic (No Express)
import { BaseResponder } from '@naman_deep_singh/http-response'
const responder = new BaseResponder()
const result = responder.ok({ user: 'John' }, 'Loaded')
// When no sender is attached, returns:
// { status: 200, body: ResponseEnvelope }
console.log(result)
š Express Integration
1ļøā£ Register Middleware
import express from 'express'
import { responderMiddleware } from '@naman_deep_singh/http-response'
const app = express()
app.use(responderMiddleware())
This injects a res.responder() factory into every request.
2ļøā£ Controller Usage
app.get('/user', (req, res) => {
const responder = res.responder<{ id: number; name: string }>()
responder.okAndSend(
{ id: 1, name: 'John Doe' },
'User found'
)
})
ā
okAndSend() automatically:
sets HTTP status
sends JSON response
returns void for clean controller ergonomics
āļø Middleware Configuration
app.use(
responderMiddleware({
timestamp: true,
extra: { service: 'user-service' },
})
)
Example response:
{
"success": true,
"data": { ... },
"error": null,
"meta": {
"timestamp": "2025-11-22T12:00:00Z"
},
"service": "user-service"
}
š¢ Pagination Support
responder.paginateAndSend(
[{ id: 1 }],
1, // page
10, // limit
42, // total
'Loaded'
)
Pagination metadata is automatically calculated.
š Available Methods
ā
Success Responses
Method HTTP
ok() 200
created() 201
noContent() 204
paginate() 200
Each method has an Express variant:
okAndSend()
createdAndSend()
paginateAndSend()
ā Error Responses
Method HTTP
badRequest() 400
unauthorized() 401
forbidden() 403
notFound() 404
conflict() 409
unprocessableEntity() 422
tooManyRequests() 429
serverError() 500
Each also has a *AndSend() variant.
š§© HTTP Status Constants
import { HTTP_STATUS } from '@naman_deep_singh/http-response'
HTTP_STATUS.SUCCESS.OK // 200
HTTP_STATUS.CLIENT_ERROR.NOT_FOUND // 404
HTTP_STATUS.SERVER_ERROR.INTERNAL_SERVER_ERROR // 500
Categories
SUCCESS
REDIRECTION
CLIENT_ERROR
SERVER_ERROR
ā Object.freeze() protected
ā Fully literal-typed (as const)
ā IDE autocomplete friendly
š§© TypeScript: Express Response Augmentation (Recommended)
For full type safety, add this once in your project:
import type { ExpressResponder } from '@naman_deep_singh/http-response'
declare global {
namespace Express {
interface Response {
responder:
() => ExpressResponder
}
}
}
ā ļø Do not use for new projects.
š Integration with Other Packages
With @naman_deep_singh/server
import { responderMiddleware } from '@naman_deep_singh/http-response'
server.app.use(responderMiddleware())
With @naman_deep_singh/errors
import { expressErrorHandler } from '@naman_deep_singh/errors'
server.app.use(expressErrorHandler)
Provides consistent error responses across services.
š Roadmap
Fastify adapter
Hono adapter
Configurable envelope key mapping
š License
MIT Ā© Naman Deep Singh