Standard API responses for Node.js

Make every API reply predictable.

replyify gives your backend one clean response format for success, errors, validation, and pagination so frontend code and SDKs stop guessing.

Install See Before / After

Quick look

import { ok, apiError, paginate } from "@ironstack/replyify"

return ok(user)
throw apiError("NOT_FOUND", "User not found")
return paginate(users, { page: 1, limit: 10, total: 42 })

Problem

Backend responses drift fast.

Teams start simple, then every route returns a slightly different JSON shape. Errors become inconsistent, pagination changes per endpoint, and frontend consumers need special-case logic.

What developers keep writing

res.json(data)

res.status(400).json({ error })

throw new Error()

Solution

One response contract for every route.

replyify centralizes reply building, error normalization, status mapping, and Express integration while keeping the core framework agnostic.

What replyify encourages

return ok(user)

throw apiError("NOT_FOUND", "User not found")

return paginate(users, { page, limit, total })

Before / After

See the difference in one route.

Before

app.get("/users", async (req,res)=>{
  res.json(users)
})

After

app.get(
  "/users",
  replyHandler(async ()=>{
    return ok(users)
  })
)

Install

Add replyify to your project.

Install the package, then import the helpers you need from the root entry point or the Express subpath.

npm

npm install @ironstack/replyify

Usage

Start with the helpers that match your route.

Success replies

Wrap route results with ok() so every successful payload follows the same shape.

Error replies

Use fail() for non-throwing errors and apiError() when you want to throw.

Pagination

Use paginate() to attach page, limit, total, and pages in one consistent meta block.

Examples

Use replyify in real handlers.

Express example

import express from "express"
import { ok } from "@ironstack/replyify"
import { replyHandler, errorMiddleware } from "@ironstack/replyify/express"

const app = express()

app.get(
  "/users/:id",
  replyHandler(async (req) => {
    const user = { id: req.params.id, name: "Asha" }
    return ok(user)
  })
)

app.use(errorMiddleware())

Pagination example

import { paginate } from "@ironstack/replyify"

return paginate(users, {
  page: 1,
  limit: 10,
  total: 42,
  meta: { requestId: "req_123" }
})

Error example

import { apiError, validationError } from "@ironstack/replyify"

if (!req.body.name) {
  return validationError([
    { field: "name", message: "Required" }
  ])
}

if (!user) {
  throw apiError("NOT_FOUND", "User not found")
}

API

Public API surface

ok(data, message?, meta?)

Build a success reply result.

fail(code, message, errors?, meta?)

Build an error reply result without throwing.

paginate(data, options)

Build a paginated reply result with pagination metadata.

apiError(code, message, errors?, meta?)

Create an ApiError instance.

validationError(errors, message?)

Create a validation error reply result.

ApiError

Error class with code, status, errors, and meta.

replyHandler(fn)

Express wrapper that formats returned reply results automatically.

errorMiddleware()

Express middleware for normalizing and formatting thrown errors.