@aws-amplify/storage 5.4.1 → 5.5.0

package/src/Storage.ts

@@ -23,6 +23,8 @@ import {
 	StorageListOutput,
 	StorageCopyOutput,
 	UploadTask,
+	StorageGetPropertiesConfig,
+	StorageGetPropertiesOutput,
 } from './types';
 import axios, { CancelTokenSource } from 'axios';
 import { PutObjectCommandInput } from '@aws-sdk/client-s3';
@@ -246,22 +248,22 @@ export class Storage {
 		config?: StorageCopyConfig<T>
 	): StorageCopyOutput<T> {
 		const provider = config?.provider || DEFAULT_PROVIDER;
-		const prov = this._pluggables.find(
+		const plugin = this._pluggables.find(
 			pluggable => pluggable.getProviderName() === provider
 		);
-		if (prov === undefined) {
+		if (plugin === undefined) {
 			logger.debug('No plugin found with providerName', provider);
 			return Promise.reject(
 				'No plugin found in Storage for the provider'
 			) as StorageCopyOutput<T>;
 		}
 		const cancelTokenSource = this.getCancellableTokenSource();
-		if (typeof prov.copy !== 'function') {
+		if (typeof plugin.copy !== 'function') {
 			return Promise.reject(
-				`.copy is not implemented on provider ${prov.getProviderName()}`
+				`.copy is not implemented on provider ${plugin.getProviderName()}`
 			) as StorageCopyOutput<T>;
 		}
-		const responsePromise = prov.copy(src, dest, {
+		const responsePromise = plugin.copy(src, dest, {
 			...config,
 			cancelTokenSource,
 		});
@@ -285,17 +287,17 @@ export class Storage {
 		T extends StorageProvider | { [key: string]: any; download?: boolean }
 	>(key: string, config?: StorageGetConfig<T>): StorageGetOutput<T> {
 		const provider = config?.provider || DEFAULT_PROVIDER;
-		const prov = this._pluggables.find(
+		const plugin = this._pluggables.find(
 			pluggable => pluggable.getProviderName() === provider
 		);
-		if (prov === undefined) {
+		if (plugin === undefined) {
 			logger.debug('No plugin found with providerName', provider);
 			return Promise.reject(
 				'No plugin found in Storage for the provider'
 			) as StorageGetOutput<T>;
 		}
 		const cancelTokenSource = this.getCancellableTokenSource();
-		const responsePromise = prov.get(key, {
+		const responsePromise = plugin.get(key, {
 			...config,
 			cancelTokenSource,
 		});
@@ -307,6 +309,30 @@ export class Storage {
 		return axios.isCancel(error);
 	}
 
+	public getProperties<T extends StorageProvider | { [key: string]: any }>(
+		key: string,
+		config?: StorageGetPropertiesConfig<T>
+	): StorageGetPropertiesOutput<T> {
+		const provider = config?.provider || DEFAULT_PROVIDER;
+		const plugin = this._pluggables.find(
+			pluggable => pluggable.getProviderName() === provider
+		);
+		if (plugin === undefined) {
+			logger.debug('No plugin found with providerName', provider);
+			throw new Error('No plugin found with providerName');
+		}
+		const cancelTokenSource = this.getCancellableTokenSource();
+		if (typeof plugin.getProperties !== 'function') {
+			return Promise.reject(
+				`.getProperties is not implemented on provider ${plugin.getProviderName()}`
+			) as StorageGetPropertiesOutput<T>;
+		}
+		const responsePromise = plugin?.getProperties(key, {
+			...config,
+		});
+		this.updateRequestToBeCancellable(responsePromise, cancelTokenSource);
+		return responsePromise as StorageGetPropertiesOutput<T>;
+	}
 	/**
 	 * Put a file in storage bucket specified to configure method
 	 * @param key - key of the object
@@ -326,17 +352,17 @@ export class Storage {
 		config?: StoragePutConfig<T>
 	): StoragePutOutput<T> {
 		const provider = config?.provider || DEFAULT_PROVIDER;
-		const prov = this._pluggables.find(
+		const plugin = this._pluggables.find(
 			pluggable => pluggable.getProviderName() === provider
 		);
-		if (prov === undefined) {
+		if (plugin === undefined) {
 			logger.debug('No plugin found with providerName', provider);
 			return Promise.reject(
 				'No plugin found in Storage for the provider'
 			) as StoragePutOutput<T>;
 		}
 		const cancelTokenSource = this.getCancellableTokenSource();
-		const response = prov.put(key, object, {
+		const response = plugin.put(key, object, {
 			...config,
 			cancelTokenSource,
 		});
@@ -361,16 +387,16 @@ export class Storage {
 		config?: StorageRemoveConfig<T>
 	): StorageRemoveOutput<T> {
 		const provider = config?.provider || DEFAULT_PROVIDER;
-		const prov = this._pluggables.find(
+		const plugin = this._pluggables.find(
 			pluggable => pluggable.getProviderName() === provider
 		);
-		if (prov === undefined) {
+		if (plugin === undefined) {
 			logger.debug('No plugin found with providerName', provider);
 			return Promise.reject(
 				'No plugin found in Storage for the provider'
 			) as StorageRemoveOutput<T>;
 		}
-		return prov.remove(key, config) as StorageRemoveOutput<T>;
+		return plugin.remove(key, config) as StorageRemoveOutput<T>;
 	}
 
 	/**
@@ -388,16 +414,16 @@ export class Storage {
 		config?: StorageListConfig<T>
 	): StorageListOutput<T> {
 		const provider = config?.provider || DEFAULT_PROVIDER;
-		const prov = this._pluggables.find(
+		const plugin = this._pluggables.find(
 			pluggable => pluggable.getProviderName() === provider
 		);
-		if (prov === undefined) {
+		if (plugin === undefined) {
 			logger.debug('No plugin found with providerName', provider);
 			return Promise.reject(
 				'No plugin found in Storage for the provider'
 			) as StorageListOutput<T>;
 		}
-		return prov.list(path, config) as StorageListOutput<T>;
+		return plugin.list(path, config) as StorageListOutput<T>;
 	}
 }
 

package/src/providers/AWSS3Provider.ts

@@ -21,6 +21,7 @@ import {
 	GetObjectCommandInput,
 	ListObjectsV2Request,
 	HeadObjectCommand,
+	HeadObjectCommandInput,
 } from '@aws-sdk/client-s3';
 import { formatUrl } from '@aws-sdk/util-format-url';
 import { createRequest } from '@aws-sdk/util-create-request';
@@ -49,6 +50,8 @@ import {
 	UploadTask,
 	S3ClientOptions,
 	S3ProviderListOutput,
+	S3ProviderGetPropertiesOutput,
+	S3ProviderGetPropertiesConfig,
 } from '../types';
 import { StorageErrorStrings } from '../common/StorageErrorStrings';
 import { dispatchStorageEvent } from '../common/StorageUtils';
@@ -498,6 +501,87 @@ export class AWSS3Provider implements StorageProvider {
 		}
 	}
 
+	/**
+	 * Get Properties of the object
+	 *
+	 * @param {string} key - key of the object
+	 * @param {S3ProviderGetPropertiesConfig} [config] - Optional configuration for the underlying S3 command
+	 * @return {Promise<S3ProviderGetPropertiesOutput>} - A promise resolves to contentType,
+	 * contentLength, eTag, lastModified, metadata
+	 */
+	public async getProperties(
+		key: string,
+		config?: S3ProviderGetPropertiesConfig
+	): Promise<S3ProviderGetPropertiesOutput> {
+		const credentialsOK = await this._ensureCredentials();
+		if (!credentialsOK || !this._isWithCredentials(this._config)) {
+			throw new Error(StorageErrorStrings.NO_CREDENTIALS);
+		}
+		const opt = Object.assign({}, this._config, config);
+		const {
+			bucket,
+			track = false,
+			SSECustomerAlgorithm,
+			SSECustomerKey,
+			SSECustomerKeyMD5,
+		} = opt;
+		const prefix = this._prefix(opt);
+		const final_key = prefix + key;
+		const emitter = new events.EventEmitter();
+		const s3 = this._createNewS3Client(opt, emitter);
+		logger.debug(`getProperties ${key} from ${final_key}`);
+
+		const params: HeadObjectCommandInput = {
+			Bucket: bucket,
+			Key: final_key,
+		};
+
+		if (SSECustomerAlgorithm) {
+			params.SSECustomerAlgorithm = SSECustomerAlgorithm;
+		}
+		if (SSECustomerKey) {
+			params.SSECustomerKey = SSECustomerKey;
+		}
+		if (SSECustomerKeyMD5) {
+			params.SSECustomerKeyMD5 = SSECustomerKeyMD5;
+		}
+		// See: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/classes/headobjectcommand.html
+
+		const headObjectCommand = new HeadObjectCommand(params);
+		try {
+			const response = await s3.send(headObjectCommand);
+			const getPropertiesResponse: S3ProviderGetPropertiesOutput = {
+				contentLength: response.ContentLength,
+				contentType: response.ContentType,
+				eTag: response.ETag,
+				lastModified: response.LastModified,
+				metadata: response.Metadata,
+			};
+			dispatchStorageEvent(
+				track,
+				'getProperties',
+				{ method: 'getProperties', result: 'success' },
+				null,
+				`getProperties successful for ${key}`
+			);
+			return getPropertiesResponse;
+		} catch (error) {
+			if (error.$metadata.httpStatusCode === 404) {
+				dispatchStorageEvent(
+					track,
+					'getProperties',
+					{
+						method: 'getProperties',
+						result: 'failed',
+					},
+					null,
+					`${key} not found`
+				);
+			}
+			throw error;
+		}
+	}
+
 	/**
 	 * Put a file in S3 bucket specified to configure method
 	 * @param key - key of the object

package/src/types/AWSS3Provider.ts

@@ -5,6 +5,7 @@ import {
 	CopyObjectRequest,
 	_Object,
 	DeleteObjectCommandOutput,
+	HeadObjectRequest,
 } from '@aws-sdk/client-s3';
 import { StorageOptions, StorageAccessLevel } from './Storage';
 import {
@@ -51,6 +52,12 @@ export type S3ProviderGetConfig = CommonStorageOptions & {
 	validateObjectExistence?: boolean;
 };
 
+export type S3ProviderGetPropertiesConfig = CommonStorageOptions & {
+	SSECustomerAlgorithm?: HeadObjectRequest['SSECustomerAlgorithm'];
+	SSECustomerKey?: HeadObjectRequest['SSECustomerKey'];
+	SSECustomerKeyMD5?: HeadObjectRequest['SSECustomerKeyMD5'];
+};
+
 export type S3ProviderGetOuput<T> = T extends { download: true }
 	? GetObjectCommandOutput
 	: string;
@@ -173,6 +180,14 @@ export type S3ProviderCopyOutput = {
 	key: string;
 };
 
+export type S3ProviderGetPropertiesOutput = {
+	contentType: string;
+	contentLength: number;
+	eTag: string;
+	lastModified: Date;
+	metadata: Record<string, string>;
+};
+
 export type PutResult = {
 	key: string;
 };

package/src/types/Provider.ts

@@ -1,4 +1,8 @@
-import { StorageCopySource, StorageCopyDestination } from './Storage';
+import {
+	StorageCopySource,
+	StorageCopyDestination,
+	StorageCopyConfig,
+} from './Storage';
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 export interface StorageProvider {
@@ -20,6 +24,9 @@ export interface StorageProvider {
 	// get object/pre-signed url from storage
 	get(key: string, options?): Promise<string | Object>;
 
+	// get properties of object
+	getProperties?(key: string, options?): Promise<Object>;
+
 	// upload storage object
 	put(key: string, object, options?): Promise<Object> | UploadTask;
 
@@ -52,4 +59,14 @@ export interface StorageProviderWithCopy extends StorageProvider {
 	): Promise<any>;
 }
 
-export type StorageProviderApi = 'copy' | 'get' | 'put' | 'remove' | 'list';
+export interface StorageProviderWithGetProperties extends StorageProvider {
+	getProperties(key: string, options?): Promise<Object>;
+}
+
+export type StorageProviderApi =
+	| 'copy'
+	| 'get'
+	| 'put'
+	| 'remove'
+	| 'list'
+	| 'getProperties';

package/src/types/Storage.ts

@@ -15,6 +15,8 @@ import {
 	S3ProviderListOutput,
 	S3ProviderCopyOutput,
 	S3ProviderPutOutput,
+	S3ProviderGetPropertiesOutput,
+	StorageProviderWithGetProperties,
 } from '../';
 
 type Tail<T extends any[]> = ((...t: T) => void) extends (
@@ -69,13 +71,26 @@ export type StorageCopyDestination = Omit<StorageCopyTarget, 'identityId'>;
  * config.
  */
 type StorageOperationConfig<
-	T extends StorageProvider | StorageProviderWithCopy,
+	T extends
+		| StorageProvider
+		| StorageProviderWithCopy
+		| StorageProviderWithGetProperties,
 	U extends StorageProviderApi
 > = ReturnType<T['getProviderName']> extends 'AWSS3'
 	? LastParameter<AWSS3Provider[U]> // check if it has 'copy' function because 'copy' is optional
+	: T extends StorageProviderWithGetProperties & StorageProviderWithCopy
+	? LastParameter<T[U]> & {
+			provider: ReturnType<T['getProviderName']>;
+	  }
 	: T extends StorageProviderWithCopy
-	? LastParameter<T[U]> & { provider: ReturnType<T['getProviderName']> }
-	: LastParameter<T[Exclude<U, 'copy'>]> & {
+	? LastParameter<T[Exclude<U, 'getProperties'>]> & {
+			provider: ReturnType<T['getProviderName']>;
+	  }
+	: T extends StorageProviderWithGetProperties
+	? LastParameter<T[Exclude<U, 'copy'>]> & {
+			provider: ReturnType<T['getProviderName']>;
+	  }
+	: LastParameter<T[Exclude<U, 'copy' | 'getProperties'>]> & {
 			provider: ReturnType<T['getProviderName']>;
 	  };
 
@@ -87,6 +102,14 @@ export type StorageGetConfig<T extends Record<string, any>> =
 				T
 		  >;
 
+export type StorageGetPropertiesConfig<T extends Record<string, any>> =
+	T extends StorageProviderWithGetProperties
+		? StorageOperationConfig<T, 'getProperties'>
+		: StorageOperationConfigMap<
+				StorageOperationConfig<AWSS3Provider, 'getProperties'>,
+				T
+		  >;
+
 export type StoragePutConfig<T extends Record<string, any>> =
 	T extends StorageProvider
 		? StorageOperationConfig<T, 'put'>
@@ -132,9 +155,13 @@ type PickProviderOutput<
 > = T extends StorageProvider
 	? T['getProviderName'] extends 'AWSS3'
 		? DefaultOutput
-		: T extends StorageProviderWithCopy
+		: T extends StorageProviderWithCopy & StorageProviderWithGetProperties
 		? ReturnType<T[api]>
-		: ReturnType<T[Exclude<api, 'copy'>]>
+		: T extends StorageProviderWithCopy
+		? ReturnType<T[Exclude<api, 'getProperties'>]>
+		: T extends StorageProviderWithGetProperties
+		? ReturnType<T[Exclude<api, 'copy'>]>
+		: ReturnType<T[Exclude<api, 'copy' | 'getProperties'>]>
 	: T extends { provider: string }
 	? T extends { provider: 'AWSS3' }
 		? DefaultOutput
@@ -168,6 +195,12 @@ export type StorageCopyOutput<T> = PickProviderOutput<
 	'copy'
 >;
 
+export type StorageGetPropertiesOutput<T> = PickProviderOutput<
+	Promise<S3ProviderGetPropertiesOutput>,
+	T,
+	'getProperties'
+>;
+
 /**
  * Utility type to allow custom provider to use any config keys, if provider is set to AWSS3 then it should use
  * AWSS3Provider's config.