fs-object-storage 1.0.0 → 1.0.2

package/.github/workflows/npm-publish.yml

@@ -29,13 +29,16 @@ jobs:
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # OIDC認証に必須
+      contents: read
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '16.x'
+          node-version: '20.x'
           registry-url: https://registry.npmjs.org/
+      - run: npm install -g npm@latest
       - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+      - name: Publish to NPM with Trusted Publishing
+        run: npm publish --access public

package/README.md

@@ -24,10 +24,10 @@ npm install fs-object-storage
 ### 基本的な使用方法
 
 ```javascript
-import { FsMinioClient } from 'fs-object-storage';
+import { ObjectStorage } from 'fs-object-storage';
 
 // MinIO/S3クライアントの設定
-const client = new FsMinioClient({
+const fs = new ObjectStorage({
   endPoint: 'localhost',
   port: 9000,
   useSSL: false,
@@ -38,18 +38,18 @@ const client = new FsMinioClient({
 // ファイル操作（fs互換）
 try {
   // ファイル書き込み
-  await client.writeFile('/mybucket/path/to/file.txt', 'Hello, World!');
+  await fs.writeFile('/mybucket/path/to/file.txt', 'Hello, World!');
   
   // ファイル読み込み
-  const data = await client.readFile('/mybucket/path/to/file.txt', 'utf8');
+  const data = await fs.readFile('/mybucket/path/to/file.txt', 'utf8');
   console.log(data); // "Hello, World!"
   
   // ファイル存在確認
-  const exists = await client.exists('/mybucket/path/to/file.txt');
+  const exists = await fs.exists('/mybucket/path/to/file.txt');
   console.log(exists); // true
   
   // ディレクトリ一覧
-  const files = await client.readdir('/mybucket/path');
+  const files = await fs.readdir('/mybucket/path');
   console.log(files); // ['to/']
   
 } catch (error) {
@@ -64,11 +64,11 @@ import fs from 'fs';
 
 // 大容量ファイルのアップロード
 const readStream = fs.createReadStream('./large-file.zip');
-const writeStream = await client.createWriteStream('/mybucket/uploads/large-file.zip');
+const writeStream = await fs.createWriteStream('/mybucket/uploads/large-file.zip');
 readStream.pipe(writeStream);
 
 // ダウンロードストリーム
-const downloadStream = await client.createReadStream('/mybucket/uploads/large-file.zip');
+const downloadStream = await fs.createReadStream('/mybucket/uploads/large-file.zip');
 const localWriteStream = fs.createWriteStream('./downloaded-file.zip');
 downloadStream.pipe(localWriteStream);
 ```
@@ -111,7 +111,7 @@ npm run test:all
 ### コンストラクタ
 
 ```javascript
-new FsMinioClient(options)
+new ObjectStorage(options)
 ```
 
 **options**:
@@ -127,28 +127,28 @@ new FsMinioClient(options)
 ファイルを読み込みます。
 
 ```javascript
-const data = await client.readFile('/bucket/file.txt', 'utf8');
+const data = await fs.readFile('/bucket/file.txt', 'utf8');
 ```
 
 #### `writeFile(path, data, options?)`
 ファイルを書き込みます。
 
 ```javascript
-await client.writeFile('/bucket/file.txt', 'データ');
+await fs.writeFile('/bucket/file.txt', 'データ');
 ```
 
 #### `exists(path)`
 ファイル/ディレクトリの存在を確認します。
 
 ```javascript
-const exists = await client.exists('/bucket/file.txt');
+const exists = await fs.exists('/bucket/file.txt');
 ```
 
 #### `stat(path)`
 ファイル/ディレクトリの統計情報を取得します。
 
 ```javascript
-const stats = await client.stat('/bucket/file.txt');
+const stats = await fs.stat('/bucket/file.txt');
 console.log(stats.size, stats.isFile(), stats.isDirectory());
 ```
 
@@ -156,14 +156,14 @@ console.log(stats.size, stats.isFile(), stats.isDirectory());
 ファイルを削除します。
 
 ```javascript
-await client.unlink('/bucket/file.txt');
+await fs.unlink('/bucket/file.txt');
 ```
 
 #### `copyFile(src, dest)`
 ファイルをコピーします。
 
 ```javascript
-await client.copyFile('/bucket/src.txt', '/bucket/dest.txt');
+await fs.copyFile('/bucket/src.txt', '/bucket/dest.txt');
 ```
 
 ### ディレクトリ操作メソッド
@@ -172,21 +172,21 @@ await client.copyFile('/bucket/src.txt', '/bucket/dest.txt');
 ディレクトリの内容を一覧します。
 
 ```javascript
-const files = await client.readdir('/bucket/directory');
+const files = await fs.readdir('/bucket/directory');
 ```
 
 #### `mkdir(path, options?)`
 ディレクトリを作成します。
 
 ```javascript
-await client.mkdir('/bucket/new-directory', { recursive: true });
+await fs.mkdir('/bucket/new-directory', { recursive: true });
 ```
 
 #### `rmdir(path)`
 空のディレクトリを削除します。
 
 ```javascript
-await client.rmdir('/bucket/empty-directory');
+await fs.rmdir('/bucket/empty-directory');
 ```
 
 ### ストリーム操作メソッド
@@ -195,14 +195,14 @@ await client.rmdir('/bucket/empty-directory');
 読み込みストリームを作成します。
 
 ```javascript
-const stream = await client.createReadStream('/bucket/file.txt');
+const stream = await fs.createReadStream('/bucket/file.txt');
 ```
 
 #### `createWriteStream(path)`
 書き込みストリームを作成します。
 
 ```javascript
-const stream = await client.createWriteStream('/bucket/file.txt');
+const stream = await fs.createWriteStream('/bucket/file.txt');
 ```
 
 ## 🗺️ パス形式
@@ -223,7 +223,7 @@ MinIOのエラーは自動的にfs互換のエラーコードに変換されま
 
 ```javascript
 try {
-  await client.readFile('/bucket/nonexistent.txt');
+  await fs.readFile('/bucket/nonexistent.txt');
 } catch (error) {
   console.log(error.code); // 'ENOENT'
   console.log(error.errno); // -2
@@ -252,7 +252,7 @@ try {
 
 本ライブラリは以下のコンポーネントで構成されています：
 
-- **FsMinioClient**: メインのfs互換クライアント
+- **ObjectStorage**: メインのfs互換クライアント
 - **ErrorHandler**: MinIO→fs エラー変換
 - **PathConverter**: ファイルパス⇔バケット/キー変換
 - **StreamConverter**: ストリーム/データ形式変換
@@ -284,4 +284,4 @@ MIT
 
 - **ドキュメント**: [`docs/`](./docs/) フォルダ
 - **GitHub Issues**: バグ報告・機能要求
-- **サンプルコード**: [`samples/`](./samples/) フォルダ"
+- **サンプルコード**: [`samples/`](./samples/) フォルダ

package/docs/technical/api-reference.md

@@ -0,0 +1,312 @@
+# fs-object-storage API リファレンス
+
+## 概要
+`fs-object-storage`は、Node.js標準の`fs`モジュールと互換性のあるAPIを提供しながら、バックエンドでMinIO/S3オブジェクトストレージを使用するライブラリです。
+
+## インストール・セットアップ
+
+### 依存関係
+```bash
+npm install minio
+```
+
+### 基本的な使用方法
+```javascript
+import { ObjectStorage } from './src/index.js';
+
+const fs = new ObjectStorage({
+  endpoint: 'localhost:9000',
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin123',
+  bucket: 'my-app-bucket',
+  useSSL: false,
+  prefix: 'app-data'  // オプション：全てのキーにプレフィックスを追加
+});
+
+// 初期化（バケット作成など）
+await fs.initialize();
+```
+
+## コンストラクター
+
+### `new ObjectStorage(options)`
+
+MinIOクライアントインスタンスを作成します。
+
+**パラメーター:**
+- `options` (Object) - 設定オプション
+  - `endpoint` (string) - MinIOエンドポイント (例: 'localhost:9000')
+  - `accessKey` (string) - アクセスキー
+  - `secretKey` (string) - シークレットキー
+  - `bucket` (string) - 使用するバケット名
+  - `useSSL` (boolean, optional) - SSL使用フラグ（デフォルト: false）
+  - `region` (string, optional) - リージョン（デフォルト: 'us-east-1'）
+  - `prefix` (string, optional) - 全キーに追加するプレフィックス
+
+## ファイル操作メソッド
+
+### `readFile(filePath, options)`
+
+ファイルの内容を読み取ります。
+
+```javascript
+// テキストファイルを読む
+const content = await fs.readFile('/data/hello.txt', 'utf8');
+
+// バイナリファイルを読む
+const buffer = await fs.readFile('/images/photo.jpg');
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+- `options` (string|Object, optional) - エンコーディングまたはオプション
+  - `encoding` (string) - テキストエンコーディング
+
+**戻り値:** `Promise<Buffer|string>` - ファイル内容
+
+### `writeFile(filePath, data, options)`
+
+ファイルにデータを書き込みます。
+
+```javascript
+// テキストファイルを書く
+await fs.writeFile('/data/hello.txt', 'Hello World!', 'utf8');
+
+// バイナリファイルを書く
+const buffer = Buffer.from([0x89, 0x50, 0x4E, 0x47]);
+await fs.writeFile('/images/test.png', buffer);
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+- `data` (string|Buffer|Uint8Array) - 書き込むデータ
+- `options` (string|Object, optional) - エンコーディングまたはオプション
+
+**戻り値:** `Promise<void>`
+
+### `exists(filePath)`
+
+ファイルの存在を確認します。
+
+```javascript
+const fileExists = await fs.exists('/data/hello.txt');
+console.log(fileExists); // true または false
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+
+**戻り値:** `Promise<boolean>` - ファイル存在フラグ
+
+### `stat(filePath)`
+
+ファイルの統計情報を取得します。
+
+```javascript
+const stats = await fs.stat('/data/hello.txt');
+console.log('ファイルサイズ:', stats.size);
+console.log('更新日時:', stats.mtime);
+console.log('ファイルかどうか:', stats.isFile());
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+
+**戻り値:** `Promise<Object>` - fs.Stats風オブジェクト
+
+### `unlink(filePath)`
+
+ファイルを削除します。
+
+```javascript
+await fs.unlink('/data/old-file.txt');
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+
+**戻り値:** `Promise<void>`
+
+## ディレクトリ操作メソッド
+
+### `readdir(dirPath, options)`
+
+ディレクトリの内容を一覧表示します。
+
+```javascript
+// ファイル名の配列を取得
+const files = await fs.readdir('/data');
+
+// Direntオブジェクトの配列を取得
+const entries = await fs.readdir('/data', { withFileTypes: true });
+```
+
+**パラメーター:**
+- `dirPath` (string) - ディレクトリパス
+- `options` (Object, optional) - オプション
+  - `withFileTypes` (boolean) - Direntオブジェクトを返すかどうか
+
+**戻り値:** `Promise<string[]|Object[]>` - ファイル名またはDirentオブジェクトの配列
+
+### `mkdir(dirPath, options)`
+
+ディレクトリを作成します。
+
+```javascript
+// 単一ディレクトリ作成
+await fs.mkdir('/new-folder');
+
+// 再帰的作成（親ディレクトリも作成）
+await fs.mkdir('/deep/nested/folder', { recursive: true });
+```
+
+**パラメーター:**
+- `dirPath` (string) - ディレクトリパス
+- `options` (Object, optional) - オプション
+  - `recursive` (boolean) - 親ディレクトリも作成するかどうか
+
+**戻り値:** `Promise<void>`
+
+### `rmdir(dirPath)`
+
+空のディレクトリを削除します。
+
+```javascript
+await fs.rmdir('/empty-folder');
+```
+
+**パラメーター:**
+- `dirPath` (string) - ディレクトリパス
+
+**戻り値:** `Promise<void>`
+
+## ストリーム操作メソッド
+
+### `createReadStream(filePath, options)`
+
+読み取りストリームを作成します。
+
+```javascript
+const readStream = await fs.createReadStream('/large-file.txt');
+
+readStream.on('data', (chunk) => {
+  console.log('受信:', chunk.length, 'バイト');
+});
+
+readStream.on('end', () => {
+  console.log('読み取り完了');
+});
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+- `options` (Object, optional) - ストリームオプション
+
+**戻り値:** `Promise<Readable>` - 読み取りストリーム
+
+### `createWriteStream(filePath, options)`
+
+書き込みストリームを作成します。
+
+```javascript
+const writeStream = fs.createWriteStream('/output.txt');
+
+writeStream.write('Hello ');
+writeStream.write('World!');
+writeStream.end();
+```
+
+**パラメーター:**
+- `filePath` (string) - ファイルパス
+- `options` (Object, optional) - ストリームオプション
+
+**戻り値:** `Writable` - 書き込みストリーム
+
+## 高度な操作
+
+### `copyFile(srcPath, destPath)`
+
+ファイルをコピーします。
+
+```javascript
+await fs.copyFile('/source.txt', '/destination.txt');
+```
+
+**パラメーター:**
+- `srcPath` (string) - コピー元ファイルパス
+- `destPath` (string) - コピー先ファイルパス
+
+**戻り値:** `Promise<void>`
+
+## エラーハンドリング
+
+ライブラリは標準的なNode.js `fs`モジュールと同じエラーコードを使用します：
+
+```javascript
+try {
+  await fs.readFile('/nonexistent.txt');
+} catch (error) {
+  if (error.code === 'ENOENT') {
+    console.log('ファイルが見つかりません');
+  } else if (error.code === 'EACCES') {
+    console.log('アクセス権限がありません');
+  }
+}
+```
+
+### 主要なエラーコード
+- `ENOENT` - ファイル/ディレクトリが存在しない
+- `EACCES` - アクセス権限拒否
+- `EEXIST` - ファイル/ディレクトリが既に存在
+- `ENOTDIR` - ディレクトリではない
+- `ENOTEMPTY` - ディレクトリが空でない
+
+## パス変換について
+
+ファイルシステムパスは自動的にMinIOオブジェクトキーに変換されます：
+
+```javascript
+// ファイルシステムパス → MinIOキー
+'/data/users/123/profile.json' → 'data/users/123/profile.json'
+
+// プレフィックス付きの場合
+// prefix: 'app-data'
+'/data/file.txt' → 'app-data/data/file.txt'
+```
+
+## 仮想ディレクトリ
+
+MinIOにはディレクトリの概念がないため、プレフィックスベースの仮想ディレクトリを実装しています：
+
+- ディレクトリマーカー（空のオブジェクト）を使用
+- `readdir()`は共通プレフィックスでオブジェクトを検索
+- `mkdir()`はディレクトリマーカーオブジェクトを作成
+
+## パフォーマンス考慮事項
+
+- 大きなファイルにはストリームAPIを使用することを推奨
+- 同期APIは提供していません（全て非同期）
+- バッチ操作は個別に実装する必要があります
+
+## トラブルシューティング
+
+### よくある問題
+
+1. **接続エラー**
+```javascript
+// 接続設定を確認
+console.log('MinIOエンドポイント:', fs.endpoint);
+// MinIOサーバーが起動しているか確認
+```
+
+2. **認証エラー**
+```javascript
+// アクセスキー・シークレットキーを確認
+// MinIOコンソールで権限を確認
+```
+
+3. **バケット存在エラー**
+```javascript
+// initialize()を呼び出してバケットを作成
+await fs.initialize();
+```

package/docs/technical/architecture.md

@@ -0,0 +1,179 @@
+# fs-object-storage アーキテクチャ設計
+
+## 概要
+Node.js fsモジュール互換のAPIを提供しながら、バックエンドでMinIO/S3オブジェクトストレージを使用するライブラリ。
+
+## アーキテクチャ
+
+### レイヤー構造
+```
+┌─────────────────────────────────────┐
+│        fs 互換 API レイヤー          │
+│  (readFile, writeFile, exists, etc.) │
+├─────────────────────────────────────┤
+│        パス変換レイヤー              │
+│  (/path/to/file → bucket/key)       │
+├─────────────────────────────────────┤
+│        ストリーム変換レイヤー         │
+│  (Buffer/String ↔ MinIO Stream)     │
+├─────────────────────────────────────┤
+│        エラー変換レイヤー            │
+│  (MinIO Error → fs Error)           │
+├─────────────────────────────────────┤
+│        MinIO クライアント            │
+│  (Low-level object operations)      │
+└─────────────────────────────────────┘
+```
+
+## 主要コンポーネント
+
+### 1. ObjectStorage
+- メインのクライアントクラス
+- fs互換APIの提供
+- 設定管理（bucket名、接続情報等）
+
+### 2. PathConverter
+- ファイルシステムパス → MinIOオブジェクトキー変換
+- 仮想ディレクトリ実装（プレフィックスベース）
+- パス正規化
+
+### 3. StreamConverter
+- Buffer/String → MinIO readable stream
+- MinIO readable stream → Buffer/String
+- 非同期ストリーム処理
+
+### 4. ErrorHandler
+- MinIOエラー → fs-style エラー変換
+- 適切なerror.codeの設定
+- エラーメッセージの正規化
+
+### 5. MetadataManager
+- ファイルメタデータの管理
+- 仮想ディレクトリ情報
+- タイムスタンプ、サイズ等の stat 情報
+
+## API設計
+
+### 基本原則
+- fs モジュールとの完全互換性
+- 同期/非同期両方のAPIサポート
+- Promise ベースの実装
+- TypeScript サポート
+
+### 実装対象メソッド（優先度順）
+
+#### Phase 1: 基本ファイル操作
+- [x] `readFile(path, options)` - ファイル読み込み
+- [x] `writeFile(path, data, options)` - ファイル書き込み
+- [x] `exists(path)` - ファイル存在確認
+- [x] `stat(path)` - ファイル情報取得
+- [x] `unlink(path)` - ファイル削除
+
+#### Phase 2: ディレクトリ操作
+- [ ] `readdir(path)` - ディレクトリ一覧
+- [ ] `mkdir(path)` - ディレクトリ作成
+- [ ] `rmdir(path)` - ディレクトリ削除
+
+#### Phase 3: ストリーム操作
+- [ ] `createReadStream(path)` - 読み込みストリーム
+- [ ] `createWriteStream(path)` - 書き込みストリーム
+
+#### Phase 4: 高度な操作
+- [ ] `copyFile(src, dest)` - ファイルコピー
+- [ ] `rename(oldPath, newPath)` - ファイル移動/リネーム
+
+## パス変換仕様
+
+### ファイルシステムパス → MinIOキー
+```javascript
+// 例：
+'/data/users/123/profile.json' 
+→ bucket: 'myapp', key: 'data/users/123/profile.json'
+
+'/images/avatar.png'
+→ bucket: 'myapp', key: 'images/avatar.png'
+```
+
+### 仮想ディレクトリ実装
+- MinIOにディレクトリ概念はないため、プレフィックスベースで実装
+- 空の「ディレクトリマーカー」オブジェクトを作成
+- readdir では共通プレフィックスでオブジェクト一覧を取得
+
+## エラーハンドリング
+
+### MinIOエラー → fsエラー変換マッピング
+```javascript
+const errorMapping = {
+  'NoSuchKey': { code: 'ENOENT', errno: -2 },
+  'AccessDenied': { code: 'EACCES', errno: -13 },
+  'BucketNotFound': { code: 'ENOENT', errno: -2 },
+  'InvalidBucketName': { code: 'EINVAL', errno: -22 },
+};
+```
+
+## 設定例
+```javascript
+const fs = new ObjectStorage({
+  endpoint: 'localhost:9000',
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin',
+  bucket: 'myapp',
+  useSSL: false
+});
+
+// fs互換API
+await fs.writeFile('/data/test.txt', 'Hello World');
+const content = await fs.readFile('/data/test.txt', 'utf8');
+```
+
+## 実装フェーズ計画
+
+### Phase 1: 基本実装 (目標: 2-3日)
+1. プロジェクト構造セットアップ
+2. FsMinioClient基本クラス作成
+3. 基本ファイル操作（read/write/exists/stat/unlink）実装
+4. 基本的なエラーハンドリング
+
+### Phase 2: ディレクトリ機能 (目標: 1-2日)
+1. PathConverter実装
+2. 仮想ディレクトリ機能
+3. readdir, mkdir, rmdir実装
+
+### Phase 3: ストリーム機能 (目標: 1-2日)
+1. StreamConverter実装
+2. createReadStream, createWriteStream実装
+3. 大きなファイル対応
+
+### Phase 4: 完成 (目標: 1日)
+1. 高度な機能（copy, rename等）
+2. TypeScript型定義
+3. 詳細テスト
+4. ドキュメント整備
+
+## テスト戦略
+
+### 単体テスト
+- 各コンポーネントの独立テスト
+- モックを使用したMinIOクライアント分離
+
+### 統合テスト
+- 実際のMinIOコンテナを使用
+- End-to-endテストシナリオ
+
+### パフォーマンステスト
+- 大きなファイルの読み書き
+- 同時接続数の確認
+- メモリ使用量の監視
+
+### `new ObjectStorage(options)`
+```javascript
+const fs = new ObjectStorage({
+  endpoint: 'localhost:9000',
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin',
+  bucket: 'myapp',
+  useSSL: false
+});
+
+// 以降のclientをfsに統一
+```