codekingpro/portable-devtools

1.TH "SELECTORS" "7" "April 2026" "NPM@11.13.0" ""
2.SH "NAME"
3\fBSelectors\fR - Dependency Selector Syntax & Querying
4.SS "Description"
5.P
6The npm help query command exposes a new dependency selector syntax (informed by & respecting many aspects of the \fBCSS Selectors 4 Spec\fR \fI\(lahttps://dev.w3.org/csswg/selectors4/#relational\(ra\fR) which:
7.RS 0
8.IP \(bu 4
9Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax
10.IP \(bu 4
11Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible
12.IP \(bu 4
13Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
14.IP \(bu 4
15Consolidates redundant logic of similar query commands in \fBnpm\fR (ex. \fBnpm fund\fR, \fBnpm ls\fR, \fBnpm outdated\fR, \fBnpm audit\fR ...)
16.RE 0
17
18.SS "Dependency Selector Syntax"
19.SS "Overview:"
20.RS 0
21.IP \(bu 4
22there is no "type" or "tag" selectors (ex. \fBdiv, h1, a\fR) as a dependency/target is the only type of \fBNode\fR that can be queried
23.IP \(bu 4
24the term "dependencies" is in reference to any \fBNode\fR found in a \fBtree\fR returned by \fBArborist\fR
25.RE 0
26
27.SS "Combinators"
28.RS 0
29.IP \(bu 4
30\fB>\fR direct descendant/child
31.IP \(bu 4
32\fB \fR any descendant/child
33.IP \(bu 4
34\fB~\fR sibling
35.RE 0
36
37.SS "Selectors"
38.RS 0
39.IP \(bu 4
40\fB*\fR universal selector
41.IP \(bu 4
42\fB#<name>\fR dependency selector (equivalent to \fB\[lB]name="..."\[rB]\fR)
43.IP \(bu 4
44\fB#<name>@<version>\fR (equivalent to \fB\[lB]name=<name>\[rB]:semver(<version>)\fR)
45.IP \(bu 4
46\fB,\fR selector list delimiter
47.IP \(bu 4
48\fB.\fR dependency type selector
49.IP \(bu 4
50\fB:\fR pseudo selector
51.RE 0
52
53.SS "Dependency Type Selectors"
54.RS 0
55.IP \(bu 4
56\fB.prod\fR dependency found in the \fBdependencies\fR section of \fBpackage.json\fR, or is a child of said dependency
57.IP \(bu 4
58\fB.dev\fR dependency found in the \fBdevDependencies\fR section of \fBpackage.json\fR, or is a child of said dependency
59.IP \(bu 4
60\fB.optional\fR dependency found in the \fBoptionalDependencies\fR section of \fBpackage.json\fR, or has \fB"optional": true\fR set in its entry in the \fBpeerDependenciesMeta\fR section of \fBpackage.json\fR, or a child of said dependency
61.IP \(bu 4
62\fB.peer\fR dependency found in the \fBpeerDependencies\fR section of \fBpackage.json\fR
63.IP \(bu 4
64\fB.workspace\fR dependency found in the \fB\[rs]fBworkspaces\[rs]fR\fR \fI\(lahttps://docs.npmjs.com/cli/v8/using-npm/workspaces\(ra\fR section of \fBpackage.json\fR
65.IP \(bu 4
66\fB.bundled\fR dependency found in the \fBbundleDependencies\fR section of \fBpackage.json\fR, or is a child of said dependency
67.RE 0
68
69.SS "Pseudo Selectors"
70.RS 0
71.IP \(bu 4
72\fB\[rs]fB:not(<selector>)\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:not\(ra\fR
73.IP \(bu 4
74\fB\[rs]fB:has(<selector>)\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:has\(ra\fR
75.IP \(bu 4
76\fB\[rs]fB:is(<selector list>)\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:is\(ra\fR
77.IP \(bu 4
78\fB\[rs]fB:root\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:root\(ra\fR matches the root node/dependency
79.IP \(bu 4
80\fB\[rs]fB:scope\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:scope\(ra\fR matches node/dependency it was queried against
81.IP \(bu 4
82\fB\[rs]fB:empty\[rs]fR\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/:empty\(ra\fR when a dependency has no dependencies
83.IP \(bu 4
84\fB\[rs]fB:private\[rs]fR\fR \fI\(lahttps://docs.npmjs.com/cli/v8/configuring-npm/package-json#private\(ra\fR when a dependency is private
85.IP \(bu 4
86\fB:link\fR when a dependency is linked (for instance, workspaces or packages manually \fB\[rs]fBlinked\[rs]fR\fR \fI\(lahttps://docs.npmjs.com/cli/v8/commands/npm-link\(ra\fR
87.IP \(bu 4
88\fB:deduped\fR when a dependency has been deduped (note that this does \fInot\fR always mean the dependency has been hoisted to the root of node_modules)
89.IP \(bu 4
90\fB:overridden\fR when a dependency has been overridden
91.IP \(bu 4
92\fB:extraneous\fR when a dependency exists but is not defined as a dependency of any node
93.IP \(bu 4
94\fB:invalid\fR when a dependency version is out of its ancestors specified range
95.IP \(bu 4
96\fB:missing\fR when a dependency is not found on disk
97.IP \(bu 4
98\fB:semver(<spec>, \[lB]selector\[rB], \[lB]function\[rB])\fR match a valid \fB\[rs]fBnode-semver\[rs]fR\fR \fI\(lahttps://github.com/npm/node-semver\(ra\fR version or range to a selector
99.IP \(bu 4
100\fB:path(<path>)\fR \fBglob\fR \fI\(lahttps://www.npmjs.com/package/glob\(ra\fR matching based on dependencies path relative to the project
101.IP \(bu 4
102\fB:type(<type>)\fR \fBbased on currently recognized types\fR \fI\(lahttps://github.com/npm/npm-package-arg#result-object\(ra\fR. You can also use the aggregate type of \fBregistry\fR for any registry dependency (e.g. tag, version, range, alias)
103.IP \(bu 4
104\fB:outdated(<type>)\fR when a dependency is outdated
105.IP \(bu 4
106\fB:vuln(<selector>)\fR when a dependency has a known vulnerability
107.RE 0
108
109.SS "\fB:semver(<spec>, \[lB]selector\[rB], \[lB]function\[rB])\fR"
110.P
111The \fB:semver()\fR pseudo selector allows comparing fields from each node's \fBpackage.json\fR using \fBsemver\fR \fI\(lahttps://github.com/npm/node-semver#readme\(ra\fR methods. It accepts up to 3 parameters, all but the first of which are optional.
112.RS 0
113.IP \(bu 4
114\fBspec\fR a semver version or range
115.IP \(bu 4
116\fBselector\fR an attribute selector for each node (default \fB\[lB]version\[rB]\fR)
117.IP \(bu 4
118\fBfunction\fR a semver method to apply, one of: \fBsatisfies\fR, \fBintersects\fR, \fBsubset\fR, \fBgt\fR, \fBgte\fR, \fBgtr\fR, \fBlt\fR, \fBlte\fR, \fBltr\fR, \fBeq\fR, \fBneq\fR or the special function \fBinfer\fR (default \fBinfer\fR)
119.RE 0
120
121.P
122When the special \fBinfer\fR function is used the \fBspec\fR and the actual value from the node are compared. If both are versions, according to \fBsemver.valid()\fR, \fBeq\fR is used. If both values are ranges, according to \fB!semver.valid()\fR, \fBintersects\fR is used. If the values are mixed types \fBsatisfies\fR is used.
123.P
124Some examples:
125.RS 0
126.IP \(bu 4
127\fB:semver(^1.0.0)\fR returns every node that has a \fBversion\fR satisfied by the provided range \fB^1.0.0\fR
128.IP \(bu 4
129\fB:semver(16.0.0, :attr(engines, \[lB]node\[rB]))\fR returns every node which has an \fBengines.node\fR property satisfying the version \fB16.0.0\fR
130.IP \(bu 4
131\fB:semver(1.0.0, \[lB]version\[rB], lt)\fR every node with a \fBversion\fR less than \fB1.0.0\fR
132.RE 0
133
134.SS "\fB:outdated(<type>)\fR"
135.P
136The \fB:outdated\fR 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:
137.RS 0
138.IP \(bu 4
139\fBany\fR (default) a version exists that is greater than the current one
140.IP \(bu 4
141\fBin-range\fR a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies
142.IP \(bu 4
143\fBout-of-range\fR a version exists that is greater than the current one, does not satisfy at least one of its parent's dependencies
144.IP \(bu 4
145\fBmajor\fR a version exists that is a semver major greater than the current one
146.IP \(bu 4
147\fBminor\fR a version exists that is a semver minor greater than the current one
148.IP \(bu 4
149\fBpatch\fR a version exists that is a semver patch greater than the current one
150.RE 0
151
152.P
153In 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 \fBqueryContext\fR property of each node.
154.RS 0
155.IP \(bu 4
156\fBversions\fR an array of every available version of the given node
157.IP \(bu 4
158\fBoutdated.inRange\fR an array of objects, each with a \fBfrom\fR and \fBversions\fR, where \fBfrom\fR is the on-disk location of the node that depends on the current node and \fBversions\fR is an array of all available versions that satisfies that dependency. This is only populated if \fB:outdated(in-range)\fR is used.
159.IP \(bu 4
160\fBoutdated.outOfRange\fR an array of objects, identical in shape to \fBinRange\fR, but where the \fBversions\fR array is every available version that does not satisfy the dependency. This is only populated if \fB:outdated(out-of-range)\fR is used.
161.RE 0
162
163.P
164Some examples:
165.RS 0
166.IP \(bu 4
167\fB:root > :outdated(major)\fR returns every direct dependency that has a new semver major release
168.IP \(bu 4
169\fB.prod:outdated(in-range)\fR returns production dependencies that have a new release that satisfies at least one of its parent's dependencies
170.RE 0
171
172.SS "\fB:vuln\fR"
173.P
174The \fB:vuln\fR 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 \fBsemver@7.6.0\fR in your tree, a vulnerability for \fBsemver\fR which affects versions \fB<=6.3.1\fR will not match.
175.P
176You can also filter results by certain attributes in advisories. Currently that includes \fBseverity\fR and \fBcwe\fR. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
177.P
178In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the \fBqueryContext\fR attribute of each node under the \fBadvisories\fR attribute.
179.P
180Some examples:
181.RS 0
182.IP \(bu 4
183\fB:root > .prod:vuln\fR returns direct production dependencies with any known vulnerability
184.IP \(bu 4
185\fB:vuln(\[lB]severity=high\[rB])\fR returns only dependencies with a vulnerability with a \fBhigh\fR severity.
186.IP \(bu 4
187\fB:vuln(\[lB]severity=high\[rB],\[lB]severity=moderate\[rB])\fR returns only dependencies with a vulnerability with a \fBhigh\fR or \fBmoderate\fR severity.
188.IP \(bu 4
189\fB:vuln(\[lB]cwe=1333\[rB])\fR returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)
190.RE 0
191
192.SS "\fBAttribute Selectors\fR \fI\(lahttps://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors\(ra\fR"
193.P
194The attribute selector evaluates the key/value pairs in \fBpackage.json\fR if they are \fBString\fRs.
195.RS 0
196.IP \(bu 4
197\fB\[lB]\[rB]\fR attribute selector (ie. existence of attribute)
198.IP \(bu 4
199\fB\[lB]attribute=value\[rB]\fR attribute value is equivalent...
200.IP \(bu 4
201\fB\[lB]attribute~=value\[rB]\fR attribute value contains word...
202.IP \(bu 4
203\fB\[lB]attribute*=value\[rB]\fR attribute value contains string...
204.IP \(bu 4
205\fB\[lB]attribute|=value\[rB]\fR attribute value is equal to or starts with...
206.IP \(bu 4
207\fB\[lB]attribute^=value\[rB]\fR attribute value starts with...
208.IP \(bu 4
209\fB\[lB]attribute$=value\[rB]\fR attribute value ends with...
210.RE 0
211
212.SS "\fBArray\fR & \fBObject\fR Attribute Selectors"
213.P
214The generic \fB:attr()\fR pseudo selector standardizes a pattern which can be used for attribute selection of \fBObject\fRs, \fBArray\fRs or \fBArrays\fR of \fBObject\fRs accessible via \fBArborist\fR's \fBNode.package\fR metadata. This allows for iterative attribute selection beyond top-level \fBString\fR evaluation. The last argument passed to \fB:attr()\fR must be an \fBattribute\fR selector or a nested \fB:attr()\fR. See examples below:
215.SS "\fBObjects\fR"
216.P
217.RS 2
218.nf
219/* return dependencies that have a `scripts.test` containing `"tap"` */
220*:attr(scripts, \[lB]test~=tap\[rB])
221.fi
222.RE
223.SS "Nested \fBObjects\fR"
224.P
225Nested objects are expressed as sequential arguments to \fB:attr()\fR.
226.P
227.RS 2
228.nf
229/* return dependencies that have a \[lB]testling config\[rB](https://ci.testling.com/guide/advanced_configuration) for opera browsers */
230*:attr(testling, browsers, \[lB]~=opera\[rB])
231.fi
232.RE
233.SS "\fBArrays\fR"
234.P
235\fBArray\fRs specifically uses a special/reserved \fB.\fR character in place of a typical attribute name. \fBArrays\fR also support exact \fBvalue\fR matching when a \fBString\fR is passed to the selector.
236.SS "Example of an \fBArray\fR Attribute Selection:"
237.P
238.RS 2
239.nf
240/* removes the distinction between properties & arrays */
241/* ie. we'd have to check the property & iterate to match selection */
242*:attr(\[lB]keywords^=react\[rB])
243*:attr(contributors, :attr(\[lB]name~=Jordan\[rB]))
244.fi
245.RE
246.SS "Example of an \fBArray\fR matching directly to a value:"
247.P
248.RS 2
249.nf
250/* return dependencies that have the exact keyword "react" */
251/* this is equivalent to `*:keywords(\[lB]value="react"\[rB])` */
252*:attr(\[lB]keywords=react\[rB])
253.fi
254.RE
255.SS "Example of an \fBArray\fR of \fBObject\fRs:"
256.P
257.RS 2
258.nf
259/* returns */
260*:attr(contributors, \[lB]email=ruyadorno@github.com\[rB])
261.fi
262.RE
263.SS "Groups"
264.P
265Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in \fBpackage.json\fR). 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 \fBprod\fR dependency may also be a \fBdev\fR dependency (in that it's also required by another \fBdev\fR dependency) & may also be \fBbundled\fR - a selector for that type of dependency would look like: \fB*.prod.dev.bundled\fR).
266.RS 0
267.IP \(bu 4
268\fB.prod\fR
269.IP \(bu 4
270\fB.dev\fR
271.IP \(bu 4
272\fB.optional\fR
273.IP \(bu 4
274\fB.peer\fR
275.IP \(bu 4
276\fB.bundled\fR
277.IP \(bu 4
278\fB.workspace\fR
279.RE 0
280
281.P
282Please note that currently \fBworkspace\fR deps are always \fBprod\fR dependencies. Additionally the \fB.root\fR dependency is also considered a \fBprod\fR dependency.
283.SS "Programmatic Usage"
284.RS 0
285.IP \(bu 4
286\fBArborist\fR's \fBNode\fR Class has a \fB.querySelectorAll()\fR method
287.RS 4
288.IP \(bu 4
289this method will return a filtered, flattened dependency Arborist \fBNode\fR list based on a valid query selector
290.RE 0
291
292.RE 0
293
294.P
295.RS 2
296.nf
297const Arborist = require('@npmcli/arborist')
298const arb = new Arborist({})
299.fi
300.RE
301.P
302.RS 2
303.nf
304// root-level
305arb.loadActual().then(async (tree) => {
306  // query all production dependencies
307  const results = await tree.querySelectorAll('.prod')
308  console.log(results)
309})
310.fi
311.RE
312.P
313.RS 2
314.nf
315// iterative
316arb.loadActual().then(async (tree) => {
317  // query for the deduped version of react
318  const results = await tree.querySelectorAll('#react:not(:deduped)')
319  // query the deduped react for git deps
320  const deps = await results\[lB]0\[rB].querySelectorAll(':type(git)')
321  console.log(deps)
322})
323.fi
324.RE
325.SH "SEE ALSO"
326.RS 0
327.IP \(bu 4
328npm help query
329.IP \(bu 4
330\fB@npmcli/arborist\fR \fI\(lahttps://npm.im/@npmcli/arborist\(ra\fR
331.RE 0
332