node-tmp.node.txt

            
   NODE-TMP  
            



ALTERNATIVES ==>                  #Retrieving main temporary directory:
                                  #  - OS.tmpdir() (preferred)
                                  #  - temp-dir: OS.tmpdir() + FS.realpathSync()
                                  #     - used by tempfile and tempy
                                  #     - reason: TMPDIR is symlink on MacOS, i.e. __dirname (inside OS.tmpdir()) !== OS.tmpdir()
                                  #Retrieving temporary file path:
                                  #  - node-tmp (preferred): more features
                                  #  - tempfile: TMPDIR/UUID.EXT
                                  #  - tempy: TMPDIR/CRYPTO_RANDOM.EXT or TMPDIR/CRYPTO_RANDOM/STR
                                  #Creating temporary file:
                                  #  - node-tmp (preferred with Node): more features
                                  #  - temp-write: tempfile() + FS.writeFile|createWriteStream|mkdir()
                                  #  - node-temp: not maintained
                                  #  - deno temp (preferred with Deno): not many features

VERSION ==>                       #0.2.3

ASYNC ==>                         #Three interfaces:
                                  #  - FUNC()->PROMISE_VAL: using tmp-promise (3.0.3), which is a thin wrapper with the same members
                                  #  - FUNC(..., FUNC2(ERROR, VAL))
                                  #  - FUNCSync(...)->VAL
                                  #Differences:
                                  #  - setGracefulCleanup() is always sync
                                  #  - OBJ returned by file|dir():
                                  #     - cleanup() -> removeCallback() with sync
                                  #     - passed as FUNC(ERROR, OBJ.name, OBJ.fs, OBJ.cleanup) with callbacks
                                  #  - withFile|withDir(): only with promises

tmpName([OPTS])                   #Returns path (does not create file)
 ->PROMISE_'TMPDIR/FILENAME'      #By default:
                                  #  - TMPDIR is OS.tmpdir() or OPTS.tmpdir
                                  #  - FILENAME is `${OPTS.prefix}${PROCESS.pid}${RANDOM}${OPTS.postfix}`
                                  #RANDOM is [a-zA-Z0-9] using CRYPTO.randomBytes()
                                  #Throws if file already exists
                                  #OPTS:
                                  #  - dir 'TMPDIR' (always relative to TMPDIR)
                                  #  - name 'FILENAME'
                                  #  - prefix STR (def: 'tmp')
                                  #  - postfix STR (def: '')
                                  #  - template '[SUBDIR/]FILENAME': must contain 'XXXXXX', replaced with RANDOM
                                  #  - tries NUM (def: 1 if OPTS.name defined, 3 otherwise): how many times to retry checking for file existence

file([OPTS])->PROMISE_OBJ         #Create temporary file
                                  #Returns OBJ:
                                  #  - name '[SUBDIR/]FILENAME'
                                  #  - fd NUM
                                  #  - cleanup([FUNC([ERROR])]): remove file
                                  #OPTS:
                                  #  - like tmpName()
                                  #  - mode NUM (def: 0o600)
                                  #  - discardDescriptor BOOL (def: false): close file descriptor right away
                                  #  - detachDescriptor BOOL: if false (def), close file descriptor on OBJ.removeCallback()
                                  #  - keep BOOL (def: false)
dir([OPTS])->PROMISE_OBJ          #Same for directory.
                                  #Def OPTS.mode is 0o700
                                  #Additional OPTS:
                                  #  - unsafeCleanup BOOL: if false (def), do not allow cleanup() if directory not empty

withFile|Dir
 (FUNC(OBJ)->PROMISE_VAL[, OPTS])
 ->PROMISE_VAL                    #Same as file|dir() except performs OBJ.cleanup() after FUNC() done
setGracefulCleanup()              #On process.on('exit|SIGINT'), remove all files created with file|dir()
                                  #  - unless OPTS.keep true was used