Modules (188)

DeprecationWarning

Description

Utilities functions to display deprecation warning in the console.

Dependencies

EventDispatcher

Functions Show Private Members

Private

_trimStack

Trim the stack so that it does not have the call to this module, and all the calls to require.js to load the extension that shows this deprecation warning.

    function _trimStack(stack) {
        var indexOfFirstRequireJSline;

        // Remove everything in the stack up to the end of the line that shows this module file path
        stack = stack.substr(stack.indexOf(")\n") + 2);

        // Find the very first line of require.js in the stack if the call is from an extension.
        // Remove all those lines from the call stack.
        indexOfFirstRequireJSline = stack.indexOf("requirejs/require.js");
        if (indexOfFirstRequireJSline !== -1) {
            indexOfFirstRequireJSline = stack.lastIndexOf(")", indexOfFirstRequireJSline) + 1;
            stack = stack.substr(0, indexOfFirstRequireJSline);
        }

        return stack;
    }

Public API

deprecateConstant

Create a deprecation warning and action for updated constants

old non-nullable string: Menu Id
new non-nullable string: Menu Id

    function deprecateConstant(obj, oldId, newId) {
        var warning     = "Use Menus." + newId + " instead of Menus." + oldId,
            newValue    = obj[newId];

        Object.defineProperty(obj, oldId, {
            get: function () {
                deprecationWarning(warning, true);
                return newValue;
            }
        });
    }

    // Define public API
    exports.deprecationWarning   = deprecationWarning;
    exports.deprecateEvent       = deprecateEvent;
    exports.deprecateConstant      = deprecateConstant;
});

Public API

deprecateEvent

Show a deprecation warning if there are listeners for the event

   DeprecationWarning.deprecateEvent(exports,
                                     MainViewManager,
                                     "workingSetAdd",
                                     "workingSetAdd",
                                     "DocumentManager.workingSetAdd",
                                     "MainViewManager.workingSetAdd");

outbound Object: the object with the old event to dispatch
inbound Object: the object with the new event to map to the old event
oldEventName string: the name of the old event
newEventName string: the name of the new event
canonicalOutboundName optional string: the canonical name of the old event
canonicalInboundName optional string: the canonical name of the new event

    function deprecateEvent(outbound, inbound, oldEventName, newEventName, canonicalOutboundName, canonicalInboundName) {
        // Mark deprecated so EventDispatcher.on() will emit warnings
        EventDispatcher.markDeprecated(outbound, oldEventName, canonicalInboundName);

        // create an event handler for the new event to listen for
        inbound.on(newEventName, function () {
            // Dispatch the event in case anyone is still listening
            EventDispatcher.triggerWithArray(outbound, oldEventName, Array.prototype.slice.call(arguments, 1));
        });
    }

Public API

deprecationWarning

Show deprecation warning with the call stack if it has never been displayed before.

message non-nullable string: The deprecation message to be displayed.
oncePerCaller optional boolean: If true, displays the message once for each unique call location. If false (the default), only displays the message once no matter where it's called from. Note that setting this to true can cause a slight performance hit (because it has to generate a stack trace), so don't set this for functions that you expect to be called from performance- sensitive code (e.g. tight loops).
callerStackPos optional number: Only used if oncePerCaller=true. Overrides the `Error().stack` depth where the client-code caller can be found. Only needed if extra shim layers are involved.

    function deprecationWarning(message, oncePerCaller, callerStackPos) {
        // If oncePerCaller isn't set, then only show the message once no matter who calls it.
        if (!message || (!oncePerCaller && displayedWarnings[message])) {
            return;
        }

        // Don't show the warning again if we've already gotten it from the current caller.
        // The true caller location is the fourth line in the stack trace:
        // * 0 is the word "Error"
        // * 1 is this function
        // * 2 is the caller of this function (the one throwing the deprecation warning)
        // * 3 is the actual caller of the deprecated function.
        var stack = new Error().stack,
            callerLocation = stack.split("\n")[callerStackPos || 3];
        if (oncePerCaller && displayedWarnings[message] && displayedWarnings[message][callerLocation]) {
            return;
        }

        console.warn(message + "\n" + _trimStack(stack));
        if (!displayedWarnings[message]) {
            displayedWarnings[message] = {};
        }
        displayedWarnings[message][callerLocation] = true;
    }