API reference / @backpack/amazon-s3 / S3Service

Class: S3Service

Utility class to interact with an S3 Bucket.

Example

import { S3Client } from "@aws-sdk/client-s3";
import { S3Service } from "@backpack/amazon-s3";

const client = new S3Client();
const service = new S3Service(client, "my-bucket-name");

// puts an object
await service.putObject("your/object.json", "...");

// retrieves the object as text
const myObjectAsText = await service.getObject("your/object.json", {
  type: "text",
});

// retrieves the object as json
const myObjectAsJson = await service.getObject("your/object.json", {
  type: "json",
});

// retrieves the object as buffer
const myObjectAsBuffer = await service.getObject("your/object.json", {
  type: "buffer",
});

// deletes the object
await service.deleteObject("your/object.json");

Constructors

Constructor

new S3Service(
   client, 
   bucketName, 
   logger?): S3Service;

Parameters

Parameter	Type	Description
client	S3Client	The S3 client from AWS SDK.
bucketName	string	The name of the bucket.
logger?	Logger	Pass a PowerTools logger instance to enable logging.

Returns

S3Service

Methods

deleteObject()

Call Signature

deleteObject(objectKey): Promise<void>;

Deletes an object from S3

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to delete.

Returns

Promise<void>

Call Signature

deleteObject(objectKey, bucketName): Promise<void>;

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to delete.
bucketName	string	The name of the S3 bucket to delete the object from.

Returns

Promise<void>

Deprecated

use deleteObject(key) instead.

---

getObject()

Retrieves an object from S3.

Call Signature

getObject(objectKey, bucketName?): Promise<Buffer<ArrayBufferLike>>;

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
bucketName?	string	The name of the S3 bucket to retrieve the object from.

Returns

Promise<Buffer<ArrayBufferLike>>

Deprecated

use getObject(objectKey, { type: 'buffer' }) instead

Call Signature

getObject(objectKey, options?): Promise<Readable>;

Retrieves an object from S3 as readable stream.

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options?	{ type: "stream"; }	Additional options.
options.type?	"stream"	-

Returns

Promise<Readable>

Call Signature

getObject(objectKey, options): Promise<Buffer<ArrayBufferLike>>;

Retrieves an object from S3 as Buffer.

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options	{ type: "buffer"; }	Additional options.
options.type	"buffer"	-

Returns

Promise<Buffer<ArrayBufferLike>>

Call Signature

getObject(objectKey, options): Promise<string>;

Retrieves an object from S3 as text.

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options	{ type: "text"; }	Additional options.
options.type	"text"	-

Returns

Promise<string>

Call Signature

getObject(objectKey, options): Promise<ArrayBuffer>;

Retrieves an object from S3 as ArrayBuffer.

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options	{ type: "arrayBuffer"; }	Additional options.
options.type	"arrayBuffer"	-

Returns

Promise<ArrayBuffer>

Call Signature

getObject(objectKey, options): Promise<Blob>;

Retrieves an object from S3 as Blob.

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options	{ type: "blob"; }	Additional options.
options.type	"blob"	-

Returns

Promise<Blob>

Call Signature

getObject<T>(objectKey, options): Promise<T>;

Retrieves an object from S3 as JSON.

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
options	{ type: "json"; }	Additional options.
options.type	"json"	-

Returns

Promise<T>

---

getObjectStream()

getObjectStream(objectKey, bucketName): Promise<Readable>;

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to retrieve.
bucketName	string	The name of the S3 bucket to retrieve the object from.

Returns

Promise<Readable>

Deprecated

use getObject(key, { type: "stream" }) instead.

---

putObject()

putObject(
   objectKey, 
   body, 
metadata?): Promise<void>;

Puts an object into S3

Parameters

Parameter	Type	Description
objectKey	string	The key of the object to put.
body	| string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Readable	The data of the object
metadata?	Record<string, string>	Additional metadata for the object.

Returns

Promise<void>