cp-file

What is cp-file?

The cp-file npm package is a utility for copying files with support for progress reporting and other advanced features. It is designed to be a simple and efficient way to copy files in Node.js applications.

What are cp-file's main functionalities?

Basic File Copy

This feature allows you to copy a file from a source path to a destination path. The promise resolves when the file has been successfully copied.

const cpFile = require('cp-file');

cpFile('source.txt', 'destination.txt').then(() => {
  console.log('File copied');
});

Progress Reporting

This feature provides progress reporting during the file copy process. You can listen to the 'progress' event to get updates on the copy progress.

const cpFile = require('cp-file');

cpFile('source.txt', 'destination.txt').on('progress', data => {
  console.log(`Progress: ${data.percent * 100}%`);
}).then(() => {
  console.log('File copied');
});

Preserve Timestamps

This feature allows you to preserve the original file timestamps when copying a file. This can be useful for maintaining file metadata.

const cpFile = require('cp-file');

cpFile('source.txt', 'destination.txt', { preserveTimestamps: true }).then(() => {
  console.log('File copied with timestamps preserved');
});

Overwrite Option

This feature allows you to specify whether to overwrite the destination file if it already exists. By setting the 'overwrite' option to false, you can prevent accidental overwrites.

const cpFile = require('cp-file');

cpFile('source.txt', 'destination.txt', { overwrite: false }).then(() => {
  console.log('File copied without overwriting existing files');
}).catch(error => {
  console.error('File already exists');
});

Other packages similar to cp-file

fs-extra

fs-extra is a popular package that extends the native Node.js fs module with additional methods, including file copying. It provides similar functionality to cp-file but also includes many other file system utilities, making it a more comprehensive solution.

ncp

ncp (Node Copy) is another package for copying files and directories. It offers similar functionality to cp-file but is more focused on copying entire directories, making it a good choice for more complex copy operations.

cpy

cpy is a package for copying files with a focus on simplicity and performance. It offers similar features to cp-file, such as progress reporting and the ability to preserve timestamps, but is designed to be more lightweight and efficient.

README

cp-file

Copy a file

Highlights

• Fast by using streams in the async version and fs.copyFileSync() in the synchronous version.
• Resilient by using graceful-fs.
• User-friendly by creating non-existent destination directories for you.
• Can be safe by turning off overwriting.
• Preserves file mode, but not ownership.
• User-friendly errors.

Install

$ npm install cp-file

Usage

const cpFile = require('cp-file');

(async () => {
	await cpFile('source/unicorn.png', 'destination/unicorn.png');
	console.log('File copied');
})();

API

cpFile(source, destination, options?)

Returns a Promise that resolves when the file is copied.

cpFile.sync(source, destination, options?)

source

Type: string

The file you want to copy.

destination

Type: string

Where you want the file copied.

options

Type: object

overwrite

Type: boolean
Default: true

Overwrite existing destination file.

cpFile.on('progress', handler)

Progress reporting. Only available when using the async method.

handler(data)

Type: Function

data

{
	sourcePath: string,
	destinationPath: string,
	size: number,
	writtenBytes: number,
	percent: number
}

• source and destination are absolute paths.
• size and writtenBytes are in bytes.
• percent is a value between 0 and 1.

Notes

• For empty files, the progress event is emitted only once.
• The .on() method is available only right after the initial cpFile() call. So make sure you add a handler before .then():

const cpFile = require('cp-file');

(async () => {
	await cpFile(source, destination).on('progress', data => {
		// …
	});
})();

Related

• cpy - Copy files
• cpy-cli - Copy files on the command-line
• move-file - Move a file
• make-dir - Make a directory and its parents if needed