turbodepot-node

/** * TurboDepot is a general purpose multi storage library (ORM, Logs, Users, Files, Objects) * * Website : -> https://turboframework.org/en/libs/turbodepot * License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License. * License Url : -> http://www.apache.org/licenses/LICENSE-2.0 * CopyRight : -> Copyright 2019 Edertone Advanded Solutions (08211 Castellar del Vallès, Barcelona). http://www.edertone.com */ /** * Files manager class */ export declare class FilesManager { /** * @see FilesManager.constructor */ private _rootPath; /** * Stores the NodeJs fs instance */ private fs; /** * Stores the NodeJs os instance */ private os; /** * Stores the NodeJs path instance */ private path; /** * Stores the NodeJs crypto instance */ private crypto; /** * Manager class that contains the most common file system interaction functionalities * * @param rootPath If we want to use an existing directory as the base path for all the methods on this class, we can define here * a full OS filesystem path to it. Setting this value means all the file operations will be based on that directory. * * @return A FilesManager instance */ constructor(rootPath?: string); /** * Gives us the current OS directory separator character, so we can build cross platform file paths * * @return The current OS directory separator character */ dirSep(): any; /** * Tells if the provided string represents a relative or absolute file system path (Windows or Linux). * * Note that this method doesn't check if the path is valid or points to an existing file or directory. * * @return True if the provided path is absolute, false if it is relative */ isPathAbsolute(path: string): boolean; /** * Check if the specified path is a file or not. * * @param path An Operating system absolute or relative path to test * * @return true if the path exists and is a file, false otherwise. */ isFile(path: string): any; /** * Check if two provided files are identical * * @param pathToFile1 Absolute or relative path to the first file to compare * @param pathToFile2 Absolute or relative path to the second file to compare * * @throws Error * * @return True if both files are identical, false otherwise */ isFileEqualTo(pathToFile1: string, pathToFile2: string): boolean; /** * Check if the specified path is a directory or not. * * @param path An Operating system absolute or relative path to test * * @return true if the path exists and is a directory, false otherwise. */ isDirectory(path: any): any; /** * Check if two directories contain exactly the same folder structure and files. * * @param path1 Absolute or relative path to the first directory to compare * @param path2 Absolute or relative path to the second directory to compare * * @return true if both paths are valid directories and contain exactly the same files and folders tree. */ isDirectoryEqualTo(path1: string, path2: string): boolean; /** * Checks if the specified folder is empty * * @param path Absolute or relative path to the directory we want to check * * @return True if directory is empty, false if not. If it does not exist or cannot be read, an exception will be generated */ isDirectoryEmpty(path: string): boolean; /** * Count elements on the specified directory based on their type or specific match with regular expressions. * With this method you can count files, directories, both or any items that match more complex regular expressions. * * @see FilesManager.findDirectoryItems * * @param path Absolute or relative path where the counting will be performed * * @param searchItemsType Defines the type for the directory elements to count: 'files' to count only files, 'folders' * to count only folders, 'both' to count on all the directory contents * * @param depth Defines the maximum number of subfolders where the count will be performed: * - If set to -1 the count will be performed on the whole folder contents * - If set to 0 the count will be performed only on the path root elements * - If set to 2 the count will be performed on the root, first and second depth level of subfolders * * @param searchRegexp A regular expression that files or folders must match to be included * into the results. See findDirectoryItems() docs for pattern examples * * @param excludeRegexp A regular expression that will exclude all the results that match it from the count * * @return The total number of elements that match the specified criteria inside the specified path */ countDirectoryItems(path: string, searchItemsType?: string, depth?: number, searchRegexp?: RegExp, excludeRegexp?: string): number; /** * Find all the elements on a directory that match a specific regexp pattern * * @param path Absolute or relative path where the search will be performed * * @param searchRegexp A regular expression that files or folders must match to be included * into the results (Note that search is dependant on the searchMode parameter to search only in the item name or the full path). * Here are some useful patterns: * /.*\.txt$/i - Match all items which end with '.txt' (case insensitive) * /^some.*./ - Match all items which start with 'some' * /text/ - Match all items which contain 'text' * /^file\.txt$/ - Match all items which are exactly 'file.txt' * /^.*\.(jpg|jpeg|png|gif)$/i - Match all items which end 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) * * @param returnFormat Defines how the array of results will be returned. 4 values are possible: * 'relative' - Each result element will contain the path relative to the search root including the file (with extension) or folder name * 'absolute' - Each result element will contain the full OS absolute path including the file (with extension) or folder name * 'name' - Each result element will contain its file (with extension) or folder name * 'name-noext' - Each result element will contain its file (without extension) or folder name * * @param searchItemsType 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 * * @param depth Defines the maximum number of subfolders where the search will be performed: * - If set to -1 (default) the search will be performed on the whole folder contents * - If set to 0 the search will be performed only on the path root elements * - If set to N the search will be performed on the root, first and N depth level of subfolders * * @param excludeRegexp A regular expression that will exclude all the results that match when tested against the item full OS absolute path * * @param searchMode Defines how searchRegexp will be used to find matches: * - If set to 'name' (default) The regexp will be tested only against the file or folder name * - If set to 'absolute' The regexp will be tested against the full OS absolute path of the file or folder * * @return A list formatted as defined in returnFormat, with all the elements that meet the search criteria, sorted ascending */ findDirectoryItems(path: string, searchRegexp: string | RegExp, returnFormat?: string, searchItemsType?: string, depth?: number, excludeRegexp?: string | RegExp, searchMode?: string): string[]; /** * 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. * * @param path Absolute or relative path to the directoy we want to check for a non existant folder name * @param desiredName This is the folder name that we would like to be available on the provided path. This method will verify * that it does not exist, or otherwise give us a name based on the desired one that is available on the path. If we provide * here an empty value, the method will take care of providing the non existant directory name we need. * @param text 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 * @param separator 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 * @param isPrefix 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 * * @return 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..). */ findUniqueDirectoryName(path: string, desiredName?: string, text?: string, separator?: string, isPrefix?: boolean): string; /** * 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. * * NOTICE: This method does not create any file or alter the given path in any way. * * @param path Absolute or relative path to the directoy we want to check for a unique file name * @param desiredName 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 * @param text 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 * @param separator 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 * @param isPrefix 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 * * @return 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..). */ findUniqueFileName(path: string, desiredName?: string, text?: string, separator?: string, isPrefix?: boolean): string | number; /** * Create a directory at the specified filesystem path * * @param path Absolute or relative path to the directoy we want to create. For example: c:\apps\my_new_folder * @param recursive Allows the creation of nested directories specified in the path. Defaults to false. * * @throws An exception will be thrown if a file exists with the same name or folder cannot be created (If the folder already * exists, no exception will be thrown). * * @return True on success or false if the folder already exists. */ createDirectory(path: string, recursive?: boolean): boolean; /** * Obtain the full path to the current operating system temporary folder location. * It will be correctly formated and without any trailing separator character. */ getOSTempDirectory(): 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). * * @param desiredName A name we want for the new directory to be created. If name exists on the system temporary folder, a unique one * (based on the desired one) will be generated automatically. We can also leave this value empty to let the method * calculate it. * @param deleteOnExecutionEnd True by default. Defines if the generated temp folder must be deleted after the current application execution finishes. * Note that when files inside the folder are locked 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 a good idea to leave this flag * to true and also handle the temporary folder removal in our code by ourselves. There won't be any problem if we * delete the folder before a delete is attempted on execution end. * * @return 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 */ createTempDirectory(desiredName: string, deleteOnExecutionEnd?: boolean): string; /** * Aux property that globally stores the list of all paths to temporary folders that must be removed when application execution ends. * This is defined static so only one shared property exists for all the FilesManager instances, and therefore we prevent memory leaks * by using also a single process 'exit' event listener */ private static _tempDirectoriesToDelete; /** * 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). * * @param path Absolute or relative path to the directory we want to list * @param sort Specifies the sort for the result: * &emsp;&emsp;'' will not sort the result. * &emsp;&emsp;'nameAsc' will sort the result by filename ascending. * &emsp;&emsp;'nameDesc' will sort the result by filename descending. * &emsp;&emsp;'mDateAsc' will sort the result by modification date ascending. * &emsp;&emsp;'mDateDesc' will sort the result by modification date descending. * * @return The list of item names inside the specified path sorted as requested, or an empty array if no items found inside the folder. */ getDirectoryList(path: string, sort?: string): string[]; /** * Calculate the full size in bytes for a specified folder and all its contents. * * @param path Absolute or relative path to the directory we want to calculate its size * * @return the size of the file in bytes. An exception will be thrown if value cannot be obtained */ getDirectorySize(path: string): number; /** * 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. * * @param sourcePath Absolute or relative path to the source directory where files and folders to copy exist * @param destPath Absolute or relative path to the destination directory where files and folders will be copied * @param destMustBeEmpty if set to true, an exception will be thrown if the destination directory is not empty. * * @throws Error * * @return True if copy was successful, false otherwise */ copyDirectory(sourcePath: string, destPath: string, destMustBeEmpty?: boolean): boolean; /** * This method performs a one way sync process which consists in applying the minimum modifications to the destination path * that will guarantee that it is an exact copy of the source path. Any files or folders that are identical on both provided paths * will be left untouched * * @param sourcePath Absolute or relative path to the source directory where files and folders to mirror exist * @param destPath Absolute or relative path to the destination directory that will be modified to exactly match the source one * @param timeout The amount of seconds that this method will be trying to delete or modify a file in case it is blocked * by the OS or temporarily not accessible. If the file can't be deleted after the given amount of seconds, an exception * will be thrown. * * @throws Error in case any of the necessary file operations fail * * @return True on success */ mirrorDirectory(sourcePath: string, destPath: string, timeout?: number): boolean; /** * TODO - translate from php */ syncDirectories(): void; /** * Renames a directory. * * @param sourcePath Absolute or relative path to the source directory that must be renamed (including the directoy itself). * @param destPath Absolute or relative path to the new directoy name (including the directoy itself). It must not exist. * @param timeout The amount of seconds that this method will be trying to rename the specified directory in case it is blocked * by the OS or temporarily not accessible. If the directory can't be renamed after the given amount of seconds, an exception * will be thrown. * * @return boolean True on success */ renameDirectory(sourcePath: string, destPath: string, timeout?: number): boolean; /** * Aux method that is used by renameFile and renameDirectory to rename a file or folder after their specific checks have been performed * * @param sourcePath Source path for the resource to rename * @param destPath Dest path for the resource to rename * @param timeout Amount of seconds to wait if not possible */ private _renameFSResource; /** * Delete a directory from the filesystem and all its contents (folders and files). * * @param path Absolute or relative path to the directory that will be removed * @param deleteDirectoryItself Set it to true if the specified directory must also be deleted. * @param timeout The amount of seconds that this method will be trying to perform a delete operation in case it is blocked * by the OS or temporarily not accessible. If the operation can't be performed after the given amount of seconds, * an exception will be thrown. * * @return int The number of files that have been deleted as part of the directory removal process. If directory is empty or ContainsElement * only folders, 0 will be returned even if many directories are deleted. If directory does not exist or it could not be deleted, * an exception will be thrown */ deleteDirectory(path: string, deleteDirectoryItself?: boolean, timeout?: number): number; /** * 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 * * @param pathToFile Absolute or relative path including full filename where data will be saved. File will be created or overwritten without warning. * @param data Any information to save on the file. * @param append 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. * @param createDirectories If set to true, all necessary non existant directories on the provided file path will be also created. * * @return True on success or false on failure. */ saveFile(pathToFile: string, data?: string, append?: boolean, createDirectories?: boolean): boolean; /** * TODO - translate from php */ createTempFile(): void; /** * Concatenate all the provided files, one after the other, into a single destination file. * * @param sourcePaths A list with the absolute or relative paths to the files we want to join. The result will be generated in the same order. * @param destFile The full path where the merged file will be stored, including the full file name (will be overwitten if exists). * @param separator 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 * * @return True on success or false on failure. */ mergeFiles(sourcePaths: string[], destFile: string, separator?: string): boolean; /** * Get the size from a file * * @param pathToFile Absolute or relative file path, including the file name and extension * * @return int the size of the file in bytes. An exception will be thrown if value cannot be obtained */ getFileSize(pathToFile: string): any; /** * TODO - adapt from PHP */ getFileModificationTime(pathToFile: string): string; /** * 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 * * @param pathToFile An Operating system absolute or relative path containing some file * * @return The file contents (binary or string). If the file is not found or cannot be read, an exception will be thrown. */ readFile(pathToFile: string): any; /** * Read and return the content of a file encoded as a base 64 string. Not suitable for big files (More than 5 MB) * cause the script memory may get full and the execution fail * * @param pathToFile An Operating system absolute or relative path containing some file * * @return The file contents as a base64 string. If the file is not found or cannot be read, an exception will be thrown. */ readFileAsBase64(pathToFile: string): any; /** * 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 * * @param pathToFile An Operating system absolute or relative path containing some file * @param downloadRateLimit 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 * * @return the number of bytes read from the file. */ readFileBuffered(): void; /** * Copies a file from a source location to the defined destination * If the destination file already exists, it will be overwritten. * * @param sourceFilePath Absolute or relative path to the source file that must be copied (including the filename itself). * @param destFilePath Absolute or relative path to the destination where the file must be copied (including the filename itself). * * @return Returns true on success or false on failure. */ copyFile(sourceFilePath: string, destFilePath: string): boolean; /** * Renames a file. * * @param sourceFilePath Absolute or relative path to the source file that must be renamed (including the filename itself). * @param destFilePath Absolute or relative path to the new file name (including the filename itself). It must not exist. * @param timeout The amount of seconds that this method will be trying to rename the specified file in case it is blocked * by the OS or temporarily not accessible. If the file can't be renamed after the given amount of seconds, an exception * will be thrown. * * @return boolean True on success */ renameFile(sourceFilePath: string, destFilePath: string, timeout?: number): boolean; /** * Delete a filesystem file. * * @param pathToFile Absolute or relative path to the file we want to delete * @param timeout The amount of seconds that this method will be trying to delete the specified file in case it is blocked * by the OS or temporarily not accessible. If the file can't be deleted after the given amount of seconds, an exception * will be thrown. * * @throws Error If the file cannot be deleted or does not exist * * @return True on success ONLY if the file existed and was deleted. */ deleteFile(pathToFile: string, timeout?: number): boolean; /** * Delete a list of filesystem files. * * @param pathsToFiles A list of filesystem absolute or relative paths to files to delete * @param timeout The amount of seconds that this method will be trying to delete a file in case it is blocked * by the OS or temporarily not accessible. If the file can't be deleted after the given amount of seconds, an exception * will be thrown. * * @throws Error if any of the files cannot be deleted, an exception will be thrown * * @return True on success */ deleteFiles(pathsToFiles: string[], timeout?: number): boolean; /** * Auxiliary method that is used by the findUniqueFileName and findUniqueDirectoryName methods * * @param i Current index for the name generation * @param desiredName Desired name as used on the parent method * @param text text name as used on the parent method * @param separator separator name as used on the parent method * @param isPrefix isPrefix name as used on the parent method * * @return The generated name */ private _generateUniqueNameAux; /** * Auxiliary method to generate a full path from a relative one and the configured root path * * If an absolute path is passed to the relativePath variable, the result of this method will be that value, ignoring * any possible value on _rootPath. */ private _composePath; }