Add a few more methods and add documentation

src/plugins/file.ts

@@ -11,13 +11,6 @@ declare var window;
  *  The (now-defunct) Directories and System extensions Latest: http://www.w3.org/TR/2012/WD-file-system-api-20120417/
  *  Although most of the plugin code was written when an earlier spec was current: http://www.w3.org/TR/2011/WD-file-system-api-20110419/
  *  It also implements the FileWriter spec : http://dev.w3.org/2009/dap/file-system/file-writer.html
- *
- * @usage
- *
- * ```ts
- * File.removeRecursively(file.applicationStorageDirectory,
- *                        "tmp").then(result => {}, err => {});
- * ```
  */
 @Plugin({
   plugin: 'cordova-plugin-file',
@@ -43,6 +36,13 @@ export class File {
   // @Cordova()
   // static getFreeDiskSpace(): Promise<any> { return }
 
+  /**
+   * Check if a directory exists in a certain path, directory.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} dir Name of directory to check
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static checkDir(path: string, dir: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -72,6 +72,16 @@ export class File {
     return promise;
   }
 
+  /**
+   * Creates a new directory in the specific path.
+   * The replace boolean value determines whether to replace an existing directory with the same name.
+   * If an existing directory exists and the replace value is false, the promise will fail and return an error.
+   *
+   * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} dirName Name of directory to create
+   * @param {boolean} replace If true, replaces file with same name. If false returns error
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static createDir(path: string, dirName: string, replace: boolean): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -107,6 +117,13 @@ export class File {
     return promise;
   }
 
+  /**
+   * Remove a directory at a given path
+   *
+   * @param {string} path The path to the directory
+   * @param {string} dirName The directory name
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static removeDir(path: string, dirName: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -140,10 +157,107 @@ export class File {
     return promise;
   }
 
-  // static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> { return }
+  /**
+   * Move a directory to a given path
+   *
+   * @param {string} path The source path to the directory
+   * @param {string} dirName The source directory name
+   * @param {string} newPath The destionation path to the directory
+   * @param {string} newDirName The destination directory name
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
+  static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> {
+    let resolveFn, rejectFn;
+    let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
 
-  // static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> { return }
+    newDirName = newDirName || dirName;
 
+    if ((/^\//.test(newDirName))) {
+      rejectFn('directory cannot start with \/');
+    }
+
+    try {
+      window.resolveLocalFileSystemURL(path, function (fileSystem) {
+        fileSystem.getDirectory(dirName, {create: false}, function (dirEntry) {
+          window.resolveLocalFileSystemURL(newPath, function (newDirEntry) {
+            dirEntry.moveTo(newDirEntry, newDirName, function (result) {
+              resolveFn(result);
+            }, function (error) {
+              rejectFn(error);
+            });
+          }, function (erro) {
+            rejectFn(erro);
+          });
+        }, function (err) {
+          rejectFn(err);
+        });
+      }, function (er) {
+        rejectFn(er);
+      });
+    } catch (e) {
+      rejectFn(e);
+    }
+
+    return promise;
+  }
+
+  /**
+   * Copy a directory in various methods. If destination directory exists, will fail to copy.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} dirName Name of directory to copy
+   * @param {string} newPath Base FileSystem of new location
+   * @param {string} newDirName New name of directory to copy to (leave blank to remain the same)
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
+  static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> {
+    let resolveFn, rejectFn;
+    let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
+
+    newDirName = newDirName || dirName;
+
+    if ((/^\//.test(newDirName))) {
+      rejectFn('directory cannot start with \/');
+    }
+
+    try {
+      window.resolveLocalFileSystemURL(path, function (fileSystem) {
+        fileSystem.getDirectory(dirName, {create: false, exclusive: false}, function (dirEntry) {
+
+          window.resolveLocalFileSystemURL(newPath, function (newDirEntry) {
+            dirEntry.copyTo(newDirEntry, newDirName, function (result) {
+              resolveFn(result);
+            }, function (error) {
+              error.message = File.cordovaFileError[error.code];
+              rejectFn(error);
+            });
+          }, function (erro) {
+            erro.message = File.cordovaFileError[erro.code];
+            rejectFn(erro);
+          });
+        }, function (err) {
+          err.message = File.cordovaFileError[err.code];
+          rejectFn(err);
+        });
+      }, function (er) {
+        er.message = File.cordovaFileError[er.code];
+        rejectFn(er);
+      });
+    } catch (e) {
+      e.message = File.cordovaFileError[e.code];
+      rejectFn(e);
+    }
+
+    return promise;
+  }
+
+  /**
+   * List files and directory from a given path
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} dirName Name of directory
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static listDir(path: string, dirName: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -182,6 +296,13 @@ export class File {
     return promise;
   }
 
+  /**
+   * Removes all files and the directory from a desired location.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} dirName Name of directory
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static removeRecursively(path: string, dirName: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -215,6 +336,13 @@ export class File {
     return promise;
   }
 
+  /**
+   * Check if a file exists in a certain path, directory.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file to check
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static checkFile(path: string, file: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -244,6 +372,16 @@ export class File {
     return promise;
   }
 
+  /**
+   * Creates a new file in the specific path.
+   * The replace boolean value determines whether to replace an existing file with the same name.
+   * If an existing file exists and the replace value is false, the promise will fail and return an error.
+   *
+   * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName Name of file to create
+   * @param {boolean} replace If true, replaces file with same name. If false returns error
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static createFile(path: string, fileName: string, replace: boolean): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -280,6 +418,13 @@ export class File {
     return promise;
   }
 
+  /**
+   * Removes a file from a desired location.
+   *
+   * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName Name of file to remove
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
   static removeFile(path: string, fileName: string): Promise<any> {
     let resolveFn, rejectFn;
     let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
@@ -325,7 +470,97 @@ export class File {
 
   // static readAsArrayBuffer(path: string, file: string): Promise<any> { return }
 
-  // static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> { return }
+  /**
+   * Move a file to a given path.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName Name of file to move
+   * @param {string} newPath Base FileSystem of new location
+   * @param {string} newFileName New name of file to move to (leave blank to remain the same)
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
+  static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+    let resolveFn, rejectFn;
+    let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
 
-  // static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> { return }
+    newFileName = newFileName || fileName
+
+    if ((/^\//.test(newFileName))) {
+      rejectFn('file-name cannot start with \/');
+    }
+
+    try {
+      window.resolveLocalFileSystemURL(path, function (fileSystem) {
+        fileSystem.getFile(fileName, {create: false}, function (fileEntry) {
+          window.resolveLocalFileSystemURL(newPath, function (newFileEntry) {
+            fileEntry.moveTo(newFileEntry, newFileName, function (result) {
+              resolveFn(result);
+            }, function (error) {
+              rejectFn(error);
+            });
+          }, function (err) {
+            rejectFn(err);
+          });
+        }, function (err) {
+          rejectFn(err);
+        });
+      }, function (er) {
+        rejectFn(er);
+      });
+    } catch (e) {
+      rejectFn(e);
+    }
+
+    return promise;
+  }
+
+  /**
+   * Copy a file in various methods. If file exists, will fail to copy.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName Name of file to copy
+   * @param {string} newPath Base FileSystem of new location
+   * @param {string} newFileName New name of file to copy to (leave blank to remain the same)
+   * @return Returns a Promise that resolves or rejects with an error.
+   */
+  static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+    let resolveFn, rejectFn;
+    let promise = new Promise((resolve, reject) => {resolveFn = resolve; rejectFn = reject; })
+
+    newFileName = newFileName || fileName
+
+    if ((/^\//.test(newFileName))) {
+      rejectFn('file-name cannot start with \/');
+    }
+
+    try {
+      window.resolveLocalFileSystemURL(path, function (fileSystem) {
+        fileSystem.getFile(fileName, {create: false, exclusive: false}, function (fileEntry) {
+
+          window.resolveLocalFileSystemURL(newPath, function (newFileEntry) {
+            fileEntry.copyTo(newFileEntry, newFileName, function (result) {
+              resolveFn(result);
+            }, function (error) {
+              error.message = File.cordovaFileError[error.code];
+              rejectFn(error);
+            });
+          }, function (erro) {
+            erro.message = File.cordovaFileError[erro.code];
+            rejectFn(erro);
+          });
+        }, function (err) {
+          err.message = File.cordovaFileError[err.code];
+          rejectFn(err);
+        });
+      }, function (er) {
+        er.message = File.cordovaFileError[er.code];
+        rejectFn(er);
+      });
+    } catch (e) {
+      e.message = File.cordovaFileError[e.code];
+      rejectFn(e);
+    }
+
+    return promise;
+  }
 }