molex-ftp-client 1.2.1 → 2.1.0

package/benchmark.js

@@ -0,0 +1,86 @@
+/**
+ * Performance benchmark for FTP client
+ * Compare different performance presets
+ */
+
+const FTPClient = require('./index.js');
+
+async function benchmark() {
+  const testData = 'x'.repeat(50000); // 50KB test data
+  const presets = ['DEFAULT', 'LOW_LATENCY', 'HIGH_THROUGHPUT', 'BALANCED'];
+  
+  console.log('\n=== FTP Client Performance Benchmark ===\n');
+  console.log('Test data size:', testData.length, 'bytes\n');
+
+  for (const preset of presets) {
+    console.log(`Testing ${preset} preset...`);
+    
+    const client = new FTPClient({
+      debug: false,
+      timeout: 60000,
+      performancePreset: preset
+    });
+
+    try {
+      // Connect
+      const connectStart = Date.now();
+      await client.connect({
+        host: 'ftp.example.com',
+        port: 21,
+        user: 'username',
+        password: 'password'
+      });
+      const connectTime = Date.now() - connectStart;
+
+      // Upload
+      const uploadStart = Date.now();
+      await client.upload(testData, '/benchmark-test.txt', true);
+      const uploadTime = Date.now() - uploadStart;
+
+      // Download
+      const downloadStart = Date.now();
+      const data = await client.download('/benchmark-test.txt');
+      const downloadTime = Date.now() - downloadStart;
+
+      // Cleanup
+      await client.delete('/benchmark-test.txt');
+      await client.close();
+
+      console.log(`  Connect:  ${connectTime}ms`);
+      console.log(`  Upload:   ${uploadTime}ms`);
+      console.log(`  Download: ${downloadTime}ms`);
+      console.log(`  Total:    ${connectTime + uploadTime + downloadTime}ms`);
+      console.log('');
+
+    } catch (err) {
+      console.error(`  Error: ${err.message}\n`);
+      await client.close();
+    }
+
+    // Wait between tests
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  console.log('=== Benchmark Complete ===\n');
+  console.log('Recommendation:');
+  console.log('  - Use LOW_LATENCY for small files (< 1MB)');
+  console.log('  - Use HIGH_THROUGHPUT for large files (> 10MB)');
+  console.log('  - Use BALANCED for mixed workloads\n');
+}
+
+// Only run if called directly
+if (require.main === module) {
+  console.log('\n⚠️  Update the benchmark() function with your FTP credentials to test.\n');
+  console.log('Example:');
+  console.log('  await client.connect({');
+  console.log('    host: "ftp.example.com",');
+  console.log('    port: 21,');
+  console.log('    user: "username",');
+  console.log('    password: "password"');
+  console.log('  });\n');
+  
+  // Uncomment to run benchmark:
+  // benchmark();
+}
+
+module.exports = benchmark;

package/lib/FTPClient.js

@@ -5,27 +5,29 @@ const FTPCommands = require('./commands');
 /**
  * Lightweight FTP Client using native Node.js TCP sockets (net module)
  */
-class FTPClient extends EventEmitter {
-  constructor(options = {}) {
+class FTPClient extends EventEmitter
+{
+  constructor(options = {})
+  {
     super();
-    
+
     // Connection state
     this.socket = null;
     this.dataSocket = null;
     this.buffer = '';
     this.connected = false;
     this.authenticated = false;
-    
+
     // Configuration
     this.debug = options.debug || false;
     this.timeout = options.timeout || 30000;
     this.keepAlive = options.keepAlive !== false;
     this._log = options.logger || console.log;
-    
+
     // Statistics
     this._commandCount = 0;
     this._lastCommand = null;
-    
+
     // Initialize subsystems
     this._connection = new FTPConnection(this);
     this._commands = new FTPCommands(this);
@@ -35,8 +37,10 @@ class FTPClient extends EventEmitter {
    * Log message if debug is enabled
    * @private
    */
-  _debug(...args) {
-    if (this.debug && this._log) {
+  _debug(...args)
+  {
+    if (this.debug && this._log)
+    {
       this._log('[FTP Debug]', ...args);
     }
   }
@@ -50,7 +54,12 @@ class FTPClient extends EventEmitter {
    * @param {string} [options.password='anonymous@'] - Password
    * @returns {Promise<void>}
    */
-  async connect(options) {
+  async connect(options)
+  {
+    if (!options || !options.host)
+    {
+      throw new Error('Connection options with host are required');
+    }
     return this._connection.connect(options);
   }
 
@@ -58,10 +67,20 @@ class FTPClient extends EventEmitter {
    * Upload file to FTP server
    * @param {string|Buffer} data - File data
    * @param {string} remotePath - Remote file path
+   * @param {boolean} ensureDir - Ensure parent directory exists (default: false)
    * @returns {Promise<void>}
    */
-  async upload(data, remotePath) {
-    return this._commands.upload(data, remotePath);
+  async upload(data, remotePath, ensureDir = false)
+  {
+    if (!data)
+    {
+      throw new Error('Data is required for upload');
+    }
+    if (!remotePath)
+    {
+      throw new Error('Remote path is required for upload');
+    }
+    return this._commands.upload(data, remotePath, ensureDir);
   }
 
   /**
@@ -69,16 +88,41 @@ class FTPClient extends EventEmitter {
    * @param {string} remotePath - Remote file path
    * @returns {Promise<Buffer>}
    */
-  async download(remotePath) {
+  async download(remotePath)
+  {
+    if (!remotePath)
+    {
+      throw new Error('Remote path is required for download');
+    }
     return this._commands.download(remotePath);
   }
 
+  /**
+   * Download file from FTP server as a stream (memory efficient for large files)
+   * @param {string} remotePath - Remote file path
+   * @param {Stream} writeStream - Writable stream to pipe data to
+   * @returns {Promise<number>} - Total bytes transferred
+   */
+  async downloadStream(remotePath, writeStream)
+  {
+    if (!remotePath)
+    {
+      throw new Error('Remote path is required for download');
+    }
+    if (!writeStream || typeof writeStream.write !== 'function')
+    {
+      throw new Error('Valid writable stream is required');
+    }
+    return this._commands.downloadStream(remotePath, writeStream);
+  }
+
   /**
    * List directory contents
    * @param {string} [path='.'] - Directory path
    * @returns {Promise<string>}
    */
-  async list(path = '.') {
+  async list(path = '.')
+  {
     return this._commands.list(path);
   }
 
@@ -87,7 +131,8 @@ class FTPClient extends EventEmitter {
    * @param {string} path - Directory path
    * @returns {Promise<void>}
    */
-  async cd(path) {
+  async cd(path)
+  {
     return this._commands.cd(path);
   }
 
@@ -95,7 +140,8 @@ class FTPClient extends EventEmitter {
    * Get current working directory
    * @returns {Promise<string>}
    */
-  async pwd() {
+  async pwd()
+  {
     return this._commands.pwd();
   }
 
@@ -104,7 +150,8 @@ class FTPClient extends EventEmitter {
    * @param {string} path - Directory path
    * @returns {Promise<void>}
    */
-  async mkdir(path) {
+  async mkdir(path)
+  {
     return this._commands.mkdir(path);
   }
 
@@ -113,7 +160,8 @@ class FTPClient extends EventEmitter {
    * @param {string} path - File path
    * @returns {Promise<void>}
    */
-  async delete(path) {
+  async delete(path)
+  {
     return this._commands.delete(path);
   }
 
@@ -123,7 +171,8 @@ class FTPClient extends EventEmitter {
    * @param {string} to - New name
    * @returns {Promise<void>}
    */
-  async rename(from, to) {
+  async rename(from, to)
+  {
     return this._commands.rename(from, to);
   }
 
@@ -132,7 +181,8 @@ class FTPClient extends EventEmitter {
    * @param {string} path - File path
    * @returns {Promise<number>}
    */
-  async size(path) {
+  async size(path)
+  {
     return this._commands.size(path);
   }
 
@@ -141,38 +191,31 @@ class FTPClient extends EventEmitter {
    * @param {string} path - File or directory path
    * @returns {Promise<boolean>}
    */
-  async exists(path) {
+  async exists(path)
+  {
     return this._commands.exists(path);
   }
 
   /**
-   * Ensure directory exists, creating it if necessary
-   * @param {string} dirPath - Directory path to ensure exists
-   * @param {boolean} recursive - Create parent directories if needed (default: true)
-   * @returns {Promise<void>}
-   */
-  async ensureDir(dirPath, recursive = true) {
-    return this._commands.ensureDir(dirPath, recursive);
-  }
-
-  /**
-   * Ensure parent directory exists for a file path
-   * @param {string} filePath - File path
-   * @returns {Promise<void>}
+   * Get file/directory information
+   * @param {string} path - Path to check
+   * @returns {Promise<Object>} - { exists, size, isFile, isDirectory }
    */
-  async ensureParentDir(filePath) {
-    return this._commands.ensureParentDir(filePath);
+  async stat(path)
+  {
+    return this._commands.stat(path);
   }
 
   /**
-   * Upload file and ensure parent directory exists
-   * @param {string|Buffer} data - File data
-   * @param {string} remotePath - Remote file path
-   * @param {boolean} ensureDir - Ensure parent directory exists (default: false)
+   * Ensure directory exists, creating it if necessary
+   * @param {string} dirPath - Directory or file path to ensure exists
+   * @param {boolean} recursive - Create parent directories if needed (default: true)
+   * @param {boolean} isFilePath - If true, ensures parent directory of file path (default: false)
    * @returns {Promise<void>}
    */
-  async uploadFile(data, remotePath, ensureDir = false) {
-    return this._commands.uploadFile(data, remotePath, ensureDir);
+  async ensureDir(dirPath, recursive = true, isFilePath = false)
+  {
+    return this._commands.ensureDir(dirPath, recursive, isFilePath);
   }
 
   /**
@@ -180,7 +223,8 @@ class FTPClient extends EventEmitter {
    * @param {string} path - File path
    * @returns {Promise<Date>}
    */
-  async modifiedTime(path) {
+  async modifiedTime(path)
+  {
     return this._commands.modifiedTime(path);
   }
 
@@ -188,7 +232,8 @@ class FTPClient extends EventEmitter {
    * Get connection statistics
    * @returns {Object}
    */
-  getStats() {
+  getStats()
+  {
     return {
       connected: this.connected,
       authenticated: this.authenticated,
@@ -197,11 +242,21 @@ class FTPClient extends EventEmitter {
     };
   }
 
+  /**
+   * Check if connected and authenticated
+   * @returns {boolean}
+   */
+  isConnected()
+  {
+    return this.connected && this.authenticated;
+  }
+
   /**
    * Enable or disable debug mode
    * @param {boolean} enabled - Enable debug mode
    */
-  setDebug(enabled) {
+  setDebug(enabled)
+  {
     this.debug = enabled;
     this._debug(`Debug mode ${enabled ? 'enabled' : 'disabled'}`);
   }
@@ -210,7 +265,8 @@ class FTPClient extends EventEmitter {
    * Close connection
    * @returns {Promise<void>}
    */
-  async close() {
+  async close()
+  {
     return this._connection.close();
   }
 
@@ -218,7 +274,8 @@ class FTPClient extends EventEmitter {
    * Disconnect (alias for close)
    * @returns {Promise<void>}
    */
-  async disconnect() {
+  async disconnect()
+  {
     return this.close();
   }
 }

package/lib/commands.js

@@ -1,5 +1,5 @@
-const net = require('net');
 const { normalizePath, getParentDir, parseMdtmResponse } = require('./utils');
+const { createOptimizedSocket } = require('./performance');
 
 /**
  * FTP command implementations
@@ -14,9 +14,16 @@ class FTPCommands {
    * Upload file to FTP server
    * @param {string|Buffer} data - File data
    * @param {string} remotePath - Remote file path
+   * @param {boolean} ensureDir - Ensure parent directory exists (default: false)
    * @returns {Promise<void>}
    */
-  async upload(data, remotePath) {
+  async upload(data, remotePath, ensureDir = false) {
+    if (!this.client.connected || !this.client.authenticated) {
+      throw new Error('Not connected to FTP server');
+    }
+    if (ensureDir) {
+      await this.ensureDir(remotePath, true, true);
+    }
     const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
     this.client._debug(`Uploading ${buffer.length} bytes to ${remotePath}`);
     const { host, port } = await this.connection.enterPassiveMode();
@@ -24,7 +31,7 @@ class FTPCommands {
     return new Promise((resolve, reject) => {
       let commandSent = false;
 
-      this.client.dataSocket = net.createConnection({ host, port }, () => {
+      this.client.dataSocket = createOptimizedSocket({ host, port }, () => {
         // Send STOR command to start upload (expects 150, then 226)
         if (!commandSent) {
           commandSent = true;
@@ -49,7 +56,7 @@ class FTPCommands {
             resolve();
           } else if (code >= 400) {
             this.client.removeListener('response', finalHandler);
-            reject(new Error(`FTP Error ${code}: ${line.substring(4)}`));
+            reject(new Error(`Upload failed - FTP Error ${code}: ${line.substring(4)} (path: ${remotePath})`));
           }
         };
         this.client.on('response', finalHandler);
@@ -58,7 +65,7 @@ class FTPCommands {
         setTimeout(() => {
           this.client.removeListener('response', finalHandler);
           resolve();
-        }, 5000);
+        }, this.client.timeout || 5000);
       });
     });
   }
@@ -69,6 +76,9 @@ class FTPCommands {
    * @returns {Promise<Buffer>}
    */
   async download(remotePath) {
+    if (!this.client.connected || !this.client.authenticated) {
+      throw new Error('Not connected to FTP server');
+    }
     this.client._debug(`Downloading ${remotePath}`);
     const { host, port } = await this.connection.enterPassiveMode();
 
@@ -76,7 +86,7 @@ class FTPCommands {
       const chunks = [];
       let commandSent = false;
 
-      this.client.dataSocket = net.createConnection({ host, port }, () => {
+      this.client.dataSocket = createOptimizedSocket({ host, port }, () => {
         // Send RETR command to start download (expects 150, then 226)
         if (!commandSent) {
           commandSent = true;
@@ -103,7 +113,7 @@ class FTPCommands {
             resolve(result);
           } else if (code >= 400) {
             this.client.removeListener('response', finalHandler);
-            reject(new Error(`FTP Error ${code}: ${line.substring(4)}`));
+            reject(new Error(`Download failed - FTP Error ${code}: ${line.substring(4)} (path: ${remotePath})`));
           }
         };
         this.client.on('response', finalHandler);
@@ -114,7 +124,75 @@ class FTPCommands {
           if (chunks.length > 0) {
             resolve(Buffer.concat(chunks));
           }
-        }, 5000);
+        }, this.client.timeout || 5000);
+      });
+    });
+  }
+
+  /**
+   * Download file from FTP server as a stream
+   * More memory efficient for large files
+   * @param {string} remotePath - Remote file path
+   * @param {Stream} writeStream - Writable stream to pipe data to
+   * @returns {Promise<number>} - Total bytes transferred
+   */
+  async downloadStream(remotePath, writeStream) {
+    if (!this.client.connected || !this.client.authenticated) {
+      throw new Error('Not connected to FTP server');
+    }
+    this.client._debug(`Streaming download: ${remotePath}`);
+    const { host, port } = await this.connection.enterPassiveMode();
+
+    return new Promise((resolve, reject) => {
+      let totalBytes = 0;
+      let commandSent = false;
+
+      this.client.dataSocket = createOptimizedSocket({ host, port }, () => {
+        if (!commandSent) {
+          commandSent = true;
+          this.client._debug(`Data connection established for streaming download`);
+          this.connection.sendCommand(`RETR ${remotePath}`, true).catch(reject);
+        }
+      });
+
+      this.client.dataSocket.on('data', (chunk) => {
+        totalBytes += chunk.length;
+        writeStream.write(chunk);
+      });
+
+      this.client.dataSocket.on('error', (err) => {
+        writeStream.end();
+        reject(err);
+      });
+
+      this.client.dataSocket.on('close', () => {
+        // Wait for final 226 response
+        const finalHandler = (line) => {
+          const code = parseInt(line.substring(0, 3));
+          if (code === 226 || code === 250) {
+            this.client.removeListener('response', finalHandler);
+            writeStream.end();
+            this.client._debug(`Streaming download completed: ${totalBytes} bytes`);
+            resolve(totalBytes);
+          } else if (code >= 400) {
+            this.client.removeListener('response', finalHandler);
+            writeStream.end();
+            reject(new Error(`Download failed - FTP Error ${code}: ${line.substring(4)} (path: ${remotePath})`));
+          }
+        };
+        this.client.on('response', finalHandler);
+        
+        // Timeout if no response
+        setTimeout(() => {
+          this.client.removeListener('response', finalHandler);
+          if (totalBytes > 0) {
+            writeStream.end();
+            resolve(totalBytes);
+          } else {
+            writeStream.end();
+            reject(new Error('Download timeout'));
+          }
+        }, this.client.timeout || 5000);
       });
     });
   }
@@ -132,7 +210,7 @@ class FTPCommands {
       const chunks = [];
       let commandSent = false;
 
-      this.client.dataSocket = net.createConnection({ host, port }, () => {
+      this.client.dataSocket = createOptimizedSocket({ host, port }, () => {
         if (!commandSent) {
           commandSent = true;
           this.connection.sendCommand(`LIST ${path}`, true).catch(reject);
@@ -160,7 +238,7 @@ class FTPCommands {
         setTimeout(() => {
           this.client.removeListener('response', finalHandler);
           resolve(Buffer.concat(chunks).toString('utf8'));
-        }, 3000);
+        }, this.client.timeout || 3000);
       });
     });
   }
@@ -219,7 +297,7 @@ class FTPCommands {
    * @returns {Promise<number>}
    */
   async size(path) {
-    this.client._debug(`Getting size of ${path}`)
+    this.client._debug(`Getting size of ${path}`);
     const response = await this.connection.sendCommand(`SIZE ${path}`);
     return parseInt(response.message);
   }
@@ -230,25 +308,61 @@ class FTPCommands {
    * @returns {Promise<boolean>}
    */
   async exists(path) {
+    const info = await this.stat(path);
+    return info.exists;
+  }
+
+  /**
+   * Get file/directory information
+   * @param {string} path - Path to check
+   * @returns {Promise<Object>} - { exists, size, isFile, isDirectory }
+   */
+  async stat(path) {
     try {
-      await this.size(path);
-      return true;
+      // First try SIZE command (works for files)
+      const size = await this.size(path);
+      return { exists: true, size, isFile: true, isDirectory: false };
     } catch (err) {
-      return false;
+      // SIZE failed, might be a directory - try CWD
+      try {
+        const currentDir = await this.pwd();
+        await this.cd(path);
+        // Restore original directory
+        await this.cd(currentDir);
+        return { exists: true, size: null, isFile: false, isDirectory: true };
+      } catch (cdErr) {
+        // Both SIZE and CWD failed - try listing parent directory
+        try {
+          const dir = getParentDir(path);
+          const basename = path.split('/').pop();
+          const listing = await this.list(dir);
+          const found = listing.split('\n').some(line => line.includes(basename));
+          return { exists: found, size: null, isFile: null, isDirectory: null };
+        } catch (listErr) {
+          return { exists: false, size: null, isFile: null, isDirectory: null };
+        }
+      }
     }
   }
 
   /**
    * Ensure directory exists, creating it if necessary
-   * @param {string} dirPath - Directory path to ensure exists
+   * @param {string} dirPath - Directory or file path to ensure exists
    * @param {boolean} recursive - Create parent directories if needed (default: true)
+   * @param {boolean} isFilePath - If true, ensures parent directory of file path (default: false)
    * @returns {Promise<void>}
    */
-  async ensureDir(dirPath, recursive = true) {
-    this.client._debug(`Ensuring directory exists: ${dirPath}`);
+  async ensureDir(dirPath, recursive = true, isFilePath = false) {
+    // If this is a file path, extract the parent directory
+    const targetPath = isFilePath ? getParentDir(dirPath) : dirPath;
+    if (!targetPath || targetPath === '.' || targetPath === '/') {
+      return; // Root or current directory always exists
+    }
+    
+    this.client._debug(`Ensuring directory exists: ${targetPath}`);
     
     // Normalize path
-    const normalized = normalizePath(dirPath);
+    const normalized = normalizePath(targetPath);
     if (normalized === '/' || normalized === '.') {
       return; // Root or current directory always exists
     }
@@ -282,32 +396,6 @@ class FTPCommands {
     }
   }
 
-  /**
-   * Ensure parent directory exists for a file path
-   * @param {string} filePath - File path
-   * @returns {Promise<void>}
-   */
-  async ensureParentDir(filePath) {
-    const parentDir = getParentDir(filePath);
-    if (parentDir && parentDir !== '.' && parentDir !== '/') {
-      await this.ensureDir(parentDir);
-    }
-  }
-
-  /**
-   * Upload file and ensure parent directory exists
-   * @param {string|Buffer} data - File data
-   * @param {string} remotePath - Remote file path
-   * @param {boolean} ensureDir - Ensure parent directory exists (default: false)
-   * @returns {Promise<void>}
-   */
-  async uploadFile(data, remotePath, ensureDir = false) {
-    if (ensureDir) {
-      await this.ensureParentDir(remotePath);
-    }
-    return this.upload(data, remotePath);
-  }
-
   /**
    * Get file modification time
    * @param {string} path - File path