エラーのフォーマット (Formatting errors)

Zod は、エラー報告において 完全性 と 正確性 を重視しています。多くの場合、$ZodError をより有用な形式に変換すると便利です。Zod はこのためにいくつかのユーティリティを提供しています。

この単純なオブジェクトスキーマを考えてみましょう。

import * as z from "zod";
 
const schema = z.strictObject({
  username: z.string(),
  favoriteNumbers: z.array(z.number()),
});

この無効なデータを解析しようとすると、3つの issue を含むエラーが発生します。

const result = schema.safeParse({
  username: 1234,
  favoriteNumbers: [1234, "4567"],
  extraKey: 1234,
});
 
result.error!.issues;
[
  {
    expected: 'string',
    code: 'invalid_type',
    path: [ 'username' ],
    message: 'Invalid input: expected string, received number'
  },
  {
    expected: 'number',
    code: 'invalid_type',
    path: [ 'favoriteNumbers', 1 ],
    message: 'Invalid input: expected number, received string'
  },
  {
    code: 'unrecognized_keys',
    keys: [ 'extraKey' ],
    path: [],
    message: 'Unrecognized key: "extraKey"'
  }
];

`z.treeifyError()`

このエラーをネストされたオブジェクトに変換（"treeify"）するには、z.treeifyError() を使用します。

const tree = z.treeifyError(result.error);
 
// =>
{
  errors: [ 'Unrecognized key: "extraKey"' ],
  properties: {
    username: { errors: [ 'Invalid input: expected string, received number' ] },
    favoriteNumbers: {
      errors: [],
      items: [
        undefined,
        {
          errors: [ 'Invalid input: expected number, received string' ]
        }
      ]
    }
  }
}

結果は、スキーマ自体を反映したネストされた構造になります。特定のパスで発生したエラーに簡単にアクセスできます。errors フィールドには指定されたパスでのエラーメッセージが含まれ、特別なプロパティ properties と items を使用してツリーの奥深くをトラバースできます。

tree.properties?.username?.errors;
// => ["Invalid input: expected string, received number"]
 
tree.properties?.favoriteNumbers?.items?.[1]?.errors;
// => ["Invalid input: expected number, received string"];

ネストされたプロパティにアクセスするときのエラーを回避するために、オプショナルチェーン (?.) を使用してください。

`z.prettifyError()`

z.prettifyError() は、エラーの人間が読める文字列表現を提供します。

const pretty = z.prettifyError(result.error);

これは次の文字列を返します：

✖ Unrecognized key: "extraKey"
✖ Invalid input: expected string, received number
  → at username
✖ Invalid input: expected number, received string
  → at favoriteNumbers[1]

`z.formatError()`

これは z.treeifyError() のために非推奨になりました。

`z.flattenError()`

z.treeifyError() は潜在的に複雑なネストされた構造をトラバースするのに便利ですが、大多数のスキーマは フラット （わずか1レベルの深さ）です。この場合、z.flattenError() を使用して、クリーンで浅いエラーオブジェクトを取得します。

const flattened = z.flattenError(result.error);
// { errors: string[], properties: { [key: string]: string[] } }
 
{
  formErrors: [ 'Unrecognized key: "extraKey"' ],
  fieldErrors: {
    username: [ 'Invalid input: expected string, received number' ],
    favoriteNumbers: [ 'Invalid input: expected number, received string' ]
  }
}

formErrors 配列には、トップレベルのエラー（path が [] の場合）が含まれます。fieldErrors オブジェクトは、スキーマの各フィールドのエラー配列を提供します。

flattened.fieldErrors.username; // => [ 'Invalid input: expected string, received number' ]
flattened.fieldErrors.favoriteNumbers; // => [ 'Invalid input: expected number, received string' ]

エラーのフォーマット (Formatting errors)

z.treeifyError()

z.prettifyError()

z.formatError()

ドキュメントを表示

z.flattenError()

On this page

`z.treeifyError()`

`z.prettifyError()`

`z.formatError()`

`z.flattenError()`