Generic, extendible REST template for NestJS projects.
npm install nestjs-restcallReusable REST client utilities for NestJS applications. nestjs-restcall provides an extendible AbstractRestTemplate class plus a default RestTemplateService, making it simple to wrap upstream HTTP APIs with consistent error handling, auth hooks, and reusable helpers.
- 🔁 Shared request pipeline across verbs (GET, POST, etc.) with typed overloads
- 🛡️ Centralized error translation via mapAndThrowError
- 🔐 Pluggable auth/token handling using RequestContext
- 🧰 Helper utilities for query strings and validation
``bash`
npm install nestjs-restcall
If you are using Yarn or pnpm, install via yarn add nestjs-restcall or pnpm add nestjs-restcall.
Register the provided module, then inject the ready-to-use RestTemplateService anywhere you need to make outbound HTTP calls.
`ts
// src/app.module.ts
import { Module } from '@nestjs/common';
import { RestTemplateModule } from 'nestjs-restcall';
@Module({
imports: [RestTemplateModule],
})
export class AppModule {}
`
`ts
// Some service or controller
import { Injectable } from '@nestjs/common';
import { RestTemplateService } from 'nestjs-restcall';
@Injectable()
export class PaymentsService {
constructor(private readonly rest: RestTemplateService) {}
async fetchPayment(id: string) {
return this.rest.get);`
}
}
`ts`
await this.rest.get
params: { limit: 50 },
headers: { 'X-Trace-Id': ctx.traceId },
context: { token: userToken, requestId: ctx.traceId },
});
Most projects will subclass AbstractRestTemplate to customize auth, headers, or error handling.
`ts
import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
import {
AbstractRestTemplate,
RequestContext,
UpstreamErrorBody,
} from 'nestjs-restcall';
@Injectable()
export class PaymentsRestTemplate extends AbstractRestTemplate {
protected getDefaultHeaders() {
return {
Accept: 'application/json',
'Content-Type': 'application/json',
} as const;
}
protected async applyAuth(config, context?: RequestContext) {
if (!context?.token) return config;
return {
...config,
headers: {
...(config.headers ?? {}),
Authorization: Bearer ${context.token},
},
};
}
protected mapAndThrowError(error: unknown): never {
const upstream = error as { response?: { status?: number; data?: UpstreamErrorBody } };
const status = upstream.response?.status ?? HttpStatus.BAD_GATEWAY;
throw new HttpException(
{
message: upstream.response?.data?.message ?? 'Upstream request failed',
code: upstream.response?.data?.code ?? 'UPSTREAM_ERROR',
details: upstream.response?.data?.details,
},
status,
);
}
}
`
Provide your subclass via Nest DI as needed (e.g., register it in a feature module, use it instead of the default RestTemplateService, or wrap it with domain-specific methods).
The package re-exports utility helpers and types to keep integrations strongly typed:
- buildUrl(url, params) – append primitive query paramsassertNonEmpty(value, label)
- – guard string argumentsRequestContext
- and RestRequestOption interfaces – consistent context typingTokenProvider
- interface – handshake around caching and refreshing auth tokens
Import them directly from the package root:
`ts`
import { buildUrl, RequestContext, TokenProvider } from 'nestjs-restcall';
Local scripts assume Node.js 18+:
`bashInstall deps
npm install
The
test script disables Watchman to stay CI-friendly. Unit coverage lives in src/rest-template/services/rest-template.service.spec.ts; expand the suite as you add features.CI & Publishing
-
.github/workflows/test.yml runs linting and tests on every pull request and pushes to main/master.
- .github/workflows/publish.yml executes lint, tests, build, and npm publish when a release is published or a version tag is pushed. Configure the NPM_TOKEN` secret in your repository settings before triggering a publish.MIT © 2025 rest-call contributors