feat(uploader.basic.api.js): removeFileRef method (#1737)

When called, this deleted the reference to the Blob/File (along with all other file state tracked by the upload handler).
closes #1711

* docs(methods.jmd): document removeFileRef method
closes #1711

client/js/uploader.basic.api.js

@@ -308,6 +308,10 @@
             return false;
         },
 
+        removeFileRef: function(id) {
+            this._handler.expunge(id);
+        },
+
         reset: function() {
             this.log("Resetting uploader...");
 

client/js/version.js

@@ -1,2 +1,2 @@
 /*global qq */
-qq.version = "5.12.0";
+qq.version = "5.14.0-beta1";

docs/api/methods.jmd

@@ -30,6 +30,11 @@ $(document).ready(function() {
 {% markdown %}
 ## Core
 {% endmarkdown %}
+
+{{
+alert("If you pass a large `Blob` that was created using JavaScript in the browser into `addFiles`, you should consider calling the [`removeFileRef` method](#removeFileRef) after the file has been successfully uploaded to free up any memory consumed by the Blob.")
+}}
+
 {{ api_method("addFiles", "addFiles (files[, params[, endpoint]])", "Submit one or more files to the uploader.
 
 A `BlobWrapper` object:
@@ -352,6 +357,15 @@ A `resizeInfo` object, which will be passed to the supplied function, contains t
 
 ]) }}
 
+{{ api_method("removeFileRef", "removeFileRef (id)", "",
+[
+    {
+        "name": "id",
+        "type": "Integer",
+        "description": "Remove internal reference to the associated Blob/File object. For Blobs that are created via JavaScript in the browser, this will free up all consumed memory."
+    }
+]) }}
+
 {{ api_method("reset", "reset ()", "Reset Fine Uploader", null, null) }}
 
 {{ api_method("retry", "retry (id)", "Attempt to upload a specific item again.",

package.json

@@ -2,7 +2,7 @@
   "name": "fine-uploader",
   "title": "Fine Uploader",
   "main": "lib/traditional.js",
-  "version": "5.13.0",
+  "version": "5.14.0-beta1",
   "description": "Multiple file upload plugin with progress-bar, drag-and-drop, direct-to-S3 & Azure uploading, client-side image scaling, preview generation, form support, chunking, auto-resume, and tons of other features.",
   "keywords": [
     "amazon",

test/unit/simple-file-uploads.js

@@ -478,5 +478,30 @@ if (qqtest.canDownloadFileAsBlob) {
                 uploader.addFiles(canvasWrapper);
             });
         });
+
+        it("removes reference to a Blob via API", function(done) {
+            qqtest.downloadFileAsBlob("up.jpg", "image/jpeg").then(function(blob) {
+                fileTestHelper.mockXhr();
+
+                var request,
+                    uploader = new qq.FineUploaderBasic({
+                        autoUpload: false,
+                        request: { endpoint: testUploadEndpoint },
+                        callbacks: {
+                            onComplete: function(id) {
+                                assert.ok(uploader.getFile(id));
+                                uploader.removeFileRef(id);
+                                assert.ok(!uploader.getFile(id));
+                                done();
+                            }
+                        }
+                    });
+
+                uploader.addFiles({name: "test", blob: blob});
+                uploader.uploadStoredFiles();
+
+                fileTestHelper.getRequests()[0].respond(200, null, JSON.stringify({success: true}));
+            });
+        });
     });
 }