@romandronov/nest-files-base

A NestJS module providing an abstract interface for file operations.

Description

This package provides the core components for a flexible and extensible file management system for NestJS applications. It uses an adapter pattern to support different storage providers.

Features

• Abstract file operations interface
• Complete file operations support:
  • Upload files
  • Download files
  • Delete files
  • Copy files between locations
  • Move files between locations
• Configurable through NestJS module system
• TypeScript support with full type definitions

Installation

# npm
npm install @romandronov/nest-files-base

# yarn
yarn add @romandronov/nest-files-base

# pnpm
pnpm add @romandronov/nest-files-base

Usage

This package provides the base components for file operations. To use it, you need to implement a storage adapter or use an existing one like @romandronov/nest-files-s3.

Using with a Custom Adapter

import { Module } from '@nestjs/common';
import { FilesModule, FilesAdapter, FilesService } from '@romandronov/nest-files-base';

// Define your configuration type
export interface CustomStorageConfig {
  apiKey: string;
  // other config options
}

// Create your custom service implementation
export class CustomStorageService extends FilesService {
  // Implement the required methods
  // ...
}

// Create your custom adapter
export class CustomStorageAdapter extends FilesAdapter<CustomStorageConfig> {
  createFilesService(): FilesService {
    // Initialize your storage client with this.config
    const client = new CustomStorageClient(this.config);

    // Return your custom service implementation
    return new CustomStorageService(client);
  }
}

@Module({
  imports: [
    FilesModule.register({
      adapter: new CustomStorageAdapter({
        apiKey: 'YOUR_API_KEY',
        // other config options
      }),
    }),
  ],
})
export class AppModule {}

API Reference

FilesService

The FilesService provides the following methods:

uploadFile(file: Buffer, destination: string, name: string): Promise<{ success: boolean }>

Uploads a file to the specified destination with the given name.

• file: The file content as a Buffer
• destination: The destination (e.g., bucket name for S3)
• name: The file name (e.g., key for S3)
• Returns: A promise that resolves to an object with a success boolean

downloadFile(destination: string, name: string): Promise<{ success: boolean, file: Buffer | null }>

Downloads a file from the specified destination with the given name.

• destination: The destination (e.g., bucket name for S3)
• name: The file name (e.g., key for S3)
• Returns: A promise that resolves to an object with a success boolean and the file content as a Buffer (or null if not found)

deleteFile(destination: string, name: string): Promise<{ success: boolean }>

Deletes a file from the specified destination with the given name.

• destination: The destination (e.g., bucket name for S3)
• name: The file name (e.g., key for S3)
• Returns: A promise that resolves to an object with a success boolean

copyFile(source: string, sourceName: string, destination: string, destinationName: string): Promise<{ success: boolean }>

Copies a file from one location to another.

• source: The source location (e.g., source bucket name for S3)
• sourceName: The source file name (e.g., source key for S3)
• destination: The destination location (e.g., destination bucket name for S3)
• destinationName: The destination file name (e.g., destination key for S3)
• Returns: A promise that resolves to an object with a success boolean

moveFile(source: string, sourceName: string, destination: string, destinationName: string): Promise<{ success: boolean }>

Moves a file from one location to another (copies and then deletes the original).

• source: The source location (e.g., source bucket name for S3)
• sourceName: The source file name (e.g., source key for S3)
• destination: The destination location (e.g., destination bucket name for S3)
• destinationName: The destination file name (e.g., destination key for S3)
• Returns: A promise that resolves to an object with a success boolean

FilesAdapter

The FilesAdapter is an abstract class that must be extended to create a storage adapter:

export abstract class FilesAdapter<Config> {
  constructor(protected readonly config: Config) {}

  abstract createFilesService(): FilesService;
}