source: trip-planner-front/node_modules/tmp/README.md

Last change on this file was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 9.1 KB
Line 
1# Tmp
2
3A simple temporary file and directory creator for [node.js.][1]
4
5[![Build Status](https://travis-ci.org/raszi/node-tmp.svg?branch=master)](https://travis-ci.org/raszi/node-tmp)
6[![Dependencies](https://david-dm.org/raszi/node-tmp.svg)](https://david-dm.org/raszi/node-tmp)
7[![npm version](https://badge.fury.io/js/tmp.svg)](https://badge.fury.io/js/tmp)
8[![API documented](https://img.shields.io/badge/API-documented-brightgreen.svg)](https://raszi.github.io/node-tmp/)
9[![Known Vulnerabilities](https://snyk.io/test/npm/tmp/badge.svg)](https://snyk.io/test/npm/tmp)
10
11## About
12
13This is a [widely used library][2] to create temporary files and directories
14in a [node.js][1] environment.
15
16Tmp offers both an asynchronous and a synchronous API. For all API calls, all
17the parameters are optional. There also exists a promisified version of the
18API, see (5) under references below.
19
20Tmp uses crypto for determining random file names, or, when using templates,
21a six letter random identifier. And just in case that you do not have that much
22entropy left on your system, Tmp will fall back to pseudo random numbers.
23
24You can set whether you want to remove the temporary file on process exit or
25not, and the destination directory can also be set.
26
27## How to install
28
29```bash
30npm install tmp
31```
32
33## Usage
34
35Please also check [API docs][4].
36
37### Asynchronous file creation
38
39Simple temporary file creation, the file will be closed and unlinked on process exit.
40
41```javascript
42var tmp = require('tmp');
43
44tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
45 if (err) throw err;
46
47 console.log('File: ', path);
48 console.log('Filedescriptor: ', fd);
49
50 // If we don't need the file anymore we could manually call the cleanupCallback
51 // But that is not necessary if we didn't pass the keep option because the library
52 // will clean after itself.
53 cleanupCallback();
54});
55```
56
57### Synchronous file creation
58
59A synchronous version of the above.
60
61```javascript
62var tmp = require('tmp');
63
64var tmpobj = tmp.fileSync();
65console.log('File: ', tmpobj.name);
66console.log('Filedescriptor: ', tmpobj.fd);
67
68// If we don't need the file anymore we could manually call the removeCallback
69// But that is not necessary if we didn't pass the keep option because the library
70// will clean after itself.
71tmpobj.removeCallback();
72```
73
74Note that this might throw an exception if either the maximum limit of retries
75for creating a temporary name fails, or, in case that you do not have the permission
76to write to the directory where the temporary file should be created in.
77
78### Asynchronous directory creation
79
80Simple temporary directory creation, it will be removed on process exit.
81
82If the directory still contains items on process exit, then it won't be removed.
83
84```javascript
85var tmp = require('tmp');
86
87tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
88 if (err) throw err;
89
90 console.log('Dir: ', path);
91
92 // Manual cleanup
93 cleanupCallback();
94});
95```
96
97If you want to cleanup the directory even when there are entries in it, then
98you can pass the `unsafeCleanup` option when creating it.
99
100### Synchronous directory creation
101
102A synchronous version of the above.
103
104```javascript
105var tmp = require('tmp');
106
107var tmpobj = tmp.dirSync();
108console.log('Dir: ', tmpobj.name);
109// Manual cleanup
110tmpobj.removeCallback();
111```
112
113Note that this might throw an exception if either the maximum limit of retries
114for creating a temporary name fails, or, in case that you do not have the permission
115to write to the directory where the temporary directory should be created in.
116
117### Asynchronous filename generation
118
119It is possible with this library to generate a unique filename in the specified
120directory.
121
122```javascript
123var tmp = require('tmp');
124
125tmp.tmpName(function _tempNameGenerated(err, path) {
126 if (err) throw err;
127
128 console.log('Created temporary filename: ', path);
129});
130```
131
132### Synchronous filename generation
133
134A synchronous version of the above.
135
136```javascript
137var tmp = require('tmp');
138
139var name = tmp.tmpNameSync();
140console.log('Created temporary filename: ', name);
141```
142
143## Advanced usage
144
145### Asynchronous file creation
146
147Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
148
149```javascript
150var tmp = require('tmp');
151
152tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
153 if (err) throw err;
154
155 console.log('File: ', path);
156 console.log('Filedescriptor: ', fd);
157});
158```
159
160### Synchronous file creation
161
162A synchronous version of the above.
163
164```javascript
165var tmp = require('tmp');
166
167var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
168console.log('File: ', tmpobj.name);
169console.log('Filedescriptor: ', tmpobj.fd);
170```
171
172### Controlling the Descriptor
173
174As a side effect of creating a unique file `tmp` gets a file descriptor that is
175returned to the user as the `fd` parameter. The descriptor may be used by the
176application and is closed when the `removeCallback` is invoked.
177
178In some use cases the application does not need the descriptor, needs to close it
179without removing the file, or needs to remove the file without closing the
180descriptor. Two options control how the descriptor is managed:
181
182* `discardDescriptor` - if `true` causes `tmp` to close the descriptor after the file
183 is created. In this case the `fd` parameter is undefined.
184* `detachDescriptor` - if `true` causes `tmp` to return the descriptor in the `fd`
185 parameter, but it is the application's responsibility to close it when it is no
186 longer needed.
187
188```javascript
189var tmp = require('tmp');
190
191tmp.file({ discardDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
192 if (err) throw err;
193 // fd will be undefined, allowing application to use fs.createReadStream(path)
194 // without holding an unused descriptor open.
195});
196```
197
198```javascript
199var tmp = require('tmp');
200
201tmp.file({ detachDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
202 if (err) throw err;
203
204 cleanupCallback();
205 // Application can store data through fd here; the space used will automatically
206 // be reclaimed by the operating system when the descriptor is closed or program
207 // terminates.
208});
209```
210
211### Asynchronous directory creation
212
213Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
214
215```javascript
216var tmp = require('tmp');
217
218tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
219 if (err) throw err;
220
221 console.log('Dir: ', path);
222});
223```
224
225### Synchronous directory creation
226
227Again, a synchronous version of the above.
228
229```javascript
230var tmp = require('tmp');
231
232var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
233console.log('Dir: ', tmpobj.name);
234```
235
236### mkstemp like, asynchronously
237
238Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
239
240```javascript
241var tmp = require('tmp');
242
243tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
244 if (err) throw err;
245
246 console.log('Dir: ', path);
247});
248```
249
250### mkstemp like, synchronously
251
252This will behave similarly to the asynchronous version.
253
254```javascript
255var tmp = require('tmp');
256
257var tmpobj = tmp.dirSync({ template: '/tmp/tmp-XXXXXX' });
258console.log('Dir: ', tmpobj.name);
259```
260
261### Asynchronous filename generation
262
263The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
264
265```javascript
266var tmp = require('tmp');
267
268tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, path) {
269 if (err) throw err;
270
271 console.log('Created temporary filename: ', path);
272});
273```
274
275### Synchronous filename generation
276
277The `tmpNameSync()` function works similarly to `tmpName()`.
278
279```javascript
280var tmp = require('tmp');
281var tmpname = tmp.tmpNameSync({ template: '/tmp/tmp-XXXXXX' });
282console.log('Created temporary filename: ', tmpname);
283```
284
285## Graceful cleanup
286
287One may want to cleanup the temporary files even when an uncaught exception
288occurs. To enforce this, you can call the `setGracefulCleanup()` method:
289
290```javascript
291var tmp = require('tmp');
292
293tmp.setGracefulCleanup();
294```
295
296## Options
297
298All options are optional :)
299
300 * `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
301 * `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
302 * `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
303 * `template`: [`mkstemp`][3] like filename template, no default
304 * `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
305 * `tries`: how many times should the function try to get a unique filename before giving up, default `3`
306 * `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
307 * Please keep in mind that it is recommended in this case to call the provided `cleanupCallback` function manually.
308 * `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
309
310[1]: http://nodejs.org/
311[2]: https://www.npmjs.com/browse/depended/tmp
312[3]: http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html
313[4]: https://raszi.github.io/node-tmp/
314[5]: https://github.com/benjamingr/tmp-promise
Note: See TracBrowser for help on using the repository browser.