codekingpro/portable-devtools
115k
1<!DOCTYPE html><html><head>
2<meta charset="utf-8">
3<title>Dependency Selectors</title>
4<style>
5body {
6 background-color: #ffffff;
7 color: #24292e;
8
9 margin: 0;
10
11 line-height: 1.5;
12
13 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
14}
15#rainbar {
16 height: 10px;
17 background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff);
18}
19
20a {
21 text-decoration: none;
22 color: #0366d6;
23}
24a:hover {
25 text-decoration: underline;
26}
27
28pre {
29 margin: 1em 0px;
30 padding: 1em;
31 border: solid 1px #e1e4e8;
32 border-radius: 6px;
33
34 display: block;
35 overflow: auto;
36
37 white-space: pre;
38
39 background-color: #f6f8fa;
40 color: #393a34;
41}
42code {
43 font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace;
44 font-size: 85%;
45 padding: 0.2em 0.4em;
46 background-color: #f6f8fa;
47 color: #393a34;
48}
49pre > code {
50 padding: 0;
51 background-color: inherit;
52 color: inherit;
53}
54h1, h2, h3 {
55 font-weight: 600;
56}
57
58#logobar {
59 background-color: #333333;
60 margin: 0 auto;
61 padding: 1em 4em;
62}
63#logobar .logo {
64 float: left;
65}
66#logobar .title {
67 font-weight: 600;
68 color: #dddddd;
69 float: left;
70 margin: 5px 0 0 1em;
71}
72#logobar:after {
73 content: "";
74 display: block;
75 clear: both;
76}
77
78#content {
79 margin: 0 auto;
80 padding: 0 4em;
81}
82
83#table_of_contents > h2 {
84 font-size: 1.17em;
85}
86#table_of_contents ul:first-child {
87 border: solid 1px #e1e4e8;
88 border-radius: 6px;
89 padding: 1em;
90 background-color: #f6f8fa;
91 color: #393a34;
92}
93#table_of_contents ul {
94 list-style-type: none;
95 padding-left: 1.5em;
96}
97#table_of_contents li {
98 font-size: 0.9em;
99}
100#table_of_contents li a {
101 color: #000000;
102}
103
104header.title {
105 border-bottom: solid 1px #e1e4e8;
106}
107header.title > h1 {
108 margin-bottom: 0.25em;
109}
110header.title > .description {
111 display: block;
112 margin-bottom: 0.5em;
113 line-height: 1;
114}
115
116header.title .version {
117 font-size: 0.8em;
118 color: #666666;
119}
120
121footer#edit {
122 border-top: solid 1px #e1e4e8;
123 margin: 3em 0 4em 0;
124 padding-top: 2em;
125}
126
127table {
128 width: 100%;
129 margin: 1em 0;
130 border-radius: 6px;
131 border: 1px solid #e1e4e8;
132 overflow: hidden;
133 border-collapse: separate;
134 border-spacing: 0;
135}
136
137table thead {
138 background-color: #f6f8fa;
139}
140
141table tbody {
142 background-color: #ffffff;
143}
144
145table th,
146table td {
147 padding: 0.75em;
148 text-align: left;
149 border-right: 1px solid #e1e4e8;
150 border-bottom: 1px solid #e1e4e8;
151}
152
153table th:last-child,
154table td:last-child {
155 border-right: none;
156}
157
158table tbody tr:last-child td {
159 border-bottom: none;
160}
161
162table th {
163 font-weight: 600;
164 background-color: #f6f8fa;
165}
166
167table code {
168 white-space: nowrap;
169}
170
171</style>
172</head>
173<body>
174<div id="banner">
175<div id="rainbar"></div>
176<div id="logobar">
177<svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700">
178<polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon>
179<polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon>
180</svg>
181<div class="title">
182npm command-line interface
183</div>
184</div>
185</div>
186
187<section id="content">
188<header class="title">
189<h1 id="----dependency-selectors----11130">
190 <span>Dependency Selectors</span>
191 <span class="version">@11.13.0</span>
192</h1>
193<span class="description">Dependency Selector Syntax & Querying</span>
194</header>
195
196<section id="table_of_contents">
197<h2 id="table-of-contents">Table of contents</h2>
198<div id="_table_of_contents"><ul><li><a href="#see-also">See Also</a></li></ul></div>
199</section>
200
201<div id="_content"><h3 id="description">Description</h3>
202<p>The <a href="../commands/npm-query.html"><code>npm query</code></a> command exposes a new dependency selector syntax (informed by & respecting many aspects of the <a href="https://dev.w3.org/csswg/selectors4/#relational">CSS Selectors 4 Spec</a>) which:</p>
203<ul>
204<li>Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax</li>
205<li>Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible</li>
206<li>Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata</li>
207<li>Consolidates redundant logic of similar query commands in <code>npm</code> (ex.
208<code>npm fund</code>, <code>npm ls</code>, <code>npm outdated</code>, <code>npm audit</code> ...)</li>
209</ul>
210<h3 id="dependency-selector-syntax">Dependency Selector Syntax</h3>
211<h4 id="overview">Overview:</h4>
212<ul>
213<li>there is no "type" or "tag" selectors (ex.
214<code>div, h1, a</code>) as a dependency/target is the only type of <code>Node</code> that can be queried</li>
215<li>the term "dependencies" is in reference to any <code>Node</code> found in a <code>tree</code> returned by <code>Arborist</code></li>
216</ul>
217<h4 id="combinators">Combinators</h4>
218<ul>
219<li><code>></code> direct descendant/child</li>
220<li><code> </code> any descendant/child</li>
221<li><code>~</code> sibling</li>
222</ul>
223<h4 id="selectors">Selectors</h4>
224<ul>
225<li><code>*</code> universal selector</li>
226<li><code>#<name></code> dependency selector (equivalent to <code>[name="..."]</code>)</li>
227<li><code>#<name>@<version></code> (equivalent to <code>[name=<name>]:semver(<version>)</code>)</li>
228<li><code>,</code> selector list delimiter</li>
229<li><code>.</code> dependency type selector</li>
230<li><code>:</code> pseudo selector</li>
231</ul>
232<h4 id="dependency-type-selectors">Dependency Type Selectors</h4>
233<ul>
234<li><code>.prod</code> dependency found in the <code>dependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
235<li><code>.dev</code> dependency found in the <code>devDependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
236<li><code>.optional</code> dependency found in the <code>optionalDependencies</code> section of <code>package.json</code>, or has <code>"optional": true</code> set in its entry in the <code>peerDependenciesMeta</code> section of <code>package.json</code>, or a child of said dependency</li>
237<li><code>.peer</code> dependency found in the <code>peerDependencies</code> section of <code>package.json</code></li>
238<li><code>.workspace</code> dependency found in the <a href="https://docs.npmjs.com/cli/v8/using-npm/workspaces"><code>workspaces</code></a> section of <code>package.json</code></li>
239<li><code>.bundled</code> dependency found in the <code>bundleDependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
240</ul>
241<h4 id="pseudo-selectors">Pseudo Selectors</h4>
242<ul>
243<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:not"><code>:not(<selector>)</code></a></li>
244<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:has"><code>:has(<selector>)</code></a></li>
245<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:is"><code>:is(<selector list>)</code></a></li>
246<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:root"><code>:root</code></a> matches the root node/dependency</li>
247<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:scope"><code>:scope</code></a> matches node/dependency it was queried against</li>
248<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:empty"><code>:empty</code></a> when a dependency has no dependencies</li>
249<li><a href="https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private"><code>:private</code></a> when a dependency is private</li>
250<li><code>:link</code> when a dependency is linked (for instance, workspaces or packages manually <a href="https://docs.npmjs.com/cli/v8/commands/npm-link"><code>linked</code></a></li>
251<li><code>:deduped</code> when a dependency has been deduped (note that this does <em>not</em> always mean the dependency has been hoisted to the root of node_modules)</li>
252<li><code>:overridden</code> when a dependency has been overridden</li>
253<li><code>:extraneous</code> when a dependency exists but is not defined as a dependency of any node</li>
254<li><code>:invalid</code> when a dependency version is out of its ancestors specified range</li>
255<li><code>:missing</code> when a dependency is not found on disk</li>
256<li><code>:semver(<spec>, [selector], [function])</code> match a valid <a href="https://github.com/npm/node-semver"><code>node-semver</code></a> version or range to a selector</li>
257<li><code>:path(<path>)</code> <a href="https://www.npmjs.com/package/glob">glob</a> matching based on dependencies path relative to the project</li>
258<li><code>:type(<type>)</code> <a href="https://github.com/npm/npm-package-arg#result-object">based on currently recognized types</a>. You can also use the aggregate type of <code>registry</code> for any registry dependency (e.g. tag, version, range, alias)</li>
259<li><code>:outdated(<type>)</code> when a dependency is outdated</li>
260<li><code>:vuln(<selector>)</code> when a dependency has a known vulnerability</li>
261</ul>
262<h5 id="semverspec-selector-function"><code>:semver(<spec>, [selector], [function])</code></h5>
263<p>The <code>:semver()</code> pseudo selector allows comparing fields from each node's <code>package.json</code> using <a href="https://github.com/npm/node-semver#readme">semver</a> methods.
264It accepts up to 3 parameters, all but the first of which are optional.</p>
265<ul>
266<li><code>spec</code> a semver version or range</li>
267<li><code>selector</code> an attribute selector for each node (default <code>[version]</code>)</li>
268<li><code>function</code> a semver method to apply, one of: <code>satisfies</code>, <code>intersects</code>, <code>subset</code>, <code>gt</code>, <code>gte</code>, <code>gtr</code>, <code>lt</code>, <code>lte</code>, <code>ltr</code>, <code>eq</code>, <code>neq</code> or the special function <code>infer</code> (default <code>infer</code>)</li>
269</ul>
270<p>When the special <code>infer</code> function is used the <code>spec</code> and the actual value from the node are compared.
271If both are versions, according to <code>semver.valid()</code>, <code>eq</code> is used.
272If both values are ranges, according to <code>!semver.valid()</code>, <code>intersects</code> is used.
273If the values are mixed types <code>satisfies</code> is used.</p>
274<p>Some examples:</p>
275<ul>
276<li><code>:semver(^1.0.0)</code> returns every node that has a <code>version</code> satisfied by the provided range <code>^1.0.0</code></li>
277<li><code>:semver(16.0.0, :attr(engines, [node]))</code> returns every node which has an <code>engines.node</code> property satisfying the version <code>16.0.0</code></li>
278<li><code>:semver(1.0.0, [version], lt)</code> every node with a <code>version</code> less than <code>1.0.0</code></li>
279</ul>
280<h5 id="outdatedtype"><code>:outdated(<type>)</code></h5>
281<p>The <code>:outdated</code> pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated.
282The type parameter may be one of the following:</p>
283<ul>
284<li><code>any</code> (default) a version exists that is greater than the current one</li>
285<li><code>in-range</code> a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies</li>
286<li><code>out-of-range</code> a version exists that is greater than the current one, does not satisfy at least one of its parent's dependencies</li>
287<li><code>major</code> a version exists that is a semver major greater than the current one</li>
288<li><code>minor</code> a version exists that is a semver minor greater than the current one</li>
289<li><code>patch</code> a version exists that is a semver patch greater than the current one</li>
290</ul>
291<p>In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects.
292The following data can be found under the <code>queryContext</code> property of each node.</p>
293<ul>
294<li><code>versions</code> an array of every available version of the given node</li>
295<li><code>outdated.inRange</code> an array of objects, each with a <code>from</code> and <code>versions</code>, where <code>from</code> is the on-disk location of the node that depends on the current node and <code>versions</code> is an array of all available versions that satisfies that dependency.
296This is only populated if <code>:outdated(in-range)</code> is used.</li>
297<li><code>outdated.outOfRange</code> an array of objects, identical in shape to <code>inRange</code>, but where the <code>versions</code> array is every available version that does not satisfy the dependency.
298This is only populated if <code>:outdated(out-of-range)</code> is used.</li>
299</ul>
300<p>Some examples:</p>
301<ul>
302<li><code>:root > :outdated(major)</code> returns every direct dependency that has a new semver major release</li>
303<li><code>.prod:outdated(in-range)</code> returns production dependencies that have a new release that satisfies at least one of its parent's dependencies</li>
304</ul>
305<h5 id="vuln"><code>:vuln</code></h5>
306<p>The <code>:vuln</code> pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability.
307Only dependencies whose current version matches a vulnerability will be returned.
308For example if you have <code>semver@7.6.0</code> in your tree, a vulnerability for <code>semver</code> which affects versions <code><=6.3.1</code> will not match.</p>
309<p>You can also filter results by certain attributes in advisories.
310Currently that includes <code>severity</code> and <code>cwe</code>.
311Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.</p>
312<p>In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the <code>queryContext</code> attribute of each node under the <code>advisories</code> attribute.</p>
313<p>Some examples:</p>
314<ul>
315<li><code>:root > .prod:vuln</code> returns direct production dependencies with any known vulnerability</li>
316<li><code>:vuln([severity=high])</code> returns only dependencies with a vulnerability with a <code>high</code> severity.</li>
317<li><code>:vuln([severity=high],[severity=moderate])</code> returns only dependencies with a vulnerability with a <code>high</code> or <code>moderate</code> severity.</li>
318<li><code>:vuln([cwe=1333])</code> returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)</li>
319</ul>
320<h4 id="attribute-selectors"><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors">Attribute Selectors</a></h4>
321<p>The attribute selector evaluates the key/value pairs in <code>package.json</code> if they are <code>String</code>s.</p>
322<ul>
323<li><code>[]</code> attribute selector (ie.
324existence of attribute)</li>
325<li><code>[attribute=value]</code> attribute value is equivalent...</li>
326<li><code>[attribute~=value]</code> attribute value contains word...</li>
327<li><code>[attribute*=value]</code> attribute value contains string...</li>
328<li><code>[attribute|=value]</code> attribute value is equal to or starts with...</li>
329<li><code>[attribute^=value]</code> attribute value starts with...</li>
330<li><code>[attribute$=value]</code> attribute value ends with...</li>
331</ul>
332<h4 id="array--object-attribute-selectors"><code>Array</code> & <code>Object</code> Attribute Selectors</h4>
333<p>The generic <code>:attr()</code> pseudo selector standardizes a pattern which can be used for attribute selection of <code>Object</code>s, <code>Array</code>s or <code>Arrays</code> of <code>Object</code>s accessible via <code>Arborist</code>'s <code>Node.package</code> metadata.
334This allows for iterative attribute selection beyond top-level <code>String</code> evaluation.
335The last argument passed to <code>:attr()</code> must be an <code>attribute</code> selector or a nested <code>:attr()</code>.
336See examples below:</p>
337<h4 id="objects"><code>Objects</code></h4>
338<pre><code class="language-css">/* return dependencies that have a `scripts.test` containing `"tap"` */
339*:attr(scripts, [test~=tap])
340</code></pre>
341<h4 id="nested-objects">Nested <code>Objects</code></h4>
342<p>Nested objects are expressed as sequential arguments to <code>:attr()</code>.</p>
343<pre><code class="language-css">/* return dependencies that have a [testling config](https://ci.testling.com/guide/advanced_configuration) for opera browsers */
344*:attr(testling, browsers, [~=opera])
345</code></pre>
346<h4 id="arrays"><code>Arrays</code></h4>
347<p><code>Array</code>s specifically uses a special/reserved <code>.</code> character in place of a typical attribute name.
348<code>Arrays</code> also support exact <code>value</code> matching when a <code>String</code> is passed to the selector.</p>
349<h5 id="example-of-an-array-attribute-selection">Example of an <code>Array</code> Attribute Selection:</h5>
350<pre><code class="language-css">/* removes the distinction between properties & arrays */
351/* ie. we'd have to check the property & iterate to match selection */
352*:attr([keywords^=react])
353*:attr(contributors, :attr([name~=Jordan]))
354</code></pre>
355<h5 id="example-of-an-array-matching-directly-to-a-value">Example of an <code>Array</code> matching directly to a value:</h5>
356<pre><code class="language-css">/* return dependencies that have the exact keyword "react" */
357/* this is equivalent to `*:keywords([value="react"])` */
358*:attr([keywords=react])
359</code></pre>
360<h5 id="example-of-an-array-of-objects">Example of an <code>Array</code> of <code>Object</code>s:</h5>
361<pre><code class="language-css">/* returns */
362*:attr(contributors, [email=ruyadorno@github.com])
363</code></pre>
364<h3 id="groups">Groups</h3>
365<p>Dependency groups are defined by the package relationships to their ancestors (ie.
366the dependency types that are defined in <code>package.json</code>).
367This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost.
368Dependencies are allowed to be included in multiple groups (ex.
369a <code>prod</code> dependency may also be a <code>dev</code> dependency (in that it's also required by another <code>dev</code> dependency) & may also be <code>bundled</code> - a selector for that type of dependency would look like: <code>*.prod.dev.bundled</code>).</p>
370<ul>
371<li><code>.prod</code></li>
372<li><code>.dev</code></li>
373<li><code>.optional</code></li>
374<li><code>.peer</code></li>
375<li><code>.bundled</code></li>
376<li><code>.workspace</code></li>
377</ul>
378<p>Please note that currently <code>workspace</code> deps are always <code>prod</code> dependencies.
379Additionally the <code>.root</code> dependency is also considered a <code>prod</code> dependency.</p>
380<h3 id="programmatic-usage">Programmatic Usage</h3>
381<ul>
382<li><code>Arborist</code>'s <code>Node</code> Class has a <code>.querySelectorAll()</code> method
383<ul>
384<li>this method will return a filtered, flattened dependency Arborist <code>Node</code> list based on a valid query selector</li>
385</ul>
386</li>
387</ul>
388<pre><code class="language-js">const Arborist = require('@npmcli/arborist')
389const arb = new Arborist({})
390</code></pre>
391<pre><code class="language-js">// root-level
392arb.loadActual().then(async (tree) => {
393 // query all production dependencies
394 const results = await tree.querySelectorAll('.prod')
395 console.log(results)
396})
397</code></pre>
398<pre><code class="language-js">// iterative
399arb.loadActual().then(async (tree) => {
400 // query for the deduped version of react
401 const results = await tree.querySelectorAll('#react:not(:deduped)')
402 // query the deduped react for git deps
403 const deps = await results[0].querySelectorAll(':type(git)')
404 console.log(deps)
405})
406</code></pre>
407<h2 id="see-also">See Also</h2>
408<ul>
409<li><a href="../commands/npm-query.html">npm query</a></li>
410<li><a href="https://npm.im/@npmcli/arborist">@npmcli/arborist</a></li>
411</ul></div>
412
413<footer id="edit">
414<a href="https://github.com/npm/cli/edit/latest/docs/lib/content/using-npm/dependency-selectors.md">
415<svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;">
416<path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path>
417</svg>
418Edit this page on GitHub
419</a>
420</footer>
421</section>
422
423
424
425</body></html>