Evaporate | AngularJS module for the resumable s3 uploads

angular-evaporate library

angular-evaporate

Stars : 10

Forks : 10

Created by uqee

bower install angular-evaporate

Download GitHub

EvaporateJS is a javascript library for directly uploading files from a web browser to AWS S3, using S3′s multipart upload.

Why?

EvaporateJS can resume an upload after a problem without having to start again at the beginning. For example, let’s say you’re uploading a 1000MB file, you’ve uploaded the first 900MBs, and then there is a problem on the network. Normally at this point you’d have to restart the upload from the beginning. Not so with EvaporateJS – it will only redo a small ~5MB chunk of the file, and then carry on from where it left off, and upload the final 100MB.

angular-evaporate

Reinforces the Evaporate library to allow Angular-specific usage along with all the native functionality plus additional features. Available injectables:

  1. Evaporate - native lib.

  2. AngularEvaporateException - dedicated exception handler.

  3. AngularEvaporateUpload - file upload handler:

    • calculates name, url, content type for a new upload,
    • calculates progress percent, speed and estimated time,
    • saves status updates with timestamps,
    • saves info, warning and error messages,
    • binds Evaporate's API to the upload id,
    • updates $scope on Evaporate's callbacks,
    • manages dependent states (e.g. pausing, paused, resumed - only one can be true),
    • adds meta states (e.g. stopped is when either completed, canceled or failed).

  4. AngularEvaporate - uploads queue handler (extends Evaporate):

    • manages uploads queue with an ability for every upload to be started later,
    • allows to specify a default config, which will be merged with every consequent upload's one,
    • allows to specify a custom naming function, where current instances of AngularEvaporateUpload and AngularEvaporate are available.

  5. angular-evaporate - directive:

    • lazy mode option - explicit uploading start,
    • same files uploading option - clean file input after every select.

Get

  1. Install

    npm install --save angular-evaporate

  2. Include

    <script src="node_modules/angular-evaporate/lib/angular-evaporate.min.js"></script>

  3. Depend

    angular.module('yourApp', ['angular-evaporate']);

Use

  1. Inject

    yourApp.controller('yourCtrl', ['$scope', 'AngularEvaporate',
  function ($scope, AngularEvaporate) {...}
]);

  2. Init

    $scope.ae = new AngularEvaporate(...);

    AngularEvaporate extends Evaporate, so its constructor accepts the same arguments.

  3. Directive

    <div ng-controller="yourCtrl">
  <input type="file" multiple angular-evaporate="ae"/>
</div>

Test

bash npm install && npm test

Example

  1. Configure

    Follow the Evaporate's instructions to set up an S3 bucket, then accordingly update AngularEvaporate's constructor parameters in the example/index.js file and AWS_SECRET_KEY value in the example/server.js file.

  2. Run

    npm install && npm start

  3. Check

    http://localhost:8080/example

  4. Hint

    Always use server-side validation for incoming requests to the signerUrl, because in this simple example anyone could send you anything he wanted and just get it signed with your secret key.

AngularEvaporate class

Extends Evaporate, therefore accepts the same constructor arguments and provides the same functionality, but also introduces additional features. To not interfere with possible future versions, all added object keys start from the $ symbol.

Properties

PropertyTypeUsageDescription
$uploadsArrayessentialinstances of AngularEvaporateUpload
$applyFunctionrecommendedset this to your $scope.$apply.bind($scope) to update UI when needed
$configObjectoptionaldefault config for an upload (explicitly specified properties on a consequent call of $enqueue() or $add() will have higher priority)
$namerFunctionoptionalcustom upload naming function (instance of AngularEvaporateUpload as an input argument, instance of AngularEvaporate as this), default one just returns a filename
$speederFunctionoptionalcustom speedometer function (input: current speed in bytes/second, output: string in readable format, like '1.23 MB/s')
$urlStringcautiouscustom url of the bucket's root directory
$slothmodeBooleanoptional(directive) lazy mode option - explicit uploading start
$rinserepeatBooleanoptional(directive) same files uploading option - clean file input after every select

API

FunctionArgumentsResultDescription
$enqueuesame as for Evaporate.add()AngularEvaporateUploadcreate an upload and append it to the queue
$dequeueAngularEvaporateUploadNumber - index in $uploadsremove an upload from the queue
$startAngularEvaporateUploadsame as from Evaporate.add()start uploading an already queued upload
$addsame as for Evaporate.add()same as from Evaporate.add()enqueue and start uploading immediately
FunctionArgumentsResult
$startAll,
$cancelAll,
$dequeueAll		--
$pauseAll,
$resumeAll		same as for Evaporate[fn](undefined, ...), where fn is pause or resumesame as from Evaporate[fn](undefined, ...)

AngularEvaporateUpload class

Properties

PropertyTypeUsageDescription
nameStringoptionaldesired path from bucket's root directory
contentTypeStringoptionalMIME type
$idNumberread onlyresult of the Evaporate.add()
$urlStringread onlyfull url of the file when it's uploaded
$started,
$paused,
$resumed,
$pausing,
$cancelled,
$complete,
$info,
$warn,
$error,
$progress		NumberoptionalDate.now() of every Evaporate's callback fired
$stoppedNumberoptionalvalue of either $complete, $cancelled or $error
$infoMsg,
$warnMsg,
$errorMsg		Stringoptionalinput parameter of the corresponding callback
$percentNumberoptionalcurrent uploading progress
$secondsNumberoptionalestimated elapsed time
$speedStringoptionalaverage upload speed

API

FunctionArgumentsResult
$start-same as from Evaporate.add()
$pause,
$resume,
$cancel		same as for the corresponding Evaporate[fn](id, ...)same as from the corresponding Evaporate[fn](id, ...)

Javscript

Javascript plugin

Angular-js