@unikvs/s3.node

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

概要

@unikvs/s3.node は、S3 互換オブジェクトストレージにバイト配列を保存する Node.js 専用プラグインです。Node.js 専用

インストールは次のように行います。

npm install @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

pnpm add @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

yarn add @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

bun add @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

nub add @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

aube add @unikvs/s3.node @aws-sdk/client-s3 @aws-sdk/lib-storage

使い方

ストレージクラスは S3 です。

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

new S3(bucket: string, config: S3ClientConfig = {}, options: S3StorageOptions = {})

構築済みの S3Client を渡す引数や、プレフィックス指定はありません。キー変換や使い分けが必要なら、キーに含めるかバケットごとにインスタンスを作ってください。

ライフサイクルは次のとおりです。生成直後は isOpen が false で、open() すると true になります。close() で破棄して false に戻ります。

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

const storage = new S3("my-bucket", {
  region: "ap-northeast-1",
});

const kvs = UniKvs.config()
  .appendStorage(storage)
  .create();

オブジェクト配置

キーはオブジェクトキーにそのまま対応します。

clear はバケット内のすべてのオブジェクトを削除します。プレフィックスで絞り込みません。UniKVS 専用のバケットを使ってください。共有していると他のデータも消えます。

ストリームとマルチパート

大容量データは単発の write ではなく書き込みストリームを使ってください。マルチパートアップロードに対応します。

const writable = storage.getWritable({ key, vars, signal });

パートサイズは vars で指定します。バイト単位の正の整数で指定し、未指定なら既定値に従います。

signal が中断済みなら開始せずに StorageAbortedError を投げます。

読み取りストリームは次のように取得します。

const readable = await storage.getReadable({ key, signal });

大きなオブジェクトも複数チャンクで読み取れます。

エラー

• 存在しないキーの read はエラーで失敗します。必要なら事前に exists を使います。
• 存在しないキーの delete はエラーになりません。

使用例

S3 互換ストレージへの最小構成例です。エンドポイントや認証情報はダミー値で、MinIO などへの接続を想定しています。バケットは事前に作っておきます。

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

const storage = new S3("my-bucket", {
  endpoint: "http://127.0.0.1:9000",
  region: "ap-northeast-1",
  credentials: {
    accessKeyId: "minioadmin",
    secretAccessKey: "minioadmin",
  },
  forcePathStyle: true,
});

storage.open();

const signal = AbortSignal.timeout(30_000);
const key = "hello.txt";
const data = new TextEncoder().encode("Hello S3");

await storage.write({ key, data, signal });
const loaded = await storage.read({ key, signal });
console.log(new TextDecoder().decode(loaded));

storage.close();