EvaporateJS

Evaporate is used by first creating an instance with a global configuration via Evaporate.create(config), and then adding specific files to upload using the .add(addConfig, overrides) method.

Key configuration options include:

• signerUrl: The URL used to obtain upload signatures.
• aws_key: Your AWS access key.
• bucket: The target S3 bucket.
• cloudfront: Boolean to enable CloudFront usage.
• computeContentMd5: Boolean to enable MD5 checksum calculations.
• cryptoMd5Method: A function to handle MD5 hashing (e.g., using Node's crypto module).

When adding a file, you can provide addConfig which includes:

• name: The name of the file.
• file: The file object to upload.
• progress: A callback receiving upload stats (transfer rate, time remaining).
• complete: A callback invoked upon successful upload.

You can also provide overrides to change properties like the bucket for a specific upload instance.

const Evaporate = require('EvaporateJS');
const Crypto = require('crypto');

const config = {
  signerUrl: SIGNER_URL,
  aws_key: AWS_KEY,
  bucket: AWS_BUCKET,
  cloudfront: true,
  computeContentMd5: true,
  cryptoMd5Method: data => Crypto
  .createHash('md5')
  .update(data)
  .digest('base64');
};

const uploadFile = evaporate => {
  const file = new File([""], "file_object_to_upload");

  const addConfig = {
    name: file.name,
    file: file,
    progress: progressValue => console.log('Progress', progressValue),
    complete: (_xhr, awsKey) => console.log('Complete!'),
  }

  const overrides = {
    bucket: AWS_BUCKET_2
  };

  evaporate.add(addConfig, overrides)
    .then(
      awsObjectKey =>
        console.log('File successfully uploaded to:', awsObjectKey),
      reason =>
        console.log('File did not upload sucessfully:', reason);
    )
}

return Evaporate.create(config).then(uploadFile);

Evaporate provides several configuration keys to control upload behavior:

Performance and Concurrency

• maxConcurrentParts: Controls the number of parallel uploads for each part.

Integrity and Security

• computeContentMd5: Enables/disables MD5 checksum calculations for each part.
• cryptoMd5Method: Allows providing a custom function for MD5 digest calculation.
• awsSignatureVersion: Specifies the AWS Signature version (e.g., Version 2 or 4).
• customAuthMethod: A pluggable signing method to support AWS Lambda or async functions.

Resilience and Optimization

• s3Acceleration: Enables S3 Transfer Acceleration.
• s3FileCacheHoursAgo: Controls recovery for huge files by determining how long to cache parts.
• allowS3ExistenceOptimization: Enables optimization by checking if the file already exists on S3.
• nameChanged: A callback invoked if the requested object name was not used (e.g., when reusing an interrupted upload).

When calling Evaporate.create(config) or new Evaporate(config), you can provide several configuration options.

Core Configuration:

• bucket: (Required) The AWS S3 bucket name.
• aws_key: The AWS access key.
• signerUrl: (Required if customAuthMethod is not provided) The URL used to obtain signed requests.
• awsRegion: The AWS region (defaults to 'us-east-1').
• awsSignatureVersion: The AWS signature version (defaults to '4').

Upload Behavior:

• maxConcurrentParts: Maximum number of parts to upload simultaneously (defaults to 5).
• partSize: Size of each part in bytes (defaults to 6 * 1024 * 1024, i.e., 6MB).
• maxFileSize: Maximum allowed file size. If exceeded, add() will reject.
• s3Acceleration: Enables S3 Transfer Acceleration.
• cloudfront: Enables CloudFront usage.

Resilience & Optimization:

• computeContentMd5: If true, computes MD5 for parts (requires cryptoMd5Method).
• allowS3ExistenceOptimization: If true and computeContentMd5 is enabled, attempts to reuse existing S3 objects if the MD5 matches.
• onlyRetryForSameFileName: If true, retries are only attempted if the filename hasn't changed.
• s3FileCacheHoursAgo: Number of hours to look back when checking for cached/interrupted uploads (must be a whole number).

Advanced:

• customAuthMethod: A function to implement custom authentication logic.
• signParams: Object containing parameters to be sent to the signer.
• signHeaders: Object containing headers to be sent to the signer.
• evaporateChanged: A callback function invoked whenever the number of evaporating parts changes.