Selectors decision tree - pick matching selectors, fast.
Installations
npm install @selderee/plugin-htmlparser2Releases
Unable to fetch releases
Developer
mxxii
Developer Guide
Module System
ESM
Min. Node Version
Typescript Support
Yes
Node Version
14.20.0
NPM Version
6.14.17
Statistics
2 Stars
38 Commits
1 Forks
2 Watching
6 Branches
1 Contributors
Updated on 25 Aug 2023
Languages
TypeScript (93.2%)
JavaScript (6.8%)
Total Downloads
Cumulative downloads
Total Downloads
139,926,256
Last day
-8.1%
320,417
Compared to previous day
Last week
3.7%
1,883,430
Compared to previous week
Last month
9.9%
7,832,105
Compared to previous month
Last year
76.5%
76,139,520
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
2
Dev Dependencies
1
selderee
Selectors decision tree - pick matching selectors, fast.
What is it for
The problem statement: there are multiple CSS selectors with attached handlers, and a HTML DOM to process. For each HTML Element a matching handler has to be found and applied.
The naive approach is to walk through the DOM and test each and every selector against each Element. This means O(n*m) complexity.
It is pretty clear though that if we have selectors that share something in common then we can reduce the number of checks.
The main selderee package offers the selectors tree structure. Runnable decision functions for specific DOM implementations are built via plugins.
Limitations
- Pseudo-classes and pseudo-elements are not supported by the underlying library parseley (yet?);
- General siblings (
~), descendants (||) are also not supported.
selderee vs css-select
css-select - a CSS selector compiler & engine.
| Feature | selderee | css-select |
|---|---|---|
Support for htmlparser2 DOM AST | plugin | + |
| "Compiles" into a function | + | + |
| Pick selector(s) for a given Element | + | |
| Query Element(s) for a given selector | + |
Packages
| Package | Version | Folder | Changelog |
|---|---|---|---|
| selderee |  | /packages/selderee | changelog |
| @selderee/plugin-htmlparser2 |  | /packages/plugin-htmlparser2 | changelog |
Install
1> npm i selderee @selderee/plugin-htmlparser2
Documentation
Usage example
1const htmlparser2 = require('htmlparser2'); 2const util = require('util'); 3 4const { DecisionTree, Treeify } = require('selderee'); 5const { hp2Builder } = require('@selderee/plugin-htmlparser2'); 6 7const selectorValuePairs = [ 8 ['p', 'A'], 9 ['p.foo[bar]', 'B'], 10 ['p[class~=foo]', 'C'], 11 ['div.foo', 'D'], 12 ['div > p.foo', 'E'], 13 ['div > p', 'F'], 14 ['#baz', 'G'] 15]; 16 17// Make a tree structure from all given selectors. 18const selectorsDecisionTree = new DecisionTree(selectorValuePairs); 19 20// `treeify` builder produces a string output for testing and debug purposes. 21// `treeify` expects string values attached to each selector. 22const prettyTree = selectorsDecisionTree.build(Treeify.treeify); 23console.log(prettyTree); 24 25const html = /*html*/`<html><body> 26 <div><p class="foo qux">second</p></div> 27</body></html>`; 28const dom = htmlparser2.parseDocument(html); 29const element = dom.children[0].children[0].children[1].children[0]; 30 31// `hp2Builder` produces a picker that can pick values 32// from the selectors tree. 33const picker = selectorsDecisionTree.build(hp2Builder); 34 35// Get all matches 36const allMatches = picker.pickAll(element); 37console.log(util.inspect(allMatches, { breakLength: 70, depth: null })); 38 39// or get the value from the most specific match. 40const bestMatch = picker.pick1(element); 41console.log(`Best matched value: ${bestMatch}`);
Example output
1▽ 2├─◻ Tag name 3│ ╟─◇ = p 4│ ║ ┠─▣ Attr value: class 5│ ║ ┃ ╙─◈ ~= "foo" 6│ ║ ┃ ┠─◨ Attr presence: bar 7│ ║ ┃ ┃ ┖─◁ #1 [0,2,1] B 8│ ║ ┃ ┠─◁ #2 [0,1,1] C 9│ ║ ┃ ┖─◉ Push element: > 10│ ║ ┃ └─◻ Tag name 11│ ║ ┃ ╙─◇ = div 12│ ║ ┃ ┖─◁ #4 [0,1,2] E 13│ ║ ┠─◁ #0 [0,0,1] A 14│ ║ ┖─◉ Push element: > 15│ ║ └─◻ Tag name 16│ ║ ╙─◇ = div 17│ ║ ┖─◁ #5 [0,0,2] F 18│ ╙─◇ = div 19│ ┖─▣ Attr value: class 20│ ╙─◈ ~= "foo" 21│ ┖─◁ #3 [0,1,1] D 22└─▣ Attr value: id 23 ╙─◈ = "baz" 24 ┖─◁ #6 [1,0,0] G 25[ { index: 2, value: 'C', specificity: [ 0, 1, 1 ] }, 26 { index: 4, value: 'E', specificity: [ 0, 1, 2 ] }, 27 { index: 0, value: 'A', specificity: [ 0, 0, 1 ] }, 28 { index: 5, value: 'F', specificity: [ 0, 0, 2 ] } ] 29Best matched value: E
Some gotcha: you may notice the check for #baz has to be performed every time the decision tree is called. If it happens to be p#baz or div#baz or even .foo#baz - it would be much better to write it like this. Deeper, narrower tree means less checks on average. (in case of .foo#baz the class check might finally outweigh the tag name check and rebalance the tree.)
Development
Targeting Node.js version >=14.
Monorepo uses NPM v7 workspaces (make sure v7 is installed when used with Node.js v14.)
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
6 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Reason
dependency not pinned by hash detected -- score normalized to 2
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/mxxii/selderee/lint.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/mxxii/selderee/lint.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/mxxii/selderee/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/mxxii/selderee/test.yml/main?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/test.yml:27
- Info: 0 out of 4 GitHub-owned GitHubAction dependencies pinned
- Info: 2 out of 3 npmCommand dependencies pinned
Reason
Found 0/30 approved changesets -- score normalized to 0
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no SAST tool detected
Details
- Warn: no pull requests merged into dev branch
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/lint.yml:1
- Warn: no topLevel permission defined: .github/workflows/test.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'main'
Score
3
/10
Last Scanned on 2024-11-18
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More