Nest.js MinIO Module

A tiny package to make a bridge between Nest.js DI system and MinIO client instance.

Table of Contents

• Nest.js MinIO Module
• Table of Contents
• Installation
• Usage
• Extending MinioService
• Comparison to other implementations
• Contributing
• License

Installation

You can install nestjs-minio-module using npm or yarn:

1npm i nestjs-minio-module minio --save
2# or
3yarn add nestjs-minio-module minio

The package also requires it's peer dependencies to be installed. Likely you already have @nestjs/common installed - that is the reason why it is not specified in the snippet above.

Usage

You may register MinioModule synchronously as follows.

1import { Module } from '@nestjs/common';
2import { MinioModule } from 'nestjs-minio-module';
3
4@Module({
5imports: [
6    MinioModule.register({
7      endPoint: '127.0.0.1',
8      port: 1337,
9      useSSL: true,
10      accessKey: 'minio_access_key',
11      secretKey: 'minio_secret_key'
12    })
13})
14export class AppModule {}

MinioModule may also be registered asynchronously with a factory or a value. Let's imagine we are using a ConfigService and want to get MinIO options from it. We may do it as follows:

1import { Module } from '@nestjs/common';
2import { MinioModule } from 'nestjs-minio-module';
3import { ConfigModule, ConfigService } from '<config_module>';
4
5@Module({
6imports: [
7    MinioModule.registerAsync({
8        imports: [ConfigModule],
9        inject: [ConfigService],
10        useFactory: (configService: ConfigService) => configService.get('minio'),
11    }),
12})
13export class AppModule {}

When registered, MinioService may be injected into Nest.js injectables as usual:

1import { Injectable } from "@nestjs/common";
2import { MinioService } from "nestjs-minio-module";
3
4@Injectable()
5export class SomeService {
6  constructor(private readonly minioService: MinioService) {}
7
8  async listAllBuckets() {
9    return this.minioService.listBuckets();
10  }
11}

MinioService instance exposes all JavaScript MinIO Client methods as it's own. You may find SDK specification here.

Extending MinioService

You may create your own services extending from MinioService. It is a generic class so you may specify your own options type.

1import { Injectable } from "@nestjs/common";
2import { MinioService } from "nestjs-minio-module";
3
4import type { MinioModuleOptions } from "nestjs-minio-module";
5
6type S3Options = {
7  publicEndPoint?: string;
8} & MinioModuleOptions;
9
10@Injectable()
11export class S3Service extends MinioService<S3Options> {
12  public constructUrl(bucket: string, usePublicUrl: boolean): string {
13    const protocol = this.options.useSSL ? "https:" : "http:";
14
15    return usePublicUrl && this.options.publicEndPoint
16      ? `${protocol}//${bucket}.${this.options.publicEndPoint}/`
17      : `${protocol}//${this.options.endPoint}/${bucket}/`;
18  }
19}

In case if you need to create a custom constructor you should not forget to pass options to the superclass. You may inject options using MINIO_OPTIONS symbol provided and exported from the module.

1import { Injectable, Inject } from "@nestjs/common";
2import { MinioService, MINIO_OPTIONS } from "nestjs-minio-module";
3
4import type { MinioModuleOptions } from "nestjs-minio-module";
5
6type S3Options = {
7  publicEndPoint?: string;
8} & MinioModuleOptions;
9
10@Injectable()
11export class S3Service extends MinioService<S3Options> {
12  constructor(
13    @Inject(MINIO_OPTIONS) options: S3Options /*, additional dependencies */
14  ) {
15    super(options);
16  }
17}

Comparison to other implementations

You may ask: how is this package different from a few other implementations of MinIO client in Nest.js?

Firstly, this package properly specifies it's peer dependencies. This means you don't get duplicate packages in your node_modules making the package smaller and as a bonus have support for a greater variety of versions.

Secondly, nestjs-minio-module properly exposes MinIO interface through a service, rather than a service field or a separate injectable.

Thirdly, this package allows you to create multiple instances of MinioModule in different scopes. You may have a module dedicated to accessing a MinIO instance in the same kubernetes container and another module accessing a remote S3 object storage.

And adjacent to the last point - this package is very easy to extend. It provides both generic types for its service and a symbol for accessing exported options provider.

Contributing

Feel free to send any suggestions in GitHub issues or open a Pull Request with your feature.

License

MIT