feat: add resultObservable

Author: js2me

.changeset/curly-forks-divide.md

@@ -0,0 +1,5 @@
+---
+"mobx-tanstack-query": minor
+---
+
+added `resultObservable` query and mutation features

docs/api/Mutation.md

@@ -152,6 +152,27 @@ const mutation = createMutation(queryClient, () => ({
 // no reactions and subscriptions will be created
 ```
 
+### `resultObservable` <Badge type="tip">MutationFeature</Badge>
+
+[_Can be specified using `QueryClient`_](https://js2me.github.io/mobx-tanstack-query/api/QueryClient.html#mutationfeatures)
+
+Chooses how MobX observes the mutation **`result`** property (the `MutationObserverResult`). The library applies `annotation.observable()` from [`yummies/mobx`](https://github.com/js2me/yummies). [`Query`](https://js2me.github.io/mobx-tanstack-query/api/Query.html#resultobservable-queryfeature) stores the payload on a private `_result` and exposes TanStack fields via getters; **`Mutation` decorates the public `result` field directly** — there is no `_result`.
+
+- **Default** — when omitted, behaviour matches **`'deep'`** (deep observability for plain objects and arrays in the result).
+- **`'ref'`** — only the reference to the result object is tracked; reactions run when the whole result is replaced, not when nested fields change in place.
+- **`'shallow'`** / **`'struct'`** — shallow or structural comparison for nested properties.
+- **`false`** — do not decorate `result` (rare; you lose automatic MobX tracking for the result blob).
+
+Example:
+
+```ts
+const mutation = new Mutation({
+  queryClient,
+  resultObservable: 'ref',
+  mutationFn: async (name: string) => api.createPet(name),
+});
+```
+
 ### `destroy()` method
 
 This method is necessary to kill all reactions and subscriptions that are created during the creation of an instance of the `Mutation` class
@@ -177,3 +198,7 @@ Reset current mutation
 ### property `result` <Badge type="info" text="observable.deep" />
 
 Mutation result (The same as returns the [`useMutation` hook](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation))
+
+::: info `observable.deep` is configurable
+The badge reflects the **default**: the public `result` property is decorated as deep observable (unlike `Query`, which uses a private `_result` behind getters). Change the MobX flavour with [`resultObservable`](#resultobservable-mutationfeature) (`ref`, `shallow`, `struct`, `true`, or `false`).
+:::

docs/api/Query.md

@@ -295,6 +295,10 @@ This field is needed for `enableOnDemand` option
 
 Query original result (The same as returns the [`useQuery` hook](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery))
 
+::: info `observable.deep` is configurable
+The badge reflects the **default**: the internal `_result` field is decorated as deep observable. You can change the MobX flavour (`ref`, `shallow`, `struct`, `true`, or `false`) with the [`resultObservable`](#resultobservable-queryfeature) query feature.
+:::
+
 ### `setData(updater, options)`
 
 Set data for current query (Uses [queryClient.setQueryData](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetquerydata))
@@ -749,6 +753,28 @@ const query = new Query({
 })
 ```
 
+### `resultObservable` <Badge type="tip">QueryFeature</Badge>
+
+[_Can be specified using `QueryClient`_](https://js2me.github.io/mobx-tanstack-query/api/QueryClient.html#queryfeatures)
+
+Chooses how MobX observes the internal TanStack Query result object (`_result`). The library applies [`annotation.observable()`](https://github.com/js2me/yummies) from `yummies/mobx`, so this maps directly to MobX flavours: `ref`, `deep`, `shallow`, `struct`, or `true` / `false`.
+
+- **Default** — when omitted, behaviour matches **`'deep'`** (deep observability for plain objects and arrays in the result).
+- **`'ref'`** — only the reference to the result object is tracked; use when the observer should react when the whole result is replaced, not when nested fields change in place.
+- **`'shallow'`** / **`'struct'`** — shallow or structural comparison for nested properties.
+- **`false`** — do not decorate `_result` with an observable annotation (rare; you lose automatic MobX tracking for the result blob).
+
+Example:
+
+```ts
+const query = new Query({
+  queryClient,
+  resultObservable: 'ref',
+  queryKey: ['pets'],
+  queryFn: async () => api.fetchPets(),
+});
+```
+
 ## Recommendations
 
 ### Don't forget about `abortSignal`s or `lazy` option

package.json

@@ -50,31 +50,31 @@
   },
   "dependencies": {
     "linked-abort-controller": "^1.1.1",
-    "yummies": "^7.12.0"
+    "yummies": "^7.16.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.4.11",
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
     "@testing-library/react": "^16.3.2",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^20.19.37",
+    "@types/node": "^20.19.39",
     "@types/react": "^18.3.28",
     "@vitejs/plugin-react-swc": "^4.3.0",
-    "@vitest/coverage-istanbul": "^4.1.2",
+    "@vitest/coverage-istanbul": "^4.1.4",
     "commitfmt": "^1.0.4",
     "js2me-biome-config": "^1.1.0",
-    "jsdom": "^29.0.1",
+    "jsdom": "^29.0.2",
     "lefthook": "^1.13.6",
     "nodemon": "^3.1.14",
     "rimraf": "^6.1.3",
-    "sborshik": "^3.0.0",
+    "sborshik": "^3.0.7",
     "terser": "^5.46.1",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
-    "vite": "^8.0.3",
+    "vite": "^8.0.8",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@9.5.0+sha512.140036830124618d624a2187b50d04289d5a087f326c9edfc0ccd733d76c4f52c3a313d4fc148794a2a9d81553016004e6742e8cf850670268a7387fc220c903"
 }