2 * The mediawiki.inspect module.
8 /* eslint-disable no-console */
12 // mw.inspect is a singleton class with static methods
13 // that itself can also be invoked as a function (mediawiki.base/mw#inspect).
14 // In JavaScript, that is implemented by starting with a function,
15 // and subsequently setting additional properties on the function object.
18 * Tools for inspecting page composition and performance.
24 var inspect
= mw
.inspect
,
25 byteLength
= require( 'mediawiki.String' ).byteLength
,
26 hasOwn
= Object
.prototype.hasOwnProperty
;
28 function sortByProperty( array
, prop
, descending
) {
29 var order
= descending
? -1 : 1;
30 return array
.sort( function ( a
, b
) {
31 if ( a
[ prop
] === undefined || b
[ prop
] === undefined ) {
32 // Sort undefined to the end, regardless of direction
33 return a
[ prop
] !== undefined ? -1 : b
[ prop
] !== undefined ? 1 : 0;
35 return a
[ prop
] > b
[ prop
] ? order
: a
[ prop
] < b
[ prop
] ? -order
: 0;
39 function humanSize( bytesInput
) {
42 units
= [ '', ' KiB', ' MiB', ' GiB', ' TiB', ' PiB' ];
44 if ( bytes
=== 0 || isNaN( bytes
) ) {
48 for ( i
= 0; bytes
>= 1024; bytes
/= 1024 ) {
51 // Maintain one decimal for kB and above, but don't
52 // add ".0" for bytes.
53 return bytes
.toFixed( i
> 0 ? 1 : 0 ) + units
[ i
];
57 * Return a map of all dependency relationships between loaded modules.
59 * @return {Object} Maps module names to objects. Each sub-object has
60 * two properties, 'requires' and 'requiredBy'.
62 inspect
.getDependencyGraph = function () {
63 var modules
= inspect
.getLoadedModules(),
66 modules
.forEach( function ( moduleName
) {
67 var dependencies
= mw
.loader
.moduleRegistry
[ moduleName
].dependencies
|| [];
69 if ( !hasOwn
.call( graph
, moduleName
) ) {
70 graph
[ moduleName
] = { requiredBy
: [] };
72 graph
[ moduleName
].requires
= dependencies
;
74 dependencies
.forEach( function ( depName
) {
75 if ( !hasOwn
.call( graph
, depName
) ) {
76 graph
[ depName
] = { requiredBy
: [] };
78 graph
[ depName
].requiredBy
.push( moduleName
);
85 * Calculate the byte size of a ResourceLoader module.
87 * @param {string} moduleName The name of the module
88 * @return {number|null} Module size in bytes or null
90 inspect
.getModuleSize = function ( moduleName
) {
91 var module
= mw
.loader
.moduleRegistry
[ moduleName
],
94 if ( module
.state
!== 'ready' ) {
98 if ( !module
.style
&& !module
.script
) {
102 function getFunctionBody( func
) {
103 return String( func
)
104 // To ensure a deterministic result, replace the start of the function
105 // declaration with a fixed string. For example, in Chrome 55, it seems
106 // V8 seemingly-at-random decides to sometimes put a line break between
107 // the opening brace and first statement of the function body. T159751.
108 .replace( /^\s*function\s*\([^)]*\)\s*{\s*/, 'function(){' )
109 .replace( /\s*}\s*$/, '}' );
112 // Based on the load.php response for this module.
113 // For example: `mw.loader.implement("example", function(){}, {"css":[".x{color:red}"]});`
114 // @see mw.loader.store.set().
122 // Trim trailing null or empty object, as load.php would have done.
123 // @see ResourceLoader::makeLoaderImplementScript and ResourceLoader::trimArray.
126 if ( args
[ i
] === null || ( $.isPlainObject( args
[ i
] ) && $.isEmptyObject( args
[ i
] ) ) ) {
134 for ( i
= 0; i
< args
.length
; i
++ ) {
135 if ( typeof args
[ i
] === 'function' ) {
136 size
+= byteLength( getFunctionBody( args
[ i
] ) );
138 size
+= byteLength( JSON
.stringify( args
[ i
] ) );
146 * Given CSS source, count both the total number of selectors it
147 * contains and the number which match some element in the current
150 * @param {string} css CSS source
151 * @return {Object} Selector counts
152 * @return {number} return.selectors Total number of selectors
153 * @return {number} return.matched Number of matched selectors
155 inspect
.auditSelectors = function ( css
) {
156 var selectors
= { total
: 0, matched
: 0 },
157 style
= document
.createElement( 'style' );
159 style
.textContent
= css
;
160 document
.body
.appendChild( style
);
161 // eslint-disable-next-line no-jquery/no-each-util
162 $.each( style
.sheet
.cssRules
, function ( index
, rule
) {
164 // document.querySelector() on prefixed pseudo-elements can throw exceptions
165 // in Firefox and Safari. Ignore these exceptions.
166 // https://bugs.webkit.org/show_bug.cgi?id=149160
167 // https://bugzilla.mozilla.org/show_bug.cgi?id=1204880
169 if ( document
.querySelector( rule
.selectorText
) !== null ) {
174 document
.body
.removeChild( style
);
179 * Get a list of all loaded ResourceLoader modules.
181 * @return {Array} List of module names
183 inspect
.getLoadedModules = function () {
184 return mw
.loader
.getModuleNames().filter( function ( module
) {
185 return mw
.loader
.getState( module
) === 'ready';
190 * Print tabular data to the console, using console.table, console.log,
191 * or mw.log (in declining order of preference).
193 * @param {Array} data Tabular data represented as an array of objects
194 * with common properties.
196 inspect
.dumpTable = function ( data
) {
198 // Use Function.prototype#call to force an exception on Firefox,
199 // which doesn't define console#table but doesn't complain if you
201 // eslint-disable-next-line no-useless-call
202 console
.table
.call( console
, data
);
206 console
.log( JSON
.stringify( data
, null, 2 ) );
211 * Generate and print reports.
213 * When invoked without arguments, prints all available reports.
215 * @param {...string} [reports] One or more of "size", "css", "store", or "time".
217 inspect
.runReports = function () {
218 var reports
= arguments
.length
> 0 ?
219 Array
.prototype.slice
.call( arguments
) :
220 Object
.keys( inspect
.reports
);
222 reports
.forEach( function ( name
) {
223 if ( console
.group
) {
224 console
.group( 'mw.inspect ' + name
+ ' report' );
226 console
.log( 'mw.inspect ' + name
+ ' report' );
228 inspect
.dumpTable( inspect
.reports
[ name
]() );
229 if ( console
.group
) {
230 console
.groupEnd( 'mw.inspect ' + name
+ ' report' );
236 * Perform a string search across the JavaScript and CSS source code
237 * of all loaded modules and return an array of the names of the
238 * modules that matched.
240 * @param {string|RegExp} pattern String or regexp to match.
241 * @return {Array} Array of the names of modules that matched.
243 inspect
.grep = function ( pattern
) {
244 if ( typeof pattern
.test
!== 'function' ) {
245 pattern
= new RegExp( mw
.RegExp
.escape( pattern
), 'g' );
248 return inspect
.getLoadedModules().filter( function ( moduleName
) {
249 var module
= mw
.loader
.moduleRegistry
[ moduleName
];
251 // Grep module's JavaScript
252 if ( typeof module
.script
=== 'function' && pattern
.test( module
.script
.toString() ) ) {
258 $.isPlainObject( module
.style
) && Array
.isArray( module
.style
.css
) &&
259 pattern
.test( module
.style
.css
.join( '' ) )
261 // Module's CSS source matches
271 * @class mw.inspect.reports
276 * Generate a breakdown of all loaded modules and their size in
277 * kilobytes. Modules are ordered from largest to smallest.
279 * @return {Object[]} Size reports
282 // Map each module to a descriptor object.
283 var modules
= inspect
.getLoadedModules().map( function ( module
) {
286 size
: inspect
.getModuleSize( module
)
290 // Sort module descriptors by size, largest first.
291 sortByProperty( modules
, 'size', true );
293 // Convert size to human-readable string.
294 modules
.forEach( function ( module
) {
295 module
.sizeInBytes
= module
.size
;
296 module
.size
= humanSize( module
.size
);
303 * For each module with styles, count the number of selectors, and
304 * count how many match against some element currently in the DOM.
306 * @return {Object[]} CSS reports
311 inspect
.getLoadedModules().forEach( function ( name
) {
312 var css
, stats
, module
= mw
.loader
.moduleRegistry
[ name
];
315 css
= module
.style
.css
.join();
316 } catch ( e
) { return; } // skip
318 stats
= inspect
.auditSelectors( css
);
321 allSelectors
: stats
.total
,
322 matchedSelectors
: stats
.matched
,
323 percentMatched
: stats
.total
!== 0 ?
324 ( stats
.matched
/ stats
.total
* 100 ).toFixed( 2 ) + '%' : null
327 sortByProperty( modules
, 'allSelectors', true );
332 * Report stats on mw.loader.store: the number of localStorage
333 * cache hits and misses, the number of items purged from the
334 * cache, and the total size of the module blob in localStorage.
336 * @return {Object[]} Store stats
339 var raw
, stats
= { enabled
: mw
.loader
.store
.enabled
};
340 if ( stats
.enabled
) {
341 $.extend( stats
, mw
.loader
.store
.stats
);
343 raw
= localStorage
.getItem( mw
.loader
.store
.getStoreKey() );
344 stats
.totalSizeInBytes
= byteLength( raw
);
345 stats
.totalSize
= humanSize( byteLength( raw
) );
352 * Generate a breakdown of all loaded modules and their time
353 * spent during initialisation (measured in milliseconds).
355 * This timing data is collected by mw.loader.profiler.
357 * @return {Object[]} Table rows
362 if ( !mw
.loader
.profiler
) {
363 mw
.log
.warn( 'mw.inspect: The time report requires $wgResourceLoaderEnableJSProfiler.' );
367 modules
= inspect
.getLoadedModules()
368 .map( function ( moduleName
) {
369 return mw
.loader
.profiler
.getProfile( moduleName
);
371 .filter( function ( perf
) {
372 // Exclude modules that reached "ready" state without involvement from mw.loader.
373 // This is primarily styles-only as loaded via <link rel="stylesheet">.
374 return perf
!== null;
377 // Sort by total time spent, highest first.
378 sortByProperty( modules
, 'total', true );
380 // Add human-readable strings
381 modules
.forEach( function ( module
) {
382 module
.totalInMs
= module
.total
;
383 module
.total
= module
.totalInMs
.toLocaleString() + ' ms';
390 if ( mw
.config
.get( 'debug' ) ) {
391 mw
.log( 'mw.inspect: reports are not available in debug mode.' );