refactor: source has been reorganized and many features have been rewritten

Author: FuuuOverclocking

.prettierignore

@@ -1,6 +1,6 @@
 .github/
 
-type-gymnastics.ts
+type-gymnastics/
 
 /tsconfig.base.json
 /tsconfig.cjs.json

README-cn.md

@@ -72,7 +72,7 @@ yarn add path-nice
 - 提供: CommonJS, ESModule 和 TypeScript typings
 - ESModule 版本可以[直接在 Node 中使用](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
 
-## 用法
+## 3 分钟教程
 
 > ⚠️ 这个库的 API 将在 2.0 版达到稳定, 在此之前请勿在生产中使用.
 
@@ -85,15 +85,15 @@ import path from 'path-nice'
 
 const pkg = path('./package.json')
 
+// 一个 PathNice 实例是对 raw path string 的包装,
+// 用于方便地生成其他路径, 或操作文件
+pkg.raw === './package.json'    // true
+
 // 是 PathNice 的实例
 pkg instanceof path.PathNice    // true
 
 // 是一个不可变对象, 所有属性是只读的
 Object.isFrozen(pkg)            // true
-
-// 一个 PathNice 实例是对 raw path string 的包装,
-// 用于方便地生成其他路径, 或操作文件
-pkg.raw                         // './package.json'
 ```
 
 ### Path 相关方法
@@ -132,6 +132,7 @@ f2.toAbsolute()                 // path('/work/path-nice/package.json'), suppose
 f2.toRelative('path-nice/docs') // path('../package.json')
 await f2.realpath()             // path('/work/path-nice/package.json'), suppose cwd is '/work',
                                 // and there are no symbolic links here.
+f2.realpathSync()               // Sync ver
 
 const parsedF2 = f2.toAbsolute().parse()
 
@@ -149,27 +150,48 @@ parsedF2.dir('/home/fuu').ext('.md')
 
 ### 文件系统相关方法
 
+可以注意到, `fs` 模块中的函数, 例如 `readFile` 和 `writeFile`, 它们的第一个参数几乎都是 `path`, 如果
+将它们改写成路径类的成员方法, 调用起来能够更加方便快捷.
+
+下面大多数方法返回一个 `Promise`. 在函数名加上后缀 `Sync`, 即为它们的同步版本.
+
 #### Read and write
 
-- readFile: 读取文件, 返回 string 或 Buffer, 返回哪个取决于是否设置编码
-- readString: 读取文件, 保证返回 string, 默认 UTF-8
-- readBuffer: 读取文件, 保证返回 Buffer
-- readJSON
+- readFile
+- readString: 等同于 readFile, 但保证返回 string, 默认 UTF-8
+- readBuffer: 等同于 readFile, 但保证返回 Buffer
+- readJSON: 读取文件, 再作为 json 解析
 - writeFile
 - writeJSON: 默认 UTF-8, 4 个空格缩进
 - outputFile: 等同于 writeFile, 但如果文件目录不存在, 自动创建
 - outputJSON
-- updateString: 例如 `path('README.md').updateString(str => str.replace(/path/g, 'path-nice'))`
-- updateJSON: 例如 `path('package.json').updateJSON(json => { json.version = '1.0.0' })`
+- updateString
+  
+  例如:
+
+  ```ts
+  path('README.md')
+      .updateString(str => str.replace(/path/g, 'path-nice'))
+  ```
+- updateJSON
+  
+  例如:
+  
+  ```ts
+  path('package.json')
+      .updateJSON(json => { json.version = '1.0.0' })
+  ```
 - appendFile
 - createReadStream
 - createWriteStream
 - open
 
 #### Copy, move and remove
 
-- copyAs
-- copyToDir
+文件夹也可直接复制移动删除. 支持跨设备移动文件.
+
+- copyAs: 复制为 ...
+- copyToDir: 复制到文件夹内
 - moveAs
 - moveToDir
 - remove

README.md

@@ -72,7 +72,7 @@ yarn add path-nice
 - Provided: CommonJS, ESModule and TypeScript typings
 - ESModule version can be [used directly in Node](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
 
-## Usage
+## 3 minutes guide
 
 > ⚠️ The API of this library will be stable in version 2.0, do not use it in production until then.
 
@@ -85,15 +85,15 @@ import path from 'path-nice'
 
 const pkg = path('./package.json')
 
+// A PathNice instance is a wrapper of the raw path string, so that the path
+// can be easily used to generate additional paths or manipulate files.
+pkg.raw === './package.json'    // true
+
 // is the instance of PathNice
 pkg instanceof path.PathNice    // true
 
 // is an immutable object, all properties are read-only
 Object.isFrozen(pkg)            // true
-
-// A PathNice instance is a wrapper of the raw path string, so that the path
-// can be easily used to generate additional paths or manipulate files.
-pkg.raw                         // './package.json'
 ```
 
 ### Path related methods
@@ -132,6 +132,7 @@ f2.toAbsolute()                 // path('/work/path-nice/package.json'), suppose
 f2.toRelative('path-nice/docs') // path('../package.json')
 await f2.realpath()             // path('/work/path-nice/package.json'), suppose cwd is '/work',
                                 // and there are no symbolic links here.
+f2.realpathSync()               // Sync ver
 
 const parsedF2 = f2.toAbsolute().parse()
 
@@ -149,27 +150,50 @@ parsedF2.dir('/home/fuu').ext('.md')
 
 ### File system related methods
 
+It can be noted that, the functions in the `fs` module, such as `readFile` and `writeFile`,
+almost always have `path` as their first parameter, so it could be more convenient to call
+these functions if we rewrite them into the form of member functions of path class.
+
+Most of the following methods return a `Promise`, and they also have a synchronized version,
+with the `Sync` suffix added to the function name.
+
 #### Read and write
 
-- readFile: Read the file, return either a string or a Buffer, depending on whether the encoding is set
-- readString: Read the file, guaranteed to return a string, UTF-8 by default
-- readBuffer: Read the file, guaranteed to return a Buffer
-- readJSON
+- readFile
+- readString: = readFile, but guaranteed to return a string, UTF-8 by default
+- readBuffer: = readFile, but guaranteed to return a Buffer
+- readJSON: read the file, then parse as json
 - writeFile
 - writeJSON: UTF-8, 4 spaces indent by default
 - outputFile: = writeFile, automatically create the parent directory if it does not exist
 - outputJSON
-- updateString: e.g. `path('README.md').updateString(str => str.replace(/path/g, 'path-nice'))`
-- updateJSON: e.g. `path('package.json').updateJSON(json => { json.version = '1.0.0' })`
+- updateString
+  
+  e.g.
+
+  ```ts
+  path('README.md')
+      .updateString(str => str.replace(/path/g, 'path-nice'))
+  ```
+- updateJSON
+  
+  e.g.
+  
+  ```ts
+  path('package.json')
+      .updateJSON(json => { json.version = '1.0.0' })
+  ```
 - appendFile
 - createReadStream
 - createWriteStream
 - open
 
 #### Copy, move and remove
 
-- copyAs
-- copyToDir
+Directories can also be directly copied and moved for deletion. Support for moving files across devices.
+
+- copyAs: copy **as** ...
+- copyToDir: copy **into** a directory
 - moveAs
 - moveToDir
 - remove

package.json

@@ -28,20 +28,23 @@
         "docs": "node ./scripts/gen-docs.js",
         "release": "node ./scripts/release.js"
     },
+    "dependencies": {
+        "@types/node": "^16",
+        "chokidar": "^3.5.3"
+    },
     "devDependencies": {
         "@types/fs-extra": "^9.0.13",
         "@types/jest": "^28.1.4",
-        "@types/node": "^12.12.6",
         "chalk": "^4.1.2",
         "commitizen": "^4.2.4",
         "conventional-changelog-cli": "^2.2.2",
         "cz-conventional-changelog": "3.3.0",
         "fs-extra": "^10.1.0",
         "jest": "^28.1.2",
-        "memfs": "^3.4.6",
+        "memfs": "^3.4.7",
         "prettier": "^2.7.1",
         "ts-jest": "^28.0.5",
-        "typedoc": "^0.22.18",
+        "typedoc": "^0.23.5",
         "typescript": "^4.7.4"
     },
     "sideEffects": false,
@@ -74,4 +77,4 @@
             "path": "./node_modules/cz-conventional-changelog"
         }
     }
-}
+}

scripts/gen-docs.js

@@ -18,7 +18,7 @@ async function main() {
     await Promise.all([fixPath('docs/index.html'), fixPath('docs/index-cn.html')]);
 
     async function fixPath(filepath) {
-        await path(filepath).updateString((str) => {
+        await path(filepath).updateFileAsString((str) => {
             str = str.replace('<a href="README-cn.md">', '<a href="index-cn.html">');
             str = str.replace('<a href="README.md">', '<a href="index.html">');
             return str;

scripts/release.js

@@ -8,46 +8,57 @@ async function main() {
 
     console.log('release: v' + version);
 
-    if ((await x('git branch --show-current')) !== 'dev') {
-        console.log(`x('git branch --show-current') !== 'dev'`);
-        return;
-    }
-
-    if ((await x('git status --porcelain')) !== '') {
-        console.log(`x('git status --porcelain') !== ''`);
-        return;
-    }
-
-    await sh('git rebase -i main');
-    await sh('git checkout main');
-    await sh('git merge dev');
-
+    // // at dev branch
+    // if ((await x('git branch --show-current')) !== 'dev') {
+    //     console.log(`x('git branch --show-current') !== 'dev'`);
+    //     return;
+    // }
+
+    // // working tree is clean
+    // if ((await x('git status --porcelain')) !== '') {
+    //     console.log(`x('git status --porcelain') !== ''`);
+    //     return;
+    // }
+
+    // // rebase & merge
+    // await sh('git rebase -i main');
+    // await sh('git checkout main');
+    // await sh('git merge dev');
+
+    // build & test
     await fs.remove('./build');
     await sh('tsc -p tsconfig.cjs.json');
     await sh('tsc -p tsconfig.esm.json');
-    await sh('jest');
+    // await sh('jest');
 
+    // we can use path-nice now
     const path = require('../build/cjs/index.cjs.js');
 
     await path('package.json').updateJSON((pkg) => {
         pkg.version = version;
     });
+    // generate release/
     await genRelease();
+    // generate docs/
     await sh('yarn docs');
+    // generate CHANGLOG.md
     await sh('conventional-changelog -p angular -i CHANGELOG.md -s');
 
-    await sh('git add -A');
-    await sh(`git commit -m "chore: release ${version}"`);
-    await sh('git checkout dev');
-    await sh('git merge main');
-    await sh('git push --all');
-    await sh(`git tag v${version}`);
-    await sh(`git push origin v${version}`);
-
-    console.log(chalk.red(`Critical operation:`));
-    console.log(chalk.red(`  $ npm publish --dry-run ./release`));
-    console.log(chalk.red(`  $ npm publish ./release`));
-    console.log(chalk.red(`Copy the command and execute it yourself.`));
+    // // commit, back to dev branch, tag
+    // await sh('git add -A');
+    // await sh(`git commit -m "chore: release ${version}"`);
+    // await sh(`git tag v${version}`);
+    // await sh('git checkout dev');
+    // await sh('git merge main');
+
+    // // sync
+    // await sh('git push --all');
+    // await sh(`git push origin v${version}`);
+
+    // console.log(chalk.red(`Critical operation:`));
+    // console.log(chalk.red(`  $ npm publish --dry-run ./release`));
+    // console.log(chalk.red(`  $ npm publish ./release`));
+    // console.log(chalk.red(`Copy the command and execute it yourself.`));
 }
 
 function getInput() {
@@ -75,23 +86,25 @@ function getInput() {
 async function genRelease() {
     const path = require('../build/cjs/index.cjs.js');
 
-    await path('release').remove();
-    await path('release').ensureDir();
+    await path('release').emptyDir();
 
     await Promise.all([
-        path('build/cjs')
-            .copyToDir('release')
-            .then(() => path('release/cjs/package.json').writeJSON({ type: 'commonjs' })),
-        path('build/esm')
-            .copyToDir('release')
-            .then(() => path('release/esm/package.json').writeJSON({ type: 'module' })),
+        path(
+            'build/cjs',
+            'build/esm',
+            'package.json',
+            'README.md',
+            'README-cn.md',
+            'LICENSE',
+        ).copyToDir('release'),
         path('release/posix/package.json').outputJSON(genSubPkgJSON('posix')),
         path('release/win32/package.json').outputJSON(genSubPkgJSON('win32')),
-        path('package.json')
-            .copyToDir('release')
-            .then(() => path('release/package.json').updateJSON(updatePkgJSON)),
-        path('README.md').copyToDir('release'),
-        path('LICENSE').copyToDir('release'),
+    ]);
+
+    await Promise.all([
+        path('release/cjs/package.json').writeJSON({ type: 'commonjs' }),
+        path('release/esm/package.json').writeJSON({ type: 'module' }),
+        path('release/package.json').updateJSON(updatePkgJSON),
     ]);
 
     /**
@@ -145,7 +158,7 @@ async function genRelease() {
                     require: './cjs/win32.cjs.js',
                 },
             },
-            files: ['cjs/', 'esm/', 'posix/', 'win32/'],
+            files: ['cjs/', 'esm/', 'posix/', 'win32/', 'README-cn.md'],
         };
     }
 }