Depolama Servisi

Modül, StorageService injection token’ı altında bir depolama servisi dışa aktarır.

Seçilen sağlayıcı’a (S3 veya MinIO) göre altyapı implementasyonu değişse de, dışarıya sunulan API tutarlıdır.

Metodlar

Metod	Açıklama
uploadAsync(args)	Buffer üzerinden dosya yükler.
uploadWithBase64Async(args)	Base64 string üzerinden dosya yükler (örn. data:<mime>;base64,...).
uploadWithUrlAsync(args)	Bir URL’den dosyayı indirip upload eder.
deleteAsync(path)	Path/key ile objeyi siler.
createShareLinkAsync(path, expiresIn?)	Obje için share link (örn. pre-signed URL) üretir.

Upload sonucu

Tüm upload metodları ortak bir response şekli döndürür.

Alan	Açıklama
path	Tam obje yolu (opsiyonel klasör prefix’i dahil).
fileName	Extension dahil dosya adı.
size	Byte cinsinden dosya boyutu.
extension	Tespit edilen (veya sağlanan) extension.
mime	Tespit edilen (veya sağlanan) mime type.

Sağlayıcı’a göre ek alanlar dönebilir.

Kullanım örnekleri

Servisi inject etmek

StorageService, StorageService token’ı ile dışa aktatılır.

files.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Injectable()
export class FilesService {
  constructor(
    @Inject('StorageService')
    private readonly storageService: NvsStorageService,
  ) {}
}

uploadAsync(args) (Buffer)

@nestjs/platform-express + Multer (@UploadedFile()) ile örnek:

files.controller.ts

import {
  Controller,
  Post,
  UploadedFile,
  UseInterceptors,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { Inject } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Controller('files')
export class FilesController {
  constructor(@Inject('StorageService') private readonly storage: NvsStorageService) {}

  @Post('upload')
  @UseInterceptors(FileInterceptor('file'))
  async upload(@UploadedFile() file: Express.Multer.File) {
    return this.storage.uploadAsync({
      file: file.buffer,
      fileName: file.originalname.replace(/\.[^/.]+$/, ''),
      path: 'uploads',
      maxSize: 10 * 1024 * 1024,
      validateFileTypes: ['image/png', 'image/jpeg'],
    });
  }
}

uploadWithBase64Async(args) (Base64)

files.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Injectable()
export class FilesService {
  constructor(@Inject('StorageService') private readonly storage: NvsStorageService) {}

  async uploadAvatarBase64(base64: string) {
    return this.storage.uploadWithBase64Async({
      file: base64,
      fileName: 'avatar',
      path: 'avatars',
      // file-type tespiti başarısız olursa fallback
      defaultMime: { mime: 'image/png', extension: 'png' },
    });
  }
}

uploadWithUrlAsync(args) (URL)

files.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Injectable()
export class FilesService {
  constructor(@Inject('StorageService') private readonly storage: NvsStorageService) {}

  async importFromUrl(url: string) {
    return this.storage.uploadWithUrlAsync({
      file: url,
      fileName: 'imported-file',
      path: 'imports',
      maxSize: 20 * 1024 * 1024,
    });
  }
}

deleteAsync(path)

files.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Injectable()
export class FilesService {
  constructor(@Inject('StorageService') private readonly storage: NvsStorageService) {}

  async remove(path: string) {
    await this.storage.deleteAsync(path);
    return { deleted: true };
  }
}

createShareLinkAsync(path, expiresIn?)

files.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { NvsStorageService } from 'nestjs-nvs-storage';

@Injectable()
export class FilesService {
  constructor(@Inject('StorageService') private readonly storage: NvsStorageService) {}

  async share(path: string) {
    const url = await this.storage.createShareLinkAsync(path, 60 * 10); // 10 dakika
    return { url };
  }
}

Notlar

• Dosya tipi file-type ile tespit edilir. Tespit başarısız olursa defaultMime verilebilir.
• maxSize verilirse limit üzerindeki dosyalarda hata fırlatılır.
• validateFileTypes verilirse allowlist dışında mime type’larda hata fırlatılır.
• uploadWithUrlAsync kullanıldığında modül, dosyayı upload etmeden önce HttpService ile uzaktan indirir.