@huyooo/file-explorer-core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+import { Stats } from 'node:fs';
+
+/**
+ * 文件类型枚举
+ */
+declare enum FileType {
+    FOLDER = "folder",
+    FILE = "file",
+    IMAGE = "image",
+    VIDEO = "video",
+    MUSIC = "music",
+    DOCUMENT = "document",
+    CODE = "code",
+    TEXT = "text",
+    ARCHIVE = "archive",
+    APPLICATION = "application",
+    UNKNOWN = "unknown"
+}
+/**
+ * 文件系统项
+ */
+interface FileItem {
+    /** 唯一标识（通常是完整路径） */
+    id: string;
+    /** 文件名 */
+    name: string;
+    /** 文件类型 */
+    type: FileType;
+    /** 文件大小（格式化后的字符串） */
+    size?: string;
+    /** 修改日期（格式化后的字符串） */
+    dateModified?: string;
+    /** 文件 URL（用于加载） */
+    url?: string;
+    /** 缩略图 URL */
+    thumbnailUrl?: string;
+    /** 子项（仅文件夹） */
+    children?: FileItem[];
+}
+/**
+ * 文件信息
+ */
+interface FileInfo {
+    path: string;
+    name: string;
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    extension?: string;
+}
+/**
+ * 操作结果
+ */
+interface OperationResult<T = void> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+/**
+ * 系统路径 ID
+ */
+type SystemPathId = 'desktop' | 'documents' | 'downloads' | 'pictures' | 'music' | 'videos' | 'applications' | 'home' | 'root';
+/**
+ * 平台适配器接口
+ * 用于处理平台特定的操作（如 Electron 的 shell.trashItem）
+ */
+interface PlatformAdapter {
+    /** 删除文件到回收站 */
+    trashItem?: (path: string) => Promise<void>;
+    /** 打开文件 */
+    openPath?: (path: string) => Promise<void>;
+    /** 使用指定应用打开 */
+    openWith?: (path: string, appPath: string) => Promise<void>;
+}
+/**
+ * 文件操作选项
+ */
+interface FileOperationOptions {
+    /** 平台适配器 */
+    adapter?: PlatformAdapter;
+    /** 是否自动重命名（当目标存在时） */
+    autoRename?: boolean;
+}
+
+/**
+ * 根据文件路径和状态获取文件类型
+ */
+declare function getFileType(filePath: string, stats: Stats): FileType;
+/**
+ * 判断是否为媒体文件
+ */
+declare function isMediaFile(type: FileType): boolean;
+/**
+ * 判断是否为可预览的文件
+ */
+declare function isPreviewable(type: FileType): boolean;
+
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 格式化日期
+ */
+declare function formatDate(date: Date): string;
+/**
+ * 格式化日期时间
+ */
+declare function formatDateTime(date: Date): string;
+
+/**
+ * URL 编码器（可由外部注入）
+ */
+type UrlEncoder = (filePath: string) => string;
+/**
+ * 读取目录配置
+ */
+interface ReadDirectoryOptions {
+    /** URL 编码器 */
+    urlEncoder?: UrlEncoder;
+    /** 是否包含隐藏文件 */
+    includeHidden?: boolean;
+    /** 缩略图 URL 获取器（同步获取缓存的缩略图，没有则返回 null 并异步生成） */
+    getThumbnailUrl?: (filePath: string) => Promise<string | null>;
+}
+/**
+ * 读取目录内容
+ */
+declare function readDirectory(dirPath: string, options?: ReadDirectoryOptions): Promise<FileItem[]>;
+/**
+ * 读取文件内容
+ */
+declare function readFileContent(filePath: string): Promise<string>;
+/**
+ * 读取图片为 Base64
+ */
+declare function readImageAsBase64(imagePath: string): Promise<{
+    success: boolean;
+    base64?: string;
+    mimeType?: string;
+    error?: string;
+}>;
+
+/**
+ * 写入文件内容
+ */
+declare function writeFileContent(filePath: string, content: string): Promise<OperationResult>;
+/**
+ * 创建文件夹（自动处理同名文件夹）
+ */
+declare function createFolder(folderPath: string): Promise<OperationResult<{
+    finalPath: string;
+}>>;
+/**
+ * 创建文件（自动处理同名文件）
+ */
+declare function createFile(filePath: string, content?: string): Promise<OperationResult<{
+    finalPath: string;
+}>>;
+
+/**
+ * 删除文件选项
+ */
+interface DeleteOptions {
+    /** 平台适配器（用于移到回收站） */
+    adapter?: PlatformAdapter;
+    /** 是否使用回收站（默认 true） */
+    useTrash?: boolean;
+    /** 删除后回调（用于清理缩略图等） */
+    onDeleted?: (path: string) => void;
+}
+/**
+ * 删除文件/文件夹
+ *
+ * 如果提供了 adapter.trashItem，则移到回收站
+ * 否则直接删除（危险操作）
+ */
+declare function deleteFiles(paths: string[], options?: DeleteOptions): Promise<OperationResult>;
+
+/**
+ * 重命名选项
+ */
+interface RenameOptions {
+    /** 重命名后回调 */
+    onRenamed?: (oldPath: string, newPath: string) => void;
+}
+/**
+ * 重命名文件/文件夹
+ */
+declare function renameFile(oldPath: string, newPath: string, options?: RenameOptions): Promise<OperationResult>;
+
+/**
+ * 复制文件到目标目录
+ */
+declare function copyFiles(sourcePaths: string[], targetDir: string): Promise<OperationResult<{
+    copiedPaths: string[];
+}>>;
+/**
+ * 移动文件到目标目录
+ */
+declare function moveFiles(sourcePaths: string[], targetDir: string): Promise<OperationResult<{
+    movedPaths: string[];
+}>>;
+
+/**
+ * 获取文件信息
+ */
+declare function getFileInfo(filePath: string): Promise<OperationResult<FileInfo>>;
+/**
+ * 检查文件/目录是否存在
+ */
+declare function exists(filePath: string): Promise<boolean>;
+/**
+ * 检查是否为目录
+ */
+declare function isDirectory(filePath: string): Promise<boolean>;
+
+/**
+ * 获取系统路径
+ */
+declare function getSystemPath(pathId: SystemPathId): string | null;
+/**
+ * 获取所有系统路径
+ */
+declare function getAllSystemPaths(): Record<SystemPathId, string | null>;
+/**
+ * 获取用户主目录
+ */
+declare function getHomeDirectory(): string;
+/**
+ * 获取当前平台
+ */
+declare function getPlatform(): NodeJS.Platform;
+
+/**
+ * 使用 fdir 快速搜索文件和文件夹
+ * fdir 可以在 1 秒内扫描 100 万个文件
+ *
+ * @param searchPath 搜索路径
+ * @param pattern 搜索模式（支持 * 通配符，忽略大小写）
+ * @param maxDepth 最大递归深度
+ */
+declare function searchFiles(searchPath: string, pattern?: string, maxDepth?: number): Promise<string[]>;
+/**
+ * 流式搜索文件（逐层搜索，边搜边返回）
+ *
+ * @param searchPath 搜索路径
+ * @param pattern 搜索模式
+ * @param onResults 找到结果时的回调
+ * @param maxResults 最大结果数
+ */
+declare function searchFilesStream(searchPath: string, pattern: string, onResults: (paths: string[], done: boolean) => void, maxResults?: number): Promise<void>;
+/**
+ * 同步搜索（用于小目录）
+ */
+declare function searchFilesSync(searchPath: string, pattern?: string, maxDepth?: number): string[];
+
+/**
+ * 计算文件的快速 hash（使用文件大小和修改时间）
+ * 这比计算完整文件 hash 快得多，适合用于缓存判断
+ */
+declare function getFileHash(filePath: string): Promise<string>;
+/**
+ * 批量计算文件 hash
+ */
+declare function getFileHashes(filePaths: string[]): Promise<Map<string, string>>;
+
+/**
+ * 剪贴板文件操作接口
+ * 由于 clipboard-files 是 native 模块，由使用者在 Electron 主进程中注入
+ */
+interface ClipboardAdapter {
+    writeFiles: (paths: string[]) => void;
+    readFiles: () => string[];
+}
+/**
+ * 复制文件到剪贴板
+ */
+declare function copyFilesToClipboard(filePaths: string[], clipboard: ClipboardAdapter): Promise<OperationResult>;
+/**
+ * 从剪贴板读取文件路径
+ */
+declare function getClipboardFiles(clipboard: ClipboardAdapter): OperationResult<{
+    files: string[];
+}>;
+/**
+ * 粘贴文件到目标目录
+ */
+declare function pasteFiles(targetDir: string, sourcePaths: string[]): Promise<OperationResult<{
+    pastedPaths: string[];
+}>>;
+
+/**
+ * 应用程序图标获取（macOS）
+ *
+ * 纯 Node.js 实现，使用 sips 命令转换 icns 为 PNG
+ */
+/**
+ * 获取应用程序图标（仅 macOS）
+ *
+ * 使用 sips 命令将 .icns 转换为 PNG，返回 base64 data URL
+ */
+declare function getApplicationIcon(appPath: string): Promise<string | null>;
+
+/**
+ * 缩略图数据库接口
+ */
+interface ThumbnailDatabase {
+    /** 获取缓存目录 */
+    getCacheDir(): string;
+    /** 快速查询缩略图（只用路径和修改时间） */
+    getThumbnailPathFast(filePath: string, mtime: number): string | null;
+    /** 获取缩略图路径（如果缓存有效） */
+    getThumbnailPath(filePath: string, fileHash: string, mtime: number): string | null;
+    /** 保存缩略图信息 */
+    saveThumbnail(filePath: string, fileHash: string, mtime: number, thumbnailPath: string): void;
+    /** 删除缩略图记录 */
+    deleteThumbnail(filePath: string): void;
+    /** 清理旧缩略图 */
+    cleanupOldThumbnails(): void;
+}
+/**
+ * 图片处理器接口
+ */
+interface ImageProcessor {
+    /** 缩放图片 */
+    resize(filePath: string, outputPath: string, size: number): Promise<void>;
+}
+/**
+ * 视频处理器接口
+ */
+interface VideoProcessor {
+    /** 截取视频帧 */
+    screenshot(filePath: string, outputPath: string, timestamp: string, size: string): Promise<void>;
+}
+/**
+ * 缩略图服务配置
+ */
+interface ThumbnailServiceOptions {
+    /** 数据库实例 */
+    database: ThumbnailDatabase;
+    /** 图片处理器（可选） */
+    imageProcessor?: ImageProcessor;
+    /** 视频处理器（可选） */
+    videoProcessor?: VideoProcessor;
+    /** URL 编码器（将本地路径转为 URL） */
+    urlEncoder?: (filePath: string) => string;
+    /** 应用图标获取器（macOS） */
+    getApplicationIcon?: (appPath: string) => Promise<string | null>;
+}
+
+/**
+ * 缩略图服务
+ */
+declare class ThumbnailService {
+    private database;
+    private imageProcessor;
+    private videoProcessor;
+    private urlEncoder;
+    private getApplicationIcon;
+    constructor(options: ThumbnailServiceOptions);
+    /**
+     * 获取缓存的缩略图 URL（不生成新的）
+     */
+    getCachedThumbnailUrl(filePath: string): Promise<string | null>;
+    /**
+     * 获取缩略图 URL（如果没有缓存则生成）
+     */
+    getThumbnailUrl(filePath: string): Promise<string | null>;
+    /**
+     * 生成缩略图
+     */
+    generateThumbnail(filePath: string, fileHash: string, mtime: number): Promise<string | null>;
+    /**
+     * 批量生成缩略图
+     */
+    generateThumbnailsBatch(files: Array<{
+        path: string;
+        hash: string;
+        mtime: number;
+    }>): Promise<void>;
+    /**
+     * 删除缩略图
+     */
+    deleteThumbnail(filePath: string): void;
+    /**
+     * 清理旧缩略图
+     */
+    cleanupOldThumbnails(): void;
+}
+/**
+ * 初始化缩略图服务
+ */
+declare function initThumbnailService(options: ThumbnailServiceOptions): ThumbnailService;
+/**
+ * 获取缩略图服务实例
+ */
+declare function getThumbnailService(): ThumbnailService | null;
+
+/**
+ * SQLite 缩略图数据库实现
+ *
+ * 需要安装 better-sqlite3：npm install better-sqlite3
+ */
+
+/**
+ * SQLite 缩略图数据库实现
+ */
+declare class SqliteThumbnailDatabase implements ThumbnailDatabase {
+    private db;
+    private cacheDir;
+    constructor(userDataPath: string);
+    /**
+     * 初始化数据库
+     */
+    init(): void;
+    getCacheDir(): string;
+    /**
+     * 快速查询缩略图（用路径和修改时间，不需要哈希）
+     * 比计算文件哈希快很多
+     */
+    getThumbnailPathFast(filePath: string, mtime: number): string | null;
+    getThumbnailPath(filePath: string, fileHash: string, mtime: number): string | null;
+    saveThumbnail(filePath: string, fileHash: string, mtime: number, thumbnailPath: string): void;
+    deleteThumbnail(filePath: string): void;
+    cleanupOldThumbnails(): void;
+    close(): void;
+}
+/**
+ * 创建 SQLite 缩略图数据库
+ */
+declare function createSqliteThumbnailDatabase(userDataPath: string): SqliteThumbnailDatabase;
+/**
+ * 获取缩略图数据库实例
+ */
+declare function getSqliteThumbnailDatabase(): SqliteThumbnailDatabase | null;
+
+/**
+ * 缩略图处理器工厂函数
+ *
+ * 需要安装：
+ * - sharp: npm install sharp
+ * - ffmpeg-static: npm install ffmpeg-static
+ */
+
+/**
+ * Sharp 类型定义（宽松类型，兼容 sharp 模块）
+ */
+interface SharpInstance {
+    resize(width: number, height: number, options?: {
+        fit?: string;
+        withoutEnlargement?: boolean;
+    }): SharpInstance;
+    jpeg(options?: {
+        quality?: number;
+    }): SharpInstance;
+    toFile(outputPath: string): Promise<unknown>;
+}
+type SharpModule = (input: string, options?: any) => SharpInstance;
+/**
+ * 创建 Sharp 图片处理器
+ *
+ * @example
+ * ```ts
+ * import sharp from 'sharp';
+ * import { createSharpImageProcessor } from '@huyooo/file-explorer-core';
+ *
+ * const imageProcessor = createSharpImageProcessor(sharp);
+ * ```
+ */
+declare function createSharpImageProcessor(sharp: SharpModule): ImageProcessor;
+/**
+ * 创建 FFmpeg 视频处理器（使用 child_process 直接调用 ffmpeg）
+ *
+ * @param ffmpegPath - ffmpeg 可执行文件路径（来自 ffmpeg-static）
+ *
+ * @example
+ * ```ts
+ * import ffmpegStatic from 'ffmpeg-static';
+ * import { createFfmpegVideoProcessor } from '@huyooo/file-explorer-core';
+ *
+ * const videoProcessor = ffmpegStatic
+ *   ? createFfmpegVideoProcessor(ffmpegStatic)
+ *   : undefined;
+ * ```
+ */
+declare function createFfmpegVideoProcessor(ffmpegPath: string): VideoProcessor;
+
+export { type ClipboardAdapter, type DeleteOptions, type FileInfo, type FileItem, type FileOperationOptions, FileType, type ImageProcessor, type OperationResult, type PlatformAdapter, type ReadDirectoryOptions, type RenameOptions, SqliteThumbnailDatabase, type SystemPathId, type ThumbnailDatabase, ThumbnailService, type ThumbnailServiceOptions, type UrlEncoder, type VideoProcessor, copyFiles, copyFilesToClipboard, createFfmpegVideoProcessor, createFile, createFolder, createSharpImageProcessor, createSqliteThumbnailDatabase, deleteFiles, exists, formatDate, formatDateTime, formatFileSize, getAllSystemPaths, getApplicationIcon, getClipboardFiles, getFileHash, getFileHashes, getFileInfo, getFileType, getHomeDirectory, getPlatform, getSqliteThumbnailDatabase, getSystemPath, getThumbnailService, initThumbnailService, isDirectory, isMediaFile, isPreviewable, moveFiles, pasteFiles, readDirectory, readFileContent, readImageAsBase64, renameFile, searchFiles, searchFilesStream, searchFilesSync, writeFileContent };