Merge pull request #9 from rhyek/orval-example

include example of orval client gen

Author: rhyek

.gitignore

@@ -1,2 +1,6 @@
 node_modules/
 openapi.json
+*.e2e-spec.ts
+!packages/test-endpoints-module/test-app-express-cjs/**/*.e2e-spec.ts
+generated/
+!packages/test-endpoints-module/test-app-express-cjs/generated

README.md

@@ -294,7 +294,7 @@ To call this endpoint:
 ## OpenAPI, Codegen setup (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 make this easy for you.
+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.
 
 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/):
@@ -316,3 +316,11 @@ async function bootstrap() {
   await app.listen(3000);
 }
 ```
+
+And then you could have something like this available:
+
+```typescript
+const { id } = await userCreate({ name: 'Tom', email: '[email protected]' });
+```
+
+Have a look at [this](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test-endpoints-module/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-endpoints-module/test-app-express-cjs/test/client.e2e-spec.ts) to understand how you would use it.

eslint.config.js

@@ -72,6 +72,7 @@ export default tseslint.config(
       '@typescript-eslint/no-unsafe-argument': 'off',
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-redundant-type-constituents': 'off',
     },
   },
   {

packages/test-endpoints-module/test-app-express-cjs/.gitignore

@@ -32,4 +32,4 @@ lerna-debug.log*
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
-!.vscode/extensions.json
+!.vscode/extensions.json

packages/test-endpoints-module/test-app-express-cjs/generated/client.ts

@@ -0,0 +1,145 @@
+/**
+ * Generated by orval v7.5.0 🍺
+ * Do not edit manually.
+ * OpenAPI spec version: 1.0.0
+ */
+import { customInstance } from './custom-axios-instance';
+export interface UserCreateInput {
+  name: string;
+  email: string;
+}
+
+export interface UserCreateOutput {
+  id: number;
+}
+
+/**
+ * @nullable
+ */
+export type UserFindOutput = {
+  id: number;
+  name: string;
+  email: string;
+} | null;
+
+export interface UserAppointmentCreateInput {
+  userId: number;
+  date: unknown;
+}
+
+export interface UserAppointmentCreate201Output {
+  id: number;
+  date: unknown;
+  address: string;
+}
+
+export type UserAppointmentCreate400OutputOneOf = {
+  message: string;
+  errorCode: string;
+};
+
+export type UserAppointmentCreate400Output =
+  | string
+  | UserAppointmentCreate400OutputOneOf;
+
+export type UserAppointmentCountOutput = number;
+
+export type UserFindParams = {
+  id: number;
+};
+
+export type UserAppointmentCountParams = {
+  userId: number;
+};
+
+type SecondParameter<T extends (...args: any) => any> = Parameters<T>[1];
+
+export const userCreate = (
+  userCreateInput: UserCreateInput,
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<UserCreateOutput>(
+    {
+      url: `/user/create`,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      data: userCreateInput,
+    },
+    options,
+  );
+};
+
+export const userFind = (
+  params: UserFindParams,
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<UserFindOutput>(
+    { url: `/user/find`, method: 'GET', params },
+    options,
+  );
+};
+
+/**
+ * @summary Create an appointment
+ */
+export const userAppointmentCreate = (
+  userAppointmentCreateInput: UserAppointmentCreateInput,
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<UserAppointmentCreate201Output>(
+    {
+      url: `/user/appointment/create`,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      data: userAppointmentCreateInput,
+    },
+    options,
+  );
+};
+
+export const userAppointmentCount = (
+  params: UserAppointmentCountParams,
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<UserAppointmentCountOutput>(
+    { url: `/user/appointment/count`, method: 'GET', params },
+    options,
+  );
+};
+
+export const testError = (
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<void>(
+    { url: `/test/error`, method: 'GET' },
+    options,
+  );
+};
+
+export const testStatus = (
+  options?: SecondParameter<typeof customInstance>,
+) => {
+  return customInstance<void>(
+    { url: `/test/status`, method: 'GET' },
+    options,
+  );
+};
+
+export type UserCreateResult = NonNullable<
+  Awaited<ReturnType<typeof userCreate>>
+>;
+export type UserFindResult = NonNullable<
+  Awaited<ReturnType<typeof userFind>>
+>;
+export type UserAppointmentCreateResult = NonNullable<
+  Awaited<ReturnType<typeof userAppointmentCreate>>
+>;
+export type UserAppointmentCountResult = NonNullable<
+  Awaited<ReturnType<typeof userAppointmentCount>>
+>;
+export type TestErrorResult = NonNullable<
+  Awaited<ReturnType<typeof testError>>
+>;
+export type TestStatusResult = NonNullable<
+  Awaited<ReturnType<typeof testStatus>>
+>;

packages/test-endpoints-module/test-app-express-cjs/generated/custom-axios-instance.ts

@@ -0,0 +1,21 @@
+import { type AxiosRequestConfig, type AxiosInstance } from 'axios';
+
+let AXIOS_INSTANCE: AxiosInstance | null = null;
+
+export const setAxiosInstance = (instance: AxiosInstance) => {
+  AXIOS_INSTANCE = instance;
+};
+
+export const customInstance = <T>(
+  config: AxiosRequestConfig,
+  options?: AxiosRequestConfig,
+): Promise<T> => {
+  if (!AXIOS_INSTANCE) {
+    throw new Error('Axios instance is not initialized');
+  }
+  const promise = AXIOS_INSTANCE({
+    ...config,
+    ...options,
+  }).then(({ data }) => data);
+  return promise;
+};

packages/test-endpoints-module/test-app-express-cjs/orval.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'orval';
+
+export default defineConfig({
+  test: {
+    output: {
+      workspace: 'generated',
+      target: 'client.ts',
+      client: 'axios-functions',
+      mode: 'single',
+      indexFiles: false,
+      override: {
+        mutator: {
+          path: './custom-axios-instance.ts',
+          name: 'customInstance',
+        },
+      },
+    },
+    input: {
+      target: './openapi.json',
+    },
+    hooks: {
+      afterAllFilesWrite: 'pnpm eslint --fix',
+    },
+  },
+});

packages/test-endpoints-module/test-app-express-cjs/package.json

@@ -6,17 +6,10 @@
   "private": true,
   "license": "UNLICENSED",
   "scripts": {
-    "build": "nest build",
     "dev": "tsx watch --include ./node_modules/nestjs-endpoints/dist --clear-screen=false --inspect=0 ./src/main.ts",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
-    "start": "nest start",
-    "start:dev": "nest start --watch",
-    "start:debug": "nest start --debug --watch",
+    "build": "nest build",
     "start:prod": "node dist/main",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:cov": "jest --coverage",
-    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "codegen": "tsx ./src/codegen.ts",
     "test:e2e": "jest --config ./test/jest-e2e.json"
   },
   "dependencies": {
@@ -35,7 +28,9 @@
     "@types/jest": "^29.5.2",
     "@types/node": "^20.3.1",
     "@types/supertest": "^2.0.12",
+    "axios": "^1.7.9",
     "jest": "^29.5.0",
+    "orval": "^7.5.0",
     "prettier": "^3.0.0",
     "source-map-support": "^0.5.21",
     "supertest": "^7.0.0",

packages/test-endpoints-module/test-app-express-cjs/src/app.module.ts

@@ -12,8 +12,8 @@ import {
 } from 'nestjs-endpoints';
 import { Observable, catchError, throwError } from 'rxjs';
 import { ZodError } from 'zod';
-import { TestModule } from './test/test.module';
-import { UserModule } from './user/user.module';
+import { TestModule } from './endpoints/test/test.module';
+import { UserModule } from './endpoints/user/user.module';
 
 @Injectable()
 export class ZodErrorInterceptor implements NestInterceptor {
@@ -35,7 +35,7 @@ export class ZodErrorInterceptor implements NestInterceptor {
 @Module({
   imports: [
     EndpointsRouterModule.forRoot({
-      rootDirectory: './',
+      rootDirectory: './endpoints',
       autoLoadEndpoints: false,
     }),
     UserModule,

packages/test-endpoints-module/test-app-express-cjs/src/codegen.ts

@@ -0,0 +1,13 @@
+import { NestFactory } from '@nestjs/core';
+import { setupOpenAPI } from 'nestjs-endpoints';
+import { generate } from 'orval';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await setupOpenAPI(app, {
+    outputFile: 'openapi.json',
+  });
+  void generate();
+}
+void bootstrap();