@dataclouder/nest-storage 0.0.8 → 0.0.10

package/README.md

@@ -0,0 +1,66 @@
+# @dataclouder/nest-storage
+
+NestJS library for storage services, providing a unified interface for Google Cloud Storage, Cloudflare R2, Minio, and Local storage.
+
+## Installation
+
+```bash
+npm install @dataclouder/nest-storage
+```
+
+## Features
+
+- **Multi-Provider Support**: Integrated support for Google Cloud Storage, Cloudflare R2, and Minio.
+- **Unified Interface**: Use the same methods regardless of the underlying storage service.
+- **Image Processing**: Automatic conversion of images to WebP format for optimized web delivery.
+- **Batch Operations**: Easily remove all storage files referenced within complex data objects or by URLs.
+- **Security**: Generate signed URLs for temporary access to private files.
+- **Auditable**: Built-in support for tracking uploads with auditable metadata.
+
+## Documentation
+
+For detailed guides and API references, please check the documentation files:
+
+- [Getting Started](./docs/index.md)
+- [Usage Guide](./docs/usage.md)
+- [Storage Providers](./docs/storage-providers.md)
+- [Frontend Integration](./docs/frontend-integration.md)
+- [Universal Storage](./docs/universal-storage.md)
+
+## Basic Usage
+
+1. **Register the module:**
+
+```typescript
+import { StorageModule } from '@dataclouder/nest-storage';
+
+@Module({
+  imports: [
+    StorageModule.register({
+      provider: 'GOOGLE', // or 'CLOUDFLARE', 'MINIO', 'LOCAL'
+      bucket: 'my-bucket',
+      // ... provider specific config
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+2. **Inject the service:**
+
+```typescript
+import { StorageService } from '@dataclouder/nest-storage';
+
+@Injectable()
+export class MyService {
+  constructor(private storageService: StorageService) {}
+
+  async uploadFile(file: Buffer, filename: string) {
+    return await this.storageService.upload(file, filename);
+  }
+}
+```
+
+---
+
+Developed by [dataclouder](https://github.com/dataclouder).

package/controllers/storage.controller.d.ts

@@ -1,6 +1,12 @@
 import { StorageFactory } from '../services/storage.factory';
-export declare class StorageTestController {
+import { FastifyRequest } from 'fastify';
+import { ConfigService } from '@nestjs/config';
+export declare class StorageController {
     private readonly storageFactory;
-    constructor(storageFactory: StorageFactory);
-    uploadTestFile(): Promise<Partial<import("..").CloudFileStorage>>;
+    private readonly configService;
+    constructor(storageFactory: StorageFactory, configService: ConfigService);
+    uploadFile(req: FastifyRequest, queryPath?: string, queryProvider?: string, queryKeepName?: any): Promise<Partial<import("..").CloudFileStorage>>;
+    uploadMultiple(req: FastifyRequest, queryPath?: string, queryProvider?: string, queryKeepName?: any): Promise<any[]>;
+    private generateFileName;
+    serveFile(filename: string, res: any): Promise<any>;
 }

package/controllers/storage.controller.js

@@ -41,37 +41,125 @@ var __importStar = (this && this.__importStar) || (function () {
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageTestController = void 0;
+exports.StorageController = void 0;
 const common_1 = require("@nestjs/common");
 const storage_factory_1 = require("../services/storage.factory");
-const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-let StorageTestController = class StorageTestController {
+const fs = __importStar(require("fs"));
+const config_1 = require("@nestjs/config");
+let StorageController = class StorageController {
     storageFactory;
-    constructor(storageFactory) {
+    configService;
+    constructor(storageFactory, configService) {
         this.storageFactory = storageFactory;
+        this.configService = configService;
+    }
+    async uploadFile(req, queryPath, queryProvider, queryKeepName) {
+        const data = await req.file();
+        if (!data) {
+            throw new Error('No file uploaded');
+        }
+        const effectiveProvider = queryProvider || data.fields?.provider?.value;
+        const effectivePath = queryPath || data.fields?.path?.value;
+        const queryKeepNameBool = queryKeepName === 'true' || queryKeepName === true;
+        const fieldKeepName = data.fields?.keepOriginalName?.value;
+        const fieldKeepNameBool = fieldKeepName === 'true' || fieldKeepName === true;
+        const effectiveKeepName = queryKeepNameBool || fieldKeepNameBool;
+        const fileBuffer = await data.toBuffer();
+        const storageService = this.storageFactory.getStorageService(effectiveProvider);
+        const auditable = { createdBy: 'system', updatedBy: 'system' };
+        const fileName = this.generateFileName(effectivePath, data.filename, effectiveKeepName);
+        if (data.mimetype.startsWith('image/')) {
+            return storageService.uploadWebpImage({
+                fileName,
+                imageBuffer: fileBuffer,
+            });
+        }
+        return storageService.uploadFile(fileName, fileBuffer, auditable, data.mimetype);
     }
-    async uploadTestFile() {
-        const storageService = this.storageFactory.getStorageService('CLOUDFLARE');
-        const filePath = path.join(process.cwd(), 'woman1.jpg');
-        const fileBuffer = fs.readFileSync(filePath);
-        const bucketName = 'polilan-bucket';
-        if (!bucketName) {
-            throw new Error('STORAGE_BUCKET environment variable not set.');
+    async uploadMultiple(req, queryPath, queryProvider, queryKeepName) {
+        const parts = req.files();
+        const uploadResults = [];
+        const currentPath = queryPath;
+        const currentProvider = queryProvider;
+        const queryKeepNameBool = queryKeepName === 'true' || queryKeepName === true;
+        const currentKeepName = queryKeepNameBool;
+        for await (const part of parts) {
+            if (part.file) {
+                const effectiveProvider = currentProvider || part.fields?.provider?.value;
+                const effectivePath = currentPath || part.fields?.path?.value;
+                const partKeepField = part.fields?.keepOriginalName?.value;
+                const partKeepNameBool = partKeepField === 'true' || partKeepField === true;
+                const effectiveKeepName = currentKeepName || partKeepNameBool;
+                const fileBuffer = await part.toBuffer();
+                const storageService = this.storageFactory.getStorageService(effectiveProvider);
+                const auditable = { createdBy: 'system', updatedBy: 'system' };
+                const fileName = this.generateFileName(effectivePath, part.filename, effectiveKeepName);
+                let result;
+                if (part.mimetype.startsWith('image/')) {
+                    result = await storageService.uploadWebpImage({
+                        fileName,
+                        imageBuffer: fileBuffer,
+                    });
+                }
+                else {
+                    result = await storageService.uploadFile(fileName, fileBuffer, auditable, part.mimetype);
+                }
+                uploadResults.push(result);
+            }
         }
-        return storageService.uploadWebpImage({ bucketName, fileName: 'myfolder/mywoman1-test.jpg', imageBuffer: fileBuffer });
+        return uploadResults;
+    }
+    generateFileName(storagePath, originalName, keepOriginalName) {
+        const sanitizedPath = storagePath ? storagePath.replace(/\/$/, '') : '';
+        const name = keepOriginalName ? originalName : `${Date.now()}-${originalName}`;
+        return sanitizedPath ? `${sanitizedPath}/${name}` : name;
+    }
+    async serveFile(filename, res) {
+        const uploadDir = this.configService.get('LOCAL_STORAGE_PATH') || path.join(process.cwd(), 'uploads');
+        const filePath = path.join(uploadDir, filename);
+        if (!fs.existsSync(filePath)) {
+            throw new common_1.NotFoundException('File not found');
+        }
+        return res.sendFile(filename, uploadDir);
     }
 };
-exports.StorageTestController = StorageTestController;
+exports.StorageController = StorageController;
 __decorate([
     (0, common_1.Post)('upload'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)('path')),
+    __param(2, (0, common_1.Query)('provider')),
+    __param(3, (0, common_1.Query)('keepOriginalName')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, String, Object]),
+    __metadata("design:returntype", Promise)
+], StorageController.prototype, "uploadFile", null);
+__decorate([
+    (0, common_1.Post)('upload-multiple'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)('path')),
+    __param(2, (0, common_1.Query)('provider')),
+    __param(3, (0, common_1.Query)('keepOriginalName')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, String, Object]),
+    __metadata("design:returntype", Promise)
+], StorageController.prototype, "uploadMultiple", null);
+__decorate([
+    (0, common_1.Get)('files/filename'),
+    __param(0, (0, common_1.Param)('filename')),
+    __param(1, (0, common_1.Res)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", []),
+    __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Promise)
-], StorageTestController.prototype, "uploadTestFile", null);
-exports.StorageTestController = StorageTestController = __decorate([
-    (0, common_1.Controller)('storage-test'),
-    __metadata("design:paramtypes", [storage_factory_1.StorageFactory])
-], StorageTestController);
+], StorageController.prototype, "serveFile", null);
+exports.StorageController = StorageController = __decorate([
+    (0, common_1.Controller)('storage'),
+    __metadata("design:paramtypes", [storage_factory_1.StorageFactory,
+        config_1.ConfigService])
+], StorageController);
 //# sourceMappingURL=storage.controller.js.map

package/controllers/storage.controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.controller.js","sourceRoot":"","sources":["../../../../../libs/nest-storage/src/controllers/storage.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAAkD;AAClD,iEAA6D;AAC7D,uCAAyB;AACzB,2CAA6B;AAGtB,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IACH;IAA7B,YAA6B,cAA8B;QAA9B,mBAAc,GAAd,cAAc,CAAgB;IAAG,CAAC;IAGzD,AAAN,KAAK,CAAC,cAAc;QAClB,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAEpC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAClE,CAAC;QAED,OAAO,cAAc,CAAC,eAAe,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,4BAA4B,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;IACzH,CAAC;CACF,CAAA;AAhBY,sDAAqB;AAI1B;IADL,IAAA,aAAI,EAAC,QAAQ,CAAC;;;;2DAYd;gCAfU,qBAAqB;IADjC,IAAA,mBAAU,EAAC,cAAc,CAAC;qCAEoB,gCAAc;GADhD,qBAAqB,CAgBjC"}
+{"version":3,"file":"storage.controller.js","sourceRoot":"","sources":["../../../../../libs/nest-storage/src/controllers/storage.controller.ts"],"names":[],"mappings":"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"}

package/docs/frontend-integration.md

@@ -0,0 +1,98 @@
+# Frontend Integration Guide
+
+This guide explains how to connect your frontend application (e.g., Angular) to the Nest Storage service.
+
+## API Endpoint
+
+- **URL**: `YOUR_BASE_URL/storage/upload`
+- **Method**: `POST`
+- **Content-Type**: `multipart/form-data`
+
+## Request Parameters
+
+Metadata is passed via **Query Parameters** in the URL, while the file itself is sent in the `multipart/form-data` body.
+
+### Query Parameters
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `path` | `string` | No | The target directory/path in storage (e.g., `avatars`, `docs/2024`). |
+| `provider` | `string` | No | The storage provider to use (`google`, `cloudflare`, `local`). |
+| `keepOriginalName` | `boolean` | No | If `true`, the file will keep its original name. If `false` (default), a timestamp prefix will be added. |
+
+### Multipart Body
+
+| Field | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `file` | `File` | **Yes** | The file object to be uploaded. |
+
+> [!TIP]
+> Using Query Parameters for metadata is the most reliable way to ensure the backend receives these values before processing the file stream.
+
+## Example Implementation (Angular)
+
+### 1. Storage Service
+
+Create a service to handle the upload logic:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HttpClient, HttpParams } from '@angular/common/http';
+import { Observable } from 'rxjs';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class FileUploadService {
+  private apiUrl = 'http://localhost:8091/storage/upload';
+
+  constructor(private http: HttpClient) {}
+
+  uploadFile(file: File, path?: string, provider?: string, keepOriginalName?: boolean): Observable<any> {
+    const formData = new FormData();
+    formData.append('file', file);
+
+    let params = new HttpParams();
+    if (path) params = params.set('path', path);
+    if (provider) params = params.set('provider', provider);
+    if (keepOriginalName) params = params.set('keepOriginalName', 'true');
+
+    return this.http.post(this.apiUrl, formData, { params });
+  }
+}
+```
+
+### 2. Component Usage
+
+```typescript
+onFileSelected(event: any) {
+  const file: File = event.target.files[0];
+  if (file) {
+    this.uploadService.uploadFile(file, 'user-uploads', 'cloudflare').subscribe({
+      next: (response) => {
+        console.log('Upload successful', response.url);
+      },
+      error: (err) => {
+        console.error('Upload failed', err);
+      }
+    });
+  }
+}
+```
+
+## Handling Response
+
+The service returns a `CloudFileStorage` object:
+
+```json
+{
+  "url": "https://storage.googleapis.com/bucket/path/to/file.png",
+  "path": "path/to/file.png",
+  "bucket": "my-bucket",
+  "provider": "google",
+  "auditable": {
+    "createdBy": "system",
+    "updatedBy": "system"
+  }
+}
+```

package/docs/index.md

@@ -0,0 +1,45 @@
+# Nest Storage Library
+
+The `@polilan/nest-storage` library provides a robust and flexible storage abstraction layer for NestJS applications. It simplifies file management by supporting multiple storage providers through a unified interface, allowing developers to switch between providers with minimal configuration changes.
+
+## Features
+
+- **Multi-Provider Support**: Integrated support for Google Cloud Storage, Cloudflare R2, and Minio.
+- **Unified Interface**: Use the same methods regardless of the underlying storage service.
+- **Image Processing**: Automatic conversion of images to WebP format for optimized web delivery.
+- **Batch Operations**: Easily remove all storage files referenced within complex data objects or by URLs.
+- **Security**: Generate signed URLs for temporary access to private files.
+- **Auditable**: Built-in support for tracking uploads with auditable metadata.
+- **Simplified Integration**: Support for metadata via URL Query Parameters to avoid multipart ordering issues.
+
+## File Size Limits
+
+By default, the application is configured to support file uploads up to **100MB**. This limit is defined at the application level in `src/main.ts` using two configurations:
+
+1.  **Fastify Body Limit**: Controls the maximum total request size.
+2.  **Multipart File Size**: Controls the maximum size for individual files.
+
+To increase these limits, modify the following in `src/main.ts`:
+
+```typescript
+// src/main.ts
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter({ bodyLimit: 104857600 }), // 100MB
+  { rawBody: true },
+);
+
+app.register(multipart as any, {
+  limits: {
+    fileSize: 104857600, // 100MB
+  },
+});
+```
+
+## References
+
+- [Frontend Integration](./frontend-integration.md): How to connect your frontend app to this service.
+- [Storage Providers](./storage-providers.md): Detailed configuration for GOOGLE, CLOUDFLARE, and LOCAL.
+- [Universal Storage](./universal-storage.md): Guide on the universal multi-provider integration.
+- [Usage Guide](./usage.md): Instructions on how to upload, download, and delete files.
+- [Cloud Models](../src/models/cloud.model.ts): Type definitions for storage objects and interfaces.