docs(guides and examples): improve and fix typo

Author: amen-souissi

docs/src/pages/guides/initial-query-data.md

@@ -23,18 +23,46 @@ const result = useQuery('todos', () => fetch('/todos'), {
 })
 ```
 
-### Initial Data and `staleTime`
-
-`initialData` is treated exactly the same as normal data, which means that is follows the same rules and expectations of `staleTime`.
-
-- If you configure your query observer with a `staleTime` of `10000`, for example, the `initialData` you provide will be considered fresh for that same amount of time, just like your normal data.
-
-```js
-const result = useQuery('todos', () => fetch('/todos'), {
-  initialData: initialTodos,
-  staleTime: 10000,
-})
-```
+### `staleTime` and `initialDataUpdatedAt`
+
+By default, `initialData` is treated as totally fresh, as if it were just fetched. This also means that it will affect how it is interpreted by the `staleTime` option.
+
+- If you configure your query observer with `initialData`, and no `staleTime` (the default `staleTime: 0`), the query will immediately refetch when it mounts:
+
+  ```js
+  function Todos() {
+    // Will show initialTodos immediately, but also immediately refetch todos after mount
+    return useQuery('todos', () => fetch('/todos'), {
+      initialData: initialTodos,
+    })
+  }
+  ```
+
+- If you configure your query observer with `initialData` and a `staleTime` of `1000` ms, the data will be considered fresh for that same amount of time, as if it was just fetched from your query function.
+
+  ```js
+  function Todos() {
+    // Show initialTodos immeidately, but won't refetch until another interaction event is encountered after 1000 ms
+    return useQuery('todos', () => fetch('/todos'), {
+      initialData: initialTodos,
+      staleTime: 1000,
+    })
+  }
+  ```
+
+- So what if your `initialData` isn't totally fresh? That leaves us with the last configuration that is actually the most accurate and uses an option called `initialDataUpdatedAt`. This options allows you to pass a numeric JS timestamp in milliseconds of when the initialData itself was last updated, e.g. what `Date.now()` provides. Take note that if you have a unix timestamp, you'll need to convert it to a JS timestamp by multiplying it by `1000`.
+  ```js
+  function Todos() {
+    // Show initialTodos immeidately, but won't refetch until another interaction event is encountered after 1000 ms
+    return useQuery('todos', () => fetch('/todos'), {
+      initialData: initialTodos,
+      staleTime: 60 * 1000 // 1 minute
+      // This could be 10 seconds ago or 10 minutes ago
+      initialDataUpdatedAt: initialTodosUpdatedTimestamp // eg. 1608412420052
+    })
+  }
+  ```
+  This option allows the staleTime to be used for it's original purpose, determining how fresh the data needs to be, while also allowing the data to be refetched on mount if the `initialData` is older than the `staleTime`. In the example above, our data needs to be fresh within 1 minute, and we can hint to the query when the initialData was last updated so the query can decide for itself whether the data needs to be refetched again or not.
 
 > If you would rather treat your data as **prefetched data**, we recommend that you use the `prefetchQuery` or `fetchQuery` APIs to populate the cache beforehand, thus letting you configure your `staleTime` independently from your initialData
 
@@ -43,42 +71,64 @@ const result = useQuery('todos', () => fetch('/todos'), {
 If the process for accessing a query's initial data is intensive or just not something you want to perform on every render, you can pass a function as the `initialData` value. This function will be executed only once when the query is initialized, saving you precious memory and/or CPU:
 
 ```js
-const result = useQuery('todos', () => fetch('/todos'), {
-  initialData: () => {
-    return getExpensiveTodos()
-  },
-})
-
+function Todos() {
+  return useQuery('todos', () => fetch('/todos'), {
+    initialData: () => {
+      return getExpensiveTodos()
+    },
+  })
+}
 ```
 
 ### Initial Data from Cache
 
 In some circumstances, you may be able to provide the initial data for a query from the cached result of another. A good example of this would be searching the cached data from a todos list query for an individual todo item, then using that as the initial data for your individual todo query:
 
 ```js
-const result = useQuery(['todo', todoId], () => fetch('/todos'), {
-  initialData: () => {
-    // Use a todo from the 'todos' query as the initial data for this todo query
-    return queryClient.getQueryData('todos')?.find(d => d.id === todoId)
-  },
-})
+function Todo({ todoId }) {
+  return useQuery(['todo', todoId], () => fetch('/todos'), {
+    initialData: () => {
+      // Use a todo from the 'todos' query as the initial data for this todo query
+      return queryClient.getQueryData('todos')?.find(d => d.id === todoId)
+    },
+  })
+}
 ```
 
-Most of the time, this pattern works well, but if the source query you're using to look up the initial data from is old, you may not want to use the data at all and just fetch from the server. To make this decision easier, you can use the `queryClient.getQueryState` method instead to get more information about the source query, including a `state.dataUpdatedAt` timestamp you can use to decide if the query is "fresh" enough for your needs:
+### Initial Data from the cache with `initialDataUpdatedAt`
+
+Getting initial data from the cache means the source query you're using to look up the initial data from is likely old, but `initialData` Instead of using an artificial `staleTime` to keep your query from refetching immediately, it's suggested that you pass the source query's `dataUpdatedAt` to `initialDataUpdatedAt`. This provides the query instance with all the information it needs to determine if and when the query needs to be refetched, regardless of initial data being provided.
 
 ```js
-const result = useQuery(['todo', todoId], () => fetch('/todos'), {
-  initialData: () => {
-    // Get the query state
-    const state = queryClient.getQueryState('todos')
-
-    // If the query exists and has data that is no older than 10 seconds...
-    if (state && Date.now() - state.dataUpdatedAt <= 10 * 1000) {
-      // return the individual todo
-      return state.data.find(d => d.id === todoId)
-    }
-
-    // Otherwise, return undefined and let it fetch!
-  },
-})
+function Todo({ todoId }) {
+  return useQuery(['todo', todoId], () => fetch('/todos'), {
+    initialData: () =>
+      queryClient.getQueryData('todos')?.find(d => d.id === todoId),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState('todos')?.dataUpdatedAt,
+  })
+}
 ```
+
+### Conditional Initial Data from Cache
+
+If the source query you're using to look up the initial data from is old, you may not want to use the cached data at all and just fetch from the server. To make this decision easier, you can use the `queryClient.getQueryState` method instead to get more information about the source query, including a `state.dataUpdatedAt` timestamp you can use to decide if the query is "fresh" enough for your needs:
+
+```js
+function Todo({ todoId }) {
+  return useQuery(['todo', todoId], () => fetch('/todos'), {
+    initialData: () => {
+      // Get the query state
+      const state = queryClient.getQueryState('todos')
+
+      // If the query exists and has data that is no older than 10 seconds...
+      if (state && Date.now() - state.dataUpdatedAt <= 10 * 1000) {
+        // return the individual todo
+        return state.data.find(d => d.id === todoId)
+      }
+
+      // Otherwise, return undefined and let it fetch from a hard loading state!
+    },
+  })
+}
+```

docs/src/pages/guides/mutations.md

@@ -50,7 +50,7 @@ In the example above, you also saw that you can pass variables to your mutations
 
 Even with just variables, mutations aren't all that special, but when used with the `onSuccess` option, the [Query Client's `invalidateQueries` method](../reference/QueryClient#queryclientinvalidatequeries) and the [Query Client's `setQueryData` method](../reference/QueryClient#queryclientsetquerydata), mutations become a very powerful tool.
 
-> IMPORTANT: The `mutate` function is an asynchronous function, which means you cannot use it directly in an event callback. If you need to access the event in `onSubmit` you need to wrap `mutate` in another function. This is due to [React event pooling](https://reactjs.org/docs/events.html#event-pooling).
+> IMPORTANT: The `mutate` function is an asynchronous function, which means you cannot use it directly in an event callback. If you need to access the event in `on:submit` you need to wrap `mutate` in another function.
 
 ```markdown
 <script>

docs/src/pages/guides/query-invalidation.md

@@ -21,7 +21,7 @@ When a query is invalidated with `invalidateQueries`, two things happen:
 
 ## Query Matching with `invalidateQueries`
 
-When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For informationo on the types of filters, you can use, please see [Query Filters](./query-filters).
+When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For information on the types of filters, you can use, please see [Query Filters](./query-filters).
 
 In this example, we can use the `todos` prefix to invalidate any queries that start with `todos` in their query key:
 

docs/src/pages/reference/focusManager.md

@@ -3,7 +3,7 @@ id: FocusManager
 title: FocusManager
 ---
 
-The `FocusManager` manages the focus state within React Query.
+The `FocusManager` manages the focus state within Svelte Query.
 
 It can be used to change the default event listeners or to manually change the focus state.
 

docs/src/pages/reference/onlineManager.md

@@ -3,7 +3,7 @@ id: OnlineManager
 title: OnlineManager
 ---
 
-The `OnlineManager` manages the online state within React Query.
+The `OnlineManager` manages the online state within Svelte Query.
 
 It can be used to change the default event listeners or to manually change the online state.
 

examples/custom-hooks/src/components/BasicQuery.svelte

@@ -11,7 +11,7 @@
 <p>
   This example is exactly the same as the basic example, but each query has been
   refactored to be it's own custom hook. This design is the suggested way to use
-  React Query, as it makes it much easier to manage query keys and shared query
+  Svelte Query, as it makes it much easier to manage query keys and shared query
   logic.
 </p>
 {#if postId > -1}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sveltestack/svelte-query",
   "private": false,
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in Svelte",
   "license": "MIT",
   "svelte": "svelte/index.js",