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
|
25 | const 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 |
|
38 | Returns a `Promise` that resolves when the file is copied.
|
39 |
|
40 | ### cpFile.sync(source, destination, [options])
|
41 |
|
42 | #### source
|
43 |
|
44 | Type: `string`
|
45 |
|
46 | File you want to copy.
|
47 |
|
48 | #### destination
|
49 |
|
50 | Type: `string`
|
51 |
|
52 | Where you want the file copied.
|
53 |
|
54 | #### options
|
55 |
|
56 | Type: `Object`
|
57 |
|
58 | ##### overwrite
|
59 |
|
60 | Type: `boolean`<br>
|
61 | Default: `true`
|
62 |
|
63 | Overwrite existing file.
|
64 |
|
65 | ### cpFile.on('progress', handler)
|
66 |
|
67 | Progress reporting. Only available when using the async method.
|
68 |
|
69 | #### handler(data)
|
70 |
|
71 | Type: `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
|
93 | you 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 |
|
114 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|