入力値のバリデーションはこれを使え（2年間でこう進化した）

[Node.jsアドベントカレンダー](https://qiita.com/advent-calendar/2020/nodejs)と[Denoアドベントカレンダー](https://qiita.com/advent-calendar/2020/deno)の9日目の記事です。
同じ記事のURLを複数のアドベントカレンダーに指定できなかったので、1つは短縮URLを使いました。

Node.jsやDenoとはどういうものかついては、以前[さくらのナレッジ](https://knowledge.sakura.ad.jp/24148/)に[寄稿した](https://knowledge.sakura.ad.jp/24150/)のでよければそちらもごらんください。[非同期処理についての記事](https://knowledge.sakura.ad.jp/serialization/javascript-async/)もどうぞ。

# はじめに

[value-schema](https://www.npmjs.com/package/value-schema)というライブラリーをご存知でしょうか。いや、**誰も知るまい**。

[2年前のNode.jsアドベントカレンダー](https://qiita.com/shimataro999/items/12a34961b50b1e45fa9d)で紹介した入力データのバリデーションライブラリー"adjuster"の後継版です。**adjusterも誰も知るまい**。
正確には、後継というよりバージョン2からリネームした地続きのライブラリーなのですが、まあそんな細かいことはどうでもいいです。

数カ月間、実際のアプリケーションなどで使い勝手を徹底的に試してきました。この記事を書いている段階ではバージョン3のリリース候補版ですが、おそらくみなさんが読んでいる頃には正式版としてリリースされています。

本記事では、

- value-schemaとは何か？
- なぜvalue-schemaが必要なのか？
- 2年前からどう変わったのか？

このあたりについて説明します。

# 対象者

- Node.jsまたはDenoで
- Webアプリケーションを作っている人が
- 対象です。

# value-schemaの存在意義

[2年前の記事](https://qiita.com/shimataro999/items/12a34961b50b1e45fa9d#%E3%81%AF%E3%81%98%E3%82%81%E3%81%AB)から引用します。

> Webアプリケーションを開発していて地味に面倒なのが**入力パラメーターの処理**です。異論は認めない。
> 
> だいたいこんな感じのことをほぼすべてのパスで行う必要があるんじゃないでしょうか。
> 
> 1. 存在チェック
>     * 必須パラメーターが存在するか？
>         * 例: `name` が存在するか？
>     * 省略可能パラメーターが省略されていたらデフォルト値を設定
>         * 例: `status` が省略されたら `"active"` を設定
> 1. 型チェック
>     * 期待通りの型か？
>         * 例: `age` は `Number` 型か？
>     * 必要なら型変換
>         * 例: `"20"` → `20`
>         * POSTやPUTではJSONデータのみを受け付けることで型変換を不要にできるが、GETでクエリストリングを処理する場合は型変換が必要
> 1. 定義域チェック
>     * 定義域に収まっているか？
>         * 例: `age` は `0` 以上の整数か？
>     * 必要なら値の調整
>         * 例1: `-1` → `0`
>         * 例2: `20.3` → `20`

あらためて面倒ですよね、はい。
adjusterは、そんな面倒なバリデーション処理を簡潔に、**宣言的に**[^1]記述できるライブラリーです。

[^1]: 宣言的＝型チェックや定義域チェックなどの**ロジックを実装せず**、「`age`は数値型で0以上の整数」「数値文字列の場合は数値型に変換する」「負の値が入力されたら0にする」「小数部分は切り捨てる」のように**あるべき姿**を記述する方式

value-schemaもこの思想は変わらず、より使いやすく改善しました。

# コードで語る

百聞は一見に如かず。実際にコードを見れば便利さはすぐわかります。

例えば、入力値として以下のようなスキーマを想定しているとしましょう。ユーザー管理APIなんかでよくある例だと思います。

- `id`
    - 数値型
    - 1以上
- `name`
    - 文字列型
    - 最大16文字（16文字を超えた分は切り捨てる）
- `age`
    - 数値型
    - 0以上
    - 整数（小数点以下は切り捨て）
- `email`
    - RFCに準拠したEメールアドレス（文字列型）
- `state`
    - 文字列型
    - `"active"`, `"inactive"`のどちらか
- `skills`
    - 文字列型の配列（ただし入力データはカンマ区切りの文字列）
    - 解析時のエラーは無視する（正常に解析できた部分だけで配列を構成する）
- `creditCard`
    - 数字文字列（数字しか含まない文字列）
        - ただし、読みやすさのために`-`で区切られている（`-`が含まれていてもエラーにはせず、最終的には数字文字列のみがほしい）
    - 全角数字も受け付ける（半角に変換する）
    - クレジットカードとして有効な文字列
- `remoteAddr`
    - 文字列
    - IPv4として有効な文字列
- `limit`
    - 数値型
    - 整数（小数部分があればエラー）
    - 1以上（1未満の場合は1にする）
    - 100以下（100を超える場合は100にする）
    - 省略可能（省略時は10）

以上の内容を**全て間違えずにロジックに落とし込む**のはかなり面倒だと思いませんか？
さらに、APIの数だけ入力データもあるので、他のAPIでも同じようなロジックを書かなければいけません。ロジックを完全に使い回せるならいいのですが、微妙に条件が違っていたりして使い回せないことも多いですよね。

value-schemaを使うと、以下のように記述できます。

```typescript
import assert from "assert";
import vs from "value-schema";

const schemaObject = { // 入力スキーマ
	id: vs.number({ // 数値型 / 1以上
		minValue: 1,
	}),
	name: vs.string({ // 文字列型 / 最大16文字（超えた分は切り捨てる）
		maxLength: {
			length: 16,
			trims: true,
		},
	}),
	age: vs.number({ // 数値型 / 0以上 / 整数（小数点以下は切り捨て）
		minValue: 0,
		integer: vs.NUMBER.INTEGER.FLOOR_RZ,
	}),
	email: vs.email(), // RFCに準拠したEメールアドレス（文字列型）
	state: vs.string({ // 文字列型 / "active", "inactive"のどちらか
		only: ["active", "inactive"],
	}),
	skills: vs.array({ // 配列型 / カンマ区切り文字列を配列化 / 配列の要素は文字列型 / 解析時のエラーは無視する
		separatedBy: ",",
		each: {
			schema: vs.string(),
			ignoresErrors: true,
		},
	}),
	creditCard: vs.numericString({ // 数字文字列 / "-"で区切られている / 全角数字も受け付ける（半角に変換する） / クレジットカード用のチェックサムを行う
		separatedBy: "-",
		fullWidthToHalf: true,
		checksum: vs.NUMERIC_STRING.CHECKSUM_ALGORITHM.CREDIT_CARD,
	}),
	remoteAddr: vs.string({ // 文字列型 / IPv4として有効な形式
		pattern: vs.STRING.PATTERN.IPV4,
	}),
	limit: vs.number({ // 数値型 / 整数（小数部分があればエラー） / 1以上（1未満の場合は1にする） / 100以下（100を超える場合は100にする） / 省略可能（省略時は10）
		integer: true,
		minValue: {
			value: 1,
			adjusts: true,
		},
		maxValue: {
			value: 100,
			adjusts: true,
		},
		ifUndefined: 10,
	}),
};
const input = { // 入力値
	id: "1",
	name: "Pablo Diego José Francisco de Paula Juan Nepomuceno María de los Remedios Ciprin Cipriano de la Santísima Trinidad Ruiz y Picasso",
	age: 20.5,
	email: "picasso@example.com",
	state: "active",
	skills: "c,c++,javascript,python,,swift,kotlin",
	creditCard: "4111-1111-1111-１１１１",
	remoteAddr: "127.0.0.1",
};
const expected = { // 最終的にこんな値になってほしい
	id: 1,
	name: "Pablo Diego José",
	age: 20,
	email: "picasso@example.com",
	state: "active",
	skills: ["c", "c++", "javascript", "python", "swift", "kotlin"],
	creditCard: "4111111111111111",
	remoteAddr: "127.0.0.1",
	limit: 10,
};

// 入力スキーマを適用してみる
const actual = vs.applySchemaObject(schemaObject, input);

// 検証
assert.deepStrictEqual(actual, expected);
```

**ね、簡単でしょう？**

記事中のコードなので長く見えるかもしれませんが、同等の機能を自前で書こうと思ったら間違いなくコード量は数倍〜十倍以上にまで膨れ上がります。

そして、何よりこのコードには**ロジックがありません**。`if`や`for`などの制御構文も何もありません。
「`id`は1以上の数値型」のような**データのあるべき姿**を宣言しているだけなので理解しやすく、「あ、条件に『整数であること』を忘れていた！」という発見もしやすくなります。

# adjusterからの変更箇所

3行で。

- Deno対応
- TypeScriptでより使いやすく
- 可読性の高いインターフェース

## Deno対応

バージョン3から[Deno](https://deno.land/)にも対応しました。
Denoで使う場合は以下のようにインポートしてください。

```typescript
import vs from "https://deno.land/x/value_schema/mod.ts";
```

`value-schema`（ダッシュ）ではなく`value_schema`（アンダースコア）であることに注意してください。deno.landへはダッシュがついた名前は登録できなかったのでアンダースコアに変更しました。

Node.jsで使う場合はハイフンです。

```typescript
// npm i value-schema
import vs from "value-schema";
```

## TypeScriptでより使いやすく

これまでもTypeScriptに対応はしていましたが、単に「TypeScriptでも使えます」というだけで型情報を使用者側であらためて定義しなくてはならず、二度手間だったり使い方の間違いをチェックできないといった問題がありました。

たとえばこんな感じです。

```typescript:adjuster（いままで）
import adjuster from "adjuster";

const input: unknown = {}; // 入力データ

interface Parameters {
    foo: number;
    bar: string;
}

// どんな型のデータになるかはGenericsで指定する
const parameters = adjuster.adjust<Parameters>(input, {
    foo: adjuster.number(),
    bar: adjuster.string(),
});
```

しかし、これでは例えば `Parameters.foo` を間違えてstring型にしてしまってもTypeScriptコンパイラーは間違いを検出できず、実行時のどこかのタイミング、たとえば文字列型のメソッドを使った時点で実行時エラーが発生してしまいます。
実行時エラーが発生するならまだいいほうで、場合によってはエラーにならず想定と全く違う動作をして（文字列連結のつもりで数値演算をしてしまうなど）頭を抱えることもあるかもしれません。

value-schema v3ではTypeScriptの型推論を最大限に活用することで、明示的に型を指定することなく**プロパティーの型を自動認識できるようになりました**。

```typescript:value-schema（これから）
import vs from "value-schema";

const input: unknown = {};

// メソッド名が変わっている＆引数の順序が変わっているので注意
const parameters = vs.applySchemaObject({
    foo: vs.number(),
    bar: vs.string(),
}, input);
```

Visual Studio CodeやIntelliJ IDEAなら、以下のようにコード補完もバッチリ使えます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/f3a2a150-97bf-c3f8-fc3b-04e6434366e5.png)
ちゃんと数値型として認識されているので、メソッドも補完できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/8e9bf5e4-8074-8460-28e2-d3d32cabd42c.png)
簡単ですね！

## 可読性の高いインターフェース

adjuster時代は（value-schema v2時代も）値の細かな挙動はメソッドチェーンで指定していました。例えば以下のような感じです。

```typescript
import adjuster from "adjuster";

// パラメーターに求める制約
const constraints = {
    name: adjuster.string().minLength(1),
    age: adjuster.number().integer(true).minValue(0, true),
    status: adjuster.string().default("active").only("active", "inactive"),
};

// parametersに検証済みのパラメーターが入っている
const parameters = adjuster.adjust(input, constraints);
```

このコードは、`integer(true)`や`minValue(0, true)`の`true`が何を意味しているのかわからないですよね。
`integer(true)`は一見すると「整数型にする場合は`true`、しない場合は`false`」かと思いますが、実は「**小数部分を切り捨てるなら`true`、切り捨てずにエラーにするなら`false`**」という意味で誤解を招く内容でした。
`minValue(0, true)`は、「**0より小さい値の場合は強制的に0にするなら`true`、エラーにするなら`false`（あるいは省略）**」という意味です。初見でこんなことわかりませんよね。

これは他の人からも指摘されていたことで、なんとかして改善できないかと考えた結果**チェーンメソッドを廃止して、全てのパラメーターをオブジェクトで渡す**ことにしました。

先ほどのコードと同様の内容をvalue-schemaで書き直すと以下のようになります。

```typescript
import vs from "value-schema";

// パラメーターに求める制約
const constraints = {
    name: vs.string({
        minLength: 1,
    }),
    age: vs.number({
        integer: vs.NUMBER.INTEGER.FLOOR_RZ, // 小数点部分を切り捨て（負の数は0に向けて切り上げ）
        minValue: {
            value: 0,
            adjusts: true,
        },
    }),
    status: vs.string({
        ifUndefined: "active",
        only: ["active", "inactive"],
    }),
};

// parametersに検証済みのパラメーターが入っている
const parameters = vs.applySchemaObject(constraints, input);
```

これなら誤解はありませんね。
丸めの方法も「切り上げ」「切り捨て」「四捨五入」「五捨五超入」など細かく指定できるようになりました。負の数の場合にどうするかも含めて計[10通りの指定方法があります](https://github.com/shimataro/value-schema#integer)。

もちろんパラメーターも補完対象なので、他にどんな指定ができるかもわかります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/d7072014-630c-c365-968b-7018c4f8403f.png)

# Q&A

## 動作環境は？

大抵の環境に対応しています。

- OS: Windows / macOS / Linux
- Node.js: v4以降（v4からv12までテスト済み）
- TypeScript: v3.4.1以降
- Deno: v1以降（v1.0からv1.6までテスト済み）

何が言いたいかというと、[GitHub Actions](https://github.co.jp/features/actions)最高！

## Node.js版とDeno版の違いは？

違いはありません。importのパスにさえ注意すれば、後は全く同じように使えます。

```typescript
// Node.js版: インストールは "npm i value-schema"
import vs from "value-schema";

// Deno版: インストールは不要 / value-schemaではなくvalue_schemaなので注意
import vs from "https://deno.land/x/value_schema/mod.ts";
```

## nullableにしたいんだけど？

null時の挙動は`ifNull`で指定できます。

```typescript
const constraints = {
	foo: vs.number({
		ifNull: null, // nullが指定されたらnullを返す
	}),
	bar: vs.number({
		ifNull: 10, // nullが指定されたら10を返す
	}),
};
```

型推論の結果は、ちゃんと`number | null`型になります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/758d60e3-046b-ebb0-033e-161eef189c1a.png)
`bar`はnullにはならないので、型推論の結果も`number`型です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/0c29db0e-3d27-9b9a-d234-0e2cb38499b7.png)
便利ですね！
これを実現するために型パズルに悩まされたけどね！

また、「省略時はnull」「空文字列が指定されたらnull」という挙動も指定できます。

```typescript
const constraints = {
	foo: vs.number({
		ifUndefined: null, // 省略時はnull
	}),
	bar: vs.number({
		ifEmptyString: null, // 空文字列が渡されたらnull
	}),
};
```

## エラー処理はどうすればいい？

2通りの方法があります。

### エラーが1つでも見つかったらすぐにエラー処理したい場合

エラーが発生したら例外がthrowされるので、catchして処理してください。

```typescript
try {
	// parametersに検証済みのパラメーターが入っている
	const parameters = vs.applySchemaObject(constraints, input);
}
catch(err) {
	const key = err.keyStack.shift();
	switch(key) { // エラーが発生したプロパティー
	case "foo":
		switch(err.cause) { // エラーの原因
		case vs.CAUSE.TYPE: // 型エラー
			...
		}

	case "bar":
		switch(err.cause) {
		case vs.CAUSE.TYPE: // 型エラー
			...

		case vs.CAUSE.NULL: // nullが渡された
			...
		}
	}
}
```

`err.cause`はエラーが発生した原因（型エラー、nullalbeじゃない場所でnullが渡されたなど）です。
`err.keyStack`はエラーが発生したキーの**配列**です。入力スキーマが「文字列の配列のオブジェクト」という場合にネストしている場合に複数の値が入ります。

```typescript:エラー処理2
import vs from "value-schema";

const input: unknown = {
	foo: {
		values: [1, 2, "a"],
	},
};

// パラメーターに求める制約
const constraints = { // 数値の配列のオブジェクト
	foo: vs.object({
		schemaObject: {
			values: vs.array({
				each: vs.number(),
			}),
		},
	}),
};

try {
	// parametersに検証済みのパラメーターが入っている
	const parameters = vs.applySchemaObject(constraints, input);
}
catch(err) {
	// "a"（"foo"プロパティーのインデックス2）でエラーが発生したので
	// err.keyStackが["foo", 2]となる
});
```

### 全てのエラーをチェックしたい場合

実際のアプリケーションでは、入力エラーが複数あった場合に全てのエラーに対して一度に指摘してあげたほうが親切ですよね。

`applySchemaObject()`の**3番目の引数**に関数を指定すると、エラーが見つかるたびに関数が呼ばれます。この場合、`err`自体の型チェックやプロパティー補完ができます。
3番目の引数を指定した場合は**エラーが見つかっても例外はthrowされません**。

```typescript:エラー処理その1
const parameters = vs.applySchemaObject(constraints, input, (err) => {
	// errの中身は例外バージョンと同じ
	const key = err.keyStack.shift();
	switch(key) {
	case "foo":
		return 0; // ここで返した値がfooエラー時の値になる

	case "bar":
		return 1; // ここで返した値がbarエラー時の値になる
	}
});
```

また、**4番目の引数**に関数を指定すると、1つでもエラーが見つかった場合に**パラメーター検証後に呼ばれます**。これを利用すれば、以下のようにエラー情報をまとめてthrowできます。

```typescript
try {
	// エラー情報の配列
	const errors: string[] = [];

	// parametersに検証済みのパラメーターが入っている
	const parameters = vs.applySchemaObject(constraints, input, (err) => {
		const key = err.keyStack.shift();
		switch(key) { // エラーが発生したプロパティー
		case "foo":
			errors.push("fooがなんかおかしいよ");
			return 0; // とりあえず0を返す

		case "bar":
			switch(err.cause) {
			case vs.CAUSE.NULL: // nullが渡された
				errors.push("barにnullはあかんよ");
				return 0;
			}
			errors.push("barがなんかおかしいよ");
			return 0;
		}
	}, () => {
		// エラーがあれば、検証処理後に呼ばれる
		throw errors;
	});
}
catch(errors) {
	// errorsにはエラー情報の配列が入っている
}
```

## ちゃんとテストしてる？

これが目に入らぬか
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221555/7a6e339f-e2ab-eb34-2d43-aa03dfd205a1.png)

# まとめ

- 入力値のバリデーションは[value-schema](https://www.npmjs.com/package/value-schema)が便利だよ
    - adjuster時代から大幅に進化したよ
- [Deno版](https://deno.land/x/value_schema)もあるよ
    - 名前は"value_schema"（アンダースコア）だから注意してね
- TypeScript補完もバッチリだよ
- めっちゃテストしてるから安心して使っていいよ