@dudousxd/nestjs-client

The framework-neutral runtime for @dudousxd/nestjs-codegen output: a typed fetcher with pluggable transports and an optional superjson transformer. No Inertia dependency.

The code generated by @dudousxd/nestjs-codegen (api.ts) imports the Fetcher type from this package and runs on a Fetcher instance you pass into createApi(fetcher). This package provides that fetcher: it owns URL building, headers, error mapping (ApiHttpError), and the payload transformer, while the actual network call goes through a pluggable transport (native fetch by default).

Because the generated client calls into it at runtime, this is a normal dependency — not a devDependency. The Fetcher interface is fully generic (get<T>(path, opts?): Promise<T>), and that typed surface is what lets the generated client and query options infer response types. A missing or any-typed fetcher silently degrades the whole generated client to any.

Install

pnpm add @dudousxd/nestjs-client

Usage

Create a fetcher, then hand it to the createApi exported by your generated api.ts:

import { createFetcher } from '@dudousxd/nestjs-client';
import { createApi } from './api'; // generated by @dudousxd/nestjs-codegen

const fetcher = createFetcher({
  baseUrl: '/api',
  headers: () => ({ authorization: `Bearer ${getToken()}` }),
});

const api = createApi(fetcher);

The default transport is native fetch. The headers function is called once per request, so dynamic auth tokens always stay current.

Bring your own axios instance

Pass axiosTransport(http) to reuse an existing axios instance with its own interceptors, auth, and withCredentials:

import axios from 'axios';
import { createFetcher, axiosTransport } from '@dudousxd/nestjs-client';

const http = axios.create({ baseURL: '/api', withCredentials: true });

const fetcher = createFetcher({ transport: axiosTransport(http) });

Set the base URL on the axios instance (not createFetcher's baseUrl) so it isn't prefixed twice.

Global headers

setGlobalHeaders registers a function applied to every request across all fetchers — handy for app-wide auth or tracing headers:

import { setGlobalHeaders } from '@dudousxd/nestjs-client';

setGlobalHeaders(() => ({ authorization: `Bearer ${getToken()}` }));

superjson & transformer pipelines

A transformer is a { stringify, parse } pair. Pass superjson to round-trip rich types (Date, Map, Set, BigInt) — the server must use the same transformer:

import superjson from 'superjson';
import { createFetcher } from '@dudousxd/nestjs-client';

const fetcher = createFetcher({ transformer: superjson });

Pass an array to compose a pipeline with composeTransformers: a base value↔string serializer first, then string↔string wrappers (compression, encryption) applied left-to-right on stringify and unwound right-to-left on parse:

import superjson from 'superjson';
import { createFetcher } from '@dudousxd/nestjs-client';
import { compress } from './my-compress'; // { stringify, parse } over strings

const fetcher = createFetcher({ transformer: [superjson, compress] });

Errors

Non-2xx responses reject with an ApiHttpError carrying status, statusText, and the parsed body, plus isUnauthorized / isForbidden / isNotFound / isClient / isServer helpers:

import { ApiHttpError } from '@dudousxd/nestjs-client';

try {
  await api.users.get({ params: { id } });
} catch (err) {
  if (err instanceof ApiHttpError && err.isNotFound) {
    // handle 404
  }
}

The Fetcher contract

The generated client depends on this typed surface — keep T generic so response types flow through:

interface Fetcher {
  get<T>(path: string, opts?: RequestOpts): Promise<T>;
  post<T>(path: string, opts?: RequestOpts): Promise<T>;
  put<T>(path: string, opts?: RequestOpts): Promise<T>;
  patch<T>(path: string, opts?: RequestOpts): Promise<T>;
  delete<T>(path: string, opts?: RequestOpts): Promise<T>;
}

createFetcher returns a value of this exact shape. Any object that satisfies the Fetcher interface works — which is why frameworks with their own client can supply a compatible createFetcher (see below).

How it fits with @dudousxd/nestjs-codegen

@dudousxd/nestjs-codegen is the codegen half — it runs in dev/CI and emits a fully typed api.ts from your NestJS controllers. That generated file imports the Fetcher type from this package and exposes a createApi(fetcher) factory.

@dudousxd/nestjs-client is the runtime half — the dependency the generated client actually executes against. You install it in your app, build a fetcher with createFetcher, and pass it to createApi.

Frameworks that ship their own client (for example @dudousxd/nestjs-inertia-client) expose a compatible createFetcher that produces a Fetcher-shaped object, so the same generated client runs unchanged on top of them.

Documentation

• Fetcher & Transports — createFetcher, custom transports, and serializers.
• Repository

License

MIT