Merge pull request #916 from dhis2/beta

feat(use-data-query): add stale-while-revalidate and query deduplication

CHANGELOG.md

@@ -1,3 +1,151 @@
+# [3.0.0-beta.2](https://github.com/dhis2/app-runtime/compare/v3.0.0-beta.1...v3.0.0-beta.2) (2021-09-07)
+
+
+### Bug Fixes
+
+* **use-data-query:** enable swr by default ([76cb34a](https://github.com/dhis2/app-runtime/commit/76cb34abcec9f76f371b1f7f70cedeafc9ccd600))
+
+
+### BREAKING CHANGES
+
+* **use-data-query:** loading will only be set to true when fetching and if there is no data. If there
+is data, loading will be false during fetching. This means that stale data will be shown during
+fetches by default. If you'd like to opt out of showing stale data during loading you can use the
+new `fetching` attribute that is now returned by the useDataQuery hook instead.
+
+# [3.0.0-beta.1](https://github.com/dhis2/app-runtime/compare/v2.12.0-beta.1...v3.0.0-beta.1) (2021-09-02)
+
+
+### chore
+
+* **use-data-query:** list breaking changes ([89cb1e6](https://github.com/dhis2/app-runtime/commit/89cb1e634a336dd871de719fcc51b80f4742294e))
+
+
+### BREAKING CHANGES
+
+* **use-data-query:** If you're using cli-app-scripts, these changes need @dhis2/cli-app-scripts version
+7.1.1 or above. Since this is an optional peer-dependency you'll need to ensure you're using the
+proper version.
+* **use-data-query:** The DataProvider is now a required parent for all components that use the
+useDataQuery hook. For apps that use the dhis2 app-platform this will be done automatically, but
+for libraries (and storybook testing) you'll have to do this manually.
+* **use-data-query:** The variables supplied to refetch are not allowed to contain circular references.
+* **use-data-query:** The data and error values will not be cleared during a refetch (this allows for
+the opt-in stale-while-revalidate). This means that logic that relies on data or error being
+cleared during a refetch will now behave differently. For example, placing an if condition that
+checks if there is an error before a condition that checks for loading will now keep showing the
+error during a refetch, instead of showing the loading spinner.
+* **use-data-query:** There have been issues reported where yarn v1 had trouble installing the correct
+babel dependencies. For the situations where that occured, deduplicating the yarn.lock resolved the
+issue.
+* **use-data-query:** There is a rare but unresolved issue where it's possible for the timing in tests
+to behave differently from the timing in apps. This happens for tests that expect loading to be set
+to true immediately after calling refetch. Changing such an assertion to an assertion that waits
+for loading to eventually be true, i.e. @testing-library/react's waitFor(), resolves this issue.
+
+# [2.12.0-beta.1](https://github.com/dhis2/app-runtime/compare/v2.11.1...v2.12.0-beta.1) (2021-09-02)
+
+
+### Bug Fixes
+
+* **dependencies:** add optional cli-app-scripts peer dependency requirement ([32733b5](https://github.com/dhis2/app-runtime/commit/32733b5725ccb3c2532b7c49ccb221e0c4e50e17))
+* **logging:** silence react-query logger by default ([aa3dc1c](https://github.com/dhis2/app-runtime/commit/aa3dc1cdce5d9ad4f0f6b79fe9b055c1954b17c7))
+* **refetch:** force refetch when variables resolve to identical query key ([524eb3e](https://github.com/dhis2/app-runtime/commit/524eb3eec0f50b00ae3db1a4c3e052993bbe4edc))
+* **use-data-query:** drop context sharing ([f9af172](https://github.com/dhis2/app-runtime/commit/f9af172fa7d14139c8d003862d597ff2183b40ab))
+* **use-data-query:** only set variables if they've changed ([e96d984](https://github.com/dhis2/app-runtime/commit/e96d9848bc036e51f470721195e05f56e99adb17))
+* **use-data-query:** throw more specific error on serialization failure ([35a6b28](https://github.com/dhis2/app-runtime/commit/35a6b280ff61f8fdd69a5d2a376f0d3e7be2c7a9))
+* **use-data-query:** use isFetching for loading state ([728f346](https://github.com/dhis2/app-runtime/commit/728f3464705b43e0c8074cf64d5fcd1d08280e91))
+* **use-data-query:** use local stable value hashing function ([147ba28](https://github.com/dhis2/app-runtime/commit/147ba281bde191597e5d402a3fc2883268dadd3a))
+* **use-data-query:** use ref to store variables hash ([3025dc7](https://github.com/dhis2/app-runtime/commit/3025dc7211b19eb2639e3c01bd19f50a8d23a012))
+
+
+### Features
+
+* **custom-data-provider:** include react-query provider in custom-data-provider ([99ff732](https://github.com/dhis2/app-runtime/commit/99ff732521f80dbe6431586ebe0b99f93ed2f080))
+* **custom-data-provider:** use query client defaults for custom data provider ([a566c4d](https://github.com/dhis2/app-runtime/commit/a566c4d943742c863006c6f7fa0ce3ba04380a4d))
+* **data-provider:** enable context sharing ([2018513](https://github.com/dhis2/app-runtime/commit/2018513f8fa53972d0c483ae8c2bd4f130175ab7))
+* **use-data-query:** set conservative defaults for caching ([e5e4f69](https://github.com/dhis2/app-runtime/commit/e5e4f6993e4736efdbc86ea4ca286f45915bc451))
+* **use-data-query:** use react-query to cache queries ([87fdcd8](https://github.com/dhis2/app-runtime/commit/87fdcd841e0fa6f299b2363773233c191d874ce0))
+
+# [2.9.0-beta.7](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.6...v2.9.0-beta.7) (2021-08-12)
+
+
+### Bug Fixes
+
+* **use-data-query:** throw more specific error on serialization failure ([35a6b28](https://github.com/dhis2/app-runtime/commit/35a6b280ff61f8fdd69a5d2a376f0d3e7be2c7a9))
+
+# [2.9.0-beta.6](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.5...v2.9.0-beta.6) (2021-08-11)
+
+
+### Bug Fixes
+
+* **refetch:** force refetch when variables resolve to identical query key ([524eb3e](https://github.com/dhis2/app-runtime/commit/524eb3eec0f50b00ae3db1a4c3e052993bbe4edc))
+* **use-data-query:** only set variables if they've changed ([e96d984](https://github.com/dhis2/app-runtime/commit/e96d9848bc036e51f470721195e05f56e99adb17))
+* **use-data-query:** use local stable value hashing function ([147ba28](https://github.com/dhis2/app-runtime/commit/147ba281bde191597e5d402a3fc2883268dadd3a))
+* **use-data-query:** use ref to store variables hash ([3025dc7](https://github.com/dhis2/app-runtime/commit/3025dc7211b19eb2639e3c01bd19f50a8d23a012))
+
+# [2.9.0-beta.5](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.4...v2.9.0-beta.5) (2021-08-09)
+
+
+### Bug Fixes
+
+* **logging:** silence react-query logger by default ([aa3dc1c](https://github.com/dhis2/app-runtime/commit/aa3dc1cdce5d9ad4f0f6b79fe9b055c1954b17c7))
+
+# [2.9.0-beta.4](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.3...v2.9.0-beta.4) (2021-07-22)
+
+
+### Bug Fixes
+
+* **use-data-query:** use isFetching for loading state ([728f346](https://github.com/dhis2/app-runtime/commit/728f3464705b43e0c8074cf64d5fcd1d08280e91))
+
+# [2.9.0-beta.3](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.2...v2.9.0-beta.3) (2021-07-21)
+
+
+### Bug Fixes
+
+* **dependencies:** add optional cli-app-scripts peer dependency requirement ([32733b5](https://github.com/dhis2/app-runtime/commit/32733b5725ccb3c2532b7c49ccb221e0c4e50e17))
+
+# [2.9.0-beta.2](https://github.com/dhis2/app-runtime/compare/v2.9.0-beta.1...v2.9.0-beta.2) (2021-07-20)
+
+
+### Bug Fixes
+
+* **use-data-query:** drop context sharing ([f9af172](https://github.com/dhis2/app-runtime/commit/f9af172fa7d14139c8d003862d597ff2183b40ab))
+
+# [2.9.0-beta.1](https://github.com/dhis2/app-runtime/compare/v2.8.0...v2.9.0-beta.1) (2021-07-20)
+
+
+### Features
+
+* **custom-data-provider:** include react-query provider in custom-data-provider ([99ff732](https://github.com/dhis2/app-runtime/commit/99ff732521f80dbe6431586ebe0b99f93ed2f080))
+* **custom-data-provider:** use query client defaults for custom data provider ([a566c4d](https://github.com/dhis2/app-runtime/commit/a566c4d943742c863006c6f7fa0ce3ba04380a4d))
+* **data-provider:** enable context sharing ([2018513](https://github.com/dhis2/app-runtime/commit/2018513f8fa53972d0c483ae8c2bd4f130175ab7))
+* **use-data-query:** set conservative defaults for caching ([e5e4f69](https://github.com/dhis2/app-runtime/commit/e5e4f6993e4736efdbc86ea4ca286f45915bc451))
+* **use-data-query:** use react-query to cache queries ([87fdcd8](https://github.com/dhis2/app-runtime/commit/87fdcd841e0fa6f299b2363773233c191d874ce0))
+
+# [2.9.0-alpha.3](https://github.com/dhis2/app-runtime/compare/v2.9.0-alpha.2...v2.9.0-alpha.3) (2021-07-12)
+
+
+### Features
+
+* **custom-data-provider:** use query client defaults for custom data provider ([a566c4d](https://github.com/dhis2/app-runtime/commit/a566c4d943742c863006c6f7fa0ce3ba04380a4d))
+* **use-data-query:** set conservative defaults for caching ([e5e4f69](https://github.com/dhis2/app-runtime/commit/e5e4f6993e4736efdbc86ea4ca286f45915bc451))
+
+# [2.9.0-alpha.2](https://github.com/dhis2/app-runtime/compare/v2.9.0-alpha.1...v2.9.0-alpha.2) (2021-07-08)
+
+
+### Features
+
+* **data-provider:** enable context sharing ([2018513](https://github.com/dhis2/app-runtime/commit/2018513f8fa53972d0c483ae8c2bd4f130175ab7))
+
+# [2.9.0-alpha.1](https://github.com/dhis2/app-runtime/compare/v2.8.0...v2.9.0-alpha.1) (2021-07-06)
+
+
+### Features
+
+* **custom-data-provider:** include react-query provider in custom-data-provider ([99ff732](https://github.com/dhis2/app-runtime/commit/99ff732521f80dbe6431586ebe0b99f93ed2f080))
+* **use-data-query:** use react-query to cache queries ([87fdcd8](https://github.com/dhis2/app-runtime/commit/87fdcd841e0fa6f299b2363773233c191d874ce0))
+
 ## [2.11.1](https://github.com/dhis2/app-runtime/compare/v2.11.0...v2.11.1) (2021-09-02)
 
 

docs/advanced/CustomDataProvider.md

@@ -1,5 +1,40 @@
 # CustomDataProvider
 
-The [CustomDataProvider](https://github.com/dhis2/app-runtime/blob/master/services/data/src/components/CustomDataProvider.tsx) can be used to provide **static** or **custom** data to its children. This is useful for interactive documentation and unit tests!
+The [CustomDataProvider](https://github.com/dhis2/app-runtime/blob/master/services/data/src/react/components/CustomDataProvider.tsx) can be used to provide **static** or **custom** data to its children. This is useful for interactive documentation and unit tests.
 
-> **TODO** Add documentation
+## Options
+
+The CustomDataProvider accepts four props:
+
+-   children: a valid React node.
+-   [data](https://github.com/dhis2/app-runtime/blob/master/services/data/src/links/CustomDataLink.ts#L15): an object that defines the replies for certain resources. See below for examples.
+-   [options](https://github.com/dhis2/app-runtime/blob/master/services/data/src/links/CustomDataLink.ts#L18): an object with the keys `loadForever` and `failOnMiss`. Set `loadForever` to `true` to force queries to keep loading indefinitely. Set `failOnMiss` to `true` to throw an error for any requests that have no matching reply defined in `data`
+-   queryClientOptions: allows you to override the default queryClientOptions, see the [react-query docs](https://react-query.tanstack.com/reference/QueryClient) for the format and available options.
+
+## Static replies
+
+The below example will reply with `reply` to all queries for the `resourceName` resource. Naturally this will only apply to queries executed from descendants of the CustomDataProvider.
+
+```jsx
+<CustomDataProvider data={{ resourceName: 'reply' }}>
+    {children}
+</CustomDataProvider>
+```
+
+## Dynamic replies
+
+Instead of defining a static response it is also possible to supply a function. This allow you to define dynamic responses for a resource. The example below will reply with a random number for each request to the `resourceName` resource.
+
+```jsx
+<CustomDataProvider
+    data={{ resourceName: (type, query, options) => Math.random() }}
+>
+    {children}
+</CustomDataProvider>
+```
+
+The supplied callback will be called with three arguments, namely:
+
+-   [type](https://github.com/dhis2/app-runtime/blob/master/services/data/src/engine/types/ExecuteOptions.ts#L4)
+-   [query](https://github.com/dhis2/app-runtime/blob/master/services/data/src/engine/types/Query.ts#L15)
+-   [options](https://github.com/dhis2/app-runtime/blob/master/services/data/src/engine/types/DataEngineLink.ts#L5)