v1.2.0 • Lightweight • Type-Safe

clean-response

Standardize API responses with type-safe, lightweight functions.
Works like your response formatter. Add, update, and remove with clean functions you already know.

$npm install @leviosary/clean-response

import { success, error, paginate } from '@leviosary/clean-response'
return success(data, "User created")

GitHub npm

0 dependencies

<1KB minified

TypeScript

Features

Everything you need

Built for developers who value simplicity and type safety

Type-Safe

TypeScript Support

Full TypeScript support with comprehensive type definitions for IntelliSense and autocomplete.

< 1KB

Lightweight

Zero dependencies. Tiny bundle size under 1KB minified.

Universal

Framework Ready

Works seamlessly with Express, Fastify, and vanilla Node.js applications.

Simple

Clean API

Simple, intuitive functions that just work. No boilerplate required.

Example

Usage in Express.js

See how easy it is to integrate clean-response into your API

Example: REST API with clean-response

import { success, error, paginate } from '@leviosary/clean-response'
// Success response
app.get('/users/:id', (req, res) => {
  const user = await findUser(req.params.id)
  return res.json(success(user, 'User retrieved successfully'))
})
// Error response
app.delete('/users/:id', (req, res) => {
  const deleted = await deleteUser(req.params.id)
  if (!deleted) {
    return res.status(404).json(error('User not found', 404))
  }
  return res.json(success(null, 'User deleted'))
})
// Paginated response
app.get('/users', (req, res) => {
  const { page = 1, limit = 10 } = req.query
  const { users, total } = await getUsers(page, limit)
  return res.json(paginate(users, {
    page: Number(page),
    perPage: Number(limit),
    total,
    totalPages: Math.ceil(total / limit)
  }))
})

More Examples

Works with any framework

Different frameworks & use cases

Express.js

Error Handling

Handle errors consistently with proper status codes

import { success, error } from '@leviosary/clean-response'

app.get('/users/:id', async (req, res) => {
  try {
    const user = await findUser(req.params.id)

    if (!user) {
      return res
        .status(404)
        .json(error('User not found', 404))
    }

    return res.json(success(user, 'User retrieved'))
  } catch (err) {
    return res
      .status(500)
      .json(error('Internal server error', 500))
  }
})

Express.js

Pagination

Return paginated data with metadata

import { paginate } from '@leviosary/clean-response'

app.get('/users', async (req, res) => {
  const { page = 1, limit = 10 } = req.query

  const { users, total } = await getUsers({
    page: Number(page),
    limit: Number(limit),
  })

  return res.json(paginate(users, {
    page: Number(page),
    perPage: Number(limit),
    total,
    totalPages: Math.ceil(total / limit),
  }))
})

Fastify

Fastify Integration

Works seamlessly with Fastify framework

import { success, error } from '@leviosary/clean-response'

fastify.get('/users/:id', async (request, reply) => {
  const user = await findUser(request.params.id)

  if (!user) {
    return reply
      .status(404)
      .send(error('User not found', 404))
  }

  return reply.send(success(user))
})

Node.js HTTP

Vanilla Node.js

Use with any Node.js HTTP server

import { success, error } from '@leviosary/clean-response'
import { createServer } from 'http'

const server = createServer(async (req, res) => {
  // Set headers
  res.setHeader('Content-Type', 'application/json')

  if (req.method === 'GET' && req.url === '/api/users') {
    const users = await getUsers()

    // Send success response
    res.end(JSON.stringify(success(users)))
  } else {
    // Send error response
    res.statusCode = 404
    res.end(JSON.stringify(error('Route not found', 404)))
  }
})

server.listen(3000)

How It Works

Response structure

All responses follow a consistent, predictable structure

success(data, message)

Success Response

Standard success response with data and optional message

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "message": "User created successfully"
}

error(message, statusCode)

Error Response

Error response with message and HTTP status code

{
  "success": false,
  "error": "User not found",
  "statusCode": 404
}

paginate(data, options)

Paginated Response

Paginated data with metadata for easy frontend handling

{
  "success": true,
  "data": [
    { "id": 1, "name": "Item 1" },
    { "id": 2, "name": "Item 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 100,
    "totalPages": 10
  }
}

Your frontend knows exactly what to expect! 🎯

Interactive Demo

Try it yourself

See how your API responses will look in real-time

Select Function

Data (JSON)

Enter the data you want to return

Success Message

Optional success message

Output

Real-time

Generated API response

{
  "success": true,
  "message": "User retrieved successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "timestamp": "2026-09-07T04:12:14.139Z"
}

Quick Start

Get up and running in seconds

Three simple steps to standardize your API responses

Step 1

Install the package

Add clean-response to your project

npm install @leviosary/clean-response

Step 2

Import functions

Import the helper functions you need

import { success, error, paginate } from '@leviosary/clean-response'

Step 3

Use in your routes

Start standardizing your API responses

// Success response
res.json(success(user, "User created"))

// Error response
res.json(error("User not found", 404))

// Paginated response
res.json(paginate(users, page, limit))

That's it! Your API responses are now standardized. 🎉

Why This Package

Problem solved

Say goodbye to inconsistent API responses

before

Inconsistent response formats

res.send({ data: user, status: 'ok' })
res.json({ success: true, result: user })
res.json({ user, timestamp: Date.now() })

after

Consistent, predictable responses

res.json(success(user))