Merge remote-tracking branch 'origin/master' into refactor/remove-deprecatations

Author: js2me

.changeset/jolly-parrots-cover.md

@@ -0,0 +1,5 @@
+---
+"mobx-tanstack-query": patch
+---
+
+[internal] update deps (dev) to latest

CHANGELOG.md

@@ -1,5 +1,23 @@
 # mobx-tanstack-query
 
+## 6.16.0
+
+### Minor Changes
+
+- [`da6909d`](https://github.com/js2me/mobx-tanstack-query/commit/da6909daed63441f63e8240eea32c31b37c7f668) Thanks [@js2me](https://github.com/js2me)! - added `lazyDelay` option for queries and mutations as features
+
+## 6.15.1
+
+### Patch Changes
+
+- [`eeb0abf`](https://github.com/js2me/mobx-tanstack-query/commit/eeb0abf73cbbe75551d94eb164cc25b0b12a75a5) Thanks [@js2me](https://github.com/js2me)! - fixed `resultObservable` work with merging with query client
+
+## 6.15.0
+
+### Minor Changes
+
+- [`73207cc`](https://github.com/js2me/mobx-tanstack-query/commit/73207cc8e22303d0a2975bac12eedcd4c14945a0) Thanks [@js2me](https://github.com/js2me)! - added `resultObservable` query and mutation features
+
 ## 6.14.1
 
 ### Patch Changes

docs/api/Mutation.md

@@ -152,6 +152,48 @@ const mutation = createMutation(queryClient, () => ({
 // no reactions and subscriptions will be created
 ```
 
+### `lazyDelay` option <Badge type="tip">MutationFeature</Badge>
+
+[_Can be specified using `QueryClient`_](https://js2me.github.io/mobx-tanstack-query/api/QueryClient.html#mutationfeatures)
+
+Only applies when [`lazy`](#lazy-option) is enabled.
+
+After the last MobX observer stops reading the mutation **`result`**, the library keeps the `MutationObserver` subscription alive for an extra **`lazyDelay` milliseconds** before tearing it down. This uses the `endDelay` option of [`lazyObserve`](https://www.npmjs.com/package/yummies) from `yummies/mobx`, same as for [`Query` `lazyDelay`](https://js2me.github.io/mobx-tanstack-query/api/Query.html#lazydelay-option-queryfeature).
+
+Use it to smooth over short-lived UI changes so you do not drop the observer subscription on every transient unmount.
+
+When **`lazyDelay`** is omitted, teardown follows the same rules as for [`Query` `lazyDelay`](https://js2me.github.io/mobx-tanstack-query/api/Query.html#lazydelay-option-queryfeature) (no extra delay unless you set a number).
+
+```ts
+const mutation = new Mutation({
+  queryClient,
+  lazy: true,
+  lazyDelay: 300,
+  mutationFn: async () => api.updatePet(),
+});
+```
+
+### `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 +219,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))
@@ -641,6 +645,32 @@ const query = createQuery(queryClient, () => ({
 // no reactions and subscriptions will be created
 ```
 
+### `lazyDelay` option <Badge type="tip">QueryFeature</Badge>
+
+[_Can be specified using `QueryClient`_](https://js2me.github.io/mobx-tanstack-query/api/QueryClient.html#queryfeatures)
+
+Only applies when [`lazy`](#lazy-option-queryfeature) is enabled.
+
+After the last MobX observer stops reading the query result, the library keeps the TanStack `QueryObserver` subscription alive for an extra **`lazyDelay` milliseconds** before tearing it down. Internally this maps to the `endDelay` option of [`lazyObserve`](https://www.npmjs.com/package/yummies) from `yummies/mobx`.
+
+Use this to avoid churn when UI code briefly mounts and unmounts (for example route transitions or conditional panels): if something starts observing the result again before the delay elapses, the existing subscription is reused and you avoid an immediate unsubscribe/resubscribe cycle.
+
+- **Omitted or `undefined`** — teardown runs as soon as nothing observes the result (equivalent to `endDelay: false` in [`lazyObserve`](https://www.npmjs.com/package/yummies) / `yummies/mobx`).
+- **A positive number** — milliseconds to wait after the last observer detaches before unsubscribing from the TanStack observer.
+
+Example (global default via `QueryClient`):
+
+```ts
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      lazy: true,
+      lazyDelay: 300,
+    },
+  },
+});
+```
+
 ### `transformError` <Badge type="tip">QueryFeature</Badge>
 
 [_Can be specified using `QueryClient`_](https://js2me.github.io/mobx-tanstack-query/api/QueryClient.html#queryfeatures)
@@ -749,6 +779,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

docs/api/QueryClient.md

@@ -44,6 +44,7 @@ export const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       lazy: true,
+      // lazyDelay: 300,
       enableOnDemand: true,
       // resetOnDestroy: false,
       // dynamicOptionsUpdateDelay: undefined,
@@ -71,6 +72,7 @@ export const queryClient = new QueryClient({
       // invalidateByKey: true,
       // resetOnDestroy: true,
       lazy: true,
+      // lazyDelay: 300,
       // transformError: (error) => error,
     },
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-tanstack-query",
-  "version": "6.14.1",
+  "version": "6.16.0",
   "scripts": {
     "prepare": "pnpm dev:install-hooks",
     "clean": "rimraf dist",
@@ -50,31 +50,31 @@
   },
   "dependencies": {
     "linked-abort-controller": "^1.1.1",
-    "yummies": "^7.12.0"
+    "yummies": "^7.19.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.4.13",
     "@changesets/changelog-github": "^0.6.0",
-    "@changesets/cli": "^2.30.0",
+    "@changesets/cli": "^2.31.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.5",
     "commitfmt": "^1.0.4",
     "js2me-biome-config": "^1.1.0",
-    "jsdom": "^29.0.1",
+    "jsdom": "^29.1.0",
     "lefthook": "^1.13.6",
     "nodemon": "^3.1.14",
     "rimraf": "^6.1.3",
-    "sborshik": "^3.0.0",
-    "terser": "^5.46.1",
+    "sborshik": "^3.5.0",
+    "terser": "^5.46.2",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.5"
   },
   "packageManager": "pnpm@9.5.0+sha512.140036830124618d624a2187b50d04289d5a087f326c9edfc0ccd733d76c4f52c3a313d4fc148794a2a9d81553016004e6742e8cf850670268a7387fc220c903"
 }