OSS探訪GitHubでログイン

小さなstructを組み合わせ、JavaScriptやTypeScriptの入力値を実行時に検証する

スコアの見方

OSS規模スコアはStars・Watchers・Forks・Contributorsを対数圧縮して重み付けした現在の規模指標(上限なし)です。発掘スコアは現在のOSS規模スコアから発掘時点のOSS規模スコアを引いた値、更新ペースは直近30日Commit数、成長モメンタムは直近の観測期間におけるOSS規模スコア差、OSS健全度は取得できた更新状況・Community Health・Releaseの0〜100評価です。

Stars
7,127
主要言語
TypeScript
ライセンス
MIT
リポジトリ最終更新
2024/10/01
ページ内ナビ

概要

Superstructは、object・array・string・numberなどのstructを組み合わせて入力値を検証するlibraryです。assert、is、validateで検証でき、custom typeやcoercionも追加できます。TypeScriptでは検証後の値を安全な型へ絞り込めます。

特徴と向いている用途

公式資料に基づく紹介・実機未検証 · 内容確認日:

主な特徴

objectやarrayなどのstructを組み合わせてschemaを作る

object、array、string、numberなどを組み合わせ、RESTやGraphQLで受け取るobjectの形をruntimeで検証できます。共通structを部品として再利用し、より大きなschemaへ組み込めます。

出典:[1]

assert・is・validateでerror handlingを選ぶ

assertは不正な値でerrorを投げ、isはbooleanで判定しながらTypeScript type guardとして働きます。validateを使えばthrowせずにvalidation resultを扱う構成も選べます。

出典:[1]

custom typeとcoercionでapplication固有の入力処理へ拡張する

defineでemailやUUIDなどのcustom validatorを追加でき、createやdefaultedを使うと検証前にdefault値の補完やcoercionを適用できます。

出典:[1]

向いている用途

frontendやAPIで小さくcomposableなruntime validationを使いたい場合に向く

JSON Schemaのような外部schema規格を前提にせず、application code内でJavaScript/TypeScriptに近い記法で入力検証を組み立てたいprojectに適します。

出典:[1]

導入前の確認

coercionを使うと検証前後で値が変わる

createやcoercion系APIはdefaultの追加や値の変換を行います。入力を変更せず検証だけしたい境界では、assert・is・validateとの役割を混ぜないようにしてください。

出典:[1]

2.0.2のrelease tagとpackage manifestには上流のversion差がある

GitHubのlatest releaseはv2.0.2ですが、そのtag内package.jsonは2.0.1のままです。現在のmain manifestは2.0.2を示しています。導入時はnpmの2.0.2 packageを基準にし、tag内manifestだけでversionを判定しない方が安全です。

出典:[2][3][4]

参考にした公式資料

  1. [1]Superstruct v2.0.2 README(2026-10-05)
  2. [2]Superstruct v2.0.2 release(2026-10-05)
  3. [3]Superstruct package metadata at v2.0.2 tag(2026-10-05)
  4. [4]Superstruct package metadata at reviewed main commit(2026-10-05)
  5. [5]Superstruct MIT license(2026-10-05)
編集部からの補足

validationだけならassert・is・validateを使い、default値の補完やcoercionが必要な場合はcreateを使います。入力値の変換を伴う処理と純粋な検証を分けておくと、API境界の挙動を追いやすくなります。

3ステップで試す

  1. 1

    Superstruct 2.0.2を一時projectへ導入する

    GitHub latest releaseに対応する2.0.2 packageを固定して導入します。

    demo=$(mktemp -d "${TMPDIR:-/tmp}/superstruct.XXXXXX") && cd "$demo" && npm init -y >/dev/null && npm install --save-exact superstruct@2.0.2
  2. 2

    object structで正しい値と不正な値を判定するscriptを作る

    READMEのobjectとisを使い、validな値でtrue、不正な型でfalseになることを確認します。

    printf "%s\n" "import {is, object, number, string} from 'superstruct';" "const User = object({id: number(), name: string()});" "if (!is({id: 1, name: 'Ada'}, User)) process.exit(1);" "if (is({id: '1', name: 'Ada'}, User)) process.exit(1);" "console.log('validated');" > demo.mjs
  3. 3

    Node.jsでvalidationを実行する

    throwを使わないisのvalidation flowが期待どおり動くことを確認します。

    node demo.mjs
公式READMEで確認

成長

成長の推移 · 直近30日

7,127 Stars

推移データを蓄積中です。

開発アクティビティ

直近90日・週次

Commit(直近30日)
0
Open PR
22

開発アクティビティを蓄積中です。

Built with

カテゴリとタグ

GitHubデータ

GitHubのデータGitHubの詳細データを見る

GitHub Topics

  • validation
  • types
  • interface
  • structs
  • schema
  • javascript
  • typescript
Stars
7,127
Forks
223
Watchers
43
Open Issues
82
Contributors
66
所有者種別
User
主要言語
TypeScript
ライセンス
MIT
リポジトリ最終更新
2024/10/01

このOSSの使い方や活用事例をMarkdownで投稿できます。管理者が承認した後に公開されます。

情報の誤りを報告

掲載内容に誤りや古い情報があればお知らせください。

このページを読んで、次に何をすればよいか分かりましたか?