1 | node-temp
|
2 | =========
|
3 |
|
4 | Temporary files, directories, and streams for Node.js.
|
5 |
|
6 | Handles generating a unique file/directory name under the appropriate
|
7 | system temporary directory, changing the file to an appropriate mode,
|
8 | and supports automatic removal (if asked)
|
9 |
|
10 | `temp` has a similar API to the `fs` module.
|
11 |
|
12 | Node.js Compatibility
|
13 | ---------------------
|
14 |
|
15 | Supports v4.0.0+.
|
16 |
|
17 | [![Build Status](https://travis-ci.org/bruce/node-temp.png)](https://travis-ci.org/bruce/node-temp)
|
18 |
|
19 | Please let me know if you have problems running it on a later version of Node.js or
|
20 | have platform-specific problems.
|
21 |
|
22 | Installation
|
23 | ------------
|
24 |
|
25 | Install it using [npm](http://github.com/isaacs/npm):
|
26 |
|
27 | $ npm install temp
|
28 |
|
29 | Or get it directly from:
|
30 | http://github.com/bruce/node-temp
|
31 |
|
32 | Synopsis
|
33 | --------
|
34 |
|
35 | You can create temporary files with `open` and `openSync`, temporary
|
36 | directories with `mkdir` and `mkdirSync`, or you can get a unique name
|
37 | in the system temporary directory with `path`.
|
38 |
|
39 | Working copies of the following examples can be found under the
|
40 | `examples` directory.
|
41 |
|
42 | ### Temporary Files
|
43 |
|
44 | To create a temporary file use `open` or `openSync`, passing
|
45 | them an optional prefix, suffix, or both (see below for details on
|
46 | affixes). The object passed to the callback (or returned) has
|
47 | `path` and `fd` keys:
|
48 |
|
49 | ```javascript
|
50 | { path: "/path/to/file",
|
51 | , fd: theFileDescriptor
|
52 | }
|
53 | ```
|
54 |
|
55 | In this example we write to a temporary file and call out to `grep` and
|
56 | `wc -l` to determine the number of time `foo` occurs in the text. The
|
57 | temporary file is chmod'd `0600` and cleaned up automatically when the
|
58 | process at exit (because `temp.track()` is called):
|
59 |
|
60 | ```javascript
|
61 | var temp = require('temp'),
|
62 | fs = require('fs'),
|
63 | util = require('util'),
|
64 | exec = require('child_process').exec;
|
65 |
|
66 | // Automatically track and cleanup files at exit
|
67 | temp.track();
|
68 |
|
69 | // Fake data
|
70 | var myData = "foo\nbar\nfoo\nbaz";
|
71 |
|
72 | // Process the data (note: error handling omitted)
|
73 | temp.open('myprefix', function(err, info) {
|
74 | if (!err) {
|
75 | fs.write(info.fd, myData);
|
76 | fs.close(info.fd, function(err) {
|
77 | exec("grep foo '" + info.path + "' | wc -l", function(err, stdout) {
|
78 | util.puts(stdout.trim());
|
79 | });
|
80 | });
|
81 | }
|
82 | });
|
83 | ```
|
84 |
|
85 | ### Want Cleanup? Make sure you ask for it.
|
86 |
|
87 | As noted in the example above, if you want temp to track the files and
|
88 | directories it creates and handle removing those files and directories
|
89 | on exit, you must call `track()`. The `track()` function is chainable,
|
90 | and it's recommended that you call it when requiring the module.
|
91 |
|
92 | ```javascript
|
93 | var temp = require("temp").track();
|
94 | ```
|
95 |
|
96 | Why is this necessary? In pre-0.6 versions of temp, tracking was
|
97 | automatic. While this works great for scripts and
|
98 | [Grunt tasks](http://gruntjs.com/), it's not so great for long-running
|
99 | server processes. Since that's arguably what Node.js is _for_, you
|
100 | have to opt-in to tracking.
|
101 |
|
102 | But it's easy.
|
103 |
|
104 | #### Cleanup anytime
|
105 |
|
106 | When tracking, you can run `cleanup()` and `cleanupSync()` anytime
|
107 | (`cleanupSync()` will be run for you on process exit). An object will
|
108 | be returned (or passed to the callback) with cleanup counts and
|
109 | the file/directory tracking lists will be reset.
|
110 |
|
111 | ```javascript
|
112 | > temp.cleanupSync();
|
113 | { files: 1,
|
114 | dirs: 0 }
|
115 | ```
|
116 |
|
117 | ```javascript
|
118 | > temp.cleanup(function(err, stats) {
|
119 | console.log(stats);
|
120 | });
|
121 | { files: 1,
|
122 | dirs: 0 }
|
123 | ```
|
124 |
|
125 | Note: If you're not tracking, an error ("not tracking") will be passed
|
126 | to the callback.
|
127 |
|
128 | ### Temporary Directories
|
129 |
|
130 | To create a temporary directory, use `mkdir` or `mkdirSync`, passing
|
131 | it an optional prefix, suffix, or both (see below for details on affixes).
|
132 |
|
133 | In this example we create a temporary directory, write to a file
|
134 | within it, call out to an external program to create a PDF, and read
|
135 | the result. While the external process creates a lot of additional
|
136 | files, the temporary directory is removed automatically at exit (because
|
137 | `temp.track()` is called):
|
138 |
|
139 | ```javascript
|
140 | var temp = require('temp'),
|
141 | fs = require('fs'),
|
142 | util = require('util'),
|
143 | path = require('path'),
|
144 | exec = require('child_process').exec;
|
145 |
|
146 | // Automatically track and cleanup files at exit
|
147 | temp.track();
|
148 |
|
149 | // For use with ConTeXt, http://wiki.contextgarden.net
|
150 | var myData = "\\starttext\nHello World\n\\stoptext";
|
151 |
|
152 | temp.mkdir('pdfcreator', function(err, dirPath) {
|
153 | var inputPath = path.join(dirPath, 'input.tex')
|
154 | fs.writeFile(inputPath, myData, function(err) {
|
155 | if (err) throw err;
|
156 | process.chdir(dirPath);
|
157 | exec("texexec '" + inputPath + "'", function(err) {
|
158 | if (err) throw err;
|
159 | fs.readFile(path.join(dirPath, 'input.pdf'), function(err, data) {
|
160 | if (err) throw err;
|
161 | sys.print(data);
|
162 | });
|
163 | });
|
164 | });
|
165 | });
|
166 | ```
|
167 |
|
168 | ### Temporary Streams
|
169 |
|
170 | To create a temporary WriteStream, use 'createWriteStream', which sits
|
171 | on top of `fs.createWriteStream`. The return value is a
|
172 | `fs.WriteStream` with a `path` property containing the temporary file
|
173 | path for the stream. The `path` is registered for removal when
|
174 | `temp.cleanup` is called (because `temp.track()` is called).
|
175 |
|
176 | ```javascript
|
177 | var temp = require('temp');
|
178 |
|
179 | // Automatically track and cleanup files at exit
|
180 | temp.track();
|
181 |
|
182 | var stream = temp.createWriteStream();
|
183 | // stream.path contains the temporary file path for the stream
|
184 | stream.write("Some data");
|
185 | // Maybe do some other things
|
186 | stream.end();
|
187 | ```
|
188 |
|
189 | ### Affixes
|
190 |
|
191 | You can provide custom prefixes and suffixes when creating temporary
|
192 | files and directories. If you provide a string, it is used as the prefix
|
193 | for the temporary name. If you provide an object with `prefix`,
|
194 | `suffix` and `dir` keys, they are used for the temporary name.
|
195 |
|
196 | Here are some examples:
|
197 |
|
198 | * `"aprefix"`: A simple prefix, prepended to the filename; this is
|
199 | shorthand for:
|
200 | * `{prefix: "aprefix"}`: A simple prefix, prepended to the filename
|
201 | * `{suffix: ".asuffix"}`: A suffix, appended to the filename
|
202 | (especially useful when the file needs to be named with specific
|
203 | extension for use with an external program).
|
204 | * `{prefix: "myprefix", suffix: "mysuffix"}`: Customize both affixes
|
205 | * `{dir: path.join(os.tmpdir(), "myapp")}`: default prefix and suffix
|
206 | within a new temporary directory.
|
207 | * `null`: Use the defaults for files and directories (prefixes `"f-"`
|
208 | and `"d-"`, respectively, no suffixes).
|
209 |
|
210 | In this simple example we read a `pdf`, write it to a temporary file with
|
211 | a `.pdf` extension, and close it.
|
212 |
|
213 | ```javascript
|
214 | var fs = require('fs'),
|
215 | temp = require('temp');
|
216 |
|
217 | fs.readFile('/path/to/source.pdf', function(err, data) {
|
218 | temp.open({suffix: '.pdf'}, function(err, info) {
|
219 | if (err) throw err;
|
220 | fs.write(info.fd, data);
|
221 | fs.close(info.fd, function(err) {
|
222 | if (err) throw err;
|
223 | // Do something with the file
|
224 | });
|
225 | });
|
226 | });
|
227 | ```
|
228 |
|
229 | ### Just a path, please
|
230 |
|
231 | If you just want a unique name in your temporary directory, use
|
232 | `path`:
|
233 |
|
234 | ```javascript
|
235 | var fs = require('fs');
|
236 | var tempName = temp.path({suffix: '.pdf'});
|
237 | // Do something with tempName
|
238 | ```
|
239 |
|
240 | Note: The file isn't created for you, and the mode is not changed -- and it
|
241 | will not be removed automatically at exit. If you use `path`, it's
|
242 | all up to you.
|
243 |
|
244 | Using it with Grunt
|
245 | -------------------
|
246 |
|
247 | If you want to use the module with [Grunt](http://gruntjs.com/), make sure you
|
248 | use `async()` in your Gruntfile:
|
249 |
|
250 | ```javascript
|
251 | module.exports = function (grunt) {
|
252 | var temp = require("temp");
|
253 | temp.track(); // Cleanup files, please
|
254 | grunt.registerTask("temptest", "Testing temp", function() {
|
255 |
|
256 | var done = this.async(); // Don't forget this!
|
257 |
|
258 | grunt.log.writeln("About to write a file...");
|
259 | temp.open('tempfile', function(err, info) {
|
260 | // File writing shenanigans here
|
261 | grunt.log.writeln("Wrote a file!")
|
262 |
|
263 | done(); // REALLY don't forget this!
|
264 |
|
265 | });
|
266 | });
|
267 | };
|
268 | ```
|
269 |
|
270 | For more information, see the [Grunt FAQ](http://gruntjs.com/frequently-asked-questions#why-doesn-t-my-asynchronous-task-complete).
|
271 |
|
272 | Testing
|
273 | -------
|
274 |
|
275 | ```sh
|
276 | $ npm test
|
277 | ```
|
278 |
|
279 | Contributing
|
280 | ------------
|
281 |
|
282 | You can find the repository at:
|
283 | http://github.com/bruce/node-temp
|
284 |
|
285 | Issues/Feature Requests can be submitted at:
|
286 | http://github.com/bruce/node-temp/issues
|
287 |
|
288 | I'd really like to hear your feedback, and I'd love to receive your
|
289 | pull-requests!
|
290 |
|
291 | Copyright
|
292 | ---------
|
293 |
|
294 | Copyright (c) 2010-2014 Bruce Williams. This software is licensed
|
295 | under the MIT License, see LICENSE for details.
|