refactor!: changed resultObservable deep -> ref globally

Author: js2me

.changeset/friendly-mails-cheat.md

@@ -0,0 +1,7 @@
+---
+"mobx-tanstack-query": major
+---
+
+Changed the global default for `resultObservable` from `'deep'` to `'ref'` for both `Query` and `Mutation`.
+
+If your app relies on deep MobX tracking of nested fields inside query or mutation results, set `resultObservable: 'deep'` explicitly (locally or via `QueryClient` defaults).

docs/api/Mutation.md

@@ -179,8 +179,9 @@ const mutation = new Mutation({
 
 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).
+- **Default** — when omitted, behaviour matches **`'ref'`** (only the result object reference is tracked).
 - **`'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.
+- **`'deep'`** — deep observability for plain objects and arrays in the result.
 - **`'shallow'`** / **`'struct'`** — shallow or structural comparison for nested properties.
 - **`false`** — do not decorate `result` (rare; you lose automatic MobX tracking for the result blob).
 
@@ -216,10 +217,10 @@ Subscribe when mutation has been finished with failure
 
 Reset current mutation
 
-### property `result` <Badge type="info" text="observable.deep" />
+### property `result` <Badge type="info" text="observable.ref" />
 
 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`).
+::: info `observable.ref` is configurable
+The badge reflects the **default**: the public `result` property is decorated as `observable.ref` (unlike `Query`, which uses a private `_result` behind getters). Change the MobX flavour with [`resultObservable`](#resultobservable-mutationfeature) (`deep`, `shallow`, `struct`, `true`, or `false`).
 :::

docs/api/Query.md

@@ -291,12 +291,12 @@ The underlying query observer instance from tanstack query core package.
 Any time when you trying to get access to `result` property this field sets as `true`  
 This field is needed for `enableOnDemand` option
 
-### `result: QueryObserverResult` <Badge type="info" text="observable.deep" />
+### `result: QueryObserverResult` <Badge type="info" text="observable.ref" />
 
 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.
+::: info `observable.ref` is configurable
+The badge reflects the **default**: the internal `_result` field is decorated as `observable.ref`. You can change the MobX flavour (`deep`, `shallow`, `struct`, `true`, or `false`) with the [`resultObservable`](#resultobservable-queryfeature) query feature.
 :::
 
 ### `setData(updater, options)`
@@ -785,8 +785,9 @@ const query = new Query({
 
 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).
+- **Default** — when omitted, behaviour matches **`'ref'`** (only the result object reference is tracked).
 - **`'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.
+- **`'deep'`** — deep observability for plain objects and arrays in the result.
 - **`'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).
 

src/base-query.ts

@@ -133,7 +133,7 @@ export abstract class BaseQuery<
       autoRemovePreviousQuery:
         config.autoRemovePreviousQuery ?? qf?.autoRemovePreviousQuery,
       resultObservable:
-        config.resultObservable ?? qf?.resultObservable ?? 'deep',
+        config.resultObservable ?? qf?.resultObservable ?? 'ref',
     };
   }
 

src/infinite-query.test.ts

@@ -1217,7 +1217,7 @@ describe('InfiniteQuery', () => {
 
     it('basic', () => {
       const query = createInfiniteQuery();
-      expect(types.isProxy(query.getInternalResult())).toBe(true);
+      expect(types.isProxy(query.getInternalResult())).toBe(false);
     });
 
     it('(query: resultObservable: false)', () => {

src/mutation.test.ts

@@ -247,7 +247,7 @@ describe('Mutation', () => {
 
     it('basic', () => {
       const mutation = createMutation();
-      expect(types.isProxy(mutation.getInternalResult())).toBe(true);
+      expect(types.isProxy(mutation.getInternalResult())).toBe(false);
     });
 
     it('(mutation: resultObservable: false)', () => {

src/mutation.ts

@@ -176,7 +176,7 @@ export class Mutation<
       resultObservable:
         config.resultObservable ??
         qc.mutationFeatures?.resultObservable ??
-        'deep',
+        'ref',
     };
 
     this.hooks = qc.hooks;

src/mutation.types.ts

@@ -52,13 +52,13 @@ export interface MutationFeatures {
    * and exposes fields via getters), `Mutation` decorates the public `result` field directly. Convenience fields
    * (`data`, `isPending`, `isError`, …) read from that object, so this option controls how deeply updates propagate.
    *
-   * - `'deep'` — default when omitted; deep observability for plain objects and arrays.
+   * - `'ref'` — default when omitted; tracks only the result reference.
+   * - `'deep'` — deep observability for plain objects and arrays.
    * - `'shallow'` / `'struct'` — shallow or structural comparison for nested keys.
-   * - `'ref'` — track only the result reference (useful when the whole result object is replaced each update).
    * - `true` — base `observable` (same as omitting the option).
    * - `false` — skip decorating `result` (no automatic MobX tracking for the result; advanced use only).
    *
-   * @default 'deep'
+   * @default 'ref'
    *
    * [**Documentation**](https://js2me.github.io/mobx-tanstack-query/api/Mutation.html#resultobservable-mutationfeature)
    */

src/query.test.ts

@@ -4620,7 +4620,7 @@ describe('Query', () => {
 
     it('basic', () => {
       const query = createQuery();
-      expect(types.isProxy(query.getInternalResult())).toBe(true);
+      expect(types.isProxy(query.getInternalResult())).toBe(false);
     });
 
     it('(query: resultObservable: false)', () => {

src/query.types.ts

@@ -194,13 +194,13 @@ export interface QueryFeatures {
    * `annotation.observable()` from `yummies/mobx`. Public fields (`data`, `status`, `isLoading`, …) read from
    * this object, so the option controls how deeply updates to the query result propagate to observers.
    *
-   * - `'deep'` — default when omitted; deep observability for plain objects and arrays.
+   * - `'ref'` — default when omitted; tracks only the result reference.
+   * - `'deep'` — deep observability for plain objects and arrays.
    * - `'shallow'` / `'struct'` — shallow or structural comparison for nested keys.
-   * - `'ref'` — track only the result reference (useful when the whole result object is replaced each update).
    * - `true` — base `observable` (same as omitting the option).
    * - `false` — skip decorating `_result` (no automatic MobX tracking for the result; advanced use only).
    *
-   * @default 'deep'
+   * @default 'ref'
    *
    * [**Documentation**](https://js2me.github.io/mobx-tanstack-query/api/Query.html#resultobservable-queryfeature)
    */