Options
All
  • Public
  • Public/Protected
  • All
Menu

Class that contains the most common file system interaction functionalities

Hierarchy

  • FilesManager

Index

Constructors

constructor

  • new FilesManager(fs: any, os: any, path: any, process: any, crypto: any): FilesManager
  • Typescript / Javascript is a bit special regarding file system operations. If we run our application in a browser environment, we won't be able to access the file system, so this class will only work in a server side environment (nodejs).

    This constructor requires some node modules to work, which are passed as dependencies

    Parameters

    • fs: any

      A node fs module instance (const fs = require('fs'))

    • os: any

      A node os module instance (const os = require('os'))

    • path: any

      A node path module instance (const path = require('path'))

    • process: any

      A node process module instance

    • crypto: any

    Returns FilesManager

    A FilesManager instance

Properties

Private _tempDirectoriesToDelete

_tempDirectoriesToDelete: string[] = []

Stores a list of paths to temporary folders that must be removed on application execution end.

Private crypto

crypto: any

Private fs

fs: any

A node fs module instance (const fs = require('fs'))

Private os

os: any

A node os module instance (const os = require('os'))

Private path

path: any

A node path module instance (const path = require('path'))

Private process

process: any

A node process module instance

Methods

Private _generateUniqueNameAux

  • _generateUniqueNameAux(i: number, desiredName: string, text: string, separator: string, isPrefix: boolean): string
  • Auxiliary method that is used by the findUniqueFileName and findUniqueDirectoryName methods

    Parameters

    • i: number

      Current index for the name generation

    • desiredName: string

      Desired name as used on the parent method

    • text: string

      text name as used on the parent method

    • separator: string

      separator name as used on the parent method

    • isPrefix: boolean

      isPrefix name as used on the parent method

    Returns string

    The generated name

copyDirectory

  • copyDirectory(sourcePath: string, destPath: string, destMustBeEmpty?: boolean): boolean
  • Copy all the contents from a source directory to a destination one (Both source and destination paths must exist).

    Any source files that exist on destination will be overwritten without warning. Files that exist on destination but not on source won't be modified, removed or altered in any way.

    throws

    Error

    Parameters

    • sourcePath: string

      The full path to the source directory where files and folders to copy exist

    • destPath: string

      The full path to the destination directory where files and folders will be copied

    • Default value destMustBeEmpty: boolean = true

      if set to true, an exception will be thrown if the destination directory is not empty.

    Returns boolean

    True if copy was successful, false otherwise

copyFile

  • copyFile(sourcePath: string, destPath: string): boolean
  • Copies a file from a source location to the defined destination If the destination file already exists, it will be overwritten.

    Parameters

    • sourcePath: string

      The full path to the source file that must be copied (including the filename itself).

    • destPath: string

      The full path to the destination where the file must be copied (including the filename itself).

    Returns boolean

    Returns true on success or false on failure.

createDirectory

  • createDirectory(path: string, recursive?: boolean): boolean
  • Create a directory at the specified filesystem path

    Parameters

    • path: string

      The full path to the directoy we want to create. For example: c:\apps\my_new_folder

    • Default value recursive: boolean = false

      Allows the creation of nested directories specified in the pathname. Defaults to false.

    Returns boolean

    Returns true on success or false if the folder already exists (an exception may be thrown if a file exists with the same name or folder cannot be created).

createTempDirectory

  • createTempDirectory(desiredName: string, deleteOnExecutionEnd?: boolean): string
  • Create a TEMPORARY directory on the operating system tmp files location, and get us the full path to access it. OS should take care of its removal but it is not assured, so it is recommended to make sure all the tmp data is deleted after using it (This is specially important if the tmp folder contains sensitive data).

    Parameters

    • desiredName: string

      A name we want for the new directory to be created. If name is not available, a unique one (based on the provided desired name) will be generated automatically.

    • Default value deleteOnExecutionEnd: boolean = true

      Defines if the generated temp folder must be deleted after the current application execution finishes. Note that when files inside the folder are still used by the app or OS, exceptions or problems may happen, and it is not 100% guaranteed that the folder will be always deleted. So it is better to always handle the temporary folder removal in our code

    Returns string

    The full path to the newly created temporary directory, including the directory itself (without a trailing slash). For example: C:\Users\Me\AppData\Local\Temp\MyDesiredName

createTempFile

  • createTempFile(): void
  • TODO - translate from php

    Returns void

deleteDirectory

  • deleteDirectory(path: string, deleteDirectoryItself?: boolean): boolean
  • Delete a directory from the filesystem and return a boolean telling if the directory delete succeeded or not Note: All directory contents, folders and files will be also removed.

    Parameters

    • path: string

      The path to the directory

    • Default value deleteDirectoryItself: boolean = true

      Set it to true if the specified directory must also be deleted.

    Returns boolean

    Returns true on success or false on failure.

deleteFile

  • deleteFile(path: string): boolean
  • Delete a filesystem file.

    Parameters

    • path: string

      The file filesystem path

    Returns boolean

    Returns true on success or false on failure.

deleteFiles

  • deleteFiles(paths: string[]): boolean
  • Delete a list of filesystem files.

    Parameters

    • paths: string[]

      A list of filesystem paths to delete

    Returns boolean

    Returns true on success or false if any of the files failed to be deleted

dirSep

  • dirSep(): any
  • Gives us the current OS directory separator character, so we can build cross platform file paths

    Returns any

    The current OS directory separator character

findDirectoryItems

  • findDirectoryItems(path: string, searchRegexp: string, returnFormat?: string, searchItemsType?: string, depth?: number): string[]
  • Find all the elements on a directory which name matches the specified regexp pattern

    Parameters

    • path: string

      A directory where the search will be performed

    • searchRegexp: string

      A regular expression that files or folders must match to be included into the results. Here are some useful patterns:
      /..txt$/i - Match all items which name ends with '.txt' (case insensitive)
      /^some.
      ./ - Match all items which name starts with 'some'
      /text/ - Match all items which name contains 'text'
      /^file.txt$/ - Match all items which name is exactly 'file.txt' /^..(jpg|jpeg|png|gif)$/i - Match all items which name ends with .jpg,.jpeg,.png or .gif (case insensitive) /^(?!..(jpg|png|gif)$)/i - Match all items that do NOT end with .jpg, .png or .gif (case insensitive)

    • Default value returnFormat: string = "relative"

      Defines how will be returned the array of results. Three values are possible:

         - If set to 'name' each result element will contain its file (with extension) or folder name<br>
         - If set to 'relative' each result element will contain its file (with extension) or folder name plus its path relative to the search root<br>
         - If set to 'absolute' each result element will contain its file (with extension) or folder name plus its full OS absolute path
    • Default value searchItemsType: string = "both"

      Defines the type for the directory elements to search: 'files' to search only files, 'folders' to search only folders, 'both' to search on all the directory contents

    • Default value depth: number = -1

      Defines the maximum number of subfolders where the search will be performed:

         - If set to -1 the search will be performed on the whole folder contents<br>
         - If set to 0 the search will be performed only on the path root elements<br>
         - If set to 2 the search will be performed on the root, first and second depth level of subfolders

    Returns string[]

    A list formatted as defined in returnFormat, with all the elements that meet the search criteria

findUniqueDirectoryName

  • findUniqueDirectoryName(path: string, desiredName?: string, text?: string, separator?: string, isPrefix?: boolean): string | number
  • Search for a folder name that does not exist on the provided path.

    If we want to create a new folder inside another one without knowing for sure what does it contain, this method will guarantee us that we have a unique directory name that does not collide with any other folder or file that currently exists on the path.

    NOTE: This method does not create any folder or alter the given path in any way.

    Parameters

    • path: string

      The full path to the directoy we want to check for a unique folder name

    • Default value desiredName: string = ""

      We can specify a suggested name for the unique directory. This method will verify that it does not exist, or otherwise give us a name based on our desired one that is unique for the path

    • Default value text: string = ""

      Text that will be appended to the suggested name in case it already exists. For example: text='copy' will generate a result like 'NewFolder-copy' or 'NewFolder-copy-1' if a folder named 'NewFolder' exists

    • Default value separator: string = "-"

      String that will be used to join the suggested name with the text and the numeric file counter. For example: separator='---' will generate a result like 'NewFolder---copy---1' if a folder named 'NewFolder' already exists

    • Default value isPrefix: boolean = false

      Defines if the extra text that will be appended to the desired name will be placed after or before the name on the result. For example: isPrefix=true will generate a result like 'copy-1-NewFolder' if a folder named 'NewFolder' already exists

    Returns string | number

    A directory name that can be safely created on the specified path, cause no one exists with the same name (No path is returned by this method, only a directory name. For example: 'folder-1', 'directoryName-5', etc..).

findUniqueFileName

  • findUniqueFileName(path: string, desiredName?: string, text?: string, separator?: string, isPrefix?: boolean): string | number
  • Search for a file name that does not exist on the provided path.

    If we want to create a new file inside a folder without knowing for sure what does it contain, this method will guarantee us that we have a unique file name that does not collide with any other folder or file that currently exists on the path.

    NOTE: This method does not create any file or alter the given path in any way.

    Parameters

    • path: string

      The full path to the directoy we want to check for a unique file name

    • Default value desiredName: string = ""

      We can specify a suggested name for the unique file. This method will verify that it does not exist, or otherwise give us a name based on our desired one that is unique for the path

    • Default value text: string = ""

      Text that will be appended to the suggested name in case it already exists. For example: text='copy' will generate a result like 'NewFile-copy' or 'NewFile-copy-1' if a file named 'NewFile' exists

    • Default value separator: string = "-"

      String that will be used to join the suggested name with the text and the numeric file counter. For example: separator='---' will generate a result like 'NewFile---copy---1' if a file named 'NewFile' already exists

    • Default value isPrefix: boolean = false

      Defines if the extra text that will be appended to the desired name will be placed after or before the name on the result. For example: isPrefix=true will generate a result like 'copy-1-NewFile' if a file named 'NewFile' already exists

    Returns string | number

    A file name that can be safely created on the specified path, cause no one exists with the same name (No path is returned by this method, only a file name. For example: 'file-1', 'fileName-5', etc..).

getDirectoryList

  • getDirectoryList(path: string, sort?: string): string[]
  • Gives the list of items that are stored on the specified folder. It will give files and directories, and each element will be the item name, without the path to it. The contents of any subfolder will not be listed. We must call this method for each child folder if we want to get it's list. (The method ignores the . and .. items if exist).

    Parameters

    • path: string

      Full path to the directory we want to list

    • Default value sort: string = ""

      Specifies the sort for the result:
        '' will not sort the result.
        'nameAsc' will sort the result by filename ascending.   'nameDesc' will sort the result by filename descending.   'mDateAsc' will sort the result by modification date ascending.   'mDateDesc' will sort the result by modification date descending.

    Returns string[]

    The list of item names inside the specified path sorted as requested, or an empty array if no items found inside the folder.

getDirectorySize

  • getDirectorySize(path: string): number
  • Calculate the full size in bytes for a specified folder and all its contents.

    Parameters

    • path: string

      Full path to the directory we want to calculate its size

    Returns number

    the size of the file in bytes. An exception will be thrown if value cannot be obtained

getFileSize

  • getFileSize(path: string): any
  • Get the size from a file

    Parameters

    • path: string

      The file full path, including the file name and extension

    Returns any

    int the size of the file in bytes. An exception will be thrown if value cannot be obtained

isDirectory

  • isDirectory(path: any): any
  • Check if the specified path is a directory or not.

    Parameters

    • path: any

      An Operating system path to test

    Returns any

    true if the path exists and is a directory, false otherwise.

isDirectoryEmpty

  • isDirectoryEmpty(path: string): boolean
  • Checks if the specified folder is empty

    Parameters

    • path: string

      The path to the directory we want to check

    Returns boolean

    True if directory is empty, false if not. If it does not exist or cannot be read, an exception will be generated

isDirectoryEqualTo

  • isDirectoryEqualTo(path1: string, path2: string): boolean
  • Check if two directories contain exactly the same folder structure and files.

    Parameters

    • path1: string

      The full path to the first directory to compare

    • path2: string

      The full path to the second directory to compare

    Returns boolean

    true if both paths are valid directories and contain exactly the same files and folders tree.

isFile

  • isFile(path: string): any
  • Check if the specified path is a file or not.

    Parameters

    • path: string

      An Operating system path to test

    Returns any

    true if the path exists and is a file, false otherwise.

isFileEqualTo

  • isFileEqualTo(file1: string, file2: string): boolean
  • Check if two provided files are identical

    throws

    Error

    Parameters

    • file1: string

      The first file to compare

    • file2: string

      The second file to compare

    Returns boolean

    True if both files are identical, false otherwise

mergeFiles

  • mergeFiles(sourcePaths: string[], destFile: string, separator?: string): boolean
  • Concatenate all the provided files, one after the other, into a single destination file.

    Parameters

    • sourcePaths: string[]

      A list with the full paths to the files we want to join. The result will be generated in the same order.

    • destFile: string

      The full path where the merged file will be stored, including the full file name (will be overwitten if exists).

    • Default value separator: string = ""

      An optional string that will be concatenated between each file content. We can for example use "\n\n" to create some empty space between each file content

    Returns boolean

    True on success or false on failure.

readFile

  • readFile(path: string): any
  • Read and return the content of a file. Not suitable for big files (More than 5 MB) cause the script memory may get full and the execution fail

    Parameters

    • path: string

      An Operating system full or relative path containing some file

    Returns any

    The file contents (binary or string). If the file is not found or cannot be read, an exception will be thrown.

readFileBuffered

  • readFileBuffered(path: string, downloadRateLimit?: number): void
  • Reads a file and performs a buffered output to the browser, by sending it as small fragments.
    This method is mandatory with big files, as reading the whole file to memory will cause the script or RAM to fail.

    Adapted from code suggested at: http://php.net/manual/es/function.readfile.php

    Parameters

    • path: string

      The file full path

    • Default value downloadRateLimit: number = 0

      If we want to limit the download rate of the file, we can do it by setting this value to > 0. For example: 20.5 will set the file download rate to 20,5 kb/s

    Returns void

    the number of bytes read from the file.

renameDirectory

  • renameDirectory(sourcePath: string, destPath: string): boolean
  • Renames a directory.

    Parameters

    • sourcePath: string

      The full path to the source directory that must be renamed (including the directoy itself).

    • destPath: string

      The full path to the new directoy name (including the directoy itself). It must not exist.

    Returns boolean

    boolean true on success or false on failure.

renameFile

  • renameFile(sourcePath: string, destPath: string): boolean
  • Renames a file.

    Parameters

    • sourcePath: string

      The full path to the source file that must be renamed (including the filename itself).

    • destPath: string

      The full path to the new file name (including the filename itself). It must not exist.

    Returns boolean

    True on success or false on failure.

saveFile

  • saveFile(pathToFile: string, data?: string, append?: boolean): boolean
  • Writes the specified data to a physical file, which will be created (if it does not exist) or overwritten without warning. This method can be used to create a new empty file, a new file with any contents or to overwrite an existing one.

    We must check for file existence before executing this method if we don't want to inadvertently replace existing files.

    see

    FilesManager.isFile

    Parameters

    • pathToFile: string

      The path including full filename where data will be saved. File will be created or overwritten without warning.

    • Default value data: string = ""

      Any information to save on the file.

    • Default value append: boolean = false

      Set it to true to append the data to the end of the file instead of overwritting it. File will be created if it does not exist, even with append set to true.

    Returns boolean

    True on success or false on failure.

syncDirectories

  • syncDirectories(): void
  • TODO - translate from php

    Returns void

Generated using TypeDoc