文件操作帮助类

介绍

文件的一些操作

/**
 * 类似node_module方式读取文件数据
 * @param {string} filename 文件名或者部分路径
 * @param {({ encoding?: null | undefined; flag?: string | undefined; } | null)} [options] 见readFileSync
 * @return {*}  {Buffer}
 */
export declare const requireFileSync: (filename: string, options?: {
    encoding?: null | undefined;
    flag?: string | undefined;
} | null) => Buffer;
/**
 * 同步创建文件夹，可递归创建
 * @param {string} dir 需要创建的文件夹路径
 * @return {*}  {boolean}
 */
export declare const mkdirSync: (dir: string) => boolean;
/**
 * 创建空白文件
 * @param {String} file 文件路径
 */
export declare const mkfileSync: (file: string) => void;
/**
 * 递归删除文件夹
 * @param {string} path 要删除的目录
 */
export declare const rmdirSync: (path: string) => void;
/**
 * 递归获取文件列表
 * @param {string} dir 要读取的文件目录
 * @param {("throw" | "ignore" | "warn")} [handling] 读取目录异常（比如无权限）时的处理方式
 * - throw：抛出异常，调用方需要自己trycatch处理，默认方式
 * - ignore：忽略这些文件，返回一个正常读取到的文件列表，此时返回值为 string[]
 * - warn：将异常的目录同步返回，此时返回值为 { success: string[], error: { dir: string, message: any }[]
 * @return {(string[] | { success: string[], error: { dir: string, message: any }[] })} 返回的数据
 * - ignore时返回string[]，warn时返回{ success: string[], error: { dir: string, message: any }[] }
 * - success：正常读取到的文件列表，同ignore时的返回值
 * - error.dir：没有权限或读取失败的目录地址
 * - error.message：通常是一个Error对象，表示了该目录读取时引发的异常信息
 */
export declare const findfilesSync: (dir: string, handling?: "throw" | "ignore" | "warn") => string[] | {
    success: string[];
    error: {
        dir: string;
        message: any;
    }[];
};
/**
 * 获取文件MD5值
 * @param {string} file 文件地址
 * @return {*}  {Promise<string>} 文件的md5
 */
export declare const md5: (file: string) => Promise<string>;
/**
 * 压缩/归档
 * @param {(string | string[])} src 要压缩的原始文件或文件列表，文件夹或者文件列表，如果是文件夹会自动递归内部所有文件
 * @param {string} dest 压缩后的文件存放路径
 * @param {string} [password] 加密压缩的密码
 * @return {*}  {Promise<void>}
 */
export declare const compressing: (src: string | string[], dest: string, password?: string) => Promise<void>;
/**
 * 解压缩
 * @param {string} src 要解压缩的文件
 * @param {string} dest 解压缩后的文件或文件夹存放路径
 * @param {string} [password] 压缩文件的密码
 * @return {*}  {Promise<void>}
 */
export declare const uncompressing: (src: string, dest: string, password?: string) => Promise<void>;
/**
 * 打开zip文件
 * @param {string} src zip文件路径
 * @param {string} [filename] zip内部某个文件名称
 * @param {string} [password] 加密压缩的密码
 * @return {*}  {(Promise<string[] | Stream>)} 当传filename时，返回该文件的流，否则返回zip文件中的所有文件名列表
 */
export declare const openZip: (src: string, filename?: string, password?: string) => Promise<string[] | Stream>;
/**
 * 大文件复制
 * @param {string} src 要复制的文件
 * @param {string} dest 复制的目标文件地址
 * @return {*}  {Promise<void>}
 */
export declare const copyLargeFile: (src: string, dest: string) => Promise<void>;
/**
 * 逐行读取文件
 * @param {string} src 要读取的文件
 * @return {*}  {Promise<string[]>}
 */
export declare const readLine: (src: string) => Promise<string[]>;
/**
 * 复制文件夹
 * @param {string} src 源地址
 * @param {string} dest 目标地址
 * @param {boolean} [cover] 是否覆盖已有文件
 * @return {*}  {Promise<boolean>}
 */
export declare const copyFolder: (src: string, dest: string, cover?: boolean) => Promise<boolean>;
/**
 * 深度复制文件夹，与copyFolder主要区别在于判断是否存在是内部单个文件而非整个目录
 * @param {string} src 源地址
 * @param {string} dest 目标地址
 * @param {boolean} [cover] 是否覆盖已有文件
 * @return {*}  {Promise<boolean>}
*/
deepCopyFolder: (src: string, dest: string, cover?: boolean) => Promise<boolean>;
/**
 * 移动文件夹
 * @param {string} src 源地址
 * @param {string} dest 目标地址
 * @param {Boolean} cover 是否覆盖已有文件
 * @return {*}  {Promise<boolean>}
 */
export declare const moveFolder: (src: string, dest: string, cover?: boolean) => Promise<boolean>;
/**
 * 获取文件的文件类型
 * @param {string} src 文件地址
 * @param {number} [chunkLength] 读取文件前多少字节（只要大于等于幻数所在的字节数即可，如果不确定可以不传）
 * @return {*}  {Promise<{ ext: string, mime: string }>} 文件扩展名及文件类型
 */
export declare const fileType: (src: string, chunkLength?: number) => Promise<{
    ext: string;
    mime: string;
}>;
/**
 * 将一个字符串或二进制数据写入文件
 * @param {string} dest 目标文件
 * @param {(string | Buffer)} data 需要写入的数据
 * @param {number} [blockSize] 每次写入的块大小，单位字节，默认10M
 * @return {*}  {Promise<void>}
 */
export declare const writeFile: (dest: string, data: string | Buffer, blockSize?: number) => Promise<void>;
/**
 * 读取文件
 * @param {string} src 待读取的文件地址
 * @return {*}  {Promise<string>}
 */
export declare const readFile: (src: string) => Promise<string>;

/**
 * 比较2个文件是否一致
 * @param {string} src1 文件1
 * @param {string} src2 文件2
 * @param {number} [block] 文件切片大小，单位字节，默认100*1024*1024，即100MB
 * @return {*}  {Promise<boolean>}
 */
export declare const congruence: (src1: string, src2: string, block?: number) => Promise<boolean>;
/**
 * 将文件按大小进行分片
 * @param {string} src 需要分片的文件
 * @param {number} [block] 每一个分片的大小，单位字节，默认1024（即1kb）
 * @return {number[]} 分片后的缓冲区偏移量起始位置
 */
export declare const slice: (src: string, block?: number) => number[];
/**
 * 读取文件的某个部分，并计算出md5
 * @param {string} src 文件
 * @param {number} offset 偏移量，单位字节
 * @param {number} block 读取的块大小，单位字节
 * @return {*}  {Promise<string>}
 */
export declare const readFileBlockMd5: (src: string, offset: number, block: number) => Promise<string>;
/**
 * 读取文件的指定分片md5信息
 * @param {string} src 文件
 * @param {number} block 分片的块大小，单位字节，默认100*1024*1024，即100MB
 * @return {Promise<string[]>} 每一块分片的MD5
 */
export declare const readFileSliceMd5: (src: string, block?: number) => Promise<string[]>;

/**
 * 获取文件的唯一标识符
 * - 修改文件或移动/复制文件，都将改变其标识符，哪怕是复制或移动到同一个位置
 * @param {string} src 文件路径
 * @return {string}
 */
export declare const fileGuid: (src: string) => string;

/**
 * 从文件MD5缓存文件中读取文件的MD5值
 * - 如果不存在缓存文件或文件变化，将重新生成缓存文件
 * @param {string} fileSrc 原始文件绝对路径
 * @param {string} cacheSrc 缓存文件绝对路径
 * @return {Promise<string>} 文件的MD5值
 */
export declare const readFileMd5FromCache: (fileSrc: string, cacheSrc: string) => Promise<string>;

/**
 * 从文件MD5缓存文件中比较2个文件是否一致
 * - 如果不存在缓存文件或文件变化，将重新生成缓存文件
 * - 第一次比较会自动在指定位置生成缓存文件，在不改变2个文件的情况下，下次比较会直接读取缓存文件进行比较，加快大文件比较的速度
 * - 当移动或修改了某一个文件，会自动重建缓存文件元数据信息
 * @param {string} fileSrc1 原始文件1绝对路径
 * @param {string} fileSrc2 原始文件2绝对路径
 * @param {string} cacheSrc 缓存文件绝对路径
 * @return {Promise<boolean>} 是否一致
 */
export declare const congruenceFromCache: (fileSrc1: string, fileSrc2: string, cacheSrc: string) => Promise<boolean>;

版本迭代记录

2025-05-13 v2.5.1

• 优化读取目录文件列表函数，异常抛出对应的异常地址：{dir:string,message:string}[]。

2025-05-12 v2.5.0

• 新增"congruenceFromCache"函数，用于大文件比较的元数据缓存创建，加速下次比较的速度（一般用于文件同步备份项目中，在占用大容量存储的原始文件和目标文件几乎不变时，效果尤为明显）。

2025-05-09 v2.4.1

• 新增"fileGuid"函数，用于获取文件的唯一标识，主要用于判断文件是否被改变，移动/复制/修改等任何操作都将改变文件的唯一标识，哪怕是复制或移动到同一个位置。
• 新增"readFileMd5FromCache"函数，获取文件缓存的md5值，注意：文件移动或复制后（哪怕是同一个位置）缓存也将失效，会自动生成新的缓存文件。

2025-05-08 v2.3.4

• 优化文件比较函数，防止大文件比较时大量占用CPU、内存、磁盘IO等资源。

2025-05-07 v2.3.3

• "findfilesSync"递归获取文件列表函数返回值修正为“string[]”。

2025-05-07 v2.3.2

• 修复已知Bug。

2025-04-29 v2.3.0

• 增加2个文件的一致性比较、文件分片、分片读取文件md5、读取某一块的md5这些函数。

2025-04-28 v2.2.0

• "findfilesSync"递归获取文件列表函数以兼容原先版本的扩展。

2025-04-25 v2.1.0

• 修复已知Bug。
• 增加深度复制目录的函数。

2025-04-11 v2.0.0

• 被移除后更名发布。

2025-03-21 v1.1.0

• 增加readFile，writeFile处理大文件读写。
• 将readLargeFile重命名成readLine。

2025-03-19 v1.0.0

• 摒弃以前的压缩函数。
• 全新的压缩文件操作帮助，并支持zip常规加密压缩或者只读取压缩文件中的部分文件数据等，详见compressing、uncompressing、openZip这3个全新的函数。
• 使用新的打包方式发布。

2024-05-18 v0.6.1

• 修复部分Bug

2024-03-22 v0.6.0

• 增加fileType函数，基于文件的MagicNumber判断文件的文件类型（修改文件后缀名或删除文件后缀名仍旧可以正确的判断出文件原有的文件类型）

2024-03-14 v0.5.0

• 添加文件夹复制和移动2个函数