Fairu is an asynchronous utility library that provides fast and reliable file-system operations that can be daisy chained together and leverage glob patterns, and serialization to toml, json, and yaml. This is a library built within the AppKu ecosystem of tools and utilities to help build apps. Specifically Fairu provides file and directory read/write operations for regular, YAML, TOML, and env files.
You can find formal documentation here.
Fairu is designed to be usable through a series of chained methods. These methods define how Fairu will perform the final action, either discovery, reading, writing, appending, touching, or unlinking.
Your Fairu usage should almost always begin with a .with
call to specify the paths (which may be glob patterns). You then can follow up with methods to define how Fairu will behave, such as specifying .throw(false)
to have Fairu avoid throwing errors and instead continue processing.
In Fairu operations (discover
, touch
, read
, write
, delete
) the returned value will be a promise of an Array
of PathState
objects.
let found = await Fairu
.with('./**/*')
.discover();
//found = [...PathState]
let readFiles = await Fairu
.with('./path/to/files.*')
.throw(false)
.read();
//found = [...ReadPathState]
let writeResults = await Fairu
.with('./hello.txt')
.write('hello world!');
//found = [...PathState]
let appendResults = await Fairu
.with('./hello.txt', 'only-mars.txt')
.append('\nalso, hello Mars!');
//found = [...PathState]
let writeResults = await Fairu
.with('./hello.txt')
.touch();
//found = [...PathState]
Fairu also provides a number of static utility functions to make your life easier:
-
mv
: Move a file or directory (recursively) to another. -
cp
: Copy a file or directory (recursively) to another. -
stringify
: Stringify a JavaScript object into ajson
,toml
, oryaml
string. -
parse
: Parsejson
,toml
, oryaml
string content into a JavaScript object. -
packageJSON
: Read apackage.json
file synchronously from a specific directory.
By default, Fairu works out of the box without needing any adjustment. You can tweak the behavior of path discovery though by setting the options
property on the Fairu instance you create. This affects the path matching and discovery prior to taking action on defined paths.
let f = new Fairu();
f.options = {
absolute: true,
debug: true
};
//f.with(...paths) etc.
You can find the full documentation on these options on the glob
package's README.
You can find examples and the fully published documentation at appku.github.io/fairu.
If you'd like to generate the documentation locally, you can do so by running npm run docs
and the site will be statically generated under the docs/
path.
npm i @appku/fairu
This project uses jest
to perform unit tests.
Run npm test
to run jest unit tests.
Run npm run lint
to run ESLint, optionally install the Visual Studio Code ESLint extension to have linting issues show in your "Problems" tab and be highlighted.
If you are writing unit tests, you may need to npm install @types/jest
to get intellisense in Visual Studio Code if for some reason it did not get installed.
Only maintainers with proper access can publish this package to npm. To do so as maintainers, you can publish by running the following command:
npm publish --registry=https://registry.npmjs.org --access=public