simplify-selector

A utility for simplifying CSS selector queries to their simplest possible form in a fully automated manner, without losing accuracy. Works with any type of document tree, not just the browser DOM.

This is an early version of this library; don't expect too much from it in terms of reliability, input validation, correct serialization, and so on.

Example

let selector = [ // div.testClass #uniqueID
	[{ type: "tag", selector: "div" }, { type: "class", selector: "testClass" }],
	[{ type: "id", selector: "uniqueID" }]
];

let simplifiedQuery = simplifySelector(selector, (newSelector) => document.querySelectorAll(newSelector));
console.log(`Simplified query: ${simplifiedQuery.stringQuery}`);

Selector format

Selectors can exist in either string format (like a browser would expect it) or in 'structured data format', which is specific to this library. The structure is visible in the example above; it's an array of arrays, where each inner array represents a (space-separated) segment of the query and each object inside represents a component of that segment.

Currently supported types are tag, class, id, pseudo, and attribute - where the attribute type accepts a {key, value} object as the selector attribute. Note that pseudo selectors must specify the entire selector including any parameters, eg. { type: "pseudo", selector: "nth-of-child(3)" }.

Additionally, any component may have a protected property; when this is set to true, the selector will not be removed from the query no matter what. Use this if you want to ensure that a specific selector always shows up in the output. The segment containing it does not need to be marked as protected; this is detected automatically.

simplifySelector(selector, testCallback)

• selector: Required. The original selector to reduce. This must be in the structured data format, not in string format.
• testCallback: Required. A function that, when called with a selector query (in string format), returns all matches as an array. The shape of the returned objects in the arrays doesn't matter, as long as they're consistent between invocations.
• options: Optional.
  • keepRemoved: Defaults to false. Whether to keep Removed symbols in the output, everywhere a selector segment or component was removed. Sometimes useful for eg. tracking changes in the simplification process. The string-format query never contains these symbols. The symbol is exported from this library.
  • anchorID: Defaults to false. ID anchoring is a technique used in scraping, where a selector query starts with the nearest ancestor element ID. As IDs are meant to be unique and are often stable, this tends to result in more 'stable' selectors, at the cost of them sometimes being larger. Enabling this option will cause simplify-selector to try this (faster) technique first, falling back to the normal process if it fails. Enable it if you are generating scraping queries; disable it if you are trying to eg. minify stylesheets in a build process.

Returns: An object with the following properties:

• query: The minimal selector, following the same selector format as the input
• stringQuery: The selector in string form, ie. in the form that you would pass into document.querySelector or some other element selection method
• matchesMultiple: Whether the selector matches multiple elements (true) or not (false).

simplifySelector.Removed

A Symbol that represents a removed segment or component in the simplified query. Only needed if you set the keepRemoved option. See the tests for an example of use.

simplifySelector.stringify(selector)

The function that simplify-selector uses internally for turning a selector in the structured data format, into the string format. This is not guaranteed to be a correct implementation; the only guarantee is that its output is equivalent to the stringQuery result.

• selector: The selector, in structured data format, to stringify. This is allowed to contain Removed symbols.

Returns: The selector in string format.