From 2d41ed746975b3f6e7c14731235f8af57d40ad8c Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 14 Oct 2024 19:56:43 -0700 Subject: [PATCH] Add warnings and update readme --- MIGRATION.md | 3 +++ README.md | 65 ++++++++++++++++++++++++++-------------------------- 2 files changed, 35 insertions(+), 33 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index d47b2de..2c38a9a 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -10,6 +10,9 @@ The extended zod api was moved out of the main package to a separate package. T ``` Additionally, `@nestjs-zod/z` is deprecated and will not be supported soon. This is because the way `@nestjs-zod/z` extends `zod` is brittle and breaks in patch versions of zod. If you still want to use the functionality of `password` and `dateString`, you can implement the same logic using [refine()](https://zod.dev/?id=refine) +> [!IMPORTANT] +> It is highly recommended to move towards importing `zod` directly, instead of `@nestjs-zod/z` + ### `nestjs-zod/frontend` is removed The same exports are now available in `@nestjs-zod/z/frontend` (see details about `@nestjs-zod/z` above). This requires a slight change to the import path: ```diff diff --git a/README.md b/README.md index ba76a39..0368c61 100755 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ - `@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 (`nestjs-zod/z`) +- Extended Zod schemas for NestJS (`@nestjs-zod/z`) - `dateString` for dates (supports casting to `Date`) - `password` for passwords (more complex string rules + OpenAPI conversion) - Customization - change exception format easily @@ -64,7 +64,6 @@ All peer dependencies are marked as optional for better client side usage, but y ## Navigation -- [Writing Zod schemas](#writing-zod-schemas) - [Creating DTO from Zod schema](#creating-dto-from-zod-schema) - [Using DTO](#using-dto) - [Using ZodValidationPipe](#using-zodvalidationpipe) @@ -87,32 +86,11 @@ All peer dependencies are marked as optional for better client side usage, but y - [Writing more Swagger-compatible schemas](#writing-more-swagger-compatible-schemas) - [Using zodToOpenAPI](#using-zodtoopenapi) -## Writing Zod schemas - -Extended Zod and Swagger integration are bound to the internal API, so even the patch updates can cause errors. - -For that reason, `nestjs-zod` uses specific `zod` version inside and re-exports it under `/z` scope: - -```ts -import { z, ZodString, ZodError } from 'nestjs-zod/z' - -const CredentialsSchema = z.object({ - username: z.string(), - password: z.string(), -}) -``` - -Zod's classes and types are re-exported too, but under `/z` scope for more clarity: - -```ts -import { ZodString, ZodError, ZodIssue } from 'nestjs-zod/z' -``` - ## Creating DTO from Zod schema ```ts import { createZodDto } from 'nestjs-zod' -import { z } from 'nestjs-zod/z' +import { z } from 'zod' const CredentialsSchema = z.object({ username: z.string(), @@ -378,10 +356,16 @@ In the above example, despite the `userService.findOne` method returns `password ## Extended Zod -As you learned in [Writing Zod Schemas](#writing-zod-schemas) section, `nestjs-zod` provides a special version of Zod. It helps you to validate the user input more accurately by using our custom schemas and methods. +> [!IMPORTANT] +> `@nestjs-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. + +`@nestjs-zod/z` provides a special version of Zod. It helps you to validate the user input more accurately by using our custom schemas and methods. ### ZodDateString +> [!IMPORTANT] +> `@nestjs-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. + In HTTP, we always accept Dates as strings. But default Zod only has validations for full date-time strings. `ZodDateString` was created to address this issue. ```ts @@ -458,6 +442,9 @@ Errors: ### ZodPassword +> [!IMPORTANT] +> `@nestjs-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. + `ZodPassword` is a string-like type, just like the `ZodDateString`. As you might have guessed, it's intended to help you with password schemas definition. Also, `ZodPassword` has a more accurate OpenAPI conversion, comparing to regular `.string()`: it has `password` format and generated RegExp string for `pattern`. @@ -496,6 +483,9 @@ Errors: ### Json Schema +> [!IMPORTANT] +> `@nestjs-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. + > Created for `nestjs-zod-prisma` ```ts @@ -504,6 +494,9 @@ z.json() ### "from" function +> [!IMPORTANT] +> `@nestjs-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. + > Created for custom schemas in `nestjs-zod-prisma` Just returns the same Schema @@ -514,6 +507,9 @@ z.from(MySchema) ### Extended Zod Errors +> [!IMPORTANT] +> `@nestjs-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. + Currently, we use `custom` error code due to some Zod limitations (`errorMap` priorities) Therefore, the error details is located inside `params` property: @@ -535,12 +531,16 @@ const error = { ### Working with errors on the client side -Optionally, you can install `nestjs-zod` on the client side. +> [!IMPORTANT] +> `@nestjs-zod/z/frontend` is deprecated and will not be supported soon. It is recommended to use `zod` directly. See [MIGRATION.md](./MIGRATION.md) for more information. + + +Optionally, you can install `@nestjs-zod/z` on the client side. -The library provides you a `/frontend` scope, that can be used to detect custom NestJS Zod issues and process them the way you want. +The library provides you a `@nestjs-zod/z/frontend` entry point, that can be used to detect custom NestJS Zod issues and process them the way you want. ```ts -import { isNestJsZodIssue, NestJsZodIssue, ZodIssue } from 'nestjs-zod/frontend' +import { isNestJsZodIssue, NestJsZodIssue, ZodIssue } from '@nestjs-zod/z/frontend' function mapToFormErrors(issues: ZodIssue[]) { for (const issue of issues) { @@ -551,7 +551,7 @@ function mapToFormErrors(issues: ZodIssue[]) { } ``` -> :warning: **If you use `zod` in your client-side application, and you want to install `nestjs-zod` too, it may be better to completely switch to `nestjs-zod` to prevent issues caused by mismatch between `zod` versions. `nestjs-zod/frontend` doesn't use `zod` at the runtime, but it uses its types.** +> :warning: **If you use `zod` in your client-side application, and you want to install `@nestjs-zod/z` too, it may be better to completely switch to `@nestjs-zod/z` to prevent issues caused by mismatch between `zod` versions. `@nestjs-zod/z/frontend` doesn't use `zod` at the runtime, but it uses its types.** ## OpenAPI (Swagger) support @@ -576,7 +576,7 @@ Then follow the [Nest.js' Swagger Module Guide](https://docs.nestjs.com/openapi/ Use `.describe()` method to add Swagger description: ```ts -import { z } from 'nestjs-zod/z' +import { z } from 'zod' const CredentialsSchema = z.object({ username: z.string().describe('This is an username'), @@ -590,7 +590,7 @@ You can convert any Zod schema to an OpenAPI JSON object: ```ts import { zodToOpenAPI } from 'nestjs-zod' -import { z } from 'nestjs-zod/z' +import { z } from 'zod' const SignUpSchema = z.object({ username: z.string().min(8).max(20), @@ -598,8 +598,7 @@ const SignUpSchema = z.object({ sex: z .enum(['male', 'female', 'nonbinary']) .describe('We respect your gender choice'), - social: z.record(z.string().url()), - birthDate: z.dateString().past(), + social: z.record(z.string().url()) }) const openapi = zodToOpenAPI(SignUpSchema)