Skip to content

Commit 79fe2b0

Browse files
jaydensericjaydenseric
committed
Documentation improvements.
- Display links to source in API docs. - Fix invalid JSX comments in examples. - Document Graphql cache instance property.
1 parent f908346 commit 79fe2b0

File tree

5 files changed

+148
-111
lines changed

5 files changed

+148
-111
lines changed

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
"build:js": "babel src -d lib",
8080
"build:mjs": "cross-env MODULE=true babel src -d lib --keep-file-extension",
8181
"postbuild": "prettier 'lib/**/*.{js,mjs}' --write",
82-
"jsdoc": "documentation readme src --re mjs --pe mjs -s API -q",
82+
"jsdoc": "documentation readme src --re mjs --pe mjs -s API -q -g",
8383
"postjsdoc": "prettier readme.md --write",
8484
"prewatch": "npm run build",
8585
"watch": "run-p watch:*",

‎readme.md

Lines changed: 135 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,7 @@ import { GraphQL, Provider } from 'graphql-react'
4747
const graphql = new GraphQL()
4848

4949
const Page = () => (
50-
<Provider value={graphql}>
51-
<!-- Use Consumer or Query components -->
52-
</Provider>
50+
<Provider value={graphql}>Use Consumer or Query components…</Provider>
5351
)
5452
```
5553

@@ -71,22 +69,25 @@ See the [example Next.js app and GraphQL API](example/readme.md).
7169
* [Provider](#provider)
7270
* [Consumer](#consumer)
7371
* [Query](#query)
74-
* [ConsumerRender](#consumerrender)
7572
* [QueryRender](#queryrender)
73+
* [ConsumerRender](#consumerrender)
74+
* [ActiveQuery](#activequery)
75+
* [HTTPError](#httperror)
76+
* [Operation](#operation)
77+
* [RequestOptions](#requestoptions)
78+
* [RequestOptionsOverride](#requestoptionsoverride)
7679
* [GraphQL](#graphql)
80+
* [cache](#cache)
7781
* [reset](#reset)
7882
* [query](#query-1)
79-
* [RequestCache](#requestcache)
80-
* [CacheUpdateCallback](#cacheupdatecallback)
8183
* [RequestCachePromise](#requestcachepromise)
82-
* [HTTPError](#httperror)
83-
* [ActiveQuery](#activequery)
84-
* [RequestOptionsOverride](#requestoptionsoverride)
85-
* [RequestOptions](#requestoptions)
86-
* [Operation](#operation)
84+
* [CacheUpdateCallback](#cacheupdatecallback)
85+
* [RequestCache](#requestcache)
8786

8887
### Provider
8988

89+
[src/components.mjs:23-23](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/components.mjs#L23-L23 'Source code on GitHub')
90+
9091
A React component that puts a [GraphQL](#graphql) instance in context for nested [Consumer](#consumer) components to use.
9192

9293
**Parameters**
@@ -102,16 +103,16 @@ import { GraphQL, Provider } from 'graphql-react'
102103
const graphql = new GraphQL()
103104

104105
const Page = () => (
105-
<Provider value={graphql}>
106-
<!-- Children… -->
107-
</Provider>
106+
<Provider value={graphql}>Use Consumer or Query components…</Provider>
108107
)
109108
```
110109

111110
Returns **ReactElement** React virtual DOM element.
112111

113112
### Consumer
114113

114+
[src/components.mjs:39-39](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/components.mjs#L39-L39 'Source code on GitHub')
115+
115116
A React component that gets the [GraphQL](#graphql) instance from context.
116117

117118
**Parameters**
@@ -136,6 +137,8 @@ Returns **ReactElement** React virtual DOM element.
136137

137138
### Query
138139

140+
[src/components.mjs:241-245](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/components.mjs#L241-L245 'Source code on GitHub')
141+
139142
A React component to manage a GraphQL query or mutation.
140143

141144
**Parameters**
@@ -212,28 +215,10 @@ const ClapArticleButton = ({ articleId }) => (
212215

213216
Returns **ReactElement** React virtual DOM element.
214217

215-
### ConsumerRender
216-
217-
Renders a [GraphQL](#graphql) consumer.
218-
219-
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
220-
221-
**Parameters**
222-
223-
* `graphql` **[GraphQL](#graphql)** [GraphQL](#graphql) instance.
224-
225-
**Examples**
226-
227-
_A button that resets the [GraphQL](#graphql) cache._
228-
229-
```javascript
230-
graphql => <button onClick={graphql.reset}>Reset cache</button>
231-
```
232-
233-
Returns **ReactElement** React virtual DOM element.
234-
235218
### QueryRender
236219

220+
[src/components.mjs:247-254](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/components.mjs#L247-L254 'Source code on GitHub')
221+
237222
Renders the status of a query or mutation.
238223

239224
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
@@ -262,101 +247,85 @@ Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Sta
262247

263248
Returns **ReactElement** React virtual DOM element.
264249

265-
### GraphQL
266-
267-
A lightweight GraphQL client that caches requests.
268-
269-
**Parameters**
270-
271-
* `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options. (optional, default `{}`)
272-
* `options.cache` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Cache to import; useful once a SSR API is available. (optional, default `{}`)
273-
* `options.requestOptions` **[RequestOptionsOverride](#requestoptionsoverride)?** A function that accepts and modifies generated options for every request.
250+
### ConsumerRender
274251

275-
**Examples**
252+
[src/components.mjs:247-254](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/components.mjs#L247-L254 'Source code on GitHub')
276253

277-
```javascript
278-
import { GraphQL } from 'graphql-react'
254+
Renders a [GraphQL](#graphql) consumer.
279255

280-
const graphql = new GraphQL({
281-
requestOptions: options => {
282-
options.url = 'https://api.example.com/graphql'
283-
options.credentials = 'include'
284-
}
285-
})
286-
```
256+
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
287257

288-
#### reset
258+
**Parameters**
289259

290-
Resets the cache. Useful when a user logs out.
260+
* `graphql` **[GraphQL](#graphql)** [GraphQL](#graphql) instance.
291261

292262
**Examples**
293263

264+
_A button that resets the [GraphQL](#graphql) cache._
265+
294266
```javascript
295-
graphql.reset()
267+
graphql => <button onClick={graphql.reset}>Reset cache</button>
296268
```
297269

298-
#### query
299-
300-
Queries a GraphQL server.
301-
302-
**Parameters**
303-
304-
* `operation` **[Operation](#operation)** GraphQL operation object.
305-
306-
Returns **[ActiveQuery](#activequery)** In-flight query details.
270+
Returns **ReactElement** React virtual DOM element.
307271

308-
### RequestCache
272+
### ActiveQuery
309273

310-
JSON serializable result of a request (including all errors and data) for caching purposes.
274+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
311275

312276
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
313277

314278
**Properties**
315279

316-
* `httpError` **[HTTPError](#httperror)?** Fetch HTTP error.
317-
* `parseError` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Parse error message.
318-
* `graphQLErrors` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** GraphQL response errors.
319-
* `data` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** GraphQL response data.
320-
321-
### CacheUpdateCallback
280+
* `pastRequestCache` **[RequestCache](#requestcache)?** Results from the last identical request.
281+
* `requestHash` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Request options hash.
282+
* `request` **[RequestCachePromise](#requestcachepromise)** Promise that resolves fresh request cache.
322283

323-
A cache update listener callback.
284+
### HTTPError
324285

325-
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
286+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
326287

327-
**Parameters**
288+
Fetch HTTP error.
328289

329-
* `requestCache` **[RequestCache](#requestcache)** Request cache.
290+
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
330291

331-
### RequestCachePromise
292+
**Properties**
332293

333-
A promise for an in-flight query that resolves the request cache.
294+
* `status` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** HTTP status code.
295+
* `statusText` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** HTTP status text.
334296

335-
Type: [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[RequestCache](#requestcache)>
297+
### Operation
336298

337-
### HTTPError
299+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
338300

339-
Fetch HTTP error.
301+
A GraphQL operation object. Additional properties may be used; all are sent to the GraphQL server.
340302

341303
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
342304

343305
**Properties**
344306

345-
* `status` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** HTTP status code.
346-
* `statusText` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** HTTP status text.
307+
* `query` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GraphQL queries or mutations.
308+
* `variables` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Variables used by the query.
347309

348-
### ActiveQuery
310+
### RequestOptions
311+
312+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
313+
314+
Options for a GraphQL fetch request. See [polyfillable fetch options](https://github.github.io/fetch/#options).
349315

350316
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
351317

352318
**Properties**
353319

354-
* `pastRequestCache` **[RequestCache](#requestcache)?** Results from the last identical request.
355-
* `requestHash` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Request options hash.
356-
* `request` **[RequestCachePromise](#requestcachepromise)** Promise that resolves fresh request cache.
320+
* `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A GraphQL API URL.
321+
* `body` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [FormData](https://developer.mozilla.org/docs/Web/API/FormData))** HTTP request body.
322+
* `headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** HTTP request headers.
323+
* `credentials` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Authentication credentials mode.
357324

358325
### RequestOptionsOverride
359326

327+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
328+
360329
A way to override request options generated for a fetch. Modify the provided options object directly; no return.
361330

362331
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
@@ -374,26 +343,92 @@ options => {
374343
}
375344
```
376345

377-
### RequestOptions
346+
### GraphQL
378347

379-
Options for a GraphQL fetch request. See [polyfillable fetch options](https://github.github.io/fetch/#options).
348+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
380349

381-
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
350+
A lightweight GraphQL client that caches requests.
382351

383-
**Properties**
352+
**Parameters**
384353

385-
* `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A GraphQL API URL.
386-
* `body` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [FormData](https://developer.mozilla.org/docs/Web/API/FormData))** HTTP request body.
387-
* `headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** HTTP request headers.
388-
* `credentials` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Authentication credentials mode.
354+
* `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options. (optional, default `{}`)
355+
* `options.cache` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Cache to import; useful once a SSR API is available. (optional, default `{}`)
356+
* `options.requestOptions` **[RequestOptionsOverride](#requestoptionsoverride)?** A function that accepts and modifies generated options for every request.
389357

390-
### Operation
358+
**Examples**
391359

392-
A GraphQL operation object. Additional properties may be used; all are sent to the GraphQL server.
360+
```javascript
361+
import { GraphQL } from 'graphql-react'
362+
363+
const graphql = new GraphQL({
364+
requestOptions: options => {
365+
options.url = 'https://api.example.com/graphql'
366+
options.credentials = 'include'
367+
}
368+
})
369+
```
370+
371+
#### cache
372+
373+
[src/graphql.mjs:25-25](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L25-L25 'Source code on GitHub')
374+
375+
GraphQL request cache.
376+
377+
#### reset
378+
379+
[src/graphql.mjs:75-79](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L75-L79 'Source code on GitHub')
380+
381+
Resets the cache. Useful when a user logs out.
382+
383+
**Examples**
384+
385+
```javascript
386+
graphql.reset()
387+
```
388+
389+
#### query
390+
391+
[src/graphql.mjs:194-206](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L194-L206 'Source code on GitHub')
392+
393+
Queries a GraphQL server.
394+
395+
**Parameters**
396+
397+
* `operation` **[Operation](#operation)** GraphQL operation object.
398+
399+
Returns **[ActiveQuery](#activequery)** In-flight query details.
400+
401+
### RequestCachePromise
402+
403+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
404+
405+
A promise for an in-flight query that resolves the request cache.
406+
407+
Type: [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[RequestCache](#requestcache)>
408+
409+
### CacheUpdateCallback
410+
411+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
412+
413+
A cache update listener callback.
414+
415+
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
416+
417+
**Parameters**
418+
419+
* `requestCache` **[RequestCache](#requestcache)** Request cache.
420+
421+
### RequestCache
422+
423+
[src/graphql.mjs:19-207](https://github.com/jaydenseric/graphql-react/blob/f908346ed98ffff6e01b29c42236745bed87a7a8/src/graphql.mjs#L19-L207 'Source code on GitHub')
424+
425+
JSON serializable result of a request (including all errors and data) for caching purposes.
393426

394427
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
395428

396429
**Properties**
397430

398-
* `query` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GraphQL queries or mutations.
399-
* `variables` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Variables used by the query.
431+
* `httpError` **[HTTPError](#httperror)?** Fetch HTTP error.
432+
* `parseError` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Parse error message.
433+
* `graphQLErrors` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** GraphQL response errors.
434+
* `data` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** GraphQL response data.

‎src/components.mjs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,7 @@ export const {
1717
* const graphql = new GraphQL()
1818
*
1919
* const Page = () => (
20-
* <Provider value={graphql}>
21-
* <!-- Children… -->
22-
* </Provider>
20+
* <Provider value={graphql}>Use Consumer or Query components…</Provider>
2321
* )
2422
*/
2523
Provider,

‎src/graphql.mjs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ import extractFiles from 'extract-files'
1818
*/
1919
export class GraphQL {
2020
constructor({ cache = {}, requestOptions } = {}) {
21+
/**
22+
* GraphQL request cache.
23+
* @type {Object.<String, RequestCache>}
24+
*/
2125
this.cache = cache
2226
this.requestOptions = requestOptions
2327
}

0 commit comments

Comments
 (0)