# @wordpress/deprecated

Deprecation utility for WordPress. Logs a message to notify developers about a deprecated feature.

## Installation

Install the module

``` bash
npm install @wordpress/deprecated --save
```

*This package assumes that your code will run in an **ES2015+** environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code.*

## Hook

The `deprecated` action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.

*Example:*

``` js
import { addAction } from '@wordpress/hooks';

function addDeprecationAlert( message, { version } ) {
    alert( `Deprecation: ${ message }. Version: ${ version }` );
}

addAction(
    'deprecated',
    'my-plugin/add-deprecation-alert',
    addDeprecationAlert
);
```

## API

### default

Logs a message to notify developers about a deprecated feature.

*Usage*

``` js
import deprecated from '@wordpress/deprecated';

deprecated( 'Eating meat', {
    since: '2019.01.01',
    version: '2020.01.01',
    alternative: 'vegetables',
    plugin: 'the earth',
    hint: 'You may find it beneficial to transition gradually.',
} );

// Logs: 'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
```

*Parameters*

- *feature* `string`: Name of the deprecated feature.
- *options* `[DeprecatedOptions]`: Personalisation options

### logged

Object map tracking messages which have been logged, for use in ensuring a message is only logged once.

*Type*

- `Record< string, true >`

## Unit testing deprecations

Each deprecation message is logged only once per loaded instance of this package. The exported `logged` object tracks the full message text. Resetting a console spy does not clear this state.

Gutenberg’s internal Vitest setup clears `logged` before each test in Node, jsdom, and Browser Mode. Suites do not need their own deprecation-history cleanup. If every test that triggers a deprecation asserts the warning, no interaction with `logged` is needed. A message still logs only once within a test. See [Expected console calls](https://developer.wordpress.org/block-editor/contributors/code/testing-overview/#expected-console-calls).

For a suite that exercises a deprecated feature, mark its message as logged in `beforeEach` to suppress it during tests of other behavior. Delete that entry before testing the warning itself.

This example uses Vitest and the `toHaveWarnedWith` matcher provided by Gutenberg’s test setup:

``` js
import { beforeEach, describe, expect, it } from 'vitest';
import deprecated, { logged } from '@wordpress/deprecated';

const DEPRECATION_MESSAGE = 'legacyFeature is deprecated.';

describe( 'legacyFeature', () => {
    beforeEach( () => {
        logged[ DEPRECATION_MESSAGE ] = true;
    } );

    it( 'warns that the feature is deprecated', () => {
        delete logged[ DEPRECATION_MESSAGE ];
        deprecated( 'legacyFeature' );

        expect( console ).toHaveWarnedWith( DEPRECATION_MESSAGE );
    } );
} );
```

Setting a `logged` entry also prevents the `deprecated` action from firing. Leave the entry absent when testing that action.

If your test setup does not clear `logged`, an earlier test can prevent a later test from observing the same warning. Delete the entries for messages your suite uses in `beforeEach` and `afterEach` to keep tests independent. For tests that suppress a warning, set its entry in `beforeEach` instead of deleting it. Limit cleanup to the messages the suite uses.

## Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).