fairu.js

///<reference path="./fairu.d.js" />
///<reference path="./package-json.d.js" />
import path from 'path';
import fs from 'fs/promises';
import fsSync from 'fs';
import { constants } from 'fs';
import glob from 'glob';
import toml from '@iarna/toml';
import yaml from 'js-yaml';
import PathState from './path-state.js';
import ReadPathState from './read-path-state.js';

/**
 * @see https://nodejs.org/api/path.html
 * @callback FairuCallback.Path
 * @param {path.PlatformPath} p - The path module for constructing file-system paths.
 * @returns {String}
 */

/**
 * 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.
 */
class Fairu {
    constructor() {

        /**
         * The globbing options to apply to path discovery.
         * @see https://www.npmjs.com/package/glob#options
         * @type {glob.IOptions}
         */
        this.options = {
            absolute: true
        };

        /**
         * The metadata for the constructed Fairu operation.
         * @private
         */
        this.metadata = {
            /**
             * @type {Array.<String>}
             */
            with: [],
            /**
             * @type {Array.<String>}
             */
            without: [],
            /**
             * @type {FairuCallback.Condition}
             */
            when: null,
            /**
             * @type {Boolean}
             */
            throw: false,
            /**
             * @type {String}
             */
            format: null,
            /**
             * Default: 'utf8'
             * @type {String}
             */
            encoding: null,
            /**
             * Default: 0o666
             * @type {Number}
             */
            mode: null
        };
    }

    /**
     * Reads a `package.json` file from the given directory. This operation is synchronous.
     * @param {String} dir - The directory of the `package.json` file.
     * @returns {PackageJSON}
     */
    static packageJSON(dir) {
        return JSON.parse(fsSync.readFileSync(path.join(dir, 'package.json')));
    }

    /**
     * Stringifies an object into the specified format (yaml, toml, or json).
     * @throws Error when the format is unknown.
     * @throws Error when stringification fails.
     * @param {String} format - Can be either 'json', 'yaml', or 'json'.
     * @param {*} object - The object to stringify.
     * @param {Number} [space=4] - The number of spaces to use for indentations.
     * @returns {String}
     */
    static stringify(format, object, space = 4) {
        if (format) {
            if (/json/i.test(format)) {
                return JSON.stringify(object, null, space);
            } else if (/yaml/i.test(format)) {
                return yaml.dump(object, {
                    indent: space,
                    lineWidth: 120
                });
            } else if (/toml/i.test(format)) {
                return toml.stringify(object);
            }
        }
        throw new Error(`Unknown format "${format}".`);
    }

    /**
     * Attempts to parse the given input string using the specified format parser into an object.
     * @throws Error when the format is unknown.
     * @throws Error when parsing fails.
     * @param {String} format - Can be either 'json', 'yaml', or 'json'.
     * @param {*} inputString - The string to be parsed.
     * @param {String} [filePath] - The file path used in error/warning messages.
     * @returns {*}
     */
    static parse(format, inputString, filePath) {
        if (format) {
            if (/json/i.test(format)) {
                return JSON.parse(inputString);
            } else if (/yaml/i.test(format)) {
                return yaml.load(inputString, {
                    filename: filePath
                });
            } else if (/toml/i.test(format)) {
                return toml.parse(inputString);
            }
        }
        throw new Error(`Unknown format "${format}".`);
    }

    /**
     * Copies a file or directory (recursively) to another.
     * @param {String} source - The file or directory path to use as the source.
     * @param {String} destination - The file or directory to use as the destination.
     */
    static async cp(source, destination) {
        let stats = await fs.stat(source);
        await fs.mkdir(path.dirname(destination), { recursive: true });
        if (stats.isDirectory()) {
            await fs.cp(source, destination, { recursive: true });
        } else {
            await fs.copyFile(source, destination);
        }
    }

    /**
     * Moves a file or directory (recursively) to another.
     * @param {String} source - The file or directory path to use as the source.
     * @param {String} destination - The file or directory to use as the destination.
     */
    static async mv(source, destination) {
        await fs.mkdir(path.dirname(destination), { recursive: true });
        await fs.rename(source, destination);
    }

    /**
     * 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.
     * @throws Error when a specified path is not a string or callback function.
     * @param  {...String | FairuCallback.Path} paths - The series of file-system paths or callback functions. 
     * @returns {Fairu}
     * @example
     * // Daisy chaining multiple operations:
     * await Fairu
     *   .with('./file1.txt', p => p.join('/home/', 'file2.txt'))
     *   .write(content)
     *   .with('./file3.txt')
     *   .write(otherContent);
     * 
     * @example
     * // Using glob paths:
     * await Fairu
     *   .with('./**', './+(hello|greetings)?(world|mars|venus).txt')
     *   .read();
     */
    static with(...paths) {
        return new Fairu().with(...paths);
    }

    /**
     * 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.
     * @throws Error when a specified path is not a string or callback function.
     * @param  {...String | FairuCallback.Path} paths - The series of file-system paths or callback functions. 
     * @returns {Fairu}
     * @example
     * // Daisy chaining multiple operations:
     * await Fairu
     *   .with('./file1.txt', p => p.join('/home/', 'file2.txt'))
     *   .write(content)
     *   .with('./file3.txt')
     *   .write(otherContent);
     * 
     * @example
     * // Using glob paths:
     * await Fairu
     *   .with('./**', './+(hello|greetings)?(world|mars|venus).txt')
     *   .read();
     */
    with(...paths) {
        this.metadata.with = [];
        for (let p of paths) {
            let pathType = typeof p;
            if (pathType === 'function') {
                this.metadata.with.push(p(path));
            } else if (pathType === 'string') {
                this.metadata.with.push(p);
            } else if (pathType === 'undefined' || p === null) {
                continue;
            } else {
                throw new Error('The "paths" argument encountered a specified non-string/non-function path. Only callbacks and strings are allowed paths. If a null or undefined value is found it is skipped.');
            }
        }
        return this;
    }

    /**
     * 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.
     * @throws Error when a specified path is not a string or callback function.
     * @param  {...String | FairuCallback.Path} paths - The series of file-system paths or callback functions. 
     * @returns {Fairu}
     * @example
     * // Skipping over certain files, in this case finding all `.js` files without `.test.` in the file name:
     * Fairu.
     *   .with('./*.js')
     *   .without('./*.test.*')
     *   .discover();
     */
    without(...paths) {
        this.metadata.without = [];
        for (let p of paths) {
            let pathType = typeof p;
            if (pathType === 'function') {
                this.metadata.without.push(p(path));
            } else if (pathType === 'string') {
                this.metadata.without.push(p);
            } else if (pathType === 'undefined' || p === null) {
                continue;
            } else {
                throw new Error('The "paths" argument encountered a specified non-string/non-function path. Only callbacks and strings are allowed paths. If a null or undefined value is found it is skipped.');
            }
        }
        return this;
    }

    /**
     * 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).
     * @throws Error when the encoding value is specified and not a string.
     * @param {String} encoding - The file text encoding to use when reading and writing files.
     * @returns {Fairu}
     */
    encoding(encoding) {
        let encodingType = typeof encoding;
        if (encodingType !== 'undefined' && encoding !== null && encodingType !== 'string') {
            throw new Error('The "encoding" argument, when specified, must be a string.');
        }
        this.metadata.encoding = encoding || null;
        return this;
    }

    /**
     * Sets the file permissions for newly created files (affecting `append` and `write`) to the specified value, 
     * usually expressed in octal. By default the file mode is 0o666 (read-write all users and groups and others).
     * 
     * Calling this function without an argument or `null` will reset it to it's default.
     * @throws Error when the mode value is specified but not a valid value.
     * @param {Number} mode - The file permissions mode to use when appending and writing files.
     * @returns {Fairu}
     */
    permission(mode) {
        let modeType = typeof mode;
        if (modeType !== 'undefined' && mode !== null && modeType !== 'number') {
            throw new Error('The "mode" argument, when specified, must be a number.');
        }
        this.metadata.mode = mode || null;
        return this;
    }

    /**
     * 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`).
     * @throws Error when the `throwErrors` argument is not a boolean value.
     * @param {Boolean} [throwErrors=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 {Fairu}
     */
    throw(throwErrors) {
        if (typeof throwErrors === 'undefined') {
            throwErrors = true;
        } else if (typeof throwErrors !== 'boolean') {
            throw new Error('The "throwErrors" argument, when specified, must be a boolean.');
        }
        this.metadata.throw = !!throwErrors;
        return this;
    }

    /**
     * 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).
     * @throws Error when the specified `format` argument is not "json", "yaml", "toml".
     * @param {Fairu.Format} format - The format (or `null`) to use for reading & writing. Can be: "json", "toml", or
     *   "yaml".
     * @returns {Fairu}
     */
    format(format) {
        let formatType = typeof format;
        if (formatType !== 'undefined' && format !== null && formatType !== 'string') {
            throw new Error('The "format" argument, when specified, must be a string.');
        } else if (
            formatType !== 'undefined'
            && format !== null
            && format !== Fairu.Format.json
            && format !== Fairu.Format.toml
            && format !== Fairu.Format.yaml) {
            throw new Error(`The "format" argument, when specified, must be either "json", "toml", or "yaml. Instead "${format}" was specified.`);
        }
        this.metadata.format = format || null;
        return this;
    }

    /**
     * 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).
     * @throws Error when the specified conditions are not a callback function.
     * @param {FairuCallback.Condition} conditions - Conditional flags indicating what states of the path must appear
     *  to be true before proceeding with the operation for a path.
     * @returns {Fairu}
     * @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);
     */
    when(conditions) {
        let conditionsType = typeof conditions;
        if (conditionsType !== 'undefined' && conditions !== null) {
            if (conditionsType === 'function') {
                this.metadata.when = conditions;
            } else {
                throw new Error('The "conditions" argument must be a callback.');
            }
        } else {
            this.metadata.when = null;
        }
        return this;
    }

    /**
     * Asynchronously resolves a glob pattern.
     * @param {String} pattern - The glob pattern to resolve.
     * @param {String | Array.<String>} [ignore] - An ignore pattern to exclude results from the matching file paths.
     * @returns {Promise.<Array.<String>>}
     * @private
     */
    async _globFind(pattern, ignore) {
        let hasDirTail = pattern.endsWith(path.sep);
        return await new Promise((resolve, reject) => {
            glob(pattern, Object.assign({}, this.options, {
                ignore: ignore
            }), (err, matches) => {
                if (err) reject(err);
                if (matches.length === 0 && glob.hasMagic(pattern, this.options) === false && (!ignore || Array.isArray(ignore) && ignore.length === 0)) {
                    matches.push(path.resolve(pattern));
                }
                if (hasDirTail) {
                    //re-affix the directory seperater, as it was on the tail, thus only directories should be found.
                    for (let i = 0; i < matches.length; i++) {
                        matches[i] += path.sep;
                    }
                }
                return resolve(matches);
            });
        });
    }

    /**
     * Expands globbed paths and discovers information about them, returning a record for each path (including invalid)
     * ones.
     * @throws Error when the `throw` flag is true and an error discovering paths is encountered.
     * @throws Error when the "when" condition for the Fairu operation fails to return a boolean result.
     * @param {FairuCallback.PathStateCreate} [create] - Optional callback that returns an initialized `PathState`.
     * @param {FairuCallback.DiscoverErrorHandler} [handleError] - Optional callback to handle an error if it occurs. 
     * @returns {Promise.<Array.<PathState>>}
     */
    async discover(create, handleError) {
        //de-glob
        let paths = [];
        for (let globPath of this.metadata.with) {
            let foundPaths = await this._globFind(globPath, this.metadata.without);
            //ensure the path only shows up once in the results.
            for (let fp of foundPaths) {
                if (paths.indexOf(fp) <= -1) {
                    paths.push(fp);
                }
            }
        }
        //iterate & discover.
        let results = [];
        for (let p of paths) {
            //build default state
            let state = null;
            if (typeof create === 'function') {
                state = create(p); //allow other Fairu operations to hijack discover for their usage.
            } else {
                state = new PathState(p);
                state.operation = 'discover';
            }
            state.exists = true;
            try {
                //gather dicey details
                state.stats = await fs.stat(p); //allowed to fail
                try {
                    await fs.access(p, constants.R_OK);
                    state.readable = true;
                } catch (readErr) { } // eslint-disable-line no-empty
                try {
                    await fs.access(p, constants.W_OK);
                    state.writable = true;
                } catch (writeErr) { } // eslint-disable-line no-empty
            } catch (err) {
                state.error = err;
                if (typeof handleError === 'function') {
                    state.error = handleError(err, state);
                }
                if (state.error) {
                    if (err.code === 'ENOENT') {
                        state.exists = false;
                        if (this.metadata.throw) {
                            throw err;
                        } else {
                            state.error = null;
                        }
                    } else if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
            if (this.metadata.when) {
                let whenResult = this.metadata.when(state);
                if (whenResult === true) {
                    results.push(state);
                } else if (whenResult !== false) {
                    throw new Error(`The "when" condition for the Fairu operation "${state.operation}" failed to return a boolean result.`);
                }
            } else {
                results.push(state);
            }
        }
        return results;
    }

    /**
     * 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.<ReadPathState>>}
     */
    async read() {
        let states = await this.discover(tp => new ReadPathState(tp));
        for (let state of states) {
            if (!state.error) { //skip paths in an errored state
                try {
                    if (state.stats.isDirectory()) {
                        //path points to a directory, read the file list instead.
                        state.data = await fs.readdir(state.path);
                    } else {
                        state.data = await fs.readFile(state.path, {
                            encoding: this.metadata.encoding
                        });
                        if (this.metadata.format) {
                            state.data = Fairu.parse(
                                this.metadata.format,
                                state.data.toString(this.metadata.encoding || undefined),
                                state.path
                            );
                        }
                    }
                } catch (err) {
                    state.error = err;
                    if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
        }
        return states;
    }

    /**
     * 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.
     * @param {String|Buffer} content - The content to be written to path.
     * @returns {Promise.<Array.<PathState>>}
     */
    async write(content) {
        let states = await this.discover(tp => {
            let ps = new PathState(tp);
            ps.operation = 'write';
            return ps;
        });
        for (let state of states) {
            if (!state.error) { //skip paths in an errored state
                try {
                    if (state.path.endsWith(path.sep) || (state.stats && state.stats.isDirectory())) {
                        await fs.mkdir(state.path, { recursive: true });
                    } else {
                        await fs.mkdir(path.dirname(state.path), { recursive: true });
                        if (this.metadata.format) {
                            content = Fairu.stringify(this.metadata.format, content);
                        }
                        await fs.writeFile(state.path, content, {
                            encoding: this.metadata.encoding,
                            mode: this.metadata.mode
                        });
                    }
                } catch (err) {
                    state.error = err;
                    if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
        }
        return states;
    }

    /**
     * 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.
     * @param {String|Buffer} content - The content to be written to path.
     * @returns {Promise.<Array.<PathState>>}
     */
    async append(content) {
        let states = await this.discover(tp => {
            let ps = new PathState(tp);
            ps.operation = 'write';
            return ps;
        });
        for (let state of states) {
            if (!state.error) { //skip paths in an errored state
                try {
                    if (state.path.endsWith(path.sep) || (state.stats && state.stats.isDirectory())) {
                        await fs.mkdir(state.path, { recursive: true });
                    } else {
                        await fs.mkdir(path.dirname(state.path), { recursive: true });
                        if (this.metadata.format) {
                            content = Fairu.stringify(this.metadata.format, content);
                        }
                        await fs.appendFile(state.path, content, {
                            encoding: this.metadata.encoding,
                            mode: this.metadata.mode
                        });
                    }
                } catch (err) {
                    state.error = err;
                    if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
        }
        return states;

    }

    /**
     * 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.<PathState>>}
     */
    async touch() {
        let states = await this.discover(
            tp => {
                let ps = new PathState(tp);
                ps.operation = 'touch';
                return ps;
            },
            (err, state) => {
                if (err.code === 'ENOENT') {
                    state.exists = false;
                    state.error = null;
                    return null;
                }
                return err;
            }
        );
        for (let state of states) {
            if (!state.error) { //skip paths in an errored state
                try {
                    let stamp = new Date();
                    if (state.path.endsWith(path.sep) || (state.stats && state.stats.isDirectory())) {
                        await fs.mkdir(state.path, { recursive: true });
                    } else {
                        await fs.mkdir(path.dirname(state.path), { recursive: true });
                        await fs.appendFile(state.path, Buffer.alloc(0));
                    }
                    await fs.utimes(state.path, stamp, stamp);
                } catch (err) {
                    state.error = err;
                    if (err.code === 'ENOENT') {
                        state.exists = false;
                    } else if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
        }
        return states;
    }

    /**
     * Deletes the files and/or directories discovered from the `.with` paths.
     * 
     * If the path is a directory, it is recursively deleted. 
     * @returns {Promise.<Array.<PathState>>}
     */
    async unlink() {
        let states = await this.discover(tp => {
            let ps = new PathState(tp);
            ps.operation = 'unlink';
            return ps;
        });
        for (let state of states) {
            if (!state.error) { //skip paths in an errored state
                try {
                    if (state.path.endsWith(path.sep) || (state.stats && state.stats.isDirectory())) {
                        await fs.rm(state.path, { recursive: true });
                    } else {
                        await fs.unlink(state.path);
                    }
                } catch (err) {
                    state.error = err;
                    if (this.metadata.throw) {
                        throw err;
                    }
                }
            }
        }
        return states;
    }

}

/**
 * @enum {String}
 */
Fairu.Format = {
    yaml: 'yaml',
    toml: 'toml',
    json: 'json'
};

export { Fairu as default };