Modules (181)

DeprecationWarning

Description

Utilities functions to display deprecation warning in the console.

Dependencies

Functions

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;
    }