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() (when available) 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.
• User-friendly errors.

Install

$ npm install cp-file

Usage

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

cpFile('src/unicorn.png', 'dist/unicorn.png').then(() => {
	console.log('File copied');
});

API

cpFile(source, destination, [options])

Returns a Promise.

cpFile.sync(source, destination, [options])

source

Type: string

File you want to copy.

destination

Type: string

Where you want the file copied.

options

Type: Object

overwrite

Type: boolean
Default: true

Overwrite existing file.

cpFile.on('progress', handler)

Progress reporting. Only available when using the async method.

handler(data)

Type: Function

data

{
	src: String,
	dest: String,
	size: Number,
	written: Number,
	percent: Number
}

• src and dest are absolute paths.
• size and written 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():

cpFile(src, dest).on('progress', data => {
	// ...
}).then(() => {
	// ...
})

Related

See cpy if you need to copy multiple files or want a CLI.

License

MIT © Sindre Sorhus