Modern File System Utilities

A modern, Promise-based file system utility library for Node.js with TypeScript support, comprehensive error handling, and logging capabilities.

Features

• 📁 File Operations

  • Read and write files with UTF-8 encoding
  • Copy and move files with automatic directory creation
  • Delete files safely
  • Calculate file hashes (SHA-256, MD5, etc.)

• 📂 Directory Operations

  • Create and delete directories recursively
  • List directory contents (recursive optional)
  • Compare directory contents
  • Check if directories are empty
  • Create ZIP archives of directories

• 🛡️ Robust Error Handling

  • Custom error types for different scenarios
  • Detailed error messages with error codes
  • Type-safe error checking utilities

• 📝 Built-in Logging

  • Component-based logging
  • Multiple log levels (debug, info, error)
  • JSON formatting for complex data
  • Timestamps for all logs

Installation

npm install file-utils

Usage

File Operations

import { file } from '@vitkuz/file-utils';

// Read file
const content = await file.readFile('path/to/file.txt');

// Write file
await file.writeFile('path/to/new-file.txt', 'Hello World');

// Copy file
await file.copyFile('source.txt', 'destination.txt');

// Move file
await file.moveFile('old-location.txt', 'new-location.txt');

// Delete file
await file.deleteFile('unwanted-file.txt');

// Calculate file hash
const hash = await file.hashFile('important-file.txt', 'sha256');

Directory Operations

import { folder } from '@vitkuz/file-utils';

// Create directory
await folder.createDir('new-directory');

// List directory contents
const files = await folder.listDir('my-directory', true); // true for recursive

// Compare directories
const comparison = await folder.compareDirs('dir1', 'dir2');
console.log(comparison.common);        // Files in both directories
console.log(comparison.onlyInDir1);    // Files only in dir1
console.log(comparison.onlyInDir2);    // Files only in dir2

// Check if directory is empty
const isEmpty = await folder.isEmpty('some-directory');

// Create ZIP archive
await folder.zipDir('source-directory', 'archive.zip');

Error Handling

import { utils } from '@vitkuz/file-utils';

try {
  await file.readFile('non-existent.txt');
} catch (error) {
  if (utils.isErrorType(error, utils.FileNotFoundError)) {
    console.log('File not found!');
  } else if (utils.isErrorType(error, utils.PermissionError)) {
    console.log('Permission denied!');
  }
}

Logging

The library includes built-in logging that provides detailed information about operations:

// Logs are automatically generated for all operations
await file.writeFile('example.txt', 'content');
// [2024-01-20T10:30:00.000Z] DEBUG files - Writing to file: example.txt

Error Types

• FSError - Base error class
• FileNotFoundError - File does not exist
• DirectoryNotFoundError - Directory does not exist
• PathExistsError - Path already exists
• InvalidPathError - Path is invalid
• PermissionError - Insufficient permissions
• HashError - Hash calculation failed
• ZipError - ZIP operation failed

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Watch mode during development
npm run dev

# Lint the code
npm run lint

# Format the code
npm run format

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.