@isograph/react 0.0.0-main-adb0955b → 0.0.0-main-1ed9144e

package/dist/core/cache.d.ts

@@ -4,6 +4,7 @@ import { IsographEntrypoint, NormalizationAst, NormalizationLinkedField, Normali
 import { ReaderLinkedField, ReaderScalarField, type ReaderAst } from './reader';
 import { WithEncounteredRecords } from './read';
 import { FragmentReference, Variables, ExtractParameters } from './FragmentReference';
+import { FetchOptions } from './check';
 export declare function getOrCreateItemInSuspenseCache<TReadFromStore extends {
     parameters: object;
     data: object;
@@ -17,7 +18,7 @@ export declare function stableCopy<T>(value: T): T;
 export declare function getOrCreateCacheForArtifact<TReadFromStore extends {
     parameters: object;
     data: object;
-}, TClientFieldValue>(environment: IsographEnvironment, entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>>;
+}, TClientFieldValue>(environment: IsographEnvironment, entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>, options?: FetchOptions): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>>;
 type NetworkResponseScalarValue = string | number | boolean;
 type NetworkResponseValue = NetworkResponseScalarValue | null | NetworkResponseObject | NetworkResponseObject[] | NetworkResponseScalarValue[];
 export type NetworkResponseObject = {

package/dist/core/cache.js

@@ -17,6 +17,7 @@ const areEqualWithDeepComparison_1 = require("./areEqualWithDeepComparison");
 const makeNetworkRequest_1 = require("./makeNetworkRequest");
 const PromiseWrapper_1 = require("./PromiseWrapper");
 const logging_1 = require("./logging");
+const check_1 = require("./check");
 const TYPENAME_FIELD_NAME = '__typename';
 function getOrCreateItemInSuspenseCache(environment, index, factory) {
     // TODO this is probably a useless message, we should remove it
@@ -52,10 +53,12 @@ function stableCopy(value) {
     }
     return stable;
 }
-function getOrCreateCacheForArtifact(environment, entrypoint, variables) {
+function getOrCreateCacheForArtifact(environment, entrypoint, variables, options) {
     const cacheKey = entrypoint.queryText + JSON.stringify(stableCopy(variables));
     const factory = () => {
-        const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.makeNetworkRequest)(environment, entrypoint, variables);
+        var _a;
+        const fetchPolicy = (_a = options === null || options === void 0 ? void 0 : options.fetchPolicy) !== null && _a !== void 0 ? _a : check_1.DEFAULT_FETCH_POLICY;
+        const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, variables, fetchPolicy);
         const itemCleanupPair = [
             {
                 kind: 'FragmentReference',

package/dist/core/check.d.ts

@@ -0,0 +1,15 @@
+import { NormalizationAst } from './entrypoint';
+import { Variables } from './FragmentReference';
+import { IsographEnvironment, Link } from './IsographEnvironment';
+export type FetchPolicy = 'Yes' | 'No' | 'IfNecessary';
+export declare const DEFAULT_FETCH_POLICY: FetchPolicy;
+export type FetchOptions = {
+    fetchPolicy?: FetchPolicy;
+};
+export type CheckResult = {
+    kind: 'EnoughData';
+} | {
+    kind: 'MissingData';
+    record: Link;
+};
+export declare function check(environment: IsographEnvironment, normalizationAst: NormalizationAst, variables: Variables): CheckResult;

package/dist/core/check.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FETCH_POLICY = void 0;
+exports.check = check;
+const cache_1 = require("./cache");
+const IsographEnvironment_1 = require("./IsographEnvironment");
+const logging_1 = require("./logging");
+exports.DEFAULT_FETCH_POLICY = 'IfNecessary';
+function check(environment, normalizationAst, variables) {
+    const checkResult = checkFromRecord(environment, normalizationAst, variables, environment.store[IsographEnvironment_1.ROOT_ID], IsographEnvironment_1.ROOT_ID);
+    (0, logging_1.logMessage)(environment, {
+        kind: 'EnvironmentCheck',
+        result: checkResult,
+    });
+    return checkResult;
+}
+function checkFromRecord(environment, normalizationAst, variables, record, backupId) {
+    var _a, _b, _c;
+    normalizationAstLoop: for (const normalizationAstNode of normalizationAst) {
+        switch (normalizationAstNode.kind) {
+            case 'Scalar': {
+                const parentRecordKey = (0, cache_1.getParentRecordKey)(normalizationAstNode, variables);
+                const scalarValue = record[parentRecordKey];
+                // null means the value is known to be missing, so it must
+                // be exactly undefined
+                if (scalarValue === undefined) {
+                    return {
+                        kind: 'MissingData',
+                        record: {
+                            __link: (_a = record.id) !== null && _a !== void 0 ? _a : backupId,
+                        },
+                    };
+                }
+                continue normalizationAstLoop;
+            }
+            case 'Linked': {
+                const parentRecordKey = (0, cache_1.getParentRecordKey)(normalizationAstNode, variables);
+                const linkedValue = record[parentRecordKey];
+                if (linkedValue === undefined) {
+                    return {
+                        kind: 'MissingData',
+                        record: {
+                            __link: (_b = record.id) !== null && _b !== void 0 ? _b : backupId,
+                        },
+                    };
+                }
+                else if (linkedValue === null) {
+                    continue;
+                }
+                else if (Array.isArray(linkedValue)) {
+                    arrayItemsLoop: for (const item of linkedValue) {
+                        const link = (0, IsographEnvironment_1.getLink)(item);
+                        if (link === null) {
+                            throw new Error('Unexpected non-link in the Isograph store. ' +
+                                'This is indicative of a bug in Isograph.');
+                        }
+                        const linkedRecord = environment.store[link.__link];
+                        if (linkedRecord === undefined) {
+                            return {
+                                kind: 'MissingData',
+                                record: link,
+                            };
+                        }
+                        else if (linkedRecord === null) {
+                            continue arrayItemsLoop;
+                        }
+                        else {
+                            // TODO in __DEV__ assert linkedRecord is an object
+                            const result = checkFromRecord(environment, normalizationAstNode.selections, variables, linkedRecord, 
+                            // TODO this seems likely to be wrong
+                            backupId + '.' + parentRecordKey);
+                            if (result.kind === 'MissingData') {
+                                return result;
+                            }
+                        }
+                    }
+                }
+                else {
+                    const link = (0, IsographEnvironment_1.getLink)(linkedValue);
+                    if (link === null) {
+                        throw new Error('Unexpected non-link in the Isograph store. ' +
+                            'This is indicative of a bug in Isograph.');
+                    }
+                    const linkedRecord = environment.store[link.__link];
+                    if (linkedRecord === undefined) {
+                        return {
+                            kind: 'MissingData',
+                            record: link,
+                        };
+                    }
+                    else if (linkedRecord === null) {
+                        continue normalizationAstLoop;
+                    }
+                    else {
+                        // TODO in __DEV__ assert linkedRecord is an object
+                        const result = checkFromRecord(environment, normalizationAstNode.selections, variables, linkedRecord, 
+                        // TODO this seems likely to be wrong
+                        backupId + '.' + parentRecordKey);
+                        if (result.kind === 'MissingData') {
+                            return result;
+                        }
+                    }
+                }
+                continue normalizationAstLoop;
+            }
+            case 'InlineFragment': {
+                const existingRecordTypename = record['__typename'];
+                if (existingRecordTypename == null ||
+                    existingRecordTypename !== normalizationAstNode.type) {
+                    return {
+                        kind: 'MissingData',
+                        record: {
+                            __link: (_c = record.id) !== null && _c !== void 0 ? _c : backupId,
+                        },
+                    };
+                }
+                const result = checkFromRecord(environment, normalizationAstNode.selections, variables, record, backupId);
+                if (result.kind === 'MissingData') {
+                    return result;
+                }
+                continue normalizationAstLoop;
+            }
+            default: {
+                let _ = normalizationAstNode;
+                _;
+                throw new Error('Unexpected case. This is indicative of a bug in Isograph.');
+            }
+        }
+    }
+    return {
+        kind: 'EnoughData',
+    };
+}

package/dist/core/logging.d.ts

@@ -5,6 +5,7 @@ import { FragmentReference, Variables } from './FragmentReference';
 import { NetworkResponseObject } from './cache';
 import { Arguments } from './util';
 import { ReadDataResult } from './read';
+import { CheckResult } from './check';
 export type LogMessage = {
     kind: 'GettingSuspenseCacheItem';
     index: string;
@@ -51,6 +52,9 @@ export type LogMessage = {
 } | {
     kind: 'NonEntrypointReceived';
     entrypoint: any;
+} | {
+    kind: 'EnvironmentCheck';
+    result: CheckResult;
 };
 export type LogFunction = (logMessage: LogMessage) => void;
 export type WrappedLogFunction = {

package/dist/core/makeNetworkRequest.d.ts

@@ -3,4 +3,6 @@ import { IsographEntrypoint, RefetchQueryNormalizationArtifact } from './entrypo
 import { Variables } from './FragmentReference';
 import { IsographEnvironment } from './IsographEnvironment';
 import { AnyError, PromiseWrapper } from './PromiseWrapper';
+import { FetchPolicy } from './check';
+export declare function maybeMakeNetworkRequest(environment: IsographEnvironment, artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>, variables: Variables, fetchPolicy: FetchPolicy): ItemCleanupPair<PromiseWrapper<void, AnyError>>;
 export declare function makeNetworkRequest(environment: IsographEnvironment, artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>, variables: Variables): ItemCleanupPair<PromiseWrapper<void, AnyError>>;

package/dist/core/makeNetworkRequest.js

@@ -1,11 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeMakeNetworkRequest = maybeMakeNetworkRequest;
 exports.makeNetworkRequest = makeNetworkRequest;
 const garbageCollection_1 = require("./garbageCollection");
 const PromiseWrapper_1 = require("./PromiseWrapper");
 const cache_1 = require("./cache");
 const logging_1 = require("./logging");
+const check_1 = require("./check");
 let networkRequestId = 0;
+function maybeMakeNetworkRequest(environment, artifact, variables, fetchPolicy) {
+    switch (fetchPolicy) {
+        case 'Yes': {
+            return makeNetworkRequest(environment, artifact, variables);
+        }
+        case 'No': {
+            return [(0, PromiseWrapper_1.wrapResolvedValue)(undefined), () => { }];
+        }
+        case 'IfNecessary': {
+            const result = (0, check_1.check)(environment, artifact.normalizationAst, variables);
+            if (result.kind === 'EnoughData') {
+                return [(0, PromiseWrapper_1.wrapResolvedValue)(undefined), () => { }];
+            }
+            else {
+                return makeNetworkRequest(environment, artifact, variables);
+            }
+        }
+    }
+}
 function makeNetworkRequest(environment, artifact, variables) {
     // TODO this should be a DataId and stored in the store
     const myNetworkRequestId = networkRequestId + '';

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { readButDoNotEvaluate } from './core/read';
 export { type ExtractSecondParam, type CombineWithIntrinsicAttributes, type Argument, type ArgumentName, type ArgumentValue, type Arguments, } from './core/util';
 export { type FragmentReference, type Variables, type ExtractParameters, type ExtractData, stableIdForFragmentReference, } from './core/FragmentReference';
 export { type LogMessage, type LogFunction, logMessage, registerLogger, } from './core/logging';
+export { check, CheckResult, FetchOptions, FetchPolicy } from './core/check';
 export { IsographEnvironmentProvider, useIsographEnvironment, type IsographEnvironmentProviderProps, } from './react/IsographEnvironmentProvider';
 export { useImperativeReference } from './react/useImperativeReference';
 export { FragmentReader } from './react/FragmentReader';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useImperativeLoadableField = exports.useConnectionSpecPagination = exports.useSkipLimitPagination = exports.useImperativeExposedMutationField = exports.useClientSideDefer = exports.RenderAfterCommit__DO_NOT_USE = exports.useRerenderOnChange = exports.useLazyReference = exports.useSubscribeToMultiple = exports.useReadAndSubscribe = exports.useResult = exports.FragmentReader = exports.useImperativeReference = exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.registerLogger = exports.logMessage = exports.stableIdForFragmentReference = exports.readButDoNotEvaluate = exports.assertIsEntrypoint = exports.defaultMissingFieldHandler = exports.createIsographStore = exports.createIsographEnvironment = exports.ROOT_ID = exports.makeNetworkRequest = exports.normalizeData = exports.subscribe = exports.wrapPromise = exports.wrapResolvedValue = exports.getPromiseState = exports.readPromise = exports.garbageCollectEnvironment = exports.unretainQuery = exports.retainQuery = void 0;
+exports.useImperativeLoadableField = exports.useConnectionSpecPagination = exports.useSkipLimitPagination = exports.useImperativeExposedMutationField = exports.useClientSideDefer = exports.RenderAfterCommit__DO_NOT_USE = exports.useRerenderOnChange = exports.useLazyReference = exports.useSubscribeToMultiple = exports.useReadAndSubscribe = exports.useResult = exports.FragmentReader = exports.useImperativeReference = exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.check = exports.registerLogger = exports.logMessage = exports.stableIdForFragmentReference = exports.readButDoNotEvaluate = exports.assertIsEntrypoint = exports.defaultMissingFieldHandler = exports.createIsographStore = exports.createIsographEnvironment = exports.ROOT_ID = exports.makeNetworkRequest = exports.normalizeData = exports.subscribe = exports.wrapPromise = exports.wrapResolvedValue = exports.getPromiseState = exports.readPromise = exports.garbageCollectEnvironment = exports.unretainQuery = exports.retainQuery = void 0;
 var garbageCollection_1 = require("./core/garbageCollection");
 Object.defineProperty(exports, "retainQuery", { enumerable: true, get: function () { return garbageCollection_1.retainQuery; } });
 Object.defineProperty(exports, "unretainQuery", { enumerable: true, get: function () { return garbageCollection_1.unretainQuery; } });
@@ -29,6 +29,8 @@ Object.defineProperty(exports, "stableIdForFragmentReference", { enumerable: tru
 var logging_1 = require("./core/logging");
 Object.defineProperty(exports, "logMessage", { enumerable: true, get: function () { return logging_1.logMessage; } });
 Object.defineProperty(exports, "registerLogger", { enumerable: true, get: function () { return logging_1.registerLogger; } });
+var check_1 = require("./core/check");
+Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_1.check; } });
 var IsographEnvironmentProvider_1 = require("./react/IsographEnvironmentProvider");
 Object.defineProperty(exports, "IsographEnvironmentProvider", { enumerable: true, get: function () { return IsographEnvironmentProvider_1.IsographEnvironmentProvider; } });
 Object.defineProperty(exports, "useIsographEnvironment", { enumerable: true, get: function () { return IsographEnvironmentProvider_1.useIsographEnvironment; } });

package/dist/react/useImperativeReference.d.ts

@@ -1,10 +1,11 @@
 import { UnassignedState } from '@isograph/react-disposable-state';
 import { IsographEntrypoint } from '../core/entrypoint';
 import { FragmentReference, ExtractParameters } from '../core/FragmentReference';
+import { FetchOptions } from '../core/check';
 export declare function useImperativeReference<TReadFromStore extends {
     parameters: object;
     data: object;
 }, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>): {
     fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue> | UnassignedState;
-    loadFragmentReference: (variables: ExtractParameters<TReadFromStore>) => void;
+    loadFragmentReference: (variables: ExtractParameters<TReadFromStore>, options?: FetchOptions) => void;
 };

package/dist/react/useImperativeReference.js

@@ -6,14 +6,17 @@ const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
 const IsographEnvironment_1 = require("../core/IsographEnvironment");
 const makeNetworkRequest_1 = require("../core/makeNetworkRequest");
 const PromiseWrapper_1 = require("../core/PromiseWrapper");
+const check_1 = require("../core/check");
 // TODO rename this to useImperativelyLoadedEntrypoint
 function useImperativeReference(entrypoint) {
     const { state, setState } = (0, react_disposable_state_1.useUpdatableDisposableState)();
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
     return {
         fragmentReference: state,
-        loadFragmentReference: (variables) => {
-            const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.makeNetworkRequest)(environment, entrypoint, variables);
+        loadFragmentReference: (variables, options) => {
+            var _a;
+            const fetchPolicy = (_a = options === null || options === void 0 ? void 0 : options.fetchPolicy) !== null && _a !== void 0 ? _a : check_1.DEFAULT_FETCH_POLICY;
+            const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, variables, fetchPolicy);
             setState([
                 {
                     kind: 'FragmentReference',

package/dist/react/useLazyReference.d.ts

@@ -1,8 +1,9 @@
 import { FragmentReference, ExtractParameters } from '../core/FragmentReference';
 import { IsographEntrypoint } from '../core/entrypoint';
+import { FetchOptions } from '../core/check';
 export declare function useLazyReference<TReadFromStore extends {
     parameters: object;
     data: object;
-}, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>): {
+}, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>, options?: FetchOptions): {
     fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
 };

package/dist/react/useLazyReference.js

@@ -5,7 +5,7 @@ const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
 const cache_1 = require("../core/cache");
 const react_disposable_state_1 = require("@isograph/react-disposable-state");
 const logging_1 = require("../core/logging");
-function useLazyReference(entrypoint, variables) {
+function useLazyReference(entrypoint, variables, options) {
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
     if ((entrypoint === null || entrypoint === void 0 ? void 0 : entrypoint.kind) !== 'Entrypoint') {
         // TODO have a separate error logger
@@ -14,7 +14,7 @@ function useLazyReference(entrypoint, variables) {
             entrypoint,
         });
     }
-    const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables);
+    const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables, options);
     return {
         fragmentReference: (0, react_disposable_state_1.useLazyDisposableState)(cache).state,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.0.0-main-adb0955b",
+  "version": "0.0.0-main-1ed9144e",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -17,9 +17,9 @@
     "tsc": "tsc"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-adb0955b",
-    "@isograph/react-disposable-state": "0.0.0-main-adb0955b",
-    "@isograph/reference-counted-pointer": "0.0.0-main-adb0955b"
+    "@isograph/disposable-types": "0.0.0-main-1ed9144e",
+    "@isograph/react-disposable-state": "0.0.0-main-1ed9144e",
+    "@isograph/reference-counted-pointer": "0.0.0-main-1ed9144e"
   },
   "peerDependencies": {
     "react": "18.3.1"

package/src/core/cache.ts

@@ -30,9 +30,10 @@ import {
   ExtractParameters,
 } from './FragmentReference';
 import { mergeObjectsUsingReaderAst } from './areEqualWithDeepComparison';
-import { makeNetworkRequest } from './makeNetworkRequest';
+import { maybeMakeNetworkRequest } from './makeNetworkRequest';
 import { wrapResolvedValue } from './PromiseWrapper';
 import { logMessage } from './logging';
+import { DEFAULT_FETCH_POLICY, FetchOptions } from './check';
 
 const TYPENAME_FIELD_NAME = '__typename';
 
@@ -87,14 +88,18 @@ export function getOrCreateCacheForArtifact<
   environment: IsographEnvironment,
   entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
   variables: ExtractParameters<TReadFromStore>,
+  options?: FetchOptions,
 ): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
   const cacheKey = entrypoint.queryText + JSON.stringify(stableCopy(variables));
   const factory = () => {
-    const [networkRequest, disposeNetworkRequest] = makeNetworkRequest(
+    const fetchPolicy = options?.fetchPolicy ?? DEFAULT_FETCH_POLICY;
+    const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
       environment,
       entrypoint,
       variables,
+      fetchPolicy,
     );
+
     const itemCleanupPair: ItemCleanupPair<
       FragmentReference<TReadFromStore, TClientFieldValue>
     > = [

package/src/core/check.ts

@@ -0,0 +1,208 @@
+import { getParentRecordKey } from './cache';
+import { NormalizationAst } from './entrypoint';
+import { Variables } from './FragmentReference';
+import {
+  getLink,
+  IsographEnvironment,
+  Link,
+  ROOT_ID,
+  StoreRecord,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
+
+export type FetchPolicy = 'Yes' | 'No' | 'IfNecessary';
+
+export const DEFAULT_FETCH_POLICY: FetchPolicy = 'IfNecessary';
+
+export type FetchOptions = {
+  fetchPolicy?: FetchPolicy;
+};
+
+export type CheckResult =
+  | {
+      kind: 'EnoughData';
+    }
+  | {
+      kind: 'MissingData';
+      record: Link;
+    };
+
+export function check(
+  environment: IsographEnvironment,
+  normalizationAst: NormalizationAst,
+  variables: Variables,
+): CheckResult {
+  const checkResult = checkFromRecord(
+    environment,
+    normalizationAst,
+    variables,
+    environment.store[ROOT_ID],
+    ROOT_ID,
+  );
+  logMessage(environment, {
+    kind: 'EnvironmentCheck',
+    result: checkResult,
+  });
+  return checkResult;
+}
+
+function checkFromRecord(
+  environment: IsographEnvironment,
+  normalizationAst: NormalizationAst,
+  variables: Variables,
+  record: StoreRecord,
+  backupId: string,
+): CheckResult {
+  normalizationAstLoop: for (const normalizationAstNode of normalizationAst) {
+    switch (normalizationAstNode.kind) {
+      case 'Scalar': {
+        const parentRecordKey = getParentRecordKey(
+          normalizationAstNode,
+          variables,
+        );
+        const scalarValue = record[parentRecordKey];
+
+        // null means the value is known to be missing, so it must
+        // be exactly undefined
+        if (scalarValue === undefined) {
+          return {
+            kind: 'MissingData',
+            record: {
+              __link: record.id ?? backupId,
+            },
+          };
+        }
+        continue normalizationAstLoop;
+      }
+      case 'Linked': {
+        const parentRecordKey = getParentRecordKey(
+          normalizationAstNode,
+          variables,
+        );
+
+        const linkedValue = record[parentRecordKey];
+
+        if (linkedValue === undefined) {
+          return {
+            kind: 'MissingData',
+            record: {
+              __link: record.id ?? backupId,
+            },
+          };
+        } else if (linkedValue === null) {
+          continue;
+        } else if (Array.isArray(linkedValue)) {
+          arrayItemsLoop: for (const item of linkedValue) {
+            const link = getLink(item);
+            if (link === null) {
+              throw new Error(
+                'Unexpected non-link in the Isograph store. ' +
+                  'This is indicative of a bug in Isograph.',
+              );
+            }
+
+            const linkedRecord = environment.store[link.__link];
+
+            if (linkedRecord === undefined) {
+              return {
+                kind: 'MissingData',
+                record: link,
+              };
+            } else if (linkedRecord === null) {
+              continue arrayItemsLoop;
+            } else {
+              // TODO in __DEV__ assert linkedRecord is an object
+              const result = checkFromRecord(
+                environment,
+                normalizationAstNode.selections,
+                variables,
+                linkedRecord,
+                // TODO this seems likely to be wrong
+                backupId + '.' + parentRecordKey,
+              );
+
+              if (result.kind === 'MissingData') {
+                return result;
+              }
+            }
+          }
+        } else {
+          const link = getLink(linkedValue);
+          if (link === null) {
+            throw new Error(
+              'Unexpected non-link in the Isograph store. ' +
+                'This is indicative of a bug in Isograph.',
+            );
+          }
+
+          const linkedRecord = environment.store[link.__link];
+
+          if (linkedRecord === undefined) {
+            return {
+              kind: 'MissingData',
+              record: link,
+            };
+          } else if (linkedRecord === null) {
+            continue normalizationAstLoop;
+          } else {
+            // TODO in __DEV__ assert linkedRecord is an object
+            const result = checkFromRecord(
+              environment,
+              normalizationAstNode.selections,
+              variables,
+              linkedRecord,
+              // TODO this seems likely to be wrong
+              backupId + '.' + parentRecordKey,
+            );
+
+            if (result.kind === 'MissingData') {
+              return result;
+            }
+          }
+        }
+
+        continue normalizationAstLoop;
+      }
+      case 'InlineFragment': {
+        const existingRecordTypename = record['__typename'];
+
+        if (
+          existingRecordTypename == null ||
+          existingRecordTypename !== normalizationAstNode.type
+        ) {
+          return {
+            kind: 'MissingData',
+            record: {
+              __link: record.id ?? backupId,
+            },
+          };
+        }
+
+        const result = checkFromRecord(
+          environment,
+          normalizationAstNode.selections,
+          variables,
+          record,
+          backupId,
+        );
+
+        if (result.kind === 'MissingData') {
+          return result;
+        }
+
+        continue normalizationAstLoop;
+      }
+      default: {
+        let _: never = normalizationAstNode;
+        _;
+        throw new Error(
+          'Unexpected case. This is indicative of a bug in Isograph.',
+        );
+      }
+    }
+  }
+
+  return {
+    kind: 'EnoughData',
+  };
+}

package/src/core/logging.ts

@@ -14,6 +14,7 @@ import { FragmentReference, Variables } from './FragmentReference';
 import { NetworkResponseObject } from './cache';
 import { Arguments } from './util';
 import { ReadDataResult } from './read';
+import { CheckResult } from './check';
 
 export type LogMessage =
   | {
@@ -74,6 +75,10 @@ export type LogMessage =
   | {
       kind: 'NonEntrypointReceived';
       entrypoint: any;
+    }
+  | {
+      kind: 'EnvironmentCheck';
+      result: CheckResult;
     };
 
 export type LogFunction = (logMessage: LogMessage) => void;

package/src/core/makeNetworkRequest.ts

@@ -11,12 +11,42 @@ import {
   unretainQuery,
 } from './garbageCollection';
 import { IsographEnvironment } from './IsographEnvironment';
-import { AnyError, PromiseWrapper, wrapPromise } from './PromiseWrapper';
+import {
+  AnyError,
+  PromiseWrapper,
+  wrapPromise,
+  wrapResolvedValue,
+} from './PromiseWrapper';
 import { normalizeData } from './cache';
 import { logMessage } from './logging';
+import { check, FetchPolicy } from './check';
 
 let networkRequestId = 0;
 
+export function maybeMakeNetworkRequest(
+  environment: IsographEnvironment,
+  artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>,
+  variables: Variables,
+  fetchPolicy: FetchPolicy,
+): ItemCleanupPair<PromiseWrapper<void, AnyError>> {
+  switch (fetchPolicy) {
+    case 'Yes': {
+      return makeNetworkRequest(environment, artifact, variables);
+    }
+    case 'No': {
+      return [wrapResolvedValue(undefined), () => {}];
+    }
+    case 'IfNecessary': {
+      const result = check(environment, artifact.normalizationAst, variables);
+      if (result.kind === 'EnoughData') {
+        return [wrapResolvedValue(undefined), () => {}];
+      } else {
+        return makeNetworkRequest(environment, artifact, variables);
+      }
+    }
+  }
+}
+
 export function makeNetworkRequest(
   environment: IsographEnvironment,
   artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>,

package/src/core/read.ts

@@ -1,4 +1,3 @@
-import { CleanupFn } from '@isograph/isograph-disposable-types/dist';
 import { getParentRecordKey, onNextChangeToRecord } from './cache';
 import { getOrCreateCachedComponent } from './componentCache';
 import {
@@ -30,6 +29,7 @@ import {
 import { ReaderAst } from './reader';
 import { Arguments } from './util';
 import { logMessage } from './logging';
+import { CleanupFn } from '@isograph/disposable-types';
 
 export type WithEncounteredRecords<T> = {
   readonly encounteredRecords: Set<DataId>;

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   logMessage,
   registerLogger,
 } from './core/logging';
+export { check, CheckResult, FetchOptions, FetchPolicy } from './core/check';
 
 export {
   IsographEnvironmentProvider,

package/src/react/useImperativeReference.ts

@@ -9,8 +9,9 @@ import {
 } from '../core/FragmentReference';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { ROOT_ID } from '../core/IsographEnvironment';
-import { makeNetworkRequest } from '../core/makeNetworkRequest';
+import { maybeMakeNetworkRequest } from '../core/makeNetworkRequest';
 import { wrapResolvedValue } from '../core/PromiseWrapper';
+import { DEFAULT_FETCH_POLICY, FetchOptions } from '../core/check';
 
 // TODO rename this to useImperativelyLoadedEntrypoint
 
@@ -23,7 +24,10 @@ export function useImperativeReference<
   fragmentReference:
     | FragmentReference<TReadFromStore, TClientFieldValue>
     | UnassignedState;
-  loadFragmentReference: (variables: ExtractParameters<TReadFromStore>) => void;
+  loadFragmentReference: (
+    variables: ExtractParameters<TReadFromStore>,
+    options?: FetchOptions,
+  ) => void;
 } {
   const { state, setState } =
     useUpdatableDisposableState<
@@ -32,11 +36,16 @@ export function useImperativeReference<
   const environment = useIsographEnvironment();
   return {
     fragmentReference: state,
-    loadFragmentReference: (variables: ExtractParameters<TReadFromStore>) => {
-      const [networkRequest, disposeNetworkRequest] = makeNetworkRequest(
+    loadFragmentReference: (
+      variables: ExtractParameters<TReadFromStore>,
+      options?: FetchOptions,
+    ) => {
+      const fetchPolicy = options?.fetchPolicy ?? DEFAULT_FETCH_POLICY;
+      const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
         environment,
         entrypoint,
         variables,
+        fetchPolicy,
       );
       setState([
         {

package/src/react/useLazyReference.ts

@@ -7,6 +7,7 @@ import { IsographEntrypoint } from '../core/entrypoint';
 import { getOrCreateCacheForArtifact } from '../core/cache';
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
 import { logMessage } from '../core/logging';
+import { FetchOptions } from '../core/check';
 
 export function useLazyReference<
   TReadFromStore extends { parameters: object; data: object },
@@ -14,6 +15,7 @@ export function useLazyReference<
 >(
   entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
   variables: ExtractParameters<TReadFromStore>,
+  options?: FetchOptions,
 ): {
   fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
 } {
@@ -27,7 +29,12 @@ export function useLazyReference<
     });
   }
 
-  const cache = getOrCreateCacheForArtifact(environment, entrypoint, variables);
+  const cache = getOrCreateCacheForArtifact(
+    environment,
+    entrypoint,
+    variables,
+    options,
+  );
 
   return {
     fragmentReference: useLazyDisposableState(cache).state,