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..fa9d591 --- /dev/null +++ b/docs/modules/fs-extra.md @@ -0,0 +1,42 @@ +# 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'; +``` + +#### 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 + +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) 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",