@unikvs/localstorage

@unikvs/localstorage の LocalStorage。localStorage に文字列を保存するストレージの使い方を説明します。

概要

@unikvs/localstorage ブラウザー専用 は localStorage に文字列を保存するストレージです。タブを閉じても残したい小さな設定値などの保存に使います。

• name は LocalStorage です。
• isOpen は常に true です。open は利用可否を確認し、close は何も行いません。
• 論理キーには keyPrefix を付けて保存します。

インストールは次のコマンドで行います。

npm install @unikvs/localstorage

pnpm add @unikvs/localstorage

yarn add @unikvs/localstorage

bun add @unikvs/localstorage

nub add @unikvs/localstorage

aube add @unikvs/localstorage

使い方

LocalStorage は IStorage を実装しています。UniKvs には persist() で渡します。

import { LocalStorage } from "@unikvs/localstorage";

コンストラクターの引数は次のとおりです。

以下は、文字列を保存して読み戻す例です。

import { LocalStorage } from "@unikvs/localstorage";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  greeting: unikvs.PlainValue<string>;
}>()
  .persist(new LocalStorage())
  .build();

await kvs.open();
await kvs.set("greeting", "hello");

const value = await kvs.get("greeting");
console.log(value); // "hello"

await kvs.close();

データ型

• 文字列のみを保存します。
• オブジェクトなどを保存する場合は、文字列に変換してから渡してください。
• ストリーム（getWritable・getReadable）には対応していません。

エラー

このパッケージが投げるエラーは次のとおりです。

KeyNotFoundError

意味

指定したキーが存在しない場合に投げます。@unikvs/core の共通エラーです。

対処方法

exists で確認してから読み出してください。

例

以下は、KeyNotFoundError を捕捉する例です。

import { KeyNotFoundError } from "@unikvs/localstorage";

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

ClearWithoutPrefixNotAllowedError

意味

keyPrefix が空で allowClearWithoutPrefix が false のまま clear を呼んだ場合に投げます。この制限は localStorage 全体の削除を防ぎます。

対処方法

空でない keyPrefix を設定するか、allowClearWithoutPrefix: true を指定してください。

LocalStorageNotAvailableError

意味

localStorage が使えない環境で操作した場合に投げます。注入された storage がなく、実行環境にも localStorage がありません。

対処方法

options.storage に Storage を注入するか、対応するブラウザーで使ってください。