FetchQueries and FetchInfiniteQueries

.changeset/wet-turtles-relax.md

@@ -0,0 +1,5 @@
+---
+"mobx-tanstack-query": minor
+---
+
+added fetch queries new features (FetchQuery, createFetchQuery)

.github/workflows/version-or-publish.yml

@@ -21,12 +21,15 @@ jobs:
     steps:
       - name: Checkout tree
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set-up Node.js
         uses: actions/setup-node@v4
         with:
           check-latest: true
           node-version-file: .nvmrc
+          registry-url: https://registry.npmjs.org
 
       - run: corepack enable
       - run: pnpm i
@@ -43,15 +46,16 @@ jobs:
             echo "last_tag=$tag" >> $GITHUB_OUTPUT
           fi
 
+      - run: npm install -g npm@latest
+
       - name: Create Release Pull Request
         uses: changesets/action@v1
         continue-on-error: false
         id: pub-or-release-pr
         with:
           version: pnpm changeset version
           publish: pnpm pub
+          createGithubReleases: false
         env:
           CI: true
           GITHUB_TOKEN: ${{ github.token }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

docs/.vitepress/config.mts

@@ -33,8 +33,10 @@ export default defineDocsVitepressConfig(configs, {
 					link: "/api/Query",
 					items: [
 						{ text: "Query", link: "/api/Query" },
+						{ text: "FetchQuery", link: "/api/FetchQuery" },
 						{ text: "Mutation", link: "/api/Mutation" },
 						{ text: "InfiniteQuery", link: "/api/InfiniteQuery" },
+						{ text: "FetchInfiniteQuery", link: "/api/FetchInfiniteQuery" },
 						{ text: "QueryClient", link: "/api/QueryClient" },
 						{ text: "Other", link: "/api/other" },
 					],
@@ -45,11 +47,21 @@ export default defineDocsVitepressConfig(configs, {
 					items: [
 						{ text: "Overview", link: "/preset" },
 						{ text: "createQuery", link: "/preset/createQuery" },
+						{ text: "createFetchQuery", link: "/preset/createFetchQuery" },
 						{ text: "createMutation", link: "/preset/createMutation" },
 						{ text: "createInfiniteQuery", link: "/preset/createInfiniteQuery" },
+						{ text: "createFetchInfiniteQuery", link: "/preset/createFetchInfiniteQuery" },
 						{ text: "queryClient", link: "/preset/queryClient" },
 					],
 				},
+				{
+					text: "Errors 🚨",
+					link: "/errors/1",
+					items: [
+						{ text: "#1: Fetch query is not configured", link: "/errors/1" },
+						{ text: "#2: Fetch infinite query is not configured", link: "/errors/2" },
+					],
+				},
 				{
 					text: "Other",
 					items: [

docs/api/FetchInfiniteQuery.md

@@ -0,0 +1,67 @@
+# FetchInfiniteQuery
+
+A [`FetchQuery`](/api/FetchQuery) for paginated data — same declarative `params` API, but with built-in page navigation.
+
+Like [`FetchQuery`](/api/FetchQuery), it auto-generates `queryKey` from `params` and handles the HTTP request for you. The difference is that `params` receives a `pageParam` argument, and you control pagination via `getNextPageParam`.
+
+**All properties and methods** (`data`, `isLoading`, `error`, `fetchNextPage`, `hasNextPage`, etc.) are inherited from [`InfiniteQuery`](/api/InfiniteQuery).
+
+[Reference to source code](/src/fetch-infinite-query.ts)
+
+## Usage
+
+```ts
+const starsQuery = new FetchInfiniteQuery({
+  queryClient,
+  params: ({ pageParam }) => ({
+    path: '/stars',
+    query: {
+      count: 20,
+      page: pageParam,
+    },
+  }),
+  initialPageParam: 1,
+  getNextPageParam: (lastPage, _, lastPageParam) => {
+    return lastPage.length ? lastPageParam + 1 : null;
+  },
+});
+```
+
+### Manual control with `start()`
+
+Create a `FetchInfiniteQuery` without `params` (disabled by default), then fetch manually:
+
+```ts
+const starsQuery = new FetchInfiniteQuery({
+  queryClient,
+  initialPageParam: 1,
+  getNextPageParam: (lastPage, _, lastPageParam) => {
+    return lastPage.length ? lastPageParam + 1 : null;
+  },
+});
+
+const result = await starsQuery.start({
+  params: { path: '/stars', query: { count: 20 } },
+});
+```
+
+### How it works
+
+1. `params` is a function that receives `{ pageParam }` — the current page parameter (starts at `initialPageParam`)
+2. Each page request uses the same `params` logic with a different `pageParam`
+3. After each page loads, `getNextPageParam` determines the next page parameter — return `null` to indicate no more pages
+4. `data` is an array of all fetched pages, and `fetchNextPage()` triggers the next request
+
+### Example: cursor-based pagination
+
+```ts
+const commentsQuery = new FetchInfiniteQuery({
+  queryClient,
+  params: ({ pageParam }) => ({
+    path: '/comments',
+    query: { cursor: pageParam },
+  }),
+  initialPageParam: undefined as string | undefined,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? null,
+});
+```

docs/api/FetchQuery.md

@@ -0,0 +1,142 @@
+# FetchQuery
+
+A [`Query`](/api/Query) that makes HTTP requests for you — no need to write `queryFn` or `queryKey` manually.
+
+Instead of describing **how** to fetch data, you describe **what** to fetch using `params`:
+
+```ts
+// Query — you write the fetch logic yourself
+new Query({
+  queryClient,
+  queryKey: ['/pets'],
+  queryFn: () => fetch('/pets').then(r => r.json()),
+})
+
+// FetchQuery — just describe the request
+new FetchQuery({
+  queryClient,
+  params: { path: '/pets' },
+})
+```
+
+`FetchQuery` auto-generates `queryKey` from your `params`, so the cache stays consistent automatically.
+
+**All properties and methods** (`data`, `isLoading`, `error`, `refetch`, etc.) are inherited from [`Query`](/api/Query).
+
+[Reference to source code](/src/fetch-query.ts)
+
+## Usage
+
+### Basic GET request
+
+```ts
+const petsQuery = new FetchQuery({
+  queryClient,
+  params: {
+    path: '/pets',
+  },
+});
+
+console.log(petsQuery.data, petsQuery.isLoading);
+```
+
+### Dynamic params
+
+`params` can be a function — when MobX observables inside it change, the query automatically refetches with new parameters. Return a falsy value to disable the query.
+
+```ts
+const petId = observable.box<string>();
+
+const petQuery = new FetchQuery({
+  queryClient,
+  params: () => petId.get()
+    ? { path: `/pets/${petId.get()}` }
+    : null, // query is disabled while petId is empty
+});
+```
+
+### POST request with body
+
+```ts
+const createPetQuery = new FetchQuery({
+  queryClient,
+  params: () => ({
+    path: '/pets',
+    method: 'POST',
+    body: { name: 'Fluffy', type: 'cat' },
+  }),
+});
+```
+
+### Full fetch configuration
+
+```ts
+const petQuery = new FetchQuery({
+  queryClient,
+  params: {
+    baseUrl: 'https://api.example.com',
+    path: '/pets',
+    query: { limit: 10, sort: 'name' },
+    method: 'GET',
+    headers: { 'X-Custom-Header': 'value' },
+    notFoundAsNull: true,
+  },
+});
+```
+
+## `FetchQueryParams`
+
+- `path: string` — **Required.** The URL path for the request
+- `baseUrl?: string` — Base URL prepended to `path`. Can also be set globally via [`QueryClient.fetchQueries`](/api/QueryClient#fetchqueries)
+- `query?: Record<string, string | number | boolean | null | undefined>` — Query parameters to be serialized and appended to the URL
+- `method?: string` — HTTP method. Defaults to `"GET"` (or `"POST"` when `body` is provided)
+- `headers?: Record<string>` — Request headers. Merged with global headers from `QueryClient.fetchQueries`
+- `body?: BodyInit | Record<string, unknown>` — Request body. Objects are JSON-serialized with `Content-Type: application/json`; native `BodyInit` (Blob, FormData, etc.) is passed through as-is
+- `request?: Partial<RequestInit>` — Additional `RequestInit` options (except `signal`, `method`, `headers`, `body`)
+- `notFoundAsNull?: boolean` — If `true`, a 404 response returns `null` instead of throwing
+- `responseType?: ResponseType` — Method to read the response body (e.g. `"json"`, `"text"`, `"blob"`). Defaults to `"json"`
+- `transformResponse?: TransformResponseFn` — Custom function to transform the `Response` object before data is returned
+- `throwOnError?: boolean` — Whether to throw the raw `Response` on non-ok status. Defaults to `true`
+- `meta?: QueryMeta` — Metadata attached to the query
+
+## Manual control with `start()`
+
+Create a `FetchQuery` without `params` (disabled by default), then fetch manually:
+
+```ts
+const petQuery = new FetchQuery({
+  queryClient,
+  // no params — query is disabled
+});
+
+const result = await petQuery.start({
+  params: { path: '/pets/123' },
+});
+
+console.log(result.data);
+```
+
+## Request behavior
+
+- Per-request `params` are **merged** with global defaults from [`QueryClient.fetchQueries`](/api/QueryClient#fetchqueries) (per-request values take precedence)
+- The full URL is built as `baseUrl + path` with `query` params serialized and appended
+- `queryKey` is auto-generated from `params` — you never set it manually
+
+## Recommendations
+
+### Use `QueryClient.fetchQueries` for global configuration
+
+Instead of repeating `baseUrl`, `headers`, and other options in every `FetchQuery`, set them once on the `QueryClient`:
+
+```ts
+const queryClient = new QueryClient({
+  fetchQueries: {
+    baseUrl: 'https://api.example.com',
+    headers: {
+      Authorization: 'Bearer my-token',
+    },
+    throwOnError: true,
+    timeout: 30_000,
+  },
+});
+```

docs/api/QueryClient.md

@@ -28,6 +28,7 @@ interface QueryClientConfig {
     mutations: MobxMutatonFeatures;
   };
   hooks?: QueryClientHooks;
+  fetchQueries?: FetchQueriesOptions;
 }
 ```
 
@@ -92,6 +93,38 @@ Entity lifecycle events. Available hooks:
 | onInfiniteQueryDestroy | Triggered when a [`InfiniteQuery`](/api/InfiniteQuery) is destroyed |
 | onMutationDestroy      | Triggered when a [`Mutation`](/api/Mutation) is destroyed           |
 
+### `fetchQueries`
+
+Global configuration for [`FetchQuery`](/api/FetchQuery) and [`FetchInfiniteQuery`](/api/FetchInfiniteQuery). These defaults are merged with per-request `params` in every fetch query.
+
+- `baseUrl?: string` — Base URL prepended to every `path`
+- `headers?: Record<string>` — Default headers merged with per-request headers
+- `customFetch?: typeof globalThis.fetch` — Custom fetch implementation (useful for testing or non-browser environments)
+- `transformResponse?: TransformResponseFn` — Global response transformation function
+- `throwOnError?: boolean` — Whether to throw the raw `Response` on non-ok status. Defaults to `true`
+- `timeout?: number` — Request timeout in milliseconds
+- `credentials?: RequestCredentials` — Credentials mode for requests (e.g. `"include"`, `"same-origin"`)
+- `mode?: RequestMode` — Request mode (e.g. `"cors"`, `"no-cors"`)
+- `meta?: QueryMeta` — Default metadata attached to fetch queries
+
+Example:
+
+```ts
+import { QueryClient } from "mobx-tanstack-query";
+
+const queryClient = new QueryClient({
+  fetchQueries: {
+    baseUrl: "https://api.example.com",
+    headers: {
+      Authorization: "Bearer __TOKEN__",
+    },
+    throwOnError: true,
+    timeout: 30_000,
+    credentials: "include",
+  },
+});
+```
+
 ## Inheritance
 
 `QueryClient` inherits all methods and properties from [QueryClient](https://tanstack.com/query/v5/docs/reference/QueryClient), including:

docs/api/other.md

@@ -1,16 +1,18 @@
 # Other
 
-## `InferQuery`, `InferMutation`, `InferInfiniteQuery` types
+## `InferQuery`, `InferMutation`, `InferInfiniteQuery`, `InferFetchQuery`, `InferFetchInfiniteQuery` types
 
 This types are needed to infer some other types from mutations\configs.
 
 ```ts
 type MyData = InferMutation<typeof myMutation, "data">;
 type MyVariables = InferMutation<typeof myMutation, "variables">;
 type MyConfig = InferMutation<typeof myMutation, "config">;
+type MyFetchData = InferFetchQuery<typeof myFetchQuery, "data">;
+type MyFetchConfig = InferFetchQuery<typeof myFetchQuery, "config">;
 ```
 
-## `QueryConfigFromFn`, `MutationConfigFromFn`, `InfiniteQueryConfigFromFn`
+## `QueryConfigFromFn`, `MutationConfigFromFn`, `InfiniteQueryConfigFromFn`, `FetchQueryConfigFromFn`, `FetchInfiniteQueryConfigFromFn`
 
 This types are needed to create configuration types from your functions of your http client
 
@@ -24,7 +26,7 @@ type Config = MutationConfigFromFn<typeof myApi.createApple>
 
 ## `using` keyword
 
-`Query`, `InfiniteQuery`, `Mutation` supports out-of-box [`using` keyword](https://github.com/tc39/proposal-explicit-resource-management).
+`Query`, `InfiniteQuery`, `Mutation`, `FetchQuery`, `FetchInfiniteQuery` supports out-of-box [`using` keyword](https://github.com/tc39/proposal-explicit-resource-management).
 
 In your project you need to install babel plugin [`@babel/plugin-proposal-explicit-resource-management`](https://www.npmjs.com/package/@babel/plugin-proposal-explicit-resource-management) to add this support.