@AppKu/Fairu

@AppKu/Fairu

v1.0.6

Class

Fairu

Fairu is a file-system reading & writing helper designed to simplify operations. It provides an asynchronous and chained method interface to working with files that helps you focus less on file system operations, and more on just getting things written and read reliably.

Constructor

new Fairu()

Source

Members

static

FormatString

Type

  • String

Properties

  • yaml String
  • toml String
  • json String

Source

Methods

asyncstatic

cp(source, destination)

Copies a file or directory (recursively) to another.

Parameters

  • source String

    The file or directory path to use as the source.

  • destination String

    The file or directory to use as the destination.

Source

asyncstatic

mv(source, destination)

Moves a file or directory (recursively) to another.

Parameters

  • source String

    The file or directory path to use as the source.

  • destination String

    The file or directory to use as the destination.

Source

static

packageJSON(dir) → {PackageJSON}

Reads a package.json file from the given directory. This operation is synchronous.

Parameters

  • dir String

    The directory of the package.json file.

Returns

Source

static

parse(format, inputString, filePathopt) → {*}

Attempts to parse the given input string using the specified format parser into an object.

Parameters

  • format String

    Can be either 'json', 'yaml', or 'json'.

  • inputString *

    The string to be parsed.

  • filePath String <optional>

    The file path used in error/warning messages.

Returns

  • *

Throws

  1. Error when the format is unknown.

  2. Error when parsing fails.

Source

static

stringify(format, object, spaceopt) → {String}

Stringifies an object into the specified format (yaml, toml, or json).

Parameters

  • format String

    Can be either 'json', 'yaml', or 'json'.

  • object *

    The object to stringify.

  • space Number <optional>
     4

    The number of spaces to use for indentations.

Returns

  • String

Throws

  1. Error when the format is unknown.

  2. Error when stringification fails.

Source

static

with(…paths) → {Fairu}

Specify the file-system paths (including glob patterns) you will be performing an operation on. You may optionally provide a callback that returns a path to use- the callback will be passed the path module as an argument.

Calling this resets the paths used in this Fairu operation, letting you daisy-chain multiple operations together, each starting with the with specification.

This function is not cummulative, specified paths will overwrite those set by a previous call.

Parameters

  • paths String | FairuCallback.Path <repeatable>

    The series of file-system paths or callback functions.

Returns

Examples

// Daisy chaining multiple operations:
await Fairu
  .with('./file1.txt', p => p.join('/home/', 'file2.txt'))
  .write(content)
  .with('./file3.txt')
  .write(otherContent);
// Using glob paths:
await Fairu
  .with('./**', './+(hello|greetings)?(world|mars|venus).txt')
  .read();

Throws

Error when a specified path is not a string or callback function.

Source

async

append(content) → {Promise.<Array.<module:path-state~PathState>>}

Appends the content to the paths specified. If the file does not exist, it is created.

If the path is a directory, it will be created.

If a format was specified, the written data will be stringified into that format before being written.

If the file is in an errored state prior to the write, it is skipped.

Parameters

  • content String | Buffer

    The content to be written to path.

Returns

  • Promise.<Array.<module:path-state~PathState>>

Source

async

discover(createopt, handleErroropt) → {Promise.<Array.<module:path-state~PathState>>}

Expands globbed paths and discovers information about them, returning a record for each path (including invalid) ones.

Parameters

Returns

  • Promise.<Array.<module:path-state~PathState>>

Throws

  1. Error when the throw flag is true and an error discovering paths is encountered.

  2. Error when the "when" condition for the Fairu operation fails to return a boolean result.

Source

encoding(encoding) → {Fairu}

Sets the text file encoding to the specified value. By default the encoding is not set.

Calling this function without an argument or null will reset it to it's default (not set).

Parameters

  • encoding String

    The file text encoding to use when reading and writing files.

Returns

Throws

Error when the encoding value is specified and not a string.

Source

format(format) → {Fairu}

Enables formatting of written or read objects or data to the specified format, either: "json", "toml", or "yaml". You may also ensure raw bufferred reads or writes by passing a null argument to clear the setting. By default the format is not set.

Calling this function without an argument or null will reset it to it's default (not set).

Parameters

  • format Fairu

    The format (or null) to use for reading & writing. Can be: "json", "toml", or "yaml".

Returns

Throws

Error when the specified format argument is not "json", "yaml", "toml".

Source

async

read() → {Promise.<Array.<module:read-path-state~ReadPathState>>}

Reads from all paths discovered from the specified .with paths. Directories will return data that is the top-level list of files and directories they contain. Files and other types will return the data read in the form of a Buffer unless a format was specified.

If a format was specified, the read data will be (attempted) to parse from that format into an in-memory object.

If the file is in an errored state prior to the read, it will not be read and data will be null.

Returns

  • Promise.<Array.<module:read-path-state~ReadPathState>>

Source

throw(throwErrorsopt) → {Fairu}

Sets the flag to have Fairu throw an error if one is encountered (true), or simply halt the operation for that path (false). By default Fairu will throw an error (true). When the flag is false and an error occurs:

  • read() will return null value for the data property in the result.
  • write() may or may not occur or may only partially write.
  • touch() may or may not occur.

Calling this function without an argument will reset it to it's default (true).

Parameters

  • throwErrors Boolean <optional>
     true

    If true an error is thrown as soon as it is encountered, when false no errors are thrown and the next path operation is attempted.

Returns

Throws

Error when the throwErrors argument is not a boolean value.

Source

async

touch() → {Promise.<Array.<module:path-state~PathState>>}

Creates a blank file write or directory if the path does not exist, and ensures the directory tree is present.

The file access and modified time is updated on the path.

If the file is in an errored state prior to the write, it is skipped.

Returns

  • Promise.<Array.<module:path-state~PathState>>

Source

async

Deletes the files and/or directories discovered from the .with paths.

If the path is a directory, it is recursively deleted.

Returns

  • Promise.<Array.<module:path-state~PathState>>

Source

when(conditions) → {Fairu}

Sets the conditional callback that determines, per discovered path, that the file-system operation being performed can continue and be processed.

Calling this function without an argument or null will reset it to it's default (no conditional callback).

Parameters

  • conditions FairuCallback.Condition

    Conditional flags indicating what states of the path must appear to be true before proceeding with the operation for a path.

Returns

Example

// Discovering only paths that are writable with a minimum size of 1024 bytes.
let states = await Fairu
  .with('./*.js')
  .when(s => s.stats && s.stats.size > 1024 && s.writable)
  .discover();
console.log(states);

Throws

Error when the specified conditions are not a callback function.

Source

with(…paths) → {Fairu}

Specify the file-system paths (including glob patterns) you will be performing an operation on. You may optionally provide a callback that returns a path to use- the callback will be passed the path module as an argument.

Calling this resets the paths used in this Fairu operation, letting you daisy-chain multiple operations together, each starting with the with specification.

This function is not cummulative, specified paths will overwrite those set by a previous call.

Parameters

  • paths String | FairuCallback.Path <repeatable>

    The series of file-system paths or callback functions.

Returns

Examples

// Daisy chaining multiple operations:
await Fairu
  .with('./file1.txt', p => p.join('/home/', 'file2.txt'))
  .write(content)
  .with('./file3.txt')
  .write(otherContent);
// Using glob paths:
await Fairu
  .with('./**', './+(hello|greetings)?(world|mars|venus).txt')
  .read();

Throws

Error when a specified path is not a string or callback function.

Source

without(…paths) → {Fairu}

Specify the file-system paths (including glob patterns) you do not want to perform an operation on. You may optionally provide a callback that returns a path to use- the callback will be passed the path module as an argument.

This function is not cummulative, specified paths will overwrite those set by a previous call.

Parameters

  • paths String | FairuCallback.Path <repeatable>

    The series of file-system paths or callback functions.

Returns

Example

// Skipping over certain files, in this case finding all `.js` files without `.test.` in the file name:
Fairu.
  .with('./*.js')
  .without('./*.test.*')
  .discover();

Throws

Error when a specified path is not a string or callback function.

Source

async

write(content) → {Promise.<Array.<module:path-state~PathState>>}

Writes the content to the paths specified. If the file is already present, the content is overwritten. If the path is a directory, it will be created.

If a format was specified, the written data will be stringified into that format before being written.

If the file is in an errored state prior to the write, it is skipped.

Parameters

  • content String | Buffer

    The content to be written to path.

Returns

  • Promise.<Array.<module:path-state~PathState>>

Source