使用法 - ファイバー上の JavaScript

JavaScript でデータを検証するためのシンプルで構成可能な方法
。

Superstruct を使用すると、インターフェイスの定義と、それらに対する JavaScript データの検証が簡単になります。その型アノテーション API は、Typescript、Flow、Go、およびGraphQLからインスピレーションを得たもので、使い慣れた理解しやすい API です。

ただし、Superstruct は実行時にデータを検証するように設計されているため、ユーザーまたはエンドユーザーに対して詳細な実行時エラーをスロー (または返し) します。これは、REST または GraphQL API で任意の入力を受け入れるような状況で特に役立ちます。必要に応じて実行時に内部データ構造を検証します。

Usage

Superstruct は、struct特定のスキーマに対してデータを検証できる構造体を作成するためのファクトリをエクスポートします。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { struct } from 'superstruct'

const Article = struct({
  id: 'number',
  title: 'string',
  is_published: 'boolean?',
  tags: ['string'],
  author: {
    id: 'number',
  },
})

const data = {
  id: 34,
  title: 'Hello World',
  tags: ['news', 'features'],
  author: {
    id: 1,
  },
}

const article = Article(data)

// This will throw when the data is invalid, and return the data otherwise.
// If you'd rather not throw, use `Struct.validate()` or `Struct.test()`.

そのまま使用できるすべてのネイティブ JavaScript 型を認識しますが、エクスポートを使用して、アプリケーションの要件に固有の独自のカスタムデータ型を定義することもできますsuperstruct。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { superstruct } from 'superstruct'
import isUuid from 'is-uuid'
import isEmail from 'is-email'

const struct = superstruct({
  types: {
    uuid: value => isUuid.v4(value),
    email: value => isEmail(value) && value.length < 256,
  },
})

const User = struct({
  id: 'uuid',
  email: 'email',
  is_admin: 'boolean?',
})

const data = {
  id: 'c8d63140-a1f7-45e0-bfc6-df72973fea86',
  email: 'jane@example.com',
}

const user = User(data)

Superstruct は、リストまたはスカラー構造体の定義、デフォルト値の適用、内部構造体の相互構成、エラーをスローする代わりにエラーを返すなど、より複雑な使用例もサポートしています。詳細については、完全なドキュメントを参照してください。

Why?

既存の検証ライブラリはたくさんありますjoi— express-validator、、、、、、...しかし、それらはコードベースの保守を困難にする多くの問題を引き起こします...validator.jsyupajvis-my-json-valid

多くのバリデーターは、理由の詳細を示さずに単に文字列のみのエラーまたはブール値を返すだけなので、エンドユーザーに役立つようにエラーをカスタマイズすることが困難になります。
多くのバリデーターには、電子メール、URL、UUID などの組み込み型が同梱されていますが、何をチェックするのか知る方法がなく、新しい型を定義するための複雑な API も含まれています。
既存の API の多くは、カスタムデータ型を何度も再定義することを奨励しており、信頼できる情報源はコードベース全体に分散されています。
コールバックはエラーをスローしません。多くは実際にはエラーをスローしないため、どこでもラップする必要があります。コールバックの時代には便利ですが、throw最新の JavaScript で使用しないとコードがはるかに複雑になります。
多くのバリデーターはスキーマをプレーンな JavaScript オブジェクトとして定義するため、スキーマロジックの解析を検証時間に委任するため、処理が大幅に遅くなります。
多くのバリデーターはExpress または他のフレームワークと密接に結合しているため、コードベース全体で再利用できない、1 回限りのわかりにくいコードが生成されます。
彼らは JSON スキーマを使用します。誤解しないでください。JSON スキーマは便利な場合もあります。しかし、これは HATEOAS のようなものです。通常、必要以上に複雑で、その利点をまったく活用できません。(申し訳ありませんが、私が言いました) 。）

もちろん、すべての検証ライブラリがこれらすべての問題に悩まされているわけではありませんが、ほとんどの検証ライブラリでは少なくとも 1 つは発生します。

そこで、Superstruct がこれらの問題をどのように解決するのかを説明します...

Principles

カスタマイズ可能なタイプ: Superstruct の機能は、アプリケーションに固有のカスタムデータタイプのセット全体を簡単に定義できることにあり、単一の場所で定義できるため、要件を完全に制御できます。
意見のないデフォルト: Superstruct にはネイティブ JavaScript タイプが同梱されており、その他すべてがカスタマイズ可能であるため、アプリケーションのニーズとは異なる「コア」によって行われた決定をオーバーライドするために苦労する必要はありません。
構成可能なインターフェイス: Superstruct インターフェイスは構成可能なため、頻繁に繰り返されるデータをコンポーネントに分解し、それらを構成してより複雑なオブジェクトを構築できます。
簡潔なスキーマ: Superstruct のスキーマは、非常に簡潔かつ表現力豊かになるように設計されているため、読み取りと書き込みが非常に簡単になり、データ検証を完全にカバーできるようになります。
コンパイルされたバリデータ: Superstruct は、ホットコードパス内の検証関数の呼び出しごとに高価なタスクの実行に時間を費やさないように、スキーマを事前にコンパイルする作業を実行します。
有用なエラー: Superstruct がスローするエラーには、独自のアプリケーション固有のエラーに簡単に変換するために必要な情報がすべて含まれており、エンドユーザーにとってより役立つエラーになります。
使い慣れた API。Superstruct API は、Typescript、Flow、Go、およびGraphQLに大きく影響を受けました。これらのいずれかに精通していれば、そのスキーマ定義 API は非常に自然に使用できるため、すぐに使い始めることができます。

Demo

JSFiddle のライブデモを試して、API がどのように機能するかを理解するか、ユースケースを簡単に検証してください。

Examples

Superstruct の API は非常に柔軟であり、サーバーやブラウザーでさまざまなユースケースに使用できます。一般的なパターンの例をいくつか示します...

Documentation

入門ガイドを読んで、Superstruct がどのように機能するかを理解してください。その後、完全な API リファレンスを参照して、構造体、型、エラーに関する詳細情報を確認してください...

License

このパッケージはMIT-licensed。

開発ガイド

基本モジュール

組み込みオブジェクト

コミュニティモジュール