Add Readme and JSDocs to the filestore-client (#179)

* Add jsdocs

* add readme

client/filestore-client/README.md

@@ -1,3 +1,25 @@
 # RainCatcher FileStore client
 
-WIP
+RainCatcher FileStore Client provides a manager which provides the support for:
+- Downloading files from a server.
+- Uploading files from a mobile device to a server.
+
+## Usage 
+1. Implement the [HttpClient](./src/HttpClient.ts) Interface
+
+2. Import FileManager
+```javascript
+var FileManager = require('@raincatcher/filestore-client').FileManager;
+...
+var fileManager = new FileManager(serverUrl, fileQueueName, httpClient);
+```
+
+3. Use the FileManager for uploading/downloading files to and from the server.
+```javascript
+fileManager.scheduleFileToBeUploaded(fileQueueEntry);
+fileManager.scheduleFileToBeDownloaded(fileQueueEntry);
+```
+- Ensure the fileQueueEntry adheres to the [FileQueueEntry](./src/FileQueueEntry.ts) interface.
+
+## HttpClient Interface
+The [HttpClient](./src/HttpClient.ts) interface should be implemented in order to enable the FileStore client to make network requests for uploading and downloading files to and from a server.

client/filestore-client/src/CordovaFileSupport.ts

@@ -5,14 +5,27 @@ import { FileQueueEntry } from './FileQueueEntry';
 import { HttpClient } from './HttpClient';
 
 /**
- * Executes low level cordova file operations for downloading and uploading files to the server.
+ * Executes a low level cordova file operation for downloading and uploading files to the server.
  */
 export class CordovaFileSupport {
+
+  /**
+   * Creates a cordova file support instance
+   *
+   * @param url - URL used for uploading to and downloading a file.
+   * @param httpClient - An implementation of the HTTP client interface.
+   *
+   * @see HttpClient
+   */
   constructor(private url: string, private httpClient: HttpClient) {
   }
 
   /**
-   * Download files from server
+   * Downloads a file from a server
+   *
+   * @param file - Contains information required to download a file
+   *
+   * @see FileQueueEntry
    */
   public downloadFileFromServer(file: FileQueueEntry): Bluebird<string> {
     const self = this;
@@ -27,9 +40,11 @@ export class CordovaFileSupport {
   }
 
   /**
-   * Upload file using local file URI. Used for uploads on mobile devices (cordova based)
+   * Uploads a file on a mobile device to a server. (cordova based)
+   *
+   * @param file - Contains information required to upload a file
    *
-   * @param file - contains source location for the file that will be send to the server
+   * @see FileQueueEntry
    */
   public uploadFile(file: FileQueueEntry): Bluebird<Response> {
     const self = this;
@@ -40,6 +55,11 @@ export class CordovaFileSupport {
     }
   }
 
+  /**
+   * Transforms a base64 file to a blob.
+   *
+   * @param dataURI - A base64 file.
+   */
   protected dataUriToBlob(dataURI: string): Blob {
     const data = dataURI.split(',')[1];
 
@@ -49,6 +69,13 @@ export class CordovaFileSupport {
     return b64ToBlob(data, mimeType);
   }
 
+  /**
+   * Uploads a file to a server from the file path on a mobile device.
+   *
+   * @param file - Contains information required to upload a file to a server.
+   *
+   * @see FileQueueEntry
+   */
   protected uploadFromFilePath(file: FileQueueEntry) {
     const self = this;
     return new Bluebird<FileEntry>((resolve, reject) => window.resolveLocalFileSystemURL(file.uri, function(entry) {
@@ -68,6 +95,14 @@ export class CordovaFileSupport {
     }));
   }
 
+  /**
+   * Upload a blob file to a server.
+   *
+   * @param file - Contains information required to upload a file to a server.
+   * @param blob - A file blob
+   *
+   * @see FileQueueEntry
+   */
   protected uploadWithBlob(file: FileQueueEntry, blob: Blob) {
     const data = new FormData();
     data.append('file', blob);

client/filestore-client/src/FileManager.ts

@@ -13,22 +13,26 @@ export class FileManager {
   private uploadQueue: FileQueue;
   private downloadQueue: FileQueue;
   private fileSupport: CordovaFileSupport;
+
   /**
-   * Create new FileManager
+   * Creates a new FileManager
+   *
+   * @param serverUrl - Server url used for downloading and uploading files to.
+   * @param name - A name for a file queue
+   * @param httpInterface - An HTTP interface for making network requests
    *
-   * @param serverUrl - server url used to save images
-   * @param name name for the queues
-   * @param httpInterface interface for making network requests
+   * @see HttpClient
    */
   public constructor(private serverUrl: string, private name: string, private httpInterface: HttpClient) {
     this.uploadQueue = new FileQueue(window.localStorage, name + '-upload');
     this.downloadQueue = new FileQueue(window.localStorage, name + '-download');
     this.fileSupport = new CordovaFileSupport(serverUrl, httpInterface);
 
-    // Start processing uploads on startup
+    // Start processing uploads and downloads on startup
     this.startProcessingUploads();
     this.startProcessingDownloads();
-    // Listen when client becomes online for uploads
+
+    // Listen when client becomes online for uploads and downloads
     const self = this;
     document.addEventListener('online', function() {
       self.startProcessingUploads();
@@ -37,38 +41,44 @@ export class FileManager {
   }
 
   /**
-   * Add file to upload queue. File would be uploaded depending on internet connectivity.
+   * Adds a file to the upload queue. Files are only uploaded when the device is online.
    *
-   * @param file file metadata to be saved
-   * @returns {*}
+   * @param file - Contains required information for uploading a file
+   *
+   * @see FileQueueEntry
    */
   public scheduleFileToBeUploaded(file: FileQueueEntry) {
     const self = this;
     return this.fileSupport.uploadFile(file).then(function(result) {
       return Bluebird.resolve(result);
     }).catch(function(err) {
-      // Add item to queue
+      // Adds a file to the upload queue
       self.uploadQueue.addItem(file);
     });
   }
 
   /**
-   * Add file to download queue. File would be downloaded to local file system depending on internet connectivity.
+   * Adds a file to the download queue. Files are only downloaded when the device is online.
+   *
+   * @param file - Contains required information for uploading a file
    *
-   * @returns {*}
+   * @see FileQueueEntry
    */
   public scheduleFileToBeDownloaded(file: FileQueueEntry) {
     const self = this;
     if (file.id) {
       return this.fileSupport.downloadFileFromServer(file).then(function(result) {
         return Bluebird.resolve(result);
       }).catch(function(err) {
-        // Add item to queue
+        // Adds a file to the upload queue if file is not available.
         self.uploadQueue.addItem(file);
       });
     }
   }
 
+  /**
+   * Starts the process of uploading files to the server.
+   */
   private startProcessingUploads() {
     const queueItems: FileQueueEntry[] = this.uploadQueue.restoreData().getItemList();
     const self = this;
@@ -82,6 +92,9 @@ export class FileManager {
     }
   }
 
+  /**
+   * Starts the process of downloading files from the server.
+   */
   private startProcessingDownloads() {
     const self = this;
     const queueItems: FileQueueEntry[] = this.downloadQueue.restoreData().getItemList();
@@ -97,6 +110,12 @@ export class FileManager {
     }
   }
 
+  /**
+   * Uploads the file to the server. Once the file has been successfully uploaded, it is removed
+   * from the queue.
+   *
+   * @param file - Contains information required to upload a file to the server.
+   */
   private saveFile(file: FileQueueEntry) {
     const self = this;
     return this.fileSupport.uploadFile(file).then(function(createdFile) {

client/filestore-client/src/FileQueue.ts

@@ -1,10 +1,8 @@
 import * as _ from 'lodash';
 import { FileQueueEntry } from './FileQueueEntry';
+
 /**
- * TODO create interface for that
- * Queue implementation backed by browser persistent storage
- *
- * @param name
+ * A queue implementation backed by the browser's persistent storage.
  */
 export class FileQueue {
   private queueName: string;
@@ -14,10 +12,9 @@ export class FileQueue {
     this.queueName = name;
   }
 
-  /**
-   * Persist queue items to local storage;
-   * @return queue
-   */
+   /**
+    * Save queue items to local storage.
+    */
   public saveData() {
     const toSave = JSON.stringify({
       queue: this.queueData
@@ -27,8 +24,7 @@ export class FileQueue {
   }
 
   /**
-   * Read queue items from local storage
-   * @return queue
+   * Read queue items from local storage.
    */
   public restoreData() {
     const queueDataString = this.localStorage.getItem(this.queueName);
@@ -42,31 +38,36 @@ export class FileQueue {
   }
 
   /**
-   * Get items
+   * Get queue items
    */
   public getItemList(): FileQueueEntry[] {
     return this.queueData;
   }
 
   /**
-   * Add new item to queue.
-   * @param item   item meta data model
+   * Add new item to the queue
+   * @param item - Contains information required to upload files to the server.
+   * @see FileQueueEntry
    */
   public addItem(item: FileQueueEntry) {
     this.queueData.push(item);
     return this.saveData();
   }
+
   /**
-   * Remove item from queue.
-   * @param item   item meta data model
+   * Remove an item from the queue.
+   * @param item - Contains file information.
+   * @see FileQueueEntry
    */
   public removeItem(item: FileQueueEntry) {
     _.remove(this.queueData, item);
     return this.saveData();
   }
 
   /**
-   * Read item from queue by id
+   * Reads an item from the queue using an id.
+   *
+   * @param id - A unique identifier used to identify the item to be read from the queue.
    */
   public readItem(id): FileQueueEntry | undefined {
     return _.find(this.queueData, function(item) {

client/filestore-client/src/FileQueueEntry.ts

@@ -1,11 +1,19 @@
 /**
- * Contains required fields required to save file
+ * Contains fields required for uploading and downloading a file.
  */
 export interface FileQueueEntry {
   /**
-   * Uri to local filesystem containing file
+   * File URI to local filesystem containing the file.
    */
   uri: string;
+
+  /**
+   * File type
+   */
   type: 'uri'|'base64';
+
+  /**
+   * File identifier
+   */
   id?: string;
 }

client/filestore-client/src/HttpClient.ts

@@ -1,5 +1,21 @@
 import * as Promise from 'bluebird';
+
+/**
+ * Interface for making network requests for uploading and downloading files from a server.
+ */
 export interface HttpClient {
+  /**
+   * Upload a file to the server.
+   *
+   * @param url - URL to the file endpoint in the server.
+   * @param data - Data containing the files and other metadata to be uploaded to the server.
+   */
   upload: (url: string, data: FormData) => Promise<Response>;
+
+  /**
+   * Download a file from the server.
+   *
+   * @param url - URL to the file endpoint in the server
+   */
   download: (url: string) => Promise<Response>;
 }