@mpenny/file-tools

A lightweight Node.js library for copying folders and performing text replacements across all files in a folder structure.

Features

• 📁 Copy entire folder structures recursively
• 🔄 Copy folders with automatic text/pattern replacement in all files
• 🎯 Filter files by extension (include/exclude)
• 📊 Get detailed statistics about copy operations
• 🔒 Safe handling of binary files
• ⚡ Built on native Node.js fs promises API

Installation

npm install @mpenny/file-tools

Usage

Import the library

const { copyFolder, copyFolderWithReplace } = require('@mpenny/file-tools');

Or with ES6 imports:

import { copyFolder, copyFolderWithReplace } from '@mpenny/file-tools';

Copy a folder

Simple folder copy operation:

const { copyFolder } = require('@mpenny/file-tools');

async function example() {
  try {
    await copyFolder('./source-folder', './destination-folder');
    console.log('Folder copied successfully!');
  } catch (error) {
    console.error('Error copying folder:', error);
  }
}

example();

Copy a folder with text replacement

Copy a folder and replace text in all files:

const { copyFolderWithReplace } = require('@mpenny/file-tools');

async function example() {
  try {
    const stats = await copyFolderWithReplace(
      './template-project',
      './new-project',
      'PLACEHOLDER_NAME',
      'MyAwesomeProject'
    );
    
    console.log('Copy complete!');
    console.log(`Files processed: ${stats.filesProcessed}`);
    console.log(`Files modified: ${stats.filesModified}`);
    console.log(`Files skipped: ${stats.filesSkipped}`);
    console.log(`Directories created: ${stats.directoriesCopied}`);
  } catch (error) {
    console.error('Error:', error);
  }
}

example();

Using regular expressions for replacement

Replace using regex patterns:

const { copyFolderWithReplace } = require('@mpenny/file-tools');

async function example() {
  const stats = await copyFolderWithReplace(
    './source',
    './destination',
    /version:\s*\d+\.\d+\.\d+/g,
    'version: 2.0.0'
  );
  
  console.log(`Modified ${stats.filesModified} files`);
}

example();

Filter files by extension

Only process specific file types or exclude certain extensions:

const { copyFolderWithReplace } = require('@mpenny/file-tools');

async function example() {
  // Only replace in .js and .json files
  const stats = await copyFolderWithReplace(
    './source',
    './destination',
    'oldValue',
    'newValue',
    {
      includeExtensions: ['.js', '.json']
    }
  );

  // Or exclude binary files
  const stats2 = await copyFolderWithReplace(
    './source',
    './destination',
    'oldValue',
    'newValue',
    {
      excludeExtensions: ['.jpg', '.png', '.pdf', '.zip']
    }
  );
}

example();

API Reference

copyFolder(source, destination)

Recursively copies a folder from source to destination.

Parameters:

• source (string): Source folder path
• destination (string): Destination folder path

Returns: Promise<void>

Throws: Error if copy operation fails

copyFolderWithReplace(source, destination, searchValue, replaceValue, options)

Recursively copies a folder and replaces text in all files.

Parameters:

• source (string): Source folder path
• destination (string): Destination folder path
• searchValue (string | RegExp): Text or pattern to search for
• replaceValue (string): Text to replace with
• options (object, optional):
  • excludeExtensions (string[]): File extensions to exclude from replacement
  • includeExtensions (string[]): Only process files with these extensions

Returns: Promise<CopyFolderWithReplaceStats>

Stats Object:

{
  filesProcessed: number;    // Files checked for replacements
  filesModified: number;      // Files where replacements were made
  filesSkipped: number;       // Files skipped (binary or excluded)
  directoriesCopied: number;  // Directories created
}

Throws: Error if operation fails

Use Cases

• Project Templates: Create project templates with placeholders and generate new projects with replaced values
• Code Generation: Copy boilerplate code and customize it for different contexts
• Configuration Management: Duplicate configuration directories with environment-specific values
• Documentation: Generate customized documentation from templates
• Build Processes: Create modified copies of source code for different build targets

Requirements

• Node.js >= 14.0.0

License

MIT

Contributing

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

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.