@isograph/react 0.0.0-main-d564e834 → 0.0.0-main-fbe23de7

package/dist/react/useResult.js

@@ -1,20 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useResult = void 0;
+exports.maybeUnwrapNetworkRequest = exports.useResult = void 0;
 const IsographEnvironmentProvider_1 = require("../react/IsographEnvironmentProvider");
 const componentCache_1 = require("../core/componentCache");
 const useReadAndSubscribe_1 = require("./useReadAndSubscribe");
-function useResult(fragmentReference) {
+const PromiseWrapper_1 = require("../core/PromiseWrapper");
+function useResult(fragmentReference, networkRequestOptions) {
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    maybeUnwrapNetworkRequest(fragmentReference.networkRequest, networkRequestOptions);
     switch (fragmentReference.readerArtifact.kind) {
         case 'ComponentReaderArtifact': {
             // @ts-expect-error
-            return (0, componentCache_1.getOrCreateCachedComponent)(environment, fragmentReference.readerArtifact.componentName, fragmentReference);
+            return (0, componentCache_1.getOrCreateCachedComponent)(environment, fragmentReference.readerArtifact.componentName, fragmentReference, networkRequestOptions);
         }
         case 'EagerReaderArtifact': {
-            const data = (0, useReadAndSubscribe_1.useReadAndSubscribe)(environment, fragmentReference);
+            const data = (0, useReadAndSubscribe_1.useReadAndSubscribe)(fragmentReference, networkRequestOptions);
             return fragmentReference.readerArtifact.resolver(data);
         }
     }
 }
 exports.useResult = useResult;
+function maybeUnwrapNetworkRequest(networkRequest, networkRequestOptions) {
+    const state = (0, PromiseWrapper_1.getPromiseState)(networkRequest);
+    if (state.kind === 'Err' && networkRequestOptions.throwOnNetworkError) {
+        throw state.error;
+    }
+    else if (state.kind === 'Pending' &&
+        networkRequestOptions.suspendIfInFlight) {
+        throw state.promise;
+    }
+}
+exports.maybeUnwrapNetworkRequest = maybeUnwrapNetworkRequest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.0.0-main-d564e834",
+  "version": "0.0.0-main-fbe23de7",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -17,8 +17,8 @@
     "tsc": "tsc"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-d564e834",
-    "@isograph/react-disposable-state": "0.0.0-main-d564e834",
+    "@isograph/disposable-types": "0.0.0-main-fbe23de7",
+    "@isograph/react-disposable-state": "0.0.0-main-fbe23de7",
     "react": "^18.2.0"
   },
   "devDependencies": {

package/src/core/FragmentReference.ts

@@ -1,6 +1,7 @@
 import { DataId } from './IsographEnvironment';
 import { RefetchQueryNormalizationArtifactWrapper } from '../core/entrypoint';
 import { TopLevelReaderArtifact } from './reader';
+import { PromiseWrapper } from './PromiseWrapper';
 
 // TODO type this better
 export type VariableValue = string | number | boolean | null | object;
@@ -21,4 +22,5 @@ export type FragmentReference<
   readonly variables: Variables | null;
   // TODO: We should instead have ReaderAst<TClientFieldProps>
   readonly nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[];
+  readonly networkRequest: PromiseWrapper<void, any>;
 };

package/src/core/PromiseWrapper.ts

@@ -1,29 +1,75 @@
+export type AnyError = any;
+
 const NOT_SET: Symbol = Symbol('NOT_SET');
 type NotSet = typeof NOT_SET;
 
+type Result<T, E> =
+  | {
+      kind: 'Ok';
+      value: T;
+    }
+  | {
+      kind: 'Err';
+      error: E;
+    };
+
 /**
  * Invariant:
  * Before the promise is resolved, value becomes non-null.
  */
-export type PromiseWrapper<T> = {
+export type PromiseWrapper<T, E> = {
   readonly promise: Promise<T>;
-  value: Exclude<T, NotSet> | NotSet;
+  result: Result<Exclude<T, NotSet>, E> | NotSet;
 };
 
-export function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T> {
+export function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T, any> {
   // TODO confirm suspense works if the promise is already resolved.
-  const wrapper: PromiseWrapper<T> = { promise, value: NOT_SET };
-  promise.then((v) => {
-    // T is assignable to Exclude<T, Symbol> | Symbol
-    wrapper.value = v as any;
-  });
+  const wrapper: PromiseWrapper<T, any> = { promise, result: NOT_SET };
+  promise
+    .then((v) => {
+      // v is assignable to Exclude<T, Symbol> | Symbol
+      wrapper.result = { kind: 'Ok', value: v as any };
+    })
+    .catch((e) => {
+      // e is assignable to Exclude<T, Symbol> | Symbol
+      wrapper.result = { kind: 'Err', error: e as any };
+    });
   return wrapper;
 }
 
-export function useReadPromise<T>(p: PromiseWrapper<T>): T {
-  if (p.value !== NOT_SET) {
-    // Safety: p.value is either NOT_SET or an actual value.
-    return p.value as any;
+export function readPromise<T, E>(p: PromiseWrapper<T, E>): T {
+  const { result } = p;
+  if (result !== NOT_SET) {
+    // Safety: p.result is either NOT_SET or an actual value.
+    const resultKind = result as Result<T, any>;
+    if (resultKind.kind === 'Ok') {
+      return resultKind.value;
+    } else {
+      throw resultKind.error;
+    }
   }
+
   throw p.promise;
 }
+
+export type PromiseState<T, E> =
+  | {
+      kind: 'Pending';
+      promise: Promise<T>;
+    }
+  | Result<T, E>;
+
+export function getPromiseState<T, E>(
+  p: PromiseWrapper<T, E>,
+): PromiseState<T, E> {
+  const { result } = p;
+  if (result !== NOT_SET) {
+    // Safety: p.result is either NOT_SET or an actual value.
+    const resultKind = result as Result<T, any>;
+    return resultKind;
+  }
+  return {
+    kind: 'Pending',
+    promise: p.promise,
+  };
+}

package/src/core/cache.ts

@@ -1,5 +1,5 @@
 import { Factory, ParentCache } from '@isograph/react-disposable-state';
-import { PromiseWrapper } from './PromiseWrapper';
+import { AnyError, PromiseWrapper } from './PromiseWrapper';
 import {
   DataId,
   ROOT_ID,
@@ -80,15 +80,10 @@ export function getOrCreateCacheForArtifact<
   environment: IsographEnvironment,
   artifact: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
   variables: Variables,
-): ParentCache<PromiseWrapper<TClientFieldValue>> {
+): ParentCache<PromiseWrapper<void, AnyError>> {
   const cacheKey = artifact.queryText + JSON.stringify(stableCopy(variables));
-  const factory: Factory<PromiseWrapper<TClientFieldValue>> = () =>
-    makeNetworkRequest<TClientFieldValue>(environment, artifact, variables);
-  return getOrCreateCache<PromiseWrapper<TClientFieldValue>>(
-    environment,
-    cacheKey,
-    factory,
-  );
+  const factory = () => makeNetworkRequest(environment, artifact, variables);
+  return getOrCreateCache(environment, cacheKey, factory);
 }
 
 type NetworkResponseScalarValue = string | number | boolean;
@@ -183,64 +178,92 @@ export function onNextChange(environment: IsographEnvironment): Promise<void> {
   });
 }
 
+// Calls to readButDoNotEvaluate can suspend (i.e. throw a promise).
+// Maybe in the future, they will be able to throw errors.
+//
+// That's probably okay to ignore. We don't, however, want to prevent
+// updating other subscriptions if one subscription had missing data.
+function withErrorHandling<T>(f: (t: T) => void): (t: T) => void {
+  return (t) => {
+    try {
+      return f(t);
+    } catch {}
+  };
+}
+
 function callSubscriptions(
   environment: IsographEnvironment,
   recordsEncounteredWhenNormalizing: Set<DataId>,
 ) {
-  environment.subscriptions.forEach((subscription) => {
-    switch (subscription.kind) {
-      case 'FragmentSubscription': {
-        // TODO if there are multiple components subscribed to the same
-        // fragment, we will call readButNotEvaluate multiple times. We
-        // should fix that.
-        if (
-          hasOverlappingIds(
-            recordsEncounteredWhenNormalizing,
-            subscription.encounteredDataAndRecords.encounteredRecords,
-          )
-        ) {
-          const newEncounteredDataAndRecords = readButDoNotEvaluate(
-            environment,
-            subscription.fragmentReference,
-          );
-
+  environment.subscriptions.forEach(
+    withErrorHandling((subscription) => {
+      switch (subscription.kind) {
+        case 'FragmentSubscription': {
+          // TODO if there are multiple components subscribed to the same
+          // fragment, we will call readButNotEvaluate multiple times. We
+          // should fix that.
           if (
-            !areEqualObjectsWithDeepComparison(
-              subscription.encounteredDataAndRecords.item,
-              newEncounteredDataAndRecords.item,
+            hasOverlappingIds(
+              recordsEncounteredWhenNormalizing,
+              subscription.encounteredDataAndRecords.encounteredRecords,
             )
           ) {
-            if (typeof window !== 'undefined' && window.__LOG) {
-              console.log('Deep equality - No', {
-                fragmentReference: subscription.fragmentReference,
-                old: subscription.encounteredDataAndRecords.item,
-                new: newEncounteredDataAndRecords.item,
-              });
-            }
-            // TODO deep compare values
-            subscription.callback(newEncounteredDataAndRecords);
-          } else {
-            if (typeof window !== 'undefined' && window.__LOG) {
-              console.log('Deep equality - Yes', {
-                fragmentReference: subscription.fragmentReference,
-                old: subscription.encounteredDataAndRecords.item,
-              });
+            const newEncounteredDataAndRecords = readButDoNotEvaluate(
+              environment,
+              subscription.fragmentReference,
+              // Is this wrong?
+              // Reasons to think no:
+              // - we are only updating the read-out value, and the network
+              //   options only affect whether we throw.
+              // - the component will re-render, and re-throw on its own, anyway.
+              //
+              // Reasons to think not:
+              // - it seems more efficient to suspend here and not update state,
+              //   if we expect that the component will just throw anyway
+              // - consistency
+              // - it's also weird, this is called from makeNetworkRequest, where
+              //   we don't currently pass network request options
+              {},
+            );
+
+            if (
+              !areEqualObjectsWithDeepComparison(
+                subscription.encounteredDataAndRecords.item,
+                newEncounteredDataAndRecords.item,
+              )
+            ) {
+              if (typeof window !== 'undefined' && window.__LOG) {
+                console.log('Deep equality - No', {
+                  fragmentReference: subscription.fragmentReference,
+                  old: subscription.encounteredDataAndRecords.item,
+                  new: newEncounteredDataAndRecords.item,
+                });
+              }
+              // TODO deep compare values
+              subscription.callback(newEncounteredDataAndRecords);
+            } else {
+              if (typeof window !== 'undefined' && window.__LOG) {
+                console.log('Deep equality - Yes', {
+                  fragmentReference: subscription.fragmentReference,
+                  old: subscription.encounteredDataAndRecords.item,
+                });
+              }
             }
           }
+          return;
+        }
+        case 'AnyRecords': {
+          return subscription.callback();
+        }
+        default: {
+          // Ensure we have covered all variants
+          const _: never = subscription;
+          _;
+          throw new Error('Unexpected case');
         }
-        return;
-      }
-      case 'AnyRecords': {
-        return subscription.callback();
-      }
-      default: {
-        // Ensure we have covered all variants
-        const _: never = subscription;
-        _;
-        throw new Error('Unexpected case');
       }
-    }
-  });
+    }),
+  );
 }
 
 function hasOverlappingIds(set1: Set<DataId>, set2: Set<DataId>): boolean {
@@ -563,7 +586,7 @@ function getStoreKeyChunkForArgumentValue(
       return argumentValue.value;
     }
     case 'Variable': {
-      return variables[argumentValue.name];
+      return variables[argumentValue.name] ?? 'null';
     }
     case 'String': {
       return argumentValue.value;

package/src/core/componentCache.ts

@@ -2,11 +2,13 @@ import { stableCopy } from './cache';
 import { IsographEnvironment } from './IsographEnvironment';
 import { FragmentReference } from './FragmentReference';
 import { useReadAndSubscribe } from '../react/useReadAndSubscribe';
+import { NetworkRequestReaderOptions } from './read';
 
 export function getOrCreateCachedComponent(
   environment: IsographEnvironment,
   componentName: string,
   fragmentReference: FragmentReference<any, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
 ): React.FC<any> {
   // cachedComponentsById is a three layer cache: id, then component name, then
   // stringified args. These three, together, uniquely identify a read at a given
@@ -27,7 +29,10 @@ export function getOrCreateCachedComponent(
     byArgs[stringifiedArgs] ??
     (() => {
       function Component(additionalRuntimeProps: { [key: string]: any }) {
-        const data = useReadAndSubscribe(environment, fragmentReference);
+        const data = useReadAndSubscribe(
+          fragmentReference,
+          networkRequestOptions,
+        );
 
         if (typeof window !== 'undefined' && window.__LOG) {
           console.log(

package/src/core/entrypoint.ts

@@ -74,3 +74,4 @@ export type ExtractReadFromStore<Type> =
   Type extends IsographEntrypoint<infer X, any> ? X : never;
 export type ExtractResolverResult<Type> =
   Type extends IsographEntrypoint<any, infer X> ? X : never;
+export type ExtractProps<Type> = Type extends React.FC<infer X> ? X : never;

package/src/core/makeNetworkRequest.ts

@@ -11,14 +11,14 @@ import {
   unretainQuery,
 } from './garbageCollection';
 import { IsographEnvironment } from './IsographEnvironment';
-import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
+import { AnyError, PromiseWrapper, wrapPromise } from './PromiseWrapper';
 import { normalizeData } from './cache';
 
-export function makeNetworkRequest<T>(
+export function makeNetworkRequest(
   environment: IsographEnvironment,
   artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>,
   variables: Variables,
-): ItemCleanupPair<PromiseWrapper<T>> {
+): ItemCleanupPair<PromiseWrapper<void, AnyError>> {
   if (typeof window !== 'undefined' && window.__LOG) {
     console.log('make network request', artifact, variables);
   }
@@ -33,6 +33,13 @@ export function makeNetworkRequest<T>(
         console.log('network response', artifact, networkResponse);
       }
 
+      if (networkResponse.errors != null) {
+        // @ts-expect-error Why are we getting the wrong constructor here?
+        throw new Error('GraphQL network response had errors', {
+          cause: networkResponse,
+        });
+      }
+
       if (status.kind === 'UndisposedIncomplete') {
         normalizeData(
           environment,
@@ -51,13 +58,11 @@ export function makeNetworkRequest<T>(
         };
         retainQuery(environment, retainedQuery);
       }
-      // TODO return null
-      return networkResponse;
     });
 
   const wrapper = wrapPromise(promise);
 
-  const response: ItemCleanupPair<PromiseWrapper<T>> = [
+  const response: ItemCleanupPair<PromiseWrapper<void, AnyError>> = [
     wrapper,
     () => {
       if (status.kind === 'UndisposedComplete') {

package/src/core/read.ts

@@ -9,6 +9,7 @@ import {
   IsographEnvironment,
 } from './IsographEnvironment';
 import { makeNetworkRequest } from './makeNetworkRequest';
+import { PromiseWrapper } from './PromiseWrapper';
 import { ReaderAst } from './reader';
 import { Arguments } from './util';
 
@@ -19,21 +20,43 @@ export type WithEncounteredRecords<T> = {
 
 export function readButDoNotEvaluate<TReadFromStore extends Object>(
   environment: IsographEnvironment,
-  reference: FragmentReference<TReadFromStore, unknown>,
+  fragmentReference: FragmentReference<TReadFromStore, unknown>,
+  networkRequestOptions: NetworkRequestReaderOptions,
 ): WithEncounteredRecords<TReadFromStore> {
   const mutableEncounteredRecords = new Set<DataId>();
   const response = readData(
     environment,
-    reference.readerArtifact.readerAst,
-    reference.root,
-    reference.variables ?? {},
-    reference.nestedRefetchQueries,
+    fragmentReference.readerArtifact.readerAst,
+    fragmentReference.root,
+    fragmentReference.variables ?? {},
+    fragmentReference.nestedRefetchQueries,
+    fragmentReference.networkRequest,
+    networkRequestOptions,
     mutableEncounteredRecords,
   );
   if (typeof window !== 'undefined' && window.__LOG) {
     console.log('done reading', { response });
   }
   if (response.kind === 'MissingData') {
+    // There are two cases here that we care about:
+    // 1. the network request is in flight, we haven't suspend on it, and we want
+    //    to throw if it errors out. So, networkRequestOptions.suspendIfInFlight === false
+    //    and networkRequestOptions.throwOnNetworkError === true.
+    // 2. everything else
+    //
+    // In the first case, we cannot simply throw onNextChange, because if the network
+    // response errors out, we will not update the store, so the onNextChange promise
+    // will not resolve.
+    if (
+      !networkRequestOptions.suspendIfInFlight &&
+      networkRequestOptions.throwOnNetworkError
+    ) {
+      // TODO assert that the network request state is not Err
+      throw new Promise((resolve, reject) => {
+        onNextChange(environment).then(resolve);
+        fragmentReference.networkRequest.promise.catch(reject);
+      });
+    }
     throw onNextChange(environment);
   } else {
     return {
@@ -61,6 +84,8 @@ function readData<TReadFromStore>(
   root: DataId,
   variables: Variables,
   nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
   mutableEncounteredRecords: Set<DataId>,
 ): ReadDataResult<TReadFromStore> {
   mutableEncounteredRecords.add(root);
@@ -126,6 +151,8 @@ function readData<TReadFromStore>(
               link.__link,
               variables,
               nestedRefetchQueries,
+              networkRequest,
+              networkRequestOptions,
               mutableEncounteredRecords,
             );
             if (result.kind === 'MissingData') {
@@ -183,6 +210,8 @@ function readData<TReadFromStore>(
           targetId,
           variables,
           nestedRefetchQueries,
+          networkRequest,
+          networkRequestOptions,
           mutableEncounteredRecords,
         );
         if (data.kind === 'MissingData') {
@@ -205,6 +234,10 @@ function readData<TReadFromStore>(
           variables,
           // Refetch fields just read the id, and don't need refetch query artifacts
           [],
+          // This is probably indicative of the fact that we are doing redundant checks
+          // on the status of this network request...
+          networkRequest,
+          networkRequestOptions,
           mutableEncounteredRecords,
         );
         if (data.kind === 'MissingData') {
@@ -256,6 +289,8 @@ function readData<TReadFromStore>(
             root,
             variables,
             resolverRefetchQueries,
+            networkRequest,
+            networkRequestOptions,
             mutableEncounteredRecords,
           );
           if (data.kind === 'MissingData') {
@@ -276,8 +311,10 @@ function readData<TReadFromStore>(
               readerArtifact: field.readerArtifact,
               root,
               variables: generateChildVariableMap(variables, field.arguments),
+              networkRequest,
               nestedRefetchQueries: resolverRefetchQueries,
             } as const,
+            networkRequestOptions,
           );
         }
         break;
@@ -290,6 +327,8 @@ function readData<TReadFromStore>(
           variables,
           // Refetch fields just read the id, and don't need refetch query artifacts
           [],
+          networkRequest,
+          networkRequestOptions,
           mutableEncounteredRecords,
         );
         if (refetchReaderParams.kind === 'MissingData') {
@@ -318,7 +357,7 @@ function readData<TReadFromStore>(
                 field.queryArguments,
                 variables,
               );
-              const [_networkRequest, disposeNetworkRequest] =
+              const [networkRequest, disposeNetworkRequest] =
                 makeNetworkRequest(
                   environment,
                   field.entrypoint,
@@ -331,7 +370,8 @@ function readData<TReadFromStore>(
                 root: localVariables.id,
                 variables: localVariables,
                 nestedRefetchQueries: field.entrypoint.nestedRefetchQueries,
-              } as const;
+                networkRequest,
+              } as FragmentReference<any, any>;
               return [fragmentReference, disposeNetworkRequest];
             },
           ];
@@ -419,3 +459,8 @@ function writeQueryArgsToVariables(
     }
   }
 }
+
+export type NetworkRequestReaderOptions = {
+  suspendIfInFlight?: boolean;
+  throwOnNetworkError?: boolean;
+};

package/src/index.ts

@@ -4,7 +4,11 @@ export {
   type RetainedQuery,
   garbageCollectEnvironment,
 } from './core/garbageCollection';
-export { type PromiseWrapper } from './core/PromiseWrapper';
+export {
+  type PromiseWrapper,
+  readPromise,
+  getPromiseState,
+} from './core/PromiseWrapper';
 export { subscribe, normalizeData } from './core/cache';
 export { makeNetworkRequest } from './core/makeNetworkRequest';
 export {
@@ -21,36 +25,42 @@ export {
   defaultMissingFieldHandler,
 } from './core/IsographEnvironment';
 export {
-  EagerReaderArtifact,
-  ComponentReaderArtifact,
-  RefetchReaderArtifact,
-  ReaderAst,
-  ReaderAstNode,
-  ReaderLinkedField,
-  ReaderNonLoadableResolverField,
-  ReaderScalarField,
-  TopLevelReaderArtifact,
-  LoadableField,
+  type EagerReaderArtifact,
+  type ComponentReaderArtifact,
+  type RefetchReaderArtifact,
+  type ReaderAst,
+  type ReaderAstNode,
+  type ReaderLinkedField,
+  type ReaderNonLoadableResolverField,
+  type ReaderScalarField,
+  type TopLevelReaderArtifact,
+  type LoadableField,
 } from './core/reader';
 export {
-  NormalizationAst,
-  NormalizationAstNode,
-  NormalizationLinkedField,
-  NormalizationScalarField,
-  IsographEntrypoint,
+  type NormalizationAst,
+  type NormalizationAstNode,
+  type NormalizationLinkedField,
+  type NormalizationScalarField,
+  type IsographEntrypoint,
   assertIsEntrypoint,
-  RefetchQueryNormalizationArtifact,
-  RefetchQueryNormalizationArtifactWrapper,
+  type RefetchQueryNormalizationArtifact,
+  type RefetchQueryNormalizationArtifactWrapper,
+  type ExtractProps,
+  type ExtractReadFromStore,
+  type ExtractResolverResult,
 } from './core/entrypoint';
 export { readButDoNotEvaluate } from './core/read';
 export {
-  ExtractSecondParam,
-  Argument,
-  ArgumentName,
-  ArgumentValue,
-  Arguments,
+  type ExtractSecondParam,
+  type Argument,
+  type ArgumentName,
+  type ArgumentValue,
+  type Arguments,
 } from './core/util';
-export { type FragmentReference } from './core/FragmentReference';
+export {
+  type FragmentReference,
+  type Variables,
+} from './core/FragmentReference';
 
 export {
   IsographEnvironmentProvider,
@@ -58,7 +68,7 @@ export {
   type IsographEnvironmentProviderProps,
 } from './react/IsographEnvironmentProvider';
 export { useImperativeReference } from './react/useImperativeReference';
-export { FragmentReferenceReader } from './react/FragmentReferenceReader';
+export { FragmentReader } from './react/FragmentReader';
 export { useResult } from './react/useResult';
 export { useLazyReference } from './react/useLazyReference';
 export { useRerenderOnChange } from './react/useRerenderOnChange';

package/src/loadable-hooks/useClientSideDefer.ts

@@ -13,10 +13,10 @@ export function useClientSideDefer<TArgs, TResult>(
   args: TArgs,
 ): FragmentReference<any, TResult>;
 
-// TODO allow the user to pass props somehow
 export function useClientSideDefer<TArgs, TResult>(
   loadableField: LoadableField<TArgs, TResult>,
   args?: TArgs,
+  // TODO this should return { fragmentReference, networkRequestReference }
 ): FragmentReference<any, TResult> {
   // @ts-expect-error args is missing iff it has the type void
   const [id, loader] = loadableField(args);