@isograph/react 0.3.1 → 0.4.0

package/src/core/FragmentReference.ts

@@ -1,6 +1,6 @@
 import { ReaderWithRefetchQueries } from '../core/entrypoint';
 import { stableCopy } from './cache';
-import { type Link } from './IsographEnvironment';
+import { type StoreLink } from './IsographEnvironment';
 import { PromiseWrapper } from './PromiseWrapper';
 import type { StartUpdate } from './reader';
 
@@ -35,11 +35,14 @@ export type ExtractParameters<T> = T extends {
   ? P
   : Variables;
 
-export type ExtractStartUpdate<
-  T extends {
-    startUpdate?: StartUpdate<object>;
-  },
-> = T['startUpdate'];
+export type ExtractStartUpdate<T extends UnknownTReadFromStore> =
+  T['startUpdate'];
+
+export type ExtractUpdatableData<T extends UnknownTReadFromStore> =
+  ExtractUpdatableDataFromStartUpdate<ExtractStartUpdate<T>>;
+
+export type ExtractUpdatableDataFromStartUpdate<T> =
+  T extends StartUpdate<infer D> ? D : never;
 
 export type FragmentReference<
   TReadFromStore extends UnknownTReadFromStore,
@@ -49,7 +52,13 @@ export type FragmentReference<
   readonly readerWithRefetchQueries: PromiseWrapper<
     ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
   >;
-  readonly root: Link;
+  readonly root: StoreLink;
+  // TODO we potentially stably copy and stringify variables a lot!
+  // So, we should employ interior mutability: pretend that fragent reference
+  // is immutable, but actually store something like
+  // `Map<Variable, StablyCopiedStringifiedOutput>`
+  // and read or update that map when we would otherwise stably copy and
+  // stringify.
   readonly variables: ExtractParameters<TReadFromStore>;
   readonly networkRequest: PromiseWrapper<void, any>;
 };

package/src/core/IsographEnvironment.ts

@@ -1,5 +1,9 @@
 import { ParentCache } from '@isograph/react-disposable-state';
-import { IsographEntrypoint } from './entrypoint';
+import {
+  IsographEntrypoint,
+  IsographOperation,
+  IsographPersistedOperation,
+} from './entrypoint';
 import {
   FragmentReference,
   Variables,
@@ -11,6 +15,7 @@ import { LogFunction, WrappedLogFunction } from './logging';
 import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
 import { WithEncounteredRecords } from './read';
 import type { ReaderAst, StartUpdate } from './reader';
+import type { Brand } from './brand';
 
 export type ComponentOrFieldName = string;
 export type StringifiedArgs = string;
@@ -34,7 +39,7 @@ export type FragmentSubscription<TReadFromStore extends UnknownTReadFromStore> =
 export type AnyChangesToRecordSubscription = {
   readonly kind: 'AnyChangesToRecord';
   readonly callback: () => void;
-  readonly recordLink: Link;
+  readonly recordLink: StoreLink;
 };
 
 export type AnyRecordSubscription = {
@@ -73,18 +78,23 @@ export type IsographEnvironment = {
 
 export type MissingFieldHandler = (
   storeRecord: StoreRecord,
-  root: Link,
+  root: StoreLink,
   fieldName: string,
   arguments_: { [index: string]: any } | null,
   variables: Variables | null,
-) => Link | undefined;
+) => StoreLink | undefined;
 
 export type IsographNetworkFunction = (
-  queryText: string,
+  operation: IsographOperation | IsographPersistedOperation,
   variables: Variables,
 ) => Promise<any>;
 
-export type Link = {
+export interface Link<T extends TypeName> extends StoreLink {
+  readonly __link: Brand<DataId, T>;
+  readonly __typename: T;
+}
+
+export type StoreLink = {
   readonly __link: DataId;
   readonly __typename: TypeName;
 };
@@ -99,7 +109,7 @@ export type DataTypeValue =
   | string
   | null
   // Singular linked fields:
-  | Link
+  | StoreLink
   // Plural scalar and linked fields:
   | DataTypeValue[];
 
@@ -158,7 +168,7 @@ export function createIsographStore(): IsographStore {
   };
 }
 
-export function assertLink(link: DataTypeValue): Link | null | undefined {
+export function assertLink(link: DataTypeValue): StoreLink | null | undefined {
   if (Array.isArray(link)) {
     throw new Error('Unexpected array');
   }
@@ -171,7 +181,7 @@ export function assertLink(link: DataTypeValue): Link | null | undefined {
   throw new Error('Invalid link');
 }
 
-export function getLink(maybeLink: DataTypeValue): Link | null {
+export function getLink(maybeLink: DataTypeValue): StoreLink | null {
   if (
     maybeLink != null &&
     typeof maybeLink === 'object' &&

package/src/core/PromiseWrapper.ts

@@ -1,6 +1,6 @@
 export type AnyError = any;
 
-export const NOT_SET: Symbol = Symbol('NOT_SET');
+export const NOT_SET = Symbol('NOT_SET');
 export type NotSet = typeof NOT_SET;
 
 export type Result<T, E> =
@@ -18,31 +18,32 @@ export type Result<T, E> =
  * Before the promise is resolved, value becomes non-null.
  */
 export type PromiseWrapper<T, E = any> = {
-  readonly promise: Promise<T>;
+  readonly promise: Promise<Exclude<T, NotSet>>;
   result: Result<Exclude<T, NotSet>, E> | NotSet;
 };
 
-export function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T, any> {
+export function wrapPromise<T>(
+  promise: Promise<Exclude<T, NotSet>>,
+): PromiseWrapper<T, unknown> {
   // TODO confirm suspense works if the promise is already resolved.
   const wrapper: PromiseWrapper<T, any> = { promise, result: NOT_SET };
   promise
     .then((v) => {
-      // v is assignable to Exclude<T, Symbol> | Symbol
-      wrapper.result = { kind: 'Ok', value: v as any };
+      wrapper.result = { kind: 'Ok', value: v };
     })
     .catch((e) => {
-      // e is assignable to Exclude<T, Symbol> | Symbol
-      wrapper.result = { kind: 'Err', error: e as any };
+      wrapper.result = { kind: 'Err', error: e };
     });
   return wrapper;
 }
 
-export function wrapResolvedValue<T>(value: T): PromiseWrapper<T, never> {
+export function wrapResolvedValue<T>(
+  value: Exclude<T, NotSet>,
+): PromiseWrapper<T, never> {
   return {
     promise: Promise.resolve(value),
     result: {
       kind: 'Ok',
-      // @ts-expect-error one should not call wrapResolvedValue with NOT_SET
       value,
     },
   };
@@ -51,8 +52,7 @@ export function wrapResolvedValue<T>(value: T): PromiseWrapper<T, never> {
 export function readPromise<T, E>(p: PromiseWrapper<T, E>): T {
   const { result } = p;
   if (result !== NOT_SET) {
-    // Safety: p.result is either NOT_SET or an actual value.
-    const resultKind = result as Result<T, any>;
+    const resultKind = result;
     if (resultKind.kind === 'Ok') {
       return resultKind.value;
     } else {
@@ -73,11 +73,8 @@ export type PromiseState<T, E> =
 export function getPromiseState<T, E>(
   p: PromiseWrapper<T, E>,
 ): PromiseState<T, E> {
-  const { result } = p;
-  if (result !== NOT_SET) {
-    // Safety: p.result is either NOT_SET or an actual value.
-    const resultKind = result as Result<T, any>;
-    return resultKind;
+  if (p.result !== NOT_SET) {
+    return p.result;
   }
   return {
     kind: 'Pending',

package/src/core/areEqualWithDeepComparison.ts

@@ -1,7 +1,7 @@
-import type { Link } from './IsographEnvironment';
+import type { StoreLink } from './IsographEnvironment';
 import type { ReaderAst, ReaderLinkedField, ReaderScalarField } from './reader';
 
-export function mergeUsingReaderAst(
+function mergeUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItem: unknown,
   newItem: unknown,
@@ -40,7 +40,7 @@ export function mergeUsingReaderAst(
   }
 }
 
-export function mergeArraysUsingReaderAst(
+function mergeArraysUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItems: ReadonlyArray<unknown>,
   newItems: Array<unknown>,
@@ -101,9 +101,9 @@ export function mergeObjectsUsingReaderAst(
       case 'Link': {
         const key = field.alias;
         // @ts-expect-error
-        const oldValue: Link = oldItemObject[key];
+        const oldValue: StoreLink = oldItemObject[key];
         // @ts-expect-error
-        const newValue: Link = newItemObject[key];
+        const newValue: StoreLink = newItemObject[key];
 
         if (
           oldValue.__link !== newValue.__link ||

package/src/core/brand.ts

@@ -0,0 +1,18 @@
+// Suppress the TypeScript compiler warning for this branded-type trick.
+// See discussion: https://github.com/microsoft/TypeScript/issues/202#issuecomment-436900738
+// Pattern: “Brand<BaseType, Brand>” leverages TypeScript conditional and `infer` types to create a pseudo-nominal type,
+// enabling BaseType to be treated as distinct only when tagged with Brand, even though Brand doesn't exist at runtime.
+//
+// Explanation:
+// - Brand extends `symbol | string` acts as a “brand” identifier.
+// - The type uses a conditional check `infer _ extends Brand ? BaseType : never` to strip out BaseType when the branding doesn't match.
+// - This yields a branded type system: `Brand<string, "UserId">` is not accidentally assignable to `Brand<string, "ProductId">`.
+//
+// Usage: Helps enforce semantic distinctions (e.g., distinguishing user IDs from product IDs) even when their runtime values are both strings.
+//
+// Caveat: This is purely a compile-time trick—Brand is erased in emitted JavaScript, so runtime checks must rely on other mechanisms.
+export type Brand<
+  BaseType,
+  Brand extends symbol | string,
+  // @ts-ignore
+> = infer _ extends Brand ? BaseType : never;

package/src/core/cache.ts

@@ -8,7 +8,6 @@ import {
   NormalizationInlineFragment,
   NormalizationLinkedField,
   NormalizationScalarField,
-  RefetchQueryNormalizationArtifactWrapper,
   type NormalizationAst,
   type NormalizationAstLoader,
   type NormalizationAstNodes,
@@ -27,15 +26,15 @@ import {
   DataTypeValue,
   FragmentSubscription,
   getLink,
-  Link,
   ROOT_ID,
+  StoreLink,
   StoreRecord,
   type IsographEnvironment,
   type TypeName,
 } from './IsographEnvironment';
 import { logMessage } from './logging';
 import { maybeMakeNetworkRequest } from './makeNetworkRequest';
-import { wrapResolvedValue } from './PromiseWrapper';
+import { wrapPromise, wrapResolvedValue } from './PromiseWrapper';
 import { readButDoNotEvaluate, WithEncounteredRecords } from './read';
 import { ReaderLinkedField, ReaderScalarField, type ReaderAst } from './reader';
 import { Argument, ArgumentValue } from './util';
@@ -93,15 +92,31 @@ export function getOrCreateCacheForArtifact<
   variables: ExtractParameters<TReadFromStore>,
   fetchOptions?: FetchOptions<TClientFieldValue>,
 ): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
-  const cacheKey =
-    entrypoint.networkRequestInfo.queryText +
-    JSON.stringify(stableCopy(variables));
+  let cacheKey = '';
+  switch (entrypoint.networkRequestInfo.operation.kind) {
+    case 'Operation':
+      cacheKey =
+        entrypoint.networkRequestInfo.operation.text +
+        JSON.stringify(stableCopy(variables));
+      break;
+    case 'PersistedOperation':
+      cacheKey =
+        entrypoint.networkRequestInfo.operation.operationId +
+        JSON.stringify(stableCopy(variables));
+      break;
+  }
   const factory = () => {
+    const readerWithRefetchQueries =
+      entrypoint.readerWithRefetchQueries.kind ===
+      'ReaderWithRefetchQueriesLoader'
+        ? wrapPromise(entrypoint.readerWithRefetchQueries.loader())
+        : wrapResolvedValue(entrypoint.readerWithRefetchQueries);
     const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
       environment,
       entrypoint,
       variables,
-      fetchOptions,
+      readerWithRefetchQueries,
+      fetchOptions ?? null,
     );
 
     const itemCleanupPair: ItemCleanupPair<
@@ -109,12 +124,7 @@ export function getOrCreateCacheForArtifact<
     > = [
       {
         kind: 'FragmentReference',
-        readerWithRefetchQueries: wrapResolvedValue({
-          kind: 'ReaderWithRefetchQueries',
-          readerArtifact: entrypoint.readerWithRefetchQueries.readerArtifact,
-          nestedRefetchQueries:
-            entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
-        }),
+        readerWithRefetchQueries,
         root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
         variables,
         networkRequest: networkRequest,
@@ -147,8 +157,7 @@ export function normalizeData(
   normalizationAst: NormalizationAstNodes,
   networkResponse: NetworkResponseObject,
   variables: Variables,
-  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
-  root: Link,
+  root: StoreLink,
 ): EncounteredIds {
   const encounteredIds: EncounteredIds = new Map();
 
@@ -169,7 +178,6 @@ export function normalizeData(
     newStoreRecord,
     root,
     variables,
-    nestedRefetchQueries,
     encounteredIds,
   );
 
@@ -197,7 +205,7 @@ export function subscribeToAnyChange(
 
 export function subscribeToAnyChangesToRecord(
   environment: IsographEnvironment,
-  recordLink: Link,
+  recordLink: StoreLink,
   callback: () => void,
 ): () => void {
   const subscription = {
@@ -232,7 +240,7 @@ export function subscribe<TReadFromStore extends UnknownTReadFromStore>(
 
 export function onNextChangeToRecord(
   environment: IsographEnvironment,
-  recordLink: Link,
+  recordLink: StoreLink,
 ): Promise<void> {
   return new Promise((resolve) => {
     const unsubscribe = subscribeToAnyChangesToRecord(
@@ -251,20 +259,28 @@ export function onNextChangeToRecord(
 //
 // That's probably okay to ignore. We don't, however, want to prevent
 // updating other subscriptions if one subscription had missing data.
-function withErrorHandling<T>(f: (t: T) => void): (t: T) => void {
+function withErrorHandling<T>(
+  environment: IsographEnvironment,
+  f: (t: T) => void,
+): (t: T) => void {
   return (t) => {
     try {
       return f(t);
-    } catch {}
+    } catch (e) {
+      logMessage(environment, () => ({
+        kind: 'ErrorEncounteredInWithErrorHandling',
+        error: e,
+      }));
+    }
   };
 }
 
-function callSubscriptions(
+export function callSubscriptions(
   environment: IsographEnvironment,
   recordsEncounteredWhenNormalizing: EncounteredIds,
 ) {
   environment.subscriptions.forEach(
-    withErrorHandling((subscription) => {
+    withErrorHandling(environment, (subscription) => {
       switch (subscription.kind) {
         case 'FragmentSubscription': {
           // TODO if there are multiple components subscribed to the same
@@ -379,9 +395,8 @@ function normalizeDataIntoRecord(
   normalizationAst: NormalizationAstNodes,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
-  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
   let recordHasBeenUpdated = false;
@@ -406,7 +421,6 @@ function normalizeDataIntoRecord(
           targetParentRecord,
           targetParentRecordLink,
           variables,
-          nestedRefetchQueries,
           mutableEncounteredIds,
         );
         recordHasBeenUpdated =
@@ -421,7 +435,6 @@ function normalizeDataIntoRecord(
           targetParentRecord,
           targetParentRecordLink,
           variables,
-          nestedRefetchQueries,
           mutableEncounteredIds,
         );
         recordHasBeenUpdated =
@@ -437,7 +450,7 @@ function normalizeDataIntoRecord(
     }
   }
   if (recordHasBeenUpdated) {
-    let encounteredRecordsIds = insertIfNotExists(
+    let encounteredRecordsIds = insertEmptySetIfMissing(
       mutableEncounteredIds,
       targetParentRecordLink.__typename,
     );
@@ -447,7 +460,7 @@ function normalizeDataIntoRecord(
   return recordHasBeenUpdated;
 }
 
-export function insertIfNotExists<K, V>(map: Map<K, Set<V>>, key: K) {
+export function insertEmptySetIfMissing<K, V>(map: Map<K, Set<V>>, key: K) {
   let result = map.get(key);
   if (result === undefined) {
     result = new Set();
@@ -487,9 +500,8 @@ function normalizeLinkedField(
   astNode: NormalizationLinkedField,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
-  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
   const networkResponseKey = getNetworkResponseKey(astNode);
@@ -513,7 +525,7 @@ function normalizeLinkedField(
 
   if (Array.isArray(networkResponseData)) {
     // TODO check astNode.plural or the like
-    const dataIds: (Link | null)[] = [];
+    const dataIds: (StoreLink | null)[] = [];
     for (let i = 0; i < networkResponseData.length; i++) {
       const networkResponseObject = networkResponseData[i];
       if (networkResponseObject == null) {
@@ -527,7 +539,6 @@ function normalizeLinkedField(
         targetParentRecordLink,
         variables,
         i,
-        nestedRefetchQueries,
         mutableEncounteredIds,
       );
 
@@ -554,7 +565,6 @@ function normalizeLinkedField(
       targetParentRecordLink,
       variables,
       null,
-      nestedRefetchQueries,
       mutableEncounteredIds,
     );
 
@@ -586,9 +596,8 @@ function normalizeInlineFragment(
   astNode: NormalizationInlineFragment,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
-  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
   const typeToRefineTo = astNode.type;
@@ -600,7 +609,6 @@ function normalizeInlineFragment(
       targetParentRecord,
       targetParentRecordLink,
       variables,
-      nestedRefetchQueries,
       mutableEncounteredIds,
     );
     return hasBeenModified;
@@ -610,7 +618,7 @@ function normalizeInlineFragment(
 
 function dataIdsAreTheSame(
   existingValue: DataTypeValue,
-  newDataIds: (Link | null)[],
+  newDataIds: (StoreLink | null)[],
 ): boolean {
   if (Array.isArray(existingValue)) {
     if (newDataIds.length !== existingValue.length) {
@@ -635,10 +643,9 @@ function normalizeNetworkResponseObject(
   environment: IsographEnvironment,
   astNode: NormalizationLinkedField,
   networkResponseData: NetworkResponseObject,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
   index: number | null,
-  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
   mutableEncounteredIds: EncounteredIds,
 ): DataId /* The id of the modified or newly created item */ {
   const newStoreRecordId = getDataIdOfNetworkResponse(
@@ -668,7 +675,6 @@ function normalizeNetworkResponseObject(
     newStoreRecord,
     { __link: newStoreRecordId, __typename: __typename },
     variables,
-    nestedRefetchQueries,
     mutableEncounteredIds,
   );
 
@@ -760,13 +766,14 @@ function getStoreKeyChunkForArgumentValue(
 }
 
 function getStoreKeyChunkForArgument(argument: Argument, variables: Variables) {
-  let chunk = getStoreKeyChunkForArgumentValue(argument[1], variables);
+  const [argumentName, argumentValue] = argument;
+  let chunk = getStoreKeyChunkForArgumentValue(argumentValue, variables);
 
   if (typeof chunk === 'object') {
     chunk = JSON.stringify(stableCopy(chunk));
   }
 
-  return `${FIRST_SPLIT_KEY}${argument[0]}${SECOND_SPLIT_KEY}${chunk}`;
+  return `${FIRST_SPLIT_KEY}${argumentName}${SECOND_SPLIT_KEY}${chunk}`;
 }
 
 function getNetworkResponseKey(
@@ -831,7 +838,7 @@ export const THIRD_SPLIT_KEY = '__';
 
 // Returns a key to look up an item in the store
 function getDataIdOfNetworkResponse(
-  parentRecordLink: Link,
+  parentRecordLink: StoreLink,
   dataToNormalize: NetworkResponseObject,
   astNode: NormalizationLinkedField,
   variables: Variables,

package/src/core/check.ts

@@ -4,7 +4,7 @@ import { Variables } from './FragmentReference';
 import {
   getLink,
   IsographEnvironment,
-  Link,
+  StoreLink,
   StoreRecord,
 } from './IsographEnvironment';
 import { logMessage } from './logging';
@@ -30,14 +30,14 @@ export type CheckResult =
     }
   | {
       kind: 'MissingData';
-      record: Link;
+      record: StoreLink;
     };
 
 export function check(
   environment: IsographEnvironment,
   normalizationAst: NormalizationAstNodes,
   variables: Variables,
-  root: Link,
+  root: StoreLink,
 ): CheckResult {
   const recordsById = (environment.store[root.__typename] ??= {});
   const newStoreRecord = (recordsById[root.__link] ??= {});
@@ -61,7 +61,7 @@ function checkFromRecord(
   normalizationAst: NormalizationAstNodes,
   variables: Variables,
   record: StoreRecord,
-  recordLink: Link,
+  recordLink: StoreLink,
 ): CheckResult {
   normalizationAstLoop: for (const normalizationAstNode of normalizationAst) {
     switch (normalizationAstNode.kind) {

package/src/core/componentCache.ts

@@ -16,7 +16,11 @@ export function getOrCreateCachedComponent(
   networkRequestOptions: NetworkRequestReaderOptions,
 ): React.FC<any> {
   // We create startUpdate outside of component to make it stable
-  const startUpdate = createStartUpdate(environment, fragmentReference);
+  const startUpdate = createStartUpdate(
+    environment,
+    fragmentReference,
+    networkRequestOptions,
+  );
 
   return (environment.componentCache[
     stableIdForFragmentReference(fragmentReference, componentName)

package/src/core/entrypoint.ts

@@ -17,11 +17,39 @@ export type ReaderWithRefetchQueries<
   readonly nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[];
 };
 
+export type ReaderWithRefetchQueriesLoader<
+  TReadFromStore extends UnknownTReadFromStore,
+  TClientFieldValue,
+> = {
+  readonly kind: 'ReaderWithRefetchQueriesLoader';
+  readonly loader: () => Promise<
+    ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
+  >;
+};
+
 export type NetworkRequestInfo<TNormalizationAst> = {
   readonly kind: 'NetworkRequestInfo';
-  readonly queryText: string;
+  readonly operation: IsographOperation | IsographPersistedOperation;
   readonly normalizationAst: TNormalizationAst;
 };
+
+export type IsographOperation = {
+  readonly kind: 'Operation';
+  readonly text: string;
+};
+
+export type IsographPersistedOperation = {
+  readonly kind: 'PersistedOperation';
+  readonly operationId: string;
+  readonly extraInfo: IsographPersistedOperationExtraInfo | null;
+};
+
+export type IsographPersistedOperationExtraInfo = {
+  readonly kind: 'PersistedOperationExtraInfo';
+  readonly operationName: string | null;
+  readonly operationKind: 'Query' | 'Mutation' | 'Subscription';
+};
+
 // This type should be treated as an opaque type.
 export type IsographEntrypoint<
   TReadFromStore extends UnknownTReadFromStore,
@@ -30,10 +58,9 @@ export type IsographEntrypoint<
 > = {
   readonly kind: 'Entrypoint';
   readonly networkRequestInfo: NetworkRequestInfo<TNormalizationAst>;
-  readonly readerWithRefetchQueries: ReaderWithRefetchQueries<
-    TReadFromStore,
-    TClientFieldValue
-  >;
+  readonly readerWithRefetchQueries:
+    | ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
+    | ReaderWithRefetchQueriesLoader<TReadFromStore, TClientFieldValue>;
   readonly concreteType: TypeName;
 };
 

package/src/core/garbageCollection.ts

@@ -7,14 +7,14 @@ import {
   IsographEnvironment,
   IsographStore,
   StoreRecord,
-  type Link,
+  type StoreLink,
   type TypeName,
 } from './IsographEnvironment';
 
 export type RetainedQuery = {
   readonly normalizationAst: NormalizationAstNodes;
   readonly variables: {};
-  readonly root: Link;
+  readonly root: StoreLink;
 };
 
 export type DidUnretainSomeQuery = boolean;
@@ -117,7 +117,7 @@ function recordReachableIdsFromRecord(
         const linkKey = getParentRecordKey(selection, variables ?? {});
         const linkedFieldOrFields = currentRecord[linkKey];
 
-        const links: Link[] = [];
+        const links: StoreLink[] = [];
         if (Array.isArray(linkedFieldOrFields)) {
           for (const maybeLink of linkedFieldOrFields) {
             const link = assertLink(maybeLink);