@isograph/react 0.0.0-main-6ea7b362 → 0.0.0-main-cd6f81ae

package/dist/core/cache.d.ts

@@ -18,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>, options?: FetchOptions): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>>;
+}, TClientFieldValue>(environment: IsographEnvironment, entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>, fetchOptions?: 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

@@ -53,12 +53,12 @@ function stableCopy(value) {
     }
     return stable;
 }
-function getOrCreateCacheForArtifact(environment, entrypoint, variables, options) {
+function getOrCreateCacheForArtifact(environment, entrypoint, variables, fetchOptions) {
     const cacheKey = entrypoint.queryText + JSON.stringify(stableCopy(variables));
     const factory = () => {
         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 shouldFetch = (_a = fetchOptions === null || fetchOptions === void 0 ? void 0 : fetchOptions.shouldFetch) !== null && _a !== void 0 ? _a : check_1.DEFAULT_SHOULD_FETCH_VALUE;
+        const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, variables, shouldFetch);
         const itemCleanupPair = [
             {
                 kind: 'FragmentReference',

package/dist/core/check.d.ts

@@ -1,10 +1,10 @@
 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 ShouldFetch = 'Yes' | 'No' | 'IfNecessary';
+export declare const DEFAULT_SHOULD_FETCH_VALUE: ShouldFetch;
 export type FetchOptions = {
-    fetchPolicy?: FetchPolicy;
+    shouldFetch?: ShouldFetch;
 };
 export type CheckResult = {
     kind: 'EnoughData';

package/dist/core/check.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_FETCH_POLICY = void 0;
+exports.DEFAULT_SHOULD_FETCH_VALUE = 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';
+exports.DEFAULT_SHOULD_FETCH_VALUE = 'IfNecessary';
 function check(environment, normalizationAst, variables) {
     const checkResult = checkFromRecord(environment, normalizationAst, variables, environment.store[IsographEnvironment_1.ROOT_ID], { __link: IsographEnvironment_1.ROOT_ID });
     (0, logging_1.logMessage)(environment, {

package/dist/core/makeNetworkRequest.d.ts

@@ -3,6 +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>>;
+import { ShouldFetch } from './check';
+export declare function maybeMakeNetworkRequest(environment: IsographEnvironment, artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>, variables: Variables, shouldFetch: ShouldFetch): 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

@@ -8,8 +8,8 @@ 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) {
+function maybeMakeNetworkRequest(environment, artifact, variables, shouldFetch) {
+    switch (shouldFetch) {
         case 'Yes': {
             return makeNetworkRequest(environment, artifact, variables);
         }

package/dist/core/read.js

@@ -8,6 +8,7 @@ const IsographEnvironment_1 = require("./IsographEnvironment");
 const makeNetworkRequest_1 = require("./makeNetworkRequest");
 const PromiseWrapper_1 = require("./PromiseWrapper");
 const logging_1 = require("./logging");
+const check_1 = require("./check");
 function readButDoNotEvaluate(environment, fragmentReference, networkRequestOptions) {
     var _a;
     const mutableEncounteredRecords = new Set();
@@ -265,7 +266,7 @@ function readData(environment, ast, root, variables, nestedRefetchQueries, netwo
                     };
                 }
                 else {
-                    target[field.alias] = (args) => {
+                    target[field.alias] = (args, fetchOptions) => {
                         // TODO we should use the reader AST for this
                         const includeReadOutData = (variables, readOutData) => {
                             variables.id = readOutData.id;
@@ -283,7 +284,9 @@ function readData(environment, ast, root, variables, nestedRefetchQueries, netwo
                             // Fetcher
                             () => {
                                 const fragmentReferenceAndDisposeFromEntrypoint = (entrypoint) => {
-                                    const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.makeNetworkRequest)(environment, entrypoint, localVariables);
+                                    var _a;
+                                    const shouldFetch = (_a = fetchOptions === null || fetchOptions === void 0 ? void 0 : fetchOptions.shouldFetch) !== null && _a !== void 0 ? _a : check_1.DEFAULT_SHOULD_FETCH_VALUE;
+                                    const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, localVariables, shouldFetch);
                                     const fragmentReference = {
                                         kind: 'FragmentReference',
                                         readerWithRefetchQueries: (0, PromiseWrapper_1.wrapResolvedValue)({
@@ -312,8 +315,10 @@ function readData(environment, ast, root, variables, nestedRefetchQueries, netwo
                                         // Promise is pending or thrown
                                         let entrypointLoaderState = { kind: 'EntrypointNotLoaded' };
                                         const networkRequest = (0, PromiseWrapper_1.wrapPromise)(isographArtifactPromiseWrapper.promise.then((entrypoint) => {
+                                            var _a;
                                             if (entrypointLoaderState.kind === 'EntrypointNotLoaded') {
-                                                const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.makeNetworkRequest)(environment, entrypoint, localVariables);
+                                                const shouldFetch = (_a = fetchOptions === null || fetchOptions === void 0 ? void 0 : fetchOptions.shouldFetch) !== null && _a !== void 0 ? _a : check_1.DEFAULT_SHOULD_FETCH_VALUE;
+                                                const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, localVariables, shouldFetch);
                                                 entrypointLoaderState = {
                                                     kind: 'NetworkRequestStarted',
                                                     disposeNetworkRequest,

package/dist/core/reader.d.ts

@@ -3,6 +3,7 @@ import { FragmentReference, ExtractParameters, ExtractData } from './FragmentRef
 import { ComponentOrFieldName, IsographEnvironment, type Link } from './IsographEnvironment';
 import { IsographEntrypoint, IsographEntrypointLoader, RefetchQueryNormalizationArtifact, RefetchQueryNormalizationArtifactWrapper } from './entrypoint';
 import { Arguments } from './util';
+import { FetchOptions } from './check';
 export type TopLevelReaderArtifact<TReadFromStore extends {
     parameters: object;
     data: object;
@@ -77,5 +78,5 @@ type StableId = string;
 export type LoadableField<TReadFromStore extends {
     data: object;
     parameters: object;
-}, TResult, TArgs = ExtractParameters<TReadFromStore>> = (args: TArgs | void) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];
+}, TResult, TArgs = ExtractParameters<TReadFromStore>> = (args: TArgs | void, fetchOptions: FetchOptions) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];
 export {};

package/dist/index.d.ts

@@ -9,7 +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 { check, CheckResult, FetchOptions, ShouldFetch } from './core/check';
 export { IsographEnvironmentProvider, useIsographEnvironment, type IsographEnvironmentProviderProps, } from './react/IsographEnvironmentProvider';
 export { useImperativeReference } from './react/useImperativeReference';
 export { FragmentReader } from './react/FragmentReader';

package/dist/loadable-hooks/useClientSideDefer.d.ts

@@ -1,14 +1,15 @@
 import { ExtractParameters, FragmentReference } from '../core/FragmentReference';
 import { LoadableField } from '../core/reader';
+import { FetchOptions } from '../core/check';
 export declare function useClientSideDefer<TReadFromStore extends {
     data: object;
     parameters: object;
-}, TResult>(loadableField: LoadableField<TReadFromStore, TResult, ExtractParameters<TReadFromStore>>): {
+}, TResult>(loadableField: LoadableField<TReadFromStore, TResult, ExtractParameters<TReadFromStore>>, fetchOptions?: FetchOptions): {
     fragmentReference: FragmentReference<TReadFromStore, TResult>;
 };
 export declare function useClientSideDefer<TReadFromStore extends {
     data: object;
     parameters: object;
-}, TResult, TProvidedArgs extends object>(loadableField: LoadableField<TReadFromStore, TResult, Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>>, args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>): {
+}, TResult, TProvidedArgs extends object>(loadableField: LoadableField<TReadFromStore, TResult, Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>>, args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>, fetchOptions?: FetchOptions): {
     fragmentReference: FragmentReference<TReadFromStore, TResult>;
 };

package/dist/loadable-hooks/useClientSideDefer.js

@@ -4,8 +4,8 @@ exports.useClientSideDefer = useClientSideDefer;
 const IsographEnvironmentProvider_1 = require("../react/IsographEnvironmentProvider");
 const cache_1 = require("../core/cache");
 const react_disposable_state_1 = require("@isograph/react-disposable-state");
-function useClientSideDefer(loadableField, args) {
-    const [id, loader] = loadableField(args);
+function useClientSideDefer(loadableField, args, fetchOptions) {
+    const [id, loader] = loadableField(args, fetchOptions !== null && fetchOptions !== void 0 ? fetchOptions : {});
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
     const cache = (0, cache_1.getOrCreateItemInSuspenseCache)(environment, id, loader);
     const fragmentReference = (0, react_disposable_state_1.useLazyDisposableState)(cache).state;

package/dist/loadable-hooks/useConnectionSpecPagination.d.ts

@@ -1,5 +1,6 @@
 import { FragmentReference } from '../core/FragmentReference';
 import { LoadableField } from '../core/reader';
+import { FetchOptions } from '../core/check';
 type UsePaginationReturnValue<TReadFromStore extends {
     parameters: object;
     data: object;
@@ -9,7 +10,7 @@ type UsePaginationReturnValue<TReadFromStore extends {
     results: ReadonlyArray<TItem>;
 } | {
     kind: 'Complete';
-    fetchMore: (count: number) => void;
+    fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
     results: ReadonlyArray<TItem>;
     hasNextPage: boolean;
 };

package/dist/loadable-hooks/useConnectionSpecPagination.js

@@ -65,11 +65,11 @@ function useConnectionSpecPagination(loadableField, pageInfo) {
             };
         });
     }
-    const getFetchMore = (after) => (count) => {
+    const getFetchMore = (after) => (count, fetchOptions) => {
         const loadedField = loadableField({
             after: after,
             first: count,
-        })[1]();
+        }, fetchOptions !== null && fetchOptions !== void 0 ? fetchOptions : {})[1]();
         const newPointer = (0, reference_counted_pointer_1.createReferenceCountedPointer)(loadedField);
         const clonedPointers = loadedReferences.map(([refCountedPointer]) => {
             const clonedRefCountedPointer = refCountedPointer.cloneIfNotDisposed();

package/dist/loadable-hooks/useImperativeLoadableField.d.ts

@@ -1,12 +1,13 @@
 import { ExtractParameters, FragmentReference } from '../core/FragmentReference';
 import { UnassignedState } from '@isograph/react-disposable-state';
 import { LoadableField } from '../core/reader';
+import { FetchOptions } from '../core/check';
 type UseImperativeLoadableFieldReturn<TReadFromStore extends {
     data: object;
     parameters: object;
 }, TResult, TProvidedArgs extends object> = {
     fragmentReference: FragmentReference<TReadFromStore, TResult> | UnassignedState;
-    loadField: (args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void) => void;
+    loadField: (args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void, fetchOptions?: FetchOptions) => void;
 };
 export declare function useImperativeLoadableField<TReadFromStore extends {
     data: object;

package/dist/loadable-hooks/useImperativeLoadableField.js

@@ -5,8 +5,8 @@ const react_disposable_state_1 = require("@isograph/react-disposable-state");
 function useImperativeLoadableField(loadableField) {
     const { state, setState } = (0, react_disposable_state_1.useUpdatableDisposableState)();
     return {
-        loadField: (args) => {
-            const [_id, loader] = loadableField(args);
+        loadField: (args, fetchOptions) => {
+            const [_id, loader] = loadableField(args, fetchOptions !== null && fetchOptions !== void 0 ? fetchOptions : {});
             setState(loader());
         },
         fragmentReference: state,

package/dist/loadable-hooks/useSkipLimitPagination.d.ts

@@ -1,11 +1,12 @@
 import { LoadableField } from '../core/reader';
 import { FragmentReference } from '../core/FragmentReference';
+import { FetchOptions } from '../core/check';
 type UseSkipLimitReturnValue<TReadFromStore extends {
     data: object;
     parameters: object;
 }, TItem> = {
     readonly kind: 'Complete';
-    readonly fetchMore: (count: number) => void;
+    readonly fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
     readonly results: ReadonlyArray<TItem>;
 } | {
     readonly kind: 'Pending';

package/dist/loadable-hooks/useSkipLimitPagination.js

@@ -58,11 +58,11 @@ function useSkipLimitPagination(loadableField, initialArgs) {
             };
         });
     }
-    const getFetchMore = (loadedSoFar) => (count) => {
+    const getFetchMore = (loadedSoFar) => (count, fetchOptions) => {
         const loadedField = loadableField({
             skip: loadedSoFar,
             limit: count,
-        })[1]();
+        }, fetchOptions !== null && fetchOptions !== void 0 ? fetchOptions : {})[1]();
         const newPointer = (0, reference_counted_pointer_1.createReferenceCountedPointer)(loadedField);
         const clonedPointers = loadedReferences.map(([refCountedPointer]) => {
             const clonedRefCountedPointer = refCountedPointer.cloneIfNotDisposed();

package/dist/react/useImperativeReference.d.ts

@@ -7,5 +7,5 @@ export declare function useImperativeReference<TReadFromStore extends {
     data: object;
 }, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>): {
     fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue> | UnassignedState;
-    loadFragmentReference: (variables: ExtractParameters<TReadFromStore>, options?: FetchOptions) => void;
+    loadFragmentReference: (variables: ExtractParameters<TReadFromStore>, fetchOptions?: FetchOptions) => void;
 };

package/dist/react/useImperativeReference.js

@@ -13,10 +13,10 @@ function useImperativeReference(entrypoint) {
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
     return {
         fragmentReference: state,
-        loadFragmentReference: (variables, options) => {
+        loadFragmentReference: (variables, fetchOptions) => {
             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 shouldFetch = (_a = fetchOptions === null || fetchOptions === void 0 ? void 0 : fetchOptions.shouldFetch) !== null && _a !== void 0 ? _a : check_1.DEFAULT_SHOULD_FETCH_VALUE;
+            const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.maybeMakeNetworkRequest)(environment, entrypoint, variables, shouldFetch);
             setState([
                 {
                     kind: 'FragmentReference',

package/dist/react/useLazyReference.d.ts

@@ -4,6 +4,6 @@ import { FetchOptions } from '../core/check';
 export declare function useLazyReference<TReadFromStore extends {
     parameters: object;
     data: object;
-}, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>, options?: FetchOptions): {
+}, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>, fetchOptions?: 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, options) {
+function useLazyReference(entrypoint, variables, fetchOptions) {
     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, options) {
             entrypoint,
         });
     }
-    const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables, options);
+    const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables, fetchOptions);
     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-6ea7b362",
+  "version": "0.0.0-main-cd6f81ae",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -19,9 +19,9 @@
     "iso-watch": "../../target/debug/isograph_cli --config ./isograph.config.json --watch"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-6ea7b362",
-    "@isograph/react-disposable-state": "0.0.0-main-6ea7b362",
-    "@isograph/reference-counted-pointer": "0.0.0-main-6ea7b362"
+    "@isograph/disposable-types": "0.0.0-main-cd6f81ae",
+    "@isograph/react-disposable-state": "0.0.0-main-cd6f81ae",
+    "@isograph/reference-counted-pointer": "0.0.0-main-cd6f81ae"
   },
   "peerDependencies": {
     "react": "18.3.1"

package/src/core/cache.ts

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

package/src/core/check.ts

@@ -10,12 +10,12 @@ import {
 } from './IsographEnvironment';
 import { logMessage } from './logging';
 
-export type FetchPolicy = 'Yes' | 'No' | 'IfNecessary';
+export type ShouldFetch = 'Yes' | 'No' | 'IfNecessary';
 
-export const DEFAULT_FETCH_POLICY: FetchPolicy = 'IfNecessary';
+export const DEFAULT_SHOULD_FETCH_VALUE: ShouldFetch = 'IfNecessary';
 
 export type FetchOptions = {
-  fetchPolicy?: FetchPolicy;
+  shouldFetch?: ShouldFetch;
 };
 
 export type CheckResult =

package/src/core/makeNetworkRequest.ts

@@ -19,7 +19,7 @@ import {
 } from './PromiseWrapper';
 import { normalizeData } from './cache';
 import { logMessage } from './logging';
-import { check, FetchPolicy } from './check';
+import { check, ShouldFetch } from './check';
 
 let networkRequestId = 0;
 
@@ -27,9 +27,9 @@ export function maybeMakeNetworkRequest(
   environment: IsographEnvironment,
   artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>,
   variables: Variables,
-  fetchPolicy: FetchPolicy,
+  shouldFetch: ShouldFetch,
 ): ItemCleanupPair<PromiseWrapper<void, AnyError>> {
-  switch (fetchPolicy) {
+  switch (shouldFetch) {
     case 'Yes': {
       return makeNetworkRequest(environment, artifact, variables);
     }

package/src/core/read.ts

@@ -18,7 +18,7 @@ import {
   IsographEnvironment,
   type Link,
 } from './IsographEnvironment';
-import { makeNetworkRequest } from './makeNetworkRequest';
+import { maybeMakeNetworkRequest } from './makeNetworkRequest';
 import {
   getPromiseState,
   PromiseWrapper,
@@ -30,6 +30,7 @@ import { ReaderAst } from './reader';
 import { Arguments } from './util';
 import { logMessage } from './logging';
 import { CleanupFn } from '@isograph/disposable-types';
+import { DEFAULT_SHOULD_FETCH_VALUE, FetchOptions } from './check';
 
 export type WithEncounteredRecords<T> = {
   readonly encounteredRecords: Set<DataId>;
@@ -408,7 +409,7 @@ function readData<TReadFromStore>(
             recordLink: refetchReaderParams.recordLink,
           };
         } else {
-          target[field.alias] = (args: any) => {
+          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;
@@ -436,8 +437,15 @@ function readData<TReadFromStore>(
                 const fragmentReferenceAndDisposeFromEntrypoint = (
                   entrypoint: IsographEntrypoint<any, any>,
                 ): [FragmentReference<any, any>, CleanupFn] => {
+                  const shouldFetch =
+                    fetchOptions?.shouldFetch ?? DEFAULT_SHOULD_FETCH_VALUE;
                   const [networkRequest, disposeNetworkRequest] =
-                    makeNetworkRequest(environment, entrypoint, localVariables);
+                    maybeMakeNetworkRequest(
+                      environment,
+                      entrypoint,
+                      localVariables,
+                      shouldFetch,
+                    );
 
                   const fragmentReference: FragmentReference<any, any> = {
                     kind: 'FragmentReference',
@@ -493,11 +501,15 @@ function readData<TReadFromStore>(
                           if (
                             entrypointLoaderState.kind === 'EntrypointNotLoaded'
                           ) {
+                            const shouldFetch =
+                              fetchOptions?.shouldFetch ??
+                              DEFAULT_SHOULD_FETCH_VALUE;
                             const [networkRequest, disposeNetworkRequest] =
-                              makeNetworkRequest(
+                              maybeMakeNetworkRequest(
                                 environment,
                                 entrypoint,
                                 localVariables,
+                                shouldFetch,
                               );
                             entrypointLoaderState = {
                               kind: 'NetworkRequestStarted',

package/src/core/reader.ts

@@ -16,6 +16,7 @@ import {
   RefetchQueryNormalizationArtifactWrapper,
 } from './entrypoint';
 import { Arguments } from './util';
+import { FetchOptions } from './check';
 
 export type TopLevelReaderArtifact<
   TReadFromStore extends { parameters: object; data: object },
@@ -147,4 +148,9 @@ export type LoadableField<
   TArgs = ExtractParameters<TReadFromStore>,
 > = (
   args: TArgs | void,
+  // Note: fetchOptions is not nullable here because a LoadableField is not a
+  // user-facing API. Users should only interact with LoadableFields via APIs
+  // like useClientSideDefer. These APIs should have a nullable fetchOptions
+  // parameter, and provide a default value ({}) to the LoadableField.
+  fetchOptions: FetchOptions,
 ) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];

package/src/index.ts

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

package/src/loadable-hooks/useClientSideDefer.ts

@@ -6,6 +6,7 @@ import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 import { getOrCreateItemInSuspenseCache } from '../core/cache';
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
 import { LoadableField } from '../core/reader';
+import { FetchOptions } from '../core/check';
 
 export function useClientSideDefer<
   TReadFromStore extends { data: object; parameters: object },
@@ -16,6 +17,7 @@ export function useClientSideDefer<
     TResult,
     ExtractParameters<TReadFromStore>
   >,
+  fetchOptions?: FetchOptions,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
 export function useClientSideDefer<
@@ -29,6 +31,7 @@ export function useClientSideDefer<
     Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
   >,
   args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
 export function useClientSideDefer<
@@ -42,8 +45,9 @@ export function useClientSideDefer<
     Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
   >,
   args?: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> } {
-  const [id, loader] = loadableField(args);
+  const [id, loader] = loadableField(args, fetchOptions ?? {});
   const environment = useIsographEnvironment();
   const cache = getOrCreateItemInSuspenseCache(environment, id, loader);
 

package/src/loadable-hooks/useConnectionSpecPagination.ts

@@ -19,6 +19,7 @@ import { LoadableField, type ReaderAst } from '../core/reader';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
 import { maybeUnwrapNetworkRequest } from '../react/useResult';
+import { FetchOptions } from '../core/check';
 
 type UsePaginationReturnValue<
   TReadFromStore extends { parameters: object; data: object },
@@ -31,7 +32,7 @@ type UsePaginationReturnValue<
     }
   | {
       kind: 'Complete';
-      fetchMore: (count: number) => void;
+      fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
       results: ReadonlyArray<TItem>;
       hasNextPage: boolean;
     };
@@ -178,11 +179,14 @@ export function useConnectionSpecPagination<
 
   const getFetchMore =
     (after: string | null) =>
-    (count: number): void => {
-      const loadedField = loadableField({
-        after: after,
-        first: count,
-      })[1]();
+    (count: number, fetchOptions?: FetchOptions): void => {
+      const loadedField = loadableField(
+        {
+          after: after,
+          first: count,
+        },
+        fetchOptions ?? {},
+      )[1]();
       const newPointer = createReferenceCountedPointer(loadedField);
       const clonedPointers = loadedReferences.map(([refCountedPointer]) => {
         const clonedRefCountedPointer = refCountedPointer.cloneIfNotDisposed();

package/src/loadable-hooks/useImperativeLoadableField.ts

@@ -7,6 +7,7 @@ import {
   useUpdatableDisposableState,
 } from '@isograph/react-disposable-state';
 import { LoadableField } from '../core/reader';
+import { FetchOptions } from '../core/check';
 
 type UseImperativeLoadableFieldReturn<
   TReadFromStore extends { data: object; parameters: object },
@@ -17,7 +18,10 @@ type UseImperativeLoadableFieldReturn<
     | FragmentReference<TReadFromStore, TResult>
     | UnassignedState;
   loadField: (
+    // TODO this should be void iff all args are provided by the query, like in
+    // useClientSideDefer.
     args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
+    fetchOptions?: FetchOptions,
   ) => void;
 };
 
@@ -38,8 +42,9 @@ export function useImperativeLoadableField<
   return {
     loadField: (
       args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
+      fetchOptions?: FetchOptions,
     ) => {
-      const [_id, loader] = loadableField(args);
+      const [_id, loader] = loadableField(args, fetchOptions ?? {});
       setState(loader());
     },
     fragmentReference: state,

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -17,6 +17,7 @@ import {
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
 import { type WithEncounteredRecords } from '../core/read';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
+import { FetchOptions } from '../core/check';
 
 type UseSkipLimitReturnValue<
   TReadFromStore extends { data: object; parameters: object },
@@ -24,7 +25,7 @@ type UseSkipLimitReturnValue<
 > =
   | {
       readonly kind: 'Complete';
-      readonly fetchMore: (count: number) => void;
+      readonly fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
       readonly results: ReadonlyArray<TItem>;
     }
   | {
@@ -163,11 +164,14 @@ export function useSkipLimitPagination<
 
   const getFetchMore =
     (loadedSoFar: number) =>
-    (count: number): void => {
-      const loadedField = loadableField({
-        skip: loadedSoFar,
-        limit: count,
-      })[1]();
+    (count: number, fetchOptions?: FetchOptions): void => {
+      const loadedField = loadableField(
+        {
+          skip: loadedSoFar,
+          limit: count,
+        },
+        fetchOptions ?? {},
+      )[1]();
       const newPointer = createReferenceCountedPointer(loadedField);
       const clonedPointers = loadedReferences.map(([refCountedPointer]) => {
         const clonedRefCountedPointer = refCountedPointer.cloneIfNotDisposed();

package/src/react/useImperativeReference.ts

@@ -11,7 +11,7 @@ import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { ROOT_ID } from '../core/IsographEnvironment';
 import { maybeMakeNetworkRequest } from '../core/makeNetworkRequest';
 import { wrapResolvedValue } from '../core/PromiseWrapper';
-import { DEFAULT_FETCH_POLICY, FetchOptions } from '../core/check';
+import { DEFAULT_SHOULD_FETCH_VALUE, FetchOptions } from '../core/check';
 
 // TODO rename this to useImperativelyLoadedEntrypoint
 
@@ -26,7 +26,7 @@ export function useImperativeReference<
     | UnassignedState;
   loadFragmentReference: (
     variables: ExtractParameters<TReadFromStore>,
-    options?: FetchOptions,
+    fetchOptions?: FetchOptions,
   ) => void;
 } {
   const { state, setState } =
@@ -38,14 +38,15 @@ export function useImperativeReference<
     fragmentReference: state,
     loadFragmentReference: (
       variables: ExtractParameters<TReadFromStore>,
-      options?: FetchOptions,
+      fetchOptions?: FetchOptions,
     ) => {
-      const fetchPolicy = options?.fetchPolicy ?? DEFAULT_FETCH_POLICY;
+      const shouldFetch =
+        fetchOptions?.shouldFetch ?? DEFAULT_SHOULD_FETCH_VALUE;
       const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
         environment,
         entrypoint,
         variables,
-        fetchPolicy,
+        shouldFetch,
       );
       setState([
         {

package/src/react/useLazyReference.ts

@@ -15,7 +15,7 @@ export function useLazyReference<
 >(
   entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
   variables: ExtractParameters<TReadFromStore>,
-  options?: FetchOptions,
+  fetchOptions?: FetchOptions,
 ): {
   fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
 } {
@@ -33,7 +33,7 @@ export function useLazyReference<
     environment,
     entrypoint,
     variables,
-    options,
+    fetchOptions,
   );
 
   return {