-
Notifications
You must be signed in to change notification settings - Fork 4.1k
/
index.js
76 lines (69 loc) · 2.81 KB
/
index.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
/**
* WordPress dependencies
*/
import { doAction } from '@wordpress/hooks';
/**
* Object map tracking messages which have been logged, for use in ensuring a
* message is only logged once.
*
* @type {Record<string,true|undefined>}
*/
export const logged = Object.create( null );
/**
* Logs a message to notify developers about a deprecated feature.
*
* @param {string} feature Name of the deprecated feature.
* @param {Object} [options] Personalisation options
* @param {string} [options.version] Version in which the feature will be removed.
* @param {string} [options.alternative] Feature to use instead
* @param {string} [options.plugin] Plugin name if it's a plugin feature
* @param {string} [options.link] Link to documentation
* @param {string} [options.hint] Additional message to help transition away from the deprecated feature.
*
* @example
* ```js
* import deprecated from '@wordpress/deprecated';
*
* deprecated( 'Eating meat', {
* version: 'the future',
* alternative: 'vegetables',
* plugin: 'the earth',
* hint: 'You may find it beneficial to transition gradually.',
* } );
*
* // Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
* ```
*/
export default function deprecated( feature, options = {} ) {
const { version, alternative, plugin, link, hint } = options;
const pluginMessage = plugin ? ` from ${ plugin }` : '';
const versionMessage = version
? ` and will be removed${ pluginMessage } in version ${ version }`
: '';
const useInsteadMessage = alternative
? ` Please use ${ alternative } instead.`
: '';
const linkMessage = link ? ` See: ${ link }` : '';
const hintMessage = hint ? ` Note: ${ hint }` : '';
const message = `${ feature } is deprecated${ versionMessage }.${ useInsteadMessage }${ linkMessage }${ hintMessage }`;
// Skip if already logged.
if ( message in logged ) {
return;
}
/**
* Fires whenever a deprecated feature is encountered
*
* @param {string} feature Name of the deprecated feature.
* @param {?Object} options Personalisation options
* @param {?string} options.version Version in which the feature will be removed.
* @param {?string} options.alternative Feature to use instead
* @param {?string} options.plugin Plugin name if it's a plugin feature
* @param {?string} options.link Link to documentation
* @param {?string} options.hint Additional message to help transition away from the deprecated feature.
* @param {?string} message Message sent to console.warn
*/
doAction( 'deprecated', feature, options, message );
// eslint-disable-next-line no-console
console.warn( message );
logged[ message ] = true;
}