Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme: explainting the well-known issue with coerce. #1116

Merged
merged 4 commits into from
Aug 24, 2023
Merged

Readme: explainting the well-known issue with coerce. #1116

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3c44f5c
Readme: explainting the well-known issue with coerce.
Aug 24, 2023
5a0e6ab
Minor: correction.
Aug 24, 2023
2aa0617
More links.
Aug 24, 2023
3cd644b
Even more links.
Aug 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,9 @@ Start your API server with I/O schema validation and custom middlewares in minut
19. [Generating a Frontend Client](#generating-a-frontend-client)
20. [Creating a documentation](#creating-a-documentation)
21. [Tagging the endpoints](#tagging-the-endpoints)
5. [Additional hints](#additional-hints)
1. [How to test endpoints](#how-to-test-endpoints)
22. [How to test endpoints](#how-to-test-endpoints)
5. [Caveats](#caveats)
1. [Coercive schema of Zod](#coercive-schema-of-zod)
2. [Excessive properties in endpoint output](#excessive-properties-in-endpoint-output)
6. [Your input to my output](#your-input-to-my-output)

Expand Down Expand Up @@ -918,8 +919,6 @@ const exampleEndpoint = taggedEndpointsFactory.build({
});
```

# Additional hints

## How to test endpoints

The way to test endpoints is to mock the request, response, and logger objects, invoke the `execute()` method, and
Expand Down Expand Up @@ -950,6 +949,21 @@ test("should respond successfully", async () => {
_This method is optimized for the `defaultResultHandler`. With the flexibility to customize, you can add additional
properties as needed._

# Caveats

There are some well-known issue and limitations, or third party bugs that cannot be fixed in the usual way, but you
should be aware of them.

## Coercive schema of Zod

Despite being supported by the library, `z.coerce.*` schema
[does not work intuitively](https://github.com/RobinTail/express-zod-api/issues/759).
Please be aware that `z.coerce.number()` and `z.number({ coerce: true })` (being typed not well) still will NOT allow
you to assign anything but number. Moreover, coercive schemas are not fail-safe and their methods `.isOptional()` and
`.isNullable()` [are buggy](https://github.com/colinhacks/zod/issues/1911). If possible, try to avoid using this type
of schemas. This issue [will NOT be fixed](https://github.com/colinhacks/zod/issues/1760#issuecomment-1407816838) in
Zod version 3.x.

## Excessive properties in endpoint output

The schema validator removes excessive properties by default. However, Typescript
Expand Down