@isograph/react 0.3.0 → 0.4.0

package/src/core/read.ts

@@ -1,39 +1,51 @@
+import { CleanupFn, type ItemCleanupPair } from '@isograph/disposable-types';
 import {
   getParentRecordKey,
-  insertIfNotExists,
+  insertEmptySetIfMissing,
   onNextChangeToRecord,
   type EncounteredIds,
 } from './cache';
+import { FetchOptions } from './check';
 import { getOrCreateCachedComponent } from './componentCache';
 import {
   IsographEntrypoint,
   RefetchQueryNormalizationArtifactWrapper,
+  type ReaderWithRefetchQueries,
 } from './entrypoint';
 import {
+  ExtractData,
   FragmentReference,
   Variables,
-  ExtractData,
-  ExtractParameters,
+  type UnknownTReadFromStore,
 } from './FragmentReference';
 import {
   assertLink,
   getOrLoadIsographArtifact,
   IsographEnvironment,
-  type Link,
+  type DataTypeValue,
+  type StoreLink,
+  type StoreRecord,
 } from './IsographEnvironment';
+import { logMessage } from './logging';
 import { maybeMakeNetworkRequest } from './makeNetworkRequest';
 import {
   getPromiseState,
+  NOT_SET,
   PromiseWrapper,
   readPromise,
   wrapPromise,
   wrapResolvedValue,
 } from './PromiseWrapper';
-import { ReaderAst } from './reader';
+import {
+  ReaderAst,
+  type LoadablySelectedField,
+  type ReaderImperativelyLoadedField,
+  type ReaderLinkedField,
+  type ReaderNonLoadableResolverField,
+  type ReaderScalarField,
+} from './reader';
+import { getOrCreateCachedStartUpdate } from './startUpdate';
 import { Arguments } from './util';
-import { logMessage } from './logging';
-import { CleanupFn } from '@isograph/disposable-types';
-import { FetchOptions } from './check';
 
 export type WithEncounteredRecords<T> = {
   readonly encounteredRecords: EncounteredIds;
@@ -41,7 +53,7 @@ export type WithEncounteredRecords<T> = {
 };
 
 export function readButDoNotEvaluate<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
 >(
   environment: IsographEnvironment,
   fragmentReference: FragmentReference<TReadFromStore, unknown>,
@@ -49,6 +61,7 @@ export function readButDoNotEvaluate<
 ): WithEncounteredRecords<TReadFromStore> {
   const mutableEncounteredRecords: EncounteredIds = new Map();
 
+  // TODO consider moving this to the outside
   const readerWithRefetchQueries = readPromise(
     fragmentReference.readerWithRefetchQueries,
   );
@@ -64,14 +77,16 @@ export function readButDoNotEvaluate<
     mutableEncounteredRecords,
   );
 
-  logMessage(environment, {
+  logMessage(environment, () => ({
     kind: 'DoneReading',
     response,
-  });
+    fieldName: readerWithRefetchQueries.readerArtifact.fieldName,
+    root: fragmentReference.root,
+  }));
 
   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
+    // 1. the network request is in flight, we haven't suspended on it, and we want
     //    to throw if it errors out. So, networkRequestOptions.suspendIfInFlight === false
     //    and networkRequestOptions.throwOnNetworkError === true.
     // 2. everything else
@@ -83,7 +98,17 @@ export function readButDoNotEvaluate<
       !networkRequestOptions.suspendIfInFlight &&
       networkRequestOptions.throwOnNetworkError
     ) {
-      // TODO assert that the network request state is not Err
+      // What are we doing here? If the network response has errored out, we can do
+      // two things: throw a rejected promise, or throw an error. Both work identically
+      // in the browser. However, during initial SSR on NextJS, throwing a rejected
+      // promise results in an infinite loop (including re-issuing the query until the
+      // process OOM's or something.) Hence, we throw an error.
+
+      const result = fragmentReference.networkRequest.result;
+      if (result !== NOT_SET && result.kind === 'Err') {
+        throw new Error('NetworkError', { cause: result.error });
+      }
+
       throw new Promise((resolve, reject) => {
         onNextChangeToRecord(environment, response.recordLink).then(resolve);
         fragmentReference.networkRequest.promise.catch(reject);
@@ -98,30 +123,31 @@ export function readButDoNotEvaluate<
   }
 }
 
-export type ReadDataResult<TReadFromStore> =
-  | {
-      readonly kind: 'Success';
-      readonly data: ExtractData<TReadFromStore>;
-      readonly encounteredRecords: EncounteredIds;
-    }
+export type ReadDataResultSuccess<Data> = {
+  readonly kind: 'Success';
+  readonly data: Data;
+};
+
+export type ReadDataResult<Data> =
+  | ReadDataResultSuccess<Data>
   | {
       readonly kind: 'MissingData';
       readonly reason: string;
       readonly nestedReason?: ReadDataResult<unknown>;
-      readonly recordLink: Link;
+      readonly recordLink: StoreLink;
     };
 
 function readData<TReadFromStore>(
   environment: IsographEnvironment,
   ast: ReaderAst<TReadFromStore>,
-  root: Link,
-  variables: ExtractParameters<TReadFromStore>,
+  root: StoreLink,
+  variables: Variables,
   nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
   networkRequest: PromiseWrapper<void, any>,
   networkRequestOptions: NetworkRequestReaderOptions,
   mutableEncounteredRecords: EncounteredIds,
-): ReadDataResult<TReadFromStore> {
-  const encounteredIds = insertIfNotExists(
+): ReadDataResult<ExtractData<TReadFromStore>> {
+  const encounteredIds = insertEmptySetIfMissing(
     mutableEncounteredRecords,
     root.__typename,
   );
@@ -139,7 +165,6 @@ function readData<TReadFromStore>(
     return {
       kind: 'Success',
       data: null as any,
-      encounteredRecords: mutableEncounteredRecords,
     };
   }
 
@@ -148,156 +173,51 @@ function readData<TReadFromStore>(
   for (const field of ast) {
     switch (field.kind) {
       case 'Scalar': {
-        const storeRecordName = getParentRecordKey(field, variables);
-        const value = storeRecord[storeRecordName];
-        // TODO consider making scalars into discriminated unions. This probably has
-        // to happen for when we handle errors.
-        if (value === undefined) {
-          return {
-            kind: 'MissingData',
-            reason:
-              'No value for ' + storeRecordName + ' on root ' + root.__link,
-            recordLink: root,
-          };
+        const data = readScalarFieldData(field, storeRecord, root, variables);
+
+        if (data.kind === 'MissingData') {
+          return data;
         }
-        target[field.alias ?? field.fieldName] = value;
+        target[field.alias ?? field.fieldName] = data.data;
+        break;
+      }
+      case 'Link': {
+        target[field.alias] = root;
         break;
       }
       case 'Linked': {
-        const storeRecordName = getParentRecordKey(field, variables);
-        const value = storeRecord[storeRecordName];
-        if (Array.isArray(value)) {
-          const results = [];
-          for (const item of value) {
-            const link = assertLink(item);
-            if (link === undefined) {
-              return {
-                kind: 'MissingData',
-                reason:
-                  'No link for ' +
-                  storeRecordName +
-                  ' on root ' +
-                  root.__link +
-                  '. Link is ' +
-                  JSON.stringify(item),
-                recordLink: root,
-              };
-            } else if (link === null) {
-              results.push(null);
-              continue;
-            }
-
-            const result = readData(
+        const data = readLinkedFieldData(
+          environment,
+          field,
+          storeRecord,
+          root,
+          variables,
+          nestedRefetchQueries,
+          networkRequest,
+          networkRequestOptions,
+          (ast, root) =>
+            readData(
               environment,
-              field.selections,
-              link,
+              ast,
+              root,
               variables,
               nestedRefetchQueries,
               networkRequest,
               networkRequestOptions,
               mutableEncounteredRecords,
-            );
-            if (result.kind === 'MissingData') {
-              return {
-                kind: 'MissingData',
-                reason:
-                  'Missing data for ' +
-                  storeRecordName +
-                  ' on root ' +
-                  root.__link +
-                  '. Link is ' +
-                  JSON.stringify(item),
-                nestedReason: result,
-                recordLink: result.recordLink,
-              };
-            }
-            results.push(result.data);
-          }
-          target[field.alias ?? field.fieldName] = results;
-          break;
-        }
-        let link = assertLink(value);
-
-        if (field.condition) {
-          const data = readData(
-            environment,
-            field.condition.readerAst,
-            root,
-            variables,
-            nestedRefetchQueries,
-            networkRequest,
-            networkRequestOptions,
-            mutableEncounteredRecords,
-          );
-          if (data.kind === 'MissingData') {
-            return {
-              kind: 'MissingData',
-              reason:
-                'Missing data for ' +
-                storeRecordName +
-                ' on root ' +
-                root.__link,
-              nestedReason: data,
-              recordLink: data.recordLink,
-            };
-          }
-          const condition = field.condition.resolver({
-            data: data.data,
-            parameters: {},
-          });
-          if (condition === true) {
-            link = root;
-          } else if (condition === false) {
-            link = null;
-          } else {
-            link = condition;
-          }
-        }
-
-        if (link === undefined) {
-          // TODO make this configurable, and also generated and derived from the schema
-          const missingFieldHandler = environment.missingFieldHandler;
-
-          const altLink = missingFieldHandler?.(
-            storeRecord,
-            root,
-            field.fieldName,
-            field.arguments,
-            variables,
-          );
-          logMessage(environment, {
-            kind: 'MissingFieldHandlerCalled',
-            root,
-            storeRecord,
-            fieldName: field.fieldName,
-            arguments: field.arguments,
-            variables,
-          });
-
-          if (altLink === undefined) {
-            return {
-              kind: 'MissingData',
-              reason:
-                'No link for ' +
-                storeRecordName +
-                ' on root ' +
-                root.__link +
-                '. Link is ' +
-                JSON.stringify(value),
-              recordLink: root,
-            };
-          } else {
-            link = altLink;
-          }
-        } else if (link === null) {
-          target[field.alias ?? field.fieldName] = null;
-          break;
+            ),
+        );
+        if (data.kind === 'MissingData') {
+          return data;
         }
-        const targetId = link;
-        const data = readData(
+        target[field.alias ?? field.fieldName] = data.data;
+        break;
+      }
+      case 'ImperativelyLoadedField': {
+        const data = readImperativelyLoadedField(
           environment,
-          field.selections,
-          targetId,
+          field,
+          root,
           variables,
           nestedRefetchQueries,
           networkRequest,
@@ -305,306 +225,45 @@ function readData<TReadFromStore>(
           mutableEncounteredRecords,
         );
         if (data.kind === 'MissingData') {
-          return {
-            kind: 'MissingData',
-            reason:
-              'Missing data for ' + storeRecordName + ' on root ' + root.__link,
-            nestedReason: data,
-            recordLink: data.recordLink,
-          };
+          return data;
         }
-        target[field.alias ?? field.fieldName] = data.data;
+        target[field.alias] = data.data;
         break;
       }
-      case 'ImperativelyLoadedField': {
-        // First, we read the data using the refetch reader AST (i.e. read out the
-        // id field).
-        const data = readData(
+      case 'Resolver': {
+        const data = readResolverFieldData(
           environment,
-          field.refetchReaderArtifact.readerAst,
+          field,
           root,
           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...
+          nestedRefetchQueries,
           networkRequest,
           networkRequestOptions,
           mutableEncounteredRecords,
         );
         if (data.kind === 'MissingData') {
-          return {
-            kind: 'MissingData',
-            reason:
-              'Missing data for ' + field.alias + ' on root ' + root.__link,
-            nestedReason: data,
-            recordLink: data.recordLink,
-          };
-        } else {
-          const refetchQueryIndex = field.refetchQuery;
-          const refetchQuery = nestedRefetchQueries[refetchQueryIndex];
-          if (refetchQuery == null) {
-            throw new Error(
-              'refetchQuery is null in RefetchField. This is indicative of a bug in Isograph.',
-            );
-          }
-          const refetchQueryArtifact = refetchQuery.artifact;
-          const allowedVariables = refetchQuery.allowedVariables;
-
-          // Second, we allow the user to call the resolver, which will ultimately
-          // use the resolver reader AST to get the resolver parameters.
-          target[field.alias] = (args: any) => [
-            // Stable id
-            root.__link + '__' + field.name,
-            // Fetcher
-            field.refetchReaderArtifact.resolver(
-              environment,
-              refetchQueryArtifact,
-              data.data,
-              filterVariables({ ...args, ...variables }, allowedVariables),
-              root,
-              // TODO these params should be removed
-              null,
-              [],
-            ),
-          ];
-        }
-        break;
-      }
-      case 'Resolver': {
-        const usedRefetchQueries = field.usedRefetchQueries;
-        const resolverRefetchQueries = usedRefetchQueries.map((index) => {
-          const resolverRefetchQuery = nestedRefetchQueries[index];
-          if (resolverRefetchQuery == null) {
-            throw new Error(
-              'resolverRefetchQuery is null in Resolver. This is indicative of a bug in Isograph.',
-            );
-          }
-          return resolverRefetchQuery;
-        });
-
-        switch (field.readerArtifact.kind) {
-          case 'EagerReaderArtifact': {
-            const data = readData(
-              environment,
-              field.readerArtifact.readerAst,
-              root,
-              generateChildVariableMap(variables, field.arguments),
-              resolverRefetchQueries,
-              networkRequest,
-              networkRequestOptions,
-              mutableEncounteredRecords,
-            );
-            if (data.kind === 'MissingData') {
-              return {
-                kind: 'MissingData',
-                reason:
-                  'Missing data for ' + field.alias + ' on root ' + root.__link,
-                nestedReason: data,
-                recordLink: data.recordLink,
-              };
-            } else {
-              const firstParameter = {
-                data: data.data,
-                parameters: variables,
-              };
-              target[field.alias] =
-                field.readerArtifact.resolver(firstParameter);
-            }
-            break;
-          }
-          case 'ComponentReaderArtifact': {
-            target[field.alias] = getOrCreateCachedComponent(
-              environment,
-              field.readerArtifact.componentName,
-              {
-                kind: 'FragmentReference',
-                readerWithRefetchQueries: wrapResolvedValue({
-                  kind: 'ReaderWithRefetchQueries',
-                  readerArtifact: field.readerArtifact,
-                  nestedRefetchQueries: resolverRefetchQueries,
-                }),
-                root,
-                variables: generateChildVariableMap(variables, field.arguments),
-                networkRequest,
-              } as const,
-              networkRequestOptions,
-            );
-            break;
-          }
-          default: {
-            let _: never = field.readerArtifact;
-            _;
-            throw new Error('Unexpected kind');
-          }
+          return data;
         }
+        target[field.alias] = data.data;
         break;
       }
       case 'LoadablySelectedField': {
-        const refetchReaderParams = readData(
+        const data = readLoadablySelectedFieldData(
           environment,
-          field.refetchReaderAst,
+          field,
           root,
           variables,
-          // Refetch fields just read the id, and don't need refetch query artifacts
-          [],
           networkRequest,
           networkRequestOptions,
           mutableEncounteredRecords,
         );
-        if (refetchReaderParams.kind === 'MissingData') {
-          return {
-            kind: 'MissingData',
-            reason:
-              'Missing data for ' + field.alias + ' on root ' + root.__link,
-            nestedReason: refetchReaderParams,
-            recordLink: refetchReaderParams.recordLink,
-          };
-        } else {
-          target[field.alias] = (args: any, fetchOptions?: FetchOptions) => {
-            // TODO we should use the reader AST for this
-            const includeReadOutData = (variables: any, readOutData: any) => {
-              variables.id = readOutData.id;
-              return variables;
-            };
-            const localVariables = includeReadOutData(
-              args ?? {},
-              refetchReaderParams.data,
-            );
-            writeQueryArgsToVariables(
-              localVariables,
-              field.queryArguments,
-              variables,
-            );
-
-            return [
-              // Stable id
-              root.__typename +
-                ':' +
-                root.__link +
-                '/' +
-                field.name +
-                '/' +
-                stableStringifyArgs(localVariables),
-              // Fetcher
-              () => {
-                const fragmentReferenceAndDisposeFromEntrypoint = (
-                  entrypoint: IsographEntrypoint<any, any>,
-                ): [FragmentReference<any, any>, CleanupFn] => {
-                  const [networkRequest, disposeNetworkRequest] =
-                    maybeMakeNetworkRequest(
-                      environment,
-                      entrypoint,
-                      localVariables,
-                      fetchOptions,
-                    );
-
-                  const fragmentReference: FragmentReference<any, any> = {
-                    kind: 'FragmentReference',
-                    readerWithRefetchQueries: wrapResolvedValue({
-                      kind: 'ReaderWithRefetchQueries',
-                      readerArtifact:
-                        entrypoint.readerWithRefetchQueries.readerArtifact,
-                      nestedRefetchQueries:
-                        entrypoint.readerWithRefetchQueries
-                          .nestedRefetchQueries,
-                    } as const),
-
-                    // TODO localVariables is not guaranteed to have an id field
-                    root,
-                    variables: localVariables,
-                    networkRequest,
-                  };
-                  return [fragmentReference, disposeNetworkRequest];
-                };
-
-                if (field.entrypoint.kind === 'Entrypoint') {
-                  return fragmentReferenceAndDisposeFromEntrypoint(
-                    field.entrypoint,
-                  );
-                } else {
-                  const isographArtifactPromiseWrapper =
-                    getOrLoadIsographArtifact(
-                      environment,
-                      field.entrypoint.typeAndField,
-                      field.entrypoint.loader,
-                    );
-                  const state = getPromiseState(isographArtifactPromiseWrapper);
-                  if (state.kind === 'Ok') {
-                    return fragmentReferenceAndDisposeFromEntrypoint(
-                      state.value,
-                    );
-                  } else {
-                    // Promise is pending or thrown
-
-                    let entrypointLoaderState:
-                      | {
-                          kind: 'EntrypointNotLoaded';
-                        }
-                      | {
-                          kind: 'NetworkRequestStarted';
-                          disposeNetworkRequest: CleanupFn;
-                        }
-                      | { kind: 'Disposed' } = { kind: 'EntrypointNotLoaded' };
-
-                    const networkRequest = wrapPromise(
-                      isographArtifactPromiseWrapper.promise.then(
-                        (entrypoint) => {
-                          if (
-                            entrypointLoaderState.kind === 'EntrypointNotLoaded'
-                          ) {
-                            const [networkRequest, disposeNetworkRequest] =
-                              maybeMakeNetworkRequest(
-                                environment,
-                                entrypoint,
-                                localVariables,
-                                fetchOptions,
-                              );
-                            entrypointLoaderState = {
-                              kind: 'NetworkRequestStarted',
-                              disposeNetworkRequest,
-                            };
-                            return networkRequest.promise;
-                          }
-                        },
-                      ),
-                    );
-                    const readerWithRefetchPromise =
-                      isographArtifactPromiseWrapper.promise.then(
-                        (entrypoint) => entrypoint.readerWithRefetchQueries,
-                      );
-
-                    const fragmentReference: FragmentReference<any, any> = {
-                      kind: 'FragmentReference',
-                      readerWithRefetchQueries: wrapPromise(
-                        readerWithRefetchPromise,
-                      ),
-
-                      // TODO localVariables is not guaranteed to have an id field
-                      root,
-                      variables: localVariables,
-                      networkRequest,
-                    };
-
-                    return [
-                      fragmentReference,
-                      () => {
-                        if (
-                          entrypointLoaderState.kind === 'NetworkRequestStarted'
-                        ) {
-                          entrypointLoaderState.disposeNetworkRequest();
-                        }
-                        entrypointLoaderState = { kind: 'Disposed' };
-                      },
-                    ];
-                  }
-                }
-              },
-            ];
-          };
+        if (data.kind === 'MissingData') {
+          return data;
         }
+        target[field.alias] = data.data;
         break;
       }
+
       default: {
         // Ensure we have covered all variants
         let _: never = field;
@@ -616,7 +275,177 @@ function readData<TReadFromStore>(
   return {
     kind: 'Success',
     data: target as any,
-    encounteredRecords: mutableEncounteredRecords,
+  };
+}
+
+export function readLoadablySelectedFieldData(
+  environment: IsographEnvironment,
+  field: LoadablySelectedField,
+  root: StoreLink,
+  variables: Variables,
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  mutableEncounteredRecords: EncounteredIds,
+): ReadDataResult<unknown> {
+  const refetchReaderParams = readData(
+    environment,
+    field.refetchReaderAst,
+    root,
+    variables,
+    // Refetch fields just read the id, and don't need refetch query artifacts
+    [],
+    networkRequest,
+    networkRequestOptions,
+    mutableEncounteredRecords,
+  );
+
+  if (refetchReaderParams.kind === 'MissingData') {
+    return {
+      kind: 'MissingData',
+      reason: 'Missing data for ' + field.alias + ' on root ' + root.__link,
+      nestedReason: refetchReaderParams,
+      recordLink: refetchReaderParams.recordLink,
+    };
+  }
+
+  return {
+    kind: 'Success',
+    data: (
+      args: any,
+      // TODO get the associated type for FetchOptions from the loadably selected field
+      fetchOptions?: FetchOptions<any>,
+    ) => {
+      // TODO we should use the reader AST for this
+      const includeReadOutData = (variables: any, readOutData: any) => {
+        variables.id = readOutData.id;
+        return variables;
+      };
+      const localVariables = includeReadOutData(
+        args ?? {},
+        refetchReaderParams.data,
+      );
+      writeQueryArgsToVariables(
+        localVariables,
+        field.queryArguments,
+        variables,
+      );
+
+      return [
+        // Stable id
+        root.__typename +
+          ':' +
+          root.__link +
+          '/' +
+          field.name +
+          '/' +
+          stableStringifyArgs(localVariables),
+        // Fetcher
+        () => {
+          const fragmentReferenceAndDisposeFromEntrypoint = (
+            entrypoint: IsographEntrypoint<any, any, any>,
+          ): [FragmentReference<any, any>, CleanupFn] => {
+            const readerWithRefetchQueries =
+              entrypoint.readerWithRefetchQueries.kind ===
+              'ReaderWithRefetchQueriesLoader'
+                ? wrapPromise(entrypoint.readerWithRefetchQueries.loader())
+                : wrapResolvedValue(entrypoint.readerWithRefetchQueries);
+            const [networkRequest, disposeNetworkRequest] =
+              maybeMakeNetworkRequest(
+                environment,
+                entrypoint,
+                localVariables,
+                readerWithRefetchQueries,
+                fetchOptions ?? null,
+              );
+
+            const fragmentReference: FragmentReference<any, any> = {
+              kind: 'FragmentReference',
+              readerWithRefetchQueries,
+
+              // TODO localVariables is not guaranteed to have an id field
+              root,
+              variables: localVariables,
+              networkRequest,
+            };
+            return [fragmentReference, disposeNetworkRequest];
+          };
+
+          if (field.entrypoint.kind === 'Entrypoint') {
+            return fragmentReferenceAndDisposeFromEntrypoint(field.entrypoint);
+          } else {
+            const isographArtifactPromiseWrapper = getOrLoadIsographArtifact(
+              environment,
+              field.entrypoint.typeAndField,
+              field.entrypoint.loader,
+            );
+            const state = getPromiseState(isographArtifactPromiseWrapper);
+            if (state.kind === 'Ok') {
+              return fragmentReferenceAndDisposeFromEntrypoint(state.value);
+            } else {
+              // Promise is pending or thrown
+
+              let entrypointLoaderState:
+                | {
+                    kind: 'EntrypointNotLoaded';
+                  }
+                | {
+                    kind: 'NetworkRequestStarted';
+                    disposeNetworkRequest: CleanupFn;
+                  }
+                | { kind: 'Disposed' } = { kind: 'EntrypointNotLoaded' };
+
+              const readerWithRefetchQueries = wrapPromise(
+                isographArtifactPromiseWrapper.promise.then((entrypoint) =>
+                  entrypoint.readerWithRefetchQueries.kind ===
+                  'ReaderWithRefetchQueriesLoader'
+                    ? entrypoint.readerWithRefetchQueries.loader()
+                    : entrypoint.readerWithRefetchQueries,
+                ),
+              );
+              const networkRequest = wrapPromise(
+                isographArtifactPromiseWrapper.promise.then((entrypoint) => {
+                  if (entrypointLoaderState.kind === 'EntrypointNotLoaded') {
+                    const [networkRequest, disposeNetworkRequest] =
+                      maybeMakeNetworkRequest(
+                        environment,
+                        entrypoint,
+                        localVariables,
+                        readerWithRefetchQueries,
+                        fetchOptions ?? null,
+                      );
+                    entrypointLoaderState = {
+                      kind: 'NetworkRequestStarted',
+                      disposeNetworkRequest,
+                    };
+                    return networkRequest.promise;
+                  }
+                }),
+              );
+
+              const fragmentReference: FragmentReference<any, any> = {
+                kind: 'FragmentReference',
+                readerWithRefetchQueries,
+
+                // TODO localVariables is not guaranteed to have an id field
+                root,
+                variables: localVariables,
+                networkRequest,
+              };
+
+              return [
+                fragmentReference,
+                () => {
+                  if (entrypointLoaderState.kind === 'NetworkRequestStarted') {
+                    entrypointLoaderState.disposeNetworkRequest();
+                  }
+                  entrypointLoaderState = { kind: 'Disposed' };
+                },
+              ];
+            }
+          }
+        },
+      ];
+    },
   };
 }
 
@@ -643,7 +472,9 @@ function generateChildVariableMap(
   type Writable<T> = { -readonly [P in keyof T]: T[P] };
   const childVars: Writable<Variables> = {};
   for (const [name, value] of fieldArguments) {
-    if (value.kind === 'Variable') {
+    if (value.kind === 'Object') {
+      childVars[name] = generateChildVariableMap(variables, value.value);
+    } else if (value.kind === 'Variable') {
       const variable = variables[value.name];
       // Variable could be null if it was not provided but has a default case,
       // so we allow the loop to continue rather than throwing an error.
@@ -667,6 +498,14 @@ function writeQueryArgsToVariables(
   }
   for (const [name, argType] of queryArgs) {
     switch (argType.kind) {
+      case 'Object': {
+        writeQueryArgsToVariables(
+          (targetVariables[name] = {}),
+          argType.value,
+          variables,
+        );
+        break;
+      }
       case 'Variable': {
         targetVariables[name] = variables[argType.name];
         break;
@@ -692,6 +531,389 @@ function writeQueryArgsToVariables(
   }
 }
 
+export function readResolverFieldData(
+  environment: IsographEnvironment,
+  field: ReaderNonLoadableResolverField,
+  root: StoreLink,
+  variables: Variables,
+  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  mutableEncounteredRecords: EncounteredIds,
+): ReadDataResult<unknown> {
+  const usedRefetchQueries = field.usedRefetchQueries;
+  const resolverRefetchQueries = usedRefetchQueries.map((index) => {
+    const resolverRefetchQuery = nestedRefetchQueries[index];
+    if (resolverRefetchQuery == null) {
+      throw new Error(
+        'resolverRefetchQuery is null in Resolver. This is indicative of a bug in Isograph.',
+      );
+    }
+    return resolverRefetchQuery;
+  });
+
+  const readerWithRefetchQueries = {
+    kind: 'ReaderWithRefetchQueries',
+    readerArtifact: field.readerArtifact,
+    nestedRefetchQueries: resolverRefetchQueries,
+  } satisfies ReaderWithRefetchQueries<any, any>;
+
+  const fragment = {
+    kind: 'FragmentReference',
+    readerWithRefetchQueries: wrapResolvedValue(readerWithRefetchQueries),
+    root,
+    variables: generateChildVariableMap(variables, field.arguments),
+    networkRequest,
+  } satisfies FragmentReference<any, any>;
+
+  switch (field.readerArtifact.kind) {
+    case 'EagerReaderArtifact': {
+      const data = readData(
+        environment,
+        field.readerArtifact.readerAst,
+        root,
+        generateChildVariableMap(variables, field.arguments),
+        resolverRefetchQueries,
+        networkRequest,
+        networkRequestOptions,
+        mutableEncounteredRecords,
+      );
+      if (data.kind === 'MissingData') {
+        return {
+          kind: 'MissingData',
+          reason: 'Missing data for ' + field.alias + ' on root ' + root.__link,
+          nestedReason: data,
+          recordLink: data.recordLink,
+        };
+      }
+      const firstParameter = {
+        data: data.data,
+        parameters: variables,
+        startUpdate: field.readerArtifact.hasUpdatable
+          ? getOrCreateCachedStartUpdate(
+              environment,
+              fragment,
+              readerWithRefetchQueries.readerArtifact.fieldName,
+              networkRequestOptions,
+            )
+          : undefined,
+      };
+      return {
+        kind: 'Success',
+        data: field.readerArtifact.resolver(firstParameter),
+      };
+    }
+    case 'ComponentReaderArtifact': {
+      return {
+        kind: 'Success',
+        data: getOrCreateCachedComponent(
+          environment,
+          field.readerArtifact.fieldName,
+          fragment,
+          networkRequestOptions,
+        ),
+      };
+    }
+    default: {
+      let _: never = field.readerArtifact;
+      _;
+      throw new Error('Unexpected kind');
+    }
+  }
+}
+
+export function readScalarFieldData(
+  field: ReaderScalarField,
+  storeRecord: StoreRecord,
+  root: StoreLink,
+  variables: Variables,
+): ReadDataResult<
+  string | number | boolean | StoreLink | DataTypeValue[] | null
+> {
+  const storeRecordName = getParentRecordKey(field, variables);
+  const value = storeRecord[storeRecordName];
+  // TODO consider making scalars into discriminated unions. This probably has
+  // to happen for when we handle errors.
+  if (value === undefined) {
+    return {
+      kind: 'MissingData',
+      reason: 'No value for ' + storeRecordName + ' on root ' + root.__link,
+      recordLink: root,
+    };
+  }
+  return { kind: 'Success', data: value };
+}
+
+export function readLinkedFieldData(
+  environment: IsographEnvironment,
+  field: ReaderLinkedField,
+  storeRecord: StoreRecord,
+  root: StoreLink,
+  variables: Variables,
+  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  readData: <TReadFromStore>(
+    ast: ReaderAst<TReadFromStore>,
+    root: StoreLink,
+  ) => ReadDataResult<object>,
+): ReadDataResult<unknown> {
+  const storeRecordName = getParentRecordKey(field, variables);
+  const value = storeRecord[storeRecordName];
+  if (Array.isArray(value)) {
+    const results = [];
+    for (const item of value) {
+      const link = assertLink(item);
+      if (link === undefined) {
+        return {
+          kind: 'MissingData',
+          reason:
+            'No link for ' +
+            storeRecordName +
+            ' on root ' +
+            root.__link +
+            '. Link is ' +
+            JSON.stringify(item),
+          recordLink: root,
+        };
+      } else if (link === null) {
+        results.push(null);
+        continue;
+      }
+
+      const result = readData(field.selections, link);
+      if (result.kind === 'MissingData') {
+        return {
+          kind: 'MissingData',
+          reason:
+            'Missing data for ' +
+            storeRecordName +
+            ' on root ' +
+            root.__link +
+            '. Link is ' +
+            JSON.stringify(item),
+          nestedReason: result,
+          recordLink: result.recordLink,
+        };
+      }
+      results.push(result.data);
+    }
+    return {
+      kind: 'Success',
+      data: results,
+    };
+  }
+  let link = assertLink(value);
+
+  if (field.condition) {
+    const data = readData(field.condition.readerAst, root);
+    if (data.kind === 'MissingData') {
+      return {
+        kind: 'MissingData',
+        reason:
+          'Missing data for ' + storeRecordName + ' on root ' + root.__link,
+        nestedReason: data,
+        recordLink: data.recordLink,
+      };
+    }
+
+    const readerWithRefetchQueries = {
+      kind: 'ReaderWithRefetchQueries',
+      readerArtifact: field.condition,
+      // TODO this is wrong
+      // should map field.condition.usedRefetchQueries
+      // but it doesn't exist
+      nestedRefetchQueries: [],
+    } satisfies ReaderWithRefetchQueries<any, any>;
+
+    const fragment = {
+      kind: 'FragmentReference',
+      readerWithRefetchQueries: wrapResolvedValue(readerWithRefetchQueries),
+      root,
+      variables: generateChildVariableMap(
+        variables,
+        // TODO this is wrong
+        // should use field.arguments
+        // but it doesn't exist
+        [],
+      ),
+      networkRequest,
+    } satisfies FragmentReference<any, any>;
+
+    const condition = field.condition.resolver({
+      data: data.data,
+      parameters: {},
+      ...(field.condition.hasUpdatable
+        ? {
+            startUpdate: getOrCreateCachedStartUpdate(
+              environment,
+              fragment,
+              readerWithRefetchQueries.readerArtifact.fieldName,
+              networkRequestOptions,
+            ),
+          }
+        : undefined),
+    });
+    link = condition;
+  }
+
+  if (link === undefined) {
+    // TODO make this configurable, and also generated and derived from the schema
+    const missingFieldHandler = environment.missingFieldHandler;
+
+    const altLink = missingFieldHandler?.(
+      storeRecord,
+      root,
+      field.fieldName,
+      field.arguments,
+      variables,
+    );
+    logMessage(environment, () => ({
+      kind: 'MissingFieldHandlerCalled',
+      root,
+      storeRecord,
+      fieldName: field.fieldName,
+      arguments: field.arguments,
+      variables,
+    }));
+
+    if (altLink === undefined) {
+      return {
+        kind: 'MissingData',
+        reason:
+          'No link for ' +
+          storeRecordName +
+          ' on root ' +
+          root.__link +
+          '. Link is ' +
+          JSON.stringify(value),
+        recordLink: root,
+      };
+    } else {
+      link = altLink;
+    }
+  } else if (link === null) {
+    return {
+      kind: 'Success',
+      data: null,
+    };
+  }
+  const targetId = link;
+  const { refetchQueryIndex } = field;
+  if (refetchQueryIndex != null) {
+    // if field.refetchQueryIndex is not null, then the field is a client pointer, i.e.
+    // it is like a loadable field that returns the selections.
+    const refetchReaderParams = readData(
+      [
+        {
+          kind: 'Scalar',
+          fieldName: 'id',
+          alias: null,
+          arguments: null,
+          isUpdatable: false,
+        },
+      ],
+      targetId,
+    );
+
+    if (refetchReaderParams.kind === 'MissingData') {
+      return {
+        kind: 'MissingData',
+        reason:
+          'Missing data for ' + field.alias + ' on root ' + targetId.__link,
+        nestedReason: refetchReaderParams,
+        recordLink: refetchReaderParams.recordLink,
+      };
+    }
+
+    const refetchQuery = nestedRefetchQueries[refetchQueryIndex];
+    if (refetchQuery == null) {
+      throw new Error(
+        'refetchQuery is null in RefetchField. This is indicative of a bug in Isograph.',
+      );
+    }
+    const refetchQueryArtifact = refetchQuery.artifact;
+    const allowedVariables = refetchQuery.allowedVariables;
+
+    return {
+      kind: 'Success',
+      data: (
+        args: any,
+        // TODO get the associated type for FetchOptions from the loadably selected field
+        fetchOptions?: FetchOptions<any>,
+      ) => {
+        const includeReadOutData = (variables: any, readOutData: any) => {
+          variables.id = readOutData.id;
+          return variables;
+        };
+        const localVariables = includeReadOutData(
+          args ?? {},
+          refetchReaderParams.data,
+        );
+        writeQueryArgsToVariables(localVariables, field.arguments, variables);
+
+        return [
+          // Stable id
+          targetId.__typename +
+            ':' +
+            targetId.__link +
+            '/' +
+            field.fieldName +
+            '/' +
+            stableStringifyArgs(localVariables),
+          // Fetcher
+          (): ItemCleanupPair<FragmentReference<any, any>> | undefined => {
+            const variables = includeReadOutData(
+              filterVariables({ ...args, ...localVariables }, allowedVariables),
+              refetchReaderParams.data,
+            );
+
+            const readerWithRefetchQueries = wrapResolvedValue({
+              kind: 'ReaderWithRefetchQueries',
+              readerArtifact: {
+                kind: 'EagerReaderArtifact',
+                fieldName: field.fieldName,
+                readerAst: field.selections,
+                resolver: ({ data }: { data: any }) => data,
+                hasUpdatable: false,
+              },
+              nestedRefetchQueries,
+            } as const);
+
+            const [networkRequest, disposeNetworkRequest] =
+              maybeMakeNetworkRequest(
+                environment,
+                refetchQueryArtifact,
+                variables,
+                readerWithRefetchQueries,
+                fetchOptions ?? null,
+              );
+
+            const fragmentReference: FragmentReference<any, any> = {
+              kind: 'FragmentReference',
+              readerWithRefetchQueries: readerWithRefetchQueries,
+              root: targetId,
+              variables,
+              networkRequest,
+            };
+            return [fragmentReference, disposeNetworkRequest];
+          },
+        ];
+      },
+    };
+  }
+  const data = readData(field.selections, targetId);
+  if (data.kind === 'MissingData') {
+    return {
+      kind: 'MissingData',
+      reason: 'Missing data for ' + storeRecordName + ' on root ' + root.__link,
+      nestedReason: data,
+      recordLink: data.recordLink,
+    };
+  }
+  return data;
+}
+
 export type NetworkRequestReaderOptions = {
   suspendIfInFlight: boolean;
   throwOnNetworkError: boolean;
@@ -720,3 +942,69 @@ function stableStringifyArgs(args: object) {
   }
   return s;
 }
+
+export function readImperativelyLoadedField(
+  environment: IsographEnvironment,
+  field: ReaderImperativelyLoadedField,
+  root: StoreLink,
+  variables: Variables,
+  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  mutableEncounteredRecords: EncounteredIds,
+): ReadDataResult<unknown> {
+  // First, we read the data using the refetch reader AST (i.e. read out the
+  // id field).
+  const data = readData(
+    environment,
+    field.refetchReaderArtifact.readerAst,
+    root,
+    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') {
+    return {
+      kind: 'MissingData',
+      reason: 'Missing data for ' + field.alias + ' on root ' + root.__link,
+      nestedReason: data,
+      recordLink: data.recordLink,
+    };
+  } else {
+    const { refetchQueryIndex } = field;
+    const refetchQuery = nestedRefetchQueries[refetchQueryIndex];
+    if (refetchQuery == null) {
+      throw new Error(
+        'Refetch query not found. This is indicative of a bug in Isograph.',
+      );
+    }
+    const refetchQueryArtifact = refetchQuery.artifact;
+    const allowedVariables = refetchQuery.allowedVariables;
+
+    // Second, we allow the user to call the resolver, which will ultimately
+    // use the resolver reader AST to get the resolver parameters.
+    return {
+      kind: 'Success',
+      data: (args: any) => [
+        // Stable id
+        root.__typename + ':' + root.__link + '__' + field.name,
+        // Fetcher
+        field.refetchReaderArtifact.resolver(
+          environment,
+          refetchQueryArtifact,
+          data.data,
+          filterVariables({ ...args, ...variables }, allowedVariables),
+          root,
+          // TODO these params should be removed
+          null,
+          [],
+        ),
+      ],
+    };
+  }
+}