From 0bf94b2f8d06bfb45a3b1438ef0679977a931ba1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20B=C3=BCtzer?= <rbuetzer@users.noreply.github.com>
Date: Sat, 3 Feb 2024 01:34:04 +0100
Subject: [PATCH] Add docs for coercing nullish values (#3067)

* Add docs for coercing nullish values

* Clean up coerce doc

* Tweak

---------

Co-authored-by: Colin McDonnell <colinmcd94@gmail.com>
---
 README.md          | 21 +++++++++++++++++----
 deno/lib/README.md | 21 +++++++++++++++++----
 playground.ts      | 28 +---------------------------
 3 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 99bda0e3d..5d13aeb25 100644
--- a/README.md
+++ b/README.md
@@ -715,16 +715,19 @@ Zod now provides a more convenient way to coerce primitive values.
 const schema = z.coerce.string();
 schema.parse("tuna"); // => "tuna"
 schema.parse(12); // => "12"
-schema.parse(true); // => "true"
 ```
 
-During the parsing step, the input is passed through the `String()` function, which is a JavaScript built-in for coercing data into strings. Note that the returned schema is a `ZodString` instance so you can use all string methods.
+During the parsing step, the input is passed through the `String()` function, which is a JavaScript built-in for coercing data into strings.
+
+The returned schema is a normal `ZodString` instance so you can use all string methods.
 
 ```ts
 z.coerce.string().email().min(5);
 ```
 
-All primitive types support coercion.
+**How coercion works**
+
+All primitive types support coercion. Zod coerces all inputs using the built-in constructors: `String(input)`, `Number(input)`, `new Date(input)`, etc.
 
 ```ts
 z.coerce.string(); // String(input)
@@ -734,9 +737,19 @@ z.coerce.bigint(); // BigInt(input)
 z.coerce.date(); // new Date(input)
 ```
 
+Note that some behavior may not be what you expect.
+
+```ts
+schema.parse(true); // => "true"
+schema.parse(undefined); // => "undefined"
+schema.parse(null); // => "null"
+```
+
+For more control over coercion logic, consider using [`z.preprocess`](#preprocess) or [`z.pipe()`](#pipe).
+
 **Boolean coercion**
 
-Zod's boolean coercion is very simple! It passes the value into the `Boolean(value)` function, that's it. Any truthy value will resolve to `true`, any falsy value will resolve to `false`.
+Zod's approach to coercion is very simple! It passes the value into the `Boolean(value)` function, that's it. Any truthy value will resolve to `true`, any falsy value will resolve to `false`.
 
 ```ts
 z.coerce.boolean().parse("tuna"); // => true
diff --git a/deno/lib/README.md b/deno/lib/README.md
index f12fd1582..136ff706f 100644
--- a/deno/lib/README.md
+++ b/deno/lib/README.md
@@ -714,16 +714,19 @@ Zod now provides a more convenient way to coerce primitive values.
 const schema = z.coerce.string();
 schema.parse("tuna"); // => "tuna"
 schema.parse(12); // => "12"
-schema.parse(true); // => "true"
 ```
 
-During the parsing step, the input is passed through the `String()` function, which is a JavaScript built-in for coercing data into strings. Note that the returned schema is a `ZodString` instance so you can use all string methods.
+During the parsing step, the input is passed through the `String()` function, which is a JavaScript built-in for coercing data into strings.
+
+The returned schema is a normal `ZodString` instance so you can use all string methods.
 
 ```ts
 z.coerce.string().email().min(5);
 ```
 
-All primitive types support coercion.
+**How coercion works**
+
+All primitive types support coercion. Zod coerces all inputs using the built-in constructors: `String(input)`, `Number(input)`, `new Date(input)`, etc.
 
 ```ts
 z.coerce.string(); // String(input)
@@ -733,9 +736,19 @@ z.coerce.bigint(); // BigInt(input)
 z.coerce.date(); // new Date(input)
 ```
 
+Note that some behavior may not be what you expect.
+
+```ts
+schema.parse(true); // => "true"
+schema.parse(undefined); // => "undefined"
+schema.parse(null); // => "null"
+```
+
+For more control over coercion logic, consider using [`z.preprocess`](#preprocess) or [`z.pipe()`](#pipe).
+
 **Boolean coercion**
 
-Zod's boolean coercion is very simple! It passes the value into the `Boolean(value)` function, that's it. Any truthy value will resolve to `true`, any falsy value will resolve to `false`.
+Zod's approach to coercion is very simple! It passes the value into the `Boolean(value)` function, that's it. Any truthy value will resolve to `true`, any falsy value will resolve to `false`.
 
 ```ts
 z.coerce.boolean().parse("tuna"); // => true
diff --git a/playground.ts b/playground.ts
index d996a212a..da58d74d0 100644
--- a/playground.ts
+++ b/playground.ts
@@ -1,29 +1,3 @@
 import { z } from "./src";
-import * as mod from "node:module";
-z;
 
-// @ts-ignore
-// const arg = await import("./index");
-// arg;
-// require.resolve(arg);
-
-load: {
-}
-interface A<T> {
-  name: T;
-  children: any;
-  render(): ReadableStream | string;
-}
-function Hyper<T>(arg: T) {
-  return function () {} as any as {
-    prototype: A<T>;
-    new (): A<T>;
-  };
-}
-
-export default class extends Hyper({ name: 1234 }) {
-  render() {
-    // this.name.name;
-    return `asdf ${this.children} asdf`;
-  }
-}
+z;
\ No newline at end of file