コンテンツにスキップ
Omnio-js
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

エラーと中断を扱う

Omnio が投げる例外を分類し、AbortSignal で操作を安全に中断します。

入力の検証エラー

公開メソッドの入力は valibot で検証されます。不正な値には ValiError が投げられます。

import * as v from "valibot";

try {
  await omnio.putObject({
    key: "notes/a.txt",
    data: bytes,
    contentType: "text/plain",
    tags: new Array(11).fill("tag"),
  });
} catch (error) {
  if (error instanceof v.ValiError) {
    console.error(error.issues);
  }
}

タグは最大 10 個、各タグは最大 128 文字かつ 128 バイトです。キーは最大 1024 文字かつ 1024 バイトです。

よくある例外

エラー 発生する状況
ValiError 入力がスキーマに合わない。
InvalidOmnioKeyError キーが空、長すぎる、または不正な UTF-8 である。
DbNotOpenError open() の前に操作した、または close() 後に操作した。
OperationAbortedError close() によって実行中の操作が中断された。
EntityMissingError インデックスにレコードがあるが、オブジェクトのバイト列が見つからない。
ChecksumMismatchError 取得したバイト列の SHA-256 がインデックスのハッシュと一致しない。
DbQueryError インデックスのデータベース操作に失敗した。
ModelLoadError 埋め込みモデルの読み込みに失敗した。
EmbedFailedError テキストまたは画像の埋め込みに失敗した。
UnsupportedModalityError 埋め込み器が対応しないモダリティーを要求した。

error.name は OmnioInvalidKeyError や OmnioDbNotOpenError という固有の名前です。クラスで判定できるときは instanceof を使ってください。

中断シグナルを渡す

各メソッドには、最後の引数か入力オブジェクトの signal で AbortSignal を渡せます。

const controller = new AbortController();

const pending = omnio.searchObjects({
  query: { text: "海辺" },
  signal: controller.signal,
});

controller.abort();

try {
  await pending;
} catch (error) {
  if (controller.signal.aborted) {
    console.log("検索を中断しました", controller.signal.reason);
  }
}

時間制限を設けたいときは AbortSignal.timeout() を使えます。

await omnio.putObject({
  key: "large/file.bin",
  data: stream,
  contentType: "application/octet-stream",
  signal: AbortSignal.timeout(30_000),
});

close による中断

close() は、実行中の操作に渡されたシグナルとライフサイクルシグナルをまとめたシグナルで中断します。中断された操作は OperationAbortedError で失敗します。

const operation = omnio.getObject("notes/a.txt");

await omnio.close();

await operation.catch((error) => {
  if (error instanceof OperationAbortedError) {
    // close による中断です。
  }
});

open() と close() は、シグナルを省略すると 30 秒でタイムアウトします。時間がかかりそうなときは、明示的なシグナルを渡してください。

再試行する

一時的なデータベース障害は DbQueryError として現れます。再試行する前に、操作が冪等かどうかを確認してください。

  • getObject、headObject、hasObject、listObjects、searchObjects は読み取りなので、再試行しやすい操作です。
  • putObject、copyObject、renameObject、deleteObject は再試行すると新しいバイト列や削除予約が増えることがあります。
  • updateObjectMetadata は同じ内容であれば再試行しても結果は変わりません。

エラーメッセージを翻訳する

@omniojs/core は setErrorMessage を公開しています。アプリケーションの言語に合わせてメッセージを差し替えられます。

import { DbNotOpenError, setErrorMessage } from "@omniojs/core";

setErrorMessage(DbNotOpenError, () => "データベースが開かれていません", "ja");

次に読む

このページは役に立ちましたか?