@unikvs/s3.node

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

概要

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

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

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

npm install @unikvs/s3.node

pnpm add @unikvs/s3.node

yarn add @unikvs/s3.node

bun add @unikvs/s3.node

nub add @unikvs/s3.node

aube add @unikvs/s3.node

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

使い方

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

import { S3 } from "@unikvs/s3.node";

S3

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

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

S3StorageOptions

将来の拡張用のオプション型です。現在は空のオブジェクトで、指定できる項目はありません。

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

import { S3 } from "@unikvs/s3.node";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new S3("my-bucket", { region: "us-east-1" }))
  .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();

データ型

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

エラー

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

InvalidPartSizeError

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

意味

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

対処方法

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

StorageAbortedError

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

意味

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

対処方法

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

AggregateError

一括削除 (clear()) でオブジェクト単位の削除に失敗したときに投げるエラーです。

意味

DeleteObjects は削除に失敗したオブジェクトがあっても HTTP 200 を返し、失敗したキーを応答の Errors に格納します。clear() はこの失敗を成功として扱わず、失敗したオブジェクトごとの Error を AggregateError の errors にまとめて投げます。

対処方法

AggregateError の errors を確認し、失敗したキーごとの原因 (アクセス権限やオブジェクトの状態など) を取り除いてから clear() を再実行してください。