unique-file-name

1.0.1 • Public • Published

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]

Tags

Filename

  • B - Basename of file
  • b - Basename of file, slugified.
  • F - Filename with extension
  • f - Filename with extension, slugified.
  • E - Extname of file, including '.'
  • e - Extname of file, slugified.
  • P - Dirname of file.
  • p - Dirname of file, slugified.

Index

  • i - integer counter, starting from 0.
  • z - hex counter

Date

  • Y - Year
  • M - Month [1-12]
  • D - Day of month [1-31]
  • h - Hour [0-23]
  • m - Minute [0-59]
  • s - Second [0-59]. Use %.3s to include fractional component.
  • T - Full JSON date ('1961-04-12T13:07:00.000Z')
  • t - Timestamp in milliseconds since the unix epoch

Misc

  • r - Random string of characters [A-Za-z0-9]

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.

Recipes

%Y%M%D/%16b%.i%8e

Camera_%10T/%h%m%0.4s.png

Versions

Current Tags

VersionDownloads (Last 7 Days)Tag
1.0.18latest

Version History

VersionDownloads (Last 7 Days)Published
1.0.18
1.0.00
0.1.750
0.1.60
0.1.50
0.1.40
0.1.30
0.1.20
0.1.00
0.0.01

Package Sidebar

Install

npm i unique-file-name

Weekly Downloads

59

Version

1.0.1

License

BSD-2-Clause

Unpacked Size

27.3 kB

Total Files

17

Last publish

Collaborators

  • koopero