Buckets service

Introduction

The S3 Bucket service is used when we want to make changes to buckets.

We can do multiple things with this service like:

create buckets
list buckets
delete buckets
tag buckets, etc.

Basic usage

The pre-requisites to use this service are to have the main module initialized in our app, so we can access all the services it exports. Later, when we need a service we can simply:

import { Injectable } from '@nestjs/common';
import { BucketsService } from '@lab08/nestjs-s3';

@Injectable()
export class MyService {
  public constructor(private readonly bucketService: BucketService) {}
}

then we can simply call start using the service freely.

Listing buckets

One of the things we can do is list buckets. In other to do that we can use the list method of the service

const buckets = await this.bucketService.list();

which will return a Promise containing

interface ListBucketsCommandOutput {
  /**
   * The list of buckets owned by the requestor.
   */
  Buckets?: Bucket[];
  /**
   * The owner of the buckets listed.
   */
  Owner?: Owner;
  /**
   * Metadata pertaining to this request.
   */
  $metadata: ResponseMetadata;
}

Creating buckets

When we need to create a new bucket we can just simply call

const bucket = await this.bucketService.create('test-bucket');

const bucket = await this.bucketService.create('test-bucket', options);

where options can be

export interface CreateBucketRequest {
  /**
   * The canned ACL to apply to the bucket.
   */
  ACL?: BucketCannedACL | string;
  /**
   * The configuration information for the bucket.
   */
  CreateBucketConfiguration?: CreateBucketConfiguration;
  /**
   * Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
   */
  GrantFullControl?: string;
  /**
   * Allows grantee to list the objects in the bucket.
   */
  GrantRead?: string;
  /**
   * Allows grantee to read the bucket ACL.
   */
  GrantReadACP?: string;
  /**
   * Allows grantee to create new objects in the bucket.
   * For the bucket and object owners of existing objects, it also allows deletions and overwrites.
   */
  GrantWrite?: string;
  /**
   * Allows grantee to write the ACL for the applicable bucket.
   */
  GrantWriteACP?: string;
  /**
   * Specifies whether you want S3 Object Lock for the new bucket.
   */
  ObjectLockEnabledForBucket?: boolean;
}

which will return a Promise containing

interface CreateBucketCommandOutput {
  /**
   * Specifies the Region where the bucket will be created. If you are creating a bucket on
   *          the US East (N. Virginia) Region (us-east-1), you do not need to specify the
   *          location.
   */
  Location?: string;
  /**
   * Metadata pertaining to this request.
   */
  $metadata: ResponseMetadata;
}

Deleting buckets

After we already have a bucket, we can easily remove it. This can be done by calling the delete method.

const result = await this.bucketService.delete('test-bucket');

which will return a Promise with the delete operation output

interface DeleteBucketCommandOutput {
  /**
   * Metadata pertaining to this request.
   */
  $metadata: ResponseMetadata;
}

Listing buckets

We can call the list method if we want to get all our existing buckets.

const result = await this.bucketService.list();

which will return a list of all the buckets, that we have access to. It returns a Promise with the following:

export interface ListBucketsCommandOutput {
  /**
   * <p>The list of buckets owned by the requestor.</p>
   */
  Buckets?: Bucket[];
  /**
   * <p>The owner of the buckets listed.</p>
   */
  Owner?: Owner;

  /**
   * Metadata pertaining to this request.
   */
  $metadata: ResponseMetadata;
}

Searching for a bucket by name

If we want to see if we have a bucket with a specific name, we can use the find method and pass the name of the bucket we want.

const result = await this.bucketService.find('test');

If found this method will return a Promise with a Bucket object, or if it cannot find a bucket - undefined.

Upading a bucket

Tagging

We can do other things with a bucket like updating tags

const result = await this.bucketService.tagging('test');

which will return a Promise with the following:

export interface GetBucketTaggingCommandOutput {
  /**
   * <p>Contains the tag set.</p>
   */
  TagSet: Tag[] | undefined;

  /**
   * Metadata pertaining to this request.
   */
  $metadata: ResponseMetadata;
}

Updating CORS

We can update the exsisting cors

const result = await this.bucketService.updateCors('test', options);

which can receive the following options

export interface CORSConfiguration {
  /**
   * <p>A set of origins and methods (cross-origin access you want to allow). You can add
   *          up to 100 rules to the configuration.</p>
   */
  CORSRules: CORSRule[] | undefined;
}