---
title: "@unikvs/session-storage"
description: "@unikvs/session-storage の SessionStorage。sessionStorage に文字列を保存するストレージの使い方を説明します。"
---

## 概要 [#overview]

`@unikvs/session-storage` ブラウザー専用 は `sessionStorage` に文字列を保存するストレージです。タブを開いている間だけ残したい一時的な値の保存に使います。

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

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

```package-install
npm install @unikvs/session-storage
```

## 使い方 [#usage]

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

```ts
import { SessionStorage } from "@unikvs/session-storage";
```

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `keyPrefix?` | `[#key-prefix] string \| undefined` | `"unikvs:"` | すべてのキーに付ける接頭辞です。 |
| `allowClearWithoutPrefix?` | `[#allow-clear-without-prefix] boolean \| undefined` | `false` | 空の接頭辞での clear を許可するかどうかです。 |
| `storage?` | `[#storage] Storage \| undefined` | - | 使う Storage です。省略した場合は globalThis.sessionStorage を使います。 |

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

```ts
import { SessionStorage } from "@unikvs/session-storage";
import * as unikvs from "unikvs";

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

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

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

await kvs.close();
```

## データ型 [#data-types]

| 操作            | 対応するデータ型 |
| --------------- | ---------------- |
| `write`・`read` | 文字列           |

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

## エラー [#errors]

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

### KeyNotFoundError [#key-not-found-error]

#### 意味

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

#### 対処方法

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

#### 例

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

```ts
import { KeyNotFoundError } from "@unikvs/session-storage";

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

### ClearWithoutPrefixNotAllowedError [#clear-without-prefix-not-allowed-error]

#### 意味

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

#### 対処方法

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

### SessionStorageNotAvailableError [#session-storage-not-available-error]

#### 意味

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

#### 対処方法

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