---
title: "@unikvs/s3.bun"
description: "S3 互換のオブジェクトストレージにバイト列を保存する @unikvs/s3.bun の使い方を説明します。"
---

## 概要 [#overview]

`@unikvs/s3.bun` は S3 互換のオブジェクトストレージにバイト列を保存するストレージプラグインです。Bun 専用 クラウドや S3 互換ストレージへの永続化に使います。

- `name` は `"S3"` で、`isOpen` で開閉状態を確認します。
- `open()` でクライアントを作成し、`close()` で参照を外します。
- このストレージは、コンストラクターで指定したバケットに対してすべての操作を行い、キーをオブジェクトキーとしてそのまま使います。

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

```package-install
npm install @unikvs/s3.bun
```

別途 S3 互換のオブジェクトストレージが必要です。

## 使い方 [#usage]

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

```ts
import { S3 } from "@unikvs/s3.bun";
```

### S3 [#s3]

S3 互換ストレージに保存するストレージです。利用者は `open()` で開き、使い終わったら `close()` で閉じます。

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `bucket` | `[#s3-bucket] string` | - | データを保存するバケット名です。 |
| `options?` | `[#s3-options] S3StorageOptions` | - | Bun の `S3Client` に渡す設定です。エンドポイントや認証情報などを指定します。 |

### S3StorageOptions [#s3storageoptions]

Bun の `S3Options` から `bucket` を除いた設定型です。バケット名はコンストラクターの第 1 引数で指定します。

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

```ts
import { S3 } from "@unikvs/s3.bun";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new S3("my-bucket"))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();
```

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

| 操作                                    | 対応するデータ型          |
| --------------------------------------- | ------------------------- |
| `write`・`read`                         | `Uint8Array<ArrayBuffer>` |
| `getWritable`・`getReadable` のチャンク | `Uint8Array<ArrayBuffer>` |

- `write`・`read` にはバイト列 (`Uint8Array<ArrayBuffer>`) を使います。
- ストリームの読み書きに対応し、チャンクは `Uint8Array<ArrayBuffer>` です。
- 書き込みストリームのパートサイズは実行時変数の `@unikvs/s3.bun:partSize` (なければ `@unikvs/s3:partSize`) で変えられます。
- `clear()` はバケット内のオブジェクトを列挙してすべて削除します。

## エラー [#errors]

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

### StorageNotOpenError [#error-storage-not-open]

未オープンで `close()` したときに投げます。

#### 意味

S3 クライアントがオープンされていないのに `close()` を呼び出しました。

#### 対処方法

`close()` の前に `open()` を呼び出してください。

### InvalidPartSizeError [#error-invalid-part-size]

`@unikvs/core` の共通エラーです。書き込みストリームのパートサイズが非整数または非正数のときに投げます。

| Prop | Type | Default | Description |
| - | - | - | - |
| `actual` | `[#invalid-part-size-actual] unknown` | - | 指定されたパートサイズの値です。 |

#### 意味

実行時変数のパートサイズ (`@unikvs/s3.bun:partSize` または `@unikvs/s3:partSize`) が正の整数ではありません。`@unikvs/core` の共通エラーです。

#### 対処方法

パートサイズに正の整数 (バイト単位) を指定してください。

### StorageAbortedError [#error-storage-aborted]

`@unikvs/core` の共通エラーです。書き込みストリームの取得前にシグナルが中断済みのときに投げます。

| Prop | Type | Default | Description |
| - | - | - | - |
| `key` | `[#storage-aborted-key] string` | - | アップロードしようとしたキーです。 |

#### 意味

`getWritable()` の呼び出し時点で `AbortSignal` が既に中断されています。`@unikvs/core` の共通エラーです。

#### 対処方法

中断されていないシグナルを渡すか、要求前にシグナルの状態を確認してください。

### UnsupportedRuntimeError [#error-unsupported-runtime]

`@unikvs/core` の共通エラーです。Bun 以外のランタイムで開こうとしたときに投げます。

#### 意味

このストレージは Bun でのみ動作します。`@unikvs/core` の共通エラーです。

#### 対処方法

Bun ランタイムで実行してください。