Package Exports

api-stds
api-stds/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (api-stds) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

api-stds

A lightweight utility library for standardized API responses, async error handling, and configuration-driven response formatting in Express.js applications.

Features

✅ Standardized JSON response format (successResponse, errorResponse)
✅ asyncHandler wrapper for safe async/await route handling
✅ ApiError class for consistent error throwing
✅ Middleware (standardize) to attach res.success and res.error methods
✅ Config-driven response metadata (timestamps, API version, etc.)
✅ Error registry support for consistent error codes/messages

Quick Start

npx api-stds init

This will set up the package in your project.

Usage

1. Middleware Setup

import express from "express";
import { standardize } from "api-stds";

const app = express();

// Apply standardize middleware
app.use(standardize());

This middleware extends the res object with:

res.success(data, meta?);
res.error(code, message?, details?, meta?);

2. Success Response

app.get("/ping", (req, res) => {
  return res.success({ pong: true });
});

Response:

{
  "success": true,
  "data": { "pong": true },
  "error": null,
  "meta": {
    "timestamp": 1734913293044,
    "apiVersion": "v1"
  }
}

3. Error Response

app.get("/error", (req, res) => {
  return res.error("NOT_FOUND", "Resource not found", { resource: "User" });
});

Response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": { "resource": "User" }
  },
  "meta": {
    "timestamp": 1734913293044,
    "apiVersion": "v1"
  }
}

4. Async Handler

import { asyncHandler, ApiError } from "api-stds";

app.get(
  "/users/:id",
  asyncHandler(async (req, res) => {
    const user = await User.findById(req.params.id);
    if (!user) throw new ApiError("NOT_FOUND", "User not found");
    return res.success(user);
  })
);

5. ApiError Class

import { ApiError } from "api-stds";

throw new ApiError("BAD_REQUEST", "Invalid input", [
  { field: "email", message: "Email is required" },
]);

6. Config

app.use(
  standardize({
    response: {
      includeMeta: true,
      timestampFormat: "iso", // "unix" | "iso"
      defaultApiVersion: "v2",
      metaFields: ["timestamp", "apiVersion"],
    },
  })
);

7. Error Registry

import { loadErrorRegistry, getError } from "api-stds";

loadErrorRegistry({
  NOT_FOUND: "The resource was not found",
  UNAUTHORIZED: "Unauthorized access",
});

res.error("NOT_FOUND", getError("NOT_FOUND"));

Response Format

{
  "success": boolean,
  "data": object | null,
  "error": {
    "code": string,
    "message": string,
    "details": any
  } | null,
  "meta": {
    "timestamp"?: number | string,
    "apiVersion"?: string
  }
}