エラーと診断

UniKVS のエラーの見分け方と対処の目安を説明します。

基本方針

すべてのエラーは ErrorBase を継承し、日本語と英語のメッセージに対応しています。まず instanceof で種類を判別し、再試行すべきか設定修正すべきか切り分けます。

import { KeyNotFoundError } from "unikvs";

try {
  await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}

クライアント操作のエラー

キーとオープン状態のエラー

エラー	主な発生条件	対処
`KeyNotFoundError`	キーがどのストレージにも存在しません。	キー名と保存済みかを確認します。
`UniKvsIsNotOpenError`	未オープンで操作しました。	`open()` を先に呼びます。
`UniKvsIsOpenError`	オープン済みで再度 `open()` しました。	二重オープンを避けます。
`MissingStorageError`	ストレージ未登録で `create()` しました。	`appendStorage()` を追加します。
`StorageIsNotOpenError`	ストレージが未オープンです。	`open()` の呼び出しを確認します。
`TransformerIsNotOpenError`	トランスフォーマーが未オープンです。	`open()` の呼び出しを確認します。

変換とストリーム対応のエラー

エラー	主な発生条件	対処
`PluginOperationAggregateError`	複数プラグイン操作が失敗しました。	内包された個別エラーを確認します。
`InvalidInputError`	入力形式が不正です。	値の型とキー定義、`schema` の内容を確認します。
`InvalidOutputError`	出力形式が不正です。	変換順序と保存データ、`schema` の内容を確認します。
`ReadableStreamNotSupportedError`	読み取りストリーム未対応です。	ストレージの対応状況を確認します。
`WritableStreamNotSupportedError`	書き込みストリーム未対応です。	ストレージの対応状況を確認します。
`EncodableStreamNotSupportedError`	エンコード用ストリーム未対応です。	トランスフォーマーの対応状況を確認します。
`DecodableStreamNotSupportedError`	デコード用ストリーム未対応です。	トランスフォーマーの対応状況を確認します。

プラグイン固有のエラー

ストレージとユーティリティーのエラー

パッケージ	エラー	主な発生条件
共通（`@unikvs/core`）	`KeyNotFoundError`	存在しないキーを参照しました。各パッケージから再エクスポートされています。
`@unikvs/memory`	`MemoryInvalidChunkTypeError`	バイト列以外のチャンクを扱いました。
`@unikvs/utils`	`InvalidFilenameError`	ファイル名が不正です。
`@unikvs/utils`	`InvalidDirnameError`	ディレクトリ名が不正です。

チェックサムのエラー

パッケージ	エラー	主な発生条件
`@unikvs/checksum`	`ChecksumMismatchError`	ハッシュが一致しません。
`@unikvs/checksum`	`ChecksumRequiredError`	検証用ハッシュが不足しています。
`@unikvs/checksum`	`ChecksumInvalidVarNameError`	変数名の指定が不正です。

集約エラー

複数ストレージへの書き込みで部分失敗すると、集約エラーにまとめます。内包された個別エラーを 1 つずつ確認し、失敗した保存先を特定してください。

国際化

エラーメッセージは日本語と英語に対応しています。自作プラグインでも同じ仕組みを使えます。詳細は @unikvs/core を参照してください。