---
title: "値のモデル"
description: "単一値とストリームの型と Valibot 検証の関係を説明します。"
---

キーごとに扱える値の種類を決めると、使える操作が型レベルで制限されます。実行時の検証を有効にすると、形式の誤りにも早く気づけます。

## 値の種類 [#value-kinds]

`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` と等価です。許可されていない組み合わせは型エラーになります。

## スキーマの指定方法 [#schema-forms]

スキーマありの構成では、Valibot スキーマから値の型を推論し、入出力値を実行時に検証します。

- オブジェクト形式は、キー名をそのまま使います。未知のキーは検証を通します。
- 配列形式は、キースキーマと値スキーマの組を並べます。最初に一致した定義を採用し、一致しないキーは `InvalidInputError` を投げます。

そのため、キー名の誤りに厳しくしたい場合は配列形式を選びます。

## 検証のタイミング [#validation-timing]

| 操作     | 検証内容                        | 失敗時のエラー       |
| -------- | ------------------------------- | -------------------- |
| `set`    | 入力値を検証します。            | `InvalidInputError`  |
| `get`    | 出力値を検証します。            | `InvalidOutputError` |
| `stream` | チャンクを 1 つずつ検証します。 | `InvalidOutputError` |

ストリームの検証はチャンク単位で遅延して行います。書き込み時は書き込み処理の中で検証し、読み取り時は消費するたびに検証します。

## ストリームの扱い [#streams]

`stream()` の戻り値は `ValueStream` です。`ReadableStream` のラッパーで、`for await...of` と `await using` による自動破棄に対応します。

ストリームのチャンク型は保存先によって異なります。たとえばメモリーでは `Uint8Array` のみに対応し、文字列専用の保存先ではストリーム自体に対応しません。利用前に各パッケージのデータ型を確認してください。

手順は[ストリームを使う](/unikvs/how-to/streams)を参照してください。

## エラーとの関係 [#errors]

形式の誤りは種類に応じて別のエラーになります。入力の不備は呼び出し側で直せるため `InvalidInputError`、保存データや変換結果の不備は出力側の問題として `InvalidOutputError` を使います。対処の手順は[エラーを処理する](/unikvs/how-to/handle-errors)を参照してください。