Add cloning support

.gitignore

@@ -2,3 +2,4 @@ node_modules
 yarn.lock
 .nyc_output
 coverage
+ts-build

.travis.yml

@@ -4,7 +4,13 @@ os:
   - windows
 language: node_js
 node_js:
+  - '14'
   - '12'
   - '10'
+before_install:
+  # Run a one-liner that prints "mount" information about the current dir
+  - if command -v mount grep df head tail cut &>/dev/null; then mount | grep "^$(df -Pk . | head -n 2 | tail -n 1 | cut -f 1 -d ' ') "; fi
+  # The cache got stuck at some old version that satisfies the requirements but breaks CI...
+  - npm update --depth 0 --no-save
 after_success:
   - './node_modules/.bin/nyc report --reporter=text-lcov | ./node_modules/.bin/coveralls'

cp-file-error.js

@@ -1,7 +1,12 @@
+/// <reference path="index.d.ts" />
 'use strict';
 const NestedError = require('nested-error-stacks');
 
 class CpFileError extends NestedError {
+	/**
+	 * @param {string} message
+	 * @param {Error} [nested]
+	 */
 	constructor(message, nested) {
 		super(message, nested);
 		Object.assign(this, nested);

fs.js

@@ -4,6 +4,7 @@ const fs = require('graceful-fs');
 const makeDir = require('make-dir');
 const pEvent = require('p-event');
 const CpFileError = require('./cp-file-error');
+const {version} = process;
 
 const stat = promisify(fs.stat);
 const lstat = promisify(fs.lstat);
@@ -13,6 +14,10 @@ const chmod = promisify(fs.chmod);
 exports.closeSync = fs.closeSync.bind(fs);
 exports.createWriteStream = fs.createWriteStream.bind(fs);
 
+/**
+@param {import('fs').PathLike} path
+@param {object} [options]
+ */
 exports.createReadStream = async (path, options) => {
 	const read = fs.createReadStream(path, options);
 
@@ -25,22 +30,40 @@ exports.createReadStream = async (path, options) => {
 	return read;
 };
 
+/**
+@param {import('fs').PathLike} path
+ */
 exports.stat = path => stat(path).catch(error => {
 	throw new CpFileError(`Cannot stat path \`${path}\`: ${error.message}`, error);
 });
 
+/**
+@param {import('fs').PathLike} path
+ */
 exports.lstat = path => lstat(path).catch(error => {
 	throw new CpFileError(`lstat \`${path}\` failed: ${error.message}`, error);
 });
 
+/**
+@param {import('fs').PathLike} path
+@param {string | number | Date} atime
+@param {string | number | Date} mtime
+ */
 exports.utimes = (path, atime, mtime) => utimes(path, atime, mtime).catch(error => {
 	throw new CpFileError(`utimes \`${path}\` failed: ${error.message}`, error);
 });
 
+/**
+@param {import('fs').PathLike} path
+@param {import('fs').Mode} mode
+ */
 exports.chmod = (path, mode) => chmod(path, mode).catch(error => {
 	throw new CpFileError(`chmod \`${path}\` failed: ${error.message}`, error);
 });
 
+/**
+@param {import('fs').PathLike} path
+ */
 exports.statSync = path => {
 	try {
 		return fs.statSync(path);
@@ -49,6 +72,11 @@ exports.statSync = path => {
 	}
 };
 
+/**
+@param {import('fs').PathLike} path
+@param {string | number | Date} atime
+@param {string | number | Date} mtime
+ */
 exports.utimesSync = (path, atime, mtime) => {
 	try {
 		return fs.utimesSync(path, atime, mtime);
@@ -57,10 +85,16 @@ exports.utimesSync = (path, atime, mtime) => {
 	}
 };
 
+/**
+@param {string} path
+ */
 exports.makeDir = path => makeDir(path, {fs}).catch(error => {
 	throw new CpFileError(`Cannot create directory \`${path}\`: ${error.message}`, error);
 });
 
+/**
+@param {string} path
+ */
 exports.makeDirSync = path => {
 	try {
 		makeDir.sync(path, {fs});
@@ -69,8 +103,28 @@ exports.makeDirSync = path => {
 	}
 };
 
+/**
+@param {import('fs').PathLike} source
+@param {import('fs').PathLike} destination
+@param {number?} [flags]
+ */
+exports.cloneFileSync = (source, destination, flags) => {
+	try {
+		if (flags == undefined) flags = 0;
+		fs.copyFileSync(source, destination, flags | fs.constants.COPYFILE_FICLONE_FORCE);
+	} catch (error) {
+		throw new CpFileError(`Cannot clone from \`${source}\` to \`${destination}\`: ${error.message}`, error);
+	}
+};
+
+/**
+@param {import('fs').PathLike} source
+@param {import('fs').PathLike} destination
+@param {number?} [flags]
+ */
 exports.copyFileSync = (source, destination, flags) => {
 	try {
+		if (flags === null) flags = undefined;
 		fs.copyFileSync(source, destination, flags);
 	} catch (error) {
 		throw new CpFileError(`Cannot copy from \`${source}\` to \`${destination}\`: ${error.message}`, error);

index.d.ts

@@ -6,6 +6,13 @@ declare namespace cpFile {
 		@default true
 		*/
 		readonly overwrite?: boolean;
+
+		/**
+		Perform a fast copy-on-write clone (reflink) if possible.
+
+		@default true
+		*/
+		readonly clone?: boolean | 'force';
 	}
 
 	interface ProgressData {

index.js

@@ -1,16 +1,55 @@
+/// <reference path="index.d.ts" />
 'use strict';
 const path = require('path');
 const {constants: fsConstants} = require('fs');
 const pEvent = require('p-event');
 const CpFileError = require('./cp-file-error');
 const fs = require('./fs');
 const ProgressEmitter = require('./progress-emitter');
+const {version} = process;
 
+const defaultOptions = {
+	overwrite: true,
+	clone: true
+};
+
+/**
+@param {import('fs').PathLike} source
+@param {import('fs').PathLike} destination
+ */
+const updateStats = async (source, destination) => {
+	const stats = await fs.lstat(source);
+
+	return Promise.all([
+		fs.utimes(destination, stats.atime, stats.mtime),
+		fs.chmod(destination, stats.mode)
+	]);
+};
+
+/**
+@param {string} source
+@param {string} destination
+@param {import('.').Options} options
+@param {ProgressEmitter} progressEmitter
+ */
 const cpFileAsync = async (source, destination, options, progressEmitter) => {
 	let readError;
 	const stat = await fs.stat(source);
 	progressEmitter.size = stat.size;
 
+	// Try to do a fast-path using FICLONE_FORCE. This will be very fast if at all successful.
+	if (options.clone) {
+		try {
+			fs.cloneFileSync(source, destination, options.overwrite ? null : fsConstants.COPYFILE_EXCL);
+			progressEmitter.writtenBytes = progressEmitter.size;
+			return updateStats(source, destination);
+		} catch (error) {
+			if (options.clone === 'force') {
+				throw error;
+			}
+		}
+	}
+
 	const readStream = await fs.createReadStream(source);
 	await fs.makeDir(path.dirname(destination));
 	const writeStream = fs.createWriteStream(destination, {flags: options.overwrite ? 'w' : 'wx'});
@@ -24,13 +63,11 @@ const cpFileAsync = async (source, destination, options, progressEmitter) => {
 		writeStream.end();
 	});
 
-	let shouldUpdateStats = false;
 	try {
 		const writePromise = pEvent(writeStream, 'close');
 		readStream.pipe(writeStream);
 		await writePromise;
 		progressEmitter.writtenBytes = progressEmitter.size;
-		shouldUpdateStats = true;
 	} catch (error) {
 		throw new CpFileError(`Cannot write to \`${destination}\`: ${error.message}`, error);
 	}
@@ -39,39 +76,47 @@ const cpFileAsync = async (source, destination, options, progressEmitter) => {
 		throw readError;
 	}
 
-	if (shouldUpdateStats) {
-		const stats = await fs.lstat(source);
-
-		return Promise.all([
-			fs.utimes(destination, stats.atime, stats.mtime),
-			fs.chmod(destination, stats.mode)
-		]);
-	}
+	// If we make it here, we should have no other errors. No need for a flag.
+	return updateStats(source, destination);
 };
 
+/**
+@param {string} sourcePath
+@param {string} destinationPath
+@param {import('.').Options} options
+@returns {Promise<void> & import('.').ProgressEmitter}
+ */
 const cpFile = (sourcePath, destinationPath, options) => {
 	if (!sourcePath || !destinationPath) {
+		// @ts-expect-error
 		return Promise.reject(new CpFileError('`source` and `destination` required'));
 	}
 
 	options = {
-		overwrite: true,
+		...defaultOptions,
 		...options
 	};
 
 	const progressEmitter = new ProgressEmitter(path.resolve(sourcePath), path.resolve(destinationPath));
 	const promise = cpFileAsync(sourcePath, destinationPath, options, progressEmitter);
 
+	// @ts-expect-error
 	promise.on = (...arguments_) => {
+		// @ts-expect-error
 		progressEmitter.on(...arguments_);
 		return promise;
 	};
 
+	// @ts-expect-error
 	return promise;
 };
 
 module.exports = cpFile;
 
+/**
+@param {import('fs').Stats} stat
+@param {string} source
+ */
 const checkSourceIsFile = (stat, source) => {
 	if (stat.isDirectory()) {
 		throw Object.assign(new CpFileError(`EISDIR: illegal operation on a directory '${source}'`), {
@@ -82,21 +127,36 @@ const checkSourceIsFile = (stat, source) => {
 	}
 };
 
+/**
+@param {string} source
+@param {string} destination
+@param {import('.').Options} options
+ */
 module.exports.sync = (source, destination, options) => {
 	if (!source || !destination) {
 		throw new CpFileError('`source` and `destination` required');
 	}
 
 	options = {
-		overwrite: true,
+		...defaultOptions,
 		...options
 	};
 
 	const stat = fs.statSync(source);
 	checkSourceIsFile(stat, source);
 	fs.makeDirSync(path.dirname(destination));
 
-	const flags = options.overwrite ? null : fsConstants.COPYFILE_EXCL;
+	let flags = 0;
+	if (!options.overwrite) {
+		flags |= fsConstants.COPYFILE_EXCL;
+	}
+
+	if (options.clone === true) {
+		flags |= fsConstants.COPYFILE_FICLONE;
+	} else if (options.clone === 'force') {
+		flags |= fsConstants.COPYFILE_FICLONE_FORCE;
+	}
+
 	try {
 		fs.copyFileSync(source, destination, flags);
 	} catch (error) {

package.json

@@ -14,7 +14,8 @@
 		"node": ">=10"
 	},
 	"scripts": {
-		"test": "xo && nyc ava && tsd"
+		"test": "xo && nyc ava && tsd && tsc",
+		"fix": "xo --fix"
 	},
 	"files": [
 		"cp-file-error.js",
@@ -54,6 +55,9 @@
 		"sinon": "^9.0.0",
 		"tsd": "^0.11.0",
 		"uuid": "^7.0.2",
-		"xo": "^0.27.2"
+		"xo": "^0.27.2",
+		"@types/graceful-fs": "^4.1.3",
+		"@types/nested-error-stacks": "^2.1.0",
+		"typescript": "^3.9.5"
 	}
 }

progress-emitter.js

@@ -1,20 +1,33 @@
+/// <reference path="index.d.ts" />
 'use strict';
-const EventEmitter = require('events');
+const { EventEmitter } = require('events');
 
+/** @type {WeakMap<ProgressEmitter, number>} */
 const writtenBytes = new WeakMap();
 
+/** @type {import('.').ProgressEmitter} */
 class ProgressEmitter extends EventEmitter {
+	/**
+	 * @param {string} sourcePath
+	 * @param {string} destinationPath
+	 */
 	constructor(sourcePath, destinationPath) {
 		super();
+		/** @type {string} */
 		this._sourcePath = sourcePath;
+		/** @type {string} */
 		this._destinationPath = destinationPath;
+		/** @type {number} */
+		this.size = Infinity;
 	}
 
 	get writtenBytes() {
+		// @ts-expect-error
 		return writtenBytes.get(this);
 	}
 
 	set writtenBytes(value) {
+		// @ts-expect-error
 		writtenBytes.set(this, value);
 		this.emitProgress();
 	}
@@ -27,6 +40,7 @@ class ProgressEmitter extends EventEmitter {
 			destinationPath: this._destinationPath,
 			size,
 			writtenBytes,
+			// @ts-expect-error
 			percent: writtenBytes === size ? 1 : writtenBytes / size
 		});
 	}