Skip to main content

api-common

A family of reusable packages for building Node.js APIs. Each is independently consumable, framework-agnostic where possible, and ships thin Express and Hono adapters as peer dependencies so you control the framework version.

  • @rtorcato/api-errors — framework-agnostic HttpError base class plus BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, and InternalServerError, each carrying a status and machine-readable code. Express and Hono adapters (errorHandler + notFoundHandler) turn thrown errors into a consistent JSON response.
  • @rtorcato/api-auth — JWT sign/verify/extract, with an Express adapter for auth and optional-auth middleware.
  • @rtorcato/api-rate-limit — in-memory sliding-window rate limiter with Express and Hono middleware.
  • @rtorcato/api-validation — zod request validation that throws a BadRequestError on failure.
  • @rtorcato/api-response — ok() success envelope, the counterpart to the error shape.
  • @rtorcato/api-config — load and validate env vars with dotenv + zod at startup.
  • @rtorcato/api-logger — pino logger factory: pretty in dev, JSON in production.
  • @rtorcato/api-openapi — Swagger UI and Scalar HTML generators, with an Express adapter to serve them.
  • @rtorcato/api-cors-express and @rtorcato/api-express-utils — CORS middleware and small Express helpers (client IP, route listing).

The error adapters emit the same response body, so switching frameworks (or running both) keeps your error contract identical:

{ "error": "NotFoundError", "code": "not_found", "message": "User not found" }

The framework (express / hono) is a peer dependency of each adapter — you control the version.

Quick example​

import { NotFoundError } from '@rtorcato/api-errors'
import { errorHandler, notFoundHandler } from '@rtorcato/api-errors-express'

app.get('/users/:id', (req, res) => {
	const user = db.find(req.params.id)
	if (!user) throw new NotFoundError('User not found')
	res.json(user)
})

app.use(notFoundHandler) // 404 for unmatched routes
app.use(errorHandler()) // maps thrown HttpErrors to JSON

Start with Installation, then the Express or Hono guide. The full API Reference is generated from the package sources.