From 251c6a51eb9d494296ec047b7cdc85d60505286e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?syuilo=E2=AD=90=EF=B8=8F?= <Syuilotan@yahoo.co.jp>
Date: Fri, 3 Mar 2017 09:48:06 +0900
Subject: [PATCH] Update it.ts

---
 src/api/it.ts | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/api/it.ts b/src/api/it.ts
index 14f6063b2..21cc872a2 100644
--- a/src/api/it.ts
+++ b/src/api/it.ts
@@ -26,6 +26,30 @@
  * const [val, err] = it(x).expect.string().required().qed();
  */
 
+/**
+ * null と undefined の扱い
+ *
+ * 「値がnullまたはundefined」な状態を「値が空である」と表現しています。
+ * 値が空である場合、バリデータやその他の処理メソッドは呼ばれません。
+ *
+ * 内部的にはnullとundefinedを次のように区別しています:
+ * null ... 値が「無い」と明示されている
+ * undefined ... 値を指定していない
+ *
+ * 例えばアカウントのプロフィールを更新するAPIに次のデータを含むリクエストが来たとします:
+ * { name: 'Alice' }
+ * アカウントには本来、他にも birthday といったフィールドがありますが、
+ * このリクエストではそれに触れず、ただ単に name フィールドを更新することを要求しています。
+ * ここで、このリクエストにおける birthday フィールドは undefined なわけですが、
+ * それはnull(=birthdayを未設定にしたい)とは違うものです。
+ * undefined も null も区別しないとしたら、触れていないフィールドまでリセットされることになってしまいます。
+ * ですので、undefined と null は区別しています。
+ *
+ * 値が空であってほしくない場合は .require() を、
+ * 値を必ず指定しなければならない場合(値を「無し」に指定することは許可)は .notUndefined() を、
+ * 値の指定をしなくてもいいけど、する場合は「無し」は許可しない場合は .notNull() を使えます。
+ */
+
 import * as mongo from 'mongodb';
 import hasDuplicates from '../common/has-duplicates';