@wider/utils_proto/proto_function/index.js

A set of extensions to basic objects giving uniform behaviour in various technical environments

'use strict';

const $moduleName = "@wider/utils_proto/proto_function";

/** 
 * Additional methods for the javascript **Function** object
 * @module @wider/utils_proto/proto_function
 *
 * @copyright Copyright (C) 1985..2021 Martin Baker. http://y-d-r.co.uk
 * @author Martin W Baker
 * @license ISC Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 */

const functionPrototypes = {
    /**
     * Create a documentation of the code description of the calling function
     * @function describe()
     * @deprecated Obsolete because `fn.caller` has not been deprecated in javascript
     * @returns {string} HTML formatted string as <div/>
     */
    wider_describe: function () {
        const $functionName = "Function.prototype.wider_describe";
        const result = [];
        let fn;
        try {
            fn = this;

            while (fn) {
                result.push("<p class=\"ydr-describe\">" +
                    (this.name || (this + "").split(/^[^\(]*function |\(/)[0] || "anonymous") +
                    "");
                fn = fn.caller;
            }
        } catch (e) {
            result.push("<p class=\"developer\">Failed during Function.prototype.wider_describe() in " + $functionName + "" +
                "<p class=\"code\">" + e.message.wider_HTMLencode() + "");
        }


        let name = (fn + "").split(/[\(\)]/)[1] || "<anonymous>".wider_HTMLencode();
        let moduleName = (fn + "").split(/\$functionName[^"]*"/);
        moduleName = (moduleName.length > 1) ?
            moduleName[1].split(/"/)[0].wider_HTMLencode() :
            "<unknown>".wider_HTMLencode();

        result.push(`<p class="indent">Function name = "${name}" within "${moduleName}"`);

        return result.join("").wider_wrapAsOK($functionName, null, "Function Prototype Describe");
    }
};

/**
 * @private
 * @param {object} target - this will normally be the javascript Function object - but if you dont want to change that object then provide your own equivalent
 */
function assignFunction(target = Function) {

    /* set the prototype of the javascript Function object or if it already exists then extend it */
    if (target.prototype)
        Object.assign(target.prototype, functionPrototypes);
    else
        target.prototype = functionPrototypes;

    return functionPrototypes;
}

assignFunction.$moduleName = $moduleName;
if (global.$wider)
    global.$wider.registry.register($moduleName, assignFunction, "protoFunction","utils");
export default assignFunction;