@aws-amplify/storage

Variables

• list

Functions

• copy()
• downloadData()
• getProperties()
• getUrl()
• isCancelError()
• remove()
• uploadData()

Classes

• StorageError

Type Aliases

• CopyInput
• CopyOutput
• DownloadDataInput
• DownloadDataOutput
• GetPropertiesInput
• GetPropertiesOutput
• GetUrlInput
• GetUrlOutput
• ListAllInput
• ListAllOutput
• ListPaginateInput
• ListPaginateOutput
• RemoveInput
• RemoveOutput
• TransferProgressEvent
• UploadDataInput
• UploadDataOutput

variable list

const list: ListApi;

function copy

copy: (input: CopyInput) => Promise<CopyOutput>;

• Copy an object from a source object to a new object within the same bucket. Can optionally copy files across different level or identityId (if source object's level is 'protected').

  Parameter input

  The CopyInput object.

  Returns

  Output containing the destination key.

  Throws

  service: S3Exception - Thrown when checking for existence of the object

  Throws

  validation: StorageValidationErrorCode - Thrown when source or destination key are not defined.

function downloadData

downloadData: (input: DownloadDataInput) => DownloadDataOutput;

• Download S3 object data to memory

  Parameter input

  The DownloadDataInput object.

  Returns

  A cancelable task exposing result promise from result property.

  Throws

  service: S3Exception - thrown when checking for existence of the object

  Throws

  validation: StorageValidationErrorCode - Validation errors

  Example 1

  // Download a file from s3 bucket
  const { body, eTag } = await downloadData({ key, data: file, options: {
    onProgress, // Optional progress callback.
  } }).result;

  Example 2

  // Cancel a task
  const downloadTask = downloadData({ key, data: file });
  //...
  downloadTask.cancel();
  try {
  	await downloadTask.result;
  } catch (error) {
  	if(isCancelError(error)) {
     // Handle error thrown by task cancelation.
  	}
  }

function getProperties

getProperties: (input: GetPropertiesInput) => Promise<GetPropertiesOutput>;

• Gets the properties of a file. The properties include S3 system metadata and the user metadata that was provided when uploading the file.

  Parameter input

  The GetPropertiesInput object.

  Returns

  Requested object properties.

  Throws

  A S3Exception when the underlying S3 service returned error.

  Throws

  A StorageValidationErrorCode when API call parameters are invalid.

function getUrl

getUrl: (input: GetUrlInput) => Promise<GetUrlOutput>;

• Get a temporary presigned URL to download the specified S3 object. The presigned URL expires when the associated role used to sign the request expires or the option expiresIn is reached. The expiresAt property in the output object indicates when the URL MAY expire.

  By default, it will not validate the object that exists in S3. If you set the options.validateObjectExistence to true, this method will verify the given object already exists in S3 before returning a presigned URL, and will throw StorageError if the object does not exist.

  Parameter input

  The GetUrlInput object.

  Returns

  Presigned URL and timestamp when the URL MAY expire.

  Throws

  service: S3Exception - thrown when checking for existence of the object

  Throws

  validation: StorageValidationErrorCode - Validation errors thrown either username or key are not defined.

function isCancelError

isCancelError: (error: unknown) => error is CanceledError;

• Check if an error is caused by user calling cancel() on a upload/download task. If an overwriting error is supplied to task.cancel(errorOverwrite), this function will return false.

function remove

remove: (input: RemoveInput) => Promise<RemoveOutput>;

• Remove a file from your S3 bucket.

  Parameter input

  The RemoveInput object. Output containing the removed object key

  Throws

  service: S3Exception - S3 service errors thrown while getting properties

  Throws

  validation: StorageValidationErrorCode - Validation errors thrown

function uploadData

uploadData: (input: UploadDataInput) => UploadDataOutput;

• Upload data to specified S3 object. By default, it uses single PUT operation to upload if the data is less than 5MB. Otherwise, it uses multipart upload to upload the data. If the data length is unknown, it uses multipart upload.

  Limitations: * Maximum object size is 5TB. * Maximum object size if the size cannot be determined before upload is 50GB.

  Parameter input

  The UploadDataInput object.

  Returns

  A cancelable and resumable task exposing result promise from result property.

  Throws

  service: S3Exception - thrown when checking for existence of the object

  Throws

  validation: StorageValidationErrorCode - Validation errors.

  Example 1

  // Upload a file to s3 bucket
  await uploadData({ key, data: file, options: {
    onProgress, // Optional progress callback.
  } }).result;

  Example 2

  // Cancel a task
  const uploadTask = uploadData({ key, data: file });
  //...
  uploadTask.cancel();
  try {
    await uploadTask.result;
  } catch (error) {
    if(isCancelError(error)) {
      // Handle error thrown by task cancelation.
    }
  }

  Example 3

  // Pause and resume a task
  const uploadTask = uploadData({ key, data: file });
  //...
  uploadTask.pause();
  //...
  uploadTask.resume();
  //...
  await uploadTask.result;

type CopyInput

type CopyInput = StorageCopyInput<CopySourceOptions, CopyDestinationOptions>;

• Input type for S3 copy API.

type CopyOutput

type CopyOutput = Pick<Item, 'key'>;

• Output type for S3 copy API.

type DownloadDataInput

type DownloadDataInput = StorageDownloadDataInput<DownloadDataOptions>;

• Input type for S3 downloadData API.

type DownloadDataOutput

type DownloadDataOutput = DownloadTask<StorageDownloadDataOutput<Item>>;

• Output type for S3 downloadData API.

type GetPropertiesInput

type GetPropertiesInput = StorageGetPropertiesInput<GetPropertiesOptions>;

• Input type for S3 getProperties API.

type GetPropertiesOutput

type GetPropertiesOutput = Item;

• Output type for S3 getProperties API.

type GetUrlInput

type GetUrlInput = StorageGetUrlInput<GetUrlOptions>;

• Input type for S3 getUrl API.

type GetUrlOutput

type GetUrlOutput = StorageGetUrlOutput;

• Output type for S3 getUrl API.

type ListAllInput

type ListAllInput = StorageListInput<ListAllOptions>;

• Input type for S3 list API. Lists all bucket objects.

type ListAllOutput

type ListAllOutput = StorageListOutput<ListOutputItem>;

• Output type for S3 list API. Lists all bucket objects.

type ListPaginateInput

type ListPaginateInput = StorageListInput<ListPaginateOptions>;

• Input type for S3 list API. Lists bucket objects with pagination.

type ListPaginateOutput

type ListPaginateOutput = StorageListOutput<ListOutputItem> & {
    nextToken?: string;
};

• Output type for S3 list API. Lists bucket objects with pagination.

type RemoveInput

type RemoveInput = StorageRemoveInput<RemoveOptions>;

• Input type for S3 remove API.

type RemoveOutput

type RemoveOutput = Pick<Item, 'key'>;

• Output type for S3 remove API.

type TransferProgressEvent

type TransferProgressEvent = {
    transferredBytes: number;
    totalBytes?: number;
};

type UploadDataInput

type UploadDataInput = StorageUploadDataInput<UploadDataOptions>;

• Input type for S3 uploadData API.

type UploadDataOutput

type UploadDataOutput = UploadTask<Item>;

• Output type for S3 uploadData API.