@yaohaixiao/renames.js 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+## <small>0.0.2 (2026-02-08)</small>
+
+
+
+
+
+
+
+
+
+
+

package/README.md

@@ -6,14 +6,20 @@ renames.js - 基于 Node 的批量文件名重命名 cli 工具库。
 
 - 方便快捷，配置灵活；
 - 支持指定文件名列表数据或者文件名列表文件；
-- 支持文件名自动生成索引；
-- 支持文件名自定义过滤；
-- 支持文件名自定义排序；
-- 支持文件名自定义格式化；
+- 支持文件名自动生成（章节）索引；
+- 支持文件名自定义过滤文件；
+- 支持文件名自定义文件排序；
+- 支持文件名自定义格式化名；
 
 ## Usage
 
-renames.js 使用方式如下：
+首先需要全局安装 renames.js，命令如下：
+
+```bash
+npm i -g @yaohaixiao/renames.js
+```
+
+全局安装完成后，我们就可以在命令行使用了，renames.js 使用方式如下：
 
 ```bash
 renames [arguments|command] [options]
@@ -154,7 +160,7 @@ filter 参数可以用来过滤 dirPath 文件夹中的文件，例如 C:\Downlo
 
 ```js
 // renames.js 内部提供的功能函数
-import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension';
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension.js';
 
 export default {
   dirPath: 'C:\\Downloads',
@@ -193,7 +199,7 @@ export default {
 
 ```js
 // renames.js 内部提供的功能函数
-import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename';
+import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename.js';
 
 export default {
   dirPath: 'C:\\Downloads',
@@ -222,7 +228,7 @@ format 参数可以对文件夹中的文件进行格式化，例如 C:\Downloads
 
 ```js
 // renames.js 内部提供的功能函数
-import stripNonDigit from '@yaohaixiao/renames.js/lib/utils/strip-non-digit';
+import stripNonDigit from '@yaohaixiao/renames.js/lib/utils/strip-non-digit.js';
 
 export default {
   dirPath: 'C:\\Downloads',
@@ -233,7 +239,467 @@ export default {
 };
 ```
 
+### Typical Use Case
+
+下面介绍通过调整配置 renames.config.js 的配置，实现批量重命名的一些典型的使用案例，操作起来是非常的简单的。
+
+#### autoIndex: 'only'
+
+将杂乱的图片库的文件名，批量重命名为自动生成数值（升序）索引（例如：1.jpg -
+2x.jpg）的文件名，调整 renames.config.js 配置如下：
+
+```js
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: '',
+  suffix: '',
+  connector: '',
+  // 自动生成数值（升序）索引
+  autoIndex: 'only',
+  startIndex: 0,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![autoIndex-only](./docs/img/autoIndex-only.png)
+
+说明：执行 renames 命令，未配置任何参数和配置参数，则执行命令时完全使用配置文件的设置。
+
+#### startIndex
+
+如果你是一个爱收集壁纸的人，应该会陆续收集更多的图片，我们可以使用 startIndex 在原来的索引位置继续自动生成数值索引名称，配置如下：
+
+```js
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: '',
+  suffix: '',
+  connector: '',
+  // 自动生成数值（升序）索引
+  autoIndex: 'only',
+  // 上图中文件名的索引值已经到 29.jpg，则 startIndex 的值就是 29
+  startIndex: 29,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![startIndex](./docs/img/startIndex.png)
+
+#### indexPadZero
+
+细心的朋友应该发现文件名 01.jpg，自动用‘0’填充。使用的就是 indexPadZero 这个配置参数。 现在将文件夹的图片文件数量增加到100以上，看看索引使用自动填充‘0’后的效果，配置如下：
+
+```js
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: '',
+  suffix: '',
+  connector: '',
+  // 自动生成数值（升序）索引
+  autoIndex: 'only',
+  startIndex: 0,
+  // 使用 '0' 自动填充
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![indexPadZero](./docs/img/indexPadZero.png)
+
+当然，如果没有强迫症，不希望文件名的长度一致，我们也可以关闭 indexPadZero，配置如下：
+
+```js
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: '',
+  suffix: '',
+  connector: '',
+  // 自动生成数值（升序）索引
+  autoIndex: 'only',
+  startIndex: 0,
+  // 使用 '0' 自动填充
+  indexPadZero: false,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![indexPadZero-false](./docs/img/indexPadZero-false.png)
+
+可以看到，关闭后就不会使用‘0’自动填充了。
+
+#### prefix、suffix、connector
+
+接着我们可以对以上重命名好的文件名再继续调整，使用 prefix、suffix、connector 这3个配置参数，添加前缀和后缀，配置如下：
+
+```js
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: 'wallpaper',
+  suffix: '1080p',
+  connector: '-',
+  // 关闭自动生成数值索引（升序）
+  autoIndex: false,
+  startIndex: 0,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![prefix-suffix-connector](./docs/img/prefix-suffix-connector.png)
+
+#### filter
+
+接着我们使用 filter 配置参数，进一步对上面重命名的文件再操作，我们将图片中的 .png 格式的图片再批量处理以下，配置如下：
+
+```js
+// renames.js 内部提供的功能函数
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension';
+
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  prefix: 'wallpaper',
+  // 添加 png 的后缀
+  suffix: 'png',
+  connector: '-',
+  // 针对 png 图片生成自动索引的文件名
+  autoIndex: 'only',
+  startIndex: 0,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  // 过滤 .png 图片
+  filter: (files) => {
+    return files.filter((filename) => {
+      const extname = getExtension(filename);
+      return extname === '.png';
+    });
+  },
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![filter](./docs/img/filter.png)
+
+#### format
+
+接下来，我们将使用 format 参数，将上面我们使用 filter 参数将 .png 格式的图片的后缀再改成 1080p，配置如下：
+
+```js
+// renames.js 内部提供的功能函数
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension';
+
+export default {
+  dirPath: 'C:\\Users\\robert\\Downloads\\壁纸',
+  namesList: '',
+  // 清空前后缀的配置，我们现在的操作是仅修改原来的文件名
+  prefix: '',
+  suffix: '',
+  connector: '',
+  // 关闭自动索引也是因为需要仅修改原始的文件名
+  autoIndex: false,
+  startIndex: 0,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  // 过滤 .png 图片，也可以配置过滤，那工具会遍历所有的文件，
+  // 为了性能，我们还是保留 filter 配置
+  filter: (files) => {
+    return files.filter((filename) => {
+      const extname = getExtension(filename);
+      return extname === '.png';
+    });
+  },
+  sortBy: 'name',
+  order: 'desc',
+  sensitivity: 'base',
+  format: (basename) => {
+    return basename.replace('png', '1080p');
+  },
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![format](./docs/img/format.png)
+
+#### nameList、sortBy
+
+前面介绍的都是直接修改原来的文件名的方式来重命名，namesList 则可以通过外部数据将定义好的文件名结合 sortBy 将文件的顺序调整跟 namesList 中的数据一致，进行批量重命名。
+
+例如，我下载了《达尔文游戏》这个动漫，但下载下来的文件名是这样的：
+
+- 1-E01-1 (1).mp4
+- 10-E09 (1).mp4
+- 11-E10 (1).mp4
+- 12-E11 (1).mp4
+- 2-E01-2 (1).mp4
+- 3-E02 (1).mp4
+- 4-E03 (1).mp4
+- 5-E04 (1).mp4
+- 6-E05 (1).mp4
+- 7-E06 (1).mp4
+- 8-E07 (1).mp4
+- 9-E08 (1).mp4
+
+顺便说以下，如果直接用内置的 sortBy:
+'name' 排序，就是以上的排序结果。而我通过 AI 获取到的《达尔文游戏》其 12集的名称如下：
+
+- 初战
+- 涉谷
+- 导火索
+- 火花
+- 记忆（特别篇）
+- 水葬
+- 金刚
+- 压碎
+- 平稳
+- 决斗
+- 旧王
+- 血盟
+
+所以我需要通过自定义的 sortBy 函数处理以下，按 1-12 的索引值升序排序，配置如下：
+
+```js
+// renames.js 内部提供的功能函数
+import getBasename from './lib/utils/get-basename.js';
+
+export default {
+  dirPath: 'C:\\Users\\haixi\\Downloads\\达尔文游戏',
+  namesList: 'C:\\Users\\haixi\\Downloads\\names.txt',
+  // namesList: ',初战,涉谷,导火索,火花,记忆（特别篇）,水葬,金刚,压碎,平稳,决斗,旧王,血盟'
+  prefix: '达尔文游戏',
+  suffix: '1080p',
+  connector: '-',
+  autoIndex: true,
+  startIndex: 0,
+  indexPadZero: true,
+  indexPrefix: '第',
+  indexSuffix: '集',
+  delimiter: '：',
+  force: false,
+  extname: '',
+  filter: null,
+  // 使用自定义的排序方式
+  sortBy: (files) => {
+    return files.sort((prev, next) => {
+      const pattern = /-(.*)/;
+      // 保留文件名中的第一个字符，也就是索引值
+      const prevIndex = getBasename(prev).replace(pattern, '');
+      const nextIndex = getBasename(next).replace(pattern, '');
+
+      // 升序排列
+      return Number(prevIndex) - Number(nextIndex);
+    });
+  },
+  // 使用自定义排序函数后 order 和 sensitivity 就没有作用了
+  order: 'asc',
+  sensitivity: 'base',
+  format: null,
+};
+```
+
+然后在命令行工具执行 renames 命令，如下图：
+
+![namesList-sortBy](./docs/img/namesList-sortBy.png)
+
+**PS**: 这是我当初开发 renames.js 的主要目的，重命名下载的视频文件名！
+
+## API Documentation
+
+renames.js 除了作为 cli 工具可以在命令行直接使用外，也额外提供了一些基础的处理获取文件信息的功能函数模块。
+
+### getBasename(filename) ⇒ <code>string</code>
+
+getBasename() 方法用来获取文件名中不含扩展名的字符串。
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回文件名中去掉扩展名部分的字符串
+
+| Param    | Type                | Description          |
+| -------- | ------------------- | -------------------- |
+| filename | <code>string</code> | 文件名（路径）字符串 |
+
+#### Usage
+
+```js
+import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename.js';
+
+const filename = '1-E01-1 (1).mp4';
+const basename = getBasename(filename);
+
+console.log(basename); // -> '1-E01-1 (1)'
+```
+
+### getExtension(filename) ⇒ <code>string</code>
+
+getExtension() 方法用来获取文件名中的扩展名部分字符串（含.）。
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回文件名中扩展名部分的字符串，例如：'.jpg'
+
+| Param    | Type                | Description          |
+| -------- | ------------------- | -------------------- |
+| filename | <code>string</code> | 文件名（路径）字符串 |
+
+#### Usage
+
+```js
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension.js';
+
+const filename = '1-E01-1 (1).mp4';
+const extname = getExtension(filename);
+
+console.log(extname); // -> '.mp4'
+```
+
+### isFileExists(filePath, [basePath]) ⇒ <code>boolean</code>
+
+isFileExists() 方法用来同步检测文件是否存在，如果存在，返回 true，否则返回 false。
+
+**Kind**: global function **Returns**:
+<code>boolean</code> - - 文件存在返回 true，否则返回 false
+
+| Param      | Type                | Default                               | Description                       |
+| ---------- | ------------------- | ------------------------------------- | --------------------------------- |
+| filePath   | <code>string</code> |                                       | 检测的文件路径                    |
+| [basePath] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | 可选，基础路径。. Default is `''` |
+
+#### Usage
+
+```js
+import isFileExists from '@yaohaixiao/renames.js/lib/utils/is-file-exists.js';
+
+const filename = '1-E01-1 (1).mp4';
+const basePath = 'C:\Users\haixi\Downloads\达尔文游戏';
+
+// console.log(isFileExists('C:\Users\haixi\Downloads\达尔文游戏\1-E01-1 (1).mp4'))
+console.log(isFileExists(filename, basePath)); // -> true
+```
+
+### padZero(val, [length]) ⇒ <code>string</code>
+
+padZero() 方法用来处理对数字/字符串补零，前置补‘0’，确保返回指定长度的字符串。
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回补零后的字符串
+
+| Param    | Type                                       | Default        | Description                                                  |
+| -------- | ------------------------------------------ | -------------- | ------------------------------------------------------------ |
+| val      | <code>number</code> \| <code>string</code> |                | 要补零的数字或字符串（如 27、'27'）                          |
+| [length] | <code>number</code>                        | <code>2</code> | 可选，目标总长度（如 3 → '027'，4 → '0027'）. Default is `2` |
+
+#### Usage
+
+```js
+import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename.js';
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension.js';
+import padZero from '@yaohaixiao/renames.js/lib/utils/pad-zero.js';
+
+const filename = '1.mp4';
+const finalFileName = `${padZero(getBasename(filename), 3)}${getExtension(filename)}`;
+
+console.log(finalFileName); // -> '001.mp4'
+```
+
+### stripNonDigit(str) ⇒ <code>string</code>
+
+stripNonDigit(str) 方法用来移除文本中所有非数值的文本，返回移除纯数值的字符串。
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回移除非数值的字符串
+
+| Param | Type                | Description        |
+| ----- | ------------------- | ------------------ |
+| str   | <code>string</code> | 文件名的文本字符串 |
+
+#### Usage
+
+```js
+import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename.js';
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension.js';
+import stripNonDigit from '@yaohaixiao/renames.js/lib/utils/strip-non-digit.js';
+
+const filename = '第01集：初战';
+const basename = getBasename(filename);
+const extname = getExtension(filename);
+
+console.log(`${stripNonDigit(basename)}${extname}`); // -> '01.mp4'
+```
+
 ## License
 
-Licensed under
-[MIT License](http://opensource.org/licenses/mit-license.html).
+Licensed under [MIT License](http://opensource.org/licenses/mit-license.html).

package/bin/renames.js

@@ -162,8 +162,7 @@ const getCommonOptions = () => [
   {
     flags: '--sort, --sortBy <sortBy>',
     description:
-      '可选，排序类型，可选项：name、type、size、birthtime 和 modify-time',
-    defaultValue: DEFAULT_SORT,
+      '可选，排序类型，可选项：name、type、size、birthtime 和 modify-time（default：name）',
   },
   {
     flags: '--order <order>',
@@ -347,10 +346,12 @@ mainCommander
         // 获取最终的文件夹路径
         const finalDirPath = await getFinalDirPath(dirPath, config);
 
-        // 合并配置并处理文件名列表
+        // 合并命令行输入的配置参数
         const finalOptions = { ...config, ...options };
 
-        finalOptions.namesList = processNameList(finalOptions.namesList);
+        if (options.namesList) {
+          finalOptions.namesList = processNameList(options.namesList);
+        }
 
         if (finalDirPath) {
           // 执行重命名

package/docs/get-basename.md

@@ -0,0 +1,23 @@
+<a name="getBasename"></a>
+
+## getBasename(filename) ⇒ <code>string</code>
+
+getBasename() 方法用来获取文件名中不含扩展名的字符串
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回文件名中去掉扩展名部分的字符串
+
+| Param    | Type                | Description          |
+| -------- | ------------------- | -------------------- |
+| filename | <code>string</code> | 文件名（路径）字符串 |
+
+#### Usage
+
+```js
+import getBasename from '@yaohaixiao/renames.js/lib/utils/get-basename.js';
+
+const filename = '1-E01-1 (1).mp4';
+const basename = getBasename(filename);
+
+console.log(basename); // -> '1-E01-1 (1)'
+```

package/docs/get-extension.md

@@ -0,0 +1,23 @@
+<a name="getExtension"></a>
+
+### getExtension(filename) ⇒ <code>string</code>
+
+getExtension() 方法用来获取文件名中的扩展名部分字符串（含.）。
+
+**Kind**: global function **Returns**:
+<code>string</code> - - 返回文件名中扩展名部分的字符串，例如：'.jpg'
+
+| Param    | Type                | Description          |
+| -------- | ------------------- | -------------------- |
+| filename | <code>string</code> | 文件名（路径）字符串 |
+
+#### Usage
+
+```js
+import getExtension from '@yaohaixiao/renames.js/lib/utils/get-extension.js';
+
+const filename = '1-E01-1 (1).mp4';
+const extname = getExtension(filename);
+
+console.log(extname); // -> '.mp4'
+```