From 663d13198756c363b5ee72bdcc2d687f4be9c2e5 Mon Sep 17 00:00:00 2001
From: shimataro <info@shimataro.me>
Date: Fri, 27 May 2022 17:19:17 +0900
Subject: [PATCH] Feature/migration guide (#570)

* add migration guide

* add link to migration guide
---
 README.md    |  2 ++
 migration.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 migration.md

diff --git a/README.md b/README.md
index f565089e..50437d2c 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,8 @@ simple, easy-to-use, and declarative input validator
 
 supports [Node.js](https://nodejs.org/), [TypeScript](https://www.typescriptlang.org/), and [Deno](https://deno.land/)
 
+Please read [migration guide](./migration.md) if you are using old version.
+
 ## Table of Contents
 
 * [Introduction](#introduction)
diff --git a/migration.md b/migration.md
new file mode 100644
index 00000000..c899a2eb
--- /dev/null
+++ b/migration.md
@@ -0,0 +1,86 @@
+# Migration Guide
+
+This document describes breaking changes due to version up.
+
+## v3 to v4
+
+### behavior of `{ifUndefined: undefined}`
+
+In v3, `{ifUndefined: undefined}` is equivalent to `{}`.
+Both versions cause error if input value is `undefined`.
+
+In v4, the former accepts `undefined` (and keeps it as-is), the latter doesn't.
+
+```typescript
+import vs from "value-schema";
+
+const input = {};
+
+// The below code throws error in v3, outputs `{foo: undefined}` in v4.
+{
+    const output = vs.applySchemaObject({
+        foo: vs.number({
+            ifUndefined: undefined,
+        }),
+    }, input);
+    console.log(output);
+}
+
+// The below code throws error in both versions.
+{
+    const output = vs.applySchemaObject({
+        foo: vs.number({}),
+    }, input);
+    console.log(output);
+}
+```
+
+#### for migration
+
+Replace `{ifUndefined: undefined}` with `{}`.
+
+### rename `ValueSchemaError.prototype.cause` to `ValueSchemaError.prototype.rule`
+
+[`Error.prototype.cause`](https://tc39.es/proposal-error-cause/) has come in ES2022.
+It conflicts `ValueSchemaError.prototype.cause`, therefore `ValueSchemaError.prototype.cause` has been renamed to `ValueSchemaError.prototype.rule`, that means "the rule that input value didn't satisfy".
+
+In addition, `CAUSE.foo` has been renamed to `RULE.foo`.
+
+```typescript
+// v3
+import vs from "value-schema";
+
+try {
+    const input = {};
+    const output = vs.applySchemaObject({
+        foo: vs.number(),
+    }, input);
+}
+catch (err) { // ValueSchemaError
+    if (err.cause === vs.CAUSE.UNDEFINED) {
+        console.error("undefined!");
+    }
+}
+```
+
+```typescript
+// v4
+import vs from "value-schema";
+
+try {
+    const input = {};
+    const output = vs.applySchemaObject({
+        foo: vs.number(),
+    }, input);
+}
+catch (err) { // ValueSchemaError
+    if (err.rule === vs.RULE.UNDEFINED) { // cause -> rule
+        console.error("undefined!");
+    }
+}
+```
+
+#### for migration
+
+* Replace `err.cause` with `err.rule`.
+* Replace `vs.CAUSE` with `vs.RULE`.