Merge pull request #20 from rhyek/zod-openapi

zod-openapi library

Author: rhyek

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.5.0 (2025-06-22)
+
+### Features
+
+- Replaced `nestjs-zod` with [zod-openapi](https://github.com/samchungy/zod-openapi). The main benefit is output schemas will now emit OpenApi schemas and consequently TypeScript definitions for endpoint payloads that consider `ZodEffects`.
+
+Example:
+
+```typescript
+const schema = z.object({
+  age: z.number().default(30),
+});
+```
+
+The above schema when used in `input` will still mark `age` as optional, but when used in `output` it will not.
+
+```typescript
+type ExampleInput = {
+  age?: number;
+};
+
+type ExampleOutput = {
+  age: number;
+};
+```
+
 ## 1.4.0 (2025-06-13)
 
 ### Features

README.md

@@ -42,7 +42,7 @@ const { data: greeting, error, status } = useHelloWorld();
   - **File-based routing:** Endpoints' HTTP paths are based on their path on disk.
 - **Traditional setup**: Explicitly set HTTP paths and import endpoints like regular controlllers.
 - **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/).
+- **End-to-end type safety:** Auto-generates `axios` and `@tanstack/react-query` client libraries. Internally uses `@nestjs/swagger`, [zod-openapi](https://github.com/samchungy/zod-openapi), and [orval](https://orval.dev/).
 - **HTTP adapter agnostic:** Works with both Express and Fastify NestJS applications.
 - **Supports CommonJS and ESM**
 
@@ -341,6 +341,37 @@ More examples:
 - [axios](https://github.com/rhyek/nestjs-endpoints/blob/f9fc77c0af9439e35e2ed3f26aa3e645795ed44f/packages/test/test-app-express-cjs/test/client.e2e-spec.ts#L15)
 - [react-query](https://github.com/rhyek/nestjs-endpoints/tree/main/packages/test/test-react-query-client)
 
+### Handling ZodEffects in output schemas
+
+The following configuration will not work:
+
+```typescript
+export default endpoint({
+  ...
+  output: z.object({
+    name: z.string()
+      .transform((s) => s.toUpperCase())
+  }),
+  ...
+})
+```
+
+The `.transform` creates a `ZodEffect` whos output type in some cases cannot be known at run-time (only compile-time), and an OpenApi schema cannot be inferred. More info [here](https://github.com/samchungy/zod-openapi?tab=readme-ov-file#effecttype).
+
+To fix it, do the following:
+
+```typescript
+export default endpoint({
+  ...
+  output: z.object({
+    name: z.string()
+      .transform((s) => s.toUpperCase())
+      .openapi({ effectType: 'same' }),
+  }),
+  ...
+})
+```
+
 ### Manual codegen with OpenAPI spec file
 
 If you just need the OpenAPI spec file or prefer to configure orval or some other tool yourself, you can do the following:

eslint.config.js

@@ -1,7 +1,6 @@
 // @ts-check
 import eslint from '@eslint/js';
 import importPlugin from 'eslint-plugin-import';
-import pluginJest from 'eslint-plugin-jest';
 import eslintConfigPrettier from 'eslint-plugin-prettier/recommended';
 import unusedImports from 'eslint-plugin-unused-imports';
 import tseslint from 'typescript-eslint';
@@ -81,16 +80,6 @@ export default tseslint.config(
       'no-console': 'error',
     },
   },
-  {
-    files: ['packages/**/*.e2e-spec.ts'],
-    ...pluginJest.configs['flat/recommended'],
-    rules: {
-      ...pluginJest.configs['flat/recommended'].rules,
-      'jest/expect-expect': 'off',
-      'jest/no-disabled-tests': 'error',
-      'jest/no-focused-tests': 'error',
-    },
-  },
   {
     files: ['packages/test/test-react-query-client/**'],
     rules: {

package.json

@@ -9,27 +9,22 @@
     "prepare": "husky"
   },
   "devDependencies": {
-    "@eslint/js": "^9.20.0",
+    "@eslint/js": "^9.29.0",
     "@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",
-    "eslint-config-prettier": "^9.0.0",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jest": "^28.11.0",
-    "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-prettier": "^5.4.1",
     "eslint-plugin-unused-imports": "^4.1.4",
     "husky": "^9.1.7",
     "lint-staged": "^15.4.3",
     "prettier": "^3.0.0",
     "typescript-eslint": "^8.24.0",
-    "zod": "^3.24.1"
-  },
-  "pnpm": {
-    "overrides": {
-      "reflect-metadata": "0.1.14"
-    }
+    "zod": "^3.25.67",
+    "reflect-metadata": "^0.1.13"
   }
 }

packages/nestjs-endpoints/package.json

@@ -26,41 +26,37 @@
     "src",
     "dist"
   ],
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/esm/index.d.ts",
   "exports": {
     ".": {
-      "require": {
-        "default": "./dist/cjs/index.js",
-        "types": "./dist/cjs/index.d.ts"
-      },
-      "import": {
-        "default": "./dist/esm/index.js",
-        "types": "./dist/esm/index.d.ts"
-      }
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js"
     }
   },
-  "types": "./dist/cjs/index.d.ts",
+  "sideEffects": false,
   "scripts": {
-    "dev": "tsc-watch --preserveWatchOutput --onSuccess \"../../scripts/build.sh\""
+    "dev": "tsc-watch --preserveWatchOutput --onSuccess \"../../scripts/build.sh\"",
+    "test": "vitest"
   },
   "dependencies": {
     "@orval/query": "~7.8.0",
     "callsites": "^3.1.0",
-    "nestjs-zod": "npm:@rhyek/[email protected]",
-    "orval": "~7.8.0"
+    "openapi-types": "^12.1.3",
+    "orval": "~7.8.0",
+    "zod-openapi": "^4.2.4"
   },
   "peerDependencies": {
     "@nestjs/common": ">=10.0.0",
     "@nestjs/core": ">=10.0.0",
     "@nestjs/swagger": ">=7.0.0",
-    "zod": ">=3.0.0"
+    "zod": ">=3.25.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.2",
     "@types/node": "^22.13.1",
-    "jest": "^29.5.0",
-    "ts-jest": "^29.1.0",
     "tsc-alias": "^1.8.10",
     "tsc-watch": "^6.2.1",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
   }
 }

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

@@ -4,7 +4,7 @@ import { Writable } from 'node:stream';
 import { INestApplication } from '@nestjs/common';
 import { DocumentBuilder } from '@nestjs/swagger';
 import type { QueryOptions } from 'orval';
-import { setupOpenAPI } from '../setup';
+import { setupOpenAPI } from '../setup-openapi';
 import { axios } from './builder/axios';
 import { reactQuery } from './builder/react-query';
 

packages/nestjs-endpoints/src/consts.ts

@@ -8,6 +8,18 @@ export const settings: {
       basePath: string;
     }) => void;
   }[];
+  openapi: {
+    components: {
+      schemas: Record<string, any>;
+    };
+  };
 } = {
   endpoints: [],
+  openapi: {
+    components: {
+      schemas: {},
+    },
+  },
 };
+
+export const openApiVersion = '3.0.0';

packages/nestjs-endpoints/src/endpoint-fn.ts

@@ -16,20 +16,20 @@ import {
 } from '@nestjs/common';
 import { HttpAdapterHost } from '@nestjs/core';
 import { ApiBody, ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { z, ZodSchema } from 'zod';
+import { settings } from './consts';
 import {
-  createZodDto,
   ZodSerializationException,
   ZodValidationException,
-} from 'nestjs-zod';
-import { z, ZodSchema } from 'zod';
-import { settings } from './consts';
+} from './exceptions';
 import {
   ApiQueries,
   getCallsiteFile,
   getEndpointHttpPath,
   getHttpPathPascalName,
   moduleAls,
 } from './helpers';
+import { zodToOpenApi } from './zod-to-openapi';
 
 type HttpMethod =
   | 'get'
@@ -39,6 +39,7 @@ type HttpMethod =
   | 'patch'
   | 'head'
   | 'options';
+
 const httpMethodDecorators = {
   get: Get,
   post: Post,
@@ -563,29 +564,37 @@ export function endpoint<
       ...(decorators ?? []),
     ];
     if (input) {
-      const schema = input instanceof SchemaDef ? input.schema : input;
-      const dto = createZodDto(schema as any);
+      const schema: ZodSchema =
+        input instanceof SchemaDef ? input.schema : input;
       const schemaName = httpPathPascalName + 'Input';
-      Object.defineProperty(dto, 'name', { value: schemaName });
       if (httpMethod === 'get') {
-        methodDecorators.push(ApiQueries(dto.schema as any));
+        methodDecorators.push(ApiQueries(schema as any));
       } else {
-        methodDecorators.push(ApiBody({ type: dto }));
+        const { openApiSchema } = zodToOpenApi({
+          schema,
+          schemaType: 'input',
+          ref: schemaName,
+        });
+        methodDecorators.push(ApiBody({ schema: openApiSchema }));
       }
     }
     if (outputSchemas) {
       for (const [status, schema] of Object.entries(outputSchemas)) {
-        const s = schema instanceof SchemaDef ? schema.schema : schema;
-        const dto = createZodDto(s as any);
+        const s: ZodSchema =
+          schema instanceof SchemaDef ? schema.schema : schema;
         const schemaName =
           httpPathPascalName +
           `${status === '200' ? '' : status}` +
           'Output';
-        Object.defineProperty(dto, 'name', { value: schemaName });
+        const { openApiSchema } = zodToOpenApi({
+          schema: s,
+          schemaType: 'output',
+          ref: schemaName,
+        });
         methodDecorators.push(
           ApiResponse({
             status: Number(status),
-            type: dto,
+            schema: openApiSchema,
             description:
               schema instanceof SchemaDef ? schema.description : undefined,
           }),

packages/nestjs-endpoints/src/exceptions.ts

@@ -0,0 +1,30 @@
+import {
+  BadRequestException,
+  HttpStatus,
+  InternalServerErrorException,
+} from '@nestjs/common';
+import { ZodError } from 'zod';
+
+export class ZodValidationException extends BadRequestException {
+  constructor(private error: ZodError) {
+    super({
+      statusCode: HttpStatus.BAD_REQUEST,
+      message: 'Validation failed',
+      errors: error.errors,
+    });
+  }
+
+  public getZodError() {
+    return this.error;
+  }
+}
+
+export class ZodSerializationException extends InternalServerErrorException {
+  constructor(private error: ZodError) {
+    super();
+  }
+
+  public getZodError() {
+    return this.error;
+  }
+}

packages/nestjs-endpoints/src/helpers.ts

@@ -3,8 +3,9 @@ import path from 'node:path';
 import { applyDecorators } from '@nestjs/common';
 import { ApiQuery, ApiQueryOptions } from '@nestjs/swagger';
 import callsites from 'callsites';
-import { zodToOpenAPI } from 'nestjs-zod';
 import { z, ZodRawShape } from 'zod';
+import { createSchema } from 'zod-openapi';
+import { zodToOpenApi } from './zod-to-openapi';
 
 function isDirPathSegment(dir: string) {
   const segment = path.basename(dir);
@@ -70,16 +71,24 @@ export const ApiQueries = <T extends z.ZodObject<ZodRawShape>>(
   zodObject: T,
 ) => {
   const optionsList = Object.keys(zodObject.shape).reduce<
-    Array<ApiQueryOptions & { schema: ReturnType<typeof zodToOpenAPI> }>
+    Array<
+      ApiQueryOptions & {
+        schema: ReturnType<typeof createSchema>['schema'];
+      }
+    >
   >((acc, name) => {
     const zodType = zodObject.shape[name];
-
-    if (zodType)
+    if (zodType) {
+      const { openApiSchema } = zodToOpenApi({
+        schema: zodType,
+        schemaType: 'input',
+      });
       acc.push({
         name,
         required: !zodType.isOptional(),
-        schema: (zodToOpenAPI as any)(zodType),
+        schema: openApiSchema,
       });
+    }
 
     return acc;
   }, []);