@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
gat-bypass-2fa-docs
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 218 lines 10.9 KB
Raw
1 ---
2 title: Dependency Selector Syntax & Querying
3 section: 7
4 description: Dependency Selector Syntax & Querying
5 github_repo: npm/cli
6 github_branch: release/v9
7 github_path: docs/lib/content/using-npm/dependency-selectors.md
8 redirect_from:
9 - /cli-documentation/v9/misc/dependency-selectors
10 - /cli-documentation/v9/using-npm/dependency-selectors
11 - /cli/v9/misc/dependency-selectors
12 ---
13
14 ### Description
15
16 The [`npm query`](/cli/v9/commands/npm-query) command exposes a new dependency selector syntax (informed by & respecting many aspects of the [CSS Selectors 4 Spec](https://dev.w3.org/csswg/selectors4/#relational)) which:
17
18 - Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax
19 - Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible
20 - Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
21 - Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
22
23 ### Dependency Selector Syntax `v1.0.0`
24
25 #### Overview:
26
27 - there is no "type" or "tag" selectors (ex. `div, h1, a`) as a dependency/target is the only type of `Node` that can be queried
28 - the term "dependencies" is in reference to any `Node` found in a `tree` returned by `Arborist`
29
30 #### Combinators
31
32 - `>` direct descendant/child
33 - ` ` any descendant/child
34 - `~` sibling
35
36 #### Selectors
37
38 - `*` universal selector
39 - `#<name>` dependency selector (equivalent to `[name="..."]`)
40 - `#<name>@<version>` (equivalent to `[name=<name>]:semver(<version>)`)
41 - `,` selector list delimiter
42 - `.` dependency type selector
43 - `:` pseudo selector
44
45 #### Dependency Type Selectors
46
47 - `.prod` dependency found in the `dependencies` section of `package.json`, or is a child of said dependency
48 - `.dev` dependency found in the `devDependencies` section of `package.json`, or is a child of said dependency
49 - `.optional` dependency found in the `optionalDependencies` section of `package.json`, or has `"optional": true` set in its entry in the `peerDependenciesMeta` section of `package.json`, or a child of said dependency
50 - `.peer` dependency found in the `peerDependencies` section of `package.json`
51 - `.workspace` dependency found in the [`workspaces`](https://docs.npmjs.com/cli/v8/using-npm/workspaces) section of `package.json`
52 - `.bundled` dependency found in the `bundleDependencies` section of `package.json`, or is a child of said dependency
53
54 #### Pseudo Selectors
55
56 - [`:not(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
57 - [`:has(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)
58 - [`:is(<selector list>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:is)
59 - [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) matches the root node/dependency
60 - [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) matches node/dependency it was queried against
61 - [`:empty`](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty) when a dependency has no dependencies
62 - [`:private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) when a dependency is private
63 - `:link` when a dependency is linked (for instance, workspaces or packages manually [`linked`](https://docs.npmjs.com/cli/v8/commands/npm-link)
64 - `:deduped` when a dependency has been deduped (note that this does _not_ always mean the dependency has been hoisted to the root of node_modules)
65 - `:overridden` when a dependency has been overridden
66 - `:extraneous` when a dependency exists but is not defined as a dependency of any node
67 - `:invalid` when a dependency version is out of its ancestors specified range
68 - `:missing` when a dependency is not found on disk
69 - `:semver(<spec>, [selector], [function])` match a valid [`node-semver`](https://github.com/npm/node-semver) version or range to a selector
70 - `:path(<path>)` [glob](https://www.npmjs.com/package/glob) matching based on dependencies path relative to the project
71 - `:type(<type>)` [based on currently recognized types](https://github.com/npm/npm-package-arg#result-object)
72 - `:outdated(<type>)` when a dependency is outdated
73
74 ##### `:semver(<spec>, [selector], [function])`
75
76 The `:semver()` pseudo selector allows comparing fields from each node's `package.json` using [semver](https://github.com/npm/node-semver#readme) methods. It accepts up to 3 parameters, all but the first of which are optional.
77
78 - `spec` a semver version or range
79 - `selector` an attribute selector for each node (default `[version]`)
80 - `function` a semver method to apply, one of: `satisfies`, `intersects`, `subset`, `gt`, `gte`, `gtr`, `lt`, `lte`, `ltr`, `eq`, `neq` or the special function `infer` (default `infer`)
81
82 When the special `infer` function is used the `spec` and the actual value from the node are compared. If both are versions, according to `semver.valid()`, `eq` is used. If both values are ranges, according to `!semver.valid()`, `intersects` is used. If the values are mixed types `satisfies` is used.
83
84 Some examples:
85
86 - `:semver(^1.0.0)` returns every node that has a `version` satisfied by the provided range `^1.0.0`
87 - `:semver(16.0.0, :attr(engines, [node]))` returns every node which has an `engines.node` property satisfying the version `16.0.0`
88 - `:semver(1.0.0, [version], lt)` every node with a `version` less than `1.0.0`
89
90 ##### `:outdated(<type>)`
91
92 The `:outdated` 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:
93
94 - `any` (default) a version exists that is greater than the current one
95 - `in-range` a version exists that is greater than the current one, and satisfies at least one if its dependents
96 - `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its dependents
97 - `major` a version exists that is a semver major greater than the current one
98 - `minor` a version exists that is a semver minor greater than the current one
99 - `patch` a version exists that is a semver patch greater than the current one
100
101 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 `queryContext` property of each node.
102
103 - `versions` an array of every available version of the given node
104 - `outdated.inRange` an array of objects, each with a `from` and `versions`, where `from` is the on-disk location of the node that depends on the current node and `versions` is an array of all available versions that satisfies that dependency. This is only populated if `:outdated(in-range)` is used.
105 - `outdated.outOfRange` an array of objects, identical in shape to `inRange`, but where the `versions` array is every available version that does not satisfy the dependency. This is only populated if `:outdated(out-of-range)` is used.
106
107 Some examples:
108
109 - `:root > :outdated(major)` returns every direct dependency that has a new semver major release
110 - `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its edges in
111
112 #### [Attribute Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
113
114 The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
115
116 - `[]` attribute selector (ie. existence of attribute)
117 - `[attribute=value]` attribute value is equivalant...
118 - `[attribute~=value]` attribute value contains word...
119 - `[attribute*=value]` attribute value contains string...
120 - `[attribute|=value]` attribute value is equal to or starts with...
121 - `[attribute^=value]` attribute value starts with...
122 - `[attribute$=value]` attribute value ends with...
123
124 #### `Array` & `Object` Attribute Selectors
125
126 The generic `:attr()` pseudo selector standardizes a pattern which can be used for attribute selection of `Object`s, `Array`s or `Arrays` of `Object`s accessible via `Arborist`'s `Node.package` metadata. This allows for iterative attribute selection beyond top-level `String` evaluation. The last argument passed to `:attr()` must be an `attribute` selector or a nested `:attr()`. See examples below:
127
128 #### `Objects`
129
130 ```css
131 /* return dependencies that have a `scripts.test` containing `"tap"` */
132 *: attr(scripts, [test~=tap]);
133 ```
134
135 #### Nested `Objects`
136
137 Nested objects are expressed as sequential arguments to `:attr()`.
138
139 ```css
140 /* return dependencies that have a testling config for opera browsers */
141 *: attr(testling, browsers, [~=opera]);
142 ```
143
144 #### `Arrays`
145
146 `Array`s specifically uses a special/reserved `.` character in place of a typical attribute name. `Arrays` also support exact `value` matching when a `String` is passed to the selector.
147
148 ##### Example of an `Array` Attribute Selection:
149
150 ```css
151 /* removes the distinction between properties & arrays */
152 /* ie. we'd have to check the property & iterate to match selection */
153 *:attr([keywords^=react])
154 *:attr(contributors, :attr([name~=Jordan]))
155 ```
156
157 ##### Example of an `Array` matching directly to a value:
158
159 ```css
160 /* return dependencies that have the exact keyword "react" */
161 /* this is equivalent to `*:keywords([value="react"])` */
162 *: attr([keywords=react]);
163 ```
164
165 ##### Example of an `Array` of `Object`s:
166
167 ```css
168 /* returns */
169 *: attr(contributors, [email=ruyadorno @github.com]);
170 ```
171
172 ### Groups
173
174 Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in `package.json`). 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 `prod` dependency may also be a `dev` dependency (in that it's also required by another `dev` dependency) & may also be `bundled` - a selector for that type of dependency would look like: `*.prod.dev.bundled`).
175
176 - `.prod`
177 - `.dev`
178 - `.optional`
179 - `.peer`
180 - `.bundled`
181 - `.workspace`
182
183 Please note that currently `workspace` deps are always `prod` dependencies. Additionally the `.root` dependency is also considered a `prod` dependency.
184
185 ### Programmatic Usage
186
187 - `Arborist`'s `Node` Class has a `.querySelectorAll()` method
188 - this method will return a filtered, flattened dependency Arborist `Node` list based on a valid query selector
189
190 ```js
191 const Arborist = require("@npmcli/arborist");
192 const arb = new Arborist({});
193 ```
194
195 ```js
196 // root-level
197 arb.loadActual().then(async (tree) => {
198 // query all production dependencies
199 const results = await tree.querySelectorAll(".prod");
200 console.log(results);
201 });
202 ```
203
204 ```js
205 // iterative
206 arb.loadActual().then(async (tree) => {
207 // query for the deduped version of react
208 const results = await tree.querySelectorAll("#react:not(:deduped)");
209 // query the deduped react for git deps
210 const deps = await results[0].querySelectorAll(":type(git)");
211 console.log(deps);
212 });
213 ```
214
215 ## See Also
216
217 - [npm query](/cli/v9/commands/npm-query)
218 - [@npmcli/arborist](https://npm.im/@npmcli/arborist)