nope/lib/parsers/open-api/OpenApiParser.ts

/**
 * @author Martin Karkowski
 * @email m.karkowski@zema.de
 * @create date 2021-11-11 11:36:37
 * @modify date 2021-11-11 11:36:37
 * @desc [description]
 */


import { readFile } from "fs/promises";
import * as handlebars from "handlebars";
import { ILogger } from "js-logger";
import { join, relative } from "path";
import { createFile, createPath } from "../../helpers/fileMethods";
import { deepClone } from "../../helpers/objectMethods";
import { replaceAll } from "../../helpers/stringMethods";
import { IJsonSchema } from "../../types/IJSONSchema";
import { INopeDescriptorFunctionParameter } from "../../types/nope/nopeDescriptor.interface";
import { IFunctionOptions, IParsableDescription } from "../../types/nope/nopeModule.interface";

/**
 * Helper function to merge the Parameters into 1 description.
 * @param elements 
 */
function _unifySchema(elements: INopeDescriptorFunctionParameter[], options: {
    sharedDefinitions: boolean,
    logger?: ILogger,
}) {
    const ret: IJsonSchema = {
        type: "object",
        properties: {},
        required: []
    };

    for (const item of elements) {

        if (options.sharedDefinitions) {
            item.schema.definitions = undefined;
            item.schema.$schema = undefined;
        }

        // Assign the Schema
        ret.properties[item.name] = item.schema as any as IJsonSchema;

        // If the Element is Optional,
        if (!item.optional) {
            ret.required.push(item.name);
        }
    }

    return ret;
}

/**
 * Function, to parse a description to an Open-API Element.
 * @param description 
 * @param options 
 */
export async function parseModuleToOpenAPI(description: IParsableDescription, options: {
    outputDir: string,
    sharedDefinitions: boolean,
    mode: "js" | "ts",
    logger?: Logger,
}): Promise<void> {

    const _description = deepClone(description);

    // load the Template.
    const template = await readFile(join(process.cwd(), "lib", "parsers", "open-api", "templates", "method." + options.mode + ".handlebars"), {
        encoding: "utf-8"
    });

    // Renderfuncting
    const renderAPI = handlebars.compile(template);

    await createPath(join(options.outputDir));

    // Now iterate over the Methods of the Module and find parsable Methods.
    for (const [idx, method] of _description.methods.entries()) {
        // Test if the Method contains some functions in the input / Output:
        const parsedInputs = JSON.stringify(method.schema.inputs);
        const parsedOutput = JSON.stringify(method.schema.outputs);
        if (!parsedInputs.includes("\"function\"") && !parsedOutput.includes("\"function\"")) {
            // The Method should be parseable.

            // 1. Specify the Mode (No Params =  GET, else POST)
            (method as any).mode = method.schema.inputs.length > 0 ? "POST" : "GET";

            (method as any).required = method.schema.inputs.filter(param => !param.optional).map(param => param.name);
            (method as any).hasInput = method.schema.inputs.length > 0;

            // Now adapt the Schema of the Method.
            // Iterate over the Inputs, add a Description if not provided
            // And determine whehter the Parameters are required or not. 
            method.schema.inputs = method.schema.inputs.map(param => {

                // Provide a Description. (If not provided)
                param.description = param.description || "Not provided";

                if (options.sharedDefinitions) {
                    param.schema.definitions = undefined;
                    param.schema.$schema = undefined;
                }

                // Parse the Schema in here.
                (param as any).parsedSchema = JSON.stringify(param.schema);

                return param;
            });

            // Make shure the Return type isnt an array
            method.schema.outputs = Array.isArray(method.schema.outputs) ?
                _unifySchema(method.schema.outputs, options) :
                method.schema.outputs;

            if (options.sharedDefinitions) {
                method.schema.outputs.definitions = undefined;
                method.schema.outputs.$schema = undefined;
            }

            // Add an Description to the result.
            (method as any).resultDescription = method.schema.outputs.description || "Not Provided";
            // And add a Schema for the Return type.
            (method as any).parsedOutput = JSON.stringify(method.schema.outputs);
            (method as any).parsedInput = JSON.stringify(_unifySchema(method.schema.inputs, options));
            (method as any).hasInput = method.schema.inputs.length > 0;
            (method as any).tag = description.name;

            // Determine the Filename.
            const fileDir = join(options.outputDir, _description.name, "{instance}", "methods");
            const fileName = join(fileDir, method.id + "." + options.mode);

            // Determine the Import Pathes.
            const imports = [
                {
                    dir: join(process.cwd(), "lib", "types", "nope"),
                    fileName: "nopeDispatcher.interface",
                    name: "pathOfDispatcher"
                },
                {
                    dir: join(process.cwd(), "lib", "helpers"),
                    fileName: "dispatcherPathes",
                    name: "pathOfHelper"
                }
            ];

            for (const imp of imports) {
                const relativDir = relative(fileDir, imp.dir);
                (method as any)[imp.name] = replaceAll(join(relativDir, imp.fileName), "\\", "/");
            }

            // Write down the Schema:
            await createFile(
                // Generate the Path.
                fileName,
                renderAPI(method)
            );

            if (options.logger) {
                options.logger.info("Generated -> " + fileName);
            }
        } else if (options.logger) {
            options.logger.warn("parser can not convert: \"" + description.name + "." + method.id + "\". The Function contains functions as parameters");
        }
    }
}

/**
 * Function, to parse a description to an Open-API Element.
 * @param description 
 * @param options 
 */
export async function parseFunctionToOpenAPI(description: IFunctionOptions, options: {
    outputDir: string,
    sharedDefinitions: boolean,
    mode: "js" | "ts",
    logger?: Logger,
}): Promise<void> {

    const _description = deepClone(description);

    // load the Template.
    const template = await readFile(join(process.cwd(), "lib", "parsers", "open-api", "templates", "function." + options.mode + ".handlebars"), {
        encoding: "utf-8"
    });

    // Renderfuncting
    const renderAPI = handlebars.compile(template);

    await createPath(join(options.outputDir));

    // Now iterate over the Methods of the Module and find parsable Methods.
    // Test if the Method contains some functions in the input / Output:
    const parsedInputs = JSON.stringify(_description.schema.inputs);
    const parsedOutput = JSON.stringify(_description.schema.outputs);
    if (!parsedInputs.includes("\"function\"") && !parsedOutput.includes("\"function\"")) {
        // The Method should be parseable.

        // 1. Specify the Mode (No Params =  GET, else POST)
        (_description as any).mode = _description.schema.inputs.length > 0 ? "POST" : "GET";

        // Now adapt the Schema of the Method.
        // Iterate over the Inputs, add a Description if not provided
        // And determine whehter the Parameters are required or not. 
        _description.schema.inputs = _description.schema.inputs.map(param => {

            // Provide a Description. (If not provided)
            param.description = param.description || "Not provided";

            if (options.sharedDefinitions) {
                param.schema.definitions = undefined;
                param.schema.$schema = undefined;
            }

            // Parse the Schema in here.
            (param as any).parsedSchema = JSON.stringify(param.schema);

            return param;
        });

        // Make shure the Return type isnt an array
        _description.schema.outputs = Array.isArray(_description.schema.outputs) ?
            _unifySchema(_description.schema.outputs, options) :
            _description.schema.outputs;

        if (options.sharedDefinitions) {
            _description.schema.outputs.definitions = undefined;
            _description.schema.outputs.$schema = undefined;
        }

        // Add an Description to the result.
        (_description as any).resultDescription = _description.schema.outputs.description || "Not Provided";
        // And add a Schema for the Return type.
        (_description as any).parsedOutput = JSON.stringify(_description.schema.outputs);
        (_description as any).tag = "generic-services";
        (_description as any).parsedInput = JSON.stringify(_unifySchema(_description.schema.inputs, options));
        (_description as any).hasInput = _description.schema.inputs.length > 0;
        (_description as any).required = _description.schema.inputs.filter(param => !param.optional).map(param => param.name);
        (_description as any).name = _description.id;

        // Determine the Filename.
        const fileDir = join(options.outputDir, "generic-services");
        const fileName = join(fileDir, _description.id + "." + options.mode);

        // Determine the Import Pathes.
        const imports = [
            {
                dir: join(process.cwd(), "lib", "types", "nope"),
                fileName: "nopeDispatcher.interface",
                name: "pathOfDispatcher"
            }
        ];

        for (const imp of imports) {
            const relativDir = relative(fileDir, imp.dir);
            (_description as any)[imp.name] = replaceAll(join(relativDir, imp.fileName), "\\", "/");
        }

        // Write down the Schema:
        await createFile(
            // Generate the Path.
            fileName,
            renderAPI(_description)
        );

        if (options.logger) {
            options.logger.info("Generated -> " + fileName);
        }
    } else if (options.logger) {
        options.logger.warn("parser can not convert: \"" + _description.id + "\". The Function contains functions as parameters");
    }
}