create branded QueryRef type without exposed properties (#11824)

* create branded `QueryReferenceBase` type

* update some test types

* changeset

* split up into new hierarchy starting from QueryRef type

* add export

* add some type assignability tests

* update doc references

* toPromise return type

* adjust changeset

* stabilize flaky test

* Update .changeset/late-planets-argue.md

Co-authored-by: Jerel Miller <[email protected]>

* types in tests

* adjust notes

* fix integration test TS
---------

Co-authored-by: Jerel Miller <[email protected]>

Author: phryneas

src/testing/matchers/index.d.ts

@@ -3,7 +3,7 @@ import type {
   DocumentNode,
   OperationVariables,
 } from "../../core/index.js";
-import type { QueryReference } from "../../react/index.js";
+import type { QueryRef } from "../../react/index.js";
 import {
   NextRenderOptions,
   Profiler,
@@ -15,8 +15,8 @@ interface ApolloCustomMatchers<R = void, T = {}> {
   /**
    * Used to determine if a queryRef has been disposed.
    */
-  toBeDisposed: T extends QueryReference<any, any> ? () => R
-  : { error: "matcher needs to be called on a QueryReference" };
+  toBeDisposed: T extends QueryRef<any, any> ? () => R
+  : { error: "matcher needs to be called on a QueryRef" };
   /**
    * Used to determine if two GraphQL query documents are equal to each other by
    * comparing their printed values. The document must be parsed by `gql`.

src/testing/matchers/toBeDisposed.ts

@@ -1,26 +1,17 @@
 import type { MatcherFunction } from "expect";
-import type { QueryReference } from "../../react/internal/index.js";
+import type { QueryRef } from "../../react/internal/index.js";
 import {
-  InternalQueryReference,
+  assertWrappedQueryRef,
   unwrapQueryRef,
 } from "../../react/internal/index.js";
 
-function isQueryRef(queryRef: unknown): queryRef is QueryReference {
-  try {
-    return unwrapQueryRef(queryRef as any) instanceof InternalQueryReference;
-  } catch (e) {
-    return false;
-  }
-}
-
-export const toBeDisposed: MatcherFunction<[]> = function (queryRef) {
+export const toBeDisposed: MatcherFunction<[]> = function (_queryRef) {
   const hint = this.utils.matcherHint("toBeDisposed", "queryRef", "", {
     isNot: this.isNot,
   });
 
-  if (!isQueryRef(queryRef)) {
-    throw new Error(`\n${hint}\n\nmust be called with a valid QueryReference`);
-  }
+  const queryRef = _queryRef as QueryRef;
+  assertWrappedQueryRef(queryRef);
 
   const pass = unwrapQueryRef(queryRef).disposed;