Deprecations

Deprecations package is a kernel that uses the deprecationsHelper to expose an API.

Deprecations helper

The deprecationsHelper manages the deprecation warnings of the application.

prepare

Configure and return a Deprecator.

Usage

prepare({
  message: String?,
  alternative: String?,
  module: String?,
  method: String?,
  pluginName: String?,
  deprecationType: String?,
}): Deprecator

• Configuration Object?

  Configuration of the deprecator.

  • message String?

    Message to display in the deprecation. If you don't configure the message when using the prepare method, it will be required when calling deprecate method from a deprecator or vice versa.

  • alternative String?

    Explain an alternative if it's available.

  • module String?

    Module of the method deprecated.

  • method String?

    Name of the method to be deprecated.

  • pluginName String?

    The name of the plugin that is consuming the deprecated method.

  • deprecationType ('error' | 'warn' | 'collapsed')

    The deprecator behavior when deprecating.

Returns

• Deprecator

  A configured Deprecator instance.

Example

class AwesomePlugin {
  constructor({ deprecationsHelper }) {
    this.deprecator = deprecationsHelper.prepare({ pluginName: 'AwesomePlugin' });
  }

  awesomeMethod() {
    // ...
    this.deprecator.deprecate({
      message: 'this methods has been deprecated because inconsistences of the API',
      alternative: 'use another newAwesomeMethod instead',
      method: 'awesomeMethod',
    });
    // ...
  }
}

Deprecator

Deprecator has the method deprecate and receives the same configuration of deprecationsHelper.prepare and applies a merge.

The deprecator can be configured with three different behaviours:

• { deprecationType: 'error' }

  Will throw when finding a deprecation (default).

• { deprecationType: 'warn' }

  Will not throw but warn instead when finding a deprecation.

• { deprecationType: 'collapsed' }

  Will not throw but warn unique deprecation messages.

You can configure deprecationType globally with the deprecationsManagerProvider.

To throw error instead of warning (default):

kernel.configure(({ deprecationsManagerProvider }) => {
  deprecationsManagerProvider.setDeprecationType('error');
});

To warn instead of throwing an error:

kernel.configure(({ deprecationsManagerProvider }) => {
  deprecationsManagerProvider.setDeprecationType('warn');
});

To warn instead of throwing an error only unique messages:

kernel.configure(({ deprecationsManagerProvider }) => {
  deprecationsManagerProvider.setDeprecationType('collapsed');
});