Remove patchNestJsSwagger in favour of _OPENAPI_METADATA_FACTORY and misc changes (#142)

Author: BenLorantfy

.github/workflows/release.yml

@@ -30,7 +30,22 @@ jobs:
       - name: Build example app
         run: cd packages/example && pnpm run build
       - name: Test example app
-        run: cd packages/example && pnpm run test:e2e
+        run: cd packages/example && pnpm run test
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('packages/example/package.json') }}
+          restore-keys: |
+            playwright-${{ runner.os }}-
+      - name: Install Playwright Browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: cd packages/example && pnpm exec playwright install --with-deps
+      - name: Test example app swagger
+        run: |
+          cd packages/example && pnpm run start &
+          cd packages/example && pnpm run test:swagger
 
       - name: Extract version
         id: version
@@ -48,6 +63,7 @@ jobs:
         run: |
           cp logo.svg packages/nestjs-zod
           cp README.md packages/nestjs-zod
+          sed -i 's/\/packages\/example/\.\.\/example/g' packages/nestjs-zod/README.md
 
       - name: Create NPM config
         run: cd packages/nestjs-zod && npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

.github/workflows/test-and-build.yml

@@ -2,9 +2,9 @@ name: Test and Build
 
 on:
   push:
-    branches: ['main']
+    branches: ['main', 'v5']
   pull_request:
-    branches: ['main']
+    branches: ['main', 'v5']
 
 jobs:
   test-and-build:
@@ -32,4 +32,20 @@ jobs:
       - name: Build example app
         run: cd packages/example && pnpm run build
       - name: Test example app
-        run: cd packages/example && pnpm run test:e2e
+        run: cd packages/example && pnpm run test
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('packages/example/package.json') }}
+          restore-keys: |
+            playwright-${{ runner.os }}-
+      - name: Install Playwright Browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: cd packages/example && pnpm exec playwright install --with-deps
+      - name: Test example app swagger
+        run: |
+          cd packages/example && pnpm run start &
+          cd packages/example && pnpm run test:swagger
+

MIGRATION.md

@@ -1,5 +1,55 @@
 # Migration
 
+## From version 4.x to 5.x
+### `patchNestJsSwagger` has been removed
+There is no need to call `patchNestJsSwagger` anymore.  The call to `patchNestJsSwagger` can simply be removed:
+```diff
+- patchNestJsSwagger()
+```
+
+### Deprecated `createZodGuard`, `UseZodGuard`, and `ZodGuard`
+
+`createZodGuard` and friends have been deprecated.  This was a mistake to add to the library, for a few reasons:
+1. It clearly states in the nestjs documentation that guards are only meant for authorization, not for validation:
+
+> Guards have a single responsibility. They determine whether a given request will be handled by the route handler or not, depending on certain conditions (like permissions, roles, ACLs, etc.) present at run-time. This is often referred to as authorization
+
+2. `createZodGuard` uses `validate` which is also deprecated 
+3. `createZodGuard` didn't do anything special.  You can create your own guard that does the same thing with very few lines of code.  However, it's recommended to use guards for authorization, not exclusively validation.  That's not to say you can't use zod inside a guard, but the main purpose of the guard should be authorization.
+
+### Deprecated `validate`
+`validate` was a redudant and confusingly named function (it should have been called `parse` if we wanted to keep it).  You can simply use the `.parse` function that is attached to the zod schema:
+
+```ts
+const MySchema = z.object(...);
+const knownData = MySchema.parse(unknownData);
+```
+
+Or if you have a DTO:
+```ts
+class PostDto extends createZodDto(...) {}
+PostDto.schema.parse(...)
+```
+
+### Deprecated `zodToOpenAPI`
+[Zod v4](https://v4.zod.dev/v4#json-schema-conversion) introduces a built-in method of converting zod schemas to OpenAPI, so this function is no longer needed.
+
+```ts
+import * as z from "zod";
+ 
+const mySchema = z.object({name: z.string(), points: z.number()});
+ 
+z.toJSONSchema(mySchema);
+// => {
+//   type: "object",
+//   properties: {
+//     name: {type: "string"},
+//     points: {type: "number"},
+//   },
+//   required: ["name", "points"],
+// }
+```
+
 ## From version 3.x to 4.x
 
 ### `nestjs-zod/z` is now `@nest-zod/z`

README.md

@@ -25,21 +25,13 @@
 
 - `createZodDto` - create DTO classes from Zod schemas
 - `ZodValidationPipe` - validate `body` / `query` / `params` using Zod DTOs
-- `ZodGuard` - guard routes by validating `body` / `query` / `params`  
-  (it can be useful when you want to do that before other guards)
-- `UseZodGuard` - alias for `@UseGuards(new ZodGuard(source, schema))`
 - `ZodValidationException` - BadRequestException extended with Zod errors
 - `zodToOpenAPI` - create OpenAPI declarations from Zod schemas
 - OpenAPI support
   - `@nestjs/swagger` integration using the patch
   - `zodToOpenAPI` - generate highly accurate Swagger Schema
   - Zod DTOs can be used in any `@nestjs/swagger` decorator
-- Extended Zod schemas for NestJS (`@nest-zod/z`)
-  - **Note:** _`@nest-zod/z` is deprecated and will not be supported soon.  It is recommended to use `zod` directly.  See [MIGRATION.md](./MIGRATION.md) for more information._
-  - `dateString` for dates (supports casting to `Date`)
-  - `password` for passwords (more complex string rules + OpenAPI conversion)
 - Customization - change exception format easily
-- Useful helpers for client side error handling (`nestjs-zod/frontend`)
 
 ## Installation
 
@@ -52,7 +44,7 @@ Peer dependencies:
 - `zod` - `>= 3.14.3`
 - `@nestjs/common` - `>= 8.0.0` (required on server side)
 - `@nestjs/core` - `>= 8.0.0` (required on server side)
-- `@nestjs/swagger` - `>= 5.0.0` (only when using `patchNestJsSwagger`)
+- `@nestjs/swagger` - `>= 5.0.0`
 
 All peer dependencies are marked as optional for better client side usage, but you need to install required ones when using `nestjs-zod` on server side.
 
@@ -200,6 +192,9 @@ const MyZodValidationPipe = createZodValidationPipe({
 
 ## Using ZodGuard
 
+> [!CAUTION]
+> `ZodGuard` is deprecated and will not be supported soon.  It is recommended to use guards for authorization, not validation. See [MIGRATION.md](./MIGRATION.md) for more information.
+
 Sometimes, we need to validate user input before specific Guards. We can't use Validation Pipe since NestJS Pipes are always executed after Guards.
 
 The solution is `ZodGuard`. It works just like `ZodValidationPipe`, except for that is doesn't transform the input.
@@ -234,6 +229,9 @@ class MyController {
 
 ### Creating custom guard
 
+> [!CAUTION]
+> `createZodGuard` is deprecated and will not be supported soon.  It is recommended to use guards for authorization, not validation. See [MIGRATION.md](./MIGRATION.md) for more information.
+
 ```ts
 import { createZodGuard } from 'nestjs-zod'
 
@@ -246,6 +244,9 @@ const MyZodGuard = createZodGuard({
 
 ## Create validation from scratch
 
+> [!CAUTION]
+> `validate` is deprecated and will not be supported soon.  It is recommended to use `.parse` directly. See [MIGRATION.md](./MIGRATION.md) for more information.
+
 If you don't like `ZodGuard` and `ZodValidationPipe`, you can use `validate` function:
 
 ```ts
@@ -561,19 +562,13 @@ function mapToFormErrors(issues: ZodIssue[]) {
 
 ## OpenAPI (Swagger) support
 
-### Setup
-
-Prerequisites:
+> [!Note]
+> There used to be a function called `patchNestJsSwagger`.  This function has been removed since it is no longer neccessary to call.  
 
-- `@nestjs/swagger` with version `^5.0.0` installed
-
-Apply the patch `patchNestJsSwagger()` in your `main.ts` file before setting up your swagger module:
-
-```ts
-import { patchNestJsSwagger } from 'nestjs-zod'
-
-patchNestJsSwagger()
-```
+If you have `@nestjs/swagger` setup, documentation will automatically be generated for:
+- Request bodies, if you use `@Body() body: MyDto`
+- Response bodies, if you use `@ApiOkResponse({ type: MyDto })`
+- Query params, if you use `@Query() query: MyQueryParamsDto`
 
 For addtional documentation, follow the [Nest.js' Swagger Module Guide](https://docs.nestjs.com/openapi/introduction), or you can see the example application guide [here](/packages/example/) .
 
@@ -592,6 +587,9 @@ const CredentialsSchema = z.object({
 
 ### Using zodToOpenAPI
 
+> [!CAUTION]
+> `zodToOpenAPI` is deprecated and will not be supported soon, since zod v4 adds built-in support for generating OpenAPI schemas from zod scehams.  See [MIGRATION.md](./MIGRATION.md) for more information.
+
 You can convert any Zod schema to an OpenAPI JSON object:
 
 ```ts

packages/example/.gitignore

@@ -54,3 +54,10 @@ pids
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Playwright
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

packages/example/README.md

@@ -83,3 +83,4 @@ Nest is an MIT-licensed open source project. It can grow thanks to the sponsors
 ## License
 
 Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+

packages/example/package.json

@@ -14,17 +14,14 @@
     "start:prod": "node dist/main",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
     "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",
-    "test:e2e": "jest --config ./test/jest-e2e.json"
+    "test:swagger": "playwright test"
   },
   "dependencies": {
+    "@nest-zod/z": "workspace:*",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",
     "@nestjs/swagger": "^11.0.1",
-    "@nest-zod/z": "workspace:*",
     "nestjs-zod": "workspace:*",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.1",
@@ -34,6 +31,7 @@
     "@nestjs/cli": "^11.0.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",
+    "@playwright/test": "^1.52.0",
     "@types/express": "^4.17.17",
     "@types/jest": "^29.5.2",
     "@types/node": "^22.7.5",

packages/example/playwright.config.ts

@@ -0,0 +1,79 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './swagger-tests',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    // baseURL: 'http://127.0.0.1:3000',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'npm run start',
+  //   url: 'http://127.0.0.1:3000',
+  //   reuseExistingServer: !process.env.CI,
+  // },
+});

packages/example/test/app.e2e-spec.ts packages/example/src/app.spec.tspackages/example/test/app.e2e-spec.ts renamed to packages/example/src/app.spec.ts

@@ -1,9 +1,6 @@
 import { NestFactory } from '@nestjs/core';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 import { AppModule } from './app.module';
-import { patchNestJsSwagger } from 'nestjs-zod';
-
-patchNestJsSwagger()
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);