@vltpkg/query 0.0.0-3 → 0.0.0-4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +99 -43
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -4,10 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
The **vlt** query syntax engine.
|
|
6
6
|
|
|
7
|
-
**[Usage](#usage)**
|
|
8
|
-
·
|
|
9
|
-
**[Examples](#examples)**
|
|
10
|
-
·
|
|
7
|
+
**[Usage](#usage)** · **[Examples](#examples)** ·
|
|
11
8
|
**[Supported Syntax Reference](#supported-syntax-reference)**
|
|
12
9
|
|
|
13
10
|
## Usage
|
|
@@ -34,73 +31,132 @@ query.search(':root > *')
|
|
|
34
31
|
|
|
35
32
|
## Supported Syntax Reference
|
|
36
33
|
|
|
37
|
-
The vlt query syntax enable usage of css-selector-like strings to
|
|
38
|
-
packages.
|
|
34
|
+
The vlt query syntax enable usage of css-selector-like strings to
|
|
35
|
+
filter packages.
|
|
39
36
|
|
|
40
|
-
Many of the common elements of the CSS language are available,
|
|
37
|
+
Many of the common elements of the CSS language are available,
|
|
38
|
+
notably:
|
|
41
39
|
|
|
42
40
|
- `*` Universal selector, matches all selected items.
|
|
43
41
|
- `&` Nesting selector, allows for nesting selectors.
|
|
44
42
|
- `{}` Curly braces, when querying can be used to nest selectors.
|
|
45
43
|
|
|
46
|
-
Split by group of selectors below is the complete reference to
|
|
47
|
-
elements.
|
|
44
|
+
Split by group of selectors below is the complete reference to
|
|
45
|
+
supported elements.
|
|
48
46
|
|
|
49
47
|
### Attribute selectors
|
|
50
48
|
|
|
51
|
-
Attribute selectors are used to match a value found in the
|
|
52
|
-
metadata for each of the nodes being queried to a
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- `[attr
|
|
56
|
-
|
|
57
|
-
- `[attr
|
|
58
|
-
|
|
59
|
-
- `[attr
|
|
49
|
+
Attribute selectors are used to match a value found in the
|
|
50
|
+
`package.json` metadata for each of the nodes being queried to a
|
|
51
|
+
arbitrary value you choose.
|
|
52
|
+
|
|
53
|
+
- `[attr]` Matches elements with an `attr` property in its
|
|
54
|
+
`package.json`.
|
|
55
|
+
- `[attr=value]` Matches elements with a property `attr` whose value
|
|
56
|
+
is exactly `value`.
|
|
57
|
+
- `[attr^=value]` Matches elements with a property `attr` whose value
|
|
58
|
+
starts with `value`.
|
|
59
|
+
- `[attr$=value]` Matches elements with a property `attr` whose value
|
|
60
|
+
ends with `value`.
|
|
61
|
+
- `[attr~=value]` Matches elements with a property `attr` whose value
|
|
62
|
+
is a whitespace-separated list of words, one of which is exactly
|
|
63
|
+
`value`.
|
|
64
|
+
- `[attr|=value]` Matches elements with a property `attr` whose value
|
|
65
|
+
is either `value` or starts with `value-`.
|
|
60
66
|
- `[attr*=value]` Matches elements with a property `attr`.
|
|
61
|
-
- `[attr=value i]` Case-insensitive flag, setting it will cause any
|
|
62
|
-
|
|
67
|
+
- `[attr=value i]` Case-insensitive flag, setting it will cause any
|
|
68
|
+
comparison to be case-insensitive.
|
|
69
|
+
- `[attr=value s]` Case-sensitive flag, setting it will cause
|
|
70
|
+
comparisons to be case-sensitive, this is the default behavior.
|
|
63
71
|
|
|
64
72
|
### Class selectors
|
|
65
73
|
|
|
66
74
|
- `.prod` Matches prod dependencies to your current project.
|
|
67
|
-
- `.dev` Matches packages that are only used as dev dependencies in
|
|
68
|
-
|
|
75
|
+
- `.dev` Matches packages that are only used as dev dependencies in
|
|
76
|
+
your current project.
|
|
77
|
+
- `.optional` Matches packages that are optional to your current
|
|
78
|
+
project.
|
|
69
79
|
- `.peer` Matches peer dependencies to your current project.
|
|
70
|
-
- `.workspace` Matches the current project worksacpes (listed in your
|
|
80
|
+
- `.workspace` Matches the current project worksacpes (listed in your
|
|
81
|
+
`vlt-workspaces.json` file).
|
|
71
82
|
|
|
72
83
|
### Combinators
|
|
73
84
|
|
|
74
|
-
- `>` Child combinator, matches packages that are direct dependencies
|
|
75
|
-
|
|
76
|
-
-
|
|
85
|
+
- `>` Child combinator, matches packages that are direct dependencies
|
|
86
|
+
of the previously selected nodes.
|
|
87
|
+
- ` ` Descendant combinator, matches all packages that are direct &
|
|
88
|
+
transitive dependencies of the previously selected nodes.
|
|
89
|
+
- `~` Sibling combinator, matches packages that are direct
|
|
90
|
+
dependencies of all dependents of the previously selected nodes.
|
|
77
91
|
|
|
78
92
|
### ID Selectors
|
|
79
93
|
|
|
80
|
-
Identifiers are a shortcut to retrieving packages by name,
|
|
94
|
+
Identifiers are a shortcut to retrieving packages by name,
|
|
95
|
+
unfortunately this shortcut only works for unscoped packages, with
|
|
96
|
+
that in mind it's advised to rely on using **Attribute selectors**
|
|
97
|
+
(showed above) instead.
|
|
81
98
|
|
|
82
99
|
e.g: `#foo` is the same as `[name=foo]`
|
|
83
100
|
|
|
84
101
|
### Pseudo class selectors
|
|
85
102
|
|
|
86
|
-
- `:attr(key, [attr=value])` The attribute pseudo-class allows for
|
|
103
|
+
- `:attr(key, [attr=value])` The attribute pseudo-class allows for
|
|
104
|
+
selecting packages based on nested properties of its `package.json`
|
|
105
|
+
metadata. As an example, here is a query that filters only packages
|
|
106
|
+
that declares an optional peer dependency named `foo`:
|
|
107
|
+
`:attr(peerDependenciesMeta, foo, [optional=true])`
|
|
87
108
|
- `:empty` Matches packages that have no dependencies installed.
|
|
88
|
-
- `:has(<selector-list>)` Matches only packages that have valid
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
109
|
+
- `:has(<selector-list>)` Matches only packages that have valid
|
|
110
|
+
results for the selector expression used. As an example, here is a
|
|
111
|
+
query that matches all packages that have a peer dependency on
|
|
112
|
+
`react`: `:has(.peer[name=react])`
|
|
113
|
+
- `:is(<forgiving-selector-list>)` Useful for writing large selectors
|
|
114
|
+
in a more compact form, the `:is()` pseudo-class takes a selector
|
|
115
|
+
list as its arguments and selects any element that can be selected
|
|
116
|
+
by one of the selectors in that list. As an example, let's say I
|
|
117
|
+
want to select packages named `a` & `b` that are direct dependencies
|
|
118
|
+
of my project root: `:root > [name=a], :root > [name=b]` using the
|
|
119
|
+
`:is()` pseudo-class, that same expression can be shortened to:
|
|
120
|
+
`:root > :is([name=a], [name=b])`. Similar to the css pseudo-class
|
|
121
|
+
of the same name, this selector has a forgiving behavior regarding
|
|
122
|
+
its nested selector list ignoring any usage of non-existing ids,
|
|
123
|
+
classes, combinators, operators and pseudo-selectors.
|
|
124
|
+
- `:not(<selector-list>)` Negation pseudo-class, select packages that
|
|
125
|
+
do not match a list of selectors.
|
|
126
|
+
- `:outdated(<type>)` Matches packages that are outdated, the type
|
|
127
|
+
parameter is optional and can be one of the following:
|
|
128
|
+
- `any` (default) a version exists that is greater than the current
|
|
129
|
+
one
|
|
130
|
+
- `in-range` a version exists that is greater than the current one,
|
|
131
|
+
and satisfies at least one if its parent's dependencies
|
|
132
|
+
- `out-of-range` a version exists that is greater than the current
|
|
133
|
+
one, does not satisfy at least one of its parent's dependencies
|
|
134
|
+
- `major` a version exists that is a semver major greater than the
|
|
135
|
+
current one
|
|
136
|
+
- `minor` a version exists that is a semver minor greater than the
|
|
137
|
+
current one
|
|
138
|
+
- `patch` a version exists that is a semver patch greater than the
|
|
139
|
+
current one
|
|
140
|
+
- `:private` Matches packages that have the property `private` set on
|
|
141
|
+
their `package.json` file.
|
|
142
|
+
- `:semver(<value>, <function>, <custom-attribute-selector>)` Matches
|
|
143
|
+
packages based on a semver value, e.g, to retrieve all packages that
|
|
144
|
+
have a `version` satisfied by the semver value `^1.0.0`:
|
|
145
|
+
`:semver(^1.0.0)`. It's also possible to define the type of semver
|
|
146
|
+
comparison function to use by defining a second parameter, e.g:
|
|
147
|
+
`:semver(^1.0.0, eq)` for an exact match, valid comparison types
|
|
148
|
+
are: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `satisfies` (default). A
|
|
149
|
+
third parameter allows for specifying a different `package.json`
|
|
150
|
+
property to use for the comparison, e.g:
|
|
151
|
+
`:semver(^22, satisfies, :attr(engines, [node]))` for comparing the
|
|
152
|
+
value of `engines.node`.
|
|
153
|
+
- `:type(registry|file|git|remote|workspace)` Matches packages based
|
|
154
|
+
on their type, e.g, to retrieve all git dependencies: `:type(git)`.
|
|
101
155
|
|
|
102
156
|
### Pseudo Elements
|
|
103
157
|
|
|
104
|
-
- `:project` Returns both the root node (as defined below) along with
|
|
105
|
-
|
|
158
|
+
- `:project` Returns both the root node (as defined below) along with
|
|
159
|
+
any workspace declared in your project.
|
|
160
|
+
- `:root` Returns the root node, that represents the package defined
|
|
161
|
+
at the top-level `package.json` of your project folder.
|
|
106
162
|
- `:scope` Returns the current scope of a given selector
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vltpkg/query",
|
|
3
3
|
"description": "Query syntax parser that retrieves items from a graph",
|
|
4
|
-
"version": "0.0.0-
|
|
4
|
+
"version": "0.0.0-4",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "git+https://github.com/vltpkg/vltpkg.git",
|
|
@@ -20,11 +20,11 @@
|
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
22
|
"postcss-selector-parser": "^6.1.2",
|
|
23
|
-
"@vltpkg/
|
|
24
|
-
"@vltpkg/graph": "0.0.0-
|
|
25
|
-
"@vltpkg/
|
|
26
|
-
"@vltpkg/
|
|
27
|
-
"@vltpkg/
|
|
23
|
+
"@vltpkg/error-cause": "0.0.0-4",
|
|
24
|
+
"@vltpkg/graph": "0.0.0-4",
|
|
25
|
+
"@vltpkg/semver": "0.0.0-4",
|
|
26
|
+
"@vltpkg/types": "0.0.0-4",
|
|
27
|
+
"@vltpkg/dep-id": "0.0.0-4"
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
30
|
"@eslint/js": "^9.20.0",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"typedoc": "0.27.6",
|
|
38
38
|
"typescript": "5.7.3",
|
|
39
39
|
"typescript-eslint": "^8.23.0",
|
|
40
|
-
"@vltpkg/spec": "0.0.0-
|
|
40
|
+
"@vltpkg/spec": "0.0.0-4"
|
|
41
41
|
},
|
|
42
42
|
"license": "BSD-2-Clause-Patent",
|
|
43
43
|
"engines": {
|