filepilot 1.0.1

package/index.js

@@ -0,0 +1,307 @@
+// index.js
+const fs = require("node:fs");
+const path = require("node:path");
+const { promisify } = require("node:util");
+
+// Convert callback-based methods to Promise-based
+const readFileAsync = promisify(fs.readFile);
+const writeFileAsync = promisify(fs.writeFile);
+const appendFileAsync = promisify(fs.appendFile);
+const unlinkAsync = promisify(fs.unlink);
+const mkdirAsync = promisify(fs.mkdir);
+const readdirAsync = promisify(fs.readdir);
+
+class FileHelper {
+  /**
+   * Read file synchronously
+   * @param {string} file - File path
+   * @param {string} encoding - File encoding (default: 'utf8')
+   * @returns {string|Buffer} File content
+   * @throws {Error} If file not found or other errors
+   */
+  static readSync(file, encoding = "utf8") {
+    try {
+      const content = fs.readFileSync(file, { encoding });
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to read file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Read file asynchronously with Promise
+   * @param {string} file - File path
+   * @param {string} encoding - File encoding (default: 'utf8')
+   * @returns {Promise<string|Buffer>} File content
+   */
+  static async read(file, encoding = "utf8") {
+    try {
+      const content = await readFileAsync(file, { encoding });
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to read file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Read file as stream
+   * @param {string} file - File path
+   * @param {Object} options - Stream options
+   * @returns {Promise<string>} File content as string
+   */
+  static async readStream(file, options = {}) {
+    return new Promise((resolve, reject) => {
+      let data = "";
+      const stream = fs.createReadStream(file, {
+        encoding: options.encoding || "utf8",
+        highWaterMark: options.highWaterMark || 64 * 1024,
+        ...options,
+      });
+
+      stream.on("data", (chunk) => {
+        data += chunk;
+        if (options.onChunk) options.onChunk(chunk);
+      });
+
+      stream.on("end", () => resolve(data));
+      stream.on("error", (err) => reject(new Error(`Stream error: ${err.message}`)));
+    });
+  }
+
+  /**
+   * Read file line by line
+   * @param {string} file - File path
+   * @param {Function} lineHandler - Callback for each line
+   * @returns {Promise<number>} Number of lines read
+   */
+  static async readLines(file, lineHandler, encoding = "utf8") {
+    try {
+      const content = await this.read(file, encoding);
+      const lines = content.split(/\r?\n/);
+      
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i]) {
+          await lineHandler(lines[i], i + 1);
+        }
+      }
+      return lines.filter(line => line).length;
+    } catch (error) {
+      throw new Error(`Failed to read lines from ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Write file synchronously
+   * @param {string} file - File path
+   * @param {string|Buffer} data - Data to write
+   * @param {Object} options - Write options
+   * @returns {boolean} Success status
+   */
+  static writeSync(file, data, options = {}) {
+    try {
+      fs.writeFileSync(file, data, {
+        encoding: options.encoding || "utf8",
+        mode: options.mode || 0o666,
+        ...options,
+      });
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to write file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Write file asynchronously
+   * @param {string} file - File path
+   * @param {string|Buffer} data - Data to write
+   * @param {Object} options - Write options
+   * @returns {Promise<boolean>} Success status
+   */
+  static async write(file, data, options = {}) {
+    try {
+      await writeFileAsync(file, data, {
+        encoding: options.encoding || "utf8",
+        mode: options.mode || 0o666,
+        ...options,
+      });
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to write file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Append content to file
+   * @param {string} file - File path
+   * @param {string|Buffer} data - Data to append
+   * @returns {Promise<boolean>} Success status
+   */
+  static async append(file, data, encoding = "utf8") {
+    try {
+      await appendFileAsync(file, data, { encoding });
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to append to file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if file exists
+   * @param {string} file - File path
+   * @returns {boolean} File existence
+   */
+  static existsSync(file) {
+    try {
+      return fs.existsSync(file);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Async file existence check
+   * @param {string} file - File path
+   * @returns {Promise<boolean>} File existence
+   */
+  static async exists(file) {
+    try {
+      await fs.promises.access(file, fs.constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get file stats
+   * @param {string} file - File path
+   * @returns {Promise<fs.Stats>} File stats
+   */
+  static async stats(file) {
+    try {
+      return await fs.promises.stat(file);
+    } catch (error) {
+      throw new Error(`Failed to get stats for ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete file
+   * @param {string} file - File path
+   * @returns {Promise<boolean>} Success status
+   */
+  static async delete(file) {
+    try {
+      await unlinkAsync(file);
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to delete file ${file}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Copy file
+   * @param {string} source - Source file path
+   * @param {string} destination - Destination file path
+   * @returns {Promise<boolean>} Success status
+   */
+  static async copy(source, destination) {
+    try {
+      await fs.promises.copyFile(source, destination);
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to copy from ${source} to ${destination}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Move/rename file
+   * @param {string} source - Source file path
+   * @param {string} destination - Destination file path
+   * @returns {Promise<boolean>} Success status
+   */
+  static async move(source, destination) {
+    try {
+      await fs.promises.rename(source, destination);
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to move from ${source} to ${destination}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create directory recursively
+   * @param {string} dir - Directory path
+   * @returns {Promise<boolean>} Success status
+   */
+  static async createDirectory(dir) {
+    try {
+      await mkdirAsync(dir, { recursive: true });
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to create directory ${dir}: ${error.message}`);
+    }
+  }
+
+  /**
+   * List directory contents
+   * @param {string} dir - Directory path
+   * @param {Object} options - Options (withFileTypes, etc.)
+   * @returns {Promise<string[]|fs.Dirent[]>} Directory contents
+   */
+  static async listDirectory(dir, options = {}) {
+    try {
+      return await readdirAsync(dir, options);
+    } catch (error) {
+      throw new Error(`Failed to list directory ${dir}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Watch file for changes
+   * @param {string} file - File path
+   * @param {Function} callback - Change handler
+   * @param {Object} options - Watch options
+   * @returns {fs.FSWatcher} Watcher instance
+   */
+  static watch(file, callback, options = {}) {
+    const watcher = fs.watch(file, options, (eventType, filename) => {
+      if (eventType === "change") {
+        callback(eventType, filename);
+      }
+    });
+    return watcher;
+  }
+}
+
+// For backward compatibility
+function ReadFile(file) {
+  return FileHelper.readSync(file);
+}
+
+function ReadStream(file) {
+  return FileHelper.readStream(file);
+}
+
+module.exports = {
+  FileHelper,
+  readSync: FileHelper.readSync,
+  read: FileHelper.read,
+  readStream: FileHelper.readStream,
+  readLines: FileHelper.readLines,
+  writeSync: FileHelper.writeSync,
+  write: FileHelper.write,
+  append: FileHelper.append,
+  existsSync: FileHelper.existsSync,
+  exists: FileHelper.exists,
+  stats: FileHelper.stats,
+  delete: FileHelper.delete,
+  copy: FileHelper.copy,
+  move: FileHelper.move,
+  createDirectory: FileHelper.createDirectory,
+  listDirectory: FileHelper.listDirectory,
+  watch: FileHelper.watch,
+  // Legacy support
+  ReadFile,
+  ReadStream,
+};

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "filepilot",
+  "version": "1.0.1",
+  "description": "A powerful, developer-friendly file system module for reading, writing, and managing files with ease",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint index.js",
+    "lint:fix": "eslint index.js --fix",
+    "docs": "jsdoc -c jsdoc.json",
+    "format": "prettier --write index.js"
+  },
+  "peerDependencies": {
+    "node": ">=14.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heroboyCloud/filepilot.git"
+  },
+  "homepage": "https://github.com/heroboyCloud/filepilot#readme",
+  "bugs": {
+    "url": "https://github.com/heroboyCloud/filepilot/issues"
+  },
+  "keywords": [
+    "fs",
+    "file-system",
+    "read",
+    "write",
+    "file",
+    "simple",
+    "sync",
+    "async",
+    "stream",
+    "watch",
+    "copy",
+    "move",
+    "delete",
+    "directory",
+    "utility",
+    "files",
+    "io",
+    "file-manager"
+  ],
+  "author": {
+    "name": "Akindele Azeez",
+    "email": "shakiratakindel@gmail.com",
+    "url": "https://github.com/heroboyCloud"
+  },
+  "license": "MIT",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/heroboyCloud"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "eslintConfig": {
+    "env": {
+      "node": true,
+      "es2021": true
+    },
+    "extends": [
+      "eslint:recommended",
+      "prettier"
+    ],
+    "parserOptions": {
+      "ecmaVersion": 2021,
+      "sourceType": "module"
+    },
+    "rules": {
+      "no-console": "off",
+      "no-unused-vars": [
+        "error",
+        {
+          "argsIgnorePattern": "^_"
+        }
+      ]
+    }
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "coveragePathIgnorePatterns": [
+      "/node_modules/",
+      "/tests/"
+    ],
+    "collectCoverageFrom": [
+      "index.js"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  },
+  "prettier": {
+    "semi": true,
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "printWidth": 100
+  }
+}

package/readme.md

@@ -0,0 +1,429 @@
+📁 Easy File Reader
+
+A powerful, developer-friendly Node.js module for seamless file operations with both synchronous and asynchronous support.
+
+https://img.shields.io/npm/v/easy-file-reader.svg
+https://img.shields.io/npm/dm/easy-file-reader.svg
+https://img.shields.io/node/v/easy-file-reader.svg
+https://img.shields.io/badge/License-MIT-yellow.svg
+
+✨ Features
+
+· 🚀 Simple & Intuitive API - Easy to learn and use
+· 📖 Multiple Reading Methods - Sync, Async, Stream, and Line-by-Line
+· ✍️ Complete File Operations - Read, Write, Append, Copy, Move, Delete
+· 📂 Directory Management - Create, list, and manage directories
+· 🔄 Stream Support - Handle large files efficiently
+· 👁️ File Watching - Monitor file changes in real-time
+· 🛡️ Robust Error Handling - Descriptive error messages
+· 🎯 Promise-based - Modern async/await support
+· 🔧 Flexible Options - Custom encoding, permissions, and more
+· 📦 Zero Dependencies - Uses only Node.js built-in modules
+
+📦 Installation
+
+```bash
+npm install easy-file-reader
+```
+
+or
+
+```bash
+yarn add easy-file-reader
+```
+
+🚀 Quick Start
+
+```javascript
+const { read, write, readLines, watch } = require('easy-file-reader');
+
+// Async/Await - Modern approach
+async function example() {
+  try {
+    // Read a file
+    const content = await read('example.txt');
+    console.log(content);
+    
+    // Write a file
+    await write('output.txt', 'Hello World!');
+    
+    // Read lines
+    await readLines('log.txt', (line, num) => {
+      console.log(`Line ${num}: ${line}`);
+    });
+    
+    // Watch for changes
+    const watcher = watch('config.json', (event, filename) => {
+      console.log(`${filename} changed!`);
+    });
+    
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+📚 API Reference
+
+Reading Files
+
+read(filePath, encoding = 'utf8')
+
+Asynchronously reads a file and returns its content.
+
+```javascript
+const content = await read('data.txt');
+const buffer = await read('image.png', null); // Returns Buffer
+```
+
+readSync(filePath, encoding = 'utf8')
+
+Synchronously reads a file.
+
+```javascript
+const content = readSync('data.txt');
+```
+
+readStream(filePath, options = {})
+
+Reads a file as a stream, perfect for large files.
+
+```javascript
+const content = await readStream('large-file.log', {
+  encoding: 'utf8',
+  highWaterMark: 1024 * 1024, // 1MB chunks
+  onChunk: (chunk) => console.log('Received chunk:', chunk.length)
+});
+```
+
+readLines(filePath, lineHandler, encoding = 'utf8')
+
+Reads a file line by line with a callback.
+
+```javascript
+const lineCount = await readLines('data.csv', (line, number) => {
+  const [name, email] = line.split(',');
+  console.log(`User ${number}: ${name} - ${email}`);
+});
+```
+
+Writing Files
+
+write(filePath, data, options = {})
+
+Asynchronously writes data to a file.
+
+```javascript
+await write('output.txt', 'Hello World', {
+  encoding: 'utf8',
+  mode: 0o644 // File permissions
+});
+```
+
+writeSync(filePath, data, options = {})
+
+Synchronously writes data to a file.
+
+```javascript
+writeSync('output.txt', 'Hello World');
+```
+
+append(filePath, data, encoding = 'utf8')
+
+Appends data to an existing file.
+
+```javascript
+await append('log.txt', 'New log entry\n');
+```
+
+File Operations
+
+copy(source, destination)
+
+Copies a file from source to destination.
+
+```javascript
+await copy('source.txt', 'backup.txt');
+```
+
+move(source, destination)
+
+Moves or renames a file.
+
+```javascript
+await move('old-name.txt', 'new-name.txt');
+```
+
+delete(filePath)
+
+Deletes a file.
+
+```javascript
+await delete('temp-file.txt');
+```
+
+exists(filePath)
+
+Checks if a file exists (async).
+
+```javascript
+if (await exists('config.json')) {
+  // File exists
+}
+```
+
+existsSync(filePath)
+
+Synchronously checks if a file exists.
+
+```javascript
+if (existsSync('config.json')) {
+  // File exists
+}
+```
+
+stats(filePath)
+
+Gets file statistics.
+
+```javascript
+const stats = await stats('file.txt');
+console.log(`Size: ${stats.size} bytes`);
+console.log(`Modified: ${stats.mtime}`);
+```
+
+Directory Operations
+
+createDirectory(dirPath)
+
+Creates a directory (recursively).
+
+```javascript
+await createDirectory('project/src/components');
+```
+
+listDirectory(dirPath, options = {})
+
+Lists directory contents.
+
+```javascript
+const files = await listDirectory('project');
+console.log(files);
+
+// With file types
+const entries = await listDirectory('project', { withFileTypes: true });
+entries.forEach(entry => {
+  console.log(`${entry.name} (${entry.isDirectory() ? 'dir' : 'file'})`);
+});
+```
+
+File Watching
+
+watch(filePath, callback, options = {})
+
+Watches a file for changes and executes callback.
+
+```javascript
+const watcher = watch('config.json', (event, filename) => {
+  console.log(`${filename} changed!`);
+  // Reload configuration
+}, { persistent: true });
+
+// Stop watching
+watcher.close();
+```
+
+Legacy Support
+
+For backward compatibility with your original API:
+
+```javascript
+const { ReadFile, ReadStream } = require('easy-file-reader');
+
+// Sync read
+const content = ReadFile('file.txt');
+
+// Stream read (returns string)
+ReadStream('file.txt').then(content => console.log(content));
+```
+
+💡 Advanced Examples
+
+Processing Large CSV Files
+
+```javascript
+const { readLines } = require('easy-file-reader');
+
+async function processLargeCSV() {
+  let total = 0;
+  await readLines('large-dataset.csv', (line, num) => {
+    // Skip header
+    if (num === 1) return;
+    
+    const [id, name, value] = line.split(',');
+    total += parseFloat(value);
+    
+    if (num % 1000 === 0) {
+      console.log(`Processed ${num} rows...`);
+    }
+  });
+  console.log(`Total: ${total}`);
+}
+```
+
+Config File with Watching
+
+```javascript
+const { read, watch } = require('easy-file-reader');
+
+class ConfigManager {
+  constructor(configPath) {
+    this.configPath = configPath;
+    this.config = null;
+    this.watcher = null;
+    this.listeners = [];
+  }
+  
+  async load() {
+    try {
+      const data = await read(this.configPath);
+      this.config = JSON.parse(data);
+      this.notifyListeners();
+      return this.config;
+    } catch (error) {
+      console.error('Failed to load config:', error.message);
+    }
+  }
+  
+  watch(autoReload = true) {
+    this.watcher = watch(this.configPath, async () => {
+      if (autoReload) {
+        console.log('Config changed, reloading...');
+        await this.load();
+      }
+    });
+  }
+  
+  onReload(callback) {
+    this.listeners.push(callback);
+  }
+  
+  notifyListeners() {
+    this.listeners.forEach(cb => cb(this.config));
+  }
+  
+  stopWatching() {
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+}
+
+// Usage
+const config = new ConfigManager('app-config.json');
+await config.load();
+config.onReload((newConfig) => console.log('Config updated:', newConfig));
+config.watch();
+```
+
+Backup System
+
+```javascript
+const { copy, read, write, stats, listDirectory } = require('easy-file-reader');
+
+async function createBackup(sourceDir, backupDir) {
+  // Create backup directory with timestamp
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${backupDir}/backup-${timestamp}`;
+  await createDirectory(backupPath);
+  
+  // Get all files
+  const files = await listDirectory(sourceDir);
+  const results = [];
+  
+  for (const file of files) {
+    const sourceFile = `${sourceDir}/${file}`;
+    const destFile = `${backupPath}/${file}`;
+    
+    // Get file stats
+    const fileStats = await stats(sourceFile);
+    
+    // Copy file
+    await copy(sourceFile, destFile);
+    results.push({
+      file,
+      size: fileStats.size,
+      modified: fileStats.mtime
+    });
+  }
+  
+  // Create manifest
+  await write(`${backupPath}/manifest.json`, JSON.stringify({
+    timestamp: new Date().toISOString(),
+    files: results,
+    totalFiles: results.length,
+    totalSize: results.reduce((sum, f) => sum + f.size, 0)
+  }, null, 2));
+  
+  return results;
+}
+```
+
+🛠️ Error Handling
+
+All methods throw descriptive errors that you should catch:
+
+```javascript
+try {
+  const content = await read('missing-file.txt');
+} catch (error) {
+  console.error('Failed to read file:', error.message);
+  // Handle the error appropriately
+}
+```
+
+⚡ Performance Tips
+
+1. Large Files: Use readStream() instead of read() for files > 100MB
+2. Line Processing: Use readLines() for processing large text files line by line
+3. Batch Operations: Use async/await with Promise.all() for multiple files
+4. Watch Mode: Use { persistent: false } for one-time change detection
+
+🔒 Security
+
+· All file operations are subject to Node.js file system permissions
+· Use mode option to set file permissions (default: 0o666)
+· Validate user input before using in file paths
+
+🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (git checkout -b feature/AmazingFeature)
+3. Commit your changes (git commit -m 'Add some AmazingFeature')
+4. Push to the branch (git push origin feature/AmazingFeature)
+5. Open a Pull Request
+
+📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+🙏 Acknowledgments
+
+· Built with Node.js built-in fs module
+· Inspired by simplicity and developer experience
+· Community feedback and contributions
+
+📧 Support
+
+· 📖 Documentation
+· 🐛 Issue Tracker
+· 💬 Discussions
+
+---
+
+Made with ❤️ for developers who want simple, powerful file operations
+
+Back to Top