universal-storage

@alneas/universal-storage (日本語)

ブラウザ・エッジ・Cloudflare Workers・Deno・Bun・Node.js 対応のゼロ依存 Web 標準ストレージレイヤー

@alneas/universal-storage は、Amazon S3、Cloudflare R2、Oracle Cloud（OCI）Object Storage、ローカルファイルシステムを統一的に扱うためのクロスプラットフォーム・ストレージ抽象化ライブラリです。

ネイティブバインディングなし、node:crypto 依存なし、@aws-sdk/client-s3 の事前インストール不要 で動作します。標準の fetch、ReadableStream、Uint8Array、Web 標準暗号アルゴリズム（純粋 TypeScript 実装）を用いて、ブラウザやエッジ環境でもそのまま動作します。

主な特徴

完全ゼロ依存（0 dependencies）: @aws-sdk 等の巨大な依存関係がなく、極めて軽量。
ユニバーサル実行環境: Cloudflare Workers、Vercel Edge、Deno、Bun、Node.js (>=24)、モダンブラウザでシームレスに動作。
Amazon S3 & Cloudflare R2: SigV4 署名および署名付き URL（Presigned URL）生成を内蔵。
Oracle Cloud (OCI): ネームスペースやコンパートメントに対応した OCI Object Storage アダプター。
データ完全性: SHA-256計算とS3 Object Lockの通信に対応。
ディレクトリトラバーサル防止: 安全にサンドボックス化されたローカルストレージアダプター。
対称的な非 ASCII メタデータ処理: 日本語などの UTF-8 メタデータをヘッダー制限に抵触せず可逆的に保管。

インストール

# npm
npm install @alneas/universal-storage

# bun
bun add @alneas/universal-storage

ライセンス

MIT © ALNEAS / DataArtHub

正本と公開手順

Publicモノレポのこのパッケージが正本です。テストは CONTRIBUTING.md、npm公開と初回の依存解決は RELEASING.md を参照してください。privateからのソース同期は行いません。

実行環境・保存の仕様

ブラウザ・Workerでは@alneas/universal-storage/portableを使います。Node builtinやpolyfillは不要です。browser/default条件のrootも同じportable入口です。LocalStorageAdapterは/serverを使い、Node条件のrootは既存exportを維持します。Nodeのrootファイルをブラウザへ直接配信しないでください。SHA-256/HMACとZIP補助処理はportableです。

S3/R2/OCIは常にfetch/SigV4経路を使い、AWS SDK導入で動作が切り替わりません。日本語・制御文字・文字列先頭のb64:は保存時に符号化し、取得時に1回だけ復号します。旧版で符号化せず保存したb64:文字列は区別不能なので、正しい元値から移行してください。copyは保存済みmetadataを保持します。CopyObjectは本文のError・不正応答を拒否し、宛先HEAD成功後にmoveの元キーを削除します。元削除失敗は例外になり、復旧用に宛先が残る場合があります。同一キーは存在確認だけで返します。

Object Lock付きPUTはSHA256 checksumヘッダーを追加・署名します。bucketのversioning/Object Lock・権限は利用環境で設定します。version付きキーの削除はdelete marker作成になることがあり、保持中のversionの消去を意味しません。

失敗応答・checksum正解値・metadata往復・訂正/削除・replica破損・ZIPを回帰テストし、tarballのportable入口をNode polyfillなしの実Chromiumで実行します。実bucketの保持・IAMは利用環境で検証します。

直接転送と公開境界

リモートアダプターはHTTP PUT用のgetUploadUrlとGET用のgetDownloadUrlを提供します。有効期限は1〜604800秒です。R2のS3互換テスト用endpointにはregionも指定できます。実Cloudflare R2は既定のautoを使います。/crypto・/zipから補助処理を利用できます。電帳法対応Manager・文書/監査型・RFC 3161 TSAはPrivateのプレミアム機能です。 bun run test:containersで実MinIOと通信します。日常テストはDockerを起動しません。

AI利用ガイドは配布物の dist/ai/SKILL.md と package-context.json に同梱します。次のコマンドはプロジェクトの指示ファイルへの追記をプレビューします。確認後に --write を付けると既存の指示を保持して反映します。

node node_modules/@alneas/universal-storage/dist/ai/setup.mjs --project .