ページ内ナビ
概要
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]
参考にした公式資料
- [1]Superstruct v2.0.2 README(2026-10-05)
- [2]Superstruct v2.0.2 release(2026-10-05)
- [3]Superstruct package metadata at v2.0.2 tag(2026-10-05)
- [4]Superstruct package metadata at reviewed main commit(2026-10-05)
- [5]Superstruct MIT license(2026-10-05)
編集部からの補足
validationだけならassert・is・validateを使い、default値の補完やcoercionが必要な場合はcreateを使います。入力値の変換を伴う処理と純粋な検証を分けておくと、API境界の挙動を追いやすくなります。
3ステップで試す
- 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
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
Node.jsでvalidationを実行する
throwを使わない
isのvalidation flowが期待どおり動くことを確認します。node demo.mjs
成長
成長の推移 · 直近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で投稿できます。管理者が承認した後に公開されます。
あわせて探訪
- ofetch5,360 Stars
共通タグ 5件 · 共通カテゴリ 1件 · 同じ言語
Node・browser・workerで同じAPIを使い、fetchへJSON解析・retry・timeout・interceptorを加える
TypeScript - Ajv14,850 Stars
共通タグ 4件 · 共通カテゴリ 2件 · 同じ言語
JSON SchemaやJTDをcompileし、API入力や設定値を高速に実行時検証する
TypeScript - openapi-typescript8,391 Stars
共通タグ 4件 · 共通カテゴリ 2件 · 同じ言語
OpenAPI 3.0/3.1の定義から実行時コードを増やさずTypeScript型を生成する
TypeScript - Typia5,931 Stars
共通タグ 4件 · 共通カテゴリ 2件 · 同じ言語
TypeScript型をcompile時に専用validatorへ変換し、runtime validationやserializerを生成する
TypeScript - Valibot9,027 Stars
共通タグ 4件 · 共通カテゴリ 1件 · 同じ言語
小さな関数を組み合わせ、TypeScript型推論と実行時のスキーマ検証を両立する
TypeScript - SWR32,487 Stars
共通タグ 3件 · 共通カテゴリ 2件 · 同じ言語
Reactのリモートデータ取得をキャッシュし、再検証と重複排除までHookで管理する
TypeScript
情報の誤りを報告
掲載内容に誤りや古い情報があればお知らせください。