fs

Write, read, clone and remove files and folders without much thinking.

The built-in NodeJS fs module is often too broad and low-level. Unlike the native fs or other packages @danielcobo/fs comes with useful defaults and just a handful of methods to learn.

🧭 Table of contents

• ✨ Benefits
• 🎒 Requierments
• 🚀 Quickstart
• 📘 Documentation
• 🆘 Troubleshooting
• 🤝 Contributing
• 🧪 Testing
• ⚖️ License

✨ Benefits

• [x] Only a few methods to remember
• [x] Uses async/await
• [x] Includes tests
• [x] MIT license

🎒 Requierments

To use this package you will need:

• NodeJS
• Knowledge of async/await or Promise handling

🚀 Quickstart

Install

npm install @danielcobo/fs

Note: In case you're wondering, @danielcobo/ is just a namespace scope - an NPM feature. Scopes make it easier to name modules and improve security.

Require the module

const fs = require('@danielcobo/fs');

Make

//Make a directory
await fs.mk('./some/folder');

//Make a file (including any missing path directories)
const path = './some/other/folder/helloworld.txt';
const content = '@danielcobo/fs is awesome!';
await fs.mk(path, content);

Note: we use the same method for directories and files. We can do that with all the methods. Less to remember, yay!

Read

//Read directory subpaths
const tree = await fs.read('./some');

console.log(tree);
/*
{
    dirs: [folder, other/folder],
    files:[other/folder/helloworld.txt]
}
*/

//Read a file
const path = './some/other/folder/helloworld.txt';
const content = await fs.read(path);

console.log(content); //@danielcobo/fs is awesome!

Clone (aka. copy & paste)

//Clone a directory and all it's contents
const original = './some/folder';
const clone = './some/clone/folder';
await fs.clone(original, clone);

//Clone a file
const originalFile = './some/other/folder/helloworld.txt';
const cloneFile = './some/other/clone/folder/helloworld.txt';
await fs.clone(originalFile, cloneFile);

Remove (aka. delete)

//Remove a directory and all it's contents
await fs.rm('./some/folder');

//Remove a file
await fs.rm('./some/other/folder/helloworld.txt');

For details see documentation below.

📘 Documentation

.mk()

Write a file or create a directory path.

| Param | Type | Default | Description | | --------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | mkPath | string | | path to write to | | content | string | | file text content (ignored for directory) | | [options] | string | Object | 'utf8' | encoding, mode, flag, signal. See NodeJS docs. |

.make()

Alias of .mk()

.read()

Read file or directory.

| Param | Type | Default | Description | | --------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | readPath | string | Array.<string> | | path to read | | [options] | string | Object | 'utf8' | encoding, mode, flag, signal. See NodeJS docs. |

| Returns | Type | Description | | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------ | | fileContent or tree | string | Tree | File text content or tree object containing paths within given tree/s. See Tree |

.clone()

Clone file or directory.

| Param | Type | Description | | -------------------------- | --------- | -------------------------------------- | | originalPath | string | original path | | destinationPath | string | clone path | | [options] | Object | Options object | | [options.overwrite=true] | boolean | If false do not overwrite existng files |

.rm()

Remove file or directory.

| Param | Type | Description | | ------ | -------- | ---------------------------------------------- | | rmPath | string | path to remove - can be file or directory path |

.remove()

Alias of .rm()

Tree : Object

Paths within a given tree

| Name | Type | Description | | ---------- | ---------------- | ------------------------------------ | | dirs | Array.<string> | paths of subdirectories | | files | Array.<string> | filepaths | | root | Array.<string> | path/s of tree/s being read | | prunedTree | prunedTree | see prunedTree |

PrunedTree : Object

Tree subpaths without root path

| Name | Type | Description | | ----- | ---------------- | ----------------------------------------- | | dirs | Array.<string> | paths of subdirectories without root path | | files | Array.<string> | filepaths without root path |

🆘 Troubleshooting

Remember await must be used inside an async function unless:

• you add "type":"module" to your project's package.json.
• change the file extension to .mjs
• wrap any code using await into an asynchronous immediately invoked function expression (my gosh that's a mouthful..). Example:

(async function () {
  //Code using await goes here
})();

The reason for these acrobatics is top-level await works in ECMAScript modules. However, NodeJS uses CommonJS modules by default. Adding "type":"module" to your project's package.json makes NodeJS parse all your .js files as ECMAScript modules. If you want it to only parse individual files as ECMAScript modules, you can do so by giving them an .mjs extension.

🤝 Contributing

Anyone can contribute

Contributions come in many shapes and sizes. All are welcome. You can contribute by:

• asking questions
• suggesting features
• sharing this repo with friends
• improving documentation (even fixing typos counts 😉)
• providing tutorials (if you do, please let me know, I would love to read them)
• improving tests
• contributing code (new features, performance boosts, code readability improvements..)

Rules for contributions

General guidelines:

• there are no dumb questions
• be polite and respectful to others
• do good

When coding remember:

• working > maintainability > performance
• best code is no code
• be descriptive when naming
• keep it DRY
• do test

Contribution licence: All contributions are considered to be under same license as this repository.

🧪 Testing

Testing suite: 🃏 Jest | Test command: npm test

Mutation testing suite: 👽 Stryker Mutator | Mutation test command: npm run mutation

If you intend to develop further or contribute code, then please ensure to write and use testing. Strive for 100% code coverage and high mutation scores. Mutation score 100 is great, but it's not always neccessary (if there are valid reasons).

⚖️ License

MIT License