Merge pull request #234 from raszi/gh-233

feat: stabilize tmp for v0.2.0 release

Author: raszi

.travis.yml

@@ -1,6 +1,7 @@
 language: node_js
 node_js:
  - "node"
+ - "13"
  - "12"
  - "11"
  - "10"

CHANGELOG.md

@@ -0,0 +1,119 @@
+# CHANGELOG
+
+## tmp v0.2.0
+
+- drop support for node version < v8.17.0
+
+ ***BREAKING CHANGE***
+ 
+ node versions < v8.17.0 are no longer supported. 
+
+- [#216](https://github.com/raszi/node-tmp/issues/216)
+
+ ***BREAKING CHANGE***
+
+ SIGINT handler has been removed. 
+
+ Users must install their own SIGINT handler and call process.exit() so that tmp's process 
+ exit handler can do the cleanup.
+ 
+ A simple handler would be
+ 
+ ```
+ process.on('SIGINT', process.exit);
+ ```
+
+- [#156](https://github.com/raszi/node-tmp/issues/156)
+
+ ***BREAKING CHANGE***
+
+ template option no longer accepts arbitrary paths. all paths must be relative to os.tmpdir().
+ the template option can point to an absolute path that is located under os.tmpdir().
+ this can now be used in conjunction with the dir option. 
+
+- [#207](https://github.com/raszi/node-tmp/issues/TBD)
+
+ ***BREAKING CHANGE***
+
+ dir option no longer accepts arbitrary paths. all paths must be relative to os.tmpdir().
+ the dir option can point to an absolute path that is located under os.tmpdir().
+
+- [#218](https://github.com/raszi/node-tmp/issues/TBD)
+
+ ***BREAKING CHANGE***
+
+ name option no longer accepts arbitrary paths. name must no longer contain a path and will always be made relative
+ to the current os.tmpdir() and the optional dir option.
+
+- [#197](https://github.com/raszi/node-tmp/issues/197)
+
+ ***BUG FIX***
+
+ sync cleanup callback must be returned when using the sync API functions.
+ 
+ fs.rmdirSync() must not be called with a second parameter that is a function.
+
+- [#176](https://github.com/raszi/node-tmp/issues/176)
+
+ ***BUG FIX***
+
+ fail early if no os.tmpdir() was specified.
+ previous versions of Electron did return undefined when calling os.tmpdir().
+ _getTmpDir() now tries to resolve the path returned by os.tmpdir().
+ 
+ now using rimraf for removing directory trees.
+
+- [#246](https://github.com/raszi/node-tmp/issues/246)
+
+ ***BUG FIX***
+
+ os.tmpdir() might return a value that includes single or double quotes,
+ similarly so the dir option, the template option and the name option
+
+- [#240](https://github.com/raszi/node-tmp/issues/240)
+
+ ***DOCUMENTATION***
+ 
+ better documentation for `tmp.setGracefulCleanup()`.
+
+- [#206](https://github.com/raszi/node-tmp/issues/206)
+
+ ***DOCUMENTATION***
+ 
+ document name option.
+
+- [#236](https://github.com/raszi/node-tmp/issues/236)
+
+ ***DOCUMENTATION***
+
+ document discardDescriptor option.
+
+- [#237](https://github.com/raszi/node-tmp/issues/237)
+
+ ***DOCUMENTATION***
+
+ document detachDescriptor option.
+
+- [#238](https://github.com/raszi/node-tmp/issues/238)
+
+ ***DOCUMENTATION***
+
+ document mode option.
+
+- [#175](https://github.com/raszi/node-tmp/issues/175)
+
+ ***DOCUMENTATION***
+
+ document unsafeCleanup option.
+
+
+### Miscellaneous
+
+- stabilized tests
+- general clean up
+- update jsdoc
+
+
+## Previous Releases
+
+- no information available

README.md

@@ -29,6 +29,8 @@ standard OS temporary directory, then you are free to override that as well.
 
 ## An Important Note on Compatibility
 
+See the [CHANGELOG](./CHANGELOG.md) for more information.
+
 ### Version 0.1.0
 
 Since version 0.1.0, all support for node versions < 0.10.0 has been dropped.
@@ -48,15 +50,6 @@ dependency to version 0.0.33.
 For node versions < 0.8 you must limit your node-tmp dependency to
 versions < 0.0.33.
 
-### Node Versions < 8.12.0
-
-The SIGINT handler will not work correctly with versions of NodeJS < 8.12.0.
-
-### Windows
-
-Signal handlers for SIGINT will not work. Pressing CTRL-C will leave behind
-temporary files and directories.
-
 ## How to install
 
 ```bash
@@ -72,7 +65,7 @@ Please also check [API docs][4].
 Simple temporary file creation, the file will be closed and unlinked on process exit.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
  if (err) throw err;
@@ -92,9 +85,9 @@ tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
 A synchronous version of the above.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var tmpobj = tmp.fileSync();
+const tmpobj = tmp.fileSync();
 console.log('File: ', tmpobj.name);
 console.log('Filedescriptor: ', tmpobj.fd);
 
@@ -115,7 +108,7 @@ Simple temporary directory creation, it will be removed on process exit.
 If the directory still contains items on process exit, then it won't be removed.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
  if (err) throw err;
@@ -135,9 +128,9 @@ you can pass the `unsafeCleanup` option when creating it.
 A synchronous version of the above.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var tmpobj = tmp.dirSync();
+const tmpobj = tmp.dirSync();
 console.log('Dir: ', tmpobj.name);
 // Manual cleanup
 tmpobj.removeCallback();
@@ -153,7 +146,7 @@ It is possible with this library to generate a unique filename in the specified
 directory.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.tmpName(function _tempNameGenerated(err, path) {
  if (err) throw err;
@@ -167,9 +160,9 @@ tmp.tmpName(function _tempNameGenerated(err, path) {
 A synchronous version of the above.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var name = tmp.tmpNameSync();
+const name = tmp.tmpNameSync();
 console.log('Created temporary filename: ', name);
 ```
 
@@ -180,9 +173,9 @@ console.log('Created temporary filename: ', name);
 Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
+tmp.file({ mode: 0o644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
  if (err) throw err;
 
  console.log('File: ', path);
@@ -195,9 +188,9 @@ tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileC
 A synchronous version of the above.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
+const tmpobj = tmp.fileSync({ mode: 0o644, prefix: 'prefix-', postfix: '.txt' });
 console.log('File: ', tmpobj.name);
 console.log('Filedescriptor: ', tmpobj.fd);
 ```
@@ -219,7 +212,7 @@ descriptor. Two options control how the descriptor is managed:
  longer needed.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.file({ discardDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
  if (err) throw err;
@@ -229,7 +222,7 @@ tmp.file({ discardDescriptor: true }, function _tempFileCreated(err, path, fd, c
 ```
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.file({ detachDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
  if (err) throw err;
@@ -246,9 +239,9 @@ tmp.file({ detachDescriptor: true }, function _tempFileCreated(err, path, fd, cl
 Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
+tmp.dir({ mode: 0o750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
  if (err) throw err;
 
  console.log('Dir: ', path);
@@ -260,9 +253,9 @@ tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path)
 Again, a synchronous version of the above.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
+const tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
 console.log('Dir: ', tmpobj.name);
 ```
 
@@ -275,7 +268,7 @@ require tmp to create your temporary filesystem object in a different place than
 default `tmp.tmpdir`.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.dir({ template: 'tmp-XXXXXX' }, function _tempDirCreated(err, path) {
  if (err) throw err;
@@ -289,9 +282,9 @@ tmp.dir({ template: 'tmp-XXXXXX' }, function _tempDirCreated(err, path) {
 This will behave similarly to the asynchronous version.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var tmpobj = tmp.dirSync({ template: 'tmp-XXXXXX' });
+const tmpobj = tmp.dirSync({ template: 'tmp-XXXXXX' });
 console.log('Dir: ', tmpobj.name);
 ```
 
@@ -303,9 +296,9 @@ The function accepts all standard options, e.g. `prefix`, `postfix`, `dir`, and
 You can also leave out the options altogether and just call the function with a callback as first parameter.
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
-var options = {};
+const options = {};
 
 tmp.tmpName(options, function _tempNameGenerated(err, path) {
  if (err) throw err;
@@ -320,19 +313,22 @@ The `tmpNameSync()` function works similarly to `tmpName()`.
 Again, you can leave out the options altogether and just invoke the function without any parameters.
 
 ```javascript
-var tmp = require('tmp');
-var options = {};
-var tmpname = tmp.tmpNameSync(options);
+const tmp = require('tmp');
+const options = {};
+const tmpname = tmp.tmpNameSync(options);
 console.log('Created temporary filename: ', tmpname);
 ```
 
 ## Graceful cleanup
 
-One may want to cleanup the temporary files even when an uncaught exception
-occurs. To enforce this, you can call the `setGracefulCleanup()` method:
+If graceful cleanup is set, tmp will remove all controlled temporary objects on process exit, otherwise the
+temporary objects will remain in place, waiting to be cleaned up on system restart or otherwise scheduled temporary
+object removal.
+
+To enforce this, you can call the `setGracefulCleanup()` method:
 
 ```javascript
-var tmp = require('tmp');
+const tmp = require('tmp');
 
 tmp.setGracefulCleanup();
 ```
@@ -341,16 +337,25 @@ tmp.setGracefulCleanup();
 
 All options are optional :)
 
- * `name`: a fixed name that overrides random name generation
- * `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
- * `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
- * `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
- * `template`: [`mkstemp`][3] like filename template, no default
- * `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
+ * `name`: a fixed name that overrides random name generation, the name must be relative and must not contain path segments
+ * `mode`: the file mode to create with, falls back to `0o600` on file creation and `0o700` on directory creation
+ * `prefix`: the optional prefix, defaults to `tmp`
+ * `postfix`: the optional postfix
+ * `template`: [`mkstemp`][3] like filename template, no default, can be either an absolute or a relative path that resolves 
+ to a relative path of the system's default temporary directory, must include `XXXXXX` once for random name generation, e.g.
+ 'foo/bar/XXXXXX'. Absolute paths are also fine as long as they are relative to os.tmpdir().
+ Any directories along the so specified path must exist, otherwise a ENOENT error will be thrown upon access, 
+ as tmp will not check the availability of the path, nor will it establish the requested path for you. 
+ * `dir`: the optional temporary directory that must be relative to the system's default temporary directory.
+ absolute paths are fine as long as they point to a location under the system's default temporary directory.
+ Any directories along the so specified path must exist, otherwise a ENOENT error will be thrown upon access, 
+ as tmp will not check the availability of the path, nor will it establish the requested path for you.
  * `tries`: how many times should the function try to get a unique filename before giving up, default `3`
  * `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`
  * In order to clean up, you will have to call the provided `cleanupCallback` function manually.
  * `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
+ * `detachDescriptor`: detaches the file descriptor, caller is responsible for closing the file, tmp will no longer try closing the file during garbage collection
+ * `discardDescriptor`: discards the file descriptor (closes file, fd is -1), tmp will no longer try closing the file during garbage collection
 
 [1]: http://nodejs.org/
 [2]: https://www.npmjs.com/browse/depended/tmp

appveyor.yml

@@ -7,6 +7,7 @@ environment:
  - nodejs_version: "10"
  - nodejs_version: "11"
  - nodejs_version: "12"
+ - nodejs_version: "13"
 
 install:
  - ps: Install-Product node $env:nodejs_version