@ackplus/nest-file-storage 1.1.23 → 2.0.0

package/README.md

@@ -1,80 +1,66 @@
 # @ackplus/nest-file-storage
 
-`@ackplus/nest-file-storage` is a NestJS file upload and storage library for Express-based applications. It connects Multer uploads to Local storage, AWS S3, or Azure Blob Storage and gives you one common runtime API for upload, read, delete, copy, and URL generation.
+> 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.
 
-This README is the canonical developer guide for using the package in an application.
+[![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)
 
-## What You Get
+---
 
-- `NestFileStorageModule` to register the default storage provider.
-- `FileStorageInterceptor()` to accept multipart uploads in controllers.
-- `FileStorageService` to work with files programmatically.
-- Built-in storage adapters for `local`, `s3`, and `azure`.
-- Request-body mapping so uploaded file keys or metadata can flow into your DTO/service layer.
+## Why this library?
 
-## Compatibility And Prerequisites
+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.
 
-This library is designed for NestJS on the Express platform.
+- **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.
 
-Required in the consuming app:
+> **Upgrading from v1?** See **[MIGRATION.md](./MIGRATION.md)**. Your old config still boots (with a deprecation warning) while you migrate.
 
-- `@nestjs/common`
-- `@nestjs/core`
-- `@nestjs/platform-express`
-- `multer`
-- `reflect-metadata`
+## Contents
 
-Peer dependency ranges exported by the package:
+- [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)
 
-- `@nestjs/common`: `^10.0.0 || ^11.0.0`
-- `@nestjs/core`: `^10.0.0 || ^11.0.0`
-- `multer`: `^1.4.5-lts.1 || ^2.0.0`
-- `reflect-metadata`: `^0.2.2`
+---
 
-Optional provider packages:
-
-- AWS S3: `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
-- Azure Blob Storage: `@azure/storage-blob`
-
-## Installation
+## Install
 
 ```bash
-pnpm add @ackplus/nest-file-storage multer reflect-metadata
+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
 ```
 
-If your Nest app does not already include the Express platform package:
-
-```bash
-pnpm add @nestjs/platform-express
-```
-
-For AWS S3 support:
-
-```bash
-pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
-```
-
-For Azure Blob Storage support:
-
-```bash
-pnpm add @azure/storage-blob
-```
+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`.
 
-## Register The Module
+## Quick start
 
-### Local storage
+**1. Register a driver:**
 
 ```ts
 import { Module } from '@nestjs/common';
-import { FileStorageEnum, NestFileStorageModule } from '@ackplus/nest-file-storage';
+import { NestFileStorageModule, localDriver } from '@ackplus/nest-file-storage';
 
 @Module({
   imports: [
     NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.LOCAL,
-      localConfig: {
-        rootPath: './uploads',
-        baseUrl: 'http://localhost:3000/uploads',
+      default: 'local',
+      drivers: {
+        local: localDriver({
+          rootPath: './uploads',
+          baseUrl: 'http://localhost:3000/uploads',
+        }),
       },
     }),
   ],
@@ -82,633 +68,401 @@ import { FileStorageEnum, NestFileStorageModule } from '@ackplus/nest-file-stora
 export class AppModule {}
 ```
 
-### AWS S3
+**2. Accept uploads in a controller:**
 
 ```ts
-import { Module } from '@nestjs/common';
-import { FileStorageEnum, NestFileStorageModule } from '@ackplus/nest-file-storage';
+import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
+import { FileStorageInterceptor } 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!,
-        cloudFrontUrl: process.env.AWS_CLOUDFRONT_URL,
-      },
-    }),
-  ],
-})
-export class AppModule {}
+@Controller('files')
+export class FilesController {
+  @Post('upload')
+  @UseInterceptors(FileStorageInterceptor('file'))
+  upload(@Body() body: { file: string }) {
+    return { key: body.file }; // body.file is the stored key
+  }
+}
 ```
 
-### Azure Blob Storage
+The interceptor parses `multipart/form-data`, stores the file, and writes the storage key into `request.body.file` before your handler runs.
 
-```ts
-import { Module } from '@nestjs/common';
-import { FileStorageEnum, NestFileStorageModule } from '@ackplus/nest-file-storage';
+## Core concepts
 
-@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!,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
+- **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).
 
-### Async configuration
+## Configure providers
 
-```ts
-import { Module } from '@nestjs/common';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { FileStorageEnum, NestFileStorageModule } from '@ackplus/nest-file-storage';
+### Local
 
-@Module({
-  imports: [
-    ConfigModule.forRoot(),
-    NestFileStorageModule.forRootAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: async (config: ConfigService) => ({
-        storage: FileStorageEnum.S3,
-        s3Config: {
-          accessKeyId: config.getOrThrow('AWS_ACCESS_KEY_ID'),
-          secretAccessKey: config.getOrThrow('AWS_SECRET_ACCESS_KEY'),
-          region: config.getOrThrow('AWS_REGION'),
-          bucket: config.getOrThrow('AWS_BUCKET'),
-        },
-      }),
-    }),
-  ],
-})
-export class AppModule {}
+```ts
+localDriver({ rootPath: './uploads', baseUrl: 'http://localhost:3000/uploads' })
 ```
 
-### Example: build module options from one shared storage config
+> `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.
 
-If your app stores provider credentials in one common config record, map that record into the module options once and return the correct provider config.
+### AWS S3 (and S3-compatible: MinIO, R2, Spaces)
 
 ```ts
-import * as path from 'path';
-import { FileStorageEnum } from '@ackplus/nest-file-storage';
-
-function buildFileStorageOptions(config: {
-  type: FileStorageEnum;
-  endpoint?: string;
-  accessKeyId?: string;
-  secretAccessKey?: string;
-  region?: string;
-  bucket?: string;
-  cloudFrontUrl?: string;
-}, appConfig: { appUrl: string }) {
-  if (config.type === FileStorageEnum.S3) {
-    return {
-      storage: FileStorageEnum.S3,
-      s3Config: {
-        endpoint: config.endpoint,
-        accessKeyId: config.accessKeyId!,
-        secretAccessKey: config.secretAccessKey!,
-        region: config.region!,
-        bucket: config.bucket!,
-        cloudFrontUrl: config.cloudFrontUrl,
-      },
-    };
-  }
-
-  if (config.type === FileStorageEnum.AZURE) {
-    return {
-      storage: FileStorageEnum.AZURE,
-      azureConfig: {
-        account: config.accessKeyId!,
-        accountKey: config.secretAccessKey!,
-        container: config.bucket!,
-      },
-    };
-  }
-
-  return {
-    storage: FileStorageEnum.LOCAL,
-    localConfig: {
-      rootPath: path.join(process.cwd(), 'public'),
-      baseUrl: `${appConfig.appUrl}/public`,
-    },
-  };
-}
+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()
+})
 ```
 
-This pattern is useful when:
-
-- S3 uses `endpoint`, `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and optional `cloudFrontUrl`.
-- Azure reuses the same credential source but maps `accessKeyId -> account`, `secretAccessKey -> accountKey`, and `bucket -> container`.
-- Local storage falls back to a public directory such as `process.cwd()/public`.
-
-## Local Storage Note: `baseUrl` Does Not Serve Files
-
-For local storage, `baseUrl` only controls the URL string returned by `getUrl()` and upload metadata. It does not expose the directory over HTTP by itself.
-
-If you want browser-accessible local files, add static serving in your Nest app:
-
-```bash
-pnpm add @nestjs/serve-static
-```
+### Azure Blob Storage
 
 ```ts
-import { Module } from '@nestjs/common';
-import { ServeStaticModule } from '@nestjs/serve-static';
-import { join } from 'path';
-
-@Module({
-  imports: [
-    ServeStaticModule.forRoot({
-      rootPath: join(process.cwd(), 'uploads'),
-      serveRoot: '/uploads',
-    }),
-  ],
+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()
 })
-export class AppModule {}
 ```
 
-Without this, local files can still be downloaded through your own controller endpoints.
-
-## Upload Files In Controllers
-
-`FileStorageInterceptor()` wraps Multer and uploads files into the configured storage engine before your route handler runs.
-
-All upload routes must accept `multipart/form-data`.
-
-### Default request-body mapping
-
-By default, the interceptor writes storage keys into `request.body`.
+### Async configuration
 
-| Upload mode | Accepted form field(s) | Default `body` value |
-| --- | --- | --- |
-| `FileStorageInterceptor('file')` | `file` | `body.file: string` |
-| `type: 'array'` | repeated `files` or `files[0]`, `files[1]`, ... | `body.files: string[]` |
-| `type: 'fields'` | each configured field name | `body[fieldName]: string[]` |
+Use `forRootAsync` when config comes from `ConfigService`, a database, etc.:
 
-Important behavior for `fields` mode:
+```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'),
+      }),
+    },
+  }),
+});
+```
 
-- Every configured field is mapped to an array.
-- That stays true even when `maxCount: 1`.
+### Provider comparison
 
-DTO note:
+| 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 |
 
-- Because the interceptor writes into `request.body` before your route handler executes, your DTO shape should match the mapped value.
-- Typical DTO fields are `string` for single uploads, `string[]` for array uploads, and custom object shapes when you use `mapToRequestBody`.
+## Custom storage drivers
 
-### Single file upload
+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.
 
 ```ts
-import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
+import { defineDriver, StorageDriver, UploadedFile } from '@ackplus/nest-file-storage';
+import { Storage } from '@google-cloud/storage';
 
-@Controller('files')
-export class FilesController {
-  @Post('single')
-  @UseInterceptors(FileStorageInterceptor('file'))
-  uploadSingle(@Body() body: { file: string }) {
+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: body.file,
+      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' }) },
+});
 ```
 
-### Multiple files in one field
+For async setup, register a plain factory instead: `drivers: { gcs: async () => new GcsDriver(await load()) }`.
 
-```ts
-import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
+## Multi-tenant storage
 
-@Controller('files')
-export class FilesController {
-  @Post('multiple')
-  @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'array',
-      fieldName: 'files',
-      maxCount: 10,
-    }),
-  )
-  uploadMultiple(@Body() body: { files: string[] }) {
-    return {
-      keys: body.files,
-      count: body.files.length,
-    };
-  }
-}
-```
-
-### Multiple named fields
+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 { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('files')
-export class FilesController {
-  @Post('fields')
-  @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'fields',
-      fields: [
-        { name: 'avatar', maxCount: 1 },
-        { name: 'attachments', maxCount: 5 },
-      ],
-    }),
-  )
-  uploadFields(@Body() body: { avatar: string[]; attachments: string[] }) {
-    return body;
-  }
-}
+import { NestFileStorageModule, localDriver, s3Driver, tenantFrom } from '@ackplus/nest-file-storage';
+
+NestFileStorageModule.forRootAsync({
+  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)
+    },
+  }),
+});
 ```
 
-## Validation
-
-Use the interceptor options for validation, not the module registration.
-
-### File size and mime type validation
-
-Use `multerOptions()` when you want Multer to reject invalid uploads before your route handler runs.
+Controllers need **no tenant-specific code** — a plain `FileStorageInterceptor('file')` is routed automatically:
 
 ```ts
-import {
-  BadRequestException,
-  Body,
-  Controller,
-  Post,
-  UseInterceptors,
-} from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('images')
-export class ImagesController {
-  @Post()
-  @UseInterceptors(
-    FileStorageInterceptor('image', {
-      multerOptions: () => ({
-        limits: {
-          fileSize: 5 * 1024 * 1024,
-        },
-        fileFilter: (_req, file, cb) => {
-          const allowed = ['image/jpeg', 'image/png', 'image/webp'];
-          if (!allowed.includes(file.mimetype)) {
-            return cb(new BadRequestException('Only JPEG, PNG, and WebP files are allowed'), false);
-          }
-          cb(null, true);
-        },
-      }),
-      fileDist: () => 'images',
-    }),
-  )
-  upload(@Body() body: { image: string }) {
-    return body;
-  }
-}
+@Post('upload')
+@UseInterceptors(FileStorageInterceptor('file'))
+upload(@Body() body: { file: string }) { return { key: body.file }; }
 ```
 
-### Cross-field or post-upload validation
-
-Use `afterUpload()` when validation depends on the final uploaded file list or multiple fields together.
+Outside a request (jobs, URL generation), resolve a tenant's driver programmatically — it uses the same cache:
 
 ```ts
-import { BadRequestException, Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('gallery')
-export class GalleryController {
-  @Post()
-  @UseInterceptors(
-    FileStorageInterceptor(
-      {
-        type: 'fields',
-        fields: [
-          { name: 'cover', maxCount: 1 },
-          { name: 'images', maxCount: 10 },
-        ],
-      },
-      {
-        afterUpload: (req) => {
-          const files = req.files as Record<string, Express.Multer.File[]>;
-          const imageCount = files?.images?.length ?? 0;
-          if (imageCount < 2) {
-            throw new BadRequestException('At least 2 gallery images are required.');
-          }
-        },
-      },
-    ),
-  )
-  create(@Body() body: { cover: string[]; images: string[] }) {
-    return body;
-  }
-}
+const { driver, prefix } = await this.fileStorage.getTenantDriver('acme');
+const url = await driver.getUrl(key);
 ```
 
-Practical guidance:
-
-- Use `limits.fileSize` for upload size limits.
-- Use `fileFilter` for mime-type or extension checks.
-- Use `afterUpload` for rules involving multiple files or fields.
-- Do not rely on `file.size` inside `fileName()`; Multer size limits are the reliable way to cap upload size.
+When a tenant changes its storage settings, drop the cached driver: `this.fileStorage.getRegistry().invalidateTenant('acme')`.
 
-## Control The Stored Path And Key
+**`tenant.driver(tenantId)` returns one of:**
 
-Two callbacks define where the file is stored and what key is saved:
+| 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) |
 
-- `fileDist(file, req)`: the directory or path prefix.
-- `fileName(file, req)`: the final filename segment.
+## Uploading in controllers
 
-The final key is effectively:
+`FileStorageInterceptor(field, options?)` accepts `multipart/form-data`, stores the file(s), and writes the result into `request.body`.
 
-```text
-<fileDist>/<fileName>
+```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[] }) {}
 ```
 
-### Default key generation
-
-If you do not override anything:
-
-- Local storage stores files under `rootPath/YYYY/MM/DD`.
-- S3 and Azure store files under `uploads/YYYY/MM/DD`.
-- The default filename is `uuid-originalname`.
-
-Examples:
-
-- Local key: `2026/04/23/2d0b8f6e-report.pdf`
-- S3 key: `uploads/2026/04/23/2d0b8f6e-report.pdf`
+| 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[]` |
 
-### Custom path and filename
+### Control the stored key
 
 ```ts
-import { extname } from 'path';
-
 FileStorageInterceptor('avatar', {
-  fileDist: (_file, req) => `users/${req.user.id}/avatars`,
-  fileName: (file) => `${Date.now()}${extname(file.originalname)}`,
+  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
 ```
 
-This gives you keys such as:
-
-```text
-users/42/avatars/1713876155123.png
-```
-
-Use `fileDist` for folder structure and `fileName` for the last path segment. That is the most reliable way to control saved keys in the current implementation.
-
-## Map Upload Results Into `request.body`
-
-The default mapping stores only keys. If you want richer metadata in the controller body, use `mapToRequestBody`.
+The final key is `joinKey(prefix, fileDist, fileName)`. Defaults: `fileDist` = `YYYY/MM/DD`, `fileName` = `uuid-originalname`.
 
-### Return metadata instead of just the key
+### Override the driver for one route
 
 ```ts
-import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('documents')
-export class DocumentsController {
-  @Post()
-  @UseInterceptors(
-    FileStorageInterceptor('document', {
-      mapToRequestBody: (file) => ({
-        key: file.key,
-        url: file.url,
-        size: file.size,
-        mimetype: file.mimetype,
-        originalName: file.originalName,
-        fullPath: file.fullPath,
-      }),
-    }),
-  )
-  upload(@Body() body: any) {
-    return body.document;
-  }
-}
+FileStorageInterceptor('file', { driver: 's3' });                        // by name
+FileStorageInterceptor('file', { driver: (req) => req.user.plan });      // dynamically
+FileStorageInterceptor('file', { tenant: false });                       // opt out of tenant routing
 ```
 
-### Preserve an existing body field
+## Validation & limits
 
-If the request already contains a JSON/text field with the same name and you only want to populate it when missing:
+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.
 
 ```ts
-FileStorageInterceptor('file', {
-  overwriteBodyField: false,
+// module-wide default
+validation: { maxSize: 10 * 1024 * 1024 }
+
+// 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)
+  },
 });
 ```
 
-## Use `FileStorageService` Programmatically
+| Rule | Becomes | Throws on violation |
+| --- | --- | --- |
+| `maxSize` | Multer `limits.fileSize` | `FileTooLargeException` |
+| `maxFiles` | Multer `limits.files` | `TooManyFilesException` |
+| `allowedMimeTypes` / `allowedExtensions` | generated `fileFilter` | `InvalidFileTypeException` |
 
-`FileStorageService.getStorage()` gives you the active storage implementation so you can upload or manage files outside controller interceptors.
+All three extend `BadRequestException`, so they surface as standard `400` responses. For cross-field rules (e.g. "at least 2 images"), use `afterUpload`:
 
 ```ts
-import { Injectable } from '@nestjs/common';
-import { FileStorageService } from '@ackplus/nest-file-storage';
-
-@Injectable()
-export class DocumentStorageService {
-  async upload(buffer: Buffer, key: string) {
-    const storage = await FileStorageService.getStorage();
-    return storage.putFile(buffer, key);
-  }
-
-  async get(key: string) {
-    const storage = await FileStorageService.getStorage();
-    return storage.getFile(key);
-  }
-
-  async remove(key: string) {
-    const storage = await FileStorageService.getStorage();
-    await storage.deleteFile(key);
-  }
+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.');
+  },
+});
+```
 
-  async copy(oldKey: string, newKey: string) {
-    const storage = await FileStorageService.getStorage();
-    return storage.copyFile(oldKey, newKey);
-  }
+## Mapping results into the request body
 
-  async url(key: string) {
-    const storage = await FileStorageService.getStorage();
-    return storage.getUrl(key);
-  }
+By default the interceptor writes the storage **key** into `request.body[field]`. Customize it with `mapToRequestBody`:
 
-  async signedUrl(key: string) {
-    const storage = await FileStorageService.getStorage();
-    if ('getSignedUrl' in storage && storage.getSignedUrl) {
-      return storage.getSignedUrl(key, { expiresIn: 3600 });
-    }
-    return storage.getUrl(key);
-  }
-}
+```ts
+FileStorageInterceptor('document', {
+  mapToRequestBody: (file) => ({ key: file.key, url: file.url, size: file.size }),
+});
+// body.document === { key, url, size }
 ```
 
-### Get full URL from a stored key/path
+Set `overwriteBodyField: false` to keep an existing body value (e.g. a JSON field with the same name on a PATCH).
 
-If you save only the storage key in your database, generate the public URL later with `getUrl(key)`. This works across Local, S3, and Azure.
+## 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 FileUrlService {
-  async getUrlFromKey(key?: string | null): Promise<string | null> {
-    if (!key) {
-      return null;
-    }
-
-    const storage = await FileStorageService.getStorage();
-    return await Promise.resolve(storage.getUrl(key));
-  }
+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); }
 }
 ```
 
-### Add full URLs after loading entities
-
-The usual pattern is to store only `fileKey` in the entity and attach the final URL after fetching data.
+A common pattern: store only the `key` in your database and build the URL when serializing a response.
 
 ```ts
-import { Injectable } from '@nestjs/common';
-import { FileStorageService } from '@ackplus/nest-file-storage';
-
-type UserRecord = {
-  id: number;
-  avatarKey?: string | null;
-};
-
-@Injectable()
-export class UsersResponseMapper {
-  async mapUser(user: UserRecord) {
-    const storage = await FileStorageService.getStorage();
-
-    return {
-      ...user,
-      avatarUrl: user.avatarKey
-        ? await Promise.resolve(storage.getUrl(user.avatarKey))
-        : null,
-    };
-  }
+async toResponse(user: { avatarKey?: string }) {
+  return { ...user, avatarUrl: user.avatarKey ? await this.fileStorage.getUrl(user.avatarKey) : null };
 }
 ```
 
-For entity-based applications:
-
-- Store the key/path in the entity, for example `avatarKey` or `documentKey`.
-- Build the full URL in a service, mapper, serializer, or response DTO step after loading the entity.
-- This is usually cleaner than doing URL generation inside ORM entity hooks, because `FileStorageService.getStorage()` is async.
+## The `UploadedFile` model (file state)
 
-### Provider capability summary
-
-| Method | Local | S3 | Azure |
-| --- | --- | --- | --- |
-| `putFile()` | yes | yes | yes |
-| `getFile()` | yes | yes | yes |
-| `deleteFile()` | yes | yes | yes |
-| `copyFile()` | yes | yes | yes |
-| `getUrl()` | yes | yes | yes |
-| `getSignedUrl()` | no | yes | yes |
-| `path()` | yes | no | no |
-
-## Route-Level Storage Override
-
-You can override the storage provider per route.
+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.
 
 ```ts
-import { Body, Controller, Post, UseInterceptors } from '@nestjs/common';
-import { FileStorageEnum, FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('avatars')
-export class AvatarController {
-  @Post()
-  @UseInterceptors(
-    FileStorageInterceptor('avatar', {
-      storageType: FileStorageEnum.S3,
-      storageOptions: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-        region: process.env.AWS_REGION!,
-        bucket: process.env.AWS_BUCKET!,
-        fileDist: (_file, req) => `users/${req.user.id}/avatars`,
-      },
-      mapToRequestBody: (file) => ({
-        key: file.key,
-        url: file.url,
-      }),
-    }),
-  )
-  upload(@Body() body: any) {
-    return body.avatar;
-  }
+interface UploadedFile {
+  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
 }
 ```
 
-Important behavior:
+| 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
 
-- If the route uses the same provider as the module default, `storageOptions` can override pieces of that provider config.
-- If the route uses a different provider than the module default, pass the full config for that provider inside `storageOptions`.
+### `NestFileStorageModule`
 
-## Configuration Reference
+- `forRoot(options)` / `forRootAsync(asyncOptions)` → a global `DynamicModule`.
+- Options: `{ default: string; drivers: Record<string, DriverFactory>; validation?: UploadValidation; tenant?: TenantOptions }`.
 
-### Common file options
+### Driver factories
 
-These are shared by Local, S3, and Azure configs:
+- `localDriver(options)` · `s3Driver(options)` · `azureDriver(options)` · `defineDriver(DriverClass, options?)` → `DriverFactory`.
 
-- `fileName(file, req)`: return the filename segment.
-- `fileDist(file, req)`: return the folder/path prefix.
-- `transformUploadedFileObject(file)`: transform the raw uploaded file object returned by the storage engine before Multer stores it.
+### `FileStorageService` (injectable)
 
-### Local config
+- `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.
 
-- `rootPath`: local directory where files are written.
-- `baseUrl`: URL prefix used by `getUrl()`.
-- Common file options listed above.
+### `FileStorageInterceptor(field, options?)`
 
-### S3 config
+`field`: a string (single file) or `{ type, fieldName?, maxCount?, fields? }`.
+`options`: `{ driver?, fileName?, fileDist?, prefix?, validation?, mapToRequestBody?, overwriteBodyField?, afterUpload?, tenant? }`.
 
-- `accessKeyId`
-- `secretAccessKey`
-- `region`
-- `bucket`
-- `endpoint`: optional custom S3-compatible endpoint.
-- `cloudFrontUrl`: optional CDN/public URL prefix used by `getUrl()`.
-- Common file options listed above.
+### The `StorageDriver` interface
 
-### Azure config
+```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? };
+}
+```
 
-- `account`
-- `accountKey`
-- `container`
-- Common file options listed above.
+### Tenant resolvers — `tenantFrom`
 
-Azure note:
+`jwt(path?)` · `header(name)` · `subdomain({ rootDomain?, ignore? })` · `param(name)` · `query(name)` · `first(...resolvers)`.
 
-- `getSignedUrl()` generates a SAS URL by default.
-- If `AZURE_CDN_DOMAIN_NAME` is set in the runtime environment, the Azure storage adapter returns `AZURE_CDN_DOMAIN_NAME/<key>` instead of a SAS URL.
+### Exceptions
 
-## Current Behavior Notes
+`FileTooLargeException` · `InvalidFileTypeException` · `TooManyFilesException` (all extend `BadRequestException`).
 
-- This package is implemented for NestJS with Express and Multer. It is not a Fastify-targeted integration.
-- In `fields` mode, each field is mapped to an array even when `maxCount` is `1`.
-- `baseUrl` is only a URL prefix. Add static serving yourself for direct local-file access.
-- The exported types include a `prefix` option, but `fileDist` and `fileName` are the reliable hooks for controlling saved paths in the current implementation.
-- The module stores one provider configuration at a time. For per-route provider switching, use `storageType` with `storageOptions`.
-- The custom `storageFactory` module option is best treated as an advanced service-level hook. The controller upload flow documented here is the built-in path for Local, S3, and Azure storage.
+---
 
-## Examples And Workspace Docs
+## More
 
-- Package examples: [`examples/`](./examples/)
-- Workspace overview: [`../../README.md`](../../README.md)
-- Example app: [`../../apps/example-app/README.md`](../../apps/example-app/README.md)
+- **[Migration from v1](./MIGRATION.md)** · **[Changelog](./CHANGELOG.md)** · **[Examples](./examples/)**
 
 ## License