molex-ftp-client 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.2.1] - 2026-02-02
+
+### Changed
+- Improved README documentation
+  - Better examples for `ensureDir()`, `ensureParentDir()`, and `uploadFile()`
+  - Added architecture section explaining modular structure
+  - Enhanced feature list highlighting directory management capabilities
+  - Reorganized API documentation for better clarity
+
 ## [1.2.0] - 2026-02-02
 
 ### Changed

package/README.md

@@ -12,9 +12,11 @@ Lightweight FTP client built with native Node.js TCP sockets (net module).
 - ✅ **Configurable timeouts** - Prevent hanging connections
 - ✅ **Event-based** - Listen to FTP responses and events
 - ✅ **Upload/download** files with Buffer support
-- ✅ **Directory operations** (list, cd, mkdir, pwd)
+- ✅ **Smart directory management** - Auto-create nested directories
+- ✅ **Directory operations** (list, cd, mkdir, pwd, ensureDir)
 - ✅ **File operations** (delete, rename, size, exists, modifiedTime)
 - ✅ **Connection statistics** - Track command count and status
+- ✅ **Clean architecture** - Modular structure with separation of concerns
 
 ## Installation
 
@@ -113,6 +115,27 @@ await client.upload(buffer, '/path/file.bin');
 
 Returns: `Promise<void>`
 
+#### `uploadFile(data, remotePath, ensureDir)`
+
+Upload file and optionally ensure parent directory exists. This is the recommended method when uploading to deep paths.
+
+```javascript
+// Upload with automatic directory creation (recommended)
+await client.uploadFile('data', '/deep/nested/path/file.txt', true);
+
+// Upload without directory creation
+await client.uploadFile('data', '/file.txt', false);
+```
+
+**Parameters:**
+- `data` (string|Buffer): File content
+- `remotePath` (string): Remote file path
+- `ensureDir` (boolean): Create parent directories if needed (default: false)
+
+**Why use this?** Simplifies uploads to nested paths by automatically creating any missing parent directories.
+
+Returns: `Promise<void>`
+
 #### `download(remotePath)`
 
 Download file from server.
@@ -177,24 +200,6 @@ console.log(`Last modified: ${date.toISOString()}`);
 
 Returns: `Promise<Date>`
 
-#### `uploadFile(data, remotePath, ensureDir)`
-
-Upload file and optionally ensure parent directory exists.
-
-```javascript
-// Upload with automatic directory creation
-await client.uploadFile('data', '/deep/nested/path/file.txt', true);
-
-// Upload without directory creation (default behavior)
-await client.uploadFile('data', '/file.txt');
-```
-
-- `data` (string|Buffer): File content
-- `remotePath` (string): Remote file path
-- `ensureDir` (boolean): Create parent directories if needed (default: false)
-
-Returns: `Promise<void>`
-
 ### Directory Operations
 
 #### `list(path)`
@@ -241,31 +246,42 @@ Returns: `Promise<void>`
 
 #### `ensureDir(dirPath, recursive)`
 
-Ensure directory exists, creating it (and parent directories) if necessary.
+Ensure directory exists, creating it (and parent directories) if necessary. Idempotent - safe to call multiple times.
 
 ```javascript
-// Create nested directories recursively
+// Create nested directories recursively (default)
 await client.ensureDir('/deep/nested/path');
 
-// Create single directory (no parent creation)
+// Create single directory only (will fail if parent doesn't exist)
 await client.ensureDir('/newdir', false);
+
+// Idempotent - no error if directory already exists
+await client.ensureDir('/existing/path'); // No error
 ```
 
+**Parameters:**
 - `dirPath` (string): Directory path to ensure exists
 - `recursive` (boolean): Create parent directories if needed (default: true)
 
+**Use case:** Preparing directory structure before multiple file uploads.
+
 Returns: `Promise<void>`
 
 #### `ensureParentDir(filePath)`
 
-Ensure the parent directory exists for a given file path.
+Ensure the parent directory exists for a given file path. Recursively creates all missing parent directories.
 
 ```javascript
 // Ensures /path/to exists before uploading
 await client.ensureParentDir('/path/to/file.txt');
 await client.upload('data', '/path/to/file.txt');
+
+// Tip: Use uploadFile() instead for convenience
+await client.uploadFile('data', '/path/to/file.txt', true); // Equivalent
 ```
 
+**Use case:** Manual directory management before upload. Consider using `uploadFile()` with `ensureDir=true` for a simpler approach.
+
 Returns: `Promise<void>`
 
 ### Utilities
@@ -415,9 +431,9 @@ async function backupFile() {
       await client.rename('/backup/data.json', '/backup/data.old.json');
     }
 
-    // Upload new backup
+    // 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');
+    await client.uploadFile(newData, '/backup/data.json', true);
     console.log('Backup uploaded successfully');
 
     // Verify
@@ -439,6 +455,26 @@ async function backupFile() {
 backupFile();
 ```
 
+## Architecture
+
+The library is organized with clean separation of concerns:
+
+```
+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)
+```
+
+**Benefits:**
+- 📁 **Modular structure** - Easy to maintain and extend
+- 🔍 **Clear responsibilities** - Each file has a single purpose
+- 🧪 **Testable** - Isolated components for unit testing
+- 📖 **Readable** - Simple entry point with organized implementation
+
 ## License
 
 ISC © Tony Wiedman / MolexWorks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "molex-ftp-client",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Lightweight FTP client using native Node.js TCP sockets (net module) with zero dependencies",
   "main": "index.js",
   "scripts": {