From b84239d18f5ed24a185ffde719f9abd8b376d936 Mon Sep 17 00:00:00 2001 From: Nathaniel Tucker Date: Mon, 2 May 2022 14:09:04 -0500 Subject: [PATCH] docs: Move resource-lifetime into expiry-policy page (#1978) --- docs/README.md | 37 +++++++++++++--- docs/getting-started/endpoint.md | 7 +++- docs/getting-started/expiry-policy.md | 44 ++++++++++++++++++++ docs/getting-started/validation.md | 3 +- docs/guides/custom-networking.md | 13 +++--- docs/guides/nested-response.md | 2 +- docs/guides/resource-lifetime.md | 41 ------------------ examples/todo-app/src/pages/Home/NewTodo.tsx | 4 +- examples/todo-app/src/pages/Home/index.tsx | 2 +- examples/todo-app/src/style/main.scss | 4 +- website/docusaurus.config.js | 4 ++ website/sidebars.json | 23 +++------- 12 files changed, 105 insertions(+), 79 deletions(-) delete mode 100644 docs/guides/resource-lifetime.md diff --git a/docs/README.md b/docs/README.md index bc399dfe0d3..76125f9dd46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -321,7 +321,11 @@ Rest Hooks what response it _expects_ to receive from the mutation call, Rest Ho can **immediately** update **all** components using the relevant entity. ```typescript -const getOptimisticResponse = (snap: SnapshotInterface, params: Params, body: FormData) => ({ +const getOptimisticResponse = ( + snap: SnapshotInterface, + params: Params, + body: FormData, +) => ({ id: params.id, ...body, }); @@ -355,7 +359,11 @@ const todoUpdate = new Endpoint(fetchTodoUpdate, { getOptimisticResponse, }); -const getOptimisticResponse = (snap: SnapshotInterface, params: Params, body: FormData) => ({ +const getOptimisticResponse = ( + snap: SnapshotInterface, + params: Params, + body: FormData, +) => ({ id: params.id, ...body, }); @@ -479,7 +487,6 @@ export const getPhoto = new Endpoint(async ({ userId }: { userId: string }) => { [Suspense](./getting-started/data-dependency.md#async-fallbacks) as well as the [render as you fetch](./guides/render-as-you-fetch.md) pattern for improved user experience. - ## Debugging redux-devtools @@ -564,6 +571,26 @@ const todoDetail404Fixture: FixtureEndpoint = { ## Demo -See this all in action in [examples/todo-app](https://stackblitz.com/github/coinbase/rest-hooks/tree/master/examples/todo-app?file=src%2Fpages%2FHome%2Findex.tsx) +### Todo Demo + + + +[Open demo in own tab](https://stackblitz.com/github/coinbase/rest-hooks/tree/master/examples/todo-app?file=src%2Fpages%2FHome%2FTodoListComponent.tsx) + +[Explore on github](https://github.com/coinbase/rest-hooks/tree/master/examples/todo-app) + +### Github Demo + + + +[Open demo in own tab](https://stackblitz.com/github/coinbase/rest-hooks/tree/master/examples/github-app?file=src%2Fpages%2FIssueList.tsx) -Or a [github api demo](https://stackblitz.com/github/coinbase/rest-hooks/tree/master/examples/github-app?file=src%2Fpages%2FIssueList.tsx) +[Explore on github](https://github.com/coinbase/rest-hooks/tree/master/examples/github-app) diff --git a/docs/getting-started/endpoint.md b/docs/getting-started/endpoint.md index 2a02f99bed3..d347fcb2e76 100644 --- a/docs/getting-started/endpoint.md +++ b/docs/getting-started/endpoint.md @@ -1,7 +1,12 @@ --- -title: Endpoint +title: Define API Endpoint +sidebar_label: Endpoint --- + + TypeScript Standard Endpoints + + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import LanguageTabs from '@site/src/components/LanguageTabs'; diff --git a/docs/getting-started/expiry-policy.md b/docs/getting-started/expiry-policy.md index 1d466cc721b..7a4a5df6099 100644 --- a/docs/getting-started/expiry-policy.md +++ b/docs/getting-started/expiry-policy.md @@ -96,6 +96,50 @@ render(); +
@rest-hooks/rest + +## Examples + +To apply to all of a [Resource's endpoints](../api/resource#detail), use [getEndpointExtra](../api/resource#getEndpointExtra) + +### Long cache lifetime + +`LongLivingResource.ts` + +```typescript +import { Resource } from '@rest-hooks/rest'; + +// We can now extend LongLivingResource to get a resource that will be cached for one hour +abstract class LongLivingResource extends Resource { + static getEndpointExtra() { + return { + ...super.getEndpointExtra(), + dataExpiryLength: 60 * 60 * 1000, // one hour + }; + } +} +``` + +### Never retry on error + +`NoRetryResource.ts` + +```typescript +import { Resource } from '@rest-hooks/rest'; + +// We can now extend NoRetryResource to get a resource that will never retry on network error +abstract class NoRetryResource extends Resource { + static getEndpointExtra() { + return { + ...super.getEndpointExtra(), + errorExpiryLength: Infinity, + }; + } +} +``` + +
+ ### Endpoint.invalidIfStale [Endpoint.invalidIfStale](../api/Endpoint#invalidifstale) eliminates the `stale` status, making data diff --git a/docs/getting-started/validation.md b/docs/getting-started/validation.md index c2377ed93f1..514b1b8db25 100644 --- a/docs/getting-started/validation.md +++ b/docs/getting-started/validation.md @@ -1,5 +1,6 @@ --- -title: Validation +title: Entity Validation +sidebar_label: Validation --- import HooksPlayground from '@site/src/components/HooksPlayground'; diff --git a/docs/guides/custom-networking.md b/docs/guides/custom-networking.md index 6da34152216..3799154bd20 100644 --- a/docs/guides/custom-networking.md +++ b/docs/guides/custom-networking.md @@ -3,7 +3,7 @@ title: Using a custom networking library sidebar_label: Custom networking library --- import CodeBlock from '@theme/CodeBlock'; -import ResourceSource from '!!raw-loader!@site/../packages/rest/src/Resource.ts'; +import ResourceSource from '!!raw-loader!@site/../packages/rest/src/BaseResource.ts'; `Resource.fetch()` wraps the standard [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). One key customization is ensuring every network related error thrown has a @@ -29,9 +29,6 @@ The [whatwg-fetch](https://github.com/github/fetch#installation) polyfill will b useful in environments that don't support it, like node and older browsers (Internet Explorer). Be sure to include it in any bundles that need it. -This implementation is provided as a useful reference for building your own. -For the most up-to-date implementation, see the [source on master](https://github.com/coinbase/rest-hooks/blob/master/packages/rest-hooks/src/resource/Resource.ts) - {ResourceSource} ## Superagent @@ -39,7 +36,7 @@ For the most up-to-date implementation, see the [source on master](https://githu [Superagent](https://visionmedia.github.io/superagent/) ```typescript -import { SimpleResource, Method } from '@rest-hooks/rest'; +import { Resource, Method } from '@rest-hooks/rest'; import type { SuperAgentRequest } from 'superagent'; const ResourceError = `JSON expected but not returned from API`; @@ -48,7 +45,7 @@ const ResourceError = `JSON expected but not returned from API`; * Represents an entity to be retrieved from a server. * Typically 1:1 with a url endpoint. */ -export default abstract class Resource extends SimpleResource { +export default abstract class SuperResource extends Resource { /** A function to mutate all requests for fetch */ static fetchPlugin?: (request: SuperAgentRequest) => SuperAgentRequest; @@ -81,10 +78,10 @@ export const isInvalidResponse = (res: request.Response): boolean => { [Axios](https://github.com/axios/axios) ```typescript -import { SimpleResource, Method } from '@rest-hooks/rest'; +import { Resource, Method } from '@rest-hooks/rest'; import axios from 'axios'; -export default abstract class AxiosResource extends SimpleResource { +export default abstract class AxiosResource extends Resource { /** Perform network request and resolve with json body */ static async fetch( input: RequestInfo, init: RequestInit diff --git a/docs/guides/nested-response.md b/docs/guides/nested-response.md index d99e58978c0..9205e2b3f76 100644 --- a/docs/guides/nested-response.md +++ b/docs/guides/nested-response.md @@ -90,7 +90,7 @@ export default class ArticleResource extends Resource { } static urlRoot = 'http://test.com/article/'; - static schema = { + static schema: { [k: string]: Schema } = { author: UserResource, contributors: [UserResource], }; diff --git a/docs/guides/resource-lifetime.md b/docs/guides/resource-lifetime.md deleted file mode 100644 index 5c892212f0f..00000000000 --- a/docs/guides/resource-lifetime.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Custom Resource cache lifetime -sidebar_label: Custom cache lifetime ---- - -Customizing [Expiry Policy](../getting-started/expiry-policy.md) for can be done for all of -a [Resource's endpoints](../api/resource#detail) by using [getEndpointExtra](../api/resource#getEndpointExtra) - -## Examples - -### Long cache lifetime - -`LongLivingResource.ts` - -```typescript -// We can now extend LongLivingResource to get a resource that will be cached for one hour -abstract class LongLivingResource extends Resource { - static getEndpointExtra() { - return { - ...super.getEndpointExtra(), - dataExpiryLength: 60 * 60 * 1000, // one hour - }; - } -} -``` - -### Never retry on error - -`NoRetryResource.ts` - -```typescript -// We can now extend NoRetryResource to get a resource that will never retry on network error -abstract class NoRetryResource extends Resource { - static getEndpointExtra() { - return { - ...super.getEndpointExtra(), - errorExpiryLength: Infinity, - }; - } -} -``` diff --git a/examples/todo-app/src/pages/Home/NewTodo.tsx b/examples/todo-app/src/pages/Home/NewTodo.tsx index 5c16fab01b8..4d16612827c 100644 --- a/examples/todo-app/src/pages/Home/NewTodo.tsx +++ b/examples/todo-app/src/pages/Home/NewTodo.tsx @@ -43,8 +43,8 @@ const TodoBox = styled.div` const TitleInput = styled.input` flex: 1 1 auto; width: 100%; - background: #aaaacc; + background: #e1e1e1; &:focus { - background: aaf; + background: eeeeee; } `; diff --git a/examples/todo-app/src/pages/Home/index.tsx b/examples/todo-app/src/pages/Home/index.tsx index 0e20446d050..f91fa824793 100644 --- a/examples/todo-app/src/pages/Home/index.tsx +++ b/examples/todo-app/src/pages/Home/index.tsx @@ -21,7 +21,7 @@ const Title = styled.nav` top: 0; width: 100%; padding: 18px; - background: #4516f0; + background: white; z-index: 100; `; diff --git a/examples/todo-app/src/style/main.scss b/examples/todo-app/src/style/main.scss index 5445407e815..595cff6af1b 100644 --- a/examples/todo-app/src/style/main.scss +++ b/examples/todo-app/src/style/main.scss @@ -9,6 +9,6 @@ body { font-family: 'Graphik', 'Avenir Next', 'Helvetica Nueue', Helvetica, sans-serif; - background-color: #4516f0; - color: white; + background-color: white; + color: #111; } diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 7549bdd1964..37cf1f37d6a 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -148,6 +148,10 @@ module.exports = { to: '/docs/api/useDLE', from: ['/docs/guides/no-suspense'], }, + { + to: '/docs/getting-started/expiry-policy', + from: ['/docs/guides/resource-lifetime'], + }, ], }, ], diff --git a/website/sidebars.json b/website/sidebars.json index c2e1954e023..766ce33583c 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -75,17 +75,9 @@ { "type": "doc", "id": "guides/mocking-unfinished" - }, - { - "type": "doc", - "id": "guides/resource-lifetime" } ] }, - { - "type": "doc", - "id": "guides/computed-properties" - }, { "type": "category", "collapsible": false, @@ -102,15 +94,12 @@ ] }, { - "type": "category", - "collapsible": false, - "label": "Advanced", - "items": [ - { - "type": "doc", - "id": "guides/custom-networking" - } - ] + "type": "doc", + "id": "guides/computed-properties" + }, + { + "type": "doc", + "id": "guides/custom-networking" } ] },