GcsModule

The GcsModule (Google Cloud Storage Module) is a NestJS module that provides a Google Cloud Storage client and service to enable you to work with buckets. It simplifies the process of interacting with Google Cloud Storage by abstracting away some of the complexities, making it easier to manage, store, and retrieve data from your buckets within your NestJS application.

Key Components

The module provides a set of reusable components that can be easily integrated into a NestJS project:

Google Storage Client

The Google Storage client provider is a component within the GcsModule that offers a convenient way to interact with Google Cloud Storage in your NestJS application. This provider wraps the Google Cloud Storage SDK, making it easy to configure, authenticate, and perform operations on your storage buckets.

Google Cloud Storage Service

The GcsService is a helpful utility that allows you to manage and interact with multiple Google Cloud Storage buckets in your application. By defining your buckets in the .env.yaml file with their respective names, aliases, and types, you can easily access and work with these buckets through the provided methods.

How to install GcsModule to my app

Install the required dependencies for GcsModule:

• Gcp Config

To import the GcsModule into your main AppModule, you need to include it in the imports array of your AppModule. Since GcsModule is a global module, it will be available to any module in your application without the need to re-import it. Here's an example of how to import the GcsModule in your AppModule:

// src/modules/app.module.ts

import { Module } from '@nestjs/common';
import { GcsModule } from '@deeepvision/nest-kit/dist/modules/gcs';
// Other imports...

@Module({
  imports: [
    GcsModule,
    // Other modules...
  ],
  controllers: [/* ... */],
  providers: [/* ... */],
})
export class AppModule {}

With this configuration, the GcsModule is now imported and available for use throughout your application. You can inject the GcsService or GoogleStorage client into any module or service as needed.

How to inject Storage client into my service

In order to inject the Google Cloud Storage instance into your MyService class (for example), you'll need to use the InjectGoogleStorage decorator. Here's an example:

import { Injectable } from '@nestjs/common';
import { Storage } from '@google-cloud/storage';
import { InjectGoogleStorage } from '@/gcs';

@Injectable()
export class MyService {
  constructor(
    @InjectGoogleStorage() private readonly googleStorage: Storage,
  ) {}

  // Your service methods using googleStorage
}

In this example, the InjectGoogleStorage decorator is used within the constructor of MyService to inject the googleStorage instance. You can now use the googleStorage instance in your service methods to interact with Google Cloud Storage.

How to retrieve a bucket instance by name or alias

You need to define application buckets in .env.yaml. For example:

GCS_BUCKETS: |
  [
    {"name":"whatsbible-assets","alias": "assets"},
    {"name":"whatsbible-uploads", "alias": "uploads"},
    {"name":"whatsbible-uploads-us", "alias": "uploads", "type": "us"}
  ]

Each bucket has name and alias.

To access a registered bucket using its name or alias within your application, you can use the GcsService provided by the GcsModule. By injecting the GcsService into your service, you can easily retrieve a Bucket instance and perform various operations.

Here's an example of how to inject the GcsService into your service and get a bucket instance by its name or alias:

import { Injectable } from '@nestjs/common';
import { GcsService } from '@deeepvision/nest-kit/dist/modules/gcs';

@Injectable()
export class MyService {
  constructor(private readonly gcsService: GcsService) {}

  async someMethod() {
    // Get a bucket by its name
    const wbAssetsBucket = this.gcsService.getBucket('whatsbible-assets');
    
    // Get a bucket by its alias
    const wbAssetsBucketByAlias = this.gcsService.getBucketBy({ alias: 'assets' });

    // Perform operations on the bucket...
  }
}

With the retrieved bucket instances, you can perform various operations on the Google Cloud Storage buckets as needed.

How to retrieve the host URL of a Google Cloud Storage bucket based on its alias

The getBucketHost method is used to retrieve the host URL of a Google Cloud Storage bucket based on its alias. It accepts an alias as a string parameter and searches for the corresponding bucket metadata in the application's configuration.

If a matching alias is found, the method returns the host URL of the bucket. If a custom host is not specified in the metadata, it defaults to the standard Google Cloud Storage URL format, https://storage.googleapis.com/${meta.name}.

If no matching alias is found, the method throws a NotFoundException with an appropriate error message and context information.

Here's an example of how to use the getBucketHost method:

import { Injectable } from '@nestjs/common';
import { GcsService } from '@/gcs/gcs.service';

@Injectable()
export class MyService {
  constructor(private readonly gcsService: GcsService) {}

  async getBucketHostExample() {
    try {
      // Replace 'assets' with the desired alias of the bucket you want to get the host URL for.
      const bucketHost = this.gcsService.getBucketHost('assets');
      console.log('Bucket Host URL:', bucketHost);
    } catch (error) {
      console.error('Error getting bucket host:', error.message);
    }
  }
}