Merge pull request #15 from rhyek/include-orval-codegen

axios client working

Author: rhyek

README.md

@@ -4,7 +4,7 @@
 
 ## Introduction
 
-**nestjs-endpoints** is a lightweight tool for writing clean and succinct HTTP APIs with NestJS that encourages the [REPR](https://www.apitemplatepack.com/docs/introduction/repr-pattern/) design pattern, code colocation, and the Single Responsibility Principle.
+**nestjs-endpoints** is a lightweight tool for writing clean, succinct, end-to-end type-safe HTTP APIs with NestJS that encourages the [REPR](https://www.apitemplatepack.com/docs/introduction/repr-pattern/) design pattern, code colocation, and the Single Responsibility Principle.
 
 It's inspired by the [Fast Endpoints](https://fast-endpoints.com/) .NET library, [tRPC](https://trpc.io/), and Next.js' file-based routing.
 
@@ -27,11 +27,10 @@ Hello, World!%
 
 - **Easy setup:** Automatically scans your entire project for endpoint files and loads them.
 - **Stable:** Produces regular **NestJS Controllers** under the hood.
-- **File-based routing:** Each endpoint's HTTP path is based on their path on disk.
-- **User-Friendly API:** Supports both basic and advanced per-endpoint configuration.
+- **File-based routing:** Endpoints' HTTP paths are based on their path on disk.
 - **Schema validation:** Compile and run-time validation of input and output values using Zod schemas.
+- **End-to-end type safety:** Auto-generates `axios` and `@tanstack/react-query` client libraries. Internally uses `@nestjs/swagger`, [nestjs-zod](https://github.com/BenLorantfy/nestjs-zod), and [orval](https://orval.dev/).
 - **HTTP adapter agnostic:** Works with both Express and Fastify NestJS applications.
-- **Client SDK codegen:** Annotates endpoints using `@nestjs/swagger` and [nestjs-zod](https://github.com/BenLorantfy/nestjs-zod) internally to output an OpenAPI document which [orval](https://orval.dev/) can use to generate a client library.
 
 ## Getting Started
 
@@ -302,39 +301,75 @@ To call this endpoint:
 {"id":1,"date":"2021-11-03T00:00:00.000Z","address":"::1"}%
 ```
 
-## OpenAPI, Codegen setup (optional)
+## Codegen (optional)
 
-It's a common practice to automatically generate a client SDK for your API that
-you can use in other backend or frontend projects and have the benefit of full-stack type-safety. tRPC and similar libraries have been written to facilitate this.
+You can automatically generate a client SDK for your API that can be used in other backend or frontend projects and have the benefit of end-to-end type safety. This will use [orval](https://orval.dev/) internally.
 
-We can achieve the same here in two steps. We first build an OpenAPI document, then use that document's
-output with [orval](https://orval.dev/):
+### Simple
+
+This is the preferred way of configuring codegen with nestjs-endpoints.
 
 `src/main.ts`
 
 ```typescript
-import { setupOpenAPI } from 'nestjs-endpoints';
+import { setupCodegen } from 'nestjs-endpoints';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
-  const { document, changed } = await setupOpenAPI(app, {
-    configure: (builder) => builder.setTitle('My Api'),
-    outputFile: process.cwd() + '/openapi.json',
+  await setupCodegen(app, {
+    clients: [
+      {
+        type: 'axios',
+        outputFile: process.cwd() + '/generated/axios-client.ts',
+      },
+      {
+        type: 'react-query',
+        outputFile: process.cwd() + '/generated/react-query-client.tsx',
+      },
+    ],
   });
-  if (changed) {
-    void import('orval').then(({ generate }) => generate());
-  }
   await app.listen(3000);
 }
 ```
 
-And then you could have something like this available:
+And then you'll have these available to use:
 
 ```typescript
+// axios
 const { id } = await userCreate({
   name: 'Tom',
   email: '[email protected]',
 });
+const user = await userFind({ id });
+
+// react-query
+const userCreate = useUserCreate();
+const { data: user, error, status } = useUserFind({ id: 1 });
 ```
 
-Have a look at [this](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test/test-app-express-cjs) test project to see how you might configure orval to generate an axios-based client and [here](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test/test-app-express-cjs/test/client.e2e-spec.ts) to understand how you would use it.
+Have a look at these examples to see to set up and consume these libraries:
+
+- [axios](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test/test-app-express-cjs/test/client.e2e-spec.ts)
+- [react-query](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test/test-react-query-client)
+
+### Manual
+
+If you prefer to configure orval yourself and just need the OpenAPI spec file, you can do the following:
+
+`src/main.ts`
+
+```typescript
+import { setupOpenAPI } from 'nestjs-endpoints';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  const { document, changed } = await setupOpenAPI(app, {
+    configure: (builder) => builder.setTitle('My Api'),
+    outputFile: process.cwd() + '/openapi.json',
+  });
+  if (changed) {
+    void import('orval').then(({ generate }) => generate());
+  }
+  await app.listen(3000);
+}
+```

eslint.config.js

@@ -91,4 +91,18 @@ export default tseslint.config(
       'jest/no-focused-tests': 'error',
     },
   },
+  {
+    files: ['packages/test/test-react-query-client/**'],
+    rules: {
+      'no-console': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+    },
+  },
+  {
+    files: ['packages/test/*/generated/**'],
+    rules: {
+      '@typescript-eslint/no-unnecessary-type-assertion': 'off',
+      'import/order': 'off',
+    },
+  },
 );

package.json

@@ -4,15 +4,15 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "./scripts/test.sh",
+    "test": "./scripts/build.sh && ./scripts/test.sh",
     "dev": "pnpm --filter nestjs-endpoints --filter test-app-express-cjs run --parallel dev",
     "prepare": "husky"
   },
   "devDependencies": {
     "@eslint/js": "^9.20.0",
-    "@nestjs/common": "^11.0.8",
-    "@nestjs/core": "^11.0.8",
-    "@nestjs/swagger": "^11.0.3",
+    "@nestjs/common": "^11.0.13",
+    "@nestjs/core": "^11.0.13",
+    "@nestjs/swagger": "^11.1.1",
     "@types/node": "^22.13.1",
     "@typescript-eslint/parser": "^8.23.0",
     "eslint": "^9.20.1",
@@ -26,5 +26,10 @@
     "prettier": "^3.0.0",
     "typescript-eslint": "^8.24.0",
     "zod": "^3.24.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "reflect-metadata": "0.1.14"
+    }
   }
 }

packages/nestjs-endpoints/package.json

@@ -43,8 +43,10 @@
     "dev": "tsc --watch --preserveWatchOutput"
   },
   "dependencies": {
+    "@orval/query": "~7.8.0",
     "callsites": "^3.1.0",
-    "nestjs-zod": "^4.2.0"
+    "nestjs-zod": "^4.2.0",
+    "orval": "~7.8.0"
   },
   "peerDependencies": {
     "@nestjs/common": ">=10.0.0",
@@ -53,8 +55,11 @@
     "zod": ">=3.0.0"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.2",
     "@types/node": "^22.13.1",
+    "jest": "^29.5.0",
     "tsc-alias": "^1.8.10",
+    "ts-jest": "^29.1.0",
     "typescript": "^5.7.3"
   }
 }

packages/nestjs-endpoints/src/codegen/builder/axios.ts

@@ -0,0 +1,49 @@
+import type { OutputClientFunc } from 'orval';
+
+export const axios = (): OutputClientFunc => {
+  return (clients) => {
+    return {
+      ...clients.axios,
+      dependencies: () => {
+        // https://github.com/orval-labs/orval/blob/a154264719ccc49b3ab95dadbb3d62513110d8c3/packages/axios/src/index.ts#L22
+        return [
+          {
+            exports: [
+              {
+                name: 'Axios',
+                default: true,
+                values: true,
+                syntheticDefaultImport: true,
+              },
+              { name: 'AxiosRequestConfig' },
+              { name: 'AxiosResponse' },
+              { name: 'CreateAxiosDefaults' },
+              { name: 'AxiosInstance' },
+            ],
+            dependency: 'axios',
+          },
+        ];
+      },
+      header: () => {
+        return `
+export const createApiClient = (config?: CreateAxiosDefaults | AxiosInstance) => {
+  const axios =
+    config &&
+    'defaults' in config &&
+    'interceptors' in config &&
+    typeof config.request === 'function'
+      ? config
+      : Axios.create(config as CreateAxiosDefaults);
+
+`;
+      },
+      footer: (params) => {
+        const result = clients.axios.footer!(params);
+        return result.replace(
+          /return {(.+?)}/,
+          (_, captured) => `return {${captured}, axios}`,
+        );
+      },
+    };
+  };
+};

packages/nestjs-endpoints/src/codegen/builder/react-query.ts

@@ -0,0 +1,144 @@
+import type { OutputClientFunc } from 'orval';
+
+export const reactQuery = (): OutputClientFunc => {
+  const fns: string[] = [];
+  return (clients) => {
+    return {
+      ...clients['react-query'],
+      dependencies: (...args) => {
+        const deps = clients['react-query'].dependencies!(...args);
+        deps.unshift({
+          dependency: 'react',
+          exports: [
+            {
+              name: 'React',
+              default: true,
+              values: true,
+              syntheticDefaultImport: true,
+            },
+          ],
+        });
+        deps
+          .find((dep) => dep.dependency === 'axios')
+          ?.exports.push(
+            {
+              name: 'AxiosInstance',
+            },
+            {
+              name: 'CreateAxiosDefaults',
+            },
+          );
+        return deps;
+      },
+      header: (params) => {
+        const operationNames = Object.values(params.verbOptions).map(
+          (verb) => verb.operationName,
+        );
+        return `
+const Axios = axios;
+export const createApiClient = (config?: CreateAxiosDefaults | AxiosInstance) => {
+  const axios =
+    config &&
+    'defaults' in config &&
+    'interceptors' in config &&
+    typeof config.request === 'function'
+      ? config
+      : Axios.create(config as CreateAxiosDefaults);
+  ${fns.join('\n')}
+  return {
+${operationNames.map((name) => `    ${name},`).join('\n')}
+    axios
+  };
+};
+
+export type ApiClient = ReturnType<typeof createApiClient>;
+
+export const ApiClientContext = React.createContext<ApiClient>(null as any);
+export const ApiClientProvider = ({ client, children }: { client: ApiClient; children: React.ReactNode }) => {
+  return <ApiClientContext.Provider value={client}>{children}</ApiClientContext.Provider>
+};
+
+export const useApiClient = () => {
+  const client = React.useContext(ApiClientContext);
+  if (!client) throw new Error('useApiClient must be used within a ApiClientProvider');
+  return client;
+};
+`;
+      },
+      client: async (verbOptions, options, outputClient, output) => {
+        const result = await clients['react-query'].client(
+          verbOptions,
+          options,
+          outputClient,
+          output,
+        );
+
+        const lines = result.implementation.split('\n');
+        let queryKeyLine: number | null = null;
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes('QueryKey')) {
+            queryKeyLine = i;
+            break;
+          }
+        }
+        if (queryKeyLine === null) {
+          for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes('MutationOptions')) {
+              queryKeyLine = i;
+              break;
+            }
+          }
+        }
+        if (queryKeyLine === null) {
+          throw new Error('No query key found in implementation');
+        }
+        const fn = lines
+          .slice(0, queryKeyLine)
+          .join('\n')
+          .replace(/export /, '');
+        fns.push(fn);
+        result.implementation = lines.slice(queryKeyLine).join('\n');
+        result.implementation = result.implementation.replace(
+          /const mutationOptions\s+=\s+(.+)\(options\);/,
+          (_, captured) => {
+            return `
+      const client = useApiClient();
+      const mutationOptions = ${captured}(Object.assign({ client }, options));
+          `;
+          },
+        );
+        result.implementation = result.implementation.replace(
+          /const queryOptions\s+=\s+(.+)\(((?:params,)?options)\)/,
+          (_, c1, c2) => {
+            return `
+      const client = useApiClient();
+      const queryOptions = ${c1}(${c2.replace('options', 'Object.assign({ client }, options)')});
+          `;
+          },
+        );
+        result.implementation = result.implementation.replace(
+          /options\?: {.+axios\?: AxiosRequestConfig/,
+          (match) => {
+            return `${match.replace('options?', 'options')}, client: ApiClient`;
+          },
+        );
+        result.implementation = result.implementation.replace(
+          /return\s+(.+)\((?:data,)?axiosOptions\)/,
+          (match, captured) =>
+            `${match.replace(captured, `options.client.${captured}`)}.then((res) => res.data);`,
+        );
+        result.implementation = result.implementation.replace(
+          /const queryFn.+=>\s+(.+\()(?:params, )?{ signal, ...axiosOptions }\)/,
+          (match, captured) =>
+            `${match.replace(captured, `options.client.${captured}`)}.then((res) => res.data)`,
+        );
+        result.implementation = result.implementation.replaceAll(
+          /Awaited<ReturnType<typeof (.+?)>>/g,
+          (match, captured) =>
+            `Awaited<ReturnType<ApiClient['${captured}']>>['data']`,
+        );
+        return result;
+      },
+    };
+  };
+};

packages/nestjs-endpoints/src/codegen/index.ts

@@ -0,0 +1 @@
+export { setupCodegen } from './setup';