Drupal.deprecationError() and Drupal.deprecatedProperty() added to allow triggering JavaScript deprecation errors

JavaScript API additions

#2918868: [policy, no patch] Use a deprecation process for JavaScript similar to what we use for PHP code introduced a JavaScript deprecation policy. That covered how to document deprecated JavaScript APIs. It didn't add support for triggering deprecation errors from JavaScript. The infrastructure necessary to provide that has now been added too.

1. Drupal.deprecationError, to trigger a deprecation error when they're not suppressed. For use in JS functions.
2. Drupal.deprecatedProperty, to decorate properties that are deprecated, to allow Drupal.deprecationError to be called automatically when deprecation errors are not suppressed.

Suppressing or surfacing deprecation errors

Drupal Core will trigger browser console warnings for usages of deprecated code in JavaScript. Deprecation errors are always prefixed with [Deprecation] so they can be tracked in CI.

Deprecation errors are suppressed by default. The suppression can be disabled by adding the following code to a module:

function hook_js_settings_alter(&$settings) {
  $settings['suppressDeprecationErrors'] = FALSE;
}

Examples

Example of deprecating a function:

Drupal.theme.div = function ($elements) {
    Drupal.deprecationError({
      message: 'The Drupal.theme.div is deprecated in drupal:8.8.0 and will be removed from drupal:9.0.0. See https://www.drupal.org/node/2575199.'
    });
    return $('<div></div>');
};

Example of deprecating an object or class property:

Drupal.deprecatedProperty({
  target: { some_property: 'value', someProperty: 'value' },
  deprecatedProperty: 'property',
  message: 'The some_property property has been deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. Use someProperty instead.',
});

More information on:

• Why we use our Drupal core deprecation process
• javascript deprecations.