rtng.js

/**
 * 
 * RTNG.js is a "Random Text and Number Generator"
 * written by Michael Kubina
 * 
 * https://github.com/michaelkubina/rtng-js
 * 
 * 2023-02-08
 * 
 */

class rtng {

    /**
     * 
     */
    constructor() {
        this.url;
        this.promise;
        this.externals;
    }

    /**
     * 
     * @param {any} url
     */
    async loadSchema(url) {
        this.url = url;
        let response = await fetch(url);
        this.promise = await response.json();
    }

    /**
     * 
     * @param {any} external
     * @param {any} prepend_path
     */
    adjustExternalTemplatePaths(external, prepend_path) {
        let debug = false;

        //console.log(">>> external");
        //console.log(external);

        var elements = Object.keys(external);
        //console.log(elements);

        for (const element of elements) {
            if (typeof (external[element]) == "object" && element != "$sequence") {
                //console.log(element + " is an object");
                //console.log(">>> go deeper");
                this.adjustExternalTemplatePaths(external[element], prepend_path);
            }
            else if (element == "$sequence") {
                //console.log(element + " is a @sequence");
                //console.log(external[element]);
                for (let idx in external[element]) {
                    let primitive = Object.keys(external[element][idx]);
                    if (primitive == "template") {
                        //console.log(external[element][idx]['template']);
                        external[element][idx]['template'] = prepend_path + external[element][idx]['template'];
                        //console.log(external[element][idx]['template']);
                    }
                }
            }
        }
    }

    /**
     * 
     */
    async loadExternal() {
        if (this.promise['@external'] != this.url) {
            for (let idx in this.promise['@external']) {
                let datapack = await rtng.init(this.promise['@external'][idx]);
                let prepend_path = "@external." + idx + ".";
                this.adjustExternalTemplatePaths(datapack['promise'], prepend_path);
                this.promise['@external'][idx] = datapack['promise'];
            }
        }
    }

    /**
     * 
     * @param {any} url
     * @returns
     */
    static async init(url) {
        const object = new rtng();
        await object.loadSchema(url);
        await object.loadExternal();
        return object;
    }

    /**
     * Returns the value of the property at the given path. Depending on the path this coul be either string/number, array or an object.
     * https://stackoverflow.com/questions/38640072/how-to-get-nested-objects-in-javascript-by-an-string-as-a-bracket-notation
     * @param {path} path
     */
    async getValue(path) {
        let debug = false;

        // start debug
        if (debug) {
            console.log(">>> getValue()");
            console.log("path: " + path);
        }

        let value = path.replace(/\[([^\]]+)]/g, '.$1').split('.').reduce(function (o, p) {
            return o[p];
        }, await this.promise);

        if (debug) {
            console.log(value);
            console.log("<<< getValue()");
        }
        return value;
    }

    /**
     * Returns an array of full paths to all members at the current path
     * @param {path} path - the path from where to list all members
     */
    async listMembers(path = '') {
        // return all members from datapack root
        if (path === '') {
            return Object.keys(await this.promise);
        }
        // get the value at the path
        let value = await this.getValue(path);
        // prevent to list string as indexed array
        if (typeof value === 'string' || value instanceof String) {
            return typeof value;
        } else {
            // get all keys from path
            let allElements = Object.keys(value);
            // add key to path in dot-notation
            allElements.forEach((item, index) => allElements[index] = path + "." + item);
            //console.log(allElements);
            return allElements;
        }
    }

    /**
     * Returns an array only of those members of the current path with a @sequence as a child
     * @param {path} path - the path from where to list all templates
     */
    async listTemplates(path = '') {
        let members = [];
        let templates = [];

        // gather all members
        if (path === '') {
            members = Object.keys(await this.promise);
        } else {
            members = Object.keys(await this.getValue(path));
            path += '.';
        }

        // check wether a member has a @sequence
        for (let idx in members) {
            if (await this.getValue(path + members[idx] + '.@sequence') != undefined) {
                templates.push(members[idx]);
            }
        }

        return templates;
    }

    /**
     * Returns an array only of those members of the current path that are 
     * objects and do not have a @sequence as a child
     * @param {path} path - the path from where to list all categories
     */
    async listCategories(path = '') {
        let members = [];
        let categories = [];

        // gather all members
        if (path === '') {
            members = Object.keys(await this.promise);
        } else {
            members = Object.keys(await this.getValue(path));
            path += '.';
        }

        // check wether a member is an object and does not have a @sequence
        for (let i in members) {
            if (await this.getValue(path + members[i] + '.@sequence') === undefined) {
                let submembers = Object.keys(await this.getValue(path + members[i]));
                let has_category = false;
                for (let j in submembers) {
                    if (typeof await this.getValue(path + members[i] + '.' + submembers[j]) === 'object') {
                        has_category = true;
                    }
                }
                if (has_category) {
                    categories.push(path + members[i]);
                }
            }
        }

        return categories;
    }

    /**
     * Returns an array only of those members of the current path that are 
     * strings or arrays and therefore metadata.
     * @param {path} path - the path from where to list all categories
     */
    async listMetadata(path = '') {
        let members = [];
        let metadata = [];

        // gather all members
        if (path === '') {
            members = Object.keys(await this.promise);
        } else {
            members = Object.keys(await this.getValue(path));
            path += '.';
        }

        // check wether a member is an object and does not have a @sequence
        for (let i in members) {
            let membertype = typeof await this.getValue(path + members[i]);
            if (membertype === 'string') {
                metadata.push(path + members[i]);
            } else if (membertype === 'object') {
                let membervalue = await this.getValue(path + members[i]);
                if (Array.isArray(membervalue)) {
                    metadata.push(path + members[i]);
                }
            }
        }
        return metadata;
    }

    /**
     * checks if element has specific name
     * @param {any} path
     * @param {any} name
     */
    isElement(path, name) {
        // check wether it is .title, .description, .anything etc.
        if (path.endsWith('.' + name)) {
            return true;
        }
        return false;
    }

    /**
     * checks if element is object-element or a value/literal
     * @param {any} path
     */
    async isObject(path) {
        let debug = false;

        // check wether it is new hierarchy
        if (typeof await this.getValue(path) === 'object' && Array.isArray(await this.getValue(path)) == false) {
            console.log(path + " is object");
            return true;
        }
        if (debug) console.log(path + " is NOT object");

        return false;
    }

    /**
     * checks if element has a sequence
     * @param {any} path
     */
    isSequence(path) {
        return this.isElement(path, '@sequence');
    }

    /**
     * checks if element has a external
     * @param {any} path
     */
    isExternal(path) {
        return path.startsWith('@external');
    }

    /**
     * add punctuation and conjunction to list
     * @param {any} list
     * @param {any} punctuation
     * @param {any} conjunction
     */
    applyPunctuation(list, punctuation, conjunction) {
        // abort on empty list or list with only one item
        if (list.length < 2) {
            return list;
        }

        // add puncuation
        if (punctuation) {
            // add punctuation to all elements in array except the two last
            for (let i = 0; i < list.length - 2; i++) {
                list[i] = list[i] + punctuation;
            }
            if (conjunction) {
                // add conjunction before the last
                list.splice(list.length - 1, 0, conjunction);
            } else {
                // if there is no conjunction add punctuation instead 
                list[list.length - 2] = list[list.length - 2] + punctuation;
            }
            return list;
        }
    }

    /**
     * Returns a sorted list of values (lexicographically or numerical)
     * @param {any} list
     * @param {any} sort
     */
    applySort(list, sort) {
        // abort on empty list or list with only one item and when no sorting direction
        if (list.length < 2 || sort == "none") {
            return list;
        }

        // sort string lexicographically and numbers numerically
        if (typeof(list[0]) == "number" && sort == "asc") {
            return list.sort(function (a, b) { return a - b });
        }
        if (typeof (list[0]) == "number" && sort == "desc") {
            return list.sort(function (a, b) { return b - a });
        }
        if (typeof (list[0]) == "string" && sort == "asc") {
            return list.sort();
        }
        if (typeof (list[0]) == "string" && sort == "desc") {
            return list.sort().reverse();
        }
    }

    /**
     * 
     * @param {any} min_picks
     * @param {any} max_picks
     * @param {any} min
     * @param {any} max
     * @param {any} steps
     * @param {any} unique
     * @returns
     */
    getPicks(min_picks, max_picks, min, max, steps, unique) {
        let debug = false;

        if (debug) {
            console.log(">>> getPicks()");
            console.log("min_picks: " + min_picks);
            console.log("max_picks: " + max_picks);
            console.log("min: " + min);
            console.log("max: " + max);
            console.log("steps: " + steps);
            console.log("unique: " + unique);
        }

        let result = [];

        // a number between min_picks (inclusive) and max_picks (inclusive)
        let picks = Math.floor(Math.random() * (max_picks - min_picks + 1) + min_picks);
        if (debug) console.log("> picks: " + picks);

        // abort on no picks
        if (!picks) {
            if (debug) console.log("<<< getPicks()");
            return result = [''];
        }

        // random pick (unique or repeatable)
        for (let i = 1; i <= picks; i++) {
            // add random list item
            let random_number;
            if (unique) {
                let unique_pick = false;
                while (!unique_pick) { // TIMEOUT ENDLESS LOOP BUG???
                    random_number = Math.round(Math.random() * ((max - min) / steps)); // random pick
                    random_number = random_number * steps + min;
                    if (debug) console.log(random_number);
                    if (result.includes(random_number)) {
                        unique_pick = false; // not necessary
                    } else {
                        result.push(random_number);
                        unique_pick = true;
                    }
                }
            } else {
                random_number = Math.round(Math.random() * ((max - min) / steps)); // random pick
                random_number = random_number * steps + min;
                result.push(random_number);
            }
        }
        if (debug) console.log("<<< getPicks()");
        return result;
    }

    /**
     * 
     * @param {any} output
     * @param {any} sort
     * @param {any} punctuation
     * @param {any} conjunction
     * @returns
     */
    processOutput(output, sort, punctuation, conjunction) {
        let debug = false;

        // start debug
        if (debug) console.log(">>> processOutput()");

        // sort
        if (sort != "none") {
            output = this.applySort(output, sort);
            if (debug) {
                console.log("> sort >");
                console.log(output);
            }
        }

        // punctuate
        if (punctuation || conjunction) {
            output = this.applyPunctuation(output, punctuation, conjunction);
            if (debug) {
                console.log("> punctuate >");
                console.log(output);
            }
        }

        // join
        output = output.join(' ');
        if (debug) {
            console.log("> join >");
            console.log(output);
        }

        // start debug
        if (debug) console.log("<<< processOutput()");

        return output
    }

    /**
     * return a parameter object preseeded with defaults where necessary
     * @param {any} object
     * @returns
     */
    async loadParameters(object) {
        let debug = false;

        // defaults
        let params = {

            // picking
            min_picks: 1,
            max_picks: 1,
            unique: true,

            // processing
            sort: "none",
            punctuation: '',
            conjunction: '',
        }

        // optional
        if (object != undefined) {
            if (await object.min_picks >= 0) params.min_picks = await object.min_picks;
            if (await object.max_picks >= 0) params.max_picks = await object.max_picks;
            if (typeof (await object.unique) == "boolean") params.unique = await object.unique;
            if (await object.sort) params.sort = await object.sort;
            if (await object.punctuation) params.punctuation = await object.punctuation;
            if (await object.conjunction) params.conjunction = await object.conjunction;
        }

        // debug parameters
        if (debug) {
            console.log("min_picks: " + params.min_picks);
            console.log("max_picks: " + params.max_picks);
            console.log("unique: " + params.unique);
            console.log("sort: " + params.sort);
            console.log("punctuation: " + params.punctuation);
            console.log("conjunction: " + params.conjunction);
        }

        return params;
    }

    /**
     * 
     * @param {any} object
     * @returns
     */
    async parseString(object) {
        let debug = false;

        // start debug
        if (debug) console.log(">>> BEGIN PARSING STRING");
        if (debug) console.log(object);

        // output
        let output = [];

        let params = await this.loadParameters(object.params);

        // if single value, return directly
        if (typeof object.string === 'string') {
            // end debug
            if (debug) console.log("<<< END PARSING STRING");
            return object.string;
        }

        // if just an array and nothing more
        if (Object.keys(object).length == 1) {
            // pick just one
            let idx = this.getPicks(1, 1, 0, object.string.length - 1, 1, true);
            // end debug
            if (debug) console.log("<<< END PARSING STRING");
            return object.string[idx];
        }

        // required
        let number_of_items = await object.string.length;

        // pick
        let picks = this.getPicks(params.min_picks, params.max_picks, 0, number_of_items - 1, 1, params.unique);
        if (debug) {
            console.log("> picks (index) >");
            console.log(picks);
        }
        for (let i in picks) {
            output.push(object.string[picks[i]]);
        }
        if (debug) {
            console.log("> picks (value) >");
            console.log(output);
        }

        // process output
        output = this.processOutput(output, params.sort, params.punctuation, params.conjunction);

        // end debug
        if (debug) console.log("<<< END PARSING STRING");

        return output;
    }

    /**
     * parse a number object within a sequence
     * @param {any} object
     */
    async parseNumber(object) {
        let debug = false;

        // start debug
        if (debug) console.log(">>> BEGIN PARSING NUMBER");

        // output
        let output = [];

        // defaults
        let min;
        let max;
        let steps = 1;

        let params = await this.loadParameters(object.params);

        // if single value, return directly
        if (typeof object.number === 'number') {
            // end debug
            if (debug) console.log("<<< END PARSING NUMBER");
            return object.number;
        }

        // if just an array and nothing more
        if (Object.keys(object).length == 1 && object.number instanceof Array) {
            // pick just one
            let idx = this.getPicks(1, 1, 0, object.number.length - 1, 1, true);
            // end debug
            if (debug) console.log("<<< END PARSING NUMBER");
            return object.number[idx];
        } 

        // get required
        if (await object.number.min) min = await object.number.min;
        if (await object.number.max) max = await object.number.max;

        // get optional
        if (await object.number.steps > 0) steps = await object.number.steps;

        // debug parameters
        if (debug) {
            console.log("min: " + min);
            console.log("max: " + max);
            console.log("steps: " + steps);
        }

        // if an array and additional parameters
        if (Object.keys(object).length > 1 && object.number instanceof Array) {
            // pick
            let picks = this.getPicks(params.min_picks, params.max_picks, 0, object.number.length - 1, 1, params.unique);
            if (debug) {
                console.log("> picks (index) >");
                console.log(picks);
            }
            for (let i in picks) {
                output.push(object.number[picks[i]]);
            }
            if (debug) {
                console.log("> picks (value) >");
                console.log(output);
            }
        } else {
            // if pick via parameters
            output = this.getPicks(params.min_picks, params.max_picks, min, max, params.steps, params.unique);
            if (debug) {
                console.log("> pick >");
                console.log(output);
            }
        }

        // process output
        if (params.punctuation || params.conjunction) {
            output = this.processOutput(output, params.sort, params.punctuation, params.conjunction);
        }

        // end debug
        if (debug) console.log("<<< END PARSING NUMBER");

        return output;
    }

    /**
     * parse a template object 
     * @param {any} path
     */
    async parseTemplate(path) {
        // debug flag
        let debug = false;

        // start debugging
        if (debug) console.log('>>> parseTemplate(' + path + ')');

        // return object
        let output = [];

        // get the sequence objects at the path
        let sequence = await this.getValue(path + '.@sequence');
        if (debug) console.log('> sequence');
        if (debug) console.log(sequence);

        // abort if no sequence objects and thus not a template
        if (sequence === undefined) {
            if (debug) console.log('<<< parseTemplate(' + path + ')');
            return 'ERROR - "' + path + '" is not a template';
        }

        // go through the list of objects
        for await (const sequence_object of sequence) {
            if (debug) console.log('> sequence_object');
            if (debug) console.log(sequence_object);

            if ('string' in sequence_object) {
                output.push(await this.parseString(sequence_object));
            }
            else if ('number' in sequence_object) {
                output.push(await this.parseNumber(sequence_object));
            }
            else if ('template' in sequence_object) {
                let params = await this.loadParameters(sequence_object.params);
                if (debug) console.log(params);

                // TODO: make sure not to fall into infinite loop!!!???

                // if single value, return directly
                if (typeof sequence_object.template === 'string') {
                    // end debug
                    if (debug) console.log('> end parsing @sequence');
                    output.push(await this.parseTemplate(sequence_object.template));
                }

                // if just an array and nothing more
                if (Object.keys(sequence_object).length == 1) {
                    // pick just one
                    let idx = this.getPicks(1, 1, 0, sequence_object.template.length - 1, 1, true);
                    // end debug
                    if (debug) console.log('> end parsing @sequence');
                    output.push(await this.parseTemplate(sequence_object.template[idx]));
                }

                // required
                let number_of_items = await sequence_object.template.length;

                // pick
                let picks = this.getPicks(params.min_picks, params.max_picks, 0, number_of_items - 1, 1, params.unique);
                if (debug) {
                    console.log("> picks (index) >");
                    console.log(picks);
                }
                for (let i in picks) {
                    output.push(await this.parseTemplate(sequence_object.template[picks[i]]));
                }
                if (debug) {
                    console.log("> picks (value) >");
                    console.log(output);
                }

                // process output
                output = this.processOutput(output, params.sort, params.punctuation, params.conjunction);
            }
        }
        if (debug) console.log('> end parsing @sequence');

        if (output instanceof Array) {
            if (output.length > 1) return output.join(' ');
            else return output[0];
        } else {
            return output;
        }
    }

    /**
     * checks if a element is a template (= has a @sequence)
     * @param {any} path
     */
    async isTemplate(path) {
        // get a list of paths of all sub-elements for a given path
        let elements = await this.listMembers(path);

        // if it's actually a list
        if (Array.isArray(await elements)) {
            // look if it has a @sequenceitem
            for await (const item of elements)
                if (item.endsWith('.@sequence')) {
                    return true;
                }
        }
        return false;
    }
}