api-res-kit

Standardize your Node.js API responses with a consistent, type-safe format.

The Problem

Every endpoint returns a different format:

{ "status": true, "result": {} }
{ "success": true, "data": {} }
{ "ok": 1, "payload": {} }

The Solution

One standard format for every response:

{
  "success": true,
  "message": "User created successfully",
  "data": {},
  "errors": [],
  "meta": {}
}

Installation

npm install api-res-kit

Quick Start

import express from "express"
import { success, error, created, notFound, validationError, paginated } from "api-res-kit"

const app = express()

// Success
app.get("/users", async (req, res) => {
  const users = await User.find()
  success(res, { data: users })
})

// Created
app.post("/users", async (req, res) => {
  const user = await User.create(req.body)
  created(res, { data: user, message: "User created" })
})

// Not Found
app.get("/users/:id", async (req, res) => {
  const user = await User.findById(req.params.id)
  if (!user) return notFound(res, "User not found")
  success(res, { data: user })
})

// Validation Error
app.post("/login", async (req, res) => {
  validationError(res, [
    { field: "email", message: "Email is required" },
    { field: "password", message: "Minimum 8 characters" }
  ])
})

// Pagination
app.get("/posts", async (req, res) => {
  const page = parseInt(req.query.page as string) || 1
  paginated(res, { data: posts, page, perPage: 20, total: 100 })
})

API Reference

Success Responses

| Function | Status Code | Description | |----------|------------|-------------| | success(res, options?) | 200 | Standard success response | | created(res, options?) | 201 | Resource created | | noContent(res) | 204 | No content to return |

Error Responses

| Function | Status Code | Description | |----------|------------|-------------| | error(res, options?) | 500 | Generic error | | notFound(res, message?) | 404 | Resource not found | | unauthorized(res, message?) | 401 | Authentication required | | forbidden(res, message?) | 403 | Access denied |

Validation

validationError(res, [
  { field: "email", message: "Email is required" },
  { field: "age", message: "Must be 18+", code: "MIN_AGE" }
])

Response (422):

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    { "field": "email", "message": "Email is required", "code": "VALIDATION_ERROR" },
    { "field": "age", "message": "Must be 18+", "code": "MIN_AGE" }
  ],
  "meta": {}
}

Pagination

paginated(res, {
  data: users,
  page: 2,
  perPage: 10,
  total: 50
})

Response:

{
  "success": true,
  "message": "Success",
  "data": [...],
  "errors": [],
  "meta": {
    "pagination": {
      "page": 2,
      "perPage": 10,
      "total": 50,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPrevPage": true
    }
  }
}

Framework Adapters

Express Middleware

import { apiResponseMiddleware } from "api-res-kit/adapters/express"

app.use(apiResponseMiddleware())

app.get("/users", (req, res) => {
  res.apiSuccess({ data: users })
  res.apiNotFound("User not found")
  res.apiValidationError([{ field: "email", message: "Required" }])
  res.apiPaginated({ data: users, page: 1, total: 100 })
})

NestJS Interceptor

import { ApiResponseInterceptor } from "api-res-kit/adapters/nestjs"

@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: ApiResponseInterceptor }
  ]
})
export class AppModule {}

Fastify Plugin

import apiResponsePlugin from "api-res-kit/adapters/fastify"

fastify.register(apiResponsePlugin)

fastify.get("/users", async (req, reply) => {
  reply.apiSuccess({ data: users })
})

TypeScript Support

All functions are fully typed with generics:

interface User {
  id: number
  name: string
}

success<User>(res, { data: { id: 1, name: "Alice" } })
paginated<User>(res, { data: users, page: 1, total: 50 })

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

License

MIT