https://jira.nine.ch/includes/jira/common/deprecator.js

1/**
2 * This is the AUI deprecation file which has been removed from the AUI API.
3 * @module
4 * @ignore
5 */
6
7define('jira/deprecator', ['exports'], function (exports) {
8  'use strict';
9
10  var deprecationCalls = [];
11  var supportsProperties = false;
12  try {
13    if (Object.defineProperty) {
14      Object.defineProperty({}, 'blam', {
15        get: function get() {},
16        set: function set() {}
17      });
18      exports.propertyDeprecationSupported = supportsProperties = true;
19    }
20  } catch (e) {}
21  /* IE8 doesn't support on non-DOM elements */
22
23  function toSentenceCase(str) {
24    str += '';
25    if (!str) {
26      return '';
27    }
28    return str.charAt(0).toUpperCase() + str.substring(1);
29  }
30  function getDeprecatedLocation(printFrameOffset) {
31    var err = new Error();
32    var stack = err.stack || err.stacktrace;
33    var stackMessage = stack && stack.replace(/^Error\n/, '') || '';
34    if (stackMessage) {
35      stackMessage = stackMessage.split('\n');
36      return stackMessage[printFrameOffset + 2];
37    }
38    return stackMessage;
39  }
40  function logger() {
41    if (typeof console !== 'undefined' && console.warn) {
42      Function.prototype.apply.call(console.warn, console, arguments);
43    }
44  }
45
46  /**
47   * @typedef {Object} DeprecationOptions
48   * @prop {string} [removeInVersion] the version this will be removed in
49   * @prop {string} [alternativeName] the name of an alternative to use
50   * @prop {string} [sinceVersion] the version this has been deprecated since
51   * @prop {string} [extraInfo] extra information to be printed at the end of the deprecation log
52   * @prop {string} [extraObject] an extra object that will be printed at the end
53   * @prop {string} [deprecationType] type of the deprecation to append to the start of the deprecation message. e.g. JS or CSS
54   */
55
56  /**
57   * Return a function that logs a deprecation warning to the console the first time it is called from a certain location.
58   * It will also print the stack frame of the calling function.
59   *
60   * @param {string} displayName the name of the thing being deprecated
61   * @param {DeprecationOptions} [options]
62   * @return {Function} that logs the warning and stack frame of the calling function. Takes in an optional parameter for the offset of
63   * the stack frame to print, the default is 0. For example, 0 will log it for the line of the calling function,
64   * -1 will print the location the logger was called from
65   */
66  function getShowDeprecationMessage(displayName, options) {
67    // This can be used internally to pas in a showmessage fn
68    if (typeof displayName === 'function') {
69      return displayName;
70    }
71    var called = false;
72    options = options || {};
73    return function (printFrameOffset) {
74      var deprecatedLocation = getDeprecatedLocation(printFrameOffset ? printFrameOffset : 1) || '';
75      // Only log once if the stack frame doesn't exist to avoid spamming the console/test output
76      if (!called || deprecationCalls.indexOf(deprecatedLocation) === -1) {
77        deprecationCalls.push(deprecatedLocation);
78        called = true;
79        var deprecationType = options.deprecationType + ' ' || '';
80        var message = 'DEPRECATED ' + deprecationType + '- ' + toSentenceCase(displayName) + ' has been deprecated' + (options.sinceVersion ? ' since ' + options.sinceVersion : '') + ' and will be removed in ' + (options.removeInVersion || 'a future release') + '.';
81        if (options.alternativeName) {
82          message += ' Use ' + options.alternativeName + ' instead. ';
83        }
84        if (options.extraInfo) {
85          message += ' ' + options.extraInfo;
86        }
87        if (deprecatedLocation === '') {
88          deprecatedLocation = ' \n ' + 'No stack trace of the deprecated usage is available in your current browser.';
89        } else {
90          deprecatedLocation = ' \n ' + deprecatedLocation;
91        }
92        if (options.extraObject) {
93          message += '\n';
94          logger(message, options.extraObject, deprecatedLocation);
95        } else {
96          logger(message, deprecatedLocation);
97        }
98      }
99    };
100  }
101
102  /**
103   * Returns a wrapped version of the function that logs a deprecation warning when the function is used.
104   * @param {Function} fn the fn to wrap
105   * @param {string} displayName the name of the fn to be displayed in the message
106   * @param {DeprecationOptions} [options] the deprecation options
107   * @return {Function} wrapping the original function
108   */
109  function deprecateFunctionExpression(fn, displayName, options) {
110    options = options || {};
111    options.deprecationType = options.deprecationType || 'JS';
112    var showDeprecationMessage = getShowDeprecationMessage(displayName || fn.name || 'this function', options);
113    return function () {
114      showDeprecationMessage();
115      return fn.apply(this, arguments);
116    };
117  }
118
119  /**
120   * Wraps a "value" object property in a deprecation warning in browsers supporting Object.defineProperty
121   * @param {Object}

121 obj the object containing the property
122   * @param {string} prop the name of the property to deprecate
123   * @param {DeprecationOptions} [options] the deprecation options
124   * @param {string} [options.displayName] the display name of the property to deprecate (optional, will fall back to the property name)
125   */
126  function deprecateValueProperty(obj, prop, options) {
127    if (supportsProperties) {
128      var oldVal = obj[prop];
129      options = options || {};
130      options.deprecationType = options.deprecationType || 'JS';
131      var displayNameOrShowMessageFn = options.displayName || prop;
132      var showDeprecationMessage = getShowDeprecationMessage(displayNameOrShowMessageFn, options);
133      Object.defineProperty(obj, prop, {
134        get: function get() {
135          showDeprecationMessage();
136          return oldVal;
137        },
138        set: function set(val) {
139          oldVal = val;
140          showDeprecationMessage();
141          return val;
142        }
143      });
144    }
145  }
146
147  /**
148   * Wraps an object property in a deprecation warning, if possible. functions will always log warnings, but other
149   * types of properties will only log in browsers supporting Object.defineProperty
150   * @param {Object} obj the object containing the property
151   * @param {string} prop the name of the property to deprecate
152   * @param {DeprecationOptions} [options] the deprecation options
153   * @param {string} [options.displayName] the display name of the property to deprecate (optional, will fall back to the property name)
154   */
155  function deprecateObjectProperty(obj, prop, options) {
156    if (typeof obj[prop] === 'function') {
157      options = options || {};
158      options.deprecationType = options.deprecationType || 'JS';
159      var displayNameOrShowMessageFn = options.displayName || prop;
160      obj[prop] = deprecateFunctionExpression(obj[prop], displayNameOrShowMessageFn, options);
161    } else {
162      deprecateValueProperty(obj, prop, options);
163    }
164  }
165  exports.getDeprecatedLocation = getDeprecatedLocation;
166  exports.prop = deprecateObjectProperty;
167});