From e93f734b60b93c96216c3a02eaa76ab9f530547e Mon Sep 17 00:00:00 2001 From: Walter Augustine Date: Wed, 16 Oct 2024 00:47:55 -0400 Subject: [PATCH 1/5] feat: add (#126) --- docs/modules/README.md | 1 + docs/modules/fs-extra.md | 60 ++++++++++++++++++++++++++++++++++++++++ docs/templates/module.md | 4 +-- manifests/preferred.json | 6 ++++ 4 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 docs/modules/fs-extra.md diff --git a/docs/modules/README.md b/docs/modules/README.md index e891cb8..297bed9 100644 --- a/docs/modules/README.md +++ b/docs/modules/README.md @@ -26,6 +26,7 @@ ESLint plugin. - [`ezspawn`](./process-exec.md) - [`faker`](./faker.md) - [`fast-glob`](./glob.md) +- [`fs-extra`](./fs-extra.md) - [`glob`](./glob.md) - [`globby`](./glob.md) - [`ìnvariant`](./invariant.md) diff --git a/docs/modules/fs-extra.md b/docs/modules/fs-extra.md new file mode 100644 index 0000000..dfd8978 --- /dev/null +++ b/docs/modules/fs-extra.md @@ -0,0 +1,60 @@ +# fs-extra + +`fs-extra` adds some file system methods that previously were not included in the native `fs` module and added `Promise` support to the `fs` methods. +Many of the fs-extra modules have since been implemented natively by Node. + +[fs-extra](https://github.com/jprichardson/node-fs-extra) + +## Alternatives + +### `node:fs` + +[Node.js File System Module](https://nodejs.org/docs/latest/api/fs.html) + +To use the promise-based APIs: + +```js +import * as fs from 'node:fs/promises'; +``` + +To use the callback and sync APIs: + +```js +import * as fs from 'node:fs/promises'; +``` + +### Equivalent Methods + +- `ensureFile` -> `fs.exists` - deprecated since v1 +- `ensureFileSync` -> `fs.existsSync` +- `copySync` -> `fs.copyFileSync` +- `mkdirp` -> fs.mkdir` +- `mkdirpSync` -> `fs.mkdirSync` +- `removeSync` -> `fs.rmSync` +- `remove` -> `fs.rm` +- `move` -> `fs.rename` +- `moveSync` -> `fs.renameSync` +- `ensureDirSync` -> `fs.existsSync` +- `pathExistsSync` -> `fs.existsSync` +- `outputFileSync` -> `fs.writeFileSync` + +### Methods that need migrating + +- `copy` +- `emptyDir` +- `emptyDirSync` +- `ensureDir` +- `ensureLink` +- `ensureLinkSync` +- `ensureSymlink` +- `ensureSymlinkSync` +- `mkdirs` +- `mkdirsSync` +- `outputFile` +- `outputJson` +- `outputJsonSync` +- `pathExists` +- `readJson` +- `readJsonSync` +- `writeJson` +- `writeJsonSync` diff --git a/docs/templates/module.md b/docs/templates/module.md index 4621d5d..ccea83a 100644 --- a/docs/templates/module.md +++ b/docs/templates/module.md @@ -2,9 +2,9 @@ {Optional description} -# Alternatives +## Alternatives -## {Alternative package name} +### {Alternative package name} {Description of alternative package} diff --git a/manifests/preferred.json b/manifests/preferred.json index 808d22d..33203d2 100644 --- a/manifests/preferred.json +++ b/manifests/preferred.json @@ -90,6 +90,12 @@ "docPath": "glob", "category": "preferred" }, + { + "type": "documented", + "moduleName": "fs-extra", + "docPath": "fs-extra", + "category": "preferred" + }, { "type": "documented", "moduleName": "glob", From 4db4fc9453494c2874cba8d19a8d2fb403f327b5 Mon Sep 17 00:00:00 2001 From: Walter <10503240+walter-0@users.noreply.github.com> Date: Wed, 16 Oct 2024 20:27:13 -0400 Subject: [PATCH 2/5] Update docs/modules/fs-extra.md Co-authored-by: pralkarz <31964869+ziebam@users.noreply.github.com> --- docs/modules/fs-extra.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/fs-extra.md b/docs/modules/fs-extra.md index dfd8978..6724c25 100644 --- a/docs/modules/fs-extra.md +++ b/docs/modules/fs-extra.md @@ -20,7 +20,7 @@ import * as fs from 'node:fs/promises'; To use the callback and sync APIs: ```js -import * as fs from 'node:fs/promises'; +import * as fs from 'node:fs'; ``` ### Equivalent Methods From 32c69f2fb99cccd37d13a769d31539b20d59698a Mon Sep 17 00:00:00 2001 From: Walter Augustine Date: Sat, 26 Oct 2024 23:20:13 -0400 Subject: [PATCH 3/5] add necessary options for equivalent methods. format into a table --- docs/modules/fs-extra.md | 84 +++++++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/docs/modules/fs-extra.md b/docs/modules/fs-extra.md index 6724c25..fcd0dde 100644 --- a/docs/modules/fs-extra.md +++ b/docs/modules/fs-extra.md @@ -23,38 +23,52 @@ To use the callback and sync APIs: import * as fs from 'node:fs'; ``` -### Equivalent Methods - -- `ensureFile` -> `fs.exists` - deprecated since v1 -- `ensureFileSync` -> `fs.existsSync` -- `copySync` -> `fs.copyFileSync` -- `mkdirp` -> fs.mkdir` -- `mkdirpSync` -> `fs.mkdirSync` -- `removeSync` -> `fs.rmSync` -- `remove` -> `fs.rm` -- `move` -> `fs.rename` -- `moveSync` -> `fs.renameSync` -- `ensureDirSync` -> `fs.existsSync` -- `pathExistsSync` -> `fs.existsSync` -- `outputFileSync` -> `fs.writeFileSync` - -### Methods that need migrating - -- `copy` -- `emptyDir` -- `emptyDirSync` -- `ensureDir` -- `ensureLink` -- `ensureLinkSync` -- `ensureSymlink` -- `ensureSymlinkSync` -- `mkdirs` -- `mkdirsSync` -- `outputFile` -- `outputJson` -- `outputJsonSync` -- `pathExists` -- `readJson` -- `readJsonSync` -- `writeJson` -- `writeJsonSync` +#### Equivalent Methods + +| fs-extra | node:fs | Notes | +| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `copySync(src, dest[, options])` | `fs.copyFileSync(src, dest[, mode])` | | +| `mkdirs(dir[,options][,callback])`, `mkdirp(dir[,options][,callback])`, `ensureDir(dir[,options][,callback])` | `fs.mkdir(dir, { recursive: true }, callback)` | `ensureDir` and `mkdirp` are aliases of `mkdirs` | +| `mkdirpSync(dir[,options])`, `mkdirsSync(dir[,options])`, `ensureDirSync(dir[,options])` | `fs.mkdirSync(dir, { recursive: true })` | `ensureDirSync` and `mkdirpSync` are aliases of `mkdirsSync` | +| `remove(path[,callback])` | `fs.rm(path, { recursive: true, force: true }, callback)` | | +| `removeSync(dir)` | `fs.rmSync(dir, { recursive: true, force: true })` | | +| `move(src, dest, { overwrite: true }, callback)` | `fs.rename(source, destination)` | | +| `moveSync(source, destination, { overwrite: true })` | `fs.renameSync(source, destination)` | These are not strictly equivalent. The `move` methods in fs-extra act like the `mv` command and they will work across devices also. The `rename` methods in fs work like the `rename` system call and will **not** work across devices. Having Node’s `rename` methods work across devices is currently [marked as a "won't fix."](https://github.com/nodejs/node/issues/19077) Also, the `overwrite: true` behaviour is the default/only behaviour in the standard library. | +| `copy(source, destination, callback)` | `fs.cp(source, destination, callback)` | | +| `pathExistsSync(file)` | `fs.existsSync(path)` | | + +#### Methods that need migrating or more than one `node:fs` method + +##### `emptyDir(dir[, callback])` + +##### `emptyDirSync(dir)` + +##### `ensureFile(file[, callback])` + +##### `ensureFileSync(file)` + +##### `ensureLink(srcPath, destPath[, callback])` + +##### `ensureLinkSync(srcPath, destPath)` + +##### `ensureSymlink(srcPath, destPath[, type][, callback])` + +##### `ensureSymlinkSync(srcPath, destPath[, type])` + +##### `outputFile(file, data[, options][, callback])` + +##### `outputFileSync(file, data[, options])` + +##### `outputJson(file, object[, options][, callback])` + +##### `outputJsonSync(file, object[, options])` + +##### `pathExists(file[, callback])` + +##### `readJson(file[, options][, callback])` + +##### `readJsonSync(file[, options])` + +##### `writeJson(file, object[, options][, callback])` + +##### `writeJsonSync(file, object[, options])` From d68990bce5d914730935c791c5c43b61c4aed145 Mon Sep 17 00:00:00 2001 From: Walter <10503240+walter-0@users.noreply.github.com> Date: Tue, 29 Oct 2024 19:29:53 -0400 Subject: [PATCH 4/5] Update fs-extra.md --- docs/modules/fs-extra.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/modules/fs-extra.md b/docs/modules/fs-extra.md index fcd0dde..92dada9 100644 --- a/docs/modules/fs-extra.md +++ b/docs/modules/fs-extra.md @@ -39,6 +39,8 @@ import * as fs from 'node:fs'; #### Methods that need migrating or more than one `node:fs` method +For all other methods, a combination of fs methods may be needed rather than there being a one-to-one replacement. See the docs [here](https://nodejs.org/docs/latest/api/fs.html) + ##### `emptyDir(dir[, callback])` ##### `emptyDirSync(dir)` From cc048aadafe5e103e12d9432526f80296a6e0c55 Mon Sep 17 00:00:00 2001 From: Walter <10503240+walter-0@users.noreply.github.com> Date: Thu, 31 Oct 2024 20:17:06 -0400 Subject: [PATCH 5/5] Update fs-extra.md --- docs/modules/fs-extra.md | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/docs/modules/fs-extra.md b/docs/modules/fs-extra.md index 92dada9..fa9d591 100644 --- a/docs/modules/fs-extra.md +++ b/docs/modules/fs-extra.md @@ -40,37 +40,3 @@ import * as fs from 'node:fs'; #### Methods that need migrating or more than one `node:fs` method For all other methods, a combination of fs methods may be needed rather than there being a one-to-one replacement. See the docs [here](https://nodejs.org/docs/latest/api/fs.html) - -##### `emptyDir(dir[, callback])` - -##### `emptyDirSync(dir)` - -##### `ensureFile(file[, callback])` - -##### `ensureFileSync(file)` - -##### `ensureLink(srcPath, destPath[, callback])` - -##### `ensureLinkSync(srcPath, destPath)` - -##### `ensureSymlink(srcPath, destPath[, type][, callback])` - -##### `ensureSymlinkSync(srcPath, destPath[, type])` - -##### `outputFile(file, data[, options][, callback])` - -##### `outputFileSync(file, data[, options])` - -##### `outputJson(file, object[, options][, callback])` - -##### `outputJsonSync(file, object[, options])` - -##### `pathExists(file[, callback])` - -##### `readJson(file[, options][, callback])` - -##### `readJsonSync(file[, options])` - -##### `writeJson(file, object[, options][, callback])` - -##### `writeJsonSync(file, object[, options])`