fs-object-storage 1.0.0 → 1.0.1

package/docs/technical/usage-examples.md

@@ -0,0 +1,394 @@
+# fs-object-storage 使用例
+
+このドキュメントでは、`fs-object-storage`ライブラリの実際的な使用例を紹介します。
+
+## 1. 基本セットアップ
+
+```javascript
+import { ObjectStorage } from 'fs-object-storage';
+
+// クライアント作成
+const fs = new ObjectStorage({
+  endpoint: 'localhost:9000',
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin123',
+  bucket: 'my-app-storage',
+  useSSL: false,
+  prefix: 'app-data'
+});
+
+// 初期化
+await fs.initialize();
+```
+
+## 2. ファイル管理システム
+
+### ファイルアップロード
+```javascript
+async function uploadFile(filePath, fileContent) {
+  try {
+    await fs.writeFile(filePath, fileContent);
+    console.log(`ファイル ${filePath} をアップロードしました`);
+  } catch (error) {
+    console.error('アップロードエラー:', error.message);
+  }
+}
+
+// テキストファイル
+await uploadFile('/documents/readme.txt', 'このファイルはMinIOに保存されています');
+
+// JSONデータ
+const userData = { name: 'ずんだもん', age: 3, hobby: 'ずんだ餅作り' };
+await uploadFile('/data/user.json', JSON.stringify(userData, null, 2));
+```
+
+### ファイルダウンロード
+```javascript
+async function downloadFile(filePath) {
+  try {
+    if (await fs.exists(filePath)) {
+      const content = await fs.readFile(filePath, 'utf8');
+      console.log(`ファイル内容: ${content}`);
+      return content;
+    } else {
+      console.log('ファイルが見つかりません');
+    }
+  } catch (error) {
+    console.error('ダウンロードエラー:', error.message);
+  }
+}
+
+await downloadFile('/documents/readme.txt');
+```
+
+## 3. 画像ストレージシステム
+
+### 画像アップロード
+```javascript
+import fs from 'fs';
+
+async function uploadImage(imagePath, localPath) {
+  try {
+    // ローカルファイルを読み込み
+    const imageBuffer = fs.readFileSync(localPath);
+    
+    // MinIOにアップロード
+    await fs.writeFile(imagePath, imageBuffer);
+    
+    console.log(`画像 ${imagePath} をアップロードしました`);
+    
+    // 画像情報を取得
+    const stats = await fs.stat(imagePath);
+    console.log(`ファイルサイズ: ${stats.size} bytes`);
+    
+  } catch (error) {
+    console.error('画像アップロードエラー:', error.message);
+  }
+}
+
+await uploadImage('/images/profile/avatar.jpg', './local-avatar.jpg');
+```
+
+### サムネイル管理
+```javascript
+async function createThumbnailStructure(userId) {
+  const userDir = `/images/users/${userId}`;
+  
+  try {
+    // ユーザー画像ディレクトリ作成
+    await fs.mkdir(userDir, { recursive: true });
+    await fs.mkdir(`${userDir}/thumbnails`, { recursive: true });
+    await fs.mkdir(`${userDir}/originals`, { recursive: true });
+    
+    console.log(`ユーザー ${userId} の画像フォルダを作成しました`);
+  } catch (error) {
+    console.error('フォルダ作成エラー:', error.message);
+  }
+}
+
+await createThumbnailStructure('user123');
+```
+
+## 4. ログ管理システム
+
+### ログ書き込み
+```javascript
+async function writeLog(level, message) {
+  const timestamp = new Date().toISOString();
+  const logEntry = `[${timestamp}] ${level.toUpperCase()}: ${message}\n`;
+  
+  const today = new Date().toISOString().split('T')[0];
+  const logPath = `/logs/${today}.log`;
+  
+  try {
+    // 既存ログがあるかチェック
+    let existingLog = '';
+    if (await fs.exists(logPath)) {
+      existingLog = await fs.readFile(logPath, 'utf8');
+    }
+    
+    // ログエントリを追加
+    await fs.writeFile(logPath, existingLog + logEntry);
+    
+  } catch (error) {
+    console.error('ログ書き込みエラー:', error.message);
+  }
+}
+
+await writeLog('info', 'アプリケーションが開始されました');
+await writeLog('error', 'データベース接続に失敗しました');
+```
+
+### ログ読み取り
+```javascript
+async function readLogs(date) {
+  const logPath = `/logs/${date}.log`;
+  
+  try {
+    if (await fs.exists(logPath)) {
+      const logContent = await fs.readFile(logPath, 'utf8');
+      const lines = logContent.split('\n').filter(line => line.trim());
+      
+      console.log(`${date}のログ (${lines.length}エントリ):`);
+      lines.forEach(line => console.log(line));
+    } else {
+      console.log(`${date}のログファイルは存在しません`);
+    }
+  } catch (error) {
+    console.error('ログ読み取りエラー:', error.message);
+  }
+}
+
+await readLogs('2025-06-04');
+```
+
+## 5. バックアップシステム
+
+### データバックアップ
+```javascript
+async function backupData(sourceDir, backupDir) {
+  try {
+    // バックアップディレクトリ作成
+    await fs.mkdir(backupDir, { recursive: true });
+    
+    // ソースディレクトリのファイル一覧取得
+    const files = await fs.readdir(sourceDir);
+    
+    console.log(`${files.length}ファイルをバックアップします...`);
+    
+    for (const file of files) {
+      const sourcePath = `${sourceDir}/${file}`;
+      const backupPath = `${backupDir}/${file}`;
+      
+      // ファイルコピー
+      await fs.copyFile(sourcePath, backupPath);
+      console.log(`✓ ${file} をバックアップしました`);
+    }
+    
+    console.log('バックアップ完了');
+    
+  } catch (error) {
+    console.error('バックアップエラー:', error.message);
+  }
+}
+
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+await backupData('/important-data', `/backups/${timestamp}`);
+```
+
+## 6. ストリーミング処理
+
+### 大きなファイルのストリーミング
+```javascript
+async function streamLargeFile(filePath) {
+  try {
+    const readStream = await fs.createReadStream(filePath);
+    
+    let totalBytes = 0;
+    
+    readStream.on('data', (chunk) => {
+      totalBytes += chunk.length;
+      console.log(`受信: ${chunk.length} bytes (合計: ${totalBytes})`);
+    });
+    
+    readStream.on('end', () => {
+      console.log(`ストリーミング完了: 合計 ${totalBytes} bytes`);
+    });
+    
+    readStream.on('error', (error) => {
+      console.error('ストリーミングエラー:', error.message);
+    });
+    
+  } catch (error) {
+    console.error('ストリーム作成エラー:', error.message);
+  }
+}
+
+await streamLargeFile('/videos/large-movie.mp4');
+```
+
+### ストリーミングアップロード
+```javascript
+function streamUpload(filePath, dataGenerator) {
+  return new Promise((resolve, reject) => {
+    const writeStream = fs.createWriteStream(filePath);
+    
+    writeStream.on('finish', () => {
+      console.log('アップロード完了');
+      resolve();
+    });
+    
+    writeStream.on('error', reject);
+    
+    // データを段階的に書き込み
+    for (const data of dataGenerator()) {
+      writeStream.write(data);
+    }
+    
+    writeStream.end();
+  });
+}
+
+// 大きなCSVファイルの生成例
+function* generateCsvData() {
+  yield 'id,name,email\n';
+  for (let i = 1; i <= 10000; i++) {
+    yield `${i},User${i},user${i}@example.com\n`;
+  }
+}
+
+await streamUpload('/data/users.csv', generateCsvData);
+```
+
+## 7. ファイル管理ユーティリティ
+
+### ディレクトリサイズ計算
+```javascript
+async function calculateDirectorySize(dirPath) {
+  try {
+    const files = await fs.readdir(dirPath);
+    let totalSize = 0;
+    
+    for (const file of files) {
+      const filePath = `${dirPath}/${file}`;
+      const stats = await fs.stat(filePath);
+      totalSize += stats.size;
+    }
+    
+    console.log(`${dirPath} のサイズ: ${totalSize} bytes`);
+    return totalSize;
+    
+  } catch (error) {
+    console.error('サイズ計算エラー:', error.message);
+    return 0;
+  }
+}
+
+await calculateDirectorySize('/documents');
+```
+
+### ファイルクリーンアップ
+```javascript
+async function cleanupOldFiles(dirPath, daysOld = 30) {
+  try {
+    const files = await fs.readdir(dirPath);
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - daysOld);
+    
+    let deletedCount = 0;
+    
+    for (const file of files) {
+      const filePath = `${dirPath}/${file}`;
+      const stats = await fs.stat(filePath);
+      
+      if (stats.mtime < cutoffDate) {
+        await fs.unlink(filePath);
+        console.log(`削除: ${file}`);
+        deletedCount++;
+      }
+    }
+    
+    console.log(`${deletedCount}ファイルを削除しました`);
+    
+  } catch (error) {
+    console.error('クリーンアップエラー:', error.message);
+  }
+}
+
+await cleanupOldFiles('/temp', 7); // 7日以上古いファイルを削除
+```
+
+## 8. エラーハンドリングのベストプラクティス
+
+```javascript
+async function robustFileOperation(filePath, data) {
+  const maxRetries = 3;
+  let retries = 0;
+  
+  while (retries < maxRetries) {
+    try {
+      await fs.writeFile(filePath, data);
+      console.log('ファイル操作成功');
+      return;
+      
+    } catch (error) {
+      retries++;
+      
+      if (error.code === 'ENOENT') {
+        // ディレクトリが存在しない場合は作成
+        const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+        await fs.mkdir(dir, { recursive: true });
+        
+      } else if (error.code === 'EACCES') {
+        console.error('アクセス権限エラー:', error.message);
+        break;
+        
+      } else if (retries < maxRetries) {
+        console.log(`リトライ ${retries}/${maxRetries}: ${error.message}`);
+        await new Promise(resolve => setTimeout(resolve, 1000 * retries));
+        
+      } else {
+        console.error('最大リトライ数に達しました:', error.message);
+        throw error;
+      }
+    }
+  }
+}
+
+await robustFileOperation('/new-dir/important-file.txt', 'Important data');
+```
+
+## 9. パフォーマンス最適化
+
+### 並列処理
+```javascript
+async function parallelUpload(files) {
+  const uploadPromises = files.map(async ({ path, content }) => {
+    try {
+      await fs.writeFile(path, content);
+      return { path, success: true };
+    } catch (error) {
+      return { path, success: false, error: error.message };
+    }
+  });
+  
+  const results = await Promise.all(uploadPromises);
+  
+  const successful = results.filter(r => r.success).length;
+  const failed = results.filter(r => !r.success).length;
+  
+  console.log(`アップロード完了: 成功 ${successful}, 失敗 ${failed}`);
+  
+  return results;
+}
+
+const filesToUpload = [
+  { path: '/batch/file1.txt', content: 'Content 1' },
+  { path: '/batch/file2.txt', content: 'Content 2' },
+  { path: '/batch/file3.txt', content: 'Content 3' }
+];
+
+await parallelUpload(filesToUpload);
+```
+
+これらの例を参考に、MinIOをファイルシステムとして活用したアプリケーションを開発できます。`fs-minio`ライブラリにより、従来のファイルシステム操作をクラウドストレージ環境でも同じように実行できるのだ！

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-object-storage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Node.js fs compatible API for object storage (MinIO/S3)",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/quick-test.js

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

package/samples/{fs-minio-test.js → fs-object-storage-test.js}

@@ -1,13 +1,12 @@
-// fs-minio-test.js - Test the fs-minio library implementation
+// fs-object-storage-test.js - Test the fs-object-storage library implementation
 
-import { FsMinioClient } from '../src/index.js';
-import path from 'path';
+import { ObjectStorage } from '../src/index.js';
 
-async function testFsMinioLibrary() {
-  console.log('🧪 Testing fs-minio library implementation...\n');
+async function testObjectStorageLibrary() {
+  console.log('🧪 Testing fs-object-storage library implementation...\n');
 
   // Create client instance
-  const client = new FsMinioClient({
+  const fs = new ObjectStorage({
     endpoint: 'localhost:9000',
     accessKey: 'minioadmin',
     secretKey: 'minioadmin123',
@@ -18,23 +17,23 @@ async function testFsMinioLibrary() {
 
   try {
     console.log('📝 Initializing client...');
-    await client.initialize();
+    await fs.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');
+    await fs.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');
+    const fileExists = await fs.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');
+    const readContent = await fs.readFile('/data/hello.txt', 'utf8');
     console.log(`✅ File content: "${readContent}"\n`);
     
     // Verify content matches
@@ -46,7 +45,7 @@ async function testFsMinioLibrary() {
 
     // Test 4: Get file stats
     console.log('📝 Test 4: stat()');
-    const stats = await client.stat('/data/hello.txt');
+    const stats = await fs.stat('/data/hello.txt');
     console.log('✅ File stats:');
     console.log(`   Size: ${stats.size} bytes`);
     console.log(`   Modified: ${stats.mtime}`);
@@ -56,29 +55,29 @@ async function testFsMinioLibrary() {
     // 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);
+    await fs.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');
+    const readBinary = await fs.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 });
+    await fs.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('/');
+    const rootFiles = await fs.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');
+      await fs.readFile('/nonexistent/file.txt');
       console.log('❌ Should have thrown error');
     } catch (error) {
       console.log(`✅ Correctly threw error: ${error.code} - ${error.message}\n`);
@@ -86,26 +85,23 @@ async function testFsMinioLibrary() {
 
     // Test 10: Delete file
     console.log('📝 Test 10: unlink()');
-    await client.unlink('/data/hello.txt');
+    await fs.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');
+    const fileExistsAfterDelete = await fs.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');
+    await fs.writeFile('/streams/test.txt', streamContent);
+    const readStream = await fs.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');
@@ -132,4 +128,4 @@ async function testFsMinioLibrary() {
 }
 
 // Run tests
-testFsMinioLibrary().catch(console.error);
+testObjectStorageLibrary().catch(console.error);

package/src/index.d.ts

@@ -1,6 +1,6 @@
 import { Readable, Writable } from 'stream';
 
-export interface MinioConfig {
+export interface Config {
   endPoint: string;
   port?: number;
   useSSL?: boolean;
@@ -41,8 +41,8 @@ export interface FileSystemError extends Error {
   syscall?: string;
 }
 
-export default class FsMinioClient {
-  constructor(config: MinioConfig);
+export default class ObjectStorage {
+  constructor(config: Config);
 
   // File operations
   readFile(path: string): Promise<Buffer>;
@@ -95,4 +95,4 @@ export class StreamConverter {
   static normalizeData(data: any): Buffer;
 }
 
-export default FsMinioClient;
+export default ObjectStorage;

package/src/index.js

@@ -1,17 +1,17 @@
-// fs-minio - fs-compatible API for MinIO/S3 object storage
+// fs-object-storage - fs-compatible API for MinIO/S3 object storage
 // Main entry point
 
-import FsMinioClient from './lib/FsMinioClient.js';
+import ObjectStorage from './lib/ObjectStorage.js';
 import PathConverter from './lib/PathConverter.js';
 import StreamConverter from './lib/StreamConverter.js';
 import ErrorHandler from './lib/ErrorHandler.js';
 
 export {
-  FsMinioClient,
+  ObjectStorage,
   PathConverter,
   StreamConverter,
   ErrorHandler
 };
 
 // Default export for convenience
-export default FsMinioClient;
+export default ObjectStorage;

package/src/lib/ErrorHandler.js

@@ -91,7 +91,7 @@ class ErrorHandler {
    * @param {string} operation - Operation name
    * @returns {Error} fs-compatible error
    */
-  static createError(code, path = null, operation = 'open') {
+  static createFileSystemError(code, path = null, operation = 'open') {
     // ENOENT, EACCES, EEXIST, EINVAL, ENAMETOOLONG など標準エラーコードにも対応
     let errorInfo = this.errorMapping[code];
     if (!errorInfo) {

package/src/lib/{FsMinioClient.js → ObjectStorage.js}

@@ -1,13 +1,13 @@
-// FsMinioClient.js - Main fs-compatible client for MinIO/S3 operations
+// ObjectStorage.js - Main fs-compatible client for MinIO/S3 operations
 
 import { Client as MinioClient } from 'minio';
 import PathConverter from './PathConverter.js';
 import StreamConverter from './StreamConverter.js';
 import ErrorHandler from './ErrorHandler.js';
 
-class FsMinioClient {
+class ObjectStorage {
   /**
-   * Create FsMinioClient instance
+   * Create ObjectStorage instance
    * @param {Object} options - Configuration options
    * @param {string} options.endpoint - MinIO endpoint (e.g., 'localhost:9000')
    * @param {string} options.accessKey - Access key
@@ -477,4 +477,4 @@ class FsMinioClient {
   }
 }
 
-export default FsMinioClient;
+export default ObjectStorage;