@buildvision/nest-sdk-generator 2.3.0 → 3.0.0

package/README.md

@@ -1,353 +1,516 @@
-# nest-sdk-generator by [![](https://user-images.githubusercontent.com/73881870/130991041-a4a1f0f4-21f5-4a54-a085-974f80f56ed2.png)](https://lonestone.io/)
+# @buildvision/nest-sdk-generator
 
-[![](https://img.shields.io/npm/v/nest-sdk-generator)](https://www.npmjs.com/package/nest-sdk-generator)
+[![npm](https://img.shields.io/npm/v/@buildvision/nest-sdk-generator)](https://www.npmjs.com/package/@buildvision/nest-sdk-generator)
+[![Test](https://github.com/build-vision/nest-sdk-generator/actions/workflows/test.yml/badge.svg)](https://github.com/build-vision/nest-sdk-generator/actions/workflows/test.yml)
 
-`nest-sdk-generator` is a tool that allows you to build automatically and in seconds a SDK for client applications to consume a NestJS server's API.
+Generate a fully-typed [RTK Query](https://redux-toolkit.js.org/rtk-query/overview) API client from your NestJS controllers.
 
-The project is split in two parts:
+The generator reads your API's source code with the TypeScript compiler: no running server, no OpenAPI spec, no decorators to add. Every route becomes an RTK Query endpoint whose arguments and result are typed from the controller itself, including return types TypeScript infers from your services.
 
-- The **analyzer** looks for all modules, controllers, methods and types in the NestJS server, and builds a JSON schema containing all informations
-- The **generator** takes this JSON schema and generates a directory containing the SDK
-
-The project has been created and is currently maintained by our developers at [Lonestone](https://lonestone.io/).
-
-For a quick glance at performances, check [here](#how-fast-is-it).
+```ts
+// API: users.controller.ts
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async getUser(@Param('id') id: string) {
+    return this.usersService.findOne(id) // Promise<User | null>
+  }
+
+  @Patch(':id')
+  renameUser(@Param('id') id: string, @Body('name') name: string) { ... }
+}
+```
 
-**Table of contents:**
+```tsx
+// Client: a React component
+const { data: user } = API.Users.getUser.useQuery({ id }) // user: User | null | undefined
+const [renameUser] = API.Users.renameUser.useMutation()
 
-- [What is nest-sdk-generator and why should I use it?](#what-is-nest-sdk-generator-and-why-should-i-use-it)
-- [Quick usage example](#quick-usage-example)
-- [How fast is it?](#how-fast-is-it)
-- [Features](#features)
-- [Limitations](#limitations)
-- [Using the SDK](#using-the-sdk)
-- [Architecture](#architecture)
-- [Step-by-step generation tutorial](#step-by-step-generation-tutorial)
-    - [Recommandations](#recommandations)
-- [SDK usage](#sdk-usage)
-    - [Importing API types](#importing-api-types)
-  - [External files](#external-files)
-- [Configuration options](#configuration-options)
-- [Magic types](#magic-types)
-- [Frequently-asked questions](#frequently-asked-questions)
-  - [Does this replace Swagger?](#does-this-replace-swagger)
-  - [I have a GraphQL API, what can this project do for me?](#i-have-a-graphql-api-what-can-this-project-do-for-me)
-  - [Does the SDK has any performance overhead?](#does-the-sdk-has-any-performance-overhead)
-  - [How do I update the SDK once I change the API's source code?](#how-do-i-update-the-sdk-once-i-change-the-apis-source-code)
-  - [Is the SDK documented?](#is-the-sdk-documented)
-  - [Can I add header or other data on-the-fly when making requests?](#can-i-add-header-or-other-data-on-the-fly-when-making-requests)
-  - [Is there a way to log the requests or responses somewhere?](#is-there-a-way-to-log-the-requests-or-responses-somewhere)
-  - [Does the API server needs to be running to generate a SDK?](#does-the-api-server-needs-to-be-running-to-generate-a-sdk)
-  - [Can I fork this project to make my own version of it?](#can-i-fork-this-project-to-make-my-own-version-of-it)
-  - [Can I use this project in commercial software?](#can-i-use-this-project-in-commercial-software)
-- [License](#license)
-
-## What is nest-sdk-generator and why should I use it?
-
-nest-sdk-generator is a tool that creates a client-side SDK based on a NestJS REST API. The SDK can be used to call the API's routes seamlessly without any friction, and also enforces type safety by typing all parameters and return values based on the API itself.
-
-This brings several advantages, including:
-
-- Missing or bad parameters and return types will be detected at compilation time
-- IDE autocompletion for parameters and return values without needing to look at the doc
-- All API routes are listed in a single block allowing to list all at once
-- Routes are split across controllers, themselves split across modules, keeping the same hierarchy as your API even if the routes don't
-- Global request and response handler acting as the main request actor, allowing to customize requests by providing additional values like headers if required
-- Simple & clean placeholders for server-side types that can't be ported to client-side (e.g. ORM dictionary types)
-
-The generator also allows you to (re-)generate a full SDK in seconds with a single command. And in case something goes wrong, you'll be able to pinpoint exactly what the problem is thanks to the colorful (can be disabled) verbose output. A log file can also be used to store all output informations in one place.
-
-## Quick usage example
-
-The SDK generator only requires you to create a small JSON configuration file to indicate where you API is located at, and to run a simple `npx nest-sdk-generator <path to the configuration file>` command. This will generate a client-side SDK hierarchised in modules, controllers and methods that will allow you to call your API's routes without manually writing the URIs yourself. The query parameters and body content is also strictly typed and automatically converted to be sent to your API.
-
-Calling methods will look like this:
-
-```typescript
-import { userController } from "../sdk/userModule"
-import { articleController } from "../sdk/articleModule"
-
-const user = await userController.profile({ username: "jack" })
-
-const userArticles = await articleController.getAll({ author: user.id })
-
-const user = await articleController.publish({}, {
-  author: user.id,
-  content: `${user.pseudo} has already published ${userArticles.length} articles!`
-})
+renameUser({ id, name: 'Jane' }) // PATCH /users/:id with body { name }
+renameUser({ id }) // Type error: `name` is missing
 ```
 
-You can find a complete demonstration API in the [`demo/server`](demo/server) directory, as well as a frontend using a SDK based on this API in [`demo/front`](demo/front). The SDK configuration is located in [`demo/front/sdk-generator.json`](demo/front/sdk-generator.json).
+**Contents**
+
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+- [How controllers become endpoints](#how-controllers-become-endpoints)
+- [Generated files](#generated-files)
+- [Configuration](#configuration)
+- [The request function](#the-request-function)
+- [Adding caching (tags)](#adding-caching-tags)
+- [Command line](#command-line)
+- [Analysis engines](#analysis-engines)
+- [Recommended workflow](#recommended-workflow)
+- [Limitations](#limitations)
+- [Troubleshooting](#troubleshooting)
+- [Plain SDK mode (`--generate`)](#plain-sdk-mode---generate)
+- [Upgrading from 2.x](#upgrading-from-2x)
+- [Development](#development)
+- [Credits and license](#credits-and-license)
 
-## How fast is it?
+## Requirements
 
-On our internal test project, with 20 controllers and 80 routes, the full process takes 3 seconds (from a cold start) on a Core i7-8750H (6-core laptop CPU from 2018) to generate 84 file with 2246 lines of code.
+- **A NestJS API written in TypeScript** with a `tsconfig.json`
+- **A client that can see the API's source code** (typically a monorepo): generated files import your DTOs and entities directly from the API's source with `import type`, so the client's TypeScript project must be able to type-check those files (see [Client TypeScript setup](#client-typescript-setup))
+- **Redux Toolkit 2.x** with React (`@reduxjs/toolkit/query/react`) in the client
+- **Node.js 20.19+ or 22.12+** to run the generator (older versions fall back to a slower [engine](#analysis-engines))
 
-The duration should be roughly proportional to the quantity of routes and DTOs you use in your application, although on very small applications in usually won't go below 2 seconds on such a CPU.
+## Getting started
 
-## Features
+The examples assume a monorepo with the API in `api/` and a React app in `web/`.
 
-- Full support for idiomatic NestJS modules and controllers
-- Recursive extraction of types controllers depend on, including types located in `node_modules`
-- Can extract classes, interfaces, enumerations and type aliases
-- Fully compatible with WSL, even if packages are installed using symbolic links from Windows
-- Compatible with alternative package managers like PNPM
-- Extremely detailed output by default for easier debugging in case of errors
-- Tree-shaking so the compiled code will only contain the methods you use from the generated SDK, no matter its size
+### 1. Install
 
-## Limitations
+```sh
+cd web
+npm install --save-dev @buildvision/nest-sdk-generator
+```
 
-nest-sdk-generator comes with a set of limitations which can find below:
+### 2. Create a configuration file
 
-1. nest-sdk-generator does not check if the source files compile correctly. Therefore, if you try to use a type that doesn't exist, the generation may still succeed although compiling the code would fail. In such case, the resulting output type is `any`.
+`web/api-gen.config.json` (paths are relative to this file):
 
-2. A current limitation of nest-sdk-generator is that it finds a controller's module by looking for a `.module.ts` file in the current directory, and parent directories if none is found in the controller's one. This means controller files must be put under a module's directory, and two module files cannot be put in the same directory.
+```json
+{
+  "apiInputPath": "../api",
+  "sdkOutputPath": "./src/api/endpoints",
+  "sdkInterfacePath": "./src/api/BaseRequest.ts",
+  "generateTimestamps": false,
+  "controllerOutput": {
+    "fileName": { "removeSuffix": ".controller", "addSuffix": ".endpoints" },
+    "exportName": { "removeSuffix": "Controller", "addSuffix": "Endpoints" },
+    "endpointGroupName": { "removeSuffix": "Controller" }
+  }
+}
+```
 
-3. Types belonging to namespaces are currently not supported and will result in error in the generated code
+All options are described in [Configuration](#configuration).
 
-4. Due to limitations of the TypeScript compiler, importing from the project's root (e.g. `import { SomeType } from "src/file.ts"` instead of `import { SomeType } from "../file.ts"`) will result in an `any` type at generation, because such types are not recognized when manipulating types. If you want to avoid this behaviour in Visual Studio Code, you can add `"typescript.preferences.importModuleSpecifier": "relative"` to your settings.
+### 3. Write the request function
 
-## Using the SDK
+Every endpoint calls a single function you own, which performs the HTTP request: this is where the base URL, authentication and error handling live. Create the file `sdkInterfacePath` points to (see [The request function](#the-request-function) for a complete example):
 
-The SDK exposes several directories:
+```ts
+// web/src/api/BaseRequest.ts
+import type { BaseQueryFn } from '@reduxjs/toolkit/query'
+
+export type BaseRequestArgs = {
+  body: unknown
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  query: Record<string, any>
+  route: string
+}
 
-- One directory for each module in your NestJS application, with inside one file for each controller belonging to this module
-- `_types`, containing the types used by the controllers, with the same directory structure than in your original project
+export type BaseRequestFn = BaseQueryFn<BaseRequestArgs, unknown, { status: number; message: string }>
 
-Each controller file exposes a simple record object with keys being your controller's methods' name. Each method takes the route's arguments (e.g. the identifier in `/users/get/:id`), the request's BODY (JSON) as well as the query parameters (e.g. `?something=...`).
+export const BaseRequest: BaseRequestFn = async ({ body, method, query, route }) => {
+  // ...perform the request, return { data } or { error }
+}
+```
 
-Methods return a typed `Promise<>` with the original method's return type.
+If the file doesn't exist, the generator creates a starter implementation for you (see [`generateDefaultSdkInterface`](#configuration)).
 
-- If the requests succeeds and returns a valid JSON string, it is parsed and returned by the method
-- If the requests fail or cannot be decoded correctly, the promise fails
+### 4. Generate the client
 
-## Architecture
+```sh
+npx nest-sdk-generator api-gen.config.json --generate-rtk
+```
 
-nest-sdk-generator analyzes your NestJS API using a provided configuration file, and produces a client-side SDK. This SDK is made of modules containing route methods that all call a central handler with the corresponding URI and parameters. The handler makes the request to the server and transmits the response. This is where you can customize the data to send to the server, if they need normalization, encryption, hashing, parsing, authentication, or anything else.
+### 5. Create the RTK Query API
 
-## Step-by-step generation tutorial
+```ts
+// web/src/api/index.ts
+import { configureStore } from '@reduxjs/toolkit'
+import { createApi } from '@reduxjs/toolkit/query/react'
 
-Generating a SDK is made in two steps:
+import { BaseRequest } from './BaseRequest'
+import endpoints from './endpoints'
 
-- Creating a configuration file for the generator
-- Performing the generation through `sdk-generator generate`
+export const rtkApi = createApi({
+  reducerPath: 'api',
+  baseQuery: BaseRequest,
+  endpoints: endpoints.buildRTKEndpoints,
+})
 
-Let's suppose we have a monorepo, with our server being in `apps/api` and running at `http://localhost:3000`, while our frontend is located in `apps/front`. We have the following structure:
+// Endpoints grouped by controller: API.Users.getUser, API.Comments.addComment...
+export const API = endpoints.groupRTKEndpoints(rtkApi)
 
-```
-.
-└── apps
-    ├── api
-    |   └── src
-    |       └── index.ts
-    └── front
-        └── src
-            └── index.ts
+export const store = configureStore({
+  reducer: { [rtkApi.reducerPath]: rtkApi.reducer },
+  middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(rtkApi.middleware),
+})
 ```
 
-We want the SDK to be located in `apps/front/sdk`.
+Wrap your app in react-redux's `<Provider store={store}>` as usual.
 
-First, we must create a configuration file. Let's put it in `front/sdk-generator.json`:
+### 6. Use the endpoints
 
-```json
-{
-  "apiInputPath": "../server",
-  "sdkOutputPath": "sdk",
-  "sdkInterfacePath": "sdk-interface.ts"
+```tsx
+import { API } from './api'
+
+export function Comments({ articleId }: { articleId: string }) {
+  const { data: comments, isLoading } = API.Comments.listComments.useQuery({ articleId })
+  const [addComment, { isLoading: isSaving }] = API.Comments.addComment.useMutation()
+
+  if (isLoading) return <p>Loading...</p>
+
+  return (
+    <>
+      <ul>
+        {comments?.map((comment) => (
+          <li key={comment.id}>{comment.text}</li>
+        ))}
+      </ul>
+      <button disabled={isSaving} onClick={() => addComment({ articleId, text: 'Nice!' })}>
+        Comment
+      </button>
+    </>
+  )
 }
 ```
 
-Let's now generate the SDK:
+Each grouped endpoint is a regular RTK Query endpoint, so everything RTK Query offers works: `useQuery`, `useLazyQuery`, `useMutation`, `initiate`, `select`, `rtkApi.util`...
 
-```shell
-sdk-generator apps/front/sdk-generator.json
-```
+### Client TypeScript setup
 
-We now have a `apps/front/sdk` directory with our SDK inside, and a default interface located in `apps/front/sdk-interface.ts`, which will handle the requests. It will only be generated if it doesn't exist, so you can edit it and commit in your repository without worrying about it being overwritten.
+Generated files contain `import type` statements pointing at your API's source files, and your client's compiler type-checks those files **with the client's compiler options**. In practice the client's `tsconfig.json` needs:
 
-**NOTE:** You can disable this generation by setting the `generateDefaultSdkInterface` setting to `false` in the `sdk-generator.json` file.
+- `"experimentalDecorators": true`, as Nest's parameter decorators (`@Param()`, `@Body()`...) are only valid with legacy decorators
+- The API's options that affect type-checking of DTOs and entities, most commonly `"strictPropertyInitialization": false`
+- The API's path aliases (`paths`), if its files import each other through aliases like `@api/*`
+- Access to the packages the API's types depend on (e.g. `class-validator`, your ORM): they are resolved from the API's directory, so they are found as long as the API's dependencies are installed
 
-#### Recommandations
+No API code ends up in your client bundle: only types are imported.
 
-In most cases, you should add the SDK's output path to your `.gitignore` and perform the generation automatically in your CI.
+## How controllers become endpoints
 
-If you want to save time in the CI, you can save the generated SDK as an artifact and put it in the registry with the key being the hash of the server's source directory. This way, the SDK will only be rebuilt when the source directory changes.
+**Controllers.** Every `*.controller.ts` file of the API's TypeScript project (as defined by its tsconfig) is analyzed. The first class of the file must have a `@Controller()` decorator called with no argument or a string literal (`@Controller('users')`); other files are skipped. Each controller belongs to the module declared in the nearest `*.module.ts` file, in the controller's directory or a parent directory.
 
-## SDK usage
+**Routes.** Methods with exactly one of `@Get()`, `@Post()`, `@Put()`, `@Patch()` or `@Delete()`, called with no argument or a string literal, become endpoints. The route is the controller's prefix followed by the method's path: `@Controller('users')` + `@Get(':id/avatar')` becomes `/users/:id/avatar`. Methods without one of these decorators are ignored.
 
-Let's suppose the NestJS server has an `UserModule` module, containing an `UserController` controller with a `getOne(id: string): Promise<UserDTO>` method. We can use it from the SDK:
+**Arguments.** The endpoint takes a single object merging all of the route's inputs:
 
-```typescript
-import { userController } from '<sdk path>/userModule/userController'
+| Controller argument | Endpoint argument | Sent as |
+| --- | --- | --- |
+| `@Param('id') id: string` | `{ id: string }` | Interpolated into the route |
+| `@Query('page') page: number` | `{ page: number }` | Query string (GET only) |
+| `@Query() query: ListQuery` | `ListQuery` | Query string (GET only) |
+| `@Body('name') name: string` | `{ name: string }` | JSON body (non-GET only) |
+| `@Body() dto: CreateUserDto` | `CreateUserDto` | JSON body (non-GET only) |
+| `@Req()`, `@Headers()`, custom decorators... | - | Ignored |
 
-const user = await userController.getOne({ id: 'some_id' })
-// typeof user == UserDTO
-```
+For example, `update(@Param('id') id: string, @Body() dto: UpdateUserDto)` produces an endpoint taking `{ id: string } & UpdateUserDto`. Routes without inputs take `void`.
 
-Each method takes three arguments: the parameters (`:xxx` in the original method's route), the body's content, and the query (`?xxx=yyy`). The query is always optional, while the body is only optional if nothing or an empty object is expected. The parameters are only optional if no parameter, nor body, is expected.
+**Results.** The result type is the method's return type with `Promise<>` unwrapped, exactly as TypeScript sees it, whether declared or inferred. A method returning `this.usersService.findOne(id)` gets the service's return type.
 
-#### Importing API types
+**RTK Query.** `GET` routes become queries (`builder.query`), every other method becomes a mutation (`builder.mutation`). The endpoint's name is the controller method's name, so **method names must be unique across all controllers**: RTK Query keeps all endpoints of an API in a single namespace.
 
-It's also possible to manually import types the API depends on.
+**Validation.** Generation fails with an explicit error when a route can't be represented reliably, for instance a `GET` route with a `@Body()`, a non-`GET` route with a `@Query()`, a route parameter missing from the URL, a parameter used twice, or a wildcard route.
 
-For instance, let's suppose `UserDTO` comes from a shared DTO package which is installed in our NestJS API's directory under `node_modules/@project/dtos/user.d.ts`.
+## Generated files
 
-We can import it from the SDK like this:
+With the configuration above, the output directory contains:
 
-```typescript
-import { UserDTO } from '<sdk path>/_types/node_modules/@project/dtos/user.d'
+```
+endpoints/
+├── index.ts               # Combines all controllers
+├── baseRequest.ts         # Re-exports the types of your request function
+├── users.endpoints.ts     # One file per controller
+└── comments.endpoints.ts
 ```
 
-It can then be used normally:
+Each controller file exports a class with:
 
-```typescript
-import { userController } from '<sdk path>/userModule/userController'
-import { UserDTO } from '<sdk path>/_types/node_modules/@project/dtos/user.d'
+- `queries` and `mutations`: functions turning an endpoint's arguments into a request for your request function (`{ body, method, query, route }`)
+- `buildRTKEndpoints(builder)`: the controller's RTK Query endpoint definitions
+- `groupRTKEndpoints(api)`: picks the controller's endpoints from a created API
 
-const user: UserDTO = await userController.getOne({ id: 'some_id' })
+`index.ts` default-exports every controller class plus:
+
+- `buildRTKEndpoints`: all endpoint definitions, to pass to `createApi({ endpoints })`
+- `groupRTKEndpoints(api)`: the created API's endpoints grouped by controller (`API.Users.getUser`)
+
+It also exports the `GeneratedAPIType` type, the type of the created API.
+
+Every endpoint is documented with its HTTP method, route and source controller method, so hovering an endpoint in your editor shows where it comes from:
+
+```ts
+/**
+ * GET /articles/:articleId/comments <=> CommentsController.listComments
+ *
+ * file:///./../../../api/src/articles/comments/comments.controller.ts (cmd + click)
+ */
+listComments: builder.query<Comment[], { articleId: string }>({
+  query: this.queries.listComments,
+}),
 ```
 
-### External files
+Generated files are overwritten on every run: don't edit them.
 
-In some situations, some of the types you are importing may belong to an external directory than the provided API source directory. For instance, if you use a mono-repository, you may have your API in `apps/api` but your DTOs built as a package in `node_modules/@apps/dtos`. In such case, the files will be placed in a special directory in `_types` called `_externalX` where `X` is the depth level (the farest the exernal file is, the larger this number will be).
+## Configuration
 
-This will make no difference when using these types, but this is a special case where the types hierarchy isn't perfectly respected.
+The configuration file is a JSON file. Relative paths are resolved from the configuration file's directory.
 
-## Configuration options
+### Paths (required)
 
-Here is the list of the configuration options you can use in the JSON file:
+| Option | Description |
+| --- | --- |
+| `apiInputPath` | Directory of the NestJS API, containing its `tsconfig.json` |
+| `sdkOutputPath` | Directory to generate the client in. It is **deleted and recreated** on each run (see `overwriteOldOutputDir`), so don't point it at a directory containing other files. Its parent directory must exist. |
+| `sdkInterfacePath` | Your [request function](#the-request-function)'s module. It must export the `BaseRequestArgs` and `BaseRequestFn` types; the generated `baseRequest.ts` re-exports them. |
 
-| Option name                   | Default         | Value type    | Description                                                                           |
-| ----------------------------- | -------         | ------------- | ------------------------------------------------------------------------------------- |
-| `apiInputPath`                | -               | `string`      | Path to your API's source folder (e.g. `apps/api`)                                    |
-| `sdkOutputPath`                   | -               | `string`      | Path to generate the SDK at (e.g. `apps/front/src/sdk`)                               |
-| `sdkInterfacePath`            | -               | `string`      | Path to the SDK interface (e.g. `apps/front/src/sdk-interface.ts`)                    |
-| `magicTypes`                  | `[]`            | `MagicType[]` | Magic types (see below)                                                               |
-| `jsonOutput`                  | `null`          | `string`      | Write the analyzer's output to a file                                                 |
-| `jsonPrettyOutput`            | `null`          | `boolean`     | Prettify the output JSON if the option above is enabled                               |
-| `prettierConfig`              | `null`          | `string`      | Use a specific Prettier config (otherwise will try to find one in a parent directory) |
-| `prettify`                    | `true`          | `boolean`     | Set to `false` to disable SDK files prettifying                                       |
-| `tsconfigFile`                | `tsconfig.json` | `string`      | Use a custom tsconfig file                                                            |
-| `overwriteOldOutputDir`       | `true`          | `boolean`     | Set to `false` to not remove the old SDK directory when re-generating it              |
-| `generateDefaultSdkInterface` | `true`          | `boolean`     | Set to `false` to not generate a default SDK interface when it does not exist yet     |
-| `generateTimestamps`          | `true`          | `boolean`     | Set to `false` to not put the timestamp in the generated SDK files                    |
-| `verbose`                     | `false`         | `boolean`     | Display verbose informations                                                          |
-| `noColor`                     | `false`         | `boolean`     | Disable colored output                                                                |
+### Naming
 
-## Magic types
+By default, generated names follow your controllers: `users.controller.ts` produces `users.controller.ts` exporting `UsersController`, grouped as `API.UsersController`. `controllerOutput` adjusts these names, each with an optional `removeSuffix` (removed from the end of the name, if present) and `addSuffix` (appended):
 
-In some cases, there are types that may not be exportable using the generator. For instance:
+| Option | Applies to | Example: `UsersController` in `users.controller.ts` |
+| --- | --- | --- |
+| `controllerOutput.fileName` | The generated file's name, from the controller's file name without extension | `{ "removeSuffix": ".controller", "addSuffix": ".endpoints" }` gives `users.endpoints.ts` |
+| `controllerOutput.exportName` | The generated class's name | `{ "removeSuffix": "Controller", "addSuffix": "Endpoints" }` gives `UsersEndpoints` |
+| `controllerOutput.endpointGroupName` | The key in `groupRTKEndpoints(api)` | `{ "removeSuffix": "Controller" }` gives `API.Users` |
 
-```tsx
-// ...
+`removeSuffix` is interpreted as a regular expression: escape special characters if you need an exact match (in `.controller`, the `.` matches any character, which is harmless in practice).
+
+### Output
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `prettify` | `true` | Format generated files with Prettier |
+| `prettierConfig` | - | Path to a Prettier configuration file (JSON). By default, the nearest `.prettierrc` file above `sdkOutputPath` is used, if any; only JSON `.prettierrc` files are supported. |
+| `generateTimestamps` | `true` | Add the generation date to each file. Set to `false` to get identical output when nothing changed (recommended). |
+| `overwriteOldOutputDir` | `true` | Replace `sdkOutputPath` if it exists. When `false`, generation fails if it exists. |
+| `generateDefaultSdkInterface` | `true` | Create a starter request function at `sdkInterfacePath` if the file doesn't exist. An existing file is never overwritten. |
+
+### Analysis
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `tsconfigFile` | `tsconfig.json` | Name of the API's tsconfig file, in `apiInputPath` (a file name, not a path) |
+| `engine` | `tsgo` | [Analysis engine](#analysis-engines): `tsgo`, `typescript` or `ts-morph` |
+| `typescriptPath` | - | TypeScript package used by the `typescript` engine. By default, the `typescript` package installed for the API (resolved from `apiInputPath`) is used. |
+| `magicTypes` | `[]` | Replacements for types that can't be extracted, for the [plain SDK mode](#plain-sdk-mode---generate) |
 
-@Entity()
-export class Author {
-    // ...
+### Debugging
 
-    @OneToMany(() => Article, (article) => article.author)
-    articles = new Collection<Article>(this)
+| Option | Default | Description |
+| --- | --- | --- |
+| `verbose` | `false` | Log every analyzed controller, method, argument and type |
+| `jsonOutput` | - | Write the analysis result (modules, controllers, routes and types) to this JSON file |
+| `jsonPrettyOutput` | `false` | Indent the JSON output |
+| `noColor` | `false` | Currently ineffective: set the `FORCE_COLOR=0` environment variable to disable colors |
 
-// ...
+## The request function
+
+The generated endpoints don't perform requests themselves: each one turns its arguments into a `BaseRequestArgs` object and hands it to RTK Query's base query, which is your request function. You decide how requests are made: base URL, headers, authentication, serialization, error format, retries, logging...
+
+```ts
+// web/src/api/BaseRequest.ts
+import type { BaseQueryFn } from '@reduxjs/toolkit/query'
+
+/** What each generated endpoint asks the request function to do */
+export type BaseRequestArgs = {
+  body: unknown
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  query: Record<string, any>
+  route: string // e.g. "/users/42", with route parameters already interpolated
 }
 
-```
+export type RequestError = { status: number; message: string }
 
-Here, the `articles` field uses the `Collection<T>` type of Mikro-ORM, which is a circular type, meaning we can't export it. Plus, it contains lots of methods and depends on multiple Mikro-ORM types, which we don't want in our SDK.
+export type BaseRequestFn = BaseQueryFn<BaseRequestArgs, unknown, RequestError>
 
-To solve this problem, we can add a `magicTypes` entry in our configuration file:
+// Include your API's global prefix and version, if any (e.g. app.setGlobalPrefix('api'))
+const BASE_URL = 'https://api.example.com'
 
-```json
-{
-  // ...
-  "magicTypes": [
-      {
-        "nodeModuleFilePath": "@mikro-orm/core/entity/Collection.d.ts",
-        "typeName": "Collection",
-        "placeholderContent": "export type Collection<T, _> = Array<T>;"
-      }
-  ]
+export const BaseRequest: BaseRequestFn = async ({ body, method, query, route }) => {
+  const url = new URL(BASE_URL + route)
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) continue
+    url.searchParams.append(key, typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value))
+  }
+
+  const response = await fetch(url, {
+    method,
+    headers: { 'Content-Type': 'application/json' /* , Authorization: `Bearer ${token}` */ },
+    body: method === 'GET' ? undefined : JSON.stringify(body ?? {}),
+  })
+
+  const text = await response.text()
+
+  if (!response.ok) {
+    return { error: { status: response.status, message: text } }
+  }
+
+  return { data: text ? JSON.parse(text) : undefined }
 }
+```
+
+The function receives RTK Query's usual extra arguments (`api`, with `getState`, `dispatch` and `signal`, and `extraOptions`), so you can read a token from the store or support request cancellation. To handle errors globally (e.g. show a toast), wrap the function and pass the wrapper to `createApi`.
+
+The `error` returned by the hooks is either the error type you declare in `BaseRequestFn`, or RTK Query's `SerializedError` (for unexpected exceptions).
+
+**Starter implementation.** When `sdkInterfacePath` doesn't exist, the generator writes a more complete starter (query serialization, a `RequestError` class with HTTP metadata, user-facing messages from Nest's error responses) that you can adapt. It assumes the API is served from `/api` on the current host.
+
+## Adding caching (tags)
+
+Generated endpoints don't declare cache tags. Add them with RTK Query's [`enhanceEndpoints`](https://redux-toolkit.js.org/rtk-query/api/created-api/code-splitting#enhanceendpoints), which keeps everything typed:
+
+```ts
+export const rtkApi = createApi({
+  reducerPath: 'api',
+  baseQuery: BaseRequest,
+  endpoints: endpoints.buildRTKEndpoints,
+}).enhanceEndpoints({
+  addTagTypes: ['Comment'],
+  endpoints: {
+    listComments: { providesTags: ['Comment'] },
+    addComment: { invalidatesTags: ['Comment'] },
+    removeComment: { invalidatesTags: ['Comment'] },
+  },
+})
 
+export const API = endpoints.groupRTKEndpoints(rtkApi)
 ```
 
-Now, when the SDK generator encounters the `Collection` type when it's imported from `@mikro-orm/core/entity/Collection.d.ts`, it will link to the `placeholderContent` we provided instead.
+The same applies to other per-endpoint options like `keepUnusedDataFor` or `transformResponse`.
 
-Note that some magic types are already [built-in](src/analyzer/builtin.ts), such as the one we just saw. If you use a library very frequently and think others may benefit from a new magic type, feel free to [open a PR](https://github.com/lonestone/nest-sdk-generator/pulls)!
+## Command line
 
-## Frequently-asked questions
+```sh
+nest-sdk-generator <config file> [--generate-rtk | --generate] [--engine <tsgo|typescript|ts-morph>]
+```
 
-### Does this replace Swagger?
+| Argument | Description |
+| --- | --- |
+| `<config file>` | Path to the configuration file (required) |
+| `--generate-rtk` | Generate the RTK Query client |
+| `--generate` | Generate the [plain SDK](#plain-sdk-mode---generate) |
+| `--engine <name>`, `--engine=<name>` | Analysis engine, overriding the configuration file |
 
-No, nest-sdk-generator only generates a client-side SDK to make requests more easily to the server ; it doesn't generate a documentation by itself. Although all routes are organized with their original name and split across controllers and modules the same way they were in the API, that doesn't make a full documentation in itself.
+Without `--generate-rtk` or `--generate`, the API is only analyzed: useful to validate it, or to produce a `jsonOutput`. The process exits with a non-zero code on errors (`1` for analysis and generation errors, `2` to `4` when the configuration file is missing or invalid).
 
-### I have a GraphQL API, what can this project do for me?
+## Analysis engines
 
-Unfortunately, nest-sdk-generator isn't compatible with GraphQL API, and for a good reason: the whole point of this project is to bring structural typing to an API, but GraphQL already provides that. So there would be no point in this tool being compatible with GraphQL projects.
+Most of the generation time is spent by the TypeScript compiler analyzing the API. Three engines are available:
 
-### Does the SDK has any performance overhead?
+| Engine | Compiler | Notes |
+| --- | --- | --- |
+| `tsgo` (default) | TypeScript 7's native compiler, bundled | Fastest |
+| `typescript` | Your API's own TypeScript compiler (6.x), in-process | Same output as `tsgo`*. Used automatically if `tsgo` can't start. |
+| `ts-morph` | TypeScript 4.8, bundled with ts-morph | Same output as version 2.x of this package |
 
-Absolutely not. The generated SDK is only made of simple objets that will call the handler you provided through the interface script, and the said script will be in charge of making the request (with `fetch` by default). This means that no kind of data transformation/conversion happens behind-the-scenes.
+On an API with 66 controllers, 687 routes and ~2,500 source files (plus large dependencies like `googleapis`), generating the RTK Query client takes:
 
-### How do I update the SDK once I change the API's source code?
+| Engine | Duration |
+| --- | --- |
+| `tsgo` | 2.4s |
+| `typescript` | 8.8s |
+| `ts-morph` | 17.7s |
 
-You simply run the same shell command you used to generate the source code originally. There isn't a special subcommand for it, as it will simply delete the old SDK and replace it with the new one.
+The `tsgo` engine requires Node.js 20.19+ or 22.12+, and Node.js itself rather than Bun's runtime: `bun x` and `npx` run the generator with Node.js, but `bun --bun` doesn't. When `tsgo` can't be started (unsupported runtime or platform), the generator falls back to the `typescript` engine and says so. The `typescript` engine needs a TypeScript 6 (or older) package with the JavaScript compiler API: the API's own, or the one set with `typescriptPath`.
 
-### Is the SDK documented?
+Newer TypeScript versions infer some types more precisely than TypeScript 4.8 (e.g. `(User | undefined)[]` becomes `User[]` after a `.filter()` with a type guard), order union members deterministically, and omit default type arguments. The `tsgo` and `typescript` engines may therefore generate slightly different, more precise types than the `ts-morph` engine.
 
-Each file in the SDK uses a generic documentation, including the exact route model for route methods. This means you will be able to check what route is called by which method each time.
+\* TypeScript 6 and 7 print a few rare types differently (e.g. classes declared inside generic functions, used as base classes). This doesn't affect the RTK Query client, but can change the types extracted for the plain SDK mode and `jsonOutput`.
 
-Here is a quick glance at a generated file sample:
+## Recommended workflow
 
-```ts
-// ...
-/// Parent module: articleModule
-/// Controller: "articleController" registered as "article" (5 routes)
+- **Don't commit the generated client.** Add `sdkOutputPath` to your `.gitignore` and generate it before anything that needs it:
 
-// ...
+  ```json
+  {
+    "scripts": {
+      "build:api": "nest-sdk-generator api-gen.config.json --generate-rtk",
+      "dev": "npm run build:api && next dev",
+      "build": "npm run build:api && next build",
+      "typecheck": "npm run build:api && tsc --noEmit",
+      "test": "npm run build:api && vitest run"
+    }
+  }
+  ```
 
-export default {
-  // GET @ /article
-  getAll(params: {} = {}, body: {} = {}, query: {} = {}): Promise<Article[]> {
-    return request('GET', `/article`, body, query)
-  },
+- **Regenerate while developing.** The generator doesn't watch files; pair it with a file watcher, e.g. `nodemon --watch ../api/src -e ts --exec "npm run build:api"`.
+- **Set `generateTimestamps: false`** so unchanged APIs produce identical files, and tools watching the output don't rebuild for nothing.
+- **Type-check the client in CI.** As the client is generated from the API, a breaking API change surfaces as a type error in the client code that uses it.
 
-  // GET @ /article/:slug
-  getOne(
-    params: { slug: string },
-    body: {} = {},
-    query: {} = {},
-  ): Promise<Article> {
-    return request('GET', `/article/${params.slug}`, body, query)
-  },
+## Limitations
+
+- **Static analysis only.** Routes are discovered from the decorators listed in [How controllers become endpoints](#how-controllers-become-endpoints): routes registered dynamically, `@All()`, `@Head()`, `@Options()`, `@Controller()` options objects, versioning and global prefixes aren't taken into account (put global prefixes in your request function's base URL).
+- **No wildcard routes** (`*`, `+`, `?` in paths), and route parameter names may only contain letters, digits and `_`.
+- **Generic `@Param()` objects aren't supported**: use one `@Param('name')` per route parameter.
+- **Optional keyed parameters are required keys.** `@Query('page') page?: number` produces `{ page: number | undefined }`: pass `page: undefined` explicitly, or use a `@Query()` DTO with optional properties.
+- **Controller paths without a prefix.** With `@Controller()` (no prefix), the method's path is used as is: write `@Get('/articles')` rather than `@Get('articles')` to get a route starting with `/`.
+- **One module file per directory.** A controller's module is found by looking for a `*.module.ts` file in its directory, then its parents.
+- **Unique names.** Controller class names, and method names across controllers, must be unique.
+- **Types must be declared at the top level of a file.** Types used by routes are also extracted during analysis (for the plain SDK mode and `jsonOutput`), and types declared inside namespaces can't be, which fails the generation.
+- **The API isn't type-checked.** Generation doesn't report compilation errors in the API; types the compiler can't resolve become `any`.
+
+## Troubleshooting
 
-  // ...
+| Error | Cause and fix |
+| --- | --- |
+| `Duplicate method name found: X in A and B` | Two controllers have a method named `X`, which would produce two RTK Query endpoints with the same name. Rename one of them. |
+| `GET request should not have @Body params` / `POST request should not have @Query params` | Move the inputs to `@Query()` (GET) or `@Body()` (other methods). |
+| `Route param X does not appear in route URL` | A `@Param('X')` has no matching `:X` in the route, or a generic `@Param()` object is used. |
+| `No module file was found for controller at path ...` | Add a `*.module.ts` file in the controller's directory or a parent directory. |
+| `Type X was not found in file ...` | `X` is not declared at the top level of that file (e.g. it is in a namespace). |
+| Type errors in API files when type-checking the client | Align the client's compiler options with the API's (see [Client TypeScript setup](#client-typescript-setup)). |
+| Generation is slow | Check that the `tsgo` engine is used (`"verbose": true` logs the engine), and that you aren't running the generator with `bun --bun`. |
+
+For anything else, `"verbose": true` logs every step of the analysis, and `jsonOutput` shows what the analyzer understood of your API.
+
+## Plain SDK mode (`--generate`)
+
+`--generate` produces a framework-agnostic SDK instead of RTK Query endpoints: one file per controller with `queries` and `mutations` objects whose methods call a `request(method, uri, body, query)` function exported by `sdkInterfacePath`. In this mode, the types used by the routes are copied into an `_types` directory (types from outside the API's directory go to `_types/_externalN/...`), so the client doesn't need access to the API's source.
+
+Types that can't be copied, like ORM types with circular references or many dependencies, can be replaced with placeholders using `magicTypes`:
+
+```json
+{
+  "magicTypes": [
+    {
+      "nodeModuleFilePath": "@mikro-orm/core/entity/Collection.d.ts",
+      "typeName": "Collection",
+      "placeholderContent": "export type Collection<T, _> = Array<T>;"
+    }
+  ]
 }
 ```
 
-### Can I add header or other data on-the-fly when making requests?
+When a type named `typeName` is imported from `node_modules/<nodeModuleFilePath>`, `placeholderContent` is used instead. Mikro-ORM's `Collection` is replaced by default.
 
-All of the SDK's methods use a central handler which calls a function you provided, where you can absolutely everything you can. You are in charge of making the requests thanks to the provided URI and query/body parameters, which means you can add, edit or remove whatever data you want.
+This mode is maintained for compatibility: the RTK Query client is the primary use case of this package. Known issue: classes with an index signature (`[key: string]: ...`) produce type files Prettier rejects.
 
-### Is there a way to log the requests or responses somewhere?
+## Upgrading from 2.x
 
-All of the SDK's methods use a central handler which calls a function you provided, where you can do absolutely everything you can. You are in charge of making 
-the requests thanks to the provided URI and query/body parameters, which means you can write the requests and responses to the local storage, send them to a log server, or anything else.
+Version 3.0 adds the [analysis engines](#analysis-engines); configurations and generated file structures are unchanged.
 
-### Does the API server needs to be running to generate a SDK?
+- Generation is much faster, but the default `tsgo` engine requires Node.js 20.19+ / 22.12+.
+- Some generated types may change, as newer TypeScript versions infer types more precisely. If this breaks your build, fix the client code (the new types reflect what your API's compiler sees), or temporarily use `--engine=ts-morph` to get exactly the 2.x output.
+- `jsonOutput` works again (it crashed in 2.x).
 
-No, the SDK is generated by analyzing the source code of your API, which means you don't need a server running for this.
+## Development
 
-### Can I fork this project to make my own version of it?
+```sh
+npm install
+npm run build            # Build the generator into build/
+npm run build:baseline   # Build version 2.3.1 into .parity/baseline, used as a reference by the tests
+npm test                 # Run the tests
+npm run lint
+```
 
-Absolutely, that's what the MIT license is for. Although, if you could get in touch with us to indicate what changes you made to the generator it would be hugely helpful to improve it on our side ;)
+The tests generate clients for the fixture API in `test/fixtures` (and ~30 error cases) and compare the results of:
 
-### Can I use this project in commercial software?
+- the 2.3.1 baseline and the `ts-morph` engine, which must produce exactly the same output
+- the analyzer behind the `tsgo` and `typescript` engines, running on ts-morph's TypeScript 4.8 program, which must also produce exactly the same output (this shows it is equivalent to the original analyzer)
+- the `tsgo` and `typescript` engines, which must produce exactly the same output
 
-Absolutely, the MIT license allows you to do that without any royalties or particular constraint.
+To also run them on a real project, set `PARITY_REAL_API_CONFIG` to the path of its generator configuration file; generated files are written to a temporary directory.
 
-If you use this project to produce any kind of program, be it paid or not, we'd love to hear about it! Feel free to get in touch with us at [contact@lonestone.studio](mailto:contact@lonestone.studio) to tell us about your projects, so we can improve our tool even more with additional real-use cases.
+## Credits and license
 
-## License
+This package is maintained by [BuildVision](https://buildvision.io). It started as a fork of [nest-sdk-generator](https://github.com/lonestone/nest-sdk-generator) by [Lonestone](https://lonestone.io/), which generated plain SDKs; this fork adds the RTK Query client and the analysis engines.
 
-This project is published under the terms of the [MIT License](LICENSE.md).
+Published under the [MIT License](LICENSE.md).