@nest-omni/core 4.1.3-2 → 4.1.3-20

package/file-upload/services/mime-registry.service.d.ts

@@ -0,0 +1,47 @@
+import { CustomFileTypes, MimeConfig, ResolvedFileTypes } from '../interfaces/custom-file-type.interface';
+import { FileType } from '../enums/file-type.enum';
+/**
+ * MIME 类型注册服务
+ * 负责管理内置和自定义文件类型
+ */
+export declare class MimeRegistryService {
+    private readonly logger;
+    private readonly typeMap;
+    constructor();
+    /**
+     * 注册自定义文件类型
+     */
+    registerCustomFileTypes(customTypes: CustomFileTypes): void;
+    /**
+     * 获取 MIME 配置
+     */
+    getMimeConfig(type: string): MimeConfig | null;
+    /**
+     * 解析文件类型为 MIME 类型和扩展名
+     */
+    resolveFileTypes(types: Array<FileType | string>): ResolvedFileTypes;
+    /**
+     * 获取所有注册的类型
+     */
+    getAllRegisteredTypes(): string[];
+    /**
+     * 检查类型是否已注册
+     */
+    isTypeRegistered(type: string): boolean;
+    /**
+     * 根据 MIME 类型查找类型名称
+     */
+    findTypeByMime(mimeType: string): string | null;
+    /**
+     * 根据扩展名查找类型名称
+     */
+    findTypeByExtension(extension: string): string | null;
+    /**
+     * 初始化内置类型
+     */
+    private initializeBuiltInTypes;
+    /**
+     * 获取默认描述
+     */
+    private getDefaultDescription;
+}

package/file-upload/services/mime-registry.service.js

@@ -0,0 +1,167 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var MimeRegistryService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MimeRegistryService = void 0;
+const common_1 = require("@nestjs/common");
+const file_type_enum_1 = require("../enums/file-type.enum");
+/**
+ * MIME 类型注册服务
+ * 负责管理内置和自定义文件类型
+ */
+let MimeRegistryService = MimeRegistryService_1 = class MimeRegistryService {
+    constructor() {
+        this.logger = new common_1.Logger(MimeRegistryService_1.name);
+        this.typeMap = new Map();
+        this.initializeBuiltInTypes();
+    }
+    /**
+     * 注册自定义文件类型
+     */
+    registerCustomFileTypes(customTypes) {
+        Object.entries(customTypes).forEach(([typeName, config]) => {
+            const mimeConfig = {
+                mimes: Array.isArray(config.mime) ? config.mime : [config.mime],
+                extensions: config.extension
+                    ? Array.isArray(config.extension)
+                        ? config.extension
+                        : [config.extension]
+                    : [],
+                description: config.description || this.getDefaultDescription(typeName),
+                icon: config.icon,
+                signatures: config.signature,
+                fileType: config.isImage
+                    ? 'image'
+                    : config.isDocument
+                        ? 'document'
+                        : config.isMedia
+                            ? 'media'
+                            : 'other',
+            };
+            this.typeMap.set(typeName, mimeConfig);
+            this.logger.debug(`Registered custom file type: ${typeName}`);
+        });
+    }
+    /**
+     * 获取 MIME 配置
+     */
+    getMimeConfig(type) {
+        return this.typeMap.get(type) || null;
+    }
+    /**
+     * 解析文件类型为 MIME 类型和扩展名
+     */
+    resolveFileTypes(types) {
+        const mimes = new Set();
+        const exts = new Set();
+        const signatureTypes = new Set();
+        for (const type of types) {
+            // 优先使用注册的配置
+            const mimeConfig = this.getMimeConfig(type);
+            if (mimeConfig) {
+                mimeConfig.mimes.forEach((m) => mimes.add(m));
+                mimeConfig.extensions.forEach((e) => exts.add(e));
+                if (mimeConfig.signatures) {
+                    signatureTypes.add(type);
+                }
+                continue;
+            }
+            // 回退到内置映射
+            if (typeof type === 'string' && type in file_type_enum_1.FILE_TYPE_MAP) {
+                const mapping = file_type_enum_1.FILE_TYPE_MAP[type];
+                mapping.mimes.forEach((m) => mimes.add(m));
+                mapping.exts.forEach((e) => exts.add(e));
+                signatureTypes.add(type);
+            }
+            else {
+                // 直接的 MIME 类型
+                mimes.add(type);
+            }
+        }
+        return {
+            mimes: Array.from(mimes),
+            exts: Array.from(exts),
+            signatureTypes: Array.from(signatureTypes),
+        };
+    }
+    /**
+     * 获取所有注册的类型
+     */
+    getAllRegisteredTypes() {
+        return Array.from(this.typeMap.keys());
+    }
+    /**
+     * 检查类型是否已注册
+     */
+    isTypeRegistered(type) {
+        return this.typeMap.has(type);
+    }
+    /**
+     * 根据 MIME 类型查找类型名称
+     */
+    findTypeByMime(mimeType) {
+        for (const [typeName, config] of this.typeMap.entries()) {
+            if (config.mimes.includes(mimeType)) {
+                return typeName;
+            }
+        }
+        return null;
+    }
+    /**
+     * 根据扩展名查找类型名称
+     */
+    findTypeByExtension(extension) {
+        const normalizedExt = extension.toLowerCase();
+        for (const [typeName, config] of this.typeMap.entries()) {
+            if (config.extensions.some((ext) => ext.toLowerCase() === normalizedExt)) {
+                return typeName;
+            }
+        }
+        return null;
+    }
+    /**
+     * 初始化内置类型
+     */
+    initializeBuiltInTypes() {
+        Object.entries(file_type_enum_1.FILE_TYPE_MAP).forEach(([type, config]) => {
+            if (!this.typeMap.has(type)) {
+                this.typeMap.set(type, {
+                    mimes: config.mimes,
+                    extensions: config.exts,
+                    description: this.getDefaultDescription(type),
+                });
+            }
+        });
+        this.logger.log(`Initialized ${this.typeMap.size} built-in file types`);
+    }
+    /**
+     * 获取默认描述
+     */
+    getDefaultDescription(type) {
+        const descriptions = {
+            Image: 'Image files',
+            PDF: 'PDF documents',
+            Word: 'Microsoft Word documents',
+            Excel: 'Microsoft Excel spreadsheets',
+            PowerPoint: 'Microsoft PowerPoint presentations',
+            Video: 'Video files',
+            Audio: 'Audio files',
+            Archive: 'Archive files',
+            Text: 'Text files',
+        };
+        return descriptions[type] || `${type} files`;
+    }
+};
+exports.MimeRegistryService = MimeRegistryService;
+exports.MimeRegistryService = MimeRegistryService = MimeRegistryService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], MimeRegistryService);

package/file-upload/utils/checksum.util.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Checksum计算工具类
+ * 提供统一的文件校验和计算方法
+ */
+export declare class ChecksumUtil {
+    /**
+     * 计算文件checksum
+     * @param filePath 文件路径
+     * @param algorithm 算法（默认md5）
+     * @returns checksum字符串（hex格式）
+     */
+    static calculate(filePath: string, algorithm?: 'md5' | 'sha1' | 'sha256'): Promise<string>;
+    /**
+     * 计算Buffer的checksum
+     * @param buffer Buffer数据
+     * @param algorithm 算法（默认md5）
+     * @returns checksum字符串（hex格式）
+     */
+    static calculateFromBuffer(buffer: Buffer, algorithm?: 'md5' | 'sha1' | 'sha256'): string;
+    /**
+     * 验证文件checksum
+     * @param filePath 文件路径
+     * @param expectedChecksum 期望的checksum
+     * @param algorithm 算法（默认md5）
+     * @returns 是否匹配
+     */
+    static verify(filePath: string, expectedChecksum: string, algorithm?: 'md5' | 'sha1' | 'sha256'): Promise<boolean>;
+}

package/file-upload/utils/checksum.util.js

@@ -0,0 +1,65 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChecksumUtil = void 0;
+const crypto = require("crypto");
+const fs = require("fs-extra");
+/**
+ * Checksum计算工具类
+ * 提供统一的文件校验和计算方法
+ */
+class ChecksumUtil {
+    /**
+     * 计算文件checksum
+     * @param filePath 文件路径
+     * @param algorithm 算法（默认md5）
+     * @returns checksum字符串（hex格式）
+     */
+    static calculate(filePath_1) {
+        return __awaiter(this, arguments, void 0, function* (filePath, algorithm = 'md5') {
+            return new Promise((resolve, reject) => {
+                const hash = crypto.createHash(algorithm);
+                const stream = fs.createReadStream(filePath);
+                stream.on('data', (data) => hash.update(data));
+                stream.on('end', () => resolve(hash.digest('hex')));
+                stream.on('error', (err) => {
+                    stream.destroy();
+                    reject(err);
+                });
+            });
+        });
+    }
+    /**
+     * 计算Buffer的checksum
+     * @param buffer Buffer数据
+     * @param algorithm 算法（默认md5）
+     * @returns checksum字符串（hex格式）
+     */
+    static calculateFromBuffer(buffer, algorithm = 'md5') {
+        const hash = crypto.createHash(algorithm);
+        hash.update(buffer);
+        return hash.digest('hex');
+    }
+    /**
+     * 验证文件checksum
+     * @param filePath 文件路径
+     * @param expectedChecksum 期望的checksum
+     * @param algorithm 算法（默认md5）
+     * @returns 是否匹配
+     */
+    static verify(filePath_1, expectedChecksum_1) {
+        return __awaiter(this, arguments, void 0, function* (filePath, expectedChecksum, algorithm = 'md5') {
+            const actualChecksum = yield this.calculate(filePath, algorithm);
+            return actualChecksum.toLowerCase() === expectedChecksum.toLowerCase();
+        });
+    }
+}
+exports.ChecksumUtil = ChecksumUtil;

package/file-upload/utils/dynamic-import.util.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 动态导入工具类
+ * 用于在运行时按需加载可选依赖，类似 TypeORM 的做法
+ * 使用 Function 构造器来规避 webpack 的静态分析
+ */
+export declare class DynamicImportUtil {
+    /**
+     * 动态导入 AWS S3 SDK
+     * 只有在实际使用时才会尝试加载
+     */
+    static importAwsS3Sdk(): Promise<{
+        S3Client: any;
+        PutObjectCommand: any;
+        GetObjectCommand: any;
+        DeleteObjectCommand: any;
+        DeleteObjectsCommand: any;
+        HeadObjectCommand: any;
+        CopyObjectCommand: any;
+        ListObjectsV2Command: any;
+        getSignedUrl: any;
+    }>;
+    /**
+     * 动态导入阿里云 OSS SDK
+     */
+    static importAliOssSdk(): Promise<any>;
+    /**
+     * 动态导入 MinIO SDK
+     */
+    static importMinioSdk(): Promise<any>;
+    /**
+     * 动态导入图片处理库 Sharp
+     */
+    static importSharp(): Promise<any>;
+    /**
+     * 动态导入 Excel 处理库
+     */
+    static importExcelJs(): Promise<any>;
+    /**
+     * 动态导入 XLSX 处理库
+     */
+    static importXlsx(): Promise<any>;
+    /**
+     * 动态导入 fast-csv 处理库
+     */
+    static importFastCsv(): Promise<any>;
+    /**
+     * 检查依赖是否已安装
+     */
+    static checkDependency(modulePath: string): Promise<boolean>;
+    /**
+     * 批量检查依赖
+     */
+    static checkDependencies(modulePaths: string[]): Promise<Record<string, boolean>>;
+}

package/file-upload/utils/dynamic-import.util.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * 动态导入工具类
+ * 用于在运行时按需加载可选依赖，类似 TypeORM 的做法
+ * 使用 Function 构造器来规避 webpack 的静态分析
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicImportUtil = void 0;
+/**
+ * 使用 Function 构造器创建真正的动态导入函数
+ * 这样 webpack 就无法在编译时静态分析模块路径
+ */
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const dynamicImport = new Function('modulePath', 'return import(modulePath)');
+/**
+ * 检查模块是否可用
+ */
+function tryImport(modulePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield dynamicImport(modulePath);
+        }
+        catch (_a) {
+            return null;
+        }
+    });
+}
+class DynamicImportUtil {
+    /**
+     * 动态导入 AWS S3 SDK
+     * 只有在实际使用时才会尝试加载
+     */
+    static importAwsS3Sdk() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const s3Module = yield tryImport('@aws-sdk/client-s3');
+            const signedModule = yield tryImport('@aws-sdk/s3-request-presigner');
+            if (!s3Module || !signedModule) {
+                throw new Error('AWS SDK for S3 is not installed. Please install it using: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner');
+            }
+            return {
+                S3Client: s3Module.S3Client,
+                PutObjectCommand: s3Module.PutObjectCommand,
+                GetObjectCommand: s3Module.GetObjectCommand,
+                DeleteObjectCommand: s3Module.DeleteObjectCommand,
+                DeleteObjectsCommand: s3Module.DeleteObjectsCommand,
+                HeadObjectCommand: s3Module.HeadObjectCommand,
+                CopyObjectCommand: s3Module.CopyObjectCommand,
+                ListObjectsV2Command: s3Module.ListObjectsV2Command,
+                getSignedUrl: signedModule.getSignedUrl,
+            };
+        });
+    }
+    /**
+     * 动态导入阿里云 OSS SDK
+     */
+    static importAliOssSdk() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const ossModule = yield tryImport('ali-oss');
+            if (!ossModule) {
+                throw new Error('Aliyun OSS SDK is not installed. Please install it using: npm install ali-oss');
+            }
+            return ossModule.default || ossModule;
+        });
+    }
+    /**
+     * 动态导入 MinIO SDK
+     */
+    static importMinioSdk() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const minioModule = yield tryImport('minio');
+            if (!minioModule) {
+                throw new Error('MinIO SDK is not installed. Please install it using: npm install minio');
+            }
+            return minioModule.Client || minioModule;
+        });
+    }
+    /**
+     * 动态导入图片处理库 Sharp
+     */
+    static importSharp() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sharpModule = yield tryImport('sharp');
+            if (!sharpModule) {
+                throw new Error('Sharp is not installed. Please install it using: npm install sharp');
+            }
+            return sharpModule.default || sharpModule;
+        });
+    }
+    /**
+     * 动态导入 Excel 处理库
+     */
+    static importExcelJs() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const excelModule = yield tryImport('exceljs');
+            if (!excelModule) {
+                throw new Error('ExcelJS is not installed. Please install it using: npm install exceljs');
+            }
+            return excelModule.default || excelModule;
+        });
+    }
+    /**
+     * 动态导入 XLSX 处理库
+     */
+    static importXlsx() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const xlsxModule = yield tryImport('xlsx');
+            if (!xlsxModule) {
+                throw new Error('XLSX is not installed. Please install it using: npm install xlsx');
+            }
+            return xlsxModule.default || xlsxModule;
+        });
+    }
+    /**
+     * 动态导入 fast-csv 处理库
+     */
+    static importFastCsv() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const csvModule = yield tryImport('fast-csv');
+            if (!csvModule) {
+                throw new Error('fast-csv is not installed. Please install it using: npm install fast-csv');
+            }
+            return csvModule.default || csvModule;
+        });
+    }
+    /**
+     * 检查依赖是否已安装
+     */
+    static checkDependency(modulePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const module = yield tryImport(modulePath);
+            return module !== null;
+        });
+    }
+    /**
+     * 批量检查依赖
+     */
+    static checkDependencies(modulePaths) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const results = {};
+            yield Promise.all(modulePaths.map((path) => __awaiter(this, void 0, void 0, function* () {
+                results[path] = yield this.checkDependency(path);
+            })));
+            return results;
+        });
+    }
+}
+exports.DynamicImportUtil = DynamicImportUtil;

package/file-upload/utils/filename.util.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 文件名处理工具类
+ * 统一管理文件名的编码、清理、截取等操作
+ */
+export declare class FileNameUtil {
+    /**
+     * 解码并标准化文件名
+     * 1. Multer 默认使用 Latin1 解码，需要转换为 UTF-8
+     * 2. 移除特殊字符和控制字符
+     * 3. 截取超长文件名到指定长度
+     *
+     * @param filename 原始文件名
+     * @param maxLength 最大长度（默认 100 字符）
+     * @returns 处理后的文件名
+     */
+    static decodeAndNormalize(filename: string, maxLength?: number): string;
+    /**
+     * 智能截取文件名（保留扩展名）
+     *
+     * @param filename 文件名
+     * @param maxLength 最大长度
+     * @returns 截取后的文件名
+     */
+    static truncateWithExtension(filename: string, maxLength: number): string;
+    /**
+     * 清理文件名（移除危险字符）
+     * 移除路径遍历、路径分隔符、控制字符等
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitize(filename: string): string;
+    /**
+     * 清理并保留原始文件名结构
+     * 先解码 UTF-8，再清理危险字符
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitizeOriginal(filename: string): string;
+    /**
+     * 提取文件扩展名
+     *
+     * @param filename 文件名
+     * @returns 扩展名（包含点）或空字符串
+     */
+    static extractExtension(filename: string): string;
+    /**
+     * 获取不包含扩展名的文件名
+     *
+     * @param filename 文件名
+     * @returns 不包含扩展名的文件名
+     */
+    static getBaseName(filename: string): string;
+    /**
+     * 检查字符串是否包含有效的字符
+     */
+    private static hasValidCharacters;
+}