-**Moon** is a featured, production ready caching **REST** client for every **React UI**. It allows you to manage queries life cycle with an api and easily build React UI components that fetch data via Axios.
+_**The power of react-query with your favorite HTTP Client**_
+
+**Moon** is a featured, production ready caching **REST** client based on [**react-query**](https://github.com/tannerlinsley/react-query) for every **React UI**. It allows you to manage queries life cycle with an api and easily build React UI components that fetch data via a HTTP client (Axios, fetch... ).
The only thing you have to do is transmit the configuration. **Moon does the rest !** π
Moon client can be used in any React app where you want to use data. It's:
@@ -9,31 +11,67 @@ Moon client can be used in any React app where you want to use data. It's:
2. **Universally compatible**, so that Moon works with any build setup, any REST server, and any REST schema.
3. **Simple to get started with**, so you can start loading data right away and learn about advanced features later.
-## Installation
+Table of contents
+=================
+
+
+ * [Installation](#installation)
+ * [Usage](#usage)
+ * [Query](#query-component)
+ * [useQuery](#usequery)
+ * [usePrefetchQuery](#usePrefetchQuery)
+ * [useInfiniteQuery](#useinfinitequery)
+ * [Mutation / useMutation](#mutationusemutation)
+ * [Other useful Hooks](#other-useful-hooks)
+ * [useQueryState](#usequeryresult)
+ * [useQueriesStates](#usequeriesstates)
+ * [useQueryResult](#usequeryresult)
+ * [useQueriesResults](#usequeriesresults)
+ * [useMoon](#usemoon)
+ * [HOCs](#hocs)
+ * [withQueryResult](#withqueryresult)
+ * [withQueriesResults](#withqueriesresults)
+ * [Query props](#query-props)
+ * [InfiniteQuery props](#infinitequery-props)
+ * [Mutation props](#mutation-props)
+ * [Moon config](#moon-config)
+ * [Demo](#demo)
+ * [Getting Started (Devs)](#gettingstarteddevs)
+ * [Running the tests](#running-the-tests)
+ * [Contributing](#contributing)
+
+
+Installation for Axios client
+============================
```bash
-npm install @decathlon/moon --save
+npm install @pricemoov-oss/moon @pricemoov-oss/moon-axios react-query axios --save
```
-## Usage
-You get started by create REST links. A link is an object which need an id and a baseUrl of your REST server (for more information about the REST link config please see the **Moon config** section).
+Usage
+=====
+
+You get started by create REST links. A link is an object which need an id and an HTTP client config like the AxiosConfig (that extends the Moon's ClientConfig) of your REST server (for more information about the REST link config please see the **Moon config** section).
+
+To connect Moon to your React app, you will need to use the MoonProvider component exported from `@pricemoov-oss/moon`. The MoonProvider is a React's Context.Provider. It wraps your React app and places the client and the store (the query cache of the **react-query**) on the context, which allows you to access it from anywhere in your component tree. You also need to add the HTTP client factory (**clientFactory**). Here we have added the Axios factory to create an axios client for each link. You can also add a client factory for each link. This is useful for using multiple data sources or for mocking data during development phase (tests, mvp...).
-To connect Moon to your React app, you will need to use the MoonProvider component exported from `@decathlon/moon`. The MoonProvider is a React's Context.Provider. It wraps your React app and places the client on the context, which allows you to access it from anywhere in your component tree.
```js
-import { MoonProvider } from "@decathlon/moon";
+import { MoonProvider } from "@pricemoov-oss/moon";
+import axiosClientFactory from "@pricemoov-oss/moon-axios";
const links = [
{
id: "FOO",
- baseUrl: "http://foo.com"
+ config: { baseURL: "http://foo.com" }, // the Client config,
+ // clientFactory?: ClientFactoryGo
;
+ mutate()}>Go
;
return error ? {error.message} : result;
}}
);
};
-
```
The same mutation with **useMutation**:
```js
-import { useQuery } from '@decathlon/moon';
+import { useMutation } from '@pricemoov-oss/moon';
const MyComponent = () => {
- const variables = React.useMemo(() => ({ foo: "bar" }), [...]);
- const [{ loading, error, response }, { mutate }] = useMutationGo
;
+ const result = data ? {data.status && "Success"} : mutate()}>Go
;
return error ? {error.message} : result;
};
```
+Internally useMutation use the **react-query**'s useMutation connected to your HTTP client.
-## Other Hooks
+Other useful Hooks
+==================
Sometimes we need to retrieve the state/result of a query in another component. useQueryResult/useQueriesResult/useQueryState/useQueriesStates allows you to do this. For that, it is enough to give him the id/ids of the query/queries:
-### useQueryState
+useQueryState
+-------------
+Updated when the query state is changed. The optional **stateToProps** function is used for selecting the part of the data from the query state that the connected component needs.
-Updated when the query state is changed. The optional **stateToProps** function is used for selecting the part of the data from the query state that the connected component needs.
+```js
+import { useQueryState } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const stateToProps = (queryState) => queryState // optional
+ const isInfinite = true // optional - true if the it's an infinite query (default value === false)
+ const { isFetching } = useQueryState("queryId", stateToProps, isInfinite);
+ return {isFetching ? "Loading..." : "success"};
+};
+```
+
+The first prop is the query id used by the query. If the query is defined without an id then the id generated by default must be used. To generate an identifier, you must use the **getQueryId** utility. The default id is generated from the source, the endPoint and the variables props of the query.
```js
-import { useQueryState } from '@decathlon/moon';
+import { useQueryState, getQueryId } from "@pricemoov-oss/moon";
const MyComponent = () => {
- const stateToProps = (queryState) => queryState
- const { loading } = useQueryState("queryId", stateToProps);
- return {loading ? "Loading..." : "success"};
+ const queryId = getQueryId({ source: "FOO", endPoint: "/users", variables: { foo: "bar" } });
+ const { isFetching } = useQueryState(queryId);
+ return {isFetching ? "Loading..." : "success"};
};
+
```
-### useQueriesStates
+
+useQueriesStates
+----------------
Updated when one of the query states is changed.The optional **statesToProps** function is used for selecting the part of the data from the query state that the connected component needs.
```js
-import { useQueriesStates } from '@decathlon/moon';
+import { useQueriesStates } from '@pricemoov-oss/moon';
const MyComponent = () => {
const statesToProps = (queriesStates) => queriesStates
- const { queryId: { loading } } = useQueriesStates(["queryId"], statesToProps);
- return {loading ? "Loading..." : "success"};
+ const { queryId: { isFetching } } = useQueriesStates(["queryId"], statesToProps);
+ return {isFetching ? "Loading..." : "success"};
};
```
-### useQueryResult
+useQueryResult
+--------------
Updated only when the query result is changed. .The optional **resultToProps** function is used for selecting the part of the data from the query result that the connected component needs.
```js
-import { useQueryResult } from '@decathlon/moon';
+import { useQueryResult } from '@pricemoov-oss/moon';
const MyComponent = () => {
- const resultToProps = (queryResult) => queryResult
- const result = useQueryResult("queryId", resultToProps);
+ const resultToProps = (queryResult) => queryResult // optional
+ const isInfinite = true // optional - true if the it's an infinite query (default value === false)
+ const result = useQueryResult("queryId", resultToProps, isInfinite);
return {...result...};
};
```
-### useQueriesResults
+useQueriesResults
+-----------------
Updated only when one of the query results is changed. The optional **statesToProps** function is used for selecting the part of the data from the queries results that the connected component needs.
```js
-import { useQueriesResults } from '@decathlon/moon';
+import { useQueriesResults } from '@pricemoov-oss/moon';
const MyComponent = () => {
const resultsToProps = (queriesResults) => queriesResults
@@ -173,86 +313,126 @@ const MyComponent = () => {
return {...queryIdResult...};
};
```
-### useMoon
+useMoon
+-------
You can use the moon client directly like this:
```js
-import { useMoon } from '@decathlon/moon';
+import { useMoon } from '@pricemoov-oss/moon';
const MyComponent = () => {
const { client, store } = useMoon();
client.query(...);
client.mutate(...);
- store.readQuery(...);
- store.writeQuery(...);
+ // the store is the queryClient of the react-query API
};
```
-## HOCs
+HOCs
+======
-### withMoon
+withMoon
+--------
Same as useMoon hook.
```js
-import { withMoon } from '@decathlon/moon';
+import { withMoon } from '@pricemoov-oss/moon';
-const MyComponent = ({ client, store }) => {
+interface Props extends IMoonContextValue {
+ prop: string;
+}
+
+const MyComponent: React.FunctionComponent
+
+_**The power of react-query with your favorite HTTP Client**_
+
+**Moon** is a featured, production ready caching **REST** client based on [**react-query**](https://github.com/tannerlinsley/react-query) for every **React UI**. It allows you to manage queries life cycle with an api and easily build React UI components that fetch data via a HTTP client (Axios, fetch... ).
+The only thing you have to do is transmit the configuration. **Moon does the rest !** π
+
+Moon client can be used in any React app where you want to use data. It's:
+
+1. **Incrementally adoptable**, so that you can drop it into an existing React app and start using Moon for just part of your UI.
+2. **Universally compatible**, so that Moon works with any build setup, any REST server, and any REST schema.
+3. **Simple to get started with**, so you can start loading data right away and learn about advanced features later.
+
+
+Table of contents
+=================
+
+
+ * [Installation](#installation)
+ * [Usage](#usage)
+ * [Query](#query-component)
+ * [useQuery](#usequery)
+ * [usePrefetchQuery](#usePrefetchQuery)
+ * [useInfiniteQuery](#useinfinitequery)
+ * [Mutation / useMutation](#mutationusemutation)
+ * [Other useful Hooks](#other-useful-hooks)
+ * [useQueryState](#usequeryresult)
+ * [useQueriesStates](#usequeriesstates)
+ * [useQueryResult](#usequeryresult)
+ * [useQueriesResults](#usequeriesresults)
+ * [useMoon](#usemoon)
+ * [HOCs](#hocs)
+ * [withQueryResult](#withqueryresult)
+ * [withQueriesResults](#withqueriesresults)
+ * [Query props](#query-props)
+ * [InfiniteQuery props](#infinitequery-props)
+ * [Mutation props](#mutation-props)
+ * [Moon config](#moon-config)
+ * [Demo](#demo)
+ * [Getting Started (Devs)](#gettingstarteddevs)
+ * [Running the tests](#running-the-tests)
+ * [Contributing](#contributing)
+
+
+Installation for Axios client
+============================
+```bash
+npm install @pricemoov-oss/moon @pricemoov-oss/moon-axios react-query axios --save
+```
+
+
+Usage
+=====
+
+You get started by create REST links. A link is an object which need an id and an HTTP client config like the AxiosConfig (that extends the Moon's ClientConfig) of your REST server (for more information about the REST link config please see the **Moon config** section).
+
+To connect Moon to your React app, you will need to use the MoonProvider component exported from `@pricemoov-oss/moon`. The MoonProvider is a React's Context.Provider. It wraps your React app and places the client and the store (the query cache of the **react-query**) on the context, which allows you to access it from anywhere in your component tree. You also need to add the HTTP client factory (**clientFactory**). Here we have added the Axios factory to create an axios client for each link. You can also add a client factory for each link. This is useful for using multiple data sources or for mocking data during development phase (tests, mvp...).
+
+
+```js
+import { MoonProvider } from "@pricemoov-oss/moon";
+import axiosClientFactory from "@pricemoov-oss/moon-axios";
+
+const links = [
+ {
+ id: "FOO",
+ config: { baseURL: "http://foo.com" }, // the Client config,
+ // clientFactory?: ClientFactorymutate()}>Go
;
+ return error ? {error.message} : result;
+ }}
+
+ );
+};
+```
+
+The same mutation with **useMutation**:
+
+```js
+import { useMutation } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const [{ error, data }, { mutate }] = useMutationmutate()}>Go
;
+ return error ? {error.message} : result;
+};
+```
+Internally useMutation use the **react-query**'s useMutation connected to your HTTP client.
+
+Other useful Hooks
+==================
+
+Sometimes we need to retrieve the state/result of a query in another component. useQueryResult/useQueriesResult/useQueryState/useQueriesStates allows you to do this. For that, it is enough to give him the id/ids of the query/queries:
+
+useQueryState
+-------------
+Updated when the query state is changed. The optional **stateToProps** function is used for selecting the part of the data from the query state that the connected component needs.
+
+```js
+import { useQueryState } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const stateToProps = (queryState) => queryState // optional
+ const isInfinite = true // optional - true if the it's an infinite query (default value === false)
+ const { isFetching } = useQueryState("queryId", stateToProps, isInfinite);
+ return {isFetching ? "Loading..." : "success"};
+};
+```
+
+The first prop is the query id used by the query. If the query is defined without an id then the id generated by default must be used. To generate an identifier, you must use the **getQueryId** utility. The default id is generated from the source, the endPoint and the variables props of the query.
+
+```js
+import { useQueryState, getQueryId } from "@pricemoov-oss/moon";
+
+const MyComponent = () => {
+ const queryId = getQueryId({ source: "FOO", endPoint: "/users", variables: { foo: "bar" } });
+ const { isFetching } = useQueryState(queryId);
+ return {isFetching ? "Loading..." : "success"};
+};
+
+```
+
+useQueriesStates
+----------------
+
+Updated when one of the query states is changed.The optional **statesToProps** function is used for selecting the part of the data from the query state that the connected component needs.
+
+```js
+import { useQueriesStates } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const statesToProps = (queriesStates) => queriesStates
+ const { queryId: { isFetching } } = useQueriesStates(["queryId"], statesToProps);
+ return {isFetching ? "Loading..." : "success"};
+};
+```
+
+useQueryResult
+--------------
+
+Updated only when the query result is changed. .The optional **resultToProps** function is used for selecting the part of the data from the query result that the connected component needs.
+
+```js
+import { useQueryResult } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const resultToProps = (queryResult) => queryResult // optional
+ const isInfinite = true // optional - true if the it's an infinite query (default value === false)
+ const result = useQueryResult("queryId", resultToProps, isInfinite);
+ return {...result...};
+};
+```
+
+useQueriesResults
+-----------------
+
+Updated only when one of the query results is changed. The optional **statesToProps** function is used for selecting the part of the data from the queries results that the connected component needs.
+
+```js
+import { useQueriesResults } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const resultsToProps = (queriesResults) => queriesResults
+ const { queryId: queryIdResult } = useQueriesResults(["queryId"], statesToProps);
+ return {...queryIdResult...};
+};
+```
+useMoon
+-------
+
+You can use the moon client directly like this:
+
+```js
+import { useMoon } from '@pricemoov-oss/moon';
+
+const MyComponent = () => {
+ const { client, store } = useMoon();
+ client.query(...);
+ client.mutate(...);
+ // the store is the queryClient of the react-query API
+};
+```
+
+HOCs
+======
+
+withMoon
+--------
+
+Same as useMoon hook.
+
+```js
+import { withMoon } from '@pricemoov-oss/moon';
+
+interface Props extends IMoonContextValue {
+ prop: string;
+}
+
+const MyComponent: React.FunctionComponent = Omit = P & { client: MoonClient };
+
+export const MoonContext: React.Context = P | null;
export type PropsWithForwardRef