@ackplus/nest-file-storage 1.1.22 → 2.0.0

package/examples/1-basic-local-storage.example.ts

@@ -1,22 +1,26 @@
 /**
  * Example 1: Basic Local Storage Configuration
- * 
- * This example shows how to set up local file storage with basic configuration.
+ *
+ * The simplest setup — register a single local driver and make it the default.
  */
 
 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.LOCAL,
-      localConfig: {
-        rootPath: './uploads', // Directory where files will be stored
-        baseUrl: 'http://localhost:3000/uploads', // Base URL for accessing files
+      default: 'local',
+      drivers: {
+        local: localDriver({
+          rootPath: './uploads', // directory where files are written
+          baseUrl: 'http://localhost:3000/uploads', // URL prefix used by getUrl()
+        }),
       },
     }),
   ],
 })
 export class AppModule {}
 
+// Note: `baseUrl` only builds the URL string — it does not serve files over HTTP.
+// Add static serving (e.g. @nestjs/serve-static) or stream files via your own controller.

package/examples/10-testing.example.ts

@@ -1,233 +1,97 @@
 /**
  * Example 10: Testing File Storage
- * 
- * This example demonstrates how to write tests for file storage functionality.
+ *
+ * Two approaches: (a) a real local driver against a temp directory, and
+ * (b) an in-memory mock driver registered with defineDriver — no disk, no network.
  */
 
 import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication } from '@nestjs/common';
-import * as request from 'supertest';
-import * as fs from 'fs';
-import * as path from 'path';
-import { 
-  NestFileStorageModule, 
+import {
+  NestFileStorageModule,
   FileStorageService,
-  FileStorageEnum,
+  localDriver,
+  defineDriver,
+  StorageDriver,
+  UploadedFile,
 } from '@ackplus/nest-file-storage';
+import * as fs from 'fs';
+import * as path from 'path';
 
-describe('File Storage (e2e)', () => {
-  let app: INestApplication;
-  let storage: any;
+// (a) Local driver against a temp directory ---------------------------------
+
+describe('FileStorageService (local)', () => {
+  let fileStorage: FileStorageService;
   const testDir = './test-uploads';
 
   beforeAll(async () => {
-    const moduleFixture: TestingModule = await Test.createTestingModule({
+    const moduleRef: TestingModule = await Test.createTestingModule({
       imports: [
         NestFileStorageModule.forRoot({
-          storage: FileStorageEnum.LOCAL,
-          localConfig: {
-            rootPath: testDir,
-            baseUrl: 'http://localhost:3000/test-uploads',
-          },
+          default: 'local',
+          drivers: { local: localDriver({ rootPath: testDir, baseUrl: 'http://localhost/test' }) },
         }),
-        // Import your controllers and services
       ],
     }).compile();
-
-    app = moduleFixture.createNestApplication();
-    await app.init();
-
-    storage = await FileStorageService.getStorage();
+    fileStorage = moduleRef.get(FileStorageService);
   });
 
-  afterAll(async () => {
-    // Cleanup test directory
-    if (fs.existsSync(testDir)) {
-      fs.rmSync(testDir, { recursive: true, force: true });
-    }
-    await app.close();
+  afterAll(() => {
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
   });
 
-  describe('File Upload', () => {
-    it('should upload a single file', async () => {
-      const response = await request(app.getHttpServer())
-        .post('/upload/single')
-        .attach('file', Buffer.from('test content'), 'test.txt')
-        .expect(201);
-
-      expect(response.body.fileKey).toBeDefined();
-      expect(response.body.message).toBe('File uploaded successfully');
-    });
+  it('puts, reads, copies, and deletes', async () => {
+    const content = Buffer.from('hello');
+    const put = await fileStorage.putFile(content, 'a/b.txt');
+    expect(put.key).toBe('a/b.txt');
+    expect(put.size).toBe(content.length);
 
-    it('should upload multiple files', async () => {
-      const response = await request(app.getHttpServer())
-        .post('/upload/multiple')
-        .attach('files', Buffer.from('test 1'), 'test1.txt')
-        .attach('files', Buffer.from('test 2'), 'test2.txt')
-        .expect(201);
+    expect((await fileStorage.getFile('a/b.txt')).toString()).toBe('hello');
 
-      expect(response.body.fileKeys).toHaveLength(2);
-    });
+    const copy = await fileStorage.copyFile('a/b.txt', 'a/c.txt');
+    expect(copy.key).toBe('a/c.txt');
 
-    it('should reject invalid file types', async () => {
-      await request(app.getHttpServer())
-        .post('/upload/image')
-        .attach('image', Buffer.from('not an image'), 'test.txt')
-        .expect(400);
-    });
+    await fileStorage.deleteFile('a/b.txt');
+    await expect(fileStorage.getFile('a/b.txt')).rejects.toThrow();
   });
+});
 
-  describe('FileStorageService', () => {
-    const testKey = 'test/file.txt';
-    const testContent = Buffer.from('Hello, World!');
-
-    it('should upload a file', async () => {
-      const result = await storage.putFile(testContent, testKey);
-
-      expect(result.key).toBe(testKey);
-      expect(result.size).toBe(testContent.length);
-      expect(result.url).toContain(testKey);
-    });
-
-    it('should retrieve a file', async () => {
-      await storage.putFile(testContent, testKey);
-      const retrieved = await storage.getFile(testKey);
-
-      expect(retrieved.toString()).toBe(testContent.toString());
-    });
-
-    it('should get file URL', () => {
-      const url = storage.getUrl(testKey);
-      expect(url).toContain(testKey);
-      expect(url).toContain('http://localhost:3000');
-    });
-
-    it('should delete a file', async () => {
-      await storage.putFile(testContent, testKey);
-      await storage.deleteFile(testKey);
-
-      await expect(storage.getFile(testKey)).rejects.toThrow();
-    });
-
-    it('should copy a file', async () => {
-      const sourceKey = 'test/source.txt';
-      const targetKey = 'test/target.txt';
-
-      await storage.putFile(testContent, sourceKey);
-      const result = await storage.copyFile(sourceKey, targetKey);
-
-      expect(result.key).toBe(targetKey);
-
-      const copiedContent = await storage.getFile(targetKey);
-      expect(copiedContent.toString()).toBe(testContent.toString());
-
-      // Cleanup
-      await storage.deleteFile(sourceKey);
-      await storage.deleteFile(targetKey);
-    });
-
-    it('should handle multiple files', async () => {
-      const files = [
-        { key: 'test/file1.txt', content: Buffer.from('Content 1') },
-        { key: 'test/file2.txt', content: Buffer.from('Content 2') },
-        { key: 'test/file3.txt', content: Buffer.from('Content 3') },
-      ];
-
-      // Upload multiple files
-      await Promise.all(
-        files.map(file => storage.putFile(file.content, file.key))
-      );
-
-      // Verify all files exist
-      const results = await Promise.all(
-        files.map(file => storage.getFile(file.key))
-      );
-
-      expect(results).toHaveLength(3);
-      expect(results[0].toString()).toBe('Content 1');
+// (b) In-memory mock driver -------------------------------------------------
 
-      // Cleanup
-      await Promise.all(
-        files.map(file => storage.deleteFile(file.key))
-      );
-    });
-  });
-
-  describe('File Service', () => {
-    // Test your custom file service
-    it('should handle file operations', async () => {
-      // Your file service tests here
-    });
-  });
-});
+class MemoryDriver implements StorageDriver {
+  private files = new Map<string, Buffer>();
+  async putFile(content: Buffer, key: string): Promise<UploadedFile> {
+    this.files.set(key, content);
+    const name = path.basename(key);
+    return { key, url: `mem://${key}`, originalName: name, fileName: name, size: content.length, fullPath: key };
+  }
+  async getFile(key: string): Promise<Buffer> {
+    const f = this.files.get(key);
+    if (!f) throw new Error('not found');
+    return f;
+  }
+  async deleteFile(key: string): Promise<void> { this.files.delete(key); }
+  async copyFile(src: string, dest: string): Promise<UploadedFile> { return this.putFile(await this.getFile(src), dest); }
+  getUrl(key: string): string { return `mem://${key}`; }
+}
 
-/**
- * Unit Test Example
- */
-describe('FileService', () => {
-  let service: any; // Your file service
+describe('FileStorageService (mock driver)', () => {
+  let fileStorage: FileStorageService;
 
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
       imports: [
         NestFileStorageModule.forRoot({
-          storage: FileStorageEnum.LOCAL,
-          localConfig: {
-            rootPath: './test-uploads',
-            baseUrl: 'http://localhost:3000/test-uploads',
-          },
+          default: 'memory',
+          drivers: { memory: defineDriver(MemoryDriver) },
         }),
       ],
-      providers: [/* Your FileService */],
     }).compile();
-
-    service = module.get(/* Your FileService */);
+    fileStorage = moduleRef.get(FileStorageService);
   });
 
-  it('should be defined', () => {
-    expect(service).toBeDefined();
+  it('stores in memory', async () => {
+    await fileStorage.putFile(Buffer.from('x'), 'k');
+    expect((await fileStorage.getFile('k')).toString()).toBe('x');
+    expect(await fileStorage.getUrl('k')).toBe('mem://k');
   });
-
-  // Add more unit tests...
 });
-
-/**
- * Mock Storage for Testing
- */
-class MockStorage {
-  private files = new Map<string, Buffer>();
-
-  async putFile(content: Buffer, key: string) {
-    this.files.set(key, content);
-    return {
-      key,
-      url: `http://mock/${key}`,
-      size: content.length,
-      fileName: path.basename(key),
-      originalName: path.basename(key),
-      fullPath: key,
-    };
-  }
-
-  async getFile(key: string): Promise<Buffer> {
-    const file = this.files.get(key);
-    if (!file) {
-      throw new Error('File not found');
-    }
-    return file;
-  }
-
-  async deleteFile(key: string): Promise<void> {
-    this.files.delete(key);
-  }
-
-  async copyFile(oldKey: string, newKey: string) {
-    const file = await this.getFile(oldKey);
-    return await this.putFile(file, newKey);
-  }
-
-  getUrl(key: string): string {
-    return `http://mock/${key}`;
-  }
-}
-

package/examples/11-custom-driver.example.ts

@@ -0,0 +1,82 @@
+/**
+ * Example 11: Custom Storage Driver
+ *
+ * Implement the StorageDriver interface and register it with defineDriver. A custom driver works
+ * everywhere a built-in does — in the interceptor, the service, and tenant resolution.
+ *
+ * This example sketches a Google Cloud Storage driver; swap in any backend.
+ */
+
+import { Module, Injectable } from '@nestjs/common';
+import {
+  NestFileStorageModule,
+  defineDriver,
+  FileStorageService,
+  StorageDriver,
+  UploadedFile,
+  PutFileMeta,
+} from '@ackplus/nest-file-storage';
+// import { Storage } from '@google-cloud/storage';
+
+class GcsDriver implements StorageDriver {
+  // private storage = new Storage();
+  constructor(private readonly opts: { bucket: string }) {}
+
+  // private file(key: string) { return this.storage.bucket(this.opts.bucket).file(key); }
+
+  async putFile(content: Buffer, key: string, meta?: PutFileMeta): Promise<UploadedFile> {
+    // await this.file(key).save(content, { contentType: meta?.contentType });
+    void content;
+    void meta;
+    const name = key.split('/').pop()!;
+    return { key, url: this.getUrl(key), originalName: name, fileName: name, size: content.length, fullPath: key };
+  }
+
+  async getFile(key: string): Promise<Buffer> {
+    // const [buf] = await this.file(key).download();
+    // return buf;
+    throw new Error(`download ${key} not implemented in this sketch`);
+  }
+
+  async deleteFile(key: string): Promise<void> {
+    // await this.file(key).delete();
+    void key;
+  }
+
+  async copyFile(src: string, dest: string): Promise<UploadedFile> {
+    // await this.file(src).copy(this.file(dest));
+    void src;
+    const name = dest.split('/').pop()!;
+    return { key: dest, url: this.getUrl(dest), originalName: name, fileName: name, size: 0, fullPath: dest };
+  }
+
+  getUrl(key: string): string {
+    return `https://storage.googleapis.com/${this.opts.bucket}/${key}`;
+  }
+}
+
+@Module({
+  imports: [
+    NestFileStorageModule.forRoot({
+      default: 'gcs',
+      drivers: {
+        // defineDriver(Class, opts) is sugar for () => new Class(opts).
+        gcs: defineDriver(GcsDriver, { bucket: 'my-bucket' }),
+        // For async setup, pass a plain factory instead:
+        // gcs: async () => new GcsDriver(await loadGcsConfig()),
+      },
+    }),
+  ],
+})
+export class AppModule {}
+
+@Injectable()
+export class ReportService {
+  constructor(private readonly fileStorage: FileStorageService) {}
+
+  // Use the custom driver by name — identical to a built-in.
+  async save(buffer: Buffer, key: string) {
+    const gcs = await this.fileStorage.getDriver('gcs');
+    return gcs.putFile(buffer, key);
+  }
+}

package/examples/12-multi-tenant.example.ts

@@ -0,0 +1,93 @@
+/**
+ * Example 12: Multi-Tenant Storage
+ *
+ * Route each upload to the right tenant's storage. "globex" gets a dedicated bucket; every other
+ * tenant shares one driver with a per-tenant key prefix. The tenant's driver is cached, so the DB
+ * lookup + client construction happen once per tenant — not per request.
+ */
+
+import { Controller, Post, Body, UseInterceptors, Injectable, Module } from '@nestjs/common';
+import {
+  NestFileStorageModule,
+  FileStorageInterceptor,
+  FileStorageService,
+  localDriver,
+  s3Driver,
+  tenantFrom,
+} from '@ackplus/nest-file-storage';
+
+// Your per-tenant storage config source (e.g. a database table).
+@Injectable()
+export class TenantStorageService {
+  async find(tenantId: string): Promise<{ dedicated: boolean; bucket?: string; region?: string; key?: string; secret?: string } | null> {
+    void tenantId;
+    return null; // look up the tenant's storage config
+  }
+}
+
+@Module({
+  providers: [TenantStorageService],
+  imports: [
+    NestFileStorageModule.forRootAsync({
+      inject: [TenantStorageService],
+      useFactory: (tenants: TenantStorageService) => ({
+        default: 'local',
+        drivers: {
+          local: localDriver({ rootPath: './uploads', baseUrl: 'http://localhost:3000/uploads' }),
+        },
+        tenant: {
+          // 1) Identify the tenant — try JWT, then subdomain, then a header.
+          resolve: tenantFrom.first(
+            tenantFrom.jwt('tenantId'),
+            tenantFrom.subdomain(),
+            tenantFrom.header('x-tenant-id'),
+          ),
+          // 2) Resolve a tenant -> storage. Cached by tenant id.
+          driver: async (tenantId) => {
+            const cfg = await tenants.find(tenantId);
+            if (cfg?.dedicated) {
+              return {
+                factory: s3Driver({
+                  bucket: cfg.bucket!, region: cfg.region!,
+                  accessKeyId: cfg.key!, secretAccessKey: cfg.secret!,
+                }),
+              };
+            }
+            return { use: 'local', prefix: `tenants/${tenantId}` };
+          },
+          cache: { ttlMs: 10 * 60_000, max: 500 },
+          fallback: 'default', // no tenant -> default driver ('error' -> 400)
+        },
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+
+@Controller('files')
+export class TenantUploadController {
+  constructor(private readonly fileStorage: FileStorageService) {}
+
+  // No tenant-specific code — the interceptor routes to the tenant's storage automatically.
+  @Post('upload')
+  @UseInterceptors(FileStorageInterceptor('file', { mapToRequestBody: (file) => file }))
+  upload(@Body() body: any) {
+    return { message: 'Uploaded to the tenant storage', file: body.file };
+  }
+}
+
+// Programmatic access outside a request (jobs, URL generation):
+@Injectable()
+export class TenantReportService {
+  constructor(private readonly fileStorage: FileStorageService) {}
+
+  async urlFor(tenantId: string, key: string) {
+    const { driver } = await this.fileStorage.getTenantDriver(tenantId);
+    return driver.getUrl(key);
+  }
+
+  // When a tenant changes its storage settings, drop the cached driver:
+  invalidate(tenantId: string) {
+    this.fileStorage.getRegistry().invalidateTenant(tenantId);
+  }
+}

package/examples/2-s3-storage.example.ts

@@ -1,31 +1,33 @@
 /**
  * Example 2: AWS S3 Storage Configuration
- * 
- * This example shows how to configure AWS S3 for file storage.
- * Requires: @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+ *
+ * Configure AWS S3 (or an S3-compatible store like MinIO / R2 / Spaces).
+ * Requires: @aws-sdk/client-s3 @aws-sdk/s3-request-presigner (loaded lazily).
  */
 
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+import { NestFileStorageModule, s3Driver } from '@ackplus/nest-file-storage';
 
 @Module({
   imports: [
     ConfigModule.forRoot(),
-    // Async configuration with ConfigService
     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', 'us-east-1'),
-          bucket: configService.get('AWS_BUCKET'),
-          cloudFrontUrl: configService.get('AWS_CLOUDFRONT_URL'), // Optional CloudFront URL
+      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.get('AWS_REGION', 'us-east-1'),
+            bucket: config.getOrThrow('AWS_BUCKET'),
+            cloudFrontUrl: config.get('AWS_CLOUDFRONT_URL'), // optional CDN for getUrl()
+            endpoint: config.get('S3_ENDPOINT'), // optional, for S3-compatible stores
+          }),
         },
       }),
-      inject: [ConfigService],
     }),
   ],
 })
@@ -36,5 +38,5 @@ export class AppModule {}
 // AWS_SECRET_ACCESS_KEY=your-secret-key
 // AWS_REGION=us-east-1
 // AWS_BUCKET=your-bucket-name
-// AWS_CLOUDFRONT_URL=https://d1234567890.cloudfront.net (optional)
-
+// AWS_CLOUDFRONT_URL=https://d1234567890.cloudfront.net  (optional)
+// S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com  (optional, S3-compatible)

package/examples/3-azure-storage.example.ts

@@ -1,28 +1,30 @@
 /**
  * Example 3: Azure Blob Storage Configuration
- * 
- * This example shows how to configure Azure Blob Storage.
- * Requires: @azure/storage-blob
+ *
+ * Requires: @azure/storage-blob (loaded lazily).
  */
 
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+import { NestFileStorageModule, azureDriver } from '@ackplus/nest-file-storage';
 
 @Module({
   imports: [
     ConfigModule.forRoot(),
     NestFileStorageModule.forRootAsync({
       imports: [ConfigModule],
-      useFactory: async (configService: ConfigService) => ({
-        storage: FileStorageEnum.AZURE,
-        azureConfig: {
-          account: configService.get('AZURE_STORAGE_ACCOUNT'),
-          accountKey: configService.get('AZURE_STORAGE_KEY'),
-          container: configService.get('AZURE_CONTAINER', 'uploads'),
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        default: 'azure',
+        drivers: {
+          azure: azureDriver({
+            account: config.getOrThrow('AZURE_STORAGE_ACCOUNT'),
+            accountKey: config.getOrThrow('AZURE_STORAGE_KEY'),
+            container: config.get('AZURE_CONTAINER', 'uploads'),
+            cdnUrl: config.get('AZURE_CDN_URL'), // optional CDN for getSignedUrl()
+          }),
         },
       }),
-      inject: [ConfigService],
     }),
   ],
 })
@@ -32,4 +34,4 @@ export class AppModule {}
 // AZURE_STORAGE_ACCOUNT=your-account-name
 // AZURE_STORAGE_KEY=your-account-key
 // AZURE_CONTAINER=uploads
-
+// AZURE_CDN_URL=https://cdn.example.com  (optional)