fs-object-storage 1.0.0

package/src/lib/StreamConverter.js

@@ -0,0 +1,281 @@
+// StreamConverter.js - Convert between different stream/data formats for MinIO operations
+
+import { Readable, PassThrough } from 'stream';
+import { promisify } from 'util';
+import stream from 'stream';
+const pipeline = promisify(stream.pipeline);
+
+class StreamConverter {
+  /**
+   * Convert various data types to readable stream for MinIO upload
+   * @param {string|Buffer|Uint8Array|Readable} data - Data to convert
+   * @returns {Readable} Readable stream
+   */
+  static toReadableStream(data) {
+    if (data instanceof Readable) {
+      return data;
+    }
+    
+    if (typeof data === 'string') {
+      return Readable.from([Buffer.from(data, 'utf8')]);
+    }
+    
+    if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+      return Readable.from([data]);
+    }
+    
+    throw new Error('Unsupported data type for stream conversion');
+  }
+
+  /**
+   * Convert readable stream to buffer
+   * @param {Readable} stream - Readable stream
+   * @returns {Promise<Buffer>} Buffer containing all stream data
+   */
+  static async streamToBuffer(stream) {
+    const chunks = [];
+    
+    return new Promise((resolve, reject) => {
+      stream.on('data', (chunk) => {
+        chunks.push(chunk);
+      });
+      
+      stream.on('end', () => {
+        resolve(Buffer.concat(chunks));
+      });
+      
+      stream.on('error', (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * Convert readable stream to string
+   * @param {Readable} stream - Readable stream
+   * @param {string} [encoding='utf8'] - Text encoding
+   * @returns {Promise<string>} String containing all stream data
+   */
+  static async streamToString(stream, encoding = 'utf8') {
+    const buffer = await this.streamToBuffer(stream);
+    return buffer.toString(encoding);
+  }
+
+  /**
+   * Create a pass-through stream for piping operations
+   * @returns {PassThrough} PassThrough stream
+   */
+  static createPassThrough() {
+    return new PassThrough();
+  }
+
+  /**
+   * Get data size for Content-Length header
+   * @param {string|Buffer|Uint8Array|Readable} data - Data to measure
+   * @returns {number|undefined} Size in bytes, undefined if unknown (stream)
+   */
+  static getDataSize(data) {
+    if (typeof data === 'string') {
+      return Buffer.byteLength(data, 'utf8');
+    }
+    
+    if (Buffer.isBuffer(data)) {
+      return data.length;
+    }
+    
+    if (data instanceof Uint8Array) {
+      return data.byteLength;
+    }
+    
+    // For streams, size is unknown
+    if (data instanceof Readable) {
+      return undefined;
+    }
+    
+    throw new Error('Unsupported data type for size calculation');
+  }
+
+  /**
+   * Create readable stream from string with specified encoding
+   * @param {string} content - String content
+   * @param {string} [encoding='utf8'] - Text encoding
+   * @returns {Readable} Readable stream
+   */
+  static stringToStream(content, encoding = 'utf8') {
+    const buffer = Buffer.from(content, encoding);
+    return Readable.from([buffer]);
+  }
+
+  /**
+   * Create readable stream from buffer
+   * @param {Buffer} buffer - Buffer data
+   * @returns {Readable} Readable stream
+   */
+  static bufferToStream(buffer) {
+    return Readable.from([buffer]);
+  }
+
+  /**
+   * Pipe stream with error handling
+   * @param {Readable} source - Source stream
+   * @param {Writable} destination - Destination stream
+   * @returns {Promise<void>} Promise that resolves when piping is complete
+   */
+  static async pipeStream(source, destination) {
+    try {
+      await pipeline(source, destination);
+    } catch (error) {
+      throw new Error(`Stream pipeline failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Clone a readable stream (create multiple consumers)
+   * @param {Readable} source - Source stream
+   * @param {number} [count=2] - Number of clones to create
+   * @returns {Readable[]} Array of cloned streams
+   */
+  static cloneStream(source, count = 2) {
+    const streams = [];
+    
+    for (let i = 0; i < count; i++) {
+      streams.push(new PassThrough());
+    }
+    
+    source.on('data', (chunk) => {
+      streams.forEach(stream => stream.write(chunk));
+    });
+    
+    source.on('end', () => {
+      streams.forEach(stream => stream.end());
+    });
+    
+    source.on('error', (error) => {
+      streams.forEach(stream => stream.destroy(error));
+    });
+    
+    return streams;
+  }
+
+  /**
+   * Transform stream data with a function
+   * @param {Readable} source - Source stream
+   * @param {Function} transformer - Transform function (chunk) => transformedChunk
+   * @returns {Readable} Transformed stream
+   */
+  static transformStream(source, transformer) {
+    const passThrough = new PassThrough();
+    
+    source.on('data', (chunk) => {
+      try {
+        const transformed = transformer(chunk);
+        passThrough.write(transformed);
+      } catch (error) {
+        passThrough.destroy(error);
+      }
+    });
+    
+    source.on('end', () => {
+      passThrough.end();
+    });
+    
+    source.on('error', (error) => {
+      passThrough.destroy(error);
+    });
+    
+    return passThrough;
+  }
+
+  /**
+   * Limit stream size
+   * @param {Readable} source - Source stream
+   * @param {number} maxSize - Maximum size in bytes
+   * @returns {Readable} Size-limited stream
+   */
+  static limitStreamSize(source, maxSize) {
+    const passThrough = new PassThrough();
+    let totalSize = 0;
+    
+    source.on('data', (chunk) => {
+      totalSize += chunk.length;
+      
+      if (totalSize > maxSize) {
+        const error = new Error(`Stream size exceeds limit of ${maxSize} bytes`);
+        error.code = 'EFBIG';
+        passThrough.destroy(error);
+        return;
+      }
+      
+      passThrough.write(chunk);
+    });
+    
+    source.on('end', () => {
+      passThrough.end();
+    });
+    
+    source.on('error', (error) => {
+      passThrough.destroy(error);
+    });
+    
+    return passThrough;
+  }
+
+  /**
+   * Convert stream to async iterator
+   * @param {Readable} stream - Source stream
+   * @returns {AsyncIterable<Buffer>} Async iterable of chunks
+   */
+  static streamToAsyncIterable(stream) {
+    return {
+      [Symbol.asyncIterator]: async function* () {
+        let resolve, reject;
+        const chunks = [];
+        let finished = false;
+        
+        stream.on('readable', () => {
+          let chunk;
+          while (null !== (chunk = stream.read())) {
+            chunks.push(chunk);
+            if (resolve) {
+              resolve(chunk);
+              resolve = null;
+            }
+          }
+        });
+        
+        stream.on('end', () => {
+          finished = true;
+          if (resolve) {
+            resolve(null);
+            resolve = null;
+          }
+        });
+        
+        stream.on('error', (error) => {
+          if (reject) {
+            reject(error);
+            reject = null;
+          }
+        });
+        
+        while (true) {
+          if (chunks.length > 0) {
+            yield chunks.shift();
+          } else if (finished) {
+            break;
+          } else {
+            await new Promise((res, rej) => {
+              resolve = res;
+              reject = rej;
+            });
+            if (resolve === null && reject === null) {
+              break; // Stream ended
+            }
+          }
+        }
+      }
+    };
+  }
+}
+
+export default StreamConverter;

package/test-package.json

@@ -0,0 +1,9 @@
+{
+  "type": "module",
+  "scripts": {
+    "test": "node --test tests/unit/*.test.js",
+    "test:watch": "node --test --watch tests/unit/*.test.js",
+    "test:integration": "node samples/fs-minio-test.js",
+    "test:all": "npm run test && npm run test:integration"
+  }
+}

package/tests/unit/ErrorHandler.test.js

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for ErrorHandler
+ */
+import ErrorHandler from '../../src/lib/ErrorHandler.js';
+import { strict as assert } from 'assert';
+import { test, describe } from 'node:test';
+
+describe('ErrorHandler', () => {
+  describe('convertMinioError', () => {
+    test('should convert NoSuchKey error to ENOENT', () => {
+      const minioError = new Error('NoSuchKey: The specified key does not exist.');
+      minioError.code = 'NoSuchKey';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/test/file.txt');
+      
+      assert.strictEqual(fsError.code, 'ENOENT');
+      assert.strictEqual(fsError.errno, -2);
+      assert.strictEqual(fsError.path, '/test/file.txt');
+      assert.ok(fsError.message.includes('ENOENT'));
+    });
+
+    test('should convert NoSuchBucket error to ENOENT', () => {
+      const minioError = new Error('NoSuchBucket: The specified bucket does not exist.');
+      minioError.code = 'NoSuchBucket';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/bucket/file.txt');
+      
+      assert.strictEqual(fsError.code, 'ENOENT');
+      assert.strictEqual(fsError.errno, -2);
+    });
+
+    test('should convert AccessDenied error to EACCES', () => {
+      const minioError = new Error('AccessDenied: Access Denied.');
+      minioError.code = 'AccessDenied';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/test/file.txt');
+      
+      assert.strictEqual(fsError.code, 'EACCES');
+      assert.strictEqual(fsError.errno, -13);
+    });
+
+    test('should convert BucketAlreadyExists error to EEXIST', () => {
+      const minioError = new Error('BucketAlreadyExists: The requested bucket name is not available.');
+      minioError.code = 'BucketAlreadyExists';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/bucket');
+      
+      assert.strictEqual(fsError.code, 'EEXIST');
+      assert.strictEqual(fsError.errno, -17);
+    });
+
+    test('should handle unknown MinIO errors as generic errors', () => {
+      const minioError = new Error('UnknownError: Something went wrong.');
+      minioError.code = 'UnknownError';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/test/file.txt');
+      
+      assert.strictEqual(fsError.code, 'EUNKNOWN');
+      assert.strictEqual(fsError.errno, -1);
+    });
+
+    test('should handle errors without MinIO code', () => {
+      const genericError = new Error('Network error');
+      
+      const fsError = ErrorHandler.convertMinioError(genericError, '/test/file.txt');
+      
+      assert.strictEqual(fsError.code, 'EUNKNOWN');
+      assert.strictEqual(fsError.errno, -1);
+      assert.ok(fsError.message.includes('Network error'));
+    });
+
+    test('should preserve original stack trace', () => {
+      const minioError = new Error('Test error');
+      minioError.code = 'TestError';
+      
+      const fsError = ErrorHandler.convertMinioError(minioError, '/test');
+      
+      assert.ok(fsError.stack);
+      assert.ok(fsError.stack.includes('Test error'));
+    });
+  });
+
+  describe('createFileSystemError', () => {
+    test('should create ENOENT error correctly', () => {
+      const error = ErrorHandler.createFileSystemError('ENOENT', '/test/file.txt', 'open');
+      
+      assert.strictEqual(error.code, 'ENOENT');
+      assert.strictEqual(error.errno, -2);
+      assert.strictEqual(error.path, '/test/file.txt');
+      assert.strictEqual(error.syscall, 'open');
+      assert.ok(error.message.includes('ENOENT'));
+      assert.ok(error.message.includes('/test/file.txt'));
+    });
+
+    test('should create EACCES error correctly', () => {
+      const error = ErrorHandler.createFileSystemError('EACCES', '/test/file.txt', 'read');
+      
+      assert.strictEqual(error.code, 'EACCES');
+      assert.strictEqual(error.errno, -13);
+      assert.strictEqual(error.syscall, 'read');
+    });
+
+    test('should create EEXIST error correctly', () => {
+      const error = ErrorHandler.createFileSystemError('EEXIST', '/test/dir', 'mkdir');
+      
+      assert.strictEqual(error.code, 'EEXIST');
+      assert.strictEqual(error.errno, -17);
+    });
+
+    test('should handle unknown error codes', () => {
+      const error = ErrorHandler.createFileSystemError('UNKNOWN', '/test', 'test');
+      
+      assert.strictEqual(error.code, 'UNKNOWN');
+      assert.strictEqual(error.errno, -1);
+    });
+  });
+});

package/tests/unit/PathConverter.test.js

@@ -0,0 +1,224 @@
+/**
+ * Unit tests for PathConverter
+ */
+import PathConverter from '../../src/lib/PathConverter.js';
+import { strict as assert } from 'assert';
+
+describe('PathConverter', () => {
+  describe('splitPath', () => {
+    it('should split absolute path correctly', () => {
+      const result = PathConverter.splitPath('/bucket/path/to/file.txt');
+      
+      assert.strictEqual(result.bucket, 'bucket');
+      assert.strictEqual(result.key, 'path/to/file.txt');
+    });
+
+    it('should handle path without leading slash', () => {
+      const result = PathConverter.splitPath('bucket/path/to/file.txt');
+      
+      assert.strictEqual(result.bucket, 'bucket');
+      assert.strictEqual(result.key, 'path/to/file.txt');
+    });
+
+    it('should handle bucket-only path', () => {
+      const result = PathConverter.splitPath('/bucket');
+      
+      assert.strictEqual(result.bucket, 'bucket');
+      assert.strictEqual(result.key, '');
+    });
+
+    it('should handle bucket-only path without slash', () => {
+      const result = PathConverter.splitPath('bucket');
+      
+      assert.strictEqual(result.bucket, 'bucket');
+      assert.strictEqual(result.key, '');
+    });
+
+    it('should handle root path', () => {
+      const result = PathConverter.splitPath('/');
+      
+      assert.strictEqual(result.bucket, '');
+      assert.strictEqual(result.key, '');
+    });
+
+    it('should handle empty path', () => {
+      const result = PathConverter.splitPath('');
+      
+      assert.strictEqual(result.bucket, '');
+      assert.strictEqual(result.key, '');
+    });
+
+    it('should handle bucket with trailing slash', () => {
+      const result = PathConverter.splitPath('/bucket/');
+      
+      assert.strictEqual(result.bucket, 'bucket');
+      assert.strictEqual(result.key, '');
+    });
+
+    it('should handle nested directory structure', () => {
+      const result = PathConverter.splitPath('/mybucket/dir1/dir2/dir3/file.txt');
+      
+      assert.strictEqual(result.bucket, 'mybucket');
+      assert.strictEqual(result.key, 'dir1/dir2/dir3/file.txt');
+    });
+  });
+
+  describe('joinPath', () => {
+    it('should join bucket and key correctly', () => {
+      const result = PathConverter.joinPath('bucket', 'path/to/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/to/file.txt');
+    });
+
+    it('should handle empty key', () => {
+      const result = PathConverter.joinPath('bucket', '');
+      
+      assert.strictEqual(result, '/bucket');
+    });
+
+    it('should handle empty bucket', () => {
+      const result = PathConverter.joinPath('', 'path/to/file.txt');
+      
+      assert.strictEqual(result, '/path/to/file.txt');
+    });
+
+    it('should handle both empty', () => {
+      const result = PathConverter.joinPath('', '');
+      
+      assert.strictEqual(result, '/');
+    });
+
+    it('should remove leading slash from key', () => {
+      const result = PathConverter.joinPath('bucket', '/path/to/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/to/file.txt');
+    });
+
+    it('should handle complex paths', () => {
+      const result = PathConverter.joinPath('my-bucket', 'documents/2023/report.pdf');
+      
+      assert.strictEqual(result, '/my-bucket/documents/2023/report.pdf');
+    });
+  });
+
+  describe('normalizePath', () => {
+    it('should normalize standard path', () => {
+      const result = PathConverter.normalizePath('/bucket/path/to/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/to/file.txt');
+    });
+
+    it('should remove double slashes', () => {
+      const result = PathConverter.normalizePath('/bucket//path///to/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/to/file.txt');
+    });
+
+    it('should handle trailing slash', () => {
+      const result = PathConverter.normalizePath('/bucket/path/');
+      
+      assert.strictEqual(result, '/bucket/path');
+    });
+
+    it('should preserve root slash', () => {
+      const result = PathConverter.normalizePath('/');
+      
+      assert.strictEqual(result, '/');
+    });
+
+    it('should add leading slash if missing', () => {
+      const result = PathConverter.normalizePath('bucket/path/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/file.txt');
+    });
+
+    it('should handle empty string', () => {
+      const result = PathConverter.normalizePath('');
+      
+      assert.strictEqual(result, '/');
+    });
+
+    it('should handle relative path components', () => {
+      const result = PathConverter.normalizePath('/bucket/./path/../file.txt');
+      
+      assert.strictEqual(result, '/bucket/file.txt');
+    });
+  });
+
+  describe('isDirectory', () => {
+    it('should identify directory by trailing slash', () => {
+      assert.strictEqual(PathConverter.isDirectory('/bucket/path/'), true);
+    });
+
+    it('should identify file by no trailing slash', () => {
+      assert.strictEqual(PathConverter.isDirectory('/bucket/path/file.txt'), false);
+    });
+
+    it('should identify root as directory', () => {
+      assert.strictEqual(PathConverter.isDirectory('/'), true);
+    });
+
+    it('should identify bucket as directory', () => {
+      assert.strictEqual(PathConverter.isDirectory('/bucket'), false);
+      assert.strictEqual(PathConverter.isDirectory('/bucket/'), true);
+    });
+  });
+
+  describe('getParentPath', () => {
+    it('should get parent directory', () => {
+      const result = PathConverter.getParentPath('/bucket/path/to/file.txt');
+      
+      assert.strictEqual(result, '/bucket/path/to');
+    });
+
+    it('should get bucket for top-level file', () => {
+      const result = PathConverter.getParentPath('/bucket/file.txt');
+      
+      assert.strictEqual(result, '/bucket');
+    });
+
+    it('should get root for bucket', () => {
+      const result = PathConverter.getParentPath('/bucket');
+      
+      assert.strictEqual(result, '/');
+    });
+
+    it('should return root for root', () => {
+      const result = PathConverter.getParentPath('/');
+      
+      assert.strictEqual(result, '/');
+    });
+
+    it('should handle nested directories', () => {
+      const result = PathConverter.getParentPath('/bucket/dir1/dir2/dir3');
+      
+      assert.strictEqual(result, '/bucket/dir1/dir2');
+    });
+  });
+
+  describe('getBasename', () => {
+    it('should get filename', () => {
+      const result = PathConverter.getBasename('/bucket/path/to/file.txt');
+      
+      assert.strictEqual(result, 'file.txt');
+    });
+
+    it('should get directory name', () => {
+      const result = PathConverter.getBasename('/bucket/path/to/dir');
+      
+      assert.strictEqual(result, 'dir');
+    });
+
+    it('should get bucket name', () => {
+      const result = PathConverter.getBasename('/bucket');
+      
+      assert.strictEqual(result, 'bucket');
+    });
+
+    it('should return empty for root', () => {
+      const result = PathConverter.getBasename('/');
+      
+      assert.strictEqual(result, '');
+    });
+  });
+});