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

    Install

    npm i unique-file-name

    DownloadsWeekly Downloads

    88

    Version

    1.0.1

    License

    BSD-2-Clause

    Unpacked Size

    27.3 kB

    Total Files

    17

    Last publish

    Collaborators

    • koopero