cssstats

Parses stylesheets and returns an object with statistics.
This is the core module used in cssstats.com

Installation

``sh
npm i --save cssstats
`

Usage

$3

`js
var fs = require('fs')
var cssstats = require('cssstats')

var css = fs.readFileSync('./styles.css', 'utf8')
var stats = cssstats(css)
`

$3

CSS Stats can be used as a PostCSS plugin.
The stats will be added to PostCSS's messages array.

`js
var fs = require('fs')
var postcss = require('postcss')
var cssstats = require('cssstats')

var css = fs.readFileSync('./styles.css', 'utf8')
postcss()
.use(cssstats())
.process(css)
.then(function (result) {
result.messages.forEach(function (message) {
console.log(message)
})
})
`

#### Options

Options may be passed as a second argument.

`js
var stats = cssstats(css, { mediaQueries: false })
`

- safe (boolean, default: true) - enables PostCSS safe mode for parsing CSS with syntax errors
- mediaQueries (boolean, default true) - determines whether or not to generate stats for each media query block
- importantDeclarations (boolean, default false) - include an array of declarations with !important

The following options add the results of helper methods to the returned object. This is helpful when using JSON.stringify().

- specificityGraph (boolean, default false)
- sortedSpecificityGraph (boolean, default false)
- repeatedSelectors (boolean, default false)
- propertyResets (boolean, default false)
- vendorPrefixedProperties (boolean, default false)

$3

`js
// Example
{
size: n,
gzipSize: n,
rules: {
total: n,
size: {
graph: [n],
max: n,
average: n
}
},
selectors: {
total: n,
id: n,
class: n,
type: n,
pseudoClass: n,
psuedoElement: n,
values: [str],
specificity: {
max: n
average: n
},
getSpecificityGraph(),
getSpecificityValues(),
getRepeatedValues(),
getSortedSpecificity()
},
declarations: {
total: n,
unique: n,
uniqueToTotalRatio: n,
important: [obj],
properties:
prop: [str]
},
getPropertyResets(),
getUniquePropertyCount(),
getPropertyValueCount(),
getVendorPrefixed(),
getAllFontSizes(),
getAllFontFamilies(),
},
mediaQueries: {
total: n,
unique: n,
values: [str],
contents: [
{
value: str,
rules: {
total: n,
size: {
graph: [n],
max: n,
average: n
}
},
selectors: {
total: n,
id: n,
class: n,
type: n,
pseudoClass: n,
pseudoElement: n,
values: [str],
specificity: {
max: n,
average: n
}
},
declarations: {
total: n,
unique: n,
important: [obj],
vendorPrefix: n,
properties: {
prop: [str]
}
}
}
]
}
}
`

#### size number

The size of the file in bytes

#### gzipSize number

The size of the stylesheet gzipped in bytes

#### rules object

- total number - total number of rules
- size object
- size.graph array - ruleset sizes (number of declarations per rule) in source order
- size.max number - maximum ruleset size
- size.average number - average ruleset size

#### selectors object

- total number - total number of selectors
- type number - total number of type selectors
- class number - total number of class selectors
- id number - total number of id selectors
- pseudoClass number - total number of pseudo class selectors
- pseudoElement number - total number of pseudo element selectors
- values array - array of strings for all selectors
- specificity object
- specificity.max number - maximum specificity as a base 10 number
- specificity.average number - average specificity as a base 10 number
- getSpecificityGraph() function - returns an array of numbers for each selector’s specificity as a base 10 number
- getSpecificityValues() function - returns an array of selectors with base 10 specificity score in order
- getRepeatedValues() function - returns an array of strings of repeated selectors
- getSortedSpecificity() function - returns an array of selectors with base 10 specificity score, sorted from highest to lowest

#### declarations object

- total number - total number of declarations
- unique number - total unique declarations
- uniqueToTotalRatio number - ratio of unique declarations to total declarations
- properties object - object with each unique property and an array of that property’s values
- getPropertyResets() function - returns an object with the number of times margin or padding is reset for each property
- getUniquePropertyCount(property) function - returns the number of unique values for the given property
- getPropertyValueCount(property, value) function - returns the number of times a declaration occurs for the given property and value
- getVendorPrefixed() function - returns an array of declarations with vendor prefixed properties
- getAllFontSizes() function - returns an array of font sizes from both font-size and font shorthand declarations
- getAllFontFamilies() function - returns an array of font families from both font-family and font shorthand declarations
- important array (optional) - !important declaration objects with property and value

#### mediaQueries object

- total number - total number of media queries
- unique number - total unique media queries
- values array - array of values for each media query
- contents array - array of media query blocks with full stats object for each

See the /test/results folder for example JSON results.

$3

`js
var cssstats = require('cssstats')
var stats = cssstats(css)
`

#### Generate a specificity graph

`js
var specificityGraph = stats.selectors.getSpecificityGraph()
`

#### Sort selectors by highest specificity

`js
var sortedSelectors = stats.selectors.getSortedSpecificity()
`

#### Get total number of unique colors

`js
var uniqueColorsCount = stats.declarations.getUniquePropertyCount('color')
`

#### display: none count

`js
var displayNoneCount = stats.declarations.getPropertyValueCount(
'display',
'none'
)
`

License

MIT

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature`)
5. Create new Pull Request