UNPKG

2.42 kBMarkdownView Raw
1# cp-file [![Build Status](https://travis-ci.org/sindresorhus/cp-file.svg?branch=master)](https://travis-ci.org/sindresorhus/cp-file) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/cp-file/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/cp-file?branch=master)
2
3> Copy a file
4
5
6## Highlights
7
8- Fast by using streams in the async version and [`fs.copyFileSync()`](https://nodejs.org/api/fs.html#fs_fs_copyfilesync_src_dest_flags) in the synchronous version.
9- Resilient by using [graceful-fs](https://github.com/isaacs/node-graceful-fs).
10- User-friendly by creating non-existent destination directories for you.
11- Can be safe by turning off [overwriting](#optionsoverwrite).
12- User-friendly errors.
13
14
15## Install
16
17```
18$ npm install cp-file
19```
20
21
22## Usage
23
24```js
25const cpFile = require('cp-file');
26
27(async () => {
28 await cpFile('source/unicorn.png', 'destination/unicorn.png');
29 console.log('File copied');
30})();
31```
32
33
34## API
35
36### cpFile(source, destination, [options])
37
38Returns a `Promise` that resolves when the file is copied.
39
40### cpFile.sync(source, destination, [options])
41
42#### source
43
44Type: `string`
45
46File you want to copy.
47
48#### destination
49
50Type: `string`
51
52Where you want the file copied.
53
54#### options
55
56Type: `Object`
57
58##### overwrite
59
60Type: `boolean`<br>
61Default: `true`
62
63Overwrite existing file.
64
65### cpFile.on('progress', handler)
66
67Progress reporting. Only available when using the async method.
68
69#### handler(data)
70
71Type: `Function`
72
73##### data
74
75```js
76{
77 src: string,
78 dest: string,
79 size: number,
80 written: number,
81 percent: number
82}
83```
84
85- `src` and `dest` are absolute paths.
86- `size` and `written` are in bytes.
87- `percent` is a value between `0` and `1`.
88
89###### Notes
90
91- For empty files, the `progress` event is emitted only once.
92- The `.on()` method is available only right after the initial `cpFile()` call. So make sure
93you add a `handler` before `.then()`:
94
95```js
96(async () => {
97 await cpFile(source, destination).on('progress', data => {
98 // …
99 });
100})();
101```
102
103
104## Related
105
106- [cpy](https://github.com/sindresorhus/cpy) - Copy files
107- [cpy-cli](https://github.com/sindresorhus/cpy-cli) - Copy files on the command-line
108- [move-file](https://github.com/sindresorhus/move-file) - Move a file
109- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed
110
111
112## License
113
114MIT © [Sindre Sorhus](https://sindresorhus.com)