molex-ftp-client 2.0.0 → 2.2.0

package/README.md

@@ -1,28 +1,22 @@
 # molex-ftp-client
 
-Lightweight FTP client built with native Node.js TCP sockets (net module).
+[![npm version](https://img.shields.io/npm/v/molex-ftp-client.svg)](https://www.npmjs.com/package/molex-ftp-client)
+[![npm downloads](https://img.shields.io/npm/dm/molex-ftp-client.svg)](https://www.npmjs.com/package/molex-ftp-client)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14-brightgreen.svg)](https://nodejs.org)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
+
+> **Lightweight FTP client built with native Node.js TCP sockets. Zero dependencies, optimized for performance.**
 
 ## Features
 
-- ✅ **Zero dependencies** - Uses only native Node.js modules
-- ✅ **Promise-based API** - Modern async/await support
-- ✅ **Passive mode** (PASV) for data transfers
-- ✅ **Debug logging** - Optional verbose logging for troubleshooting
-- ✅ **Connection keep-alive** - Automatic TCP keep-alive
-- ✅ **Configurable timeouts** - Prevent hanging connections
-- ✅ **Event-based** - Listen to FTP responses and events
-- ✅ **Upload/download** files with Buffer support
-- ✅ **Smart directory management** - Auto-create nested directories
-- ✅ **Directory operations** (list, cd, mkdir, pwd, ensureDir)
-- ✅ **File operations** (delete, rename, size, exists, modifiedTime)
-- ✅ **Robust exists()** - Properly detects both files and directories
-- ✅ **Connection validation** - Automatic state checking before operations
-- ✅ **Enhanced error messages** - Include context for better debugging
-- ✅ **High-performance TCP** - Optimized socket settings (TCP_NODELAY, buffer tuning)
-- ✅ **Performance presets** - LOW_LATENCY, HIGH_THROUGHPUT, BALANCED modes
-- ✅ **Streaming downloads** - Memory-efficient for large files
-- ✅ **Connection statistics** - Track command count and status
-- ✅ **Clean architecture** - Modular structure with separation of concerns
+- **Zero dependencies** - Uses only native Node.js modules
+- **Promise-based API** - Modern async/await support
+- **TCP optimizations** - TCP_NODELAY and keep-alive applied by default (~2.5 MB/s transfer speeds)
+- **Auto-create directories** - Upload files to nested paths automatically
+- **Streaming support** - Memory-efficient downloads for large files
+- **Full FTP support** - Upload, download, list, delete, rename, chmod, stat, and more
+- **Debug mode** - See all FTP commands and responses in real-time
 
 ## Installation
 
@@ -35,384 +29,206 @@ npm install molex-ftp-client
 ```javascript
 const FTPClient = require('molex-ftp-client');
 
-const client = new FTPClient({
-  debug: true,           // Enable debug logging (default: false)
-  timeout: 30000,        // Command timeout in ms (default: 30000)
-  keepAlive: true        // Enable TCP keep-alive (default: true)
+const client = new FTPClient();
+
+await client.connect({
+  host: 'ftp.example.com',
+  user: 'username',
+  password: 'password'
 });
 
-try {
-  // Connect to FTP server
-  await client.connect({
-    host: 'ftp.example.com',
-    port: 21,
-    user: 'username',
-    password: 'password'
-  });
-
-  // Upload file
-  await client.upload('Hello World!', '/remote/path/file.txt');
-
-  // Download file
-  const data = await client.download('/remote/path/file.txt');
-  console.log(data.toString());
-
-  // Close connection
-  await client.close();
-} catch (err) {
-  console.error('FTP Error:', err);
-}
+// Upload with auto-directory creation
+await client.upload('Hello World!', '/path/to/file.txt', true);
+
+// Download
+const data = await client.download('/path/to/file.txt');
+console.log(data.toString());
+
+await client.close();
 ```
 
 ## Constructor Options
 
 ```javascript
 const client = new FTPClient({
-  debug: false,                      // Enable debug logging
-  timeout: 30000,                    // Command timeout in milliseconds
-  keepAlive: true,                   // Enable TCP keep-alive
-  logger: console.log,               // Custom logger function
-  performancePreset: 'BALANCED',     // Performance preset: LOW_LATENCY, HIGH_THROUGHPUT, BALANCED
-  performance: {                     // Custom performance tuning (overrides preset)
-    noDelay: true,                   // TCP_NODELAY - disable Nagle's algorithm
-    sendBufferSize: 65536,          // SO_SNDBUF in bytes
-    receiveBufferSize: 65536,       // SO_RCVBUF in bytes
-    keepAlive: true,                // TCP keep-alive
-    keepAliveDelay: 10000           // Keep-alive delay in ms
-  }
+  debug: false,       // Enable debug logging
+  timeout: 30000,     // Command timeout in milliseconds (default: 30000)
+  logger: console.log // Custom logger function
 });
 ```
 
-### Performance Presets
-
-Choose a preset based on your use case:
-
-- **`LOW_LATENCY`** - Optimized for small files and interactive operations (fastest response)
-- **`HIGH_THROUGHPUT`** - Optimized for large file transfers (maximum bandwidth)
-- **`BALANCED`** - Good default for most use cases (recommended)
-
-```javascript
-// For small files like privileges.xml
-const client = new FTPClient({ performancePreset: 'LOW_LATENCY' });
-
-// For large backups or video files
-const client = new FTPClient({ performancePreset: 'HIGH_THROUGHPUT' });
-```
-
-## API
+## API Reference
 
-### Connection
+### Connection Methods
 
 #### `connect(options)`
-
-Connect to FTP server.
-
 ```javascript
 await client.connect({
-  host: 'ftp.example.com',  // Required
-  port: 21,                  // Default: 21
-  user: 'username',          // Default: 'anonymous'
-  password: 'password'       // Default: 'anonymous@'
+  host: 'ftp.example.com',    // Required
+  port: 21,                    // Default: 21
+  user: 'username',            // Default: 'anonymous'
+  password: 'password'         // Default: 'anonymous@'
 });
 ```
 
-Returns: `Promise<void>`
-
-#### `close()` / `disconnect()`
-
-Close connection to FTP server.
-
+#### `close()`
 ```javascript
 await client.close();
 ```
 
-Returns: `Promise<void>`
-
-### File Operations
+### File Methods
 
 #### `upload(data, remotePath, ensureDir)`
-
-Upload file to server.
-
 ```javascript
-// Upload string
-await client.upload('Hello World!', '/path/file.txt');
-
-// Upload Buffer
-const buffer = Buffer.from('data');
-await client.upload(buffer, '/path/file.bin');
-
-// Upload with automatic directory creation (recommended for nested paths)
-await client.upload('data', '/deep/nested/path/file.txt', true);
+await client.upload('content', '/path/file.txt');           // Basic upload
+await client.upload(buffer, '/path/file.bin');              // Upload Buffer
+await client.upload('content', '/deep/path/file.txt', true); // Auto-create dirs
 ```
 
-**Parameters:**
-- `data` (string|Buffer): File content
-- `remotePath` (string): Remote file path
-- `ensureDir` (boolean): Create parent directories if needed (default: false)
-
-Returns: `Promise<void>`
-
-#### `download(remotePath)`
-
-Download file from server.
-
+#### `download(remotePath)` → `Buffer`
 ```javascript
 const data = await client.download('/path/file.txt');
-console.log(data.toString()); // Convert Buffer to string
 ```
 
-Returns: `Promise<Buffer>`
-
-#### `downloadStream(remotePath, writeStream)`
-
-Download file as a stream (memory efficient for large files).
-
+#### `downloadStream(remotePath, writeStream)` → `number`
+Stream download directly to a writable stream (for saving to disk or processing chunks).
 ```javascript
 const fs = require('fs');
-
-// Stream large file directly to disk
-const writeStream = fs.createWriteStream('./local-file.bin');
-const bytesTransferred = await client.downloadStream('/large-file.bin', writeStream);
-console.log(`Downloaded ${bytesTransferred} bytes`);
-
-// Stream to any writable stream
-const { PassThrough } = require('stream');
-const stream = new PassThrough();
-stream.on('data', (chunk) => {
-  console.log(`Received ${chunk.length} bytes`);
-});
-await client.downloadStream('/file.txt', stream);
+const fileStream = fs.createWriteStream('./local-file.bin');
+const bytes = await client.downloadStream('/remote.bin', fileStream);
+console.log(`Saved ${bytes} bytes to disk`);
 ```
 
-**Use this for:** Large files where you don't want to buffer everything in memory.
-
-Returns: `Promise<number>` - Total bytes transferred
-
 #### `delete(path)`
-
-Delete file.
-
 ```javascript
 await client.delete('/path/file.txt');
 ```
 
-Returns: `Promise<void>`
+#### `removeDir(path, recursive)`
+Remove directory, optionally with all contents.
+```javascript
+await client.removeDir('/path/emptydir');           // Remove empty directory
+await client.removeDir('/path/dir', true);          // Delete recursively with contents
+```
 
 #### `rename(from, to)`
-
-Rename or move file.
-
 ```javascript
-await client.rename('/old/path.txt', '/new/path.txt');
+await client.rename('/old.txt', '/new.txt');
 ```
 
-Returns: `Promise<void>`
-
-#### `size(path)`
-
-Get file size in bytes.
-
+#### `exists(path)` → `boolean`
 ```javascript
-const bytes = await client.size('/path/file.txt');
-console.log(`File size: ${bytes} bytes`);
+const exists = await client.exists('/path/file.txt');
 ```
 
-Returns: `Promise<number>`
-
-#### `exists(path)`
-
-Check if file or directory exists.
-
+#### `stat(path)` → `Object`
+Get detailed file/directory information.
 ```javascript
-const fileExists = await client.exists('/path/file.txt');
-console.log(fileExists ? 'File exists' : 'File not found');
-
-const dirExists = await client.exists('/path/to/directory');
-console.log(dirExists ? 'Directory exists' : 'Directory not found');
+const info = await client.stat('/path/file.txt');
+// { exists: true, size: 1024, isFile: true, isDirectory: false }
 ```
 
-Returns: `Promise<boolean>`
-
-#### `modifiedTime(path)`
-
-Get file modification time.
+#### `size(path)` → `number`
+```javascript
+const bytes = await client.size('/path/file.txt');
+```
 
+#### `modifiedTime(path)` → `Date`
 ```javascript
 const date = await client.modifiedTime('/path/file.txt');
-console.log(`Last modified: ${date.toISOString()}`);
 ```
 
-Returns: `Promise<Date>`
-
-### Directory Operations
-
-#### `list(path)`
-
-List directory contents.
-
+#### `chmod(path, mode)`
+Change file permissions (Unix/Linux servers only).
 ```javascript
-const listing = await client.list('/remote/path');
-console.log(listing);
+await client.chmod('/path/file.txt', '755');    // String format
+await client.chmod('/path/script.sh', 0755);    // Octal format
 ```
 
-Returns: `Promise<string>` - Raw directory listing
-
-#### `cd(path)`
-
-Change working directory.
+### Directory Methods
 
+#### `list(path)` → `string`
+Raw directory listing.
 ```javascript
-await client.cd('/remote/path');
+const listing = await client.list('/path');
 ```
 
-Returns: `Promise<void>`
-
-#### `pwd()`
-
-Get current working directory.
-
+#### `listDetailed(path)` → `Array`
+Parsed directory listing with permissions, owner, size, etc.
 ```javascript
-const dir = await client.pwd();
-console.log(`Current directory: ${dir}`);
+const files = await client.listDetailed('/path');
+// [
+//   { name: 'file.txt', type: 'file', permissions: '-rw-r--r--', 
+//     owner: 'user', group: 'group', size: 1024, date: 'Jan 15 10:30' },
+//   { name: 'subdir', type: 'directory', permissions: 'drwxr-xr-x', ... }
+// ]
 ```
 
-Returns: `Promise<string>`
-
 #### `mkdir(path)`
-
-Create directory.
-
 ```javascript
-await client.mkdir('/remote/newdir');
+await client.mkdir('/path/newdir');
 ```
 
-Returns: `Promise<void>`
-
-#### `ensureDir(dirPath, recursive, isFilePath)`
-
-Ensure directory exists, creating it (and parent directories) if necessary. Idempotent - safe to call multiple times.
-
+#### `cd(path)`
 ```javascript
-// Create nested directories recursively (default)
-await client.ensureDir('/deep/nested/path');
-
-// Create single directory only (will fail if parent doesn't exist)
-await client.ensureDir('/newdir', false);
-
-// Ensure parent directory for a file path
-await client.ensureDir('/path/to/file.txt', true, true);
-
-// Idempotent - no error if directory already exists
-await client.ensureDir('/existing/path'); // No error
+await client.cd('/path/to/directory');
 ```
 
-**Parameters:**
-- `dirPath` (string): Directory path or file path to ensure exists
-- `recursive` (boolean): Create parent directories if needed (default: true)
-- `isFilePath` (boolean): If true, ensures parent directory of file path (default: false)
-
-**Use case:** Preparing directory structure before multiple file uploads. For single file uploads, use `upload()` with `ensureDir=true`.
-
-Returns: `Promise<void>`
-
-### Utilities
-
-#### `isConnected()`
-
-Check if client is connected and authenticated.
-
+#### `pwd()` → `string`
 ```javascript
-if (client.isConnected()) {
-  console.log('Ready to execute commands');
-} else {
-  console.log('Not connected');
-}
+const currentDir = await client.pwd();
 ```
 
-Returns: `boolean`
-
-#### `getStats()`
+#### `ensureDir(dirPath, recursive, isFilePath)`
+Create directory if it doesn't exist, optionally creating parent directories.
+```javascript
+await client.ensureDir('/deep/nested/path');              // Create full path
+await client.ensureDir('/path/file.txt', true, true);     // Ensure parent dir for file
+```
 
-Get connection statistics.
+### Utility Methods
 
+#### `getState()` → `Object`
+Get current client state for debugging.
 ```javascript
-const stats = client.getStats();
-console.log(stats);
+const state = client.getState();
 // {
 //   connected: true,
 //   authenticated: true,
-//   commandCount: 5,
-//   lastCommand: 'LIST .'
+//   host: 'ftp.example.com',
+//   ...
 // }
 ```
 
-Returns: `Object`
-
 #### `setDebug(enabled)`
-
-Enable or disable debug mode at runtime.
-
+Toggle debug mode at runtime.
 ```javascript
-client.setDebug(true);  // Enable debug logging
-client.setDebug(false); // Disable debug logging
+client.setDebug(true);
 ```
 
-## Events
-
-The client extends EventEmitter and emits the following events:
-
-### `connected`
-
-Fired when TCP connection is established.
-
+#### `site(command)` → `Object`
+Execute server-specific SITE commands.
 ```javascript
-client.on('connected', () => {
-  console.log('Connected to FTP server');
-});
+await client.site('CHMOD 755 /path/file.txt');  // Alternative chmod
+const response = await client.site('HELP');      // Get server help
 ```
 
-### `response`
-
-Fired for each FTP response (useful for debugging).
-
-```javascript
-client.on('response', (line) => {
-  console.log('FTP:', line);
-});
-```
-
-### `error`
-
-Fired on connection errors.
+## Events
 
 ```javascript
-client.on('error', (err) => {
-  console.error('FTP Error:', err);
-});
+client.on('connected', () => console.log('TCP connection established'));
+client.on('response', (line) => console.log('FTP:', line));
+client.on('error', (err) => console.error('Error:', err));
+client.on('close', () => console.log('Connection closed'));
 ```
 
-### `close`
+## Debugging
 
-Fired when connection is closed.
-
-```javascript
-client.on('close', () => {
-  console.log('Connection closed');
-});
-```
-
-## Debug Mode
-
-Enable debug logging to troubleshoot FTP issues:
+Enable debug mode to see all FTP commands and responses:
 
 ```javascript
 const client = new FTPClient({ debug: true });
 
-client.on('response', (line) => {
-  console.log('FTP Response:', line);
-});
-
 await client.connect({ host: 'ftp.example.com', user: 'user', password: 'pass' });
 // [FTP Debug] Connecting to ftp.example.com:21 as user
 // [FTP Debug] TCP connection established
@@ -421,147 +237,72 @@ await client.connect({ host: 'ftp.example.com', user: 'user', password: 'pass' }
 // [FTP Debug] <<< 331 Password required
 // [FTP Debug] >>> PASS ********
 // [FTP Debug] <<< 230 Login successful
-// [FTP Debug] Authentication successful
 ```
 
-## Performance Optimization
-
-This library implements TCP-level optimizations:
-
-### TCP_NODELAY (Nagle's Algorithm)
-
-By default, the client uses `TCP_NODELAY` which disables Nagle's algorithm. This reduces latency by sending packets immediately instead of buffering them.
-
-**When to use:**
-- Small file transfers
-- Interactive operations
-- When latency matters more than bandwidth
-
-**Trade-off:** Slightly more network overhead, but much faster response times.
+## Performance
 
-### Buffer Sizing
+TCP optimizations are automatically applied:
+- **TCP_NODELAY** - Disables Nagle's algorithm for lower latency
+- **Keep-alive** - Detects dead connections (10s interval)
 
-The client optimizes socket buffers based on your use case:
+**Typical transfer speeds:** ~2.5 MB/s for 1MB files over standard internet connections.
 
-```javascript
-// Low latency (32KB buffers) - fast for small files
-const client = new FTPClient({ performancePreset: 'LOW_LATENCY' });
-
-// High throughput (128KB buffers) - better for large files
-const client = new FTPClient({ performancePreset: 'HIGH_THROUGHPUT' });
-```
-
-### Streaming for Large Files
-
-Use `downloadStream()` for memory-efficient transfers:
+For large files, use `downloadStream()` to save directly to disk without buffering in memory:
 
 ```javascript
 const fs = require('fs');
-const writeStream = fs.createWriteStream('./large-backup.zip');
-await client.downloadStream('/backup.zip', writeStream);
+const fileStream = fs.createWriteStream('./large-backup.zip');
+const bytes = await client.downloadStream('/backup.zip', fileStream);
+console.log(`Saved ${bytes} bytes to disk`);
 ```
 
-**Benefits:**
-- Constant memory usage (no buffering entire file)
-- Start processing data before download completes
-- Better for files > 10MB
-
-### Performance Comparison
-
-For a typical privileges.xml (< 100KB):
-- **Without optimization:** ~150-200ms
-- **With LOW_LATENCY preset:** ~80-120ms
-- **40-50% faster** response time
-
 ## Error Handling
 
-All methods return promises and will reject on errors:
-
 ```javascript
 try {
   await client.upload('data', '/readonly/file.txt');
 } catch (err) {
   if (err.message.includes('FTP Error 550')) {
     console.error('Permission denied');
-  } else {
-    console.error('Upload failed:', err.message);
   }
 }
 ```
 
-## Complete Example
+## Example
 
 ```javascript
 const FTPClient = require('molex-ftp-client');
 
-async function backupFile() {
-  const client = new FTPClient({ 
-    debug: true,
-    timeout: 60000 
-  });
+async function main() {
+  const client = new FTPClient({ debug: true });
 
   try {
-    // Connect
     await client.connect({
-      host: 'ftp.myserver.com',
-      port: 21,
+      host: 'ftp.example.com',
       user: 'admin',
-      password: 'secret123'
+      password: 'secret'
     });
 
-    console.log('Current directory:', await client.pwd());
-
-    // Check if file exists
-    const exists = await client.exists('/backup/data.json');
-    if (exists) {
-      // Download existing file
-      const oldData = await client.download('/backup/data.json');
-      console.log('Old backup size:', oldData.length, 'bytes');
-      
-      // Get modification time
-      const modTime = await client.modifiedTime('/backup/data.json');
-      console.log('Last modified:', modTime.toISOString());
-      
-      // Rename old backup
-      await client.rename('/backup/data.json', '/backup/data.old.json');
+    // Check file info
+    const info = await client.stat('/backup/data.json');
+    if (info.exists) {
+      console.log(`File size: ${info.size} bytes`);
+      const data = await client.download('/backup/data.json');
+      console.log('Downloaded:', data.toString());
     }
 
-    // Upload new backup (with automatic directory creation)
-    const newData = JSON.stringify({ timestamp: Date.now(), data: [1, 2, 3] });
-    await client.upload(newData, '/backup/data.json', true);
-    console.log('Backup uploaded successfully');
-
-    // Verify
-    const size = await client.size('/backup/data.json');
-    console.log('New backup size:', size, 'bytes');
-
-    // Get stats
-    const stats = client.getStats();
-    console.log('Commands executed:', stats.commandCount);
-
-    // Close connection
+    // Upload new file
+    await client.upload('new data', '/backup/updated.json', true);
+    
     await client.close();
   } catch (err) {
-    console.error('Backup failed:', err.message);
-    await client.close();
+    console.error('FTP Error:', err.message);
   }
 }
 
-backupFile();
+main();
 ```
 
-## Architecture
-
-```
-molex-ftp-client/
-├── index.js           # Entry point - exports FTPClient
-├── lib/
-│   ├── FTPClient.js   # Main class definition & public API
-│   ├── connection.js  # Connection & authentication logic
-│   ├── commands.js    # FTP command implementations
-│   └── utils.js       # Helper functions (parsing, paths)
-```
 ## License
 
-ISC © Tony Wiedman / MolexWorks
-
+ISC License