A powerful Node.js script for bulk file renaming with pattern-based matching and comprehensive validation.

• Pattern-based Renaming: Automatically rename files based on configurable naming patterns
• Recursive Directory Scanning: Process entire directory trees with subdirectory support
• Comprehensive Validation: Full settings validation with specific error messages
• Flexible Configuration: Customizable target names, separators, and replacement patterns
• Safe Operation: Built-in safeguards and detailed logging
• Error Resilience: Continues processing despite individual file failures
• TypeScript: Fully typed with comprehensive type definitions

1. Clone the repository:

   git clone https://github.com/orassayag/renamer.git
   cd renamer

2. Install dependencies:

   npm install
   # or
   pnpm install

3. Configure settings in src/settings/index.ts:

   export const SETTINGS: Settings = {
     targetNames: ['IMG', 'Screenshot'],
     replaceName: 'notes-',
     scanPath: 'C:\\Users\\Username\\Downloads',
     separator: '_',
     ignorePaths: ['node_modules', '.git'],
     sleepAfterMilliseconds: 50,
   };

4. Run the script:

   npm start

The script renames files that match the pattern:

[targetName][separator][remainingFileName]

Example: Files like IMG_photo1.jpg become notes-photo1.jpg

Before:
├── IMG_photo1.jpg
├── Screenshot_2023.png
├── IMG_vacation.jpg
└── document.pdf

After (with targetNames: ["IMG", "Screenshot"], replaceName: "notes-"):
├── notes-photo1.jpg
├── notes-2023.png
├── notes-vacation.jpg
└── document.pdf (unchanged - doesn't match pattern)

• INSTRUCTIONS.md: Comprehensive usage guide and configuration details
• Type Definitions: Full TypeScript support with src/types/settings.ts
• Code Documentation: Inline JSDoc comments throughout the codebase

# Run the rename script
npm start

# Lint the codebase
npm run lint

src/
├── logic/
│   ├── processFile.ts          # Individual file processing logic
│   ├── scanAndRenameFiles.ts   # Directory scanning and recursion
│   └── validateSettings.ts     # Comprehensive settings validation
├── scripts/
│   └── renameScript.ts         # Main execution script
├── settings/
│   └── index.ts                # Configuration settings
├── types/
│   ├── settings.ts             # TypeScript type definitions
│   └── index.ts                # Type exports
└── utils/
    ├── shouldIgnorePath.ts     # Path filtering utilities
    ├── sleep.ts                # Async delay utility
    └── index.ts                # Utility exports

• Pre-execution Validation: All settings validated before processing
• Detailed Logging: Comprehensive operation logs and error reporting
• Error Resilience: Continues processing despite individual file failures
• Path Sanitization: Prevents path traversal vulnerabilities
• Configurable Delays: Prevents file system overload

• Backup First: Always backup important directories before bulk operations
• Test Small: Test with a small directory before processing large volumes
• No Undo: The script doesn't provide undo functionality - keep backups!
• Pattern Matching: Only processes files matching the exact naming pattern

1. "Cannot access scanPath": Verify the directory exists and you have read permissions
2. "No files renamed": Check that your target names and separators match existing files
3. "Permission denied": Ensure you have write permissions in the target directory

The script provides specific error messages for common issues:

• Invalid settings with detailed parameter validation
• File system access problems
• Type checking errors
• Path validation failures

MIT License - see LICENSE file for details.

Or Assayag - GitHub - Email

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

1. Fork the repository
2. Create your 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

• file - File operations and management
• files - Multiple file processing
• rename - Bulk renaming functionality
• bulk - Batch processing capabilities

⚡ Fast, Safe, and Reliable Bulk File Renaming