T Comm

Appearance

引入 ​

ts
import {
  collectFilesSync,
  parseCommentJson,
  readCommentJson,
  mkDirsSync,
  copyDir,
  deleteFolder,
  rmEmptyDir,
  deleteFolderRecursive,
  copyFile,
  traverseFolder,
  readJsonLog,
  getJsonLogDir,
  saveJsonToLog,
  saveJsonToLogMore,
  getJsonFromLog,
  getFileName,
  readJson,
  writeFileSync,
  readFileSync,
  getLocalFileHash,
  getLocalFileMd5,
  getLocalFileSize
} from 't-comm';

// 不支持 tree-shaking 的项目
import {
  collectFilesSync,
  parseCommentJson,
  readCommentJson,
  mkDirsSync,
  copyDir,
  deleteFolder,
  rmEmptyDir,
  deleteFolderRecursive,
  copyFile,
  traverseFolder,
  readJsonLog,
  getJsonLogDir,
  saveJsonToLog,
  saveJsonToLogMore,
  getJsonFromLog,
  getFileName,
  readJson,
  writeFileSync,
  readFileSync,
  getLocalFileHash,
  getLocalFileMd5,
  getLocalFileSize
} from 't-comm/lib/fs/index';

// 只支持 ESM 的项目
import {
  collectFilesSync,
  parseCommentJson,
  readCommentJson,
  mkDirsSync,
  copyDir,
  deleteFolder,
  rmEmptyDir,
  deleteFolderRecursive,
  copyFile,
  traverseFolder,
  readJsonLog,
  getJsonLogDir,
  saveJsonToLog,
  saveJsonToLogMore,
  getJsonFromLog,
  getFileName,
  readJson,
  writeFileSync,
  readFileSync,
  getLocalFileHash,
  getLocalFileMd5,
  getLocalFileSize
} from 't-comm/es/fs/index';

collectFilesSync(dirPath, [fileList]) ​

描述：同步递归收集目录下所有文件路径 递归遍历指定目录，收集所有文件的绝对路径到数组中

参数：

参数名类型默认值描述
dirPathstring目录路径
[fileList]Array<string>[]用于累积结果的数组（可选，递归内部使用）

返回: Array<string>

所有文件的绝对路径数组

示例

ts
const files = collectFilesSync('/path/to/dir');
// ['/path/to/dir/a.ts', '/path/to/dir/sub/b.ts', ...]

parseCommentJson(content) ​

描述：解析带注释的 json 文件

参数：

参数名描述
content原始文件内容

返回: json数据

示例

ts
const text = `{
  // 这是一个注释
  "name": "foo",
  "version": "1.0.0" // 末尾注释
}`;
parseCommentJson(text); // { name: 'foo', version: '1.0.0' }

readCommentJson(file) ​

描述：获取带注释的 json 文件内容

参数：

参数名描述
file文件路径

返回: json数据

示例

ts
// tsconfig.json 中可能含有 // 注释
const config = readCommentJson('./tsconfig.json');
console.log(config.compilerOptions);

mkDirsSync(dirname) ​

描述：递归创建目录（同步方法） 如果目录已存在则直接返回，否则递归创建父目录

参数：

参数名描述
dirname要创建的目录路径

返回: 创建成功返回 true

示例

ts
mkDirsSync('/path/to/new/directory');

copyDir(src, dist, callback) ​

描述：拷贝目录以及子文件 递归复制整个目录结构，包括所有子目录和文件

参数：

参数名描述
src源目录路径
dist目标目录路径
callback可选的回调函数，复制完成后执行

示例

ts
copyDir('/source/path', '/target/path', () => {
  console.log('复制完成');
});

deleteFolder(tPath) ​

描述：删除目录及其所有内容 递归删除目录下的所有文件和子目录

参数：

参数名描述
tPath要删除的目录路径

示例

ts
deleteFolder('/path/to/folder');

rmEmptyDir(tPath, level) ​

描述：递归删除空目录 从指定路径开始，递归删除所有空目录（不删除包含文件的目录）

参数：

参数名描述
tPath要检查和删除的目录路径
level当前递归层级，默认为 0（根层级不会被删除）

示例

ts
rmEmptyDir('/path/to/check');

deleteFolderRecursive(path, options) ​

描述：递归删除文件夹（可配置是否删除文件） 递归遍历目录，根据配置决定是否删除文件，并删除空目录

参数：

参数名描述
path要处理的目录路径
options配置选项
options.deleteFile是否删除文件，默认为 false
options.log是否输出日志，默认为 false

示例

ts
// 只删除空目录
deleteFolderRecursive('/path/to/folder');

// 删除所有文件和目录
deleteFolderRecursive('/path/to/folder', { deleteFile: true, log: true });

copyFile(from, to) ​

描述：拷贝单个文件 将文件从源路径复制到目标路径

参数：

参数名描述
from源文件路径
to目标文件路径

返回: 写入操作的结果

示例

ts
copyFile('/source/file.txt', '/target/file.txt');

traverseFolder(cb, tPath) ​

描述：递归遍历文件夹，并对每个文件执行回调函数 遍历目录树，对每个文件（非目录）执行指定的回调函数

参数：

参数名描述
cb回调函数，接收文件路径作为参数
tPath要遍历的文件夹或文件路径

示例

ts
traverseFolder((filePath) => {
  console.log('处理文件:', filePath);
}, '/path/to/folder');

readJsonLog(file, defaultContent) ​

描述：从日志目录读取 JSON 文件 读取 ./log 目录下的 JSON 文件内容

参数：

参数名描述
file文件名（相对于 log 目录）
defaultContent文件不存在时返回的默认内容，默认为 ''

返回: JSON 文件内容字符串

示例

ts
const content = readJsonLog('data.json', '[]');

getJsonLogDir() ​

描述：获取 JSON 日志目录的绝对路径

参数：

返回: 日志目录的绝对路径

示例

ts
const logDir = getJsonLogDir();
console.log(logDir); // /path/to/project/log

saveJsonToLog(content, file, needLog) ​

描述：将 JSON 对象保存到日志文件 将对象序列化为 JSON 并保存到 ./log 目录下

参数：

参数名描述
content要保存的对象内容
file文件名（相对于 log 目录）
needLog是否需要保存日志，默认为 true

示例

ts
saveJsonToLog({ status: 'success', data: [1, 2, 3] }, 'result.json');

saveJsonToLogMore(content, file, options) ​

描述：将内容追加保存到日志文件（支持保留历史记录） 以数组形式保存多条日志记录，每条记录包含时间戳和数据，支持限制最大记录数

参数：

参数名描述
content要保存的内容
file文件名（相对于 log 目录）
options配置选项
options.needLog是否需要保存日志，默认为 true
options.max最大保留记录数，默认为 10

示例

ts
saveJsonToLogMore({ action: 'upload', status: 'success' }, 'history.json', {
  needLog: true,
  max: 20
});

getJsonFromLog(file) ​

描述：从日志目录读取并解析 JSON 文件 读取 ./log 目录下的 JSON 文件并解析为对象

参数：

参数名描述
file文件名（相对于 log 目录）

返回: 解析后的 JSON 对象，解析失败或文件不存在时返回空对象

示例

ts
const data = getJsonFromLog('config.json');
console.log(data);

getFileName(file) ​

描述：从文件路径中提取文件名（不含扩展名）

参数：

参数名描述
file文件路径

返回: 不含扩展名的文件名

示例

ts
const name = getFileName('/path/to/file.txt');
console.log(name); // 'file'

readJson(content, file) ​

描述：解析 JSON 字符串为对象 安全地解析 JSON 字符串，解析失败时输出错误信息并返回空对象

参数：

参数名描述
contentJSON 字符串内容
file文件路径（用于错误日志）

返回: 解析后的对象，解析失败时返回空对象

示例

ts
const data = readJson('{"name":"test"}', 'config.json');
console.log(data); // { name: 'test' }

writeFileSync(file, data, [isJson]) ​

描述：写入文件

参数：

参数名类型描述
filestring文件地址
dataany文件数据
[isJson]boolean是否需要 json 序列化

示例

ts
writeFileSync('a', 'b.txt', false);

writeFileSync({ a: 1 }, 'b.json', true);

readFileSync(file, [isJson]) ​

描述：读取文件

参数：

参数名类型描述
filestring文件地址
[isJson]boolean是否需要 json 反序列化

返回: any

文件内容

示例

ts
readFileSync('b.txt', false);

readFileSync('b.json', true);

getLocalFileHash(filePath, [algorithm]) ​

描述：计算本地文件的哈希值

参数：

参数名类型默认值描述
filePathstring文件路径
[algorithm]&#x27;md5&#x27; | &#x27;sha1&#x27; | &#x27;sha256&#x27;&#x27;md5&#x27;哈希算法

返回: string | null

哈希值（hex 字符串）；文件不存在或读取失败时返回 null

示例

ts
const md5 = getLocalFileHash('/path/to/file');
const sha256 = getLocalFileHash('/path/to/file', 'sha256');

getLocalFileMd5(filePath) ​

描述：计算本地文件的 MD5

参数：

参数名类型描述
filePathstring文件路径

返回: string | null

MD5 值（hex 字符串）；文件不存在或读取失败时返回 null

示例

ts
const md5 = getLocalFileMd5('/path/to/file');

getLocalFileSize(filePath) ​

描述：获取本地文件大小（字节数）

参数：

参数名类型描述
filePathstring文件路径

返回: number | null

文件大小（字节）；文件不存在或读取失败时返回 null

示例

ts
const size = getLocalFileSize('/path/to/file');