copy-recursive

A flexible and powerful Node.js utility for recursively copying files and directories with advanced configuration options.

Features

• Recursive file and directory copying
• Configurable copy depth and height limits
• Directory flattening option
• Multiple conflict resolution strategies
• Support for single source or multiple sources
• Asynchronous operation with Promises
• Comprehensive error handling
• Configurable logging levels with Gulp-style output

Installation

npm install copy-recursive

Usage

import copy from 'copy-recursive';

// Single file/directory copy with logging
const config = [{
    src: 'source/path',
    dest: 'destination/path',
    depth: 2,
    height: 0,
    flatten: false,
    conflictResolution: 'rename',
    logLevel: 'brief'
}];
await copy(config);

// Multiple sources with verbose logging
const multiConfig = [{
    src: ['source1', 'source2', 'source3'],
    dest: 'destination/path',
    flatten: true,
    logLevel: 'verbose'
}];
await copy(multiConfig);

Configuration Options

Each configuration object supports the following options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | src | string\|string[] | required | Source path(s) to copy from | | dest | string | required | Destination path to copy to | | depth | number | 0 | Maximum copy depth (0 for unlimited) | | height | number | 0 | Maximum copy height from root (0 for unlimited) | | flatten | boolean | false | When true, flattens directory structure | | conflictResolution | string | 'overwrite' | How to handle conflicts ('overwrite', 'skip', or 'rename') | | logLevel | string | 'none' | Logging level ('none', 'verbose', or 'brief') |

Conflict Resolution Strategies

• overwrite: Overwrites existing files at destination
• skip: Skips copying if file exists at destination
• rename: Adds a numeric suffix to create a unique filename

Logging Levels

• none: No logging output
• verbose: Detailed logging of all operations
• brief: Concise, Gulp-style logging with symbols
  • → File copied
  • ↺ File overwritten
  • ⠿ File skipped
  • ⥅ File renamed

Example brief logging output:

Starting copy task...
→ src/file1.txt → dest/file1.txt
↺ src/file2.txt → dest/file2.txt
⠿ src/file3.txt
⥅ src/file4.txt → dest/file4_1.txt
Copy task completed

Project Structure

copy-recursive/
├── index.js         # Main module file
├── test-script.js   # Test script by shell
├── test/            # Test by Mocha/Chai
├── docs/            # Generated documentation
├── jsdoc.json       # JSDoc configuration
├── .mocharc.json    # Mocha configuration
├── package.json     # Project configuration
└── README.md        # This file

Documentation

To generate documentation:

npm run docs

Documentation will be generated in the docs directory. Open docs/index.html in your browser to view.

Testing

To run tests:

npm test

Development

1. Clone the repository
2. Install dependencies:

npm install

3. Make your changes
4. Run tests:

npm test

5. Generate documentation:

npm run docs

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

Please open an issue for support.