Unique-file-name NPM

Unique File Name

unique-file-name is a node module for creating file names. It can take filenames from untrusted sources such as user uploads and transform them into names which are:

Unique - UNF will check to see if a file already exists, and pick a new name if it does.
Safe - Names will not include special characters, and may be used unescaped as shell command arguments.
Recognizable - File names will look similar to their original form. Extensions can be preserved to allow files to be recognized by the OS.
Secure - With a random component, file names can be made reasonably unguessable.
Timestamped - Files and directories can be marked with numeric timestamps in units like year, month and millisecond.

Example

const unf = require('unique-file-name')
const namer = unf( {
  format: '%4Y-%M-%D/%16b_%6r%8e',
  dir: 'upload_directory'
})

var untrustedFileName = 'dir///~@!\'long\' file name with spaces and special chars!.mp4     '

// As Promise
namer( untrustedFileName )
  .then( function ( betterName ) {
    // betterName will look somethings like this:
    '2015-11-04/long_file_name_wi_a6BC9b.mp4'

    // The file will already exist in upload_directory/2015-11-04 as a zero-length placeholder.

  })

// With callback
namer( untrustedFileName, function(err, betterName ) {
  if(err) {
      console.log('An error occurred :('); }
  else {
      console..log('The unique filename is: ' + betterName);
  }
})

API

Functions

main ( options )

main ( options, filename, iteration, time, callback )

sync ( options, filename, iteration, time )

format ( format, filename, iteration, time )

random ( length )

Format

UNF's filename template format is similar to the standard printf format, but with very different keys. Tags with the following format will be replaced:

%[digits][.precision][tag]

Options

Object or string. If string, will resolve to { format: string }

dir - Base directory for output ( default: CWD )
format -
touch - Function used to create empty placeholder file, or false to not create them. function ( filename, cb ) Defaults to fs-extra.ensureFile or fs-extra.ensureFileSync.
exists - function used to check if file already exists, or false not to check. function ( filename, cb ). ( defaults: fs.exists or fs.existsSync )
UTC - Format timestamps in UTC rather than local time zone.