Merge pull request #57 from morrys/render-as-you-fetch

useLazyLoadQuery & render-as-you-fetch pattern in offline mode

Author: morrys

.prettierrc

@@ -4,5 +4,6 @@
   "trailingComma": "all",
   "arrowParens": "always",
   "printWidth": 140,
-  "parser": "typescript"
+  "parser": "typescript",
+  "endOfLine": "auto"
 }

README.md

@@ -77,39 +77,20 @@ You then need to link the native parts of the library for the platforms you are
 
 <a href="https://memorangapp.com" target="_blank"><img height=40px src="https://github.com/morrys/react-relay-offline/raw/master/docs/assets/memorang-logo.png" alt="Memorang">
 
-## React Web Example
+## react-relay-offline examples
 
-The [react-relay-offline-examples](https://github.com/morrys/react-relay-offline-example) repository contains an integration of react-relay-offline. To try it out:
+The [offline-examples](https://github.com/morrys/offline-examples) repository contains example projects on how to use react-relay-offline:
 
-```
-git clone https://github.com/morrys/react-relay-offline-example.git
-cd react-relay-offline-example/todo
-yarn
-yarn build
-yarn start
-```
-
-Then, just point your browser at `http://localhost:3000`.
-
-or
-
-```
-git clone https://github.com/morrys/react-relay-offline-example.git
-cd react-relay-offline-example/todo-updater
-yarn
-yarn build
-yarn start
-```
+  * `nextjs-ssr-preload`: using the render-as-you-fetch pattern with loadQuery in SSR contexts
+  * `nextjs`: using the QueryRenderer in SSR contexts
+  * `react-native/todo-updater`: using QueryRender in an RN application
+  * `todo-updater`: using the QueryRender
+  * `suspense/cra`: using useLazyLoadQuery in a CRA
+  * `suspense/nextjs-ssr-preload`: using the render-as-you-fetch pattern with loadLazyQuery in react concurrent + SSR contexts
+  * `suspense/nextjs-ssr`: using useLazyLoadQuery in SSR contexts
 
-Then, just point your browser at `http://localhost:3000`.
+To try it out!
 
-## React NextJS Offline SSR Example
-
-The [React NextJS Offline SSR Example](https://github.com/morrys/offline-examples/tree/master/relay/nextjs)
-
-## React Native Example
-
-The [react native offline example](https://github.com/morrys/offline-examples#react-native)
 
 ## Environment
 
@@ -259,10 +240,35 @@ import { QueryRenderer } from 'react-relay-offline';
         render={({ props, error, retry, cached }) => {
 ```
 
+## useQuery
+
+```ts
+import { useQuery } from "react-relay-offline";
+const hooksProps = useQuery(query, variables, {
+  networkCacheConfig: cacheConfig,
+  fetchPolicy,
+  ttl
+});
+```
+
+## useLazyLoadQuery
+
+```ts
+import { useQuery } from "react-relay-offline";
+const hooksProps = useLazyLoadQuery(query, variables, {
+  networkCacheConfig: cacheConfig,
+  fetchPolicy,
+  ttl
+});
+```
+
 ## useRestore & loading
 
-the **useRestore** hook allows you to manage the restore of data persisted in the storage.
-**To be used if relay components are used outside of the QueryRenderer** or **for web applications without SSR & react-native** (
+the **useRestore** hook allows you to manage the hydratation of persistent data in memory and to initialize the environment.
+
+**It must always be used before using environement in web applications without SSR & react legacy & react-native.**
+
+**Otherwise, for SSR and react concurrent applications the restore is natively managed by QueryRenderer & useQueryLazyLoad & useQuery.**
 
 ```
 const isRehydrated = useRestore(environment);
@@ -271,9 +277,6 @@ const isRehydrated = useRestore(environment);
    }
 ```
 
-**For SSR web applications there is a native management in the QueryRenderer to correctly manage the DOM returned by the server and restore the environment**
-
-
 ## fetchQuery
 
 ```ts
@@ -294,24 +297,76 @@ import { useNetInfo } from "react-relay-offline";
 import { NetInfo } from "react-relay-offline";
 ```
 
-## Hooks & useQuery
+## Supports Hooks from relay-hooks
 
 Now you can use hooks (useFragment, usePagination, useRefetch) from [relay-hooks](https://github.com/relay-tools/relay-hooks)
 
-while it is necessary to use `useQuery` of react-relay-offline to manage the offline.
+## render-as-you-fetch & usePreloadedQuery
+
+### loadQuery
+
+* input parameters
+
+same as useQuery + environment
+
+* output parameters
+  * 
+    `next: <TOperationType extends OperationType>(
+        environment: Environment,
+        gqlQuery: GraphQLTaggedNode,
+        variables?: TOperationType['variables'],
+        options?: QueryOptions,
+    ) => Promise<void>`:  fetches data. A promise returns to allow the await in case of SSR
+  * `dispose: () => void`: cancel the subscription and dispose of the fetch
+  * `subscribe: (callback: (value: any) => any) => () => void`:  used by the usePreloadedQuery
+  * `getValue <TOperationType>(environment?: Environment,) => OfflineRenderProps<TOperationType> | Promise<any>`:  used by the usePreloadedQuery
 
 ```ts
-import { useQuery } from "react-relay-offline";
-const hooksProps = useQuery(query, variables, {
-  networkCacheConfig: cacheConfig,
-  fetchPolicy,
-  ttl
-});
+import {graphql, loadQuery} from 'react-relay-offline';
+import {environment} from ''./environment';
+
+const query = graphql`
+  query AppQuery($id: ID!) {
+    user(id: $id) {
+      name
+    }
+  }
+`;
+
+const prefetch = loadQuery();
+prefetch.next(
+  environment,
+  query,
+  {id: '4'},
+  {fetchPolicy: 'store-or-network'},
+);
+// pass prefetch to usePreloadedQuery()
+```
+
+### loadLazyQuery
+
+**is the same as loadQuery but must be used with suspense**
+
+### render-as-you-fetch in SSR
+
+In SSR contexts, **not using the useRestore hook** it is necessary to manually invoke the hydrate but without using the await.
+
+This will allow the usePreloadedQuery hook to correctly retrieve the data from the store and once the hydration is done it will be react-relay-offline
+
+to notify any updated data in the store.
+
+```ts
+  if (!environment.isRehydrated() && ssr) {
+      environment.hydrate().then(() => {}).catch((error) => {});
+  }
+  prefetch.next(environment, QUERY_APP, variables, {
+         fetchPolicy: NETWORK_ONLY,
+  });
 ```
 
 ## Requirement
 
-- Version >=6.0.0 of the react-relay library
+- Version >=8.0.0 of the react-relay library
 - When a new node is created by mutation the id must be generated in the browser to use it in the optimistic response
 
 ## License