fs-object-storage 1.0.0

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

@@ -0,0 +1,41 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '16.x'
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nojaja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# fs-object-storage
+
+Node.js fs互換APIでオブジェクトストレージ（MinIO/S3）を操作するライブラリです。
+
+既存のファイルシステムコードを最小限の変更でオブジェクトストレージに対応させることができます。
+
+## 🚀 特徴
+
+- **fs互換API**: 標準のNode.js fsモジュールと同じインターフェース
+- **MinIO/S3対応**: MinIOおよびAmazon S3と互換性
+- **型安全性**: TypeScriptサポート（型定義含む）
+- **ES Modules**: モダンなES Modules形式
+- **ストリーミング**: 大容量ファイルのストリーミング処理対応
+- **エラーハンドリング**: fs互換のエラーコード変換
+
+## 📦 インストール
+
+```bash
+npm install fs-object-storage
+```
+
+## 🏃‍♂️ クイックスタート
+
+### 基本的な使用方法
+
+```javascript
+import { FsMinioClient } from 'fs-object-storage';
+
+// MinIO/S3クライアントの設定
+const client = new FsMinioClient({
+  endPoint: 'localhost',
+  port: 9000,
+  useSSL: false,
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin123'
+});
+
+// ファイル操作（fs互換）
+try {
+  // ファイル書き込み
+  await client.writeFile('/mybucket/path/to/file.txt', 'Hello, World!');
+  
+  // ファイル読み込み
+  const data = await client.readFile('/mybucket/path/to/file.txt', 'utf8');
+  console.log(data); // "Hello, World!"
+  
+  // ファイル存在確認
+  const exists = await client.exists('/mybucket/path/to/file.txt');
+  console.log(exists); // true
+  
+  // ディレクトリ一覧
+  const files = await client.readdir('/mybucket/path');
+  console.log(files); // ['to/']
+  
+} catch (error) {
+  console.error('エラー:', error.message);
+}
+```
+
+### ストリーミング操作
+
+```javascript
+import fs from 'fs';
+
+// 大容量ファイルのアップロード
+const readStream = fs.createReadStream('./large-file.zip');
+const writeStream = await client.createWriteStream('/mybucket/uploads/large-file.zip');
+readStream.pipe(writeStream);
+
+// ダウンロードストリーム
+const downloadStream = await client.createReadStream('/mybucket/uploads/large-file.zip');
+const localWriteStream = fs.createWriteStream('./downloaded-file.zip');
+downloadStream.pipe(localWriteStream);
+```
+
+## 🔧 開発環境のセットアップ
+
+### MinIO開発環境（Docker）
+
+```bash
+# リポジトリをクローン
+git clone <repository-url>
+cd fs-object-storage
+
+# 依存関係のインストール
+npm install
+
+# MinIO開発環境の起動
+docker-compose up -d
+
+# MinIO管理画面: http://localhost:9001
+# ユーザー名: minioadmin
+# パスワード: minioadmin123
+```
+
+### テスト実行
+
+```bash
+# 単体テスト
+npm run test
+
+# 統合テスト（MinIO必須）
+npm run test:integration
+
+# 全テスト
+npm run test:all
+```
+
+## 📚 API リファレンス
+
+### コンストラクタ
+
+```javascript
+new FsMinioClient(options)
+```
+
+**options**:
+- `endPoint`: MinIO/S3エンドポイント
+- `port`: ポート番号
+- `useSSL`: SSL使用フラグ
+- `accessKey`: アクセスキー
+- `secretKey`: シークレットキー
+
+### ファイル操作メソッド
+
+#### `readFile(path, encoding?)`
+ファイルを読み込みます。
+
+```javascript
+const data = await client.readFile('/bucket/file.txt', 'utf8');
+```
+
+#### `writeFile(path, data, options?)`
+ファイルを書き込みます。
+
+```javascript
+await client.writeFile('/bucket/file.txt', 'データ');
+```
+
+#### `exists(path)`
+ファイル/ディレクトリの存在を確認します。
+
+```javascript
+const exists = await client.exists('/bucket/file.txt');
+```
+
+#### `stat(path)`
+ファイル/ディレクトリの統計情報を取得します。
+
+```javascript
+const stats = await client.stat('/bucket/file.txt');
+console.log(stats.size, stats.isFile(), stats.isDirectory());
+```
+
+#### `unlink(path)`
+ファイルを削除します。
+
+```javascript
+await client.unlink('/bucket/file.txt');
+```
+
+#### `copyFile(src, dest)`
+ファイルをコピーします。
+
+```javascript
+await client.copyFile('/bucket/src.txt', '/bucket/dest.txt');
+```
+
+### ディレクトリ操作メソッド
+
+#### `readdir(path)`
+ディレクトリの内容を一覧します。
+
+```javascript
+const files = await client.readdir('/bucket/directory');
+```
+
+#### `mkdir(path, options?)`
+ディレクトリを作成します。
+
+```javascript
+await client.mkdir('/bucket/new-directory', { recursive: true });
+```
+
+#### `rmdir(path)`
+空のディレクトリを削除します。
+
+```javascript
+await client.rmdir('/bucket/empty-directory');
+```
+
+### ストリーム操作メソッド
+
+#### `createReadStream(path)`
+読み込みストリームを作成します。
+
+```javascript
+const stream = await client.createReadStream('/bucket/file.txt');
+```
+
+#### `createWriteStream(path)`
+書き込みストリームを作成します。
+
+```javascript
+const stream = await client.createWriteStream('/bucket/file.txt');
+```
+
+## 🗺️ パス形式
+
+ファイルパスは `/bucket/path/to/file.txt` 形式で指定します：
+
+- 先頭の `/` は必須
+- 最初のセグメントがバケット名
+- それ以降がオブジェクトキー
+
+例：
+- `/mybucket/documents/report.pdf` → バケット: `mybucket`, キー: `documents/report.pdf`
+- `/photos/2023/vacation.jpg` → バケット: `photos`, キー: `2023/vacation.jpg`
+
+## 🚨 エラーハンドリング
+
+MinIOのエラーは自動的にfs互換のエラーコードに変換されます：
+
+```javascript
+try {
+  await client.readFile('/bucket/nonexistent.txt');
+} catch (error) {
+  console.log(error.code); // 'ENOENT'
+  console.log(error.errno); // -2
+  console.log(error.path); // '/bucket/nonexistent.txt'
+}
+```
+
+## 📋 対応エラーコード
+
+| MinIOエラー | fsエラーコード | 説明 |
+|-------------|----------------|------|
+| NoSuchKey | ENOENT | ファイルが存在しない |
+| NoSuchBucket | ENOENT | バケットが存在しない |
+| AccessDenied | EACCES | アクセス権限がない |
+| BucketAlreadyExists | EEXIST | バケットが既に存在 |
+
+## 🔍 使用例
+
+詳細な使用例は以下のファイルを参照してください：
+
+- [`docs/technical/usage-examples.md`](./docs/technical/usage-examples.md) - 包括的な使用例
+- [`samples/fs-minio-test.js`](./samples/fs-minio-test.js) - 統合テストサンプル
+- [`quick-test.js`](./quick-test.js) - 基本動作確認
+
+## 🏗️ アーキテクチャ
+
+本ライブラリは以下のコンポーネントで構成されています：
+
+- **FsMinioClient**: メインのfs互換クライアント
+- **ErrorHandler**: MinIO→fs エラー変換
+- **PathConverter**: ファイルパス⇔バケット/キー変換
+- **StreamConverter**: ストリーム/データ形式変換
+
+詳細は [`docs/technical/architecture.md`](./docs/technical/architecture.md) を参照してください。
+
+## 🧪 テスト
+
+```bash
+# 単体テスト（3つのコンポーネント）
+npm run test
+
+# 統合テスト（MinIO接続必須）
+npm run test:integration
+
+# 全テスト実行
+npm run test:all
+```
+
+## 📄 ライセンス
+
+MIT
+
+## 🤝 コントリビューション
+
+バグ報告や機能提案は Issue からお願いします。プルリクエストも歓迎します。
+
+## 📞 サポート
+
+- **ドキュメント**: [`docs/`](./docs/) フォルダ
+- **GitHub Issues**: バグ報告・機能要求
+- **サンプルコード**: [`samples/`](./samples/) フォルダ"

package/docker-compose.yml

@@ -0,0 +1,24 @@
+version: '3.8'
+
+services:
+  minio:
+    image: minio/minio:latest
+    container_name: fs-object-storage-minio
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin123
+    command: server /data --console-address ":9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+volumes:
+  minio_data:
+    driver: local

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "fs-object-storage",
+  "version": "1.0.0",
+  "description": "Node.js fs compatible API for object storage (MinIO/S3)",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",  "scripts": {
+    "test": "node --test unit-tests.js",
+    "test:integration": "node samples/fs-minio-test.js",
+    "test:all": "npm run test && npm run test:integration",
+    "dev": "node src/index.js",
+    "build": "webpack --mode production"
+  },"keywords": [
+    "filesystem",
+    "fs",
+    "object-storage",
+    "minio",
+    "s3",
+    "compatible",
+    "node",
+    "typescript"
+  ],
+  "author": "nojaja <free.riccia@gmail.com> (https://github.com/nojaja)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nojaja/fs-object-storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nojaja/fs-object-storage/issues"
+  },
+  "homepage": "https://github.com/nojaja/fs-object-storage#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "jest": "^28.1.3",
+    "webpack": "^5.99.8",
+    "webpack-cli": "^5.1.4"
+  },
+  "dependencies": {
+    "memfs": "^4.17.2",
+    "minio": "^8.0.5"
+  }
+}

package/quick-test.js

@@ -0,0 +1,36 @@
+// quick-test.js - Quick test of fs-minio library
+
+console.log('Starting fs-minio quick test...');
+
+import { FsMinioClient } from './src/index.js';
+
+async function quickTest() {
+  try {
+    console.log('Creating client...');    const client = new FsMinioClient({
+      endpoint: 'localhost:9000',
+      accessKey: 'minioadmin',
+      secretKey: 'minioadmin123',
+      bucket: 'fs-minio-test',
+      useSSL: false
+    });
+
+    console.log('Initializing client...');
+    await client.initialize();
+    console.log('Client initialized!');
+
+    console.log('Writing test file...');
+    await client.writeFile('/test.txt', 'Hello World!', 'utf8');
+    console.log('File written!');
+
+    console.log('Reading test file...');
+    const content = await client.readFile('/test.txt', 'utf8');
+    console.log('File content:', content);
+
+    console.log('Test completed successfully!');
+  } catch (error) {
+    console.error('Test failed:', error.message);
+    console.error('Stack:', error.stack);
+  }
+}
+
+quickTest();

package/samples/fs-minio-test.js

@@ -0,0 +1,135 @@
+// fs-minio-test.js - Test the fs-minio library implementation
+
+import { FsMinioClient } from '../src/index.js';
+import path from 'path';
+
+async function testFsMinioLibrary() {
+  console.log('🧪 Testing fs-minio library implementation...\n');
+
+  // Create client instance
+  const client = new FsMinioClient({
+    endpoint: 'localhost:9000',
+    accessKey: 'minioadmin',
+    secretKey: 'minioadmin123',
+    bucket: 'fs-minio-test',
+    useSSL: false,
+    prefix: 'test'
+  });
+
+  try {
+    console.log('📝 Initializing client...');
+    await client.initialize();
+    console.log('✅ Client initialized successfully\n');
+
+    // Test 1: Write file
+    console.log('📝 Test 1: writeFile()');
+    const testContent = 'Hello from fs-minio library!\nThis is a test file.\n今日は良い天気ですね。';
+    await client.writeFile('/data/hello.txt', testContent, 'utf8');
+    console.log('✅ File written successfully\n');
+
+    // Test 2: Check if file exists
+    console.log('📝 Test 2: exists()');
+    const fileExists = await client.exists('/data/hello.txt');
+    console.log(`✅ File exists: ${fileExists}\n`);
+
+    // Test 3: Read file
+    console.log('📝 Test 3: readFile()');
+    const readContent = await client.readFile('/data/hello.txt', 'utf8');
+    console.log(`✅ File content: "${readContent}"\n`);
+    
+    // Verify content matches
+    if (readContent === testContent) {
+      console.log('✅ Content matches original\n');
+    } else {
+      console.log('❌ Content does not match!\n');
+    }
+
+    // Test 4: Get file stats
+    console.log('📝 Test 4: stat()');
+    const stats = await client.stat('/data/hello.txt');
+    console.log('✅ File stats:');
+    console.log(`   Size: ${stats.size} bytes`);
+    console.log(`   Modified: ${stats.mtime}`);
+    console.log(`   Is file: ${stats.isFile()}`);
+    console.log(`   Is directory: ${stats.isDirectory()}\n`);
+
+    // Test 5: Write binary file
+    console.log('📝 Test 5: writeFile() with binary data');
+    const binaryData = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]); // PNG header
+    await client.writeFile('/images/test.png', binaryData);
+    console.log('✅ Binary file written successfully\n');
+
+    // Test 6: Read binary file
+    console.log('📝 Test 6: readFile() binary data');
+    const readBinary = await client.readFile('/images/test.png');
+    console.log(`✅ Binary data read: ${readBinary.length} bytes`);
+    console.log(`   First 8 bytes: ${Array.from(readBinary.slice(0, 8)).map(b => '0x' + b.toString(16).padStart(2, '0')).join(', ')}\n`);
+
+    // Test 7: Create directory
+    console.log('📝 Test 7: mkdir()');
+    await client.mkdir('/documents/projects', { recursive: true });
+    console.log('✅ Directory created successfully\n');
+
+    // Test 8: List files in root
+    console.log('📝 Test 8: readdir()');
+    const rootFiles = await client.readdir('/');
+    console.log(`✅ Root directory contents: ${JSON.stringify(rootFiles)}\n`);
+
+    // Test 9: Test error handling (non-existent file)
+    console.log('📝 Test 9: Error handling');
+    try {
+      await client.readFile('/nonexistent/file.txt');
+      console.log('❌ Should have thrown error');
+    } catch (error) {
+      console.log(`✅ Correctly threw error: ${error.code} - ${error.message}\n`);
+    }
+
+    // Test 10: Delete file
+    console.log('📝 Test 10: unlink()');
+    await client.unlink('/data/hello.txt');
+    console.log('✅ File deleted successfully\n');
+
+    // Test 11: Verify file is deleted
+    console.log('📝 Test 11: Verify deletion');
+    const fileExistsAfterDelete = await client.exists('/data/hello.txt');
+    console.log(`✅ File exists after delete: ${fileExistsAfterDelete}\n`);
+
+    // Test 12: Test streams
+    console.log('📝 Test 12: createReadStream()');
+    const streamContent = 'This is stream test content\nLine 2\nLine 3';
+    await client.writeFile('/streams/test.txt', streamContent);
+    
+    const readStream = await client.createReadStream('/streams/test.txt');
+    const chunks = [];
+    
+    readStream.on('data', (chunk) => {
+      chunks.push(chunk);
+    });
+    
+    await new Promise((resolve, reject) => {
+      readStream.on('end', () => {
+        const streamData = Buffer.concat(chunks).toString('utf8');
+        console.log(`✅ Stream content: "${streamData}"`);
+        if (streamData === streamContent) {
+          console.log('✅ Stream content matches original\n');
+        } else {
+          console.log('❌ Stream content does not match!\n');
+        }
+        resolve();
+      });
+      readStream.on('error', reject);
+    });
+
+    console.log('🎉 All tests completed successfully!');
+
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    if (error.originalError) {
+      console.error('Original error:', error.originalError.message);
+    }
+    console.error('Stack:', error.stack);
+  }
+}
+
+// Run tests
+testFsMinioLibrary().catch(console.error);

package/samples/memfs-sample.js

@@ -0,0 +1,44 @@
+// memfsライブラリのAPI調査用サンプル
+import { fs } from 'memfs';
+
+console.log('=== memfs API調査 ===');
+
+// 1. memfsの基本的なfs互換API確認
+console.log('\n1. 利用可能なメソッド:');
+const fsMethods = Object.getOwnPropertyNames(fs).filter(name => typeof fs[name] === 'function');
+console.log(fsMethods.slice(0, 20)); // 最初の20個のメソッドを表示
+
+// 2. fs.writeFileの動作確認
+try {
+    fs.writeFileSync('/test.txt', 'Hello memfs!');
+    console.log('\n2. writeFileSync成功');
+    
+    // 3. fs.readFileの動作確認
+    const content = fs.readFileSync('/test.txt', 'utf8');
+    console.log('3. readFileSync結果:', content);
+    
+    // 4. fs.existsSyncの動作確認
+    const exists = fs.existsSync('/test.txt');
+    console.log('4. existsSync結果:', exists);
+    
+    // 5. fs.statSyncの動作確認
+    const stats = fs.statSync('/test.txt');
+    console.log('5. statSync結果:', {
+        size: stats.size,
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory()
+    });
+    
+    // 6. Promise版APIの確認
+    console.log('\n6. Promise版API確認:');
+    console.log('fs.promises利用可能:', typeof fs.promises === 'object');
+    if (fs.promises) {
+        const promiseMethods = Object.getOwnPropertyNames(fs.promises).filter(name => typeof fs.promises[name] === 'function');
+        console.log('Promise版メソッド例:', promiseMethods.slice(0, 10));
+    }
+    
+} catch (error) {
+    console.error('エラーが発生したのだ:', error.message);
+}
+
+console.log('\n=== memfs調査完了 ===');