171 lines
5.2 KiB
Markdown
171 lines
5.2 KiB
Markdown
# temp-fs
|
|
|
|
[](https://travis-ci.org/jakwings/node-temp-fs)
|
|
[](http://badge.fury.io/js/temp-fs)
|
|
|
|
A temporary file and directory creator for io.js and Node.js™.
|
|
|
|
Just like raszi/node-tmp and bruce/node-temp, it can safely create temporary
|
|
files and directories without worrying a lot of about race conditions as long
|
|
as you don't do some tricky things. ;-) You can also let this module track the
|
|
files or directories you created and delete them when the program exits.
|
|
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install temp-fs
|
|
```
|
|
|
|
```javascript
|
|
var tempfs = require('temp-fs');
|
|
|
|
// Create a tempfile in the system-provided tempdir.
|
|
tempfs.open(function (err, file) {
|
|
if (err) { throw err; }
|
|
|
|
console.log(file.path, file.fd);
|
|
// async
|
|
file.unlink(function () {
|
|
console.log('File delected');
|
|
});
|
|
// sync
|
|
// No problem even if unlink() is called twice.
|
|
file.unlink();
|
|
});
|
|
|
|
// Create a tempdir in current directory.
|
|
tempfs.mkdir({
|
|
dir: '.',
|
|
recursive: true, // It and its content will be remove recursively.
|
|
track: true // Track this directory.
|
|
}, function (err, dir) {
|
|
if (err) { throw err; }
|
|
|
|
console.log(dir.path, dir.recursive);
|
|
throw new Error('Since it is tracked, tempfs will remove it for you.');
|
|
dir.unlink();
|
|
});
|
|
```
|
|
|
|
|
|
## APIs
|
|
|
|
### options
|
|
|
|
* `limit: Number`
|
|
|
|
The maximum number of chance to retry before throwing an error. It should
|
|
be a finite number. Default: 5
|
|
|
|
* `recursive: Boolean`
|
|
|
|
Whether `unlink()` should remove a directory recursively. Default: false
|
|
|
|
* `track: Boolean`
|
|
|
|
If set to `true`, let temp-fs manage the the current file/directory for you
|
|
even if the global tracking is off. If set to `false`, don't let temp-fs
|
|
manage it even if the global tracking is on. Otherwise, use the current
|
|
global setting.
|
|
|
|
* `mode: Number`
|
|
|
|
File mode (default: 0600) or directory mode (default: 0700) to use.
|
|
|
|
* `name: String`
|
|
|
|
If set, join the two paths `options.dir || tempfs.dir()` and
|
|
`options.name` together and use the result as the customized
|
|
filename/pathname.
|
|
|
|
* `dir: String`
|
|
|
|
Where to put the generated tempfile or tempdir. Also see `options.name`
|
|
above. Default: tempfs.dir()
|
|
|
|
* `prefix: String`
|
|
|
|
The prefix for the generated random name. Default: "tmp-"
|
|
|
|
* `suffix: String`
|
|
|
|
The suffix for the generated random name. Default: ""
|
|
|
|
* `template: String`
|
|
|
|
A string containing some capital letters Xs for substitution with random
|
|
characters. Then it is used as part of the filename/dirname. Just like what
|
|
you do with the `mktemp (3)` function in the C library.
|
|
|
|
### tempfs.track(on = true)
|
|
|
|
Use it to switch global files/directories tracking on or off. Turn it on if
|
|
you don't want to manually delete everything. When it is turned off, all
|
|
recorded files and directories will not be removed but still kept in case it
|
|
is turned on again before the program exits.
|
|
|
|
This switch does not affect manually tracked files through `options.track`.
|
|
They will be removed automatically on exit.
|
|
|
|
**Note: When an uncaught exception occurs, all tracked temporary files and
|
|
directories will be removed no matter it is on or off.**
|
|
|
|
### tempfs.dir()
|
|
|
|
Return the path of a system-provided tempdir as `require('os').tmpdir()` does.
|
|
You should not make any assumption about whether the path contains a trailing
|
|
path separator, or it is a real path. On most system it is not a fixed path,
|
|
and it can be changed by the user environment. When in doubt, check it first.
|
|
|
|
### tempfs.name([options])
|
|
|
|
Return a customized/random filename/dirname. Options are documented at
|
|
[options](#options).
|
|
|
|
### tempfs.open([options], [callback])
|
|
|
|
Try to open a unique tempfile asynchronously. The callback function receives
|
|
two arguments `error` and `file`. If `error` is null, `file` has these
|
|
properties:
|
|
|
|
* `path`: The absolute path to the tempfile.
|
|
* `fd`: An integer file descriptor.
|
|
* `unlink`: A special function for you to delete the file. If you invoke it
|
|
with a callback function, it will become asynchronous. If the file is not
|
|
tracked, it may throw when an error occurs or the first argument of the
|
|
callback function will be an Error object.
|
|
|
|
### tempfs.openSync([options]): file
|
|
|
|
The synchronous version of `tempfs.open`. It will throw when an error happens.
|
|
|
|
### tempfs.mkdir([options], [callback])
|
|
|
|
Try to create a new tempdir asynchronously. The callback function receives two
|
|
arguments `error` and `dir`. If `error` is null, `dir` has these properties:
|
|
|
|
* `path`: The absolute path to the tempdir.
|
|
* `recursive`: Whether unlink() will remove the tempdir recursively.
|
|
* `unlink`: A special function for you to remove the directory. If you
|
|
invoke it with a callback function, it will become asynchronous. If the
|
|
directory is not tracked, it may throw when an error occurs or the first
|
|
argument of the callback function will be an Error object.
|
|
|
|
### tempfs.mkdirSync([options]): dir
|
|
|
|
The synchronous version of `tempfs.mkdir`. It will throw when an error happens.
|
|
|
|
### tempfs.clear([callback])
|
|
|
|
Remove all tracked files and directories asynchronously.
|
|
|
|
### tempfs.clearSync()
|
|
|
|
Remove all tracked files and directories synchronously.
|
|
|
|
|
|
## License
|
|
|
|
The MIT License (MIT)
|