@aws-amplify/storage

@aws-amplify/storage

Version 6.9.1
Published 5 days ago
2.25 MB
6 dependencies
Apache-2.0 license

Install

npm i @aws-amplify/storage

yarn add @aws-amplify/storage

pnpm add @aws-amplify/storage

Overview

Storage category of aws-amplify

Variables

variable DEFAULT_PART_SIZE

const DEFAULT_PART_SIZE: number;

Default part size in MB that is used to determine if an upload task is single part or multi part.

Functions

function copy

copy: {
    (input: CopyWithPathInput): Promise<CopyWithPathOutput>;
    (input: CopyInput): Promise<CopyOutput>;
};

Copy an object from a source to a destination object within the same bucket.
Parameter input
The CopyWithPathInput object.
Returns
Output containing the destination object path.
Throws
service: S3Exception - Thrown when checking for existence of the object
Throws
validation: StorageValidationErrorCode - Thrown when source or destination path is not defined.
Parameter input
The CopyInput object.
Returns
Output containing the destination object key.
Throws
service: S3Exception - Thrown when checking for existence of the object
Throws
validation: StorageValidationErrorCode - Thrown when source or destination key is not defined.
Deprecated
The key and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead.
Copy an object from a source to a destination object within the same bucket. Can optionally copy files across different accessLevel or identityId (if source object's accessLevel is 'protected').

function downloadData

downloadData: {
    (input: DownloadDataWithPathInput): DownloadDataWithPathOutput;
    (input: DownloadDataInput): DownloadDataOutput;
};

Download S3 object data to memory

Parameter input

The DownloadDataWithPathInput 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({ path, options: {
  onProgress, // Optional progress callback.
} }).result;

Example 2

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

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, options: { onProgress, // Optional progress callback. } }).result;
Example 2
// Cancel a task const downloadTask = downloadData({ key }); //... downloadTask.cancel(); try { await downloadTask.result; } catch (error) { if(isCancelError(error)) { // Handle error thrown by task cancelation. } }
Deprecated
The key and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead.
Download S3 object data to memory

function getProperties

getProperties: {
    (input: GetPropertiesWithPathInput): Promise<GetPropertiesWithPathOutput>;
    (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 GetPropertiesWithPathInput object.
Returns
Requested object properties.
Throws
An S3Exception when the underlying S3 service returned error.
Throws
A StorageValidationErrorCode when API call parameters are invalid.
Parameter input
The GetPropertiesInput object.
Returns
Requested object properties.
Throws
An S3Exception when the underlying S3 service returned error.
Throws
A StorageValidationErrorCode when API call parameters are invalid.
Deprecated
The key and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead.
Gets the properties of a file. The properties include S3 system metadata and the user metadata that was provided when uploading the file.

function getUrl

getUrl: {
    (input: GetUrlWithPathInput): Promise<GetUrlWithPathOutput>;
    (input: GetUrlInput): Promise<StorageGetUrlOutput>;
};

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 GetUrlWithPathInput 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.
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.
Deprecated
The key and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead.
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.

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.
Parameter error
The unknown exception to be checked.
Returns
- A boolean indicating if the error was from an upload cancellation

function list

list: {
    (input: ListPaginateWithPathInput): Promise<ListPaginateWithPathOutput>;
    (input: ListAllWithPathInput): Promise<ListAllWithPathOutput>;
    (input?: ListPaginateInput): Promise<ListPaginateOutput>;
    (input?: ListAllInput): Promise<ListAllOutput>;
};

List files in pages with the given path. pageSize is defaulted to 1000. Additionally, the result will include a nextToken if there are more items to retrieve.
Parameter input
The ListPaginateWithPathInput object.
Returns
A list of objects with path and metadata
Throws
service: S3Exception - S3 service errors thrown when checking for existence of bucket
Throws
validation: StorageValidationErrorCode - thrown when there are issues with credentials
List all files from S3 for a given path. You can set listAll to true in options to get all the files from S3.
Parameter input
The ListAllWithPathInput object.
Returns
A list of all objects with path and metadata
Throws
service: S3Exception - S3 service errors thrown when checking for existence of bucket
Throws
validation: StorageValidationErrorCode - thrown when there are issues with credentials
Parameter input
The ListPaginateInput object.
Returns
A list of objects with key and metadata
Throws
service: S3Exception - S3 service errors thrown when checking for existence of bucket
Throws
validation: StorageValidationErrorCode - thrown when there are issues with credentials
Deprecated
The prefix and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead. List files in pages with the given prefix. pageSize is defaulted to 1000. Additionally, the result will include a nextToken if there are more items to retrieve.
Parameter input
The ListAllInput object.
Returns
A list of all objects with key and metadata
Throws
service: S3Exception - S3 service errors thrown when checking for existence of bucket
Throws
validation: StorageValidationErrorCode - thrown when there are issues with credentials
Deprecated
The prefix and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead. List all files from S3 for a given prefix. You can set listAll to true in options to get all the files from S3.

function remove

remove: {
    (input: RemoveWithPathInput): Promise<RemoveWithPathOutput>;
    (input: RemoveInput): Promise<RemoveOutput>;
};

Remove a file from your S3 bucket.
Parameter input
The RemoveWithPathInput object. Output containing the removed object path.
Throws
service: S3Exception - S3 service errors thrown while while removing the object.
Throws
validation: StorageValidationErrorCode - Validation errors thrown when there is no path or path is empty or path has a leading slash.
Parameter input
The RemoveInput object. Output containing the removed object key
Throws
service: S3Exception - S3 service errors thrown while while removing the object
Throws
validation: StorageValidationErrorCode - Validation errors thrown when there is no key or its empty.
Deprecated
The key and accessLevel parameters are deprecated and may be removed in the next major version. Please use path instead.
Remove a file from your S3 bucket.

function uploadData

uploadData: {
    (input: UploadDataWithPathInput): UploadDataWithPathOutput;
    (input: UploadDataInput): UploadDataOutput;
};

Upload data to the specified S3 object path. By default uses single PUT operation to upload if the payload is less than 5MB. Otherwise, uses multipart upload to upload the payload. If the payload length cannot be determined, uses multipart upload.
Limitations: * Maximum object size is 5TB. * Maximum object size if the size cannot be determined before upload is 50GB.
Parameter input
A UploadDataWithPathInput 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 thrown when a validation error occurs.
Example 1
// Upload a file to s3 bucket await uploadData({ path, data: file, options: { onProgress, // Optional progress callback. } }).result;
Example 2
// Cancel a task const uploadTask = uploadData({ path, 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({ path, data: file }); //... uploadTask.pause(); //... uploadTask.resume(); //... await uploadTask.result;
Upload data to the specified S3 object key. By default uses single PUT operation to upload if the payload is less than 5MB. Otherwise, uses multipart upload to upload the payload. If the payload length cannot be determined, uses multipart upload.
Limitations: * Maximum object size is 5TB. * Maximum object size if the size cannot be determined before upload is 50GB.
Parameter input
A UploadDataInput object.
Returns
A cancelable and resumable task exposing result promise from the result property.
Throws
Service: S3Exception thrown when checking for existence of the object.
Throws
Validation: StorageValidationErrorCode thrown when a validation error occurs.
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;
Deprecated
The key and accessLevel parameters are deprecated and will be removed in next major version. Please use path instead.

Classes

class StorageError

class StorageError extends AmplifyError {}

constructor

constructor(params: AmplifyErrorParams);

Interfaces

interface TransferProgressEvent

interface TransferProgressEvent {}

property totalBytes

totalBytes?: number;

property transferredBytes

transferredBytes: number;

Type Aliases

type CopyInput

type CopyInput = StorageCopyInputWithKey<
    CopySourceWithKeyOptions,
    CopyDestinationWithKeyOptions
>;

Deprecated
Use CopyWithPathInput instead. Input type for S3 copy API.

type CopyOutput

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

Output type with path for S3 copy API.
Deprecated
Use CopyWithPathOutput instead.

type CopyWithPathInput

type CopyWithPathInput = StorageCopyInputWithPath;

Input type with path for S3 copy API.

type CopyWithPathOutput

type CopyWithPathOutput = Pick<ItemWithPath, 'path'>;

Output type with path for S3 copy API.

type DownloadDataInput

type DownloadDataInput = StorageDownloadDataInputWithKey<DownloadDataWithKeyOptions>;

Deprecated
Use DownloadDataWithPathInput instead. Input type for S3 downloadData API.

type DownloadDataOutput

type DownloadDataOutput = DownloadTask<StorageDownloadDataOutput<ItemWithKey>>;

Output type for S3 downloadData API.
Deprecated
Use DownloadDataWithPathOutput instead.

type DownloadDataWithPathInput

type DownloadDataWithPathInput =
    StorageDownloadDataInputWithPath<DownloadDataWithPathOptions>;

Input type with path for S3 downloadData API.

type DownloadDataWithPathOutput

type DownloadDataWithPathOutput = DownloadTask<
    StorageDownloadDataOutput<ItemWithPath>
>;

Output type with path for S3 downloadData API.

type GetPropertiesInput

type GetPropertiesInput =
    StorageGetPropertiesInputWithKey<GetPropertiesWithKeyOptions>;

Deprecated
Use GetPropertiesWithPathInput instead. Input type for S3 getProperties API.

type GetPropertiesOutput

type GetPropertiesOutput = ItemBase & StorageItemWithKey;

Output type for S3 getProperties API.
Deprecated
Use GetPropertiesWithPathOutput instead.

type GetPropertiesWithPathInput

type GetPropertiesWithPathInput =
    StorageGetPropertiesInputWithPath<GetPropertiesWithPathOptions>;

Input type with for S3 getProperties API.

type GetPropertiesWithPathOutput

type GetPropertiesWithPathOutput = ItemBase & StorageItemWithPath;

Output type with path for S3 getProperties API.

type GetUrlInput

type GetUrlInput = StorageGetUrlInputWithKey<GetUrlWithKeyOptions>;

Deprecated
Use GetUrlWithPathInput instead. Input type for S3 getUrl API.

type GetUrlOutput

type GetUrlOutput = StorageGetUrlOutput;

Output type for S3 getUrl API.
Deprecated
Use GetUrlWithPathOutput instead.

type GetUrlWithPathInput

type GetUrlWithPathInput = StorageGetUrlInputWithPath<GetUrlWithPathOptions>;

Input type with path for S3 getUrl API.

type GetUrlWithPathOutput

type GetUrlWithPathOutput = StorageGetUrlOutput;

Output type with path for S3 getUrl API.

type ListAllInput

type ListAllInput = StorageListInputWithPrefix<ListAllWithPrefixOptions>;

Deprecated
Use ListAllWithPathInput instead. Input type for S3 list API. Lists all bucket objects.

type ListAllOutput

type ListAllOutput = Omit<StorageListOutput<ListOutputItem>, 'excludedSubpaths'>;

Deprecated
Use ListAllWithPathOutput instead. Output type for S3 list API. Lists all bucket objects.

type ListAllWithPathInput

type ListAllWithPathInput = StorageListInputWithPath<ListAllWithPathOptions>;

Input type with path for S3 list API. Lists all bucket objects.

type ListAllWithPathOutput

type ListAllWithPathOutput = StorageListOutput<ListOutputItemWithPath>;

Output type with path for S3 list API. Lists all bucket objects.

type ListPaginateInput

type ListPaginateInput = StorageListInputWithPrefix<ListPaginateWithPrefixOptions>;

Deprecated
Use ListPaginateWithPathInput instead. Input type for S3 list API. Lists bucket objects with pagination.

type ListPaginateOutput

type ListPaginateOutput = Omit<
    StorageListOutput<ListOutputItem>,
    'excludedSubpaths'
> & {
    nextToken?: string;
};

Deprecated
Use ListPaginateWithPathOutput instead. Output type for S3 list API. Lists bucket objects with pagination.

type ListPaginateWithPathInput

type ListPaginateWithPathInput =
    StorageListInputWithPath<ListPaginateWithPathOptions>;

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

type ListPaginateWithPathOutput

type ListPaginateWithPathOutput = StorageListOutput<ListOutputItemWithPath> & {
    nextToken?: string;
};

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

type RemoveInput

type RemoveInput = StorageRemoveInputWithKey<RemoveOptions>;

Deprecated
Use RemoveWithPathInput instead. Input type with key for S3 remove API.

type RemoveOutput

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

Deprecated
Use RemoveWithPathOutput instead. Output type with key for S3 remove API.

type RemoveWithPathInput

type RemoveWithPathInput = StorageRemoveInputWithPath<
    Omit<RemoveOptions, 'accessLevel'>
>;

Input type with path for S3 remove API.

type RemoveWithPathOutput

type RemoveWithPathOutput = Pick<ItemWithPath, 'path'>;

Output type with path for S3 remove API.

type UploadDataInput

type UploadDataInput = StorageUploadDataInputWithKey<UploadDataWithKeyOptions>;

Deprecated
Use UploadDataWithPathInput instead. Input type for S3 uploadData API.

type UploadDataOutput

type UploadDataOutput = UploadTask<ItemWithKey>;

Output type for S3 uploadData API.
Deprecated
Use UploadDataWithPathOutput instead.

type UploadDataWithPathInput

type UploadDataWithPathInput =
    StorageUploadDataInputWithPath<UploadDataWithPathOptions>;

Input type with path for S3 uploadData API.

type UploadDataWithPathOutput

type UploadDataWithPathOutput = UploadTask<ItemWithPath>;

Output type with path for S3 uploadData API.

Package Files (14)

Dependencies (6)

Dev Dependencies (3)

Peer Dependencies (1)

@aws-amplify/core

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@aws-amplify/storage.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@aws-amplify/storage)

HTML

<a href="https://www.jsdocs.io/package/@aws-amplify/storage"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 5038 ms.
Missing or incorrect documentation? Open an issue for this package.

@aws-amplify/storage

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Variables

variable DEFAULT_PART_SIZE

Functions

function copy

Parameter input

Returns

Throws

Throws

Parameter input

Returns

Throws

Throws

Deprecated

function downloadData

Parameter input

Returns

Throws

Throws

Example 1

Example 2

Parameter input

Returns

Throws

Throws

Example 1

Example 2

Deprecated

function getProperties

Parameter input

Returns

Throws

Throws

Parameter input

Returns

Throws

Throws

Deprecated

function getUrl

Parameter input

Returns

Throws

Throws

Parameter input

Returns

Throws

Throws

Deprecated

function isCancelError

Parameter error

Returns

function list

Parameter input

Returns

Throws

Throws

Parameter input

Returns

Throws

Throws

Parameter input

Returns

Throws

Throws

Deprecated

Parameter input

Returns

Throws

Throws

Deprecated

function remove

Parameter input