refractor(file): additions to documentation and type definitions for …

…File plugin (#446) * Additions to documentations and type definitions Added return types to documentation as well as modified return type definition to match actual types returned. Used union types for promises where applicable. Builds and gulp docs ok. * Update file.ts
danielsogl · Aug 17, 2016 · abd706f · abd706f
1 parent 4c00e14
commit abd706f
Showing 1 changed file with 95 additions and 40 deletions.
diff --git a/src/plugins/file.ts b/src/plugins/file.ts
@@ -341,6 +341,17 @@ declare var FileError: {
  * @description
  * This plugin implements a File API allowing read/write access to files residing on the device.
  *
+ * The File class implements static convenience functions to access files and directories.
+ *
+ * Example:
+ * ```
+ * import { File } from 'ionic-native';
+ *
+ * declare var cordova: any;
+ * const fs:string = cordova.file.dataDirectory;
+ * File.checkDir(this.fs, 'mydir').then(_ => console.log('yay')).catch(err => console.log('boooh'));
+ * ```
+ *
  *  This plugin is based on several specs, including : The HTML5 File API http://www.w3.org/TR/FileAPI/
  *  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/
@@ -379,14 +390,14 @@ export class File {
    *
    * @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.
+   * @return {Promise<boolean|FileError>} Returns a Promise that resolves to true if the directory exists or rejects with an error.
    */
 
-  static checkDir(path: string, dir: string): Promise<boolean> {
+  static checkDir(path: string, dir: string): Promise<boolean|FileError> {
     if ((/^\//.test(dir))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<boolean>(err);
+      return Promise.reject<FileError>(err);
     }
 
     let fullpath = path + dir;
@@ -404,14 +415,14 @@ export class File {
    * @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.
+   * @return {Promise<DirectoryEntry|FileError>} Returns a Promise that resolves with a DirectoryEntry or rejects with an error.
    */
 
-  static createDir(path: string, dirName: string, replace: boolean): Promise<DirectoryEntry> {
+  static createDir(path: string, dirName: string, replace: boolean): Promise<DirectoryEntry|FileError> {
     if ((/^\//.test(dirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<DirectoryEntry>(err);
+      return Promise.reject<FileError>(err);
     }
 
     let options: Flags = {
@@ -433,14 +444,14 @@ export class File {
    *
    * @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.
+   * @return {Promise<RemoveResult|FileError>} Returns a Promise that resolves to a RemoveResult or rejects with an error.
    */
 
-  static removeDir(path: string, dirName: string): Promise<RemoveResult> {
+  static removeDir(path: string, dirName: string): Promise<RemoveResult|FileError> {
     if ((/^\//.test(dirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<RemoveResult>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -459,16 +470,16 @@ export class File {
    * @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.
+   * @return {Promise<DirectoryEntry|FileError>} Returns a Promise that resolves to the new DirectoryEntry object or rejects with an error.
    */
 
-  static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<DirectoryEntry> {
+  static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<DirectoryEntry|FileError> {
     newDirName = newDirName || dirName;
 
     if ((/^\//.test(newDirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<DirectoryEntry>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -490,13 +501,13 @@ export class File {
    * @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.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to the new Entry object or rejects with an error.
    */
-  static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> {
+  static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<Entry|FileError> {
     if ((/^\//.test(newDirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -516,7 +527,7 @@ export class File {
    *
    * @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.
+   * @return {Promise<Entry[]>} Returns a Promise that resolves to an array of Entry objects or rejects with an error.
    */
 
   static listDir(path: string, dirName: string): Promise<Entry[]> {
@@ -541,7 +552,7 @@ export class File {
    *
    * @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.
+   * @return {Promise<RemoveResult>} Returns a Promise that resolves with a RemoveResult or rejects with an error.
    */
 
   static removeRecursively(path: string, dirName: string): Promise<RemoveResult> {
@@ -565,14 +576,14 @@ export class File {
    *
    * @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.
+   * @return {Promise<boolean|FileError>} Returns a Promise that resolves with a boolean or rejects with an error.
    */
 
-   static checkFile(path: string, file: string): Promise<boolean> {
+  static checkFile(path: string, file: string): Promise<boolean|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file cannot start with \/';
-      return Promise.reject<boolean>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveLocalFilesystemUrl(path + file)
@@ -595,13 +606,13 @@ export class File {
    * @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.
+   * @return {Promise<FileEntry|FileError>} Returns a Promise that resolves to a FileEntry or rejects with an error.
    */
-  static createFile(path: string, fileName: string, replace: boolean): Promise<any> {
+  static createFile(path: string, fileName: string, replace: boolean): Promise<FileEntry|FileError> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     let options: Flags = {
@@ -623,14 +634,14 @@ export class File {
    *
    * @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.
+   * @return {Promise<RemoveResult|FileError>} Returns a Promise that resolves to a RemoveResult or rejects with an error.
    */
 
-  static removeFile(path: string, fileName: string): Promise<RemoveResult> {
+  static removeFile(path: string, fileName: string): Promise<RemoveResult|FileError> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<RemoveResult>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -642,6 +653,14 @@ export class File {
       });
   }
 
+  /** Write a new file to the desired location.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName path relative to base path
+   * @param {string} text content to write
+   * @param {boolean | WriteOptions} replaceOrOptions replace file if set to true. See WriteOptions for more information.
+   * @returns {Promise<void>} Returns a Promise that resolves or rejects with an error.
+   */
   static writeFile(path: string, fileName: string,
                    text: string, replaceOrOptions: boolean | WriteOptions): Promise<void> {
     if ((/^\//.test(fileName))) {
@@ -681,6 +700,13 @@ export class File {
       });
   }
 
+  /** Write to an existing file.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName path relative to base path
+   * @param {string} text content to write
+   * @returns {Promise<void>} Returns a Promise that resolves or rejects with an error.
+   */
   static writeExistingFile(path: string, fileName: string, text: string): Promise<void> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
@@ -700,11 +726,18 @@ export class File {
       });
   }
 
-  static readAsText(path: string, file: string): Promise<string> {
+  /**
+   * Read the contents of a file as text.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as string or rejects with an error.
+   */
+  static readAsText(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -728,12 +761,20 @@ export class File {
         });
       });
   }
+  /**
+   * Read file and return data as a base64 encoded data url.
+   * A data url is of the form:
+   *      data:[<mediatype>][;base64],<data>
 
-  static readAsDataURL(path: string, file: string): Promise<string> {
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as data URL or rejects with an error.
+   */
+  static readAsDataURL(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -758,11 +799,18 @@ export class File {
       });
   }
 
-  static readAsBinaryString(path: string, file: string): Promise<string> {
+  /**
+   * Read file and return data as a binary data.
+
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as string rejects with an error.
+   */
+  static readAsBinaryString(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -787,11 +835,18 @@ export class File {
       });
   }
 
-  static readAsArrayBuffer(path: string, file: string): Promise<ArrayBuffer> {
+  /**
+   * Read file and return data as an ArrayBuffer.
+
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<ArrayBuffer|FileError>} Returns a Promise that resolves with the contents of the file as ArrayBuffer or rejects with an error.
+   */
+  static readAsArrayBuffer(path: string, file: string): Promise<ArrayBuffer|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<ArrayBuffer>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -823,15 +878,15 @@ export class File {
    * @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.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to the new Entry or rejects with an error.
    */
-  static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+  static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<Entry|FileError> {
     newFileName = newFileName || fileName;
 
     if ((/^\//.test(newFileName))) {
       let err = new FileError(5);
       err.message = 'file name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -853,15 +908,15 @@ export class File {
    * @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.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to an Entry or rejects with an error.
    */
-  static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+  static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<Entry|FileError> {
     newFileName = newFileName || fileName;
 
     if ((/^\//.test(newFileName))) {
       let err = new FileError(5);
       err.message = 'file name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)