graphql-tag 2.10.2-beta.0 → 2.11.0
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/CHANGELOG.md +16 -1
- package/README.md +130 -68
- package/index.d.ts +2 -2
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,21 @@
|
|
|
1
1
|
# Change log
|
|
2
2
|
|
|
3
|
-
###
|
|
3
|
+
### v2.11.0 (2020-07-28)
|
|
4
|
+
|
|
5
|
+
* `package.json` `sideEffects` changes to clearly identify that `graphql-tag` doesn't have side effects. <br/>
|
|
6
|
+
[@hwillson](http://github.com/hwillson) in [#313](https://github.com/apollographql/graphql-tag/pull/313)
|
|
7
|
+
|
|
8
|
+
### v2.10.4 (2020-07-08)
|
|
9
|
+
|
|
10
|
+
* Bump dev/peer deps to accommodate `graphql` 15. <br/>
|
|
11
|
+
[@adriencohen](https://github.com/adriencohen) in [#299](https://github.com/apollographql/graphql-tag/pull/299)
|
|
12
|
+
|
|
13
|
+
### v2.10.3 (2020-02-05)
|
|
14
|
+
|
|
15
|
+
* Further adjustments to the TS `index.d.ts` declaration file. <br/>
|
|
16
|
+
[@Guillaumez](https://github.com/Guillaumez) in [#289](https://github.com/apollographql/graphql-tag/pull/289)
|
|
17
|
+
|
|
18
|
+
### v2.10.2 (2020-02-04)
|
|
4
19
|
|
|
5
20
|
* Update/fix the existing TS `index.d.ts` declaration file. <br/>
|
|
6
21
|
[@hwillson](https://github.com/hwillson) in [#285](https://github.com/apollographql/graphql-tag/pull/285)
|
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ Helpful utilities for parsing GraphQL queries. Includes:
|
|
|
12
12
|
|
|
13
13
|
### gql
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
The `gql` template literal tag can be used to concisely write a GraphQL query that is parsed into a standard GraphQL AST. It is the recommended method for passing queries to [Apollo Client](https://github.com/apollographql/apollo-client). While it is primarily built for Apollo Client, it generates a generic GraphQL AST which can be used by any GraphQL client.
|
|
16
16
|
|
|
17
17
|
```js
|
|
18
18
|
import gql from 'graphql-tag';
|
|
@@ -25,34 +25,68 @@ const query = gql`
|
|
|
25
25
|
}
|
|
26
26
|
}
|
|
27
27
|
`
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The above query now contains the following syntax tree.
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
{
|
|
34
|
+
"kind": "Document",
|
|
35
|
+
"definitions": [
|
|
36
|
+
{
|
|
37
|
+
"kind": "OperationDefinition",
|
|
38
|
+
"operation": "query",
|
|
39
|
+
"name": null,
|
|
40
|
+
"variableDefinitions": null,
|
|
41
|
+
"directives": [],
|
|
42
|
+
"selectionSet": {
|
|
43
|
+
"kind": "SelectionSet",
|
|
44
|
+
"selections": [
|
|
45
|
+
{
|
|
46
|
+
"kind": "Field",
|
|
47
|
+
"alias": null,
|
|
48
|
+
"name": {
|
|
49
|
+
"kind": "Name",
|
|
50
|
+
"value": "user",
|
|
51
|
+
...
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
]
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
]
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
#### Fragments
|
|
62
|
+
|
|
63
|
+
The `gql` tag can also be used to define reusable fragments, which can easily be added to queries or other fragments.
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
import gql from 'graphql-tag';
|
|
28
67
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
// {
|
|
36
|
-
// "kind": "OperationDefinition",
|
|
37
|
-
// "operation": "query",
|
|
38
|
-
// "name": null,
|
|
39
|
-
// "variableDefinitions": null,
|
|
40
|
-
// "directives": [],
|
|
41
|
-
// "selectionSet": {
|
|
42
|
-
// "kind": "SelectionSet",
|
|
43
|
-
// "selections": [
|
|
44
|
-
// {
|
|
45
|
-
// "kind": "Field",
|
|
46
|
-
// "alias": null,
|
|
47
|
-
// "name": {
|
|
48
|
-
// "kind": "Name",
|
|
49
|
-
// "value": "user",
|
|
50
|
-
// ...
|
|
68
|
+
const userFragment = gql`
|
|
69
|
+
fragment User_user on User {
|
|
70
|
+
firstName
|
|
71
|
+
lastName
|
|
72
|
+
}
|
|
73
|
+
`
|
|
51
74
|
```
|
|
52
75
|
|
|
53
|
-
|
|
76
|
+
The above `userFragment` document can be embedded in another document using a template literal placeholder.
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
const query = gql`
|
|
80
|
+
{
|
|
81
|
+
user(id: 5) {
|
|
82
|
+
...User_user
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
${userFragment}
|
|
86
|
+
`
|
|
87
|
+
```
|
|
54
88
|
|
|
55
|
-
|
|
89
|
+
**Note:** _While it may seem redundant to have to both embed the `userFragment` variable in the template literal **AND** spread the `...User_user` fragment in the graphQL selection set, this requirement makes static analysis by tools such as `eslint-plugin-graphql` possible._
|
|
56
90
|
|
|
57
91
|
#### Why use this?
|
|
58
92
|
|
|
@@ -64,78 +98,100 @@ That's where this package comes in - it lets you write your queries with [ES2015
|
|
|
64
98
|
|
|
65
99
|
This package only has one feature - it caches previous parse results in a simple dictionary. This means that if you call the tag on the same query multiple times, it doesn't waste time parsing it again. It also means you can use `===` to compare queries to check if they are identical.
|
|
66
100
|
|
|
67
|
-
### Babel preprocessing
|
|
68
101
|
|
|
69
|
-
|
|
102
|
+
### Importing graphQL files
|
|
70
103
|
|
|
71
|
-
|
|
72
|
-
Try this custom transformer to pre-compile your GraphQL queries in TypeScript: [ts-transform-graphql-tag](https://github.com/firede/ts-transform-graphql-tag).
|
|
104
|
+
_To add support for importing `.graphql`/`.gql` files, see [Webpack loading and preprocessing](#webpack-loading-and-preprocessing) below._
|
|
73
105
|
|
|
74
|
-
|
|
106
|
+
Given a file `MyQuery.graphql`
|
|
75
107
|
|
|
76
|
-
|
|
108
|
+
```graphql
|
|
109
|
+
query MyQuery {
|
|
110
|
+
...
|
|
111
|
+
}
|
|
112
|
+
```
|
|
77
113
|
|
|
78
|
-
|
|
79
|
-
```javascript
|
|
80
|
-
import myImportedQuery from './productsQuery.graphql'
|
|
114
|
+
If you have configured [the webpack graphql-tag/loader](#webpack-loading-and-preprocessing), you can import modules containing graphQL queries. The imported value will be the pre-built AST.
|
|
81
115
|
|
|
82
|
-
|
|
116
|
+
```graphql
|
|
117
|
+
import MyQuery from 'query.graphql'
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
#### Importing queries by name
|
|
121
|
+
|
|
122
|
+
You can also import query and fragment documents by name.
|
|
123
|
+
|
|
124
|
+
```graphql
|
|
125
|
+
query MyQuery1 {
|
|
126
|
+
...
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
query MyQuery2 {
|
|
83
130
|
...
|
|
84
131
|
}
|
|
85
132
|
```
|
|
86
133
|
|
|
87
|
-
|
|
134
|
+
And in your JavaScript:
|
|
88
135
|
|
|
89
|
-
|
|
136
|
+
```javascript
|
|
137
|
+
import { MyQuery1, MyQuery2 } from 'query.graphql'
|
|
138
|
+
```
|
|
90
139
|
|
|
91
|
-
|
|
140
|
+
### Preprocessing queries and fragments
|
|
92
141
|
|
|
93
|
-
|
|
142
|
+
Preprocessing GraphQL queries and fragments into ASTs at build time can greatly improve load times.
|
|
94
143
|
|
|
95
|
-
|
|
144
|
+
#### Babel preprocessing
|
|
96
145
|
|
|
97
|
-
|
|
98
|
-
loaders: [
|
|
99
|
-
{
|
|
100
|
-
test: /\.(graphql|gql)$/,
|
|
101
|
-
exclude: /node_modules/,
|
|
102
|
-
loader: 'graphql-tag/loader'
|
|
103
|
-
}
|
|
104
|
-
]
|
|
105
|
-
```
|
|
146
|
+
GraphQL queries can be compiled at build time using [babel-plugin-graphql-tag](https://github.com/gajus/babel-plugin-graphql-tag). Pre-compiling queries decreases script initialization time and reduces bundle sizes by potentially removing the need for `graphql-tag` at runtime.
|
|
106
147
|
|
|
107
|
-
|
|
148
|
+
#### TypeScript preprocessing
|
|
108
149
|
|
|
109
|
-
|
|
110
|
-
import query from './query.graphql';
|
|
150
|
+
Try this custom transformer to pre-compile your GraphQL queries in TypeScript: [ts-transform-graphql-tag](https://github.com/firede/ts-transform-graphql-tag).
|
|
111
151
|
|
|
112
|
-
|
|
113
|
-
// {
|
|
114
|
-
// "kind": "Document",
|
|
115
|
-
// ...
|
|
116
|
-
```
|
|
152
|
+
#### React Native and Next.js preprocessing
|
|
117
153
|
|
|
118
|
-
|
|
154
|
+
Preprocessing queries via the webpack loader is not always possible. [babel-plugin-import-graphql](https://www.npmjs.com/package/babel-plugin-import-graphql) supports importing graphql files directly into your JavaScript by preprocessing GraphQL queries into ASTs at compile-time.
|
|
119
155
|
|
|
120
|
-
|
|
156
|
+
E.g.:
|
|
121
157
|
|
|
122
|
-
|
|
158
|
+
```javascript
|
|
159
|
+
import myImportedQuery from './productsQuery.graphql'
|
|
123
160
|
|
|
124
|
-
|
|
125
|
-
```graphql
|
|
126
|
-
query MyQuery1 {
|
|
161
|
+
class ProductsPage extends React.Component {
|
|
127
162
|
...
|
|
128
163
|
}
|
|
164
|
+
```
|
|
129
165
|
|
|
130
|
-
|
|
166
|
+
#### Webpack loading and preprocessing
|
|
167
|
+
|
|
168
|
+
Using the included `graphql-tag/loader` it is possible to maintain query logic that is separate from the rest of your application logic. With the loader configured, imported graphQL files will be converted to AST during the webpack build process.
|
|
169
|
+
|
|
170
|
+
_**Example webpack configuration**_
|
|
171
|
+
|
|
172
|
+
```js
|
|
173
|
+
{
|
|
174
|
+
...
|
|
175
|
+
loaders: [
|
|
176
|
+
{
|
|
177
|
+
test: /\.(graphql|gql)$/,
|
|
178
|
+
exclude: /node_modules/,
|
|
179
|
+
loader: 'graphql-tag/loader'
|
|
180
|
+
}
|
|
181
|
+
],
|
|
131
182
|
...
|
|
132
183
|
}
|
|
133
184
|
```
|
|
134
185
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
186
|
+
#### Create React App
|
|
187
|
+
|
|
188
|
+
Preprocessing GraphQL imports is supported in **create-react-app** >= v2 using [evenchange4/graphql.macro](https://github.com/evenchange4/graphql.macro).
|
|
189
|
+
|
|
190
|
+
For **create-react-app** < v2, you'll either need to eject or use [react-app-rewire-inline-import-graphql-ast](https://www.npmjs.com/package/react-app-rewire-inline-import-graphql-ast).
|
|
191
|
+
|
|
192
|
+
#### Testing
|
|
193
|
+
|
|
194
|
+
Testing environments that don't support Webpack require additional configuration. For [Jest](https://facebook.github.io/jest/) use [jest-transform-graphql](https://github.com/remind101/jest-transform-graphql).
|
|
139
195
|
|
|
140
196
|
### Warnings
|
|
141
197
|
|
|
@@ -152,13 +208,19 @@ disableFragmentWarnings()
|
|
|
152
208
|
This package exports an `experimentalFragmentVariables` flag that allows you to use experimental support for [parameterized fragments](https://github.com/facebook/graphql/issues/204).
|
|
153
209
|
|
|
154
210
|
You can enable / disable this with:
|
|
211
|
+
|
|
155
212
|
```js
|
|
156
213
|
import { enableExperimentalFragmentVariables, disableExperimentalFragmentVariables } from 'graphql-tag';
|
|
157
214
|
```
|
|
158
215
|
|
|
159
216
|
Enabling this feature allows you declare documents of the form
|
|
217
|
+
|
|
160
218
|
```graphql
|
|
161
219
|
fragment SomeFragment ($arg: String!) on SomeType {
|
|
162
220
|
someField
|
|
163
221
|
}
|
|
164
222
|
```
|
|
223
|
+
|
|
224
|
+
### Resources
|
|
225
|
+
|
|
226
|
+
You can easily generate and explore a GraphQL AST on [astexplorer.net](https://astexplorer.net/#/drYr8X1rnP/1).
|
package/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
declare module "graphql-tag" {
|
|
2
2
|
function gql(
|
|
3
|
-
literals: ReadonlyArray<string>,
|
|
3
|
+
literals: ReadonlyArray<string> | Readonly<string>,
|
|
4
4
|
...placeholders: any[]
|
|
5
|
-
): import("graphql").DocumentNode
|
|
5
|
+
): import("graphql").DocumentNode;
|
|
6
6
|
|
|
7
7
|
namespace gql {
|
|
8
8
|
function resetCaches(): void;
|
package/package.json
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "graphql-tag",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.11.0",
|
|
4
4
|
"description": "A JavaScript template literal tag that parses GraphQL queries",
|
|
5
5
|
"main": "./lib/graphql-tag.umd.js",
|
|
6
6
|
"module": "./src/index.js",
|
|
7
7
|
"jsnext:main": "./src/index.js",
|
|
8
|
+
"sideEffects": false,
|
|
8
9
|
"scripts": {
|
|
9
10
|
"bundle": "rollup -c && cp src/index.js.flow lib/graphql-tag.umd.js.flow",
|
|
10
11
|
"test": "mocha test/graphql.js",
|
|
@@ -25,12 +26,12 @@
|
|
|
25
26
|
"babel-preset-es2015": "^6.9.0",
|
|
26
27
|
"babel-register": "^6.9.0",
|
|
27
28
|
"chai": "^4.0.2",
|
|
28
|
-
"graphql": "^
|
|
29
|
+
"graphql": "^15.0.0",
|
|
29
30
|
"mocha": "^3.4.1",
|
|
30
31
|
"rollup": "^0.45.0",
|
|
31
32
|
"test-all-versions": "^3.3.2"
|
|
32
33
|
},
|
|
33
34
|
"peerDependencies": {
|
|
34
|
-
"graphql": "^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0"
|
|
35
|
+
"graphql": "^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0"
|
|
35
36
|
}
|
|
36
37
|
}
|