@rtorcato/api-response

api-common

A monorepo of reusable Node.js library packages for building API projects. Targets Express, Hono, and other Node HTTP frameworks. Each package under packages/ is independently consumable.

The old single-package repo lives at https://gitlab.com/rtorcato/api-common and is being broken up and migrated here.

Stack

• pnpm workspaces
• TypeScript (configs extend @rtorcato/js-tooling)
• Vitest for tests
• Biome for lint + format
• Husky + commitlint (conventional commits) on commit
• GitHub Actions for CI + CodeQL, Dependabot for updates

Packages

Package	npm	Description
@rtorcato/api-amqp		Typed amqplib publisher/consumer helpers for RabbitMQ — JSON encoding, exchange/queue assertion, and ack/nack handling.
@rtorcato/api-auth		Framework-agnostic JWT sign/verify helpers with Bearer-header and cookie token extraction.
@rtorcato/api-auth-express		Express middleware for @rtorcato/api-auth — JWT authentication with Bearer-header and cookie support.
@rtorcato/api-auth-hono		Hono middleware for @rtorcato/api-auth — JWT authentication with Bearer-header and cookie support.
@rtorcato/api-config		Load and validate environment variables with dotenv + zod for Node API projects.
@rtorcato/api-cors-express		Express CORS middleware with sane defaults (credentials, standard methods, preflight).
@rtorcato/api-errors		Framework-agnostic HTTP error classes for Node.js APIs.
@rtorcato/api-errors-express		Express middleware for @rtorcato/api-errors (error handler + not-found handler).
@rtorcato/api-errors-hono		Hono middleware for @rtorcato/api-errors (error handler + not-found handler).
@rtorcato/api-express-utils		Small Express utility helpers: client IP extraction and route logging.
@rtorcato/api-graceful-shutdown		Framework-agnostic graceful shutdown for Node API servers — SIGTERM/SIGINT drain with ordered cleanup hooks and a hard timeout.
@rtorcato/api-health		Framework-agnostic liveness/readiness health-check registry for Node API projects.
@rtorcato/api-health-express		Express liveness/readiness probe handlers for @rtorcato/api-health.
@rtorcato/api-health-hono		Hono liveness/readiness probe handlers for @rtorcato/api-health.
@rtorcato/api-http		Typed HTTP client over native fetch — base URL, default headers, timeout, and errors normalized to @rtorcato/api-errors.
@rtorcato/api-logger		Framework-agnostic pino logger factory for Node API projects.
@rtorcato/api-openapi		Framework-agnostic OpenAPI 3.1 helpers — generate Scalar docs HTML from a spec object.
@rtorcato/api-openapi-express		Express router that serves Scalar API docs from an OpenAPI spec object.
@rtorcato/api-openapi-hono		Hono adapter for schema-first OpenAPI docs — wires @hono/zod-openapi and serves the Scalar API reference UI.
@rtorcato/api-rate-limit		Framework-agnostic in-memory sliding-window rate limiter for Node API projects.
@rtorcato/api-rate-limit-express		Express middleware for @rtorcato/api-rate-limit (sliding-window rate limiter).
@rtorcato/api-rate-limit-hono		Hono middleware for @rtorcato/api-rate-limit (sliding-window rate limiter).
@rtorcato/api-response		Consistent success-response envelope and zod schema helper for Node API projects.
@rtorcato/api-testing		Test helpers for API projects: supertest re-export, JWT auth fixtures, and response assertion matchers.
@rtorcato/api-ts-rest-express		Mount a ts-rest contract on Express and serve its OpenAPI docs (Scalar) — wires @ts-rest/express + @ts-rest/open-api into api-common.
@rtorcato/api-upload		Promise-based S3 file upload for Express via multer-s3 — public/private ACL, cache-control, deterministic keys, typed errors.
@rtorcato/api-validation		Zod request validation helpers with pretty error formatting for Node API projects.

Install

pnpm add @rtorcato/api-errors                       # error classes only
pnpm add @rtorcato/api-errors @rtorcato/api-errors-express express
pnpm add @rtorcato/api-errors @rtorcato/api-errors-hono hono

Per-package READMEs (on npm and in each packages/*/README.md) carry the usage examples.

Releases

Versioning + publishing is automated via Changesets. To propose a release:

pnpm changeset           # describe what changed, pick affected packages + bump type
git commit -am "feat: …"
git push                 # the Release workflow opens a "Version Packages" PR

Merging the auto-PR bumps versions, writes per-package CHANGELOG.md, and publishes to npm. The same merge redeploys the docs site automatically (the Deploy Docs workflow runs on any packages/** change), so changelogs and the generated API reference stay current — no manual docs step. READMEs use unversioned install commands, so they only need editing when a package's API changes, not on every release.

Commands

Run from the repo root.

pnpm install                              # install workspace deps
pnpm -r build                             # build every package
pnpm -r test                              # test every package
pnpm -r typecheck                         # typecheck every package
pnpm --filter <pkg-name> <script>         # run a script in one package
pnpm check                                # biome lint + format check
pnpm check:fix                            # biome lint + format autofix

Adding a new package

Use the /new-package skill so the new package matches existing conventions (tsconfig extends, exports map, vitest config, scripts). Framework deps (Express, Hono) go in peerDependencies so consumers control the version.

The Packages table above is generated from each package.json — run pnpm gen:readme after adding a package or changing a description. CI (pnpm check:readme) fails if it's stale.

Conventions

• Packages must be framework-agnostic where possible. Framework-specific helpers live in their own package (e.g. api-errors is generic, api-errors-express is the adapter).
• Public API is whatever a package's exports field exposes. Internal modules are not part of the contract.
• Conventional commits are enforced by commitlint.