Evaporate.prototype.add()

var completionPromise = evaporate.add(config[, overrideOptions])

config is an object with 2 required keys:

• name: String. the S3 ObjectName that the completed file will have (you can upload to folders in a bucket by providing path to the uploaded file within a folder)

• file: File. The reference to the JavaScript File object to upload.

  The completionPromise is an implementation of Promises/A+. The promise resolves with the AWS object key of the uploaded object. This object key may be different than the requested object key if allowS3ExistenceOptimization is enabled and Evaporate was able to identify the already uploaded object in the requested bucket. The promise rejects with a message as to why the file could not be uploaded.

  Evaporate.create({
    bucket: 'mybucket'
  })
  .then(function (evaporate) {
    evaporate.add({
      name: 'myFile',
      file: new File()
    })
    .then(
      function (awsS3ObjectKey) {
        // "Sucessfully uploaded to: mybucket/myfile"
        console.log('Successfully uploaded to:', awsS3ObjectKey);
      },
      function (reason) {
        console.log('Failed to upload because:', reason);
      }
    );

And a number of optional parameters:

• xAmzHeadersAtInitiate: Object. an object of key/value pairs that represents the x-amz-... headers that should be added to the initiate multipart upload POST request. For example, some customers need to delcare an ACL like so: {'x-amz-acl': 'public-read'}.

• notSignedHeadersAtInitiate: Object. an object of key/value pairs that represents the headers that should be added to the initiate request but should not be included in the signing request. For example, a caching directive like this {'Cache-Control': 'max-age=3600'} should be excluded.

• xAmzHeadersAtUpload, xAmzHeadersAtComplete: Object. an object of key/value pairs that represents the x-amz-... headers that should be added to the upload PUTS and the complete POST request respectively. For example, {'x-amz-security-token':'the-long-session-token'} is needed when using temporary security credentials (IAM roles). If all AWS requests (excluding the initiate request) use the same headers, then prefer using the xAmzHeadersCommon option.

• xAmzHeadersCommon: Object. an object of key/value pairs that represents the x-amz-... headers that should be added to all AWS requests other than the initiate request. xAmzHeadersAtUpload and xAmzHeadersAtComplete do not need to be specified if xAmzHeadersCommon satisfies the AWS header requirements.

• started: function(file_key). a function that will be called when the file upload starts. The file_key represents the internal identifier of the file whose upload is starting.

• uploadInitiated: function(s3UploadId). a function that will be called when the S3 upload is successfully initiated. s3UploadId is the AWS S3 uploaded ID returned when the multipart upload is initiated.

• paused: function(). a function that will be called when the file upload is completely paused (all in-progress parts are aborted or completed). The file_key represents the file whose upload has been paused.

• resumed: function(). a function that will be called when the file upload resumes.

• pausing: function(). a function that will be called when the file upload has been asked to pause after all in-progress parts are completed. The file_key represents the file whose upload has been requested to pause.

• cancelled: function(). a function that will be called when a successful cancel is called for an upload id.

• complete: function(xhr, awsObjectKey, stats). a function that will be called when the file upload is complete. Version 1.0.0 introduced the awsObjectKey parameter to notify the client of the S3 object key that was used if the object already exists on S3.

  For information on stats, refer to the progress() callback.

• nameChanged: function(awsObjectKey). a function that will be called when the requested AWS S3 object key changes either because the requested object was previously interrupted (and is being resumed) or because the entire object already exists on S3.

• info: function(msg). a function that will be called with a debug/info message, usually logged as well.

• warn: function(msg). a function that will be called on a potentially recoverable error, and will be retried (e.g. part upload).

• error: function(msg). a function that will be called on an irrecoverable error.

• progress: function(p, stats). a function that will be called at a frequency determined by progressIntervalMS as the file uploads, where p is the fraction (between 0 and 1) of the file that is uploaded. Note that this number will increase or decrease depending on the status of uploading parts.

  stats is an object that contains the unformatted and formatted transfer rate in bytes and a value approximating in how may seconds the upload should complete.

  {
      speed: 70343222.003493043, // avgSpeedBytesPerSecond,
      readableSpeed: "703 Kb",
      loaded: 7034333, // Bytes loaded since the last call. it's for part upload.
      totalUploaded: 10024457, // Total bytes uploaded
      remainingSize: 20000000,
      secondsLeft: 10, //when -1, it's unknown.
      fileSize: 30024457
  }

• contentType: String. the content type (MIME type) the file will have

• beforeSigner: function(xhr, url). a function that will be just before the signUrl is sent.

overrideOptions, an object, when present, will override th Evaporate global configuration options for the added file only. With the exception of the following options, all other Evaporate configuration options can be overridden:

• maxConcurrentParts
• logging
• cloudfront
• encodeFilename
• computeContentMd5,
• allowS3ExistenceOptimization
• onlyRetryForSameFileName
• timeUrl
• cryptoMd5Method
• aws_url
• cryptoHexEncodedHash256
• awsRegion
• awsSignatureVersion

The .add() method returns a Promise that resolves when the upload completes.

To pause, resume or cancel an upload, construct a file_key to pass to the respective Evaporate methods. file_key is the optional file key of the upload that you want to pause. File key is constructed as bucket + '/' + object_name.