11cb0ef41Sopenharmony_ci<!DOCTYPE html><html><head> 21cb0ef41Sopenharmony_ci<meta charset="utf-8"> 31cb0ef41Sopenharmony_ci<title>Dependency Selector Syntax & Querying</title> 41cb0ef41Sopenharmony_ci<style> 51cb0ef41Sopenharmony_cibody { 61cb0ef41Sopenharmony_ci background-color: #ffffff; 71cb0ef41Sopenharmony_ci color: #24292e; 81cb0ef41Sopenharmony_ci 91cb0ef41Sopenharmony_ci margin: 0; 101cb0ef41Sopenharmony_ci 111cb0ef41Sopenharmony_ci line-height: 1.5; 121cb0ef41Sopenharmony_ci 131cb0ef41Sopenharmony_ci font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; 141cb0ef41Sopenharmony_ci} 151cb0ef41Sopenharmony_ci#rainbar { 161cb0ef41Sopenharmony_ci height: 10px; 171cb0ef41Sopenharmony_ci background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff); 181cb0ef41Sopenharmony_ci} 191cb0ef41Sopenharmony_ci 201cb0ef41Sopenharmony_cia { 211cb0ef41Sopenharmony_ci text-decoration: none; 221cb0ef41Sopenharmony_ci color: #0366d6; 231cb0ef41Sopenharmony_ci} 241cb0ef41Sopenharmony_cia:hover { 251cb0ef41Sopenharmony_ci text-decoration: underline; 261cb0ef41Sopenharmony_ci} 271cb0ef41Sopenharmony_ci 281cb0ef41Sopenharmony_cipre { 291cb0ef41Sopenharmony_ci margin: 1em 0px; 301cb0ef41Sopenharmony_ci padding: 1em; 311cb0ef41Sopenharmony_ci border: solid 1px #e1e4e8; 321cb0ef41Sopenharmony_ci border-radius: 6px; 331cb0ef41Sopenharmony_ci 341cb0ef41Sopenharmony_ci display: block; 351cb0ef41Sopenharmony_ci overflow: auto; 361cb0ef41Sopenharmony_ci 371cb0ef41Sopenharmony_ci white-space: pre; 381cb0ef41Sopenharmony_ci 391cb0ef41Sopenharmony_ci background-color: #f6f8fa; 401cb0ef41Sopenharmony_ci color: #393a34; 411cb0ef41Sopenharmony_ci} 421cb0ef41Sopenharmony_cicode { 431cb0ef41Sopenharmony_ci font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace; 441cb0ef41Sopenharmony_ci font-size: 85%; 451cb0ef41Sopenharmony_ci padding: 0.2em 0.4em; 461cb0ef41Sopenharmony_ci background-color: #f6f8fa; 471cb0ef41Sopenharmony_ci color: #393a34; 481cb0ef41Sopenharmony_ci} 491cb0ef41Sopenharmony_cipre > code { 501cb0ef41Sopenharmony_ci padding: 0; 511cb0ef41Sopenharmony_ci background-color: inherit; 521cb0ef41Sopenharmony_ci color: inherit; 531cb0ef41Sopenharmony_ci} 541cb0ef41Sopenharmony_cih1, h2, h3 { 551cb0ef41Sopenharmony_ci font-weight: 600; 561cb0ef41Sopenharmony_ci} 571cb0ef41Sopenharmony_ci 581cb0ef41Sopenharmony_ci#logobar { 591cb0ef41Sopenharmony_ci background-color: #333333; 601cb0ef41Sopenharmony_ci margin: 0 auto; 611cb0ef41Sopenharmony_ci padding: 1em 4em; 621cb0ef41Sopenharmony_ci} 631cb0ef41Sopenharmony_ci#logobar .logo { 641cb0ef41Sopenharmony_ci float: left; 651cb0ef41Sopenharmony_ci} 661cb0ef41Sopenharmony_ci#logobar .title { 671cb0ef41Sopenharmony_ci font-weight: 600; 681cb0ef41Sopenharmony_ci color: #dddddd; 691cb0ef41Sopenharmony_ci float: left; 701cb0ef41Sopenharmony_ci margin: 5px 0 0 1em; 711cb0ef41Sopenharmony_ci} 721cb0ef41Sopenharmony_ci#logobar:after { 731cb0ef41Sopenharmony_ci content: ""; 741cb0ef41Sopenharmony_ci display: block; 751cb0ef41Sopenharmony_ci clear: both; 761cb0ef41Sopenharmony_ci} 771cb0ef41Sopenharmony_ci 781cb0ef41Sopenharmony_ci#content { 791cb0ef41Sopenharmony_ci margin: 0 auto; 801cb0ef41Sopenharmony_ci padding: 0 4em; 811cb0ef41Sopenharmony_ci} 821cb0ef41Sopenharmony_ci 831cb0ef41Sopenharmony_ci#table_of_contents > h2 { 841cb0ef41Sopenharmony_ci font-size: 1.17em; 851cb0ef41Sopenharmony_ci} 861cb0ef41Sopenharmony_ci#table_of_contents ul:first-child { 871cb0ef41Sopenharmony_ci border: solid 1px #e1e4e8; 881cb0ef41Sopenharmony_ci border-radius: 6px; 891cb0ef41Sopenharmony_ci padding: 1em; 901cb0ef41Sopenharmony_ci background-color: #f6f8fa; 911cb0ef41Sopenharmony_ci color: #393a34; 921cb0ef41Sopenharmony_ci} 931cb0ef41Sopenharmony_ci#table_of_contents ul { 941cb0ef41Sopenharmony_ci list-style-type: none; 951cb0ef41Sopenharmony_ci padding-left: 1.5em; 961cb0ef41Sopenharmony_ci} 971cb0ef41Sopenharmony_ci#table_of_contents li { 981cb0ef41Sopenharmony_ci font-size: 0.9em; 991cb0ef41Sopenharmony_ci} 1001cb0ef41Sopenharmony_ci#table_of_contents li a { 1011cb0ef41Sopenharmony_ci color: #000000; 1021cb0ef41Sopenharmony_ci} 1031cb0ef41Sopenharmony_ci 1041cb0ef41Sopenharmony_ciheader.title { 1051cb0ef41Sopenharmony_ci border-bottom: solid 1px #e1e4e8; 1061cb0ef41Sopenharmony_ci} 1071cb0ef41Sopenharmony_ciheader.title > h1 { 1081cb0ef41Sopenharmony_ci margin-bottom: 0.25em; 1091cb0ef41Sopenharmony_ci} 1101cb0ef41Sopenharmony_ciheader.title > .description { 1111cb0ef41Sopenharmony_ci display: block; 1121cb0ef41Sopenharmony_ci margin-bottom: 0.5em; 1131cb0ef41Sopenharmony_ci line-height: 1; 1141cb0ef41Sopenharmony_ci} 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_cifooter#edit { 1171cb0ef41Sopenharmony_ci border-top: solid 1px #e1e4e8; 1181cb0ef41Sopenharmony_ci margin: 3em 0 4em 0; 1191cb0ef41Sopenharmony_ci padding-top: 2em; 1201cb0ef41Sopenharmony_ci} 1211cb0ef41Sopenharmony_ci</style> 1221cb0ef41Sopenharmony_ci</head> 1231cb0ef41Sopenharmony_ci<body> 1241cb0ef41Sopenharmony_ci<div id="banner"> 1251cb0ef41Sopenharmony_ci<div id="rainbar"></div> 1261cb0ef41Sopenharmony_ci<div id="logobar"> 1271cb0ef41Sopenharmony_ci<svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700"> 1281cb0ef41Sopenharmony_ci<polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon> 1291cb0ef41Sopenharmony_ci<polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon> 1301cb0ef41Sopenharmony_ci</svg> 1311cb0ef41Sopenharmony_ci<div class="title"> 1321cb0ef41Sopenharmony_cinpm command-line interface 1331cb0ef41Sopenharmony_ci</div> 1341cb0ef41Sopenharmony_ci</div> 1351cb0ef41Sopenharmony_ci</div> 1361cb0ef41Sopenharmony_ci 1371cb0ef41Sopenharmony_ci<section id="content"> 1381cb0ef41Sopenharmony_ci<header class="title"> 1391cb0ef41Sopenharmony_ci<h1 id="dependency-selector-syntax--querying">Dependency Selector Syntax & Querying</h1> 1401cb0ef41Sopenharmony_ci<span class="description">Dependency Selector Syntax & Querying</span> 1411cb0ef41Sopenharmony_ci</header> 1421cb0ef41Sopenharmony_ci 1431cb0ef41Sopenharmony_ci<section id="table_of_contents"> 1441cb0ef41Sopenharmony_ci<h2 id="table-of-contents">Table of contents</h2> 1451cb0ef41Sopenharmony_ci<div id="_table_of_contents"><ul><li><a href="#see-also">See Also</a></li></ul></div> 1461cb0ef41Sopenharmony_ci</section> 1471cb0ef41Sopenharmony_ci 1481cb0ef41Sopenharmony_ci<div id="_content"><h3 id="description">Description</h3> 1491cb0ef41Sopenharmony_ci<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> 1501cb0ef41Sopenharmony_ci<ul> 1511cb0ef41Sopenharmony_ci<li>Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax</li> 1521cb0ef41Sopenharmony_ci<li>Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible</li> 1531cb0ef41Sopenharmony_ci<li>Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata</li> 1541cb0ef41Sopenharmony_ci<li>Consolidates redundant logic of similar query commands in <code>npm</code> (ex. <code>npm fund</code>, <code>npm ls</code>, <code>npm outdated</code>, <code>npm audit</code> ...)</li> 1551cb0ef41Sopenharmony_ci</ul> 1561cb0ef41Sopenharmony_ci<h3 id="dependency-selector-syntax">Dependency Selector Syntax</h3> 1571cb0ef41Sopenharmony_ci<h4 id="overview">Overview:</h4> 1581cb0ef41Sopenharmony_ci<ul> 1591cb0ef41Sopenharmony_ci<li>there is no "type" or "tag" selectors (ex. <code>div, h1, a</code>) as a dependency/target is the only type of <code>Node</code> that can be queried</li> 1601cb0ef41Sopenharmony_ci<li>the term "dependencies" is in reference to any <code>Node</code> found in a <code>tree</code> returned by <code>Arborist</code></li> 1611cb0ef41Sopenharmony_ci</ul> 1621cb0ef41Sopenharmony_ci<h4 id="combinators">Combinators</h4> 1631cb0ef41Sopenharmony_ci<ul> 1641cb0ef41Sopenharmony_ci<li><code>></code> direct descendant/child</li> 1651cb0ef41Sopenharmony_ci<li><code> </code> any descendant/child</li> 1661cb0ef41Sopenharmony_ci<li><code>~</code> sibling</li> 1671cb0ef41Sopenharmony_ci</ul> 1681cb0ef41Sopenharmony_ci<h4 id="selectors">Selectors</h4> 1691cb0ef41Sopenharmony_ci<ul> 1701cb0ef41Sopenharmony_ci<li><code>*</code> universal selector</li> 1711cb0ef41Sopenharmony_ci<li><code>#<name></code> dependency selector (equivalent to <code>[name="..."]</code>)</li> 1721cb0ef41Sopenharmony_ci<li><code>#<name>@<version></code> (equivalent to <code>[name=<name>]:semver(<version>)</code>)</li> 1731cb0ef41Sopenharmony_ci<li><code>,</code> selector list delimiter</li> 1741cb0ef41Sopenharmony_ci<li><code>.</code> dependency type selector</li> 1751cb0ef41Sopenharmony_ci<li><code>:</code> pseudo selector</li> 1761cb0ef41Sopenharmony_ci</ul> 1771cb0ef41Sopenharmony_ci<h4 id="dependency-type-selectors">Dependency Type Selectors</h4> 1781cb0ef41Sopenharmony_ci<ul> 1791cb0ef41Sopenharmony_ci<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> 1801cb0ef41Sopenharmony_ci<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> 1811cb0ef41Sopenharmony_ci<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> 1821cb0ef41Sopenharmony_ci<li><code>.peer</code> dependency found in the <code>peerDependencies</code> section of <code>package.json</code></li> 1831cb0ef41Sopenharmony_ci<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> 1841cb0ef41Sopenharmony_ci<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> 1851cb0ef41Sopenharmony_ci</ul> 1861cb0ef41Sopenharmony_ci<h4 id="pseudo-selectors">Pseudo Selectors</h4> 1871cb0ef41Sopenharmony_ci<ul> 1881cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:not"><code>:not(<selector>)</code></a></li> 1891cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:has"><code>:has(<selector>)</code></a></li> 1901cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:is"><code>:is(<selector list>)</code></a></li> 1911cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:root"><code>:root</code></a> matches the root node/dependency</li> 1921cb0ef41Sopenharmony_ci<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> 1931cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:empty"><code>:empty</code></a> when a dependency has no dependencies</li> 1941cb0ef41Sopenharmony_ci<li><a href="https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private"><code>:private</code></a> when a dependency is private</li> 1951cb0ef41Sopenharmony_ci<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> 1961cb0ef41Sopenharmony_ci<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> 1971cb0ef41Sopenharmony_ci<li><code>:overridden</code> when a dependency has been overridden</li> 1981cb0ef41Sopenharmony_ci<li><code>:extraneous</code> when a dependency exists but is not defined as a dependency of any node</li> 1991cb0ef41Sopenharmony_ci<li><code>:invalid</code> when a dependency version is out of its ancestors specified range</li> 2001cb0ef41Sopenharmony_ci<li><code>:missing</code> when a dependency is not found on disk</li> 2011cb0ef41Sopenharmony_ci<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> 2021cb0ef41Sopenharmony_ci<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> 2031cb0ef41Sopenharmony_ci<li><code>:type(<type>)</code> <a href="https://github.com/npm/npm-package-arg#result-object">based on currently recognized types</a></li> 2041cb0ef41Sopenharmony_ci<li><code>:outdated(<type>)</code> when a dependency is outdated</li> 2051cb0ef41Sopenharmony_ci<li><code>:vuln(<selector>)</code> when a dependency has a known vulnerability</li> 2061cb0ef41Sopenharmony_ci</ul> 2071cb0ef41Sopenharmony_ci<h5 id="semverspec-selector-function"><code>:semver(<spec>, [selector], [function])</code></h5> 2081cb0ef41Sopenharmony_ci<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. It accepts up to 3 parameters, all but the first of which are optional.</p> 2091cb0ef41Sopenharmony_ci<ul> 2101cb0ef41Sopenharmony_ci<li><code>spec</code> a semver version or range</li> 2111cb0ef41Sopenharmony_ci<li><code>selector</code> an attribute selector for each node (default <code>[version]</code>)</li> 2121cb0ef41Sopenharmony_ci<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> 2131cb0ef41Sopenharmony_ci</ul> 2141cb0ef41Sopenharmony_ci<p>When the special <code>infer</code> function is used the <code>spec</code> and the actual value from the node are compared. If both are versions, according to <code>semver.valid()</code>, <code>eq</code> is used. If both values are ranges, according to <code>!semver.valid()</code>, <code>intersects</code> is used. If the values are mixed types <code>satisfies</code> is used.</p> 2151cb0ef41Sopenharmony_ci<p>Some examples:</p> 2161cb0ef41Sopenharmony_ci<ul> 2171cb0ef41Sopenharmony_ci<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> 2181cb0ef41Sopenharmony_ci<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> 2191cb0ef41Sopenharmony_ci<li><code>:semver(1.0.0, [version], lt)</code> every node with a <code>version</code> less than <code>1.0.0</code></li> 2201cb0ef41Sopenharmony_ci</ul> 2211cb0ef41Sopenharmony_ci<h5 id="outdatedtype"><code>:outdated(<type>)</code></h5> 2221cb0ef41Sopenharmony_ci<p>The <code>:outdated</code> pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated. The type parameter may be one of the following:</p> 2231cb0ef41Sopenharmony_ci<ul> 2241cb0ef41Sopenharmony_ci<li><code>any</code> (default) a version exists that is greater than the current one</li> 2251cb0ef41Sopenharmony_ci<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> 2261cb0ef41Sopenharmony_ci<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> 2271cb0ef41Sopenharmony_ci<li><code>major</code> a version exists that is a semver major greater than the current one</li> 2281cb0ef41Sopenharmony_ci<li><code>minor</code> a version exists that is a semver minor greater than the current one</li> 2291cb0ef41Sopenharmony_ci<li><code>patch</code> a version exists that is a semver patch greater than the current one</li> 2301cb0ef41Sopenharmony_ci</ul> 2311cb0ef41Sopenharmony_ci<p>In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects. The following data can be found under the <code>queryContext</code> property of each node.</p> 2321cb0ef41Sopenharmony_ci<ul> 2331cb0ef41Sopenharmony_ci<li><code>versions</code> an array of every available version of the given node</li> 2341cb0ef41Sopenharmony_ci<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. This is only populated if <code>:outdated(in-range)</code> is used.</li> 2351cb0ef41Sopenharmony_ci<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. This is only populated if <code>:outdated(out-of-range)</code> is used.</li> 2361cb0ef41Sopenharmony_ci</ul> 2371cb0ef41Sopenharmony_ci<p>Some examples:</p> 2381cb0ef41Sopenharmony_ci<ul> 2391cb0ef41Sopenharmony_ci<li><code>:root > :outdated(major)</code> returns every direct dependency that has a new semver major release</li> 2401cb0ef41Sopenharmony_ci<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> 2411cb0ef41Sopenharmony_ci</ul> 2421cb0ef41Sopenharmony_ci<h5 id="vuln"><code>:vuln</code></h5> 2431cb0ef41Sopenharmony_ci<p>The <code>:vuln</code> pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability. Only dependencies whose current version matches a vulnerability will be returned. For 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> 2441cb0ef41Sopenharmony_ci<p>You can also filter results by certain attributes in advisories. Currently that includes <code>severity</code> and <code>cwe</code>. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.</p> 2451cb0ef41Sopenharmony_ci<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> 2461cb0ef41Sopenharmony_ci<p>Some examples:</p> 2471cb0ef41Sopenharmony_ci<ul> 2481cb0ef41Sopenharmony_ci<li><code>:root > .prod:vuln</code> returns direct production dependencies with any known vulnerability</li> 2491cb0ef41Sopenharmony_ci<li><code>:vuln([severity=high])</code> returns only dependencies with a vulnerability with a <code>high</code> severity.</li> 2501cb0ef41Sopenharmony_ci<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> 2511cb0ef41Sopenharmony_ci<li><code>:vuln([cwe=1333])</code> returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)</li> 2521cb0ef41Sopenharmony_ci</ul> 2531cb0ef41Sopenharmony_ci<h4 id="attribute-selectors"><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors">Attribute Selectors</a></h4> 2541cb0ef41Sopenharmony_ci<p>The attribute selector evaluates the key/value pairs in <code>package.json</code> if they are <code>String</code>s.</p> 2551cb0ef41Sopenharmony_ci<ul> 2561cb0ef41Sopenharmony_ci<li><code>[]</code> attribute selector (ie. existence of attribute)</li> 2571cb0ef41Sopenharmony_ci<li><code>[attribute=value]</code> attribute value is equivalent...</li> 2581cb0ef41Sopenharmony_ci<li><code>[attribute~=value]</code> attribute value contains word...</li> 2591cb0ef41Sopenharmony_ci<li><code>[attribute*=value]</code> attribute value contains string...</li> 2601cb0ef41Sopenharmony_ci<li><code>[attribute|=value]</code> attribute value is equal to or starts with...</li> 2611cb0ef41Sopenharmony_ci<li><code>[attribute^=value]</code> attribute value starts with...</li> 2621cb0ef41Sopenharmony_ci<li><code>[attribute$=value]</code> attribute value ends with...</li> 2631cb0ef41Sopenharmony_ci</ul> 2641cb0ef41Sopenharmony_ci<h4 id="array--object-attribute-selectors"><code>Array</code> & <code>Object</code> Attribute Selectors</h4> 2651cb0ef41Sopenharmony_ci<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. This allows for iterative attribute selection beyond top-level <code>String</code> evaluation. The last argument passed to <code>:attr()</code> must be an <code>attribute</code> selector or a nested <code>:attr()</code>. See examples below:</p> 2661cb0ef41Sopenharmony_ci<h4 id="objects"><code>Objects</code></h4> 2671cb0ef41Sopenharmony_ci<pre><code class="language-css">/* return dependencies that have a `scripts.test` containing `"tap"` */ 2681cb0ef41Sopenharmony_ci*:attr(scripts, [test~=tap]) 2691cb0ef41Sopenharmony_ci</code></pre> 2701cb0ef41Sopenharmony_ci<h4 id="nested-objects">Nested <code>Objects</code></h4> 2711cb0ef41Sopenharmony_ci<p>Nested objects are expressed as sequential arguments to <code>:attr()</code>.</p> 2721cb0ef41Sopenharmony_ci<pre><code class="language-css">/* return dependencies that have a testling config for opera browsers */ 2731cb0ef41Sopenharmony_ci*:attr(testling, browsers, [~=opera]) 2741cb0ef41Sopenharmony_ci</code></pre> 2751cb0ef41Sopenharmony_ci<h4 id="arrays"><code>Arrays</code></h4> 2761cb0ef41Sopenharmony_ci<p><code>Array</code>s specifically uses a special/reserved <code>.</code> character in place of a typical attribute name. <code>Arrays</code> also support exact <code>value</code> matching when a <code>String</code> is passed to the selector.</p> 2771cb0ef41Sopenharmony_ci<h5 id="example-of-an-array-attribute-selection">Example of an <code>Array</code> Attribute Selection:</h5> 2781cb0ef41Sopenharmony_ci<pre><code class="language-css">/* removes the distinction between properties & arrays */ 2791cb0ef41Sopenharmony_ci/* ie. we'd have to check the property & iterate to match selection */ 2801cb0ef41Sopenharmony_ci*:attr([keywords^=react]) 2811cb0ef41Sopenharmony_ci*:attr(contributors, :attr([name~=Jordan])) 2821cb0ef41Sopenharmony_ci</code></pre> 2831cb0ef41Sopenharmony_ci<h5 id="example-of-an-array-matching-directly-to-a-value">Example of an <code>Array</code> matching directly to a value:</h5> 2841cb0ef41Sopenharmony_ci<pre><code class="language-css">/* return dependencies that have the exact keyword "react" */ 2851cb0ef41Sopenharmony_ci/* this is equivalent to `*:keywords([value="react"])` */ 2861cb0ef41Sopenharmony_ci*:attr([keywords=react]) 2871cb0ef41Sopenharmony_ci</code></pre> 2881cb0ef41Sopenharmony_ci<h5 id="example-of-an-array-of-objects">Example of an <code>Array</code> of <code>Object</code>s:</h5> 2891cb0ef41Sopenharmony_ci<pre><code class="language-css">/* returns */ 2901cb0ef41Sopenharmony_ci*:attr(contributors, [email=ruyadorno@github.com]) 2911cb0ef41Sopenharmony_ci</code></pre> 2921cb0ef41Sopenharmony_ci<h3 id="groups">Groups</h3> 2931cb0ef41Sopenharmony_ci<p>Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in <code>package.json</code>). This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost. Dependencies are allowed to be included in multiple groups (ex. a <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> 2941cb0ef41Sopenharmony_ci<ul> 2951cb0ef41Sopenharmony_ci<li><code>.prod</code></li> 2961cb0ef41Sopenharmony_ci<li><code>.dev</code></li> 2971cb0ef41Sopenharmony_ci<li><code>.optional</code></li> 2981cb0ef41Sopenharmony_ci<li><code>.peer</code></li> 2991cb0ef41Sopenharmony_ci<li><code>.bundled</code></li> 3001cb0ef41Sopenharmony_ci<li><code>.workspace</code></li> 3011cb0ef41Sopenharmony_ci</ul> 3021cb0ef41Sopenharmony_ci<p>Please note that currently <code>workspace</code> deps are always <code>prod</code> dependencies. Additionally the <code>.root</code> dependency is also considered a <code>prod</code> dependency.</p> 3031cb0ef41Sopenharmony_ci<h3 id="programmatic-usage">Programmatic Usage</h3> 3041cb0ef41Sopenharmony_ci<ul> 3051cb0ef41Sopenharmony_ci<li><code>Arborist</code>'s <code>Node</code> Class has a <code>.querySelectorAll()</code> method 3061cb0ef41Sopenharmony_ci<ul> 3071cb0ef41Sopenharmony_ci<li>this method will return a filtered, flattened dependency Arborist <code>Node</code> list based on a valid query selector</li> 3081cb0ef41Sopenharmony_ci</ul> 3091cb0ef41Sopenharmony_ci</li> 3101cb0ef41Sopenharmony_ci</ul> 3111cb0ef41Sopenharmony_ci<pre><code class="language-js">const Arborist = require('@npmcli/arborist') 3121cb0ef41Sopenharmony_ciconst arb = new Arborist({}) 3131cb0ef41Sopenharmony_ci</code></pre> 3141cb0ef41Sopenharmony_ci<pre><code class="language-js">// root-level 3151cb0ef41Sopenharmony_ciarb.loadActual().then(async (tree) => { 3161cb0ef41Sopenharmony_ci // query all production dependencies 3171cb0ef41Sopenharmony_ci const results = await tree.querySelectorAll('.prod') 3181cb0ef41Sopenharmony_ci console.log(results) 3191cb0ef41Sopenharmony_ci}) 3201cb0ef41Sopenharmony_ci</code></pre> 3211cb0ef41Sopenharmony_ci<pre><code class="language-js">// iterative 3221cb0ef41Sopenharmony_ciarb.loadActual().then(async (tree) => { 3231cb0ef41Sopenharmony_ci // query for the deduped version of react 3241cb0ef41Sopenharmony_ci const results = await tree.querySelectorAll('#react:not(:deduped)') 3251cb0ef41Sopenharmony_ci // query the deduped react for git deps 3261cb0ef41Sopenharmony_ci const deps = await results[0].querySelectorAll(':type(git)') 3271cb0ef41Sopenharmony_ci console.log(deps) 3281cb0ef41Sopenharmony_ci}) 3291cb0ef41Sopenharmony_ci</code></pre> 3301cb0ef41Sopenharmony_ci<h2 id="see-also">See Also</h2> 3311cb0ef41Sopenharmony_ci<ul> 3321cb0ef41Sopenharmony_ci<li><a href="../commands/npm-query.html">npm query</a></li> 3331cb0ef41Sopenharmony_ci<li><a href="https://npm.im/@npmcli/arborist">@npmcli/arborist</a></li> 3341cb0ef41Sopenharmony_ci</ul></div> 3351cb0ef41Sopenharmony_ci 3361cb0ef41Sopenharmony_ci<footer id="edit"> 3371cb0ef41Sopenharmony_ci<a href="https://github.com/npm/cli/edit/latest/docs/content/using-npm/dependency-selectors.md"> 3381cb0ef41Sopenharmony_ci<svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;"> 3391cb0ef41Sopenharmony_ci<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> 3401cb0ef41Sopenharmony_ci</svg> 3411cb0ef41Sopenharmony_ciEdit this page on GitHub 3421cb0ef41Sopenharmony_ci</a> 3431cb0ef41Sopenharmony_ci</footer> 3441cb0ef41Sopenharmony_ci</section> 3451cb0ef41Sopenharmony_ci 3461cb0ef41Sopenharmony_ci 3471cb0ef41Sopenharmony_ci 3481cb0ef41Sopenharmony_ci</body></html>