docs: readme

Author: feelixe

packages/react-query-tree/README.md

@@ -2,6 +2,10 @@
 
 React Query Tree lets you define your API as a tree of queries and mutations, with fully typed queryKeys and a slim API for accessing them.
 
+> React Query Tree is heavily inspired by the tRPC React Query client. It provides the same type-safe, hierarchical developer experience, but is designed for client-side use cases where a tRPC server is not required.
+
+<br />
+
 **☹️ Traditional method**
 
 - Query keys and path keys are not typed
@@ -11,9 +15,7 @@ React Query Tree lets you define your API as a tree of queries and mutations, wi
 const todosQuery = useQuery({
   queryKey: ["todos", "list"],
   queryFn: () => {
-    return fetch("https://jsonplaceholder.typicode.com/todos").then((res) =>
-      res.json()
-    );
+    return fetch("/todos");
   },
 });
 ```
@@ -28,13 +30,13 @@ const todosQuery = useQuery({
 **api.ts**
 
 ```ts
-export const api = createClient({
+import { createApi, query } from "react-query-tree";
+
+export const api = createApi({
   todos: {
     list: query({
-      queryFn: async () => {
-        return fetch("https://jsonplaceholder.typicode.com/todos").then((res) =>
-          res.json()
-        );
+      queryFn: () => {
+        return fetch("/todos");
       },
     }),
   },
@@ -49,6 +51,96 @@ const todosQuery = useQuery(api.todos.list.queryOptions());
 
 ## API Documentation
 
-### Collections and client
+### Nested APIs
+
+To avoid making the API object huge you can split it into smaller chunks that are then used the main API object.
+
+```ts
+import { createApi, query } from "react-query-tree";
+
+const todosApi = createApi({
+  list: query({
+    queryFn: () => {
+      return fetch("/todos");
+    },
+  }),
+});
+
+const usersApi = createApi({
+  list: query({
+    queryFn: () => {
+      return fetch("/users");
+    },
+  }),
+});
+export const api = createApi({
+  todos: todosApi,
+  users: usersApi,
+});
+```
+
+### Invalidation
+
+Invalidating a query.
+
+```ts
+queryClient.invalidateQueries({ queryKey: api.todos.list.queryKey() });
+```
+
+Invalidating a path (all nested queries inside that object).
+
+```ts
+queryClient.invalidateQueries({ queryKey: api.todos.pathKey() });
+```
+
+Invalidating inside an API.
+
+```ts
+const todosApi = createApi({
+  list: query({
+    queryFn: () => {
+      return fetch("/todos").then((res) => res.json());
+    },
+  }),
+  create: mutation({
+    mutationFn: (todo) => {
+      return fetch("/todos", {
+        method: "POST",
+        body: JSON.stringify(todo),
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: api.todos.pathKey() });
+    },
+  }),
+});
+```
+
+### Query and Mutation options
+
+You can add query and mutation option directly inside your API.
+
+```ts
+const todosApi = createApi({
+  list: query({
+    queryFn: () => {
+      return fetch("/todos").then((res) => res.json());
+    },
+    staleTime: 10_000,
+    retry: false,
+  }),
+});
+```
+
+These can be extended when consuming the API.
+
+```ts
+useQuery(
+  todosApi.list.queryOptions({
+    staleTime: 5_000,
+  })
+);
+```
 
-To avoid making the api object huge you can split it into collections and move to separate files.
+- Primitive values will override the base options.
+- Functions such as `onSuccess` will be merged.