@yaohaixiao/renames.js 0.0.1

package/lib/read-list.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+
+import getExtension from './utils/get-extension.js';
+import isFileExists from './utils/is-file-exists.js';
+import readFile from './utils/read-file.js';
+import showWarningLog from './utils/show-warning-log.js';
+
+// 辅助函数：过滤文件列表中的空值
+const filter = (list) => list.filter((item) => item !== '' && item !== null);
+
+/**
+ * # 同步读取文件名列表文件中的文件名数据，返回文件名数组
+ *
+ * @function readList
+ * @param {string} listPath - 文件名列表文件路径
+ * @param {string} [prop=''] - 可选，当前读取的 .json 文件是 JSON 对象格式时，指定当局去的对象属性名.
+ *   Default is `''`
+ * @returns {Array} - 返回读取列表文件的数组数据，文件不存在则返回 false
+ */
+const readList = (listPath, prop = '') => {
+  const { resolve } = path;
+  const { parse } = JSON;
+  // 解析绝对路径（避免相对路径混乱）
+  const finalListPath = resolve(listPath);
+  let items = [];
+
+  // 检测文件是否存在
+  if (!isFileExists(finalListPath)) {
+    showWarningLog('跳过', finalListPath, '文件不存在或已被删除。');
+    return items;
+  }
+
+  // 同步读取文件（utf8 编码直接返回字符串，不加编码返回 Buffer）
+  const content = readFile(finalListPath);
+  const extname = getExtension(finalListPath).toLowerCase();
+  // 按行分割（兼容 Windows \r\n 和 Linux \n 换行符） split(/\r?\n/) 匹配两种换行符，filter(Boolean) 过滤空行（可选）
+  const pattern = /\r?\n/;
+  const { isArray } = Array;
+
+  switch (extname) {
+    case '.txt': {
+      items = content.split(pattern).filter(Boolean);
+      break;
+    }
+    case '.json': {
+      items = parse(content);
+
+      // 读取 JSON 数组数据
+      if (isArray(items)) {
+        items = filter(items);
+      } else if (prop && items[prop]) {
+        // 读取 JSON 对象的某个属性值，且该属性值是数组格式
+        if (isArray(items[prop])) {
+          items = filter(items[prop]);
+        } else {
+          items = [];
+          showWarningLog(
+            '警告',
+            `${finalListPath} 中JSON对象的 ${prop}`,
+            '属性不是数组格式数据。',
+          );
+        }
+      } else {
+        items = [];
+        showWarningLog(
+          '警告',
+          `${finalListPath} 中的数据`,
+          '不是JSON数组格式。',
+        );
+      }
+
+      break;
+    }
+    default: {
+      showWarningLog(
+        '警告',
+        '仅支持 .txt 和 .json',
+        '格式文件的数据分析读取。',
+      );
+      break;
+    }
+  }
+
+  return items;
+};
+
+export default readList;

package/lib/utils/get-basename.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+
+import getExtension from './get-extension.js';
+
+/**
+ * # 获取不含扩展名的文件名
+ *
+ * @function getBasename
+ * @param {string} filename - 文件名（路径）字符串
+ * @returns {string} - 返回文件名中去掉扩展名部分的字符串
+ */
+const getBasename = (filename) => {
+  const extname = getExtension(filename);
+
+  return path.basename(filename, extname);
+};
+
+export default getBasename;

package/lib/utils/get-extension.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+
+/**
+ * # 获取扩展名（含.）
+ *
+ * @function getExtension
+ * @param {string} filename - 文件名（路径）字符串
+ * @returns {string} - 返回文件名中扩展名部分的字符串，例如：'.jpg'
+ */
+const getExtension = (filename) => {
+  const extname = path.extname(filename);
+
+  if (!extname) {
+    return filename;
+  }
+
+  return extname;
+};
+
+export default getExtension;

package/lib/utils/is-empty-object.js

@@ -0,0 +1,23 @@
+/**
+ * # 判断一个值是否为空对象（纯对象 + 无自身可枚举属性）
+ *
+ * @function isEmptyObject
+ * @param {object} val - 要检测的值
+ * @returns {boolean} - 是为空对象返回 true，否则返回 false
+ */
+const isEmptyObject = (val) => {
+  // 先判断是否为纯对象（排除 null、数组、函数、基本类型等）
+  if (typeof val !== 'object' || val === null) {
+    return false;
+  }
+
+  // 判断是否为空数组
+  if (Array.isArray(val) && val.length === 0) {
+    return true;
+  }
+
+  // 判断是否有自身可枚举属性
+  return Object.keys(val).length === 0;
+};
+
+export default isEmptyObject;

package/lib/utils/is-file-exists.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * # 同步检测文件是否存在
+ *
+ * @function isFileExists
+ * @param {string} filePath - 检测的文件路径
+ * @param {string} [basePath=''] - 可选，基础路径。. Default is `''`
+ * @returns {boolean} - 文件存在返回 true，否则返回 false
+ */
+const isFileExists = (filePath = '', basePath = '') => {
+  const { resolve } = path;
+
+  if (!filePath) {
+    return false;
+  }
+
+  const finalFilePath = basePath
+    ? resolve(basePath, filePath)
+    : resolve(filePath);
+
+  return fs.existsSync(finalFilePath);
+};
+
+export default isFileExists;

package/lib/utils/is-function.js

@@ -0,0 +1,29 @@
+/**
+ * # 判断一个值是否为函数（兼容所有函数类型）
+ *
+ * @function isFunction
+ * @param {Function} val - 要判断的值
+ * @returns {boolean} - 返回是否为函数的检测结果
+ */
+const isFunction = (val) => {
+  // 基础判断：排除 null/undefined/非对象类型
+  if (val == null || (typeof val !== 'function' && typeof val !== 'object')) {
+    return false;
+  }
+
+  /**
+   * 核心判断：通过原型链和内部属性区分函数与其他对象
+   *
+   * 1. 普通函数/箭头函数/异步函数/生成器函数：prototype 存在（箭头函数除外，但 typeof 为 function）
+   * 2. DOM 方法（如 document.createElement）：typeof 为 function
+   * 3. 类（class）：typeof 为 function，但实例化需要 new，仍属于函数类型
+   * 4. 排除其他对象（如数组、对象字面量等）
+   */
+  return (
+    // 处理某些特殊环境下 typeof 误判为 object 的函数（极少数情况）
+    typeof val === 'function' ||
+    Object.prototype.toString.call(val) === '[object Function]'
+  );
+};
+
+export default isFunction;

package/lib/utils/pad-start.js

@@ -0,0 +1,31 @@
+/**
+ * # 自定义 padStart 方法，在字符串开头填充字符至目标长度
+ *
+ * @function padStart
+ * @param {string | number} val - 原始字符串（需处理的字符串）
+ * @param {number | string} [length=2] - 可选，最终目标字符串长度. Default is `2`
+ * @param {string} [padString=' '] - 可选：填充字符. Default is `' '`
+ * @returns {string} - 返回填充后的字符串
+ */
+const padStart = (val, length = 2, padString = ' ') => {
+  // 类型转换：确保 val 是字符串（原生 padStart 会隐式转换）
+  const originalStr = String(val);
+  // 处理填充字符：默认空格，若为非字符串则转为字符串，空字符串则返回原串（无填充）
+  let [finalLength, padChar] = [length, padString];
+
+  // length 参数为字符串类型，则当作 padString 使用，此时默认 length = 2
+  if (typeof finalLength === 'string') {
+    padChar = length;
+    finalLength = 2;
+  }
+
+  if (padChar === '' || finalLength <= originalStr.length) {
+    // 处理目标长度：若目标长度 ≤ 原字符串长度，或者没有设置 pad 填充字符，直接返回原串
+    return originalStr;
+  }
+
+  // node 环境下已支持 String.prototype.padStart 原生方法
+  return originalStr.padStart(finalLength, padChar);
+};
+
+export default padStart;

package/lib/utils/pad-zero.js

@@ -0,0 +1,24 @@
+import padStart from './pad-start.js';
+
+/**
+ * # 数字/字符串补零（前置补0，确保指定长度）
+ *
+ * @function padZero
+ * @param {number | string} val - 要补零的数字或字符串（如 27、'27'）
+ * @param {number} [length=2] - 可选，目标总长度（如 3 → '027'，4 → '0027'）. Default is `2`
+ * @returns {string} - 返回补零后的字符串
+ */
+const padZero = (val, length = 2) => {
+  // 转换为字符串（处理数字/字符串输入）
+  const str = String(val);
+
+  // 验证目标长度（必须大于0，否则返回原字符串）
+  if (length <= 0 || str.length >= length) {
+    return str;
+  }
+
+  // 前置补0到目标长度（padStart(目标长度, 补位字符)）
+  return padStart(str, length, '0');
+};
+
+export default padZero;

package/lib/utils/read-dir.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import isFileExists from './is-file-exists.js';
+import isFunction from './is-function.js';
+import showWarningLog from './show-warning-log.js';
+
+/**
+ * # （同步）读取文件夹中的文件
+ *
+ * @function readDir
+ * @param {string} dirPath - 文件夹的路径
+ * @param {string | object | Function} [options='utf8'] - 可选，读取文件夹的配置参数. Default
+ *   is `'utf8'`
+ * @param {Function} [callback=null] - 可选，读取完数据后的处理函数. Default is `null`
+ * @returns {string[]} - 返回读取文件夹中的文件数组信息
+ */
+const readDir = (dirPath, options = 'utf8', callback = null) => {
+  const { readdirSync, lstatSync } = fs;
+  const { resolve } = path;
+  const finalDirPath = resolve(dirPath);
+  let files = [];
+  let afterRead = callback;
+
+  if (!isFileExists(finalDirPath)) {
+    showWarningLog('跳过', finalDirPath, '文件夹不存在或已被删除。');
+    return files;
+  }
+
+  const stats = lstatSync(finalDirPath);
+
+  if (!stats.isDirectory()) {
+    showWarningLog('跳过', finalDirPath, '不是有效的文件夹。');
+    return files;
+  }
+
+  const defaultOptions = {
+    // 显式指定 UTF-8 编码（默认值，可省略）
+    encoding: 'utf8',
+    withFileTypes: false,
+  };
+  let mergedOptions = {};
+
+  // options 作为 callback 函数
+  if (isFunction(options)) {
+    afterRead = options;
+    mergedOptions = {
+      ...defaultOptions,
+    };
+  } else {
+    mergedOptions = {
+      ...defaultOptions,
+      ...(typeof options === 'object' && options !== null ? options : {}),
+    };
+  }
+
+  const encodings = ['utf8', 'ascii', 'buffer', null];
+
+  // 若传入的 encoding 非法，回退到默认的 utf8
+  if (!encodings.includes(mergedOptions.encoding)) {
+    mergedOptions.encoding = defaultOptions.encoding;
+  }
+
+  files = readdirSync(finalDirPath, mergedOptions);
+
+  if (isFunction(afterRead)) {
+    afterRead(files);
+  }
+
+  return files;
+};
+
+export default readDir;

package/lib/utils/read-file.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import isFileExists from './is-file-exists.js';
+import isFunction from './is-function.js';
+import showWarningLog from './show-warning-log.js';
+
+/**
+ * # （同步）读取文本文件数据
+ *
+ * @function readFile
+ * @param {string} filePath - 读取文件的路径
+ * @param {object | string | Function} [options='utf8'] -
+ *   可选，读取文件的配置信息或者文件读取完成后的处理函数. Default is `'utf8'`
+ * @param {Function} [callback=null] - 可选，文件读取完成后的处理函数. Default is `null`
+ * @returns {Buffer | string} - 返回读取文件的文本字符串或者Buffer数据
+ */
+const readFile = (filePath, options = 'utf8', callback = null) => {
+  const { resolve } = path;
+  const finalFilePath = resolve(filePath);
+  const defaultOptions = {
+    encoding: 'utf8',
+    flag: 'r',
+  };
+  let finalOptions = {};
+  let content = '';
+  let afterRead = callback;
+
+  if (!isFileExists(finalFilePath)) {
+    showWarningLog('跳过', finalFilePath, '不存在或已被删除。');
+    return content;
+  }
+
+  if (isFunction(options)) {
+    afterRead = options;
+    finalOptions = { ...defaultOptions };
+  } else {
+    finalOptions =
+      typeof options === 'string'
+        ? {
+            ...defaultOptions,
+            encoding: options,
+          }
+        : { ...defaultOptions, ...options };
+  }
+
+  content = fs.readFileSync(finalFilePath, finalOptions);
+
+  if (isFunction(afterRead)) {
+    afterRead(content);
+  }
+
+  return content;
+};
+
+export default readFile;

package/lib/utils/remove-file.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import isFileExists from './is-file-exists.js';
+import isFunction from './is-function.js';
+import showWarningLog from './show-warning-log.js';
+
+/**
+ * # 同步删除指定文件或目录（支持递归删除目录内容）
+ *
+ * @function removeFile
+ * @param {string} filePath - 要删除的文件/目录路径（相对路径或绝对路径）
+ * @param {object | Function} [options={}] - 删除配置选项（可选，继承 fs.rmSync
+ *   的配置参数）或者执行完成后的回调函数. Default is `{}`
+ * @param {boolean} [options.recursive=true] - 可选，递归删除目录下的所有文件和子目录. Default is
+ *   `true`
+ * @param {boolean} [options.force=true] - 可选，忽略不存在的路径，避免抛出错误. Default is `true`
+ * @param {number} [options.maxRetries=0] - 可选，删除失败时的重试次数. Default is `0`
+ * @param {number} [options.retryDelay=100] - 可选，重试间隔时间（毫秒）. Default is `100`
+ * @param {Function} [callback=null] - 可选，执行完成后的回调函数. Default is `null`
+ * @returns {boolean} - 文件不存在时，返回 false，删除成功，返回 true.
+ */
+const removeFile = (filePath, options = {}, callback = null) => {
+  const { resolve } = path;
+  const finalPath = resolve(filePath);
+  const defaultOptions = {
+    recursive: true,
+    force: true,
+    maxRetries: 0,
+    retryDelay: 100,
+  };
+  let finalOptions = {};
+  let afterRemove = callback;
+
+  if (!isFileExists(finalPath)) {
+    showWarningLog('跳过', finalPath, '文件不存在或已被删除。');
+    return false;
+  }
+
+  // options 类型为函数时，options 作为 afterRemove 回调函数使用，则直接使用默认配置
+  if (isFunction(options)) {
+    afterRemove = options;
+    finalOptions = { ...defaultOptions };
+  } else {
+    finalOptions = {
+      ...defaultOptions,
+      ...(typeof options === 'object' && options !== null ? options : {}),
+    };
+  }
+
+  fs.rmSync(finalPath, finalOptions);
+
+  if (isFunction(afterRemove)) {
+    afterRemove(filePath);
+  }
+
+  return true;
+};
+
+export default removeFile;

package/lib/utils/rename.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+
+import chalk from 'chalk';
+
+import getBasename from './get-basename.js';
+import getExtension from './get-extension.js';
+import isFileExists from './is-file-exists.js';
+import isFunction from './is-function.js';
+import showWarningLog from './show-warning-log.js';
+
+/**
+ * # 重命名文件
+ *
+ * @function rename
+ * @param {string} oldFilePath - 原来的文件名
+ * @param {string} newFilePath - 新的文件名
+ * @param {boolean | Function} [force=false] - 可选，是否强制重命名. Default is `false`
+ * @param {Function} [callback=null] - 可选，读取完毕后的处理函数. Default is `null`
+ * @returns {boolean} - 数据不对或者文件不存在，返回 false，重命名成功，返回 true
+ */
+const rename = (oldFilePath, newFilePath, force = false, callback = null) => {
+  // 检测文件是否存在
+  if (!isFileExists(oldFilePath)) {
+    showWarningLog('跳过', oldFilePath, '文件不存在或已被删除。');
+    return false;
+  }
+
+  const oldFilename = getBasename(oldFilePath);
+  const oldExtname = getExtension(oldFilePath);
+
+  const newFilename = getBasename(newFilePath);
+  const newExtname = getExtension(newFilePath);
+
+  let afterRename = callback;
+  let isForce;
+
+  if (isFunction(force)) {
+    afterRename = force;
+  } else {
+    isForce = force;
+  }
+
+  // 避免重复命名（如果新文件名已存在并且未设置强制重命名，则跳过重命名）
+  if (
+    !isForce &&
+    ((oldFilename === newFilename && oldExtname === newExtname) ||
+      isFileExists(newFilePath))
+  ) {
+    showWarningLog(
+      '跳过',
+      `${oldFilename}${oldExtname}`,
+      '文件名已存在无需修改。',
+    );
+    return false;
+  }
+
+  // 执行重命名
+  fs.renameSync(oldFilePath, newFilePath);
+
+  console.log(
+    chalk.greenBright(`成功：`),
+    chalk.blue(`${oldFilename}${oldExtname}`),
+    chalk.blueBright(` → `),
+    chalk.green(`${newFilename}${newExtname}`),
+  );
+
+  if (isFunction(afterRename)) {
+    afterRename();
+  }
+
+  return true;
+};
+
+export default rename;

package/lib/utils/replace-index-chapter.js

@@ -0,0 +1,53 @@
+import getBasename from './get-basename.js';
+import isFunction from './is-function.js';
+import padZero from './pad-zero.js';
+import toIndexChapter from './to-index-chapter.js';
+
+/**
+ * # 替换文件名中的章节信息
+ *
+ * @function replaceIndexChapter
+ * @param {string} filename - 原始的文件名字符串
+ * @param {object | Function} [chapter] - 可选，过滤文件名中的索引编号的处理函数
+ * @param {string} chapter.name - 文件名中的整个索引编号的字符出，例如：第04章
+ * @param {string} chapter.index - 件名中的索引编号的字符，例如：04
+ * @param {number} chapter.number - 件名中的索引编号的数值，例如：4
+ * @param {number | boolean} [length=2] - 可选，自动填充索引编号的长度. Default is `2`
+ * @param {object} [options={}] - 可选，其他的格式化配置参数. Default is `{}`
+ * @param {string} [options.prefix='第'] - 可选，索引部分的前缀. Default is `'第'`
+ * @param {string} [options.suffix='集'] - 可选，索引部分的后缀. Default is `'集'`
+ * @param {string} [options.delimiter='：'] - 可选，用来拆分索引部分和正式名的分割符号. Default is
+ *   `'：'`
+ * @returns {string} - 返回替换了章节信息的文件名字符串
+ */
+const replaceIndexChapter = (filename, chapter, length = 2, options = {}) => {
+  const basename = getBasename(filename);
+
+  const { prefix = '第', suffix = '集', delimiter = '：' } = options;
+  let padZeroIndex = true;
+
+  // 关闭了自动填充索引编号
+  if (length === false) {
+    padZeroIndex = false;
+  }
+
+  if (!chapter) {
+    return basename;
+  }
+
+  const originChapter = isFunction(chapter) ? chapter(basename) : chapter;
+  const { index, number, name } = originChapter;
+  const indexChapter = toIndexChapter(
+    padZeroIndex ? padZero(number, length) : index,
+    false,
+    {
+      prefix,
+      suffix,
+      delimiter,
+    },
+  );
+
+  return basename.replace(name, indexChapter);
+};
+
+export default replaceIndexChapter;

package/lib/utils/show-warning-log.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+
+/**
+ * # 显示警告提示信息
+ *
+ * @function showWarningLog
+ * @param {string} title - 警告类型的文本，例如："警告"
+ * @param {string} keyword - 警告内容的关键内容文本
+ * @param {string} detail - 警告内容的详细描述文本
+ * @returns {void}
+ */
+const showWarningLog = (title, keyword, detail) => {
+  console.log(
+    chalk.yellow(`${title}：`),
+    chalk.blue(`${keyword}`),
+    chalk.yellowBright(`${detail}`),
+  );
+};
+
+export default showWarningLog;