@ackplus/nest-file-storage 1.1.22 → 2.0.0

package/README.md

@@ -1,105 +1,66 @@
 # @ackplus/nest-file-storage
 
-A flexible and feature-rich file storage solution for NestJS applications with support for Local, AWS S3, and Azure Blob Storage.
+> One file-storage API for NestJS — Local, S3, Azure, or your own driver. Upload through a controller interceptor or call it directly. Pick storage **per request** (great for multi-tenant apps), validate declaratively, and store one consistent file shape everywhere.
 
-## ✨ Features
+[![npm](https://img.shields.io/npm/v/@ackplus/nest-file-storage.svg)](https://www.npmjs.com/package/@ackplus/nest-file-storage)
+[![license](https://img.shields.io/npm/l/@ackplus/nest-file-storage.svg)](./LICENSE)
 
-- 📦 **Multiple Storage Providers** - Local, AWS S3, and Azure Blob Storage support
-- 🔄 **Easy Switching** - Switch between storage providers with minimal configuration
-- 🎯 **NestJS Integration** - Seamless integration with NestJS decorators and interceptors
-- 📁 **File Operations** - Upload, download, delete, copy files with ease
-- 🔐 **Signed URLs** - Generate presigned URLs for secure file access (S3)
-- 🎨 **Customizable** - Custom file naming, directory structure, and transformations
-- 📝 **TypeScript** - Full TypeScript support with type safety
-- 🧪 **Test-Friendly** - Easy to mock and test
+---
 
-## 📦 Installation
+## Why this library?
 
-```bash
-npm install @ackplus/nest-file-storage
-# or
-pnpm add @ackplus/nest-file-storage
-# or
-yarn add @ackplus/nest-file-storage
-```
+Wiring Multer to S3/Azure/local by hand means juggling storage engines, SDK clients, key generation, URL building, and validation in every project — and swapping providers later means rewriting it all. This library gives you **one stable API** over all of them.
 
-**For AWS S3 support:**
+- **Provider-agnostic.** Write your upload code once. Switch Local → S3 → Azure (or your own backend) by changing config, not controllers.
+- **Custom storage is first-class.** Implement a small `StorageDriver` interface and it works **everywhere** — interceptor and service alike. No fork, no adapter glue.
+- **Per-request / multi-tenant storage.** Route each upload to the right bucket/folder based on the request (tenant, user plan, file type). Built-in caching means one client per tenant, not per request.
+- **Declarative validation.** Size, MIME type, extension, and file-count limits as data — not hand-rolled checks scattered through your handlers. Rejections are typed `400`s.
+- **One result shape.** Every upload — local or cloud — returns the same `UploadedFile` (`key`, `url`, `size`, …), so the rest of your app never branches on provider.
+- **Lean dependencies.** The AWS and Azure SDKs are optional peers, loaded lazily only if you use them. Install nothing extra for local storage.
+- **NestJS-native.** A dynamic module, an injectable service, and a route interceptor — the patterns you already use.
 
-```bash
-npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
-```
+> **Upgrading from v1?** See **[MIGRATION.md](./MIGRATION.md)**. Your old config still boots (with a deprecation warning) while you migrate.
 
-**For Azure Blob Storage support:**
+## Contents
 
-```bash
-npm install @azure/storage-blob
-```
-
-## 🚀 Quick Start
-
-### Step 1: Configure Module
+- [Install](#install) · [Quick start](#quick-start) · [Core concepts](#core-concepts)
+- [Configure providers](#configure-providers) · [Provider comparison](#provider-comparison)
+- [Custom storage drivers](#custom-storage-drivers) · [Multi-tenant storage](#multi-tenant-storage)
+- [Uploading in controllers](#uploading-in-controllers) · [Validation & limits](#validation--limits)
+- [Mapping results into the body](#mapping-results-into-the-request-body) · [Using the service](#using-the-service-programmatically)
+- [The `UploadedFile` model (file state)](#the-uploadedfile-model-file-state) · [API reference](#api-reference)
 
-Choose your storage provider and configure the module:
+---
 
-#### Local Storage
+## Install
 
-```typescript
-// app.module.ts
-import { Module } from '@nestjs/common';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.LOCAL,
-      localConfig: {
-        rootPath: './uploads',
-        baseUrl: 'http://localhost:3000/uploads',
-      },
-    }),
-  ],
-})
-export class AppModule {}
+```bash
+npm i @ackplus/nest-file-storage multer reflect-metadata
+# AWS S3 (optional):
+npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+# Azure Blob (optional):
+npm i @azure/storage-blob
 ```
 
-#### AWS S3
+Requires NestJS on **Express** (`@nestjs/platform-express`). Peer ranges: `@nestjs/common`/`@nestjs/core` `^10 || ^11`, `multer` `^1.4.5-lts.1 || ^2`, `reflect-metadata` `^0.2.2`.
 
-```typescript
-// app.module.ts
-import { Module } from '@nestjs/common';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.S3,
-      s3Config: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-        region: process.env.AWS_REGION,
-        bucket: process.env.AWS_BUCKET,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
+## Quick start
 
-#### Azure Blob Storage
+**1. Register a driver:**
 
-```typescript
-// app.module.ts
+```ts
 import { Module } from '@nestjs/common';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+import { NestFileStorageModule, localDriver } from '@ackplus/nest-file-storage';
 
 @Module({
   imports: [
     NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.AZURE,
-      azureConfig: {
-        account: process.env.AZURE_STORAGE_ACCOUNT,
-        accountKey: process.env.AZURE_STORAGE_KEY,
-        container: process.env.AZURE_CONTAINER,
+      default: 'local',
+      drivers: {
+        local: localDriver({
+          rootPath: './uploads',
+          baseUrl: 'http://localhost:3000/uploads',
+        }),
       },
     }),
   ],
@@ -107,557 +68,402 @@ import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-stora
 export class AppModule {}
 ```
 
-### Step 2: Upload Files in Controller
+**2. Accept uploads in a controller:**
 
-```typescript
-// upload.controller.ts
-import { Controller, Post, UseInterceptors } from '@nestjs/common';
+```ts
+import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
 import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
 
-@Controller('upload')
-export class UploadController {
-  // Single file upload
-  @Post('single')
+@Controller('files')
+export class FilesController {
+  @Post('upload')
   @UseInterceptors(FileStorageInterceptor('file'))
-  uploadSingle(@Body() body: any) {
-    // File key is automatically added to body.file
-    return {
-      message: 'File uploaded successfully',
-      fileKey: body.file,
-    };
-  }
-
-  // Multiple files upload
-  @Post('multiple')
-  @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'array',
-      fieldName: 'files',
-      maxCount: 10,
-    })
-  )
-  uploadMultiple(@Body() body: any) {
-    // File keys are automatically added to body.files as array
-    return {
-      message: 'Files uploaded successfully',
-      fileKeys: body.files,
-    };
-  }
-
-  // Multiple fields
-  @Post('fields')
-  @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'fields',
-      fields: [
-        { name: 'avatar', maxCount: 1 },
-        { name: 'photos', maxCount: 5 },
-      ],
-    })
-  )
-  uploadFields(@Body() body: any) {
-    return {
-      message: 'Files uploaded successfully',
-      avatar: body.avatar,
-      photos: body.photos,
-    };
+  upload(@Body() body: { file: string }) {
+    return { key: body.file }; // body.file is the stored key
   }
 }
 ```
 
-### Step 3: Use File Storage Service
+The interceptor parses `multipart/form-data`, stores the file, and writes the storage key into `request.body.file` before your handler runs.
 
-```typescript
-// file.service.ts
-import { Injectable } from '@nestjs/common';
-import { FileStorageService } from '@ackplus/nest-file-storage';
+## Core concepts
 
-@Injectable()
-export class FileService {
-  // Get file
-  async getFile(key: string): Promise<Buffer> {
-    const storage = await FileStorageService.getStorage();
-    return await storage.getFile(key);
-  }
+- **Driver** — a backend implementing the [`StorageDriver`](#the-storagedriver-interface) contract (put/get/delete/copy/url). Built-ins: `localDriver`, `s3Driver`, `azureDriver`. Bring your own with `defineDriver`.
+- **Registry** — the module builds a registry from your `drivers` map. Drivers are instantiated **once** and cached. The interceptor and the service both resolve from it, so everything behaves the same.
+- **Default driver** — `default` names the driver used when nothing else is specified.
+- **`UploadedFile`** — the one result shape returned by every driver. See [file state](#the-uploadedfile-model-file-state).
 
-  // Delete file
-  async deleteFile(key: string): Promise<void> {
-    const storage = await FileStorageService.getStorage();
-    await storage.deleteFile(key);
-  }
+## Configure providers
 
-  // Copy file
-  async copyFile(oldKey: string, newKey: string) {
-    const storage = await FileStorageService.getStorage();
-    return await storage.copyFile(oldKey, newKey);
-  }
+### Local
 
-  // Get public URL
-  async getFileUrl(key: string): Promise<string> {
-    const storage = await FileStorageService.getStorage();
-    return storage.getUrl(key);
-  }
-
-  // Get signed URL (S3 only)
-  async getSignedUrl(key: string): Promise<string> {
-    const storage = await FileStorageService.getStorage();
-    if ('getSignedUrl' in storage) {
-      return await storage.getSignedUrl(key, { expiresIn: 3600 });
-    }
-    return storage.getUrl(key);
-  }
-}
+```ts
+localDriver({ rootPath: './uploads', baseUrl: 'http://localhost:3000/uploads' })
 ```
 
-## 📚 Configuration Options
+> `baseUrl` only builds the URL string — it does not serve files. Add static serving (e.g. `@nestjs/serve-static`) for browser access, or stream files through your own controller.
 
-### Local Storage Options
+### AWS S3 (and S3-compatible: MinIO, R2, Spaces)
 
-```typescript
-interface LocalStorageOptions {
-  rootPath: string; // Directory to store files
-  baseUrl: string; // Base URL for file access
-  prefix?: string; // Optional prefix for file keys
-  fileName?: (file: any, req: Request) => string; // Custom file naming
-  fileDist?: (file: any, req: Request) => string; // Custom directory structure
-  transformUploadedFileObject?: (file: any) => any; // Transform uploaded file object
-}
+```ts
+s3Driver({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: process.env.AWS_REGION!,
+  bucket: process.env.AWS_BUCKET!,
+  endpoint: process.env.S3_ENDPOINT,       // optional, for S3-compatible
+  cloudFrontUrl: process.env.CDN_URL,      // optional, used by getUrl()
+})
 ```
 
-### S3 Storage Options
-
-```typescript
-interface S3StorageOptions {
-  accessKeyId: string; // AWS access key
-  secretAccessKey: string; // AWS secret key
-  region: string; // AWS region
-  bucket: string; // S3 bucket name
-  endpoint?: string; // Custom S3 endpoint (for S3-compatible services)
-  cloudFrontUrl?: string; // CloudFront distribution URL
-  prefix?: string; // Optional prefix for file keys
-  fileName?: (file: any, req: Request) => string; // Custom file naming
-  fileDist?: (file: any, req: Request) => string; // Custom directory structure
-  transformUploadedFileObject?: (file: any) => any; // Transform uploaded file object
-}
-```
+### Azure Blob Storage
 
-### Azure Storage Options
-
-```typescript
-interface AzureStorageOptions {
-  account: string; // Azure storage account name
-  accountKey: string; // Azure storage account key
-  container: string; // Container name
-  prefix?: string; // Optional prefix for file keys
-  fileName?: (file: any, req: Request) => string; // Custom file naming
-  fileDist?: (file: any, req: Request) => string; // Custom directory structure
-  transformUploadedFileObject?: (file: any) => any; // Transform uploaded file object
-}
+```ts
+azureDriver({
+  account: process.env.AZURE_ACCOUNT!,
+  accountKey: process.env.AZURE_KEY!,
+  container: process.env.AZURE_CONTAINER!,
+  cdnUrl: process.env.AZURE_CDN_URL,       // optional, used by getSignedUrl()
+})
 ```
 
-## 🎨 Advanced Usage
+### Async configuration
 
-### Custom File Naming
+Use `forRootAsync` when config comes from `ConfigService`, a database, etc.:
 
-```typescript
-NestFileStorageModule.forRoot({
-  storage: FileStorageEnum.LOCAL,
-  localConfig: {
-    rootPath: './uploads',
-    baseUrl: 'http://localhost:3000/uploads',
-    fileName: (file, req) => {
-      // Custom file name with timestamp
-      const timestamp = Date.now();
-      const ext = file.originalname.split('.').pop();
-      return `${timestamp}-${file.originalname}`;
+```ts
+NestFileStorageModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    default: 's3',
+    drivers: {
+      s3: s3Driver({
+        accessKeyId: config.getOrThrow('AWS_ACCESS_KEY_ID'),
+        secretAccessKey: config.getOrThrow('AWS_SECRET_ACCESS_KEY'),
+        region: config.getOrThrow('AWS_REGION'),
+        bucket: config.getOrThrow('AWS_BUCKET'),
+      }),
     },
-  },
-})
+  }),
+});
 ```
 
-### Custom Directory Structure
+### Provider comparison
 
-```typescript
-NestFileStorageModule.forRoot({
-  storage: FileStorageEnum.LOCAL,
-  localConfig: {
-    rootPath: './uploads',
-    baseUrl: 'http://localhost:3000/uploads',
-    fileDist: (file, req) => {
-      // Organize by year/month/day
-      const date = new Date();
-      return `${date.getFullYear()}/${date.getMonth() + 1}/${date.getDate()}`;
-    },
-  },
-})
-```
+| Capability | Local | S3 | Azure | Custom |
+| --- | :---: | :---: | :---: | :---: |
+| `putFile` / `getFile` / `deleteFile` / `copyFile` | ✅ | ✅ | ✅ | ✅ |
+| `getUrl` | ✅ | ✅ | ✅ | ✅ |
+| `getSignedUrl` | — | ✅ | ✅ (SAS) | optional |
+| `path` (absolute FS path) | ✅ | — | — | optional |
+| Public URLs need extra setup | static serving | bucket/CDN policy | container/CDN policy | your call |
+| Extra dependency | none | `@aws-sdk/*` | `@azure/storage-blob` | your SDK |
 
-### Transform Uploaded File Object
+## Custom storage drivers
 
-```typescript
-NestFileStorageModule.forRoot({
-  storage: FileStorageEnum.S3,
-  s3Config: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    region: process.env.AWS_REGION,
-    bucket: process.env.AWS_BUCKET,
-    transformUploadedFileObject: (file) => {
-      // Return only specific fields
-      return {
-        key: file.key,
-        url: file.url,
-        size: file.size,
-        mimetype: file.mimetype,
-      };
-    },
-  },
-})
-```
+Implement the small [`StorageDriver`](#the-storagedriver-interface) interface and register it with `defineDriver`. It then works in the interceptor, the service, and tenant resolution — identically to the built-ins.
 
-### Custom File Mapping in Interceptor
+```ts
+import { defineDriver, StorageDriver, UploadedFile } from '@ackplus/nest-file-storage';
+import { Storage } from '@google-cloud/storage';
 
-```typescript
-@Post('upload')
-@UseInterceptors(
-  FileStorageInterceptor('file', {
-    mapToRequestBody: (file, fieldName, req) => {
-      // Return full file object instead of just key
-      return file;
-    },
-  })
-)
-uploadFile(@Body() body: any) {
-  // body.file now contains the full file object
-  return {
-    message: 'File uploaded',
-    file: body.file,
-  };
+class GcsDriver implements StorageDriver {
+  private storage = new Storage();
+  constructor(private opts: { bucket: string }) {}
+
+  async putFile(content: Buffer, key: string, meta?): Promise<UploadedFile> {
+    await this.storage.bucket(this.opts.bucket).file(key).save(content, {
+      contentType: meta?.contentType,
+    });
+    return {
+      key, url: this.getUrl(key), originalName: key.split('/').pop()!,
+      fileName: key.split('/').pop()!, size: content.length, fullPath: key,
+    };
+  }
+  async getFile(key: string) { const [buf] = await this.storage.bucket(this.opts.bucket).file(key).download(); return buf; }
+  async deleteFile(key: string) { await this.storage.bucket(this.opts.bucket).file(key).delete(); }
+  async copyFile(src: string, dest: string) { /* copy + return UploadedFile */ }
+  getUrl(key: string) { return `https://storage.googleapis.com/${this.opts.bucket}/${key}`; }
 }
+
+NestFileStorageModule.forRoot({
+  default: 'gcs',
+  drivers: { gcs: defineDriver(GcsDriver, { bucket: 'my-bucket' }) },
+});
 ```
 
-### Async Configuration
+For async setup, register a plain factory instead: `drivers: { gcs: async () => new GcsDriver(await load()) }`.
+
+## Multi-tenant storage
+
+Route each upload to the right storage based on the request — a different **folder per tenant** in one bucket, a **dedicated bucket per tenant**, or a mix. The library does no authentication: your guard/middleware identifies the tenant; these hooks read it.
+
+```ts
+import { NestFileStorageModule, localDriver, s3Driver, tenantFrom } from '@ackplus/nest-file-storage';
 
-```typescript
-// app.module.ts
 NestFileStorageModule.forRootAsync({
-  imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
-    storage: FileStorageEnum.S3,
-    s3Config: {
-      accessKeyId: configService.get('AWS_ACCESS_KEY_ID'),
-      secretAccessKey: configService.get('AWS_SECRET_ACCESS_KEY'),
-      region: configService.get('AWS_REGION'),
-      bucket: configService.get('AWS_BUCKET'),
+  inject: [TenantStorageService],
+  useFactory: (tenants: TenantStorageService) => ({
+    default: 'local',
+    drivers: {
+      local: localDriver({ rootPath: './uploads', baseUrl: 'http://localhost:3000/uploads' }),
+    },
+    tenant: {
+      // Identify the tenant — try several strategies in order.
+      resolve: tenantFrom.first(
+        tenantFrom.jwt('tenantId'),      // req.user.tenantId (after your auth guard)
+        tenantFrom.subdomain(),          // acme.app.com -> 'acme'
+        tenantFrom.header('x-tenant-id'),
+      ),
+      // Resolve a tenant -> storage. Cached by tenant id (this runs once per tenant).
+      driver: async (tenantId) => {
+        const cfg = await tenants.find(tenantId);            // your DB lookup
+        if (cfg?.dedicated) {
+          return { factory: s3Driver({ bucket: cfg.bucket, region: cfg.region,
+            accessKeyId: cfg.key, secretAccessKey: cfg.secret }) };  // dedicated bucket
+        }
+        return { use: 'local', prefix: `tenants/${tenantId}` };       // shared + folder
+      },
+      cache: { ttlMs: 10 * 60_000, max: 500 },
+      fallback: 'default', // no tenant on the request -> use the default driver ('error' to 400)
     },
   }),
-  inject: [ConfigService],
-})
+});
 ```
 
-### Dynamic Storage Type
-
-```typescript
-// Override storage type per route
-@Post('upload-to-s3')
-@UseInterceptors(
-  FileStorageInterceptor('file', {
-    storageType: FileStorageEnum.S3,
-  })
-)
-uploadToS3(@Body() body: any) {
-  return { fileKey: body.file };
-}
+Controllers need **no tenant-specific code** — a plain `FileStorageInterceptor('file')` is routed automatically:
+
+```ts
+@Post('upload')
+@UseInterceptors(FileStorageInterceptor('file'))
+upload(@Body() body: { file: string }) { return { key: body.file }; }
 ```
 
-## 🔥 Complete Examples
+Outside a request (jobs, URL generation), resolve a tenant's driver programmatically — it uses the same cache:
 
-### Image Upload with Validation
+```ts
+const { driver, prefix } = await this.fileStorage.getTenantDriver('acme');
+const url = await driver.getUrl(key);
+```
 
-```typescript
-import { Controller, Post, UseInterceptors, BadRequestException } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
+When a tenant changes its storage settings, drop the cached driver: `this.fileStorage.getRegistry().invalidateTenant('acme')`.
 
-@Controller('images')
-export class ImageController {
-  @Post('upload')
-  @UseInterceptors(
-    FileStorageInterceptor('image', {
-      fileName: (file, req) => {
-        // Validate image type
-        const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
-        if (!allowedTypes.includes(file.mimetype)) {
-          throw new BadRequestException('Only image files are allowed');
-        }
-        
-        // Generate unique filename
-        const timestamp = Date.now();
-        const ext = file.originalname.split('.').pop();
-        return `image-${timestamp}.${ext}`;
-      },
-      fileDist: (file, req) => {
-        // Organize by year/month
-        const date = new Date();
-        return `images/${date.getFullYear()}/${date.getMonth() + 1}`;
-      },
-    })
-  )
-  async uploadImage(@Body() body: any) {
-    return {
-      message: 'Image uploaded successfully',
-      imageKey: body.image,
-    };
-  }
-}
+**`tenant.driver(tenantId)` returns one of:**
+
+| Return | Meaning |
+| --- | --- |
+| `'local'` | a registered driver, no prefix |
+| `{ use: 'local', prefix: 'tenants/acme' }` | a shared driver + per-tenant key prefix (folder isolation) |
+| `{ factory: s3Driver({...}), prefix? }` | a dedicated driver built for this tenant (bucket isolation) |
+
+## Uploading in controllers
+
+`FileStorageInterceptor(field, options?)` accepts `multipart/form-data`, stores the file(s), and writes the result into `request.body`.
+
+```ts
+// Single file (field name 'file')
+@UseInterceptors(FileStorageInterceptor('file'))
+upload(@Body() body: { file: string }) {}
+
+// Multiple files in one field
+@UseInterceptors(FileStorageInterceptor({ type: 'array', fieldName: 'photos', maxCount: 5 }))
+uploadMany(@Body() body: { photos: string[] }) {}
+
+// Multiple named fields
+@UseInterceptors(FileStorageInterceptor({
+  type: 'fields',
+  fields: [{ name: 'avatar', maxCount: 1 }, { name: 'docs', maxCount: 10 }],
+}))
+uploadFields(@Body() body: { avatar: string[]; docs: string[] }) {}
 ```
 
-### User Avatar Upload
+| Mode | Accepted field(s) | Default `body` value |
+| --- | --- | --- |
+| `'file'` (string) | `file` | `body.file: string` |
+| `{ type: 'array' }` | repeated `photos` or `photos[0]`, `photos[1]`, … | `body.photos: string[]` |
+| `{ type: 'fields' }` | each named field | `body[field]: string[]` |
 
-```typescript
-import { Controller, Post, UseInterceptors, Body } from '@nestjs/common';
-import { FileStorageInterceptor, FileStorageService } from '@ackplus/nest-file-storage';
+### Control the stored key
 
-@Controller('users')
-export class UserController {
-  constructor(private readonly userService: UserService) {}
+```ts
+FileStorageInterceptor('avatar', {
+  fileDist: (_file, req) => `users/${req.user.id}/avatars`, // folder (relative)
+  fileName: (file) => `${Date.now()}${extname(file.originalname)}`, // last segment
+  prefix: 'public', // optional static prefix
+});
+// -> public/users/42/avatars/1713876155123.png
+```
 
-  @Post('avatar')
-  @UseInterceptors(
-    FileStorageInterceptor('avatar', {
-      fileName: (file, req) => {
-        const userId = req.user.id; // Assuming user from auth guard
-        const ext = file.originalname.split('.').pop();
-        return `avatar-${userId}.${ext}`;
-      },
-      fileDist: () => 'avatars',
-    })
-  )
-  async uploadAvatar(@Body() body: any, @Request() req) {
-    // Delete old avatar if exists
-    const user = await this.userService.findById(req.user.id);
-    if (user.avatarKey) {
-      const storage = await FileStorageService.getStorage();
-      await storage.deleteFile(user.avatarKey);
-    }
-
-    // Update user with new avatar
-    await this.userService.updateAvatar(req.user.id, body.avatar);
+The final key is `joinKey(prefix, fileDist, fileName)`. Defaults: `fileDist` = `YYYY/MM/DD`, `fileName` = `uuid-originalname`.
 
-    return {
-      message: 'Avatar updated successfully',
-      avatarKey: body.avatar,
-    };
-  }
-}
+### Override the driver for one route
+
+```ts
+FileStorageInterceptor('file', { driver: 's3' });                        // by name
+FileStorageInterceptor('file', { driver: (req) => req.user.plan });      // dynamically
+FileStorageInterceptor('file', { tenant: false });                       // opt out of tenant routing
 ```
 
-### Document Management
+## Validation & limits
 
-```typescript
-import { Controller, Get, Post, Delete, Param, UseInterceptors, Body } from '@nestjs/common';
-import { FileStorageInterceptor, FileStorageService } from '@ackplus/nest-file-storage';
+Declare limits as data — at the module level (applies to every route) and/or per route (merged over the module default). Rejections throw typed `400`s.
 
-@Controller('documents')
-export class DocumentController {
-  @Post('upload')
-  @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'array',
-      fieldName: 'documents',
-      maxCount: 10,
-    }, {
-      fileDist: () => 'documents',
-      mapToRequestBody: (files, fieldName) => {
-        // Return detailed file info
-        return files;
-      },
-    })
-  )
-  async uploadDocuments(@Body() body: any) {
-    return {
-      message: `${body.documents.length} documents uploaded`,
-      documents: body.documents,
-    };
-  }
+```ts
+// module-wide default
+validation: { maxSize: 10 * 1024 * 1024 }
 
-  @Get(':key/download')
-  async downloadDocument(@Param('key') key: string, @Res() res) {
-    const storage = await FileStorageService.getStorage();
-    const file = await storage.getFile(key);
-    
-    res.setHeader('Content-Type', 'application/octet-stream');
-    res.setHeader('Content-Disposition', `attachment; filename="${key}"`);
-    res.send(file);
-  }
+// per route
+FileStorageInterceptor('image', {
+  validation: {
+    maxSize: 5 * 1024 * 1024,                       // bytes
+    allowedMimeTypes: ['image/jpeg', 'image/png', 'image/*'], // wildcards supported
+    allowedExtensions: ['.jpg', '.png'],            // case-insensitive
+    maxFiles: 10,                                   // total files per request
+    fileFilter: (req, file, cb) => cb(null, true),  // escape hatch (runs after the above)
+  },
+});
+```
 
-  @Delete(':key')
-  async deleteDocument(@Param('key') key: string) {
-    const storage = await FileStorageService.getStorage();
-    await storage.deleteFile(key);
-    
-    return { message: 'Document deleted successfully' };
-  }
+| Rule | Becomes | Throws on violation |
+| --- | --- | --- |
+| `maxSize` | Multer `limits.fileSize` | `FileTooLargeException` |
+| `maxFiles` | Multer `limits.files` | `TooManyFilesException` |
+| `allowedMimeTypes` / `allowedExtensions` | generated `fileFilter` | `InvalidFileTypeException` |
 
-  @Get(':key/url')
-  async getDocumentUrl(@Param('key') key: string) {
-    const storage = await FileStorageService.getStorage();
-    const url = storage.getUrl(key);
-    
-    return { url };
-  }
-}
+All three extend `BadRequestException`, so they surface as standard `400` responses. For cross-field rules (e.g. "at least 2 images"), use `afterUpload`:
+
+```ts
+FileStorageInterceptor({ type: 'fields', fields: [{ name: 'images', maxCount: 10 }] }, {
+  afterUpload: (req) => {
+    const files = req.files as Record<string, Express.Multer.File[]>;
+    if ((files?.images?.length ?? 0) < 2) throw new BadRequestException('At least 2 images required.');
+  },
+});
 ```
 
-## 📚 API Reference
+## Mapping results into the request body
 
-### FileStorageService
+By default the interceptor writes the storage **key** into `request.body[field]`. Customize it with `mapToRequestBody`:
 
-```typescript
-class FileStorageService {
-  // Get storage instance
-  static async getStorage(storageType?: FileStorageEnum): Promise<Storage>
-  
-  // Get module options
-  static getOptions(): FileStorageModuleOptions
-  
-  // Set module options
-  static setOptions(options: FileStorageModuleOptions): void
-}
+```ts
+FileStorageInterceptor('document', {
+  mapToRequestBody: (file) => ({ key: file.key, url: file.url, size: file.size }),
+});
+// body.document === { key, url, size }
 ```
 
-### Storage Interface
-
-```typescript
-interface Storage {
-  // Get file content as Buffer
-  getFile(key: string): Promise<Buffer> | Buffer
-  
-  // Delete file
-  deleteFile(key: string): Promise<void> | void
-  
-  // Upload file
-  putFile(fileContent: Buffer, key: string): Promise<UploadedFile> | UploadedFile
-  
-  // Copy file
-  copyFile(oldKey: string, newKey: string): Promise<UploadedFile>
-  
-  // Get file URL
-  getUrl(key: string): Promise<string> | string
-  
-  // Get signed URL (S3 only)
-  getSignedUrl?(key: string, options: any): Promise<string> | string
-  
-  // Get file path (Local only)
-  path?(filePath: string): Promise<string> | string
+Set `overwriteBodyField: false` to keep an existing body value (e.g. a JSON field with the same name on a PATCH).
+
+## Using the service programmatically
+
+`FileStorageService` is injectable (the module is global). Use it in services, jobs, or response mappers.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { FileStorageService } from '@ackplus/nest-file-storage';
+
+@Injectable()
+export class DocsService {
+  constructor(private readonly fileStorage: FileStorageService) {}
+
+  upload(buf: Buffer, key: string) { return this.fileStorage.putFile(buf, key); }
+  read(key: string) { return this.fileStorage.getFile(key); }
+  remove(key: string) { return this.fileStorage.deleteFile(key); }
+  url(key: string) { return this.fileStorage.getUrl(key); }
+  signedUrl(key: string) { return this.fileStorage.getSignedUrl(key, { expiresIn: 3600 }); }
+
+  // a specific driver, or a tenant's driver:
+  async s3() { return this.fileStorage.getDriver('s3'); }
+  async forTenant(id: string) { return this.fileStorage.getTenantDriver(id); }
 }
 ```
 
-### FileStorageInterceptor
-
-```typescript
-// Single file upload
-FileStorageInterceptor(
-  fieldName: string,
-  options?: FileStorageInterceptorOptions
-)
-
-// Multiple files or fields
-FileStorageInterceptor(
-  config: {
-    type: 'single' | 'array' | 'fields';
-    fieldName?: string;
-    maxCount?: number;
-    fields?: { name: string; maxCount?: number }[];
-  },
-  options?: FileStorageInterceptorOptions
-)
+A common pattern: store only the `key` in your database and build the URL when serializing a response.
+
+```ts
+async toResponse(user: { avatarKey?: string }) {
+  return { ...user, avatarUrl: user.avatarKey ? await this.fileStorage.getUrl(user.avatarKey) : null };
+}
 ```
 
-### UploadedFile Interface
+## The `UploadedFile` model (file state)
+
+Every driver returns the same shape from `putFile`/`copyFile`, and the interceptor exposes it to `mapToRequestBody`. Persist the **`key`** (stable); derive the **`url`** when you need it.
 
-```typescript
+```ts
 interface UploadedFile {
-  fieldName?: string;      // Form field name
-  fileName: string;        // Generated file name
-  originalName: string;    // Original file name
-  size: number;           // File size in bytes
-  mimetype?: string;      // MIME type
-  buffer?: Buffer;        // File buffer (optional)
-  key: string;           // Storage key/path
-  url: string;           // Public URL
-  fullPath: string;      // Full storage path
-  encoding?: string;     // File encoding
+  key: string;          // storage key/path — persist THIS
+  url: string;          // public URL (local needs static serving)
+  originalName: string; // original client filename
+  fileName: string;     // final filename segment of the key
+  size: number;         // bytes
+  mimetype?: string;    // when known
+  fieldName?: string;   // upload field it came from
+  fullPath: string;     // provider-native path (local absolute; cloud key)
+  encoding?: string;
+  buffer?: Buffer;      // when the provider returns bytes
 }
 ```
 
-## 🧪 Testing
-
-```typescript
-import { Test, TestingModule } from '@nestjs/testing';
-import { NestFileStorageModule, FileStorageService, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-describe('FileService', () => {
-  let service: FileService;
-  let storage: Storage;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      imports: [
-        NestFileStorageModule.forRoot({
-          storage: FileStorageEnum.LOCAL,
-          localConfig: {
-            rootPath: './test-uploads',
-            baseUrl: 'http://localhost:3000/test-uploads',
-          },
-        }),
-      ],
-      providers: [FileService],
-    }).compile();
-
-    service = module.get<FileService>(FileService);
-    storage = await FileStorageService.getStorage();
-  });
-
-  it('should upload file', async () => {
-    const buffer = Buffer.from('test content');
-    const result = await storage.putFile(buffer, 'test/file.txt');
-    
-    expect(result.key).toBe('test/file.txt');
-    expect(result.size).toBeGreaterThan(0);
-  });
-
-  it('should delete file', async () => {
-    const buffer = Buffer.from('test content');
-    await storage.putFile(buffer, 'test/file.txt');
-    
-    await storage.deleteFile('test/file.txt');
-    
-    await expect(storage.getFile('test/file.txt')).rejects.toThrow();
-  });
-});
-```
+| Field | Use it for |
+| --- | --- |
+| `key` | the database value; the input to `getFile`/`getUrl`/`deleteFile`/`copyFile` |
+| `url` | rendering/links (regenerate from `key` via `getUrl` rather than storing) |
+| `fullPath` | local file operations; provider-native identifier |
+| `size` / `mimetype` / `originalName` | metadata you may want to persist alongside the key |
+
+## API reference
+
+### `NestFileStorageModule`
 
-## 🤝 Contributing
+- `forRoot(options)` / `forRootAsync(asyncOptions)` → a global `DynamicModule`.
+- Options: `{ default: string; drivers: Record<string, DriverFactory>; validation?: UploadValidation; tenant?: TenantOptions }`.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+### Driver factories
 
-## 📄 License
+- `localDriver(options)` · `s3Driver(options)` · `azureDriver(options)` · `defineDriver(DriverClass, options?)` → `DriverFactory`.
 
-This project is licensed under the MIT License.
+### `FileStorageService` (injectable)
 
-## 🙏 Acknowledgments
+- `getDriver(name?)` · `getTenantDriver(tenantId)` · `getRegistry()`
+- `putFile` · `getFile` · `deleteFile` · `copyFile` · `getUrl` · `getSignedUrl` (delegate to the default driver)
+- `static getStorage(name?)` — *deprecated* facade for non-DI call sites.
 
-- Built with [NestJS](https://nestjs.com/)
-- Uses [Multer](https://github.com/expressjs/multer) for file handling
-- AWS S3 support via [@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3)
-- Azure support via [@azure/storage-blob](https://www.npmjs.com/package/@azure/storage-blob)
+### `FileStorageInterceptor(field, options?)`
 
-## 📮 Support
+`field`: a string (single file) or `{ type, fieldName?, maxCount?, fields? }`.
+`options`: `{ driver?, fileName?, fileDist?, prefix?, validation?, mapToRequestBody?, overwriteBodyField?, afterUpload?, tenant? }`.
 
-If you have any questions or need help:
-- Open an issue on [GitHub](https://github.com/ack-solutions/nest-file-storage/issues)
-- Check the [examples](./examples/) directory
+### The `StorageDriver` interface
+
+```ts
+interface StorageDriver {
+  putFile(content: Buffer, key: string, meta?: PutFileMeta): Promise<UploadedFile>;
+  getFile(key: string): Promise<Buffer>;
+  deleteFile(key: string): Promise<void>;
+  copyFile(sourceKey: string, destKey: string): Promise<UploadedFile>;
+  getUrl(key: string): string | Promise<string>;
+  getSignedUrl?(key: string, options?: SignedUrlOptions): Promise<string>;
+  path?(key: string): string | Promise<string>;
+  readonly keyDefaults?: { fileName?; fileDist?; prefix? };
+}
+```
+
+### Tenant resolvers — `tenantFrom`
+
+`jwt(path?)` · `header(name)` · `subdomain({ rootDomain?, ignore? })` · `param(name)` · `query(name)` · `first(...resolvers)`.
+
+### Exceptions
+
+`FileTooLargeException` · `InvalidFileTypeException` · `TooManyFilesException` (all extend `BadRequestException`).
 
 ---
 
-Made with ❤️ for the NestJS community
+## More
+
+- **[Migration from v1](./MIGRATION.md)** · **[Changelog](./CHANGELOG.md)** · **[Examples](./examples/)**
+
+## License
+
+MIT