@qhr123/sa2kit 0.1.1 → 0.2.0

package/dist/universalFile/index.d.ts

@@ -0,0 +1,519 @@
+/**
+ * 通用文件服务类型定义
+ *
+ * 定义了文件存储、上传、下载等核心接口和类型
+ */
+/** 文件存储类型 */
+type StorageType = 'local' | 'aliyun-oss' | 'aws-s3' | 'qcloud-cos';
+/** CDN提供者类型 */
+type CDNType = 'none' | 'aliyun-cdn' | 'aws-cloudfront' | 'qcloud-cdn';
+/** 文件处理类型 */
+type ProcessorType = 'image' | 'audio' | 'video' | 'document';
+/** 文件上传状态 */
+type UploadStatus = 'pending' | 'uploading' | 'processing' | 'completed' | 'failed';
+/** 访问权限类型 */
+type AccessPermission = 'public' | 'private' | 'authenticated' | 'owner-only';
+/** 文件元数据基础接口 */
+interface FileMetadata {
+    /** 文件ID */
+    id: string;
+    /** 原始文件名 */
+    originalName: string;
+    /** 存储文件名 */
+    storageName: string;
+    /** 文件大小(字节) */
+    size: number;
+    /** MIME类型 */
+    mimeType: string;
+    /** 文件扩展名 */
+    extension: string;
+    /** 文件哈希值 */
+    hash?: string;
+    /** 上传时间 */
+    uploadTime: Date;
+    /** 访问权限 */
+    permission: AccessPermission;
+    /** 上传者ID */
+    uploaderId: string;
+    /** 模块标识 */
+    moduleId: string;
+    /** 业务标识 */
+    businessId?: string;
+    /** 存储提供者 */
+    storageProvider: StorageType;
+    /** 存储路径 */
+    storagePath: string;
+    /** CDN URL */
+    cdnUrl?: string;
+    /** 访问次数 */
+    accessCount: number;
+    /** 最后访问时间 */
+    lastAccessTime?: Date;
+    /** 过期时间 */
+    expiresAt?: Date;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}
+/** 上传文件信息（客户端使用） */
+interface UploadFileInfo {
+    /** 文件对象 */
+    file: File;
+    /** 模块标识 */
+    moduleId: string;
+    /** 业务标识 */
+    businessId?: string;
+    /** 访问权限 */
+    permission?: AccessPermission;
+    /** 自定义存储路径 */
+    customPath?: string;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+    /** 是否需要处理 */
+    needsProcessing?: boolean;
+    /** 处理选项 */
+    processingOptions?: ProcessingOptions;
+}
+/** 文件处理选项 */
+interface ProcessingOptions {
+    /** 处理器类型 */
+    type: ProcessorType;
+    /** 处理参数 */
+    params?: Record<string, any>;
+}
+/** 上传进度 */
+interface UploadProgress {
+    /** 文件ID */
+    fileId: string;
+    /** 上传状态 */
+    status: UploadStatus;
+    /** 进度百分比(0-100) */
+    progress: number;
+    /** 已上传字节数 */
+    uploadedBytes: number;
+    /** 总字节数 */
+    totalBytes: number;
+    /** 上传速度(字节/秒) */
+    speed: number;
+    /** 剩余时间(秒) */
+    remainingTime: number;
+    /** 错误信息 */
+    error?: string;
+}
+/** 上传结果 */
+interface UploadResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 文件元数据 */
+    file?: FileMetadata;
+    /** 文件访问URL */
+    url?: string;
+    /** 错误信息 */
+    error?: string;
+}
+/** 文件查询选项 */
+interface FileQueryOptions {
+    /** 模块标识 */
+    moduleId?: string;
+    /** 业务标识 */
+    businessId?: string;
+    /** 上传者ID */
+    uploaderId?: string;
+    /** MIME类型过滤 */
+    mimeType?: string;
+    /** 最小文件大小 */
+    minSize?: number;
+    /** 最大文件大小 */
+    maxSize?: number;
+    /** 开始时间 */
+    startTime?: Date;
+    /** 结束时间 */
+    endTime?: Date;
+    /** 搜索关键词 */
+    keyword?: string;
+    /** 标签 */
+    tags?: string[];
+    /** 排序字段 */
+    sortBy?: string;
+    /** 排序方向 */
+    sortOrder?: 'asc' | 'desc';
+    /** 页码 */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+}
+/** 分页结果 */
+interface PaginatedResult<T> {
+    /** 数据项 */
+    items: T[];
+    /** 总数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总页数 */
+    totalPages: number;
+    /** 是否有下一页 */
+    hasNext: boolean;
+    /** 是否有上一页 */
+    hasPrev: boolean;
+}
+/** 批量操作结果 */
+interface BatchOperationResult {
+    /** 成功数量 */
+    successCount: number;
+    /** 失败数量 */
+    failureCount: number;
+    /** 失败详情 */
+    failures: Array<{
+        fileId: string;
+        error: string;
+    }>;
+}
+/** 文件事件类型 */
+type FileEventType = 'upload:start' | 'upload:progress' | 'upload:complete' | 'upload:error' | 'download:start' | 'download:complete' | 'download:error' | 'delete:complete' | 'processing:start' | 'processing:complete' | 'processing:error';
+/** 文件事件 */
+interface FileEvent {
+    /** 事件类型 */
+    type: FileEventType;
+    /** 文件ID */
+    fileId: string;
+    /** 事件时间 */
+    timestamp: Date;
+    /** 事件数据 */
+    data?: Record<string, any>;
+    /** 错误信息 */
+    error?: string;
+}
+/** 文件事件监听器 */
+type FileEventListener = (event: FileEvent) => void | Promise<void>;
+/** 文件服务基础异常 */
+declare class FileServiceError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/** 文件上传错误 */
+declare class FileUploadError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 文件处理错误 */
+declare class FileProcessingError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 存储提供者错误 */
+declare class StorageProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** CDN提供者错误 */
+declare class CDNProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+/**
+ * 通用文件服务客户端SDK
+ *
+ * 提供文件上传、下载、查询等功能的客户端接口
+ */
+
+interface UniversalFileClientConfig {
+    /** API基础URL */
+    baseUrl?: string;
+    /** 请求超时时间(毫秒) */
+    timeout?: number;
+    /** 上传超时时间(毫秒) */
+    uploadTimeout?: number;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+}
+/**
+ * 通用文件服务客户端
+ */
+declare class UniversalFileClient {
+    private config;
+    constructor(config?: UniversalFileClientConfig);
+    /**
+     * 上传文件
+     */
+    uploadFile(fileInfo: UploadFileInfo, onProgress?: (progress: UploadProgress) => void): Promise<FileMetadata>;
+    /**
+     * 获取文件访问URL
+     */
+    getFileUrl(fileId: string, expiresIn?: number): Promise<string>;
+    /**
+     * 获取文件元数据
+     */
+    getFileMetadata(fileId: string): Promise<FileMetadata>;
+    /**
+     * 查询文件列表
+     */
+    queryFiles(options: FileQueryOptions): Promise<PaginatedResult<FileMetadata>>;
+    /**
+     * 删除文件
+     */
+    deleteFile(fileId: string): Promise<void>;
+    /**
+     * 批量删除文件
+     */
+    batchDeleteFiles(fileIds: string[]): Promise<BatchOperationResult>;
+    /**
+     * 获取上传进度
+     */
+    getUploadProgress(fileId: string): Promise<UploadProgress>;
+    /**
+     * 获取请求头
+     */
+    private getHeaders;
+    /**
+     * 带超时的fetch请求
+     */
+    private fetchWithTimeout;
+    /**
+     * 转换API返回的文件元数据
+     */
+    private transformFileMetadataFromAPI;
+}
+/**
+ * 默认客户端实例
+ */
+declare const universalFileClient: UniversalFileClient;
+/**
+ * 创建自定义客户端实例
+ */
+declare function createFileClient(config?: UniversalFileClientConfig): UniversalFileClient;
+
+/**
+ * 通用文件服务常量定义
+ */
+/** 模块版本 */
+declare const UNIVERSAL_FILE_VERSION = "1.0.0";
+/** 模块名称 */
+declare const UNIVERSAL_FILE_NAME = "@qhr123/sa2kit/universalFile";
+/** 默认最大文件大小(字节) - 100MB */
+declare const DEFAULT_MAX_FILE_SIZE: number;
+/** 默认最大图片大小(字节) - 10MB */
+declare const DEFAULT_MAX_IMAGE_SIZE: number;
+/** 默认最大视频大小(字节) - 500MB */
+declare const DEFAULT_MAX_VIDEO_SIZE: number;
+/** 默认最大音频大小(字节) - 50MB */
+declare const DEFAULT_MAX_AUDIO_SIZE: number;
+/** 默认最大文档大小(字节) - 20MB */
+declare const DEFAULT_MAX_DOCUMENT_SIZE: number;
+/** 图片MIME类型 */
+declare const IMAGE_MIME_TYPES: string[];
+/** 视频MIME类型 */
+declare const VIDEO_MIME_TYPES: string[];
+/** 音频MIME类型 */
+declare const AUDIO_MIME_TYPES: string[];
+/** 文档MIME类型 */
+declare const DOCUMENT_MIME_TYPES: string[];
+/** 所有支持的MIME类型 */
+declare const ALL_SUPPORTED_MIME_TYPES: string[];
+/** 图片扩展名 */
+declare const IMAGE_EXTENSIONS: string[];
+/** 视频扩展名 */
+declare const VIDEO_EXTENSIONS: string[];
+/** 音频扩展名 */
+declare const AUDIO_EXTENSIONS: string[];
+/** 文档扩展名 */
+declare const DOCUMENT_EXTENSIONS: string[];
+/** API基础路径 */
+declare const API_BASE_PATH = "/api/universal-file";
+/** API端点 */
+declare const API_ENDPOINTS: {
+    /** 上传文件 */
+    readonly UPLOAD: "/api/universal-file/upload";
+    /** 获取文件URL */
+    readonly GET_URL: (fileId: string) => string;
+    /** 获取文件元数据 */
+    readonly GET_METADATA: (fileId: string) => string;
+    /** 删除文件 */
+    readonly DELETE: (fileId: string) => string;
+    /** 查询文件列表 */
+    readonly QUERY: "/api/universal-file/files";
+    /** 批量删除 */
+    readonly BATCH_DELETE: "/api/universal-file/files/batch-delete";
+    /** 获取上传进度 */
+    readonly GET_PROGRESS: (fileId: string) => string;
+};
+/** 错误代码 */
+declare const ERROR_CODES: {
+    /** 文件上传错误 */
+    readonly FILE_UPLOAD_ERROR: "FILE_UPLOAD_ERROR";
+    /** 文件大小超限 */
+    readonly FILE_SIZE_EXCEEDED: "FILE_SIZE_EXCEEDED";
+    /** 文件类型不支持 */
+    readonly FILE_TYPE_NOT_SUPPORTED: "FILE_TYPE_NOT_SUPPORTED";
+    /** 文件不存在 */
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    /** 文件处理错误 */
+    readonly FILE_PROCESSING_ERROR: "FILE_PROCESSING_ERROR";
+    /** 存储提供者错误 */
+    readonly STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR";
+    /** CDN提供者错误 */
+    readonly CDN_PROVIDER_ERROR: "CDN_PROVIDER_ERROR";
+    /** 网络错误 */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** 超时错误 */
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    /** 未授权 */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** 权限不足 */
+    readonly FORBIDDEN: "FORBIDDEN";
+    /** 服务器错误 */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+/** 默认分页大小 */
+declare const DEFAULT_PAGE_SIZE = 20;
+/** 默认请求超时时间(毫秒) - 30秒 */
+declare const DEFAULT_REQUEST_TIMEOUT = 30000;
+/** 默认上传超时时间(毫秒) - 5分钟 */
+declare const DEFAULT_UPLOAD_TIMEOUT = 300000;
+/** 默认分片上传大小(字节) - 5MB */
+declare const DEFAULT_CHUNK_SIZE: number;
+
+/**
+ * 通用文件服务工具函数
+ */
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 解析文件大小字符串
+ */
+declare function parseFileSize(sizeStr: string): number;
+/**
+ * 获取文件扩展名
+ */
+declare function getFileExtension(fileName: string): string;
+/**
+ * 根据文件名获取MIME类型
+ */
+declare function getMimeTypeFromFileName(fileName: string): string;
+/**
+ * 检查MIME类型是否支持
+ */
+declare function isMimeTypeSupported(mimeType: string, allowedTypes?: string[]): boolean;
+/**
+ * 判断是否为图片类型
+ */
+declare function isImageFile(mimeType: string): boolean;
+/**
+ * 判断是否为视频类型
+ */
+declare function isVideoFile(mimeType: string): boolean;
+/**
+ * 判断是否为音频类型
+ */
+declare function isAudioFile(mimeType: string): boolean;
+/**
+ * 判断是否为文档类型
+ */
+declare function isDocumentFile(mimeType: string): boolean;
+/**
+ * 获取文件类型类别
+ */
+declare function getFileCategory(mimeType: string): 'image' | 'video' | 'audio' | 'document' | 'other';
+/**
+ * 验证文件名是否合法
+ */
+declare function validateFileName(fileName: string): boolean;
+/**
+ * 清理文件名，移除非法字符
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * 生成唯一文件名
+ */
+declare function generateUniqueFileName(originalName: string, fileId: string): string;
+/**
+ * 生成存储路径
+ */
+declare function generateStoragePath(moduleId: string, fileName: string, options?: {
+    businessId?: string;
+    useDate?: boolean;
+    customPrefix?: string;
+}): string;
+/**
+ * 解析存储路径
+ */
+declare function parseStoragePath(path: string): {
+    moduleId?: string;
+    businessId?: string;
+    year?: string;
+    month?: string;
+    day?: string;
+    fileName: string;
+};
+/**
+ * 验证文件大小
+ */
+declare function validateFileSize(file: File, maxSize: number): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件类型
+ */
+declare function validateFileType(file: File, allowedTypes?: string[]): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件
+ */
+declare function validateFile(file: File, options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+}): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 构建查询字符串
+ */
+declare function buildQueryString(params: Record<string, any>): string;
+/**
+ * 解析URL查询参数
+ */
+declare function parseQueryString(url: string): Record<string, string>;
+/**
+ * 计算上传进度
+ */
+declare function calculateProgress(uploadedBytes: number, totalBytes: number): number;
+/**
+ * 计算上传速度
+ */
+declare function calculateSpeed(uploadedBytes: number, elapsedTime: number): number;
+/**
+ * 计算剩余时间
+ */
+declare function calculateRemainingTime(uploadedBytes: number, totalBytes: number, speed: number): number;
+/**
+ * 创建文件错误对象
+ */
+declare function createFileError(code: string, message: string, details?: Record<string, any>): {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+    timestamp: Date;
+};
+/**
+ * 格式化错误消息
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * 读取文件为Base64
+ */
+declare function readFileAsBase64(file: File): Promise<string>;
+/**
+ * 读取文件为ArrayBuffer
+ */
+declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;
+/**
+ * 读取文件为文本
+ */
+declare function readFileAsText(file: File, encoding?: string): Promise<string>;
+
+export { ALL_SUPPORTED_MIME_TYPES, API_BASE_PATH, API_ENDPOINTS, AUDIO_EXTENSIONS, AUDIO_MIME_TYPES, type AccessPermission, type BatchOperationResult, CDNProviderError, type CDNType, DEFAULT_CHUNK_SIZE, DEFAULT_MAX_AUDIO_SIZE, DEFAULT_MAX_DOCUMENT_SIZE, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_IMAGE_SIZE, DEFAULT_MAX_VIDEO_SIZE, DEFAULT_PAGE_SIZE, DEFAULT_REQUEST_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, DOCUMENT_EXTENSIONS, DOCUMENT_MIME_TYPES, ERROR_CODES, type FileEvent, type FileEventListener, type FileEventType, type FileMetadata, FileProcessingError, type FileQueryOptions, FileServiceError, FileUploadError, IMAGE_EXTENSIONS, IMAGE_MIME_TYPES, type PaginatedResult, type ProcessingOptions, type ProcessorType, StorageProviderError, type StorageType, UNIVERSAL_FILE_NAME, UNIVERSAL_FILE_VERSION, UniversalFileClient, type UniversalFileClientConfig, type UploadFileInfo, type UploadProgress, type UploadResult, type UploadStatus, VIDEO_EXTENSIONS, VIDEO_MIME_TYPES, buildQueryString, calculateProgress, calculateRemainingTime, calculateSpeed, createFileClient, createFileError, formatErrorMessage, formatFileSize, generateStoragePath, generateUniqueFileName, getFileCategory, getFileExtension, getMimeTypeFromFileName, isAudioFile, isDocumentFile, isImageFile, isMimeTypeSupported, isVideoFile, parseFileSize, parseQueryString, parseStoragePath, readFileAsArrayBuffer, readFileAsBase64, readFileAsText, sanitizeFileName, universalFileClient, validateFile, validateFileName, validateFileSize, validateFileType };