Skip to content

Commit b1ec226

Browse files
author
Alex Cory
committed
alphabetizing options in docs
1 parent 862c9b0 commit b1ec226

File tree

2 files changed

+130
-162
lines changed

2 files changed

+130
-162
lines changed

‎README.md

Lines changed: 64 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -775,56 +775,77 @@ This is exactly what you would pass to the normal js `fetch`, with a little extr
775775
776776
| Option | Description | Default |
777777
| --------------------- | --------------------------------------------------------------------------|------------- |
778-
| `suspense` | Enables Experimental React Suspense mode. [example](https://codesandbox.io/s/usefetch-suspense-i22wv) | false |
779-
| `cachePolicy` | These will be the same ones as Apollo's [fetch policies](https://www.apollographql.com/docs/react/api/react-apollo/#optionsfetchpolicy). Possible values are `cache-and-network`, `network-only`, `cache-only`, `no-cache`, `cache-first`. Currently only supports **`cache-first`** or **`no-cache`** | `cache-first` |
780778
| `cacheLife` | After a successful cache update, that cache data will become stale after this duration | `0` |
781-
| `url` | Allows you to set a base path so relative paths can be used for each request :) | empty string |
782-
| `onNewData` | Merges the current data with the incoming data. Great for pagination. | `(curr, new) => new` |
783-
| `perPage` | Stops making more requests if there is no more data to fetch. (i.e. if we have 25 todos, and the perPage is 10, after fetching 2 times, we will have 20 todos. The last 5 tells us we don't have any more to fetch because it's less than 10) For pagination. | `0` |
784-
| `onAbort` | Runs when the request is aborted. | empty function |
785-
| `onTimeout` | Called when the request times out. | empty function |
786-
| `retries` | When a request fails or times out, retry the request this many times. By default it will not retry. | `0` |
787-
| `retryOn` | You can retry on certain http status codes or have a custom logic to decide whether to retry or not. | `undefined` |
788-
| `retryDelay` | You can retry with certain intervals i.e. 30 seconds `30000` or with custom logic (i.e. to increase retry intervals). | `10000` |
789-
| `timeout` | The request will be aborted/cancelled after this amount of time. This is also the interval at which `retries` will be made at. **in milliseconds** | `30000` </br> (30 seconds) |
779+
| `cachePolicy` | These will be the same ones as Apollo's [fetch policies](https://www.apollographql.com/docs/react/api/react-apollo/#optionsfetchpolicy). Possible values are `cache-and-network`, `network-only`, `cache-only`, `no-cache`, `cache-first`. Currently only supports **`cache-first`** or **`no-cache`** | `cache-first` |
790780
| `data` | Allows you to set a default value for `data` | `undefined` |
791-
| `path` | When using a global `url` set in the `Provider`, this is useful for adding onto it | `''` |
792-
| `loading` | Allows you to set default value for `loading` | `false` unless the last argument of `useFetch` is `[]` |
793781
| `interceptors.request` | Allows you to do something before an http request is sent out. Useful for authentication if you need to refresh tokens a lot. | `undefined` |
794782
| `interceptors.response` | Allows you to do something after an http response is recieved. Useful for something like camelCasing the keys of the response. | `undefined` |
783+
| `loading` | Allows you to set default value for `loading` | `false` unless the last argument of `useFetch` is `[]` |
784+
| `onAbort` | Runs when the request is aborted. | empty function |
785+
| `onNewData` | Merges the current data with the incoming data. Great for pagination. | `(curr, new) => new` |
786+
| `onTimeout` | Called when the request times out. | empty function |
787+
| `path` | When using a global `url` set in the `Provider`, this is useful for adding onto it | `''` |
795788
| `persist` | Persists data for the duration of `cacheLife`. If `cacheLife` is not set it defaults to 24h. Currently only available in Browser. | `false` |
789+
| `perPage` | Stops making more requests if there is no more data to fetch. (i.e. if we have 25 todos, and the perPage is 10, after fetching 2 times, we will have 20 todos. The last 5 tells us we don't have any more to fetch because it's less than 10) For pagination. | `0` |
790+
| `retries` | When a request fails or times out, retry the request this many times. By default it will not retry. | `2` |
791+
| `retryDelay` | You can retry with certain intervals i.e. 30 seconds `30000` or with custom logic (i.e. to increase retry intervals). | `1000` |
792+
| `retryOn` | You can retry on certain http status codes or have custom logic to decide whether to retry or not via a function. | `[]` |
793+
| `suspense` | Enables Experimental React Suspense mode. [example](https://codesandbox.io/s/usefetch-suspense-i22wv) | `false` |
794+
| `timeout` | The request will be aborted/cancelled after this amount of time. This is also the interval at which `retries` will be made at. **in milliseconds**. If set to `0`, it will not timeout except for browser defaults. | `0` |
795+
| `url` | Allows you to set a base path so relative paths can be used for each request :) | empty string |
796796
797797
```jsx
798798
const options = {
799799
// accepts all `fetch` options such as headers, method, etc.
800800

801-
// enables experimental React Suspense mode
802-
suspense: true, // defaults to `false`
801+
// The time in milliseconds that cache data remains fresh.
802+
cacheLife: 0,
803803

804804
// Cache responses to improve speed and reduce amount of requests
805805
// Only one request to the same endpoint will be initiated unless cacheLife expires for 'cache-first'.
806806
cachePolicy: 'cache-first' // 'no-cache'
807+
808+
// set's the default for the `data` field
809+
data: [],
807810

808-
// The time in milliseconds that cache data remains fresh.
809-
cacheLife: 0,
811+
// typically, `interceptors` would be added as an option to the `<Provider />`
812+
interceptors: {
813+
request: async (options, url, path, route) => { // `async` is not required
814+
return options // returning the `options` is important
815+
},
816+
response: async (response) => {
817+
// note: `response.data` is equivalent to `await response.json()`
818+
return response // returning the `response` is important
819+
}
820+
},
821+
822+
// set's the default for `loading` field
823+
loading: false,
824+
825+
// called when aborting the request
826+
onAbort: () => {},
827+
828+
// this will allow you to merge the `data` for pagination.
829+
onNewData: (currData, newData) => {
830+
return [...currData, ...newData]
831+
},
832+
833+
// called when the request times out
834+
onTimeout: () => {},
835+
836+
// if you have a global `url` set up, this is how you can add to it
837+
path: '/path/to/your/api',
838+
839+
// this will tell useFetch not to run the request if the list doesn't haveMore. (pagination)
840+
// i.e. if the last page fetched was < 15, don't run the request again
841+
perPage: 15,
810842

811843
// Allows caching to persist after page refresh. Only supported in the Browser currently.
812844
persist: false,
813845

814846
// amount of times it should retry before erroring out
815847
retries: 3,
816848

817-
// can retry on certain http status codes
818-
retryOn: [503],
819-
// OR
820-
retryOn({ attempt, error, response }) {
821-
// retry on any network error, or 4xx or 5xx status codes
822-
if (error !== null || response.status >= 400) {
823-
console.log(`retrying, attempt number ${attempt + 1}`);
824-
return true;
825-
}
826-
},
827-
828849
// The time between retries
829850
retryDelay: 10000,
830851
// OR
@@ -836,46 +857,25 @@ const options = {
836857
return attempt * 1000
837858
},
838859

839-
// used to be `baseUrl`. You can set your URL this way instead of as the 1st argument
840-
url: 'https://example.com',
841-
842-
// called when the request times out
843-
onTimeout: () => {},
844-
845-
// called when aborting the request
846-
onAbort: () => {},
847-
848-
// this will allow you to merge the data however you choose. Used for Pagination
849-
onNewData: (currData, newData) => {
850-
return [...currData, ...newData]
860+
// can retry on certain http status codes
861+
retryOn: [503],
862+
// OR
863+
retryOn({ attempt, error, response }) {
864+
// retry on any network error, or 4xx or 5xx status codes
865+
if (error !== null || response.status >= 400) {
866+
console.log(`retrying, attempt number ${attempt + 1}`);
867+
return true;
868+
}
851869
},
852-
853-
// this will tell useFetch not to run the request if the list doesn't haveMore. (pagination)
854-
// i.e. if the last page fetched was < 15, don't run the request again
855-
perPage: 15,
856870

857-
// amount of time before the request (or request(s) for each retry) errors out.
871+
// enables experimental React Suspense mode
872+
suspense: true, // defaults to `false`
873+
874+
// amount of time before the request get's canceled/aborted
858875
timeout: 10000,
859876

860-
// if you have a global `url` set up, this is how you can add to it
861-
path: '/path/to/your/api',
862-
863-
// set's the default for the `data` field
864-
data: [],
865-
866-
// set's the default for `loading` field
867-
loading: false,
868-
869-
// typically, `interceptors` would be added as an option to the `<Provider />`
870-
interceptors: {
871-
request: async (options, url, path, route) => { // `async` is not required
872-
return options // returning the `options` is important
873-
},
874-
response: async (response) => {
875-
// note: `response.data` is equivalent to `await response.json()`
876-
return response // returning the `response` is important
877-
}
878-
}
877+
// used to be `baseUrl`. You can set your URL this way instead of as the 1st argument
878+
url: 'https://example.com',
879879
}
880880

881881
useFetch(options)
@@ -1018,38 +1018,6 @@ Todos
10181018
10191019
- [ ] make code editor plugin/package/extension that adds GraphQL syntax highlighting for `useQuery` and `useMutation` 😊
10201020
1021-
<details><summary><b>GraphQL with Suspense <sup><strong>(not implemented yet)</strong></sup></b></summary>
1022-
1023-
```jsx
1024-
const App = () => {
1025-
const [todoTitle, setTodoTitle] = useState('')
1026-
// if there's no <Provider /> used, useMutation works this way
1027-
const mutation = useMutation('http://example.com', `
1028-
mutation CreateTodo($todoTitle string) {
1029-
todo(title: $todoTitle) {
1030-
id
1031-
title
1032-
}
1033-
}
1034-
`)
1035-
1036-
// ideally, I think it should be mutation.write({ todoTitle }) since mutation ~= POST
1037-
const createTodo = () => mutation.read({ todoTitle })
1038-
1039-
if (!request.data) return null
1040-
1041-
return (
1042-
<>
1043-
<input onChange={e => setTodoTitle(e.target.value)} />
1044-
<button onClick={createTodo}>Create Todo</button>
1045-
<pre>{mutation.data}</pre>
1046-
</>
1047-
)
1048-
}
1049-
```
1050-
</details>
1051-
1052-
10531021
[1]: https://github.com/alex-cory/use-http/issues/new?title=[Feature%20Request]%20YOUR_FEATURE_NAME
10541022
[2]: https://github.com/alex-cory/use-http/issues/93#issuecomment-600896722
10551023
[3]: https://github.com/alex-cory/use-http/raw/master/public/dog.png

‎docs/README.md

Lines changed: 66 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -734,56 +734,77 @@ This is exactly what you would pass to the normal js `fetch`, with a little extr
734734
735735
| Option | Description | Default |
736736
| --------------------- | --------------------------------------------------------------------------|------------- |
737-
| `suspense` | Enables React Suspense mode. [example](https://codesandbox.io/s/usefetch-suspense-i22wv) | false |
738-
| `cachePolicy` | These will be the same ones as Apollo's [fetch policies](https://www.apollographql.com/docs/react/api/react-apollo/#optionsfetchpolicy). Possible values are `cache-and-network`, `network-only`, `cache-only`, `no-cache`, `cache-first`. Currently only supports **`cache-first`** or **`no-cache`** | `cache-first` |
739737
| `cacheLife` | After a successful cache update, that cache data will become stale after this duration | `0` |
740-
| `url` | Allows you to set a base path so relative paths can be used for each request :) | empty string |
741-
| `onNewData` | Merges the current data with the incoming data. Great for pagination. | `(curr, new) => new` |
742-
| `perPage` | Stops making more requests if there is no more data to fetch. (i.e. if we have 25 todos, and the perPage is 10, after fetching 2 times, we will have 20 todos. The last 5 tells us we don't have any more to fetch because it's less than 10) For pagination. | `0` |
743-
| `onAbort` | Runs when the request is aborted. | empty function |
744-
| `onTimeout` | Called when the request times out. | empty function |
745-
| `retries` | When a request fails or times out, retry the request this many times. By default it will not retry. | `0` |
746-
| `retryOn` | You can retry on certain http status codes or have a custom logic to decide whether to retry or not. | `undefined` |
747-
| `retryDelay` | You can retry with certain intervals i.e. 30 seconds `30000` or with custom logic (i.e. to increase retry intervals). | `10000` |
748-
| `timeout` | The request will be aborted/cancelled after this amount of time. This is also the interval at which `retries` will be made at. **in milliseconds** | `30000` </br> (30 seconds) |
738+
| `cachePolicy` | These will be the same ones as Apollo's [fetch policies](https://www.apollographql.com/docs/react/api/react-apollo/#optionsfetchpolicy). Possible values are `cache-and-network`, `network-only`, `cache-only`, `no-cache`, `cache-first`. Currently only supports **`cache-first`** or **`no-cache`** | `cache-first` |
749739
| `data` | Allows you to set a default value for `data` | `undefined` |
750-
| `path` | When using a global `url` set in the `Provider`, this is useful for adding onto it | `''` |
751-
| `loading` | Allows you to set default value for `loading` | `false` unless the last argument of `useFetch` is `[]` |
752740
| `interceptors.request` | Allows you to do something before an http request is sent out. Useful for authentication if you need to refresh tokens a lot. | `undefined` |
753741
| `interceptors.response` | Allows you to do something after an http response is recieved. Useful for something like camelCasing the keys of the response. | `undefined` |
742+
| `loading` | Allows you to set default value for `loading` | `false` unless the last argument of `useFetch` is `[]` |
743+
| `onAbort` | Runs when the request is aborted. | empty function |
744+
| `onNewData` | Merges the current data with the incoming data. Great for pagination. | `(curr, new) => new` |
745+
| `onTimeout` | Called when the request times out. | empty function |
746+
| `path` | When using a global `url` set in the `Provider`, this is useful for adding onto it | `''` |
754747
| `persist` | Persists data for the duration of `cacheLife`. If `cacheLife` is not set it defaults to 24h. Currently only available in Browser. | `false` |
748+
| `perPage` | Stops making more requests if there is no more data to fetch. (i.e. if we have 25 todos, and the perPage is 10, after fetching 2 times, we will have 20 todos. The last 5 tells us we don't have any more to fetch because it's less than 10) For pagination. | `0` |
749+
| `retries` | When a request fails or times out, retry the request this many times. By default it will not retry. | `2` |
750+
| `retryDelay` | You can retry with certain intervals i.e. 30 seconds `30000` or with custom logic (i.e. to increase retry intervals). | `1000` |
751+
| `retryOn` | You can retry on certain http status codes or have custom logic to decide whether to retry or not via a function. | `[]` |
752+
| `suspense` | Enables Experimental React Suspense mode. [example](https://codesandbox.io/s/usefetch-suspense-i22wv) | `false` |
753+
| `timeout` | The request will be aborted/cancelled after this amount of time. This is also the interval at which `retries` will be made at. **in milliseconds**. If set to `0`, it will not timeout except for browser defaults. | `0` |
754+
| `url` | Allows you to set a base path so relative paths can be used for each request :) | empty string |
755755
756756
```jsx
757757
const options = {
758758
// accepts all `fetch` options such as headers, method, etc.
759-
760-
// enables React Suspense mode
761-
suspense: true, // defaults to `false`
759+
760+
// The time in milliseconds that cache data remains fresh.
761+
cacheLife: 0,
762762

763763
// Cache responses to improve speed and reduce amount of requests
764764
// Only one request to the same endpoint will be initiated unless cacheLife expires for 'cache-first'.
765765
cachePolicy: 'cache-first' // 'no-cache'
766+
767+
// set's the default for the `data` field
768+
data: [],
766769

767-
// The time in milliseconds that cache data remains fresh.
768-
cacheLife: 0,
770+
// typically, `interceptors` would be added as an option to the `<Provider />`
771+
interceptors: {
772+
request: async (options, url, path, route) => { // `async` is not required
773+
return options // returning the `options` is important
774+
},
775+
response: async (response) => {
776+
// note: `response.data` is equivalent to `await response.json()`
777+
return response // returning the `response` is important
778+
}
779+
},
780+
781+
// set's the default for `loading` field
782+
loading: false,
783+
784+
// called when aborting the request
785+
onAbort: () => {},
786+
787+
// this will allow you to merge the `data` for pagination.
788+
onNewData: (currData, newData) => {
789+
return [...currData, ...newData]
790+
},
791+
792+
// called when the request times out
793+
onTimeout: () => {},
794+
795+
// if you have a global `url` set up, this is how you can add to it
796+
path: '/path/to/your/api',
797+
798+
// this will tell useFetch not to run the request if the list doesn't haveMore. (pagination)
799+
// i.e. if the last page fetched was < 15, don't run the request again
800+
perPage: 15,
769801

770802
// Allows caching to persist after page refresh. Only supported in the Browser currently.
771803
persist: false,
772804

773805
// amount of times it should retry before erroring out
774806
retries: 3,
775807

776-
// can retry on certain http status codes
777-
retryOn: [503],
778-
// OR
779-
retryOn({ attempt, error, response }) {
780-
// retry on any network error, or 4xx or 5xx status codes
781-
if (error !== null || response.status >= 400) {
782-
console.log(`retrying, attempt number ${attempt + 1}`);
783-
return true;
784-
}
785-
},
786-
787808
// The time between retries
788809
retryDelay: 10000,
789810
// OR
@@ -795,46 +816,25 @@ const options = {
795816
return attempt * 1000
796817
},
797818

798-
// used to be `baseUrl`. You can set your URL this way instead of as the 1st argument
799-
url: 'https://example.com',
800-
801-
// called when the request times out
802-
onTimeout: () => {},
803-
804-
// called when aborting the request
805-
onAbort: () => {},
806-
807-
// this will allow you to merge the data however you choose. Used for Pagination
808-
onNewData: (currData, newData) => {
809-
return [...currData, ...newData]
819+
// can retry on certain http status codes
820+
retryOn: [503],
821+
// OR
822+
retryOn({ attempt, error, response }) {
823+
// retry on any network error, or 4xx or 5xx status codes
824+
if (error !== null || response.status >= 400) {
825+
console.log(`retrying, attempt number ${attempt + 1}`);
826+
return true;
827+
}
810828
},
829+
830+
// enables experimental React Suspense mode
831+
suspense: true, // defaults to `false`
811832

812-
// this will tell useFetch not to run the request if the list doesn't haveMore. (pagination)
813-
// i.e. if the last page fetched was < 15, don't run the request again
814-
perPage: 15,
815-
816-
// amount of time before the request (or request(s) for each retry) errors out.
833+
// amount of time before the request get's canceled/aborted
817834
timeout: 10000,
818-
819-
// if you have a global `url` set up, this is how you can add to it
820-
path: '/path/to/your/api',
821-
822-
// set's the default for the `data` field
823-
data: [],
824-
825-
// set's the default for `loading` field
826-
loading: false,
827-
828-
// typically, `interceptors` would be added as an option to the `<Provider />`
829-
interceptors: {
830-
request: async (options, url, path, route) => { // `async` is not required
831-
return options // returning the `options` is important
832-
},
833-
response: async (response) => { // `async` is not required
834-
// note: `response.data` is equivalent to `await response.json()`
835-
return response // returning the `response` is important
836-
}
837-
}
835+
836+
// used to be `baseUrl`. You can set your URL this way instead of as the 1st argument
837+
url: 'https://example.com',
838838
}
839839

840840
useFetch(options)

0 commit comments

Comments
 (0)