値のモデル
単一値とストリームの型と Valibot 検証の関係を説明します。
キーごとに扱える値の種類を決めると、使える操作が型レベルで制限されます。実行時の検証を有効にすると、形式の誤りにも早く気づけます。
値の種類
PlainValue と StreamValue は用途が異なり、Value は両方に対応する糖衣構文です。
| 型 | 書き込み | 読み取り | ストリーム読み取り |
|---|---|---|---|
PlainValue<T> |
set(key, T) |
get(key): T |
不可。 |
StreamValue<T> |
set(key, T | ReadableStream<T>) |
不可。 | stream(key): ValueStream<T> |
Value<T> |
set(key, T | ReadableStream<T>) |
get(key): T |
stream(key): ValueStream<T> |
Value は PlainValue | StreamValue と等価です。許可されていない組み合わせは型エラーになります。
スキーマの指定方法
スキーマありの構成では、Valibot スキーマから値の型を推論し、入出力値を実行時に検証します。
- オブジェクト形式は、キー名をそのまま使います。未知のキーは検証を通します。
- 配列形式は、キースキーマと値スキーマの組を並べます。最初に一致した定義を採用し、一致しないキーは
InvalidInputErrorを投げます。
そのため、キー名の誤りに厳しくしたい場合は配列形式を選びます。
検証のタイミング
| 操作 | 検証内容 | 失敗時のエラー |
|---|---|---|
set |
入力値を検証します。 | InvalidInputError |
get |
出力値を検証します。 | InvalidOutputError |
stream |
チャンクを 1 つずつ検証します。 | InvalidOutputError |
ストリームの検証はチャンク単位で遅延して行います。書き込み時は書き込み処理の中で検証し、読み取り時は消費するたびに検証します。
ストリームの扱い
stream() の戻り値は ValueStream です。ReadableStream のラッパーで、for await...of と await using による自動破棄に対応します。
ストリームのチャンク型は保存先によって異なります。たとえばメモリーでは Uint8Array のみに対応し、文字列専用の保存先ではストリーム自体に対応しません。利用前に各パッケージのデータ型を確認してください。
手順はストリームを使うを参照してください。
エラーとの関係
形式の誤りは種類に応じて別のエラーになります。入力の不備は呼び出し側で直せるため InvalidInputError、保存データや変換結果の不備は出力側の問題として InvalidOutputError を使います。対処の手順はエラーを処理するを参照してください。