@isograph/react 0.4.3 → 0.5.1

package/src/core/check.ts

@@ -1,28 +1,35 @@
 import { getParentRecordKey } from './cache';
-import { NormalizationAstNodes } from './entrypoint';
-import { Variables } from './FragmentReference';
-import {
-  getLink,
+import type { NormalizationAstNodes } from './entrypoint';
+import type { Variables } from './FragmentReference';
+import type {
   IsographEnvironment,
   StoreLink,
   StoreRecord,
 } from './IsographEnvironment';
+import { getLink } from './IsographEnvironment';
 import { logMessage } from './logging';
+import { getStoreRecordProxy } from './optimisticProxy';
 
 export type ShouldFetch = RequiredShouldFetch | 'IfNecessary';
 export type RequiredShouldFetch = 'Yes' | 'No';
 
 export const DEFAULT_SHOULD_FETCH_VALUE: ShouldFetch = 'IfNecessary';
 
-export type FetchOptions<TReadOutData> = {
-  shouldFetch?: ShouldFetch;
+type FetchOptionsShared<TReadOutData> = {
   onComplete?: (data: TReadOutData) => void;
   onError?: () => void;
 };
 
-export type RequiredFetchOptions<TReadOutData> = {
+export interface FetchOptions<TReadOutData, TRawResponseType>
+  extends FetchOptionsShared<TReadOutData> {
+  shouldFetch?: ShouldFetch;
+  optimisticNetworkResponse?: TRawResponseType;
+}
+
+export interface RequiredFetchOptions<TReadOutData>
+  extends FetchOptionsShared<TReadOutData> {
   shouldFetch: RequiredShouldFetch;
-} & FetchOptions<TReadOutData>;
+}
 
 export type CheckResult =
   | {
@@ -39,8 +46,14 @@ export function check(
   variables: Variables,
   root: StoreLink,
 ): CheckResult {
-  const recordsById = (environment.store[root.__typename] ??= {});
-  const newStoreRecord = (recordsById[root.__link] ??= {});
+  const newStoreRecord = getStoreRecordProxy(environment.store, root);
+
+  if (newStoreRecord == null) {
+    return {
+      kind: 'MissingData',
+      record: root,
+    };
+  }
 
   const checkResult = checkFromRecord(
     environment,
@@ -95,27 +108,26 @@ function checkFromRecord(
             kind: 'MissingData',
             record: recordLink,
           };
-        } else if (linkedValue === null) {
+        } else if (linkedValue == null) {
           continue;
         } else if (Array.isArray(linkedValue)) {
           arrayItemsLoop: for (const item of linkedValue) {
             const link = getLink(item);
-            if (link === null) {
+            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.__typename]?.[link.__link];
+            const linkedRecord = getStoreRecordProxy(environment.store, link);
 
             if (linkedRecord === undefined) {
               return {
                 kind: 'MissingData',
                 record: link,
               };
-            } else if (linkedRecord === null) {
+            } else if (linkedRecord == null) {
               continue arrayItemsLoop;
             } else {
               // TODO in __DEV__ assert linkedRecord is an object
@@ -134,22 +146,21 @@ function checkFromRecord(
           }
         } else {
           const link = getLink(linkedValue);
-          if (link === null) {
+          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.__typename]?.[link.__link];
+          const linkedRecord = getStoreRecordProxy(environment.store, link);
 
           if (linkedRecord === undefined) {
             return {
               kind: 'MissingData',
               record: link,
             };
-          } else if (linkedRecord === null) {
+          } else if (linkedRecord == null) {
             continue normalizationAstLoop;
           } else {
             // TODO in __DEV__ assert linkedRecord is an object
@@ -195,13 +206,6 @@ function checkFromRecord(
 
         continue normalizationAstLoop;
       }
-      default: {
-        let _: never = normalizationAstNode;
-        _;
-        throw new Error(
-          'Unexpected case. This is indicative of a bug in Isograph.',
-        );
-      }
     }
   }
 

package/src/core/componentCache.ts

@@ -1,17 +1,11 @@
-import { useReadAndSubscribe } from '../react/useReadAndSubscribe';
-import {
-  FragmentReference,
-  stableIdForFragmentReference,
-} from './FragmentReference';
-import { IsographEnvironment } from './IsographEnvironment';
-import { logMessage } from './logging';
-import { readPromise } from './PromiseWrapper';
-import { NetworkRequestReaderOptions } from './read';
+import type { FragmentReference } from './FragmentReference';
+import { stableIdForFragmentReference } from './FragmentReference';
+import type { IsographEnvironment } from './IsographEnvironment';
+import type { NetworkRequestReaderOptions } from './read';
 import { createStartUpdate } from './startUpdate';
 
 export function getOrCreateCachedComponent(
   environment: IsographEnvironment,
-  componentName: string,
   fragmentReference: FragmentReference<any, any>,
   networkRequestOptions: NetworkRequestReaderOptions,
 ): React.FC<any> {
@@ -23,38 +17,11 @@ export function getOrCreateCachedComponent(
   );
 
   return (environment.componentCache[
-    stableIdForFragmentReference(fragmentReference, componentName)
-  ] ??= (() => {
-    function Component(additionalRuntimeProps: { [key: string]: any }) {
-      const readerWithRefetchQueries = readPromise(
-        fragmentReference.readerWithRefetchQueries,
-      );
-
-      const data = useReadAndSubscribe(
-        fragmentReference,
-        networkRequestOptions,
-        readerWithRefetchQueries.readerArtifact.readerAst,
-      );
-
-      logMessage(environment, () => ({
-        kind: 'ComponentRerendered',
-        componentName,
-        rootLink: fragmentReference.root,
-      }));
-
-      return readerWithRefetchQueries.readerArtifact.resolver(
-        {
-          data,
-          parameters: fragmentReference.variables,
-          startUpdate: readerWithRefetchQueries.readerArtifact.hasUpdatable
-            ? startUpdate
-            : undefined,
-        },
-        additionalRuntimeProps,
-      );
-    }
-    const idString = `(type: ${fragmentReference.root.__typename}, id: ${fragmentReference.root.__link})`;
-    Component.displayName = `${componentName} ${idString} @component`;
-    return Component;
-  })());
+    stableIdForFragmentReference(fragmentReference)
+  ] ??= environment.componentFunction(
+    environment,
+    fragmentReference,
+    networkRequestOptions,
+    startUpdate,
+  ));
 }

package/src/core/entrypoint.ts

@@ -1,7 +1,12 @@
-import type { UnknownTReadFromStore } from './FragmentReference';
-import type { TypeName } from './IsographEnvironment';
-import { TopLevelReaderArtifact } from './reader';
-import { Arguments } from './util';
+import type { Contravariant, PhantomData } from './brand';
+import type { NetworkResponseObject } from './cache';
+import type {
+  FragmentReference,
+  UnknownTReadFromStore,
+} from './FragmentReference';
+import type { ComponentOrFieldName, TypeName } from './IsographEnvironment';
+import type { TopLevelReaderArtifact } from './reader';
+import type { Arguments } from './util';
 
 export type ReaderWithRefetchQueries<
   TReadFromStore extends UnknownTReadFromStore,
@@ -22,6 +27,10 @@ export type ReaderWithRefetchQueriesLoader<
   TClientFieldValue,
 > = {
   readonly kind: 'ReaderWithRefetchQueriesLoader';
+  readonly fieldName: ComponentOrFieldName;
+  readonly readerArtifactKind:
+    | 'EagerReaderArtifact'
+    | 'ComponentReaderArtifact';
   readonly loader: () => Promise<
     ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
   >;
@@ -55,6 +64,7 @@ export type IsographEntrypoint<
   TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
   TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
+  TRawResponseType extends NetworkResponseObject,
 > = {
   readonly kind: 'Entrypoint';
   readonly networkRequestInfo: NetworkRequestInfo<TNormalizationAst>;
@@ -62,16 +72,36 @@ export type IsographEntrypoint<
     | ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
     | ReaderWithRefetchQueriesLoader<TReadFromStore, TClientFieldValue>;
   readonly concreteType: TypeName;
+  /**
+   * This field exists solely for typechecking, and will not exist at runtime.
+   */
+  readonly '~TRawResponseType'?: PhantomData<Contravariant<TRawResponseType>>;
 };
 
+export type FragmentReferenceOfEntrypoint<
+  TEntrypoint extends IsographEntrypoint<any, any, any, any>,
+> = FragmentReference<
+  ExtractReadFromStore<TEntrypoint>,
+  ExtractClientFieldValue<TEntrypoint>
+>;
+
 export type IsographEntrypointLoader<
   TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
+  TRawResponseType extends NetworkResponseObject,
 > = {
   readonly kind: 'EntrypointLoader';
   readonly typeAndField: string;
+  readonly readerArtifactKind:
+    | 'EagerReaderArtifact'
+    | 'ComponentReaderArtifact';
   readonly loader: () => Promise<
-    IsographEntrypoint<TReadFromStore, TClientFieldValue, NormalizationAst>
+    IsographEntrypoint<
+      TReadFromStore,
+      TClientFieldValue,
+      NormalizationAst,
+      TRawResponseType
+    >
   >;
 };
 
@@ -129,9 +159,15 @@ export function assertIsEntrypoint<
   TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
   TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
+  TRawResponseType extends NetworkResponseObject,
 >(
   value:
-    | IsographEntrypoint<TReadFromStore, TClientFieldValue, TNormalizationAst>
+    | IsographEntrypoint<
+        TReadFromStore,
+        TClientFieldValue,
+        TNormalizationAst,
+        TRawResponseType
+      >
     | ((_: any) => any)
     // Temporarily, allow any here. Once we automatically provide
     // types to entrypoints, we probably don't need this.
@@ -139,13 +175,18 @@ export function assertIsEntrypoint<
 ): asserts value is IsographEntrypoint<
   TReadFromStore,
   TClientFieldValue,
-  TNormalizationAst
+  TNormalizationAst,
+  TRawResponseType
 > {
   if (typeof value === 'function') throw new Error('Not a string');
 }
 
 export type ExtractReadFromStore<Type> =
-  Type extends IsographEntrypoint<infer X, any, any> ? X : never;
+  Type extends IsographEntrypoint<infer X, any, any, any> ? X : never;
+export type ExtractClientFieldValue<Type> =
+  Type extends IsographEntrypoint<any, infer X, any, any> ? X : never;
+export type ExtractRawResponseType<Type> =
+  Type extends IsographEntrypoint<any, any, any, infer X> ? X : never;
 export type ExtractResolverResult<Type> =
-  Type extends IsographEntrypoint<any, infer X, any> ? X : never;
+  Type extends IsographEntrypoint<any, infer X, any, any> ? X : never;
 export type ExtractProps<Type> = Type extends React.FC<infer X> ? X : never;

package/src/core/garbageCollection.ts

@@ -1,22 +1,41 @@
-import { getParentRecordKey } from './cache';
-import { NormalizationAstNodes } from './entrypoint';
-import { Variables } from './FragmentReference';
+import { getParentRecordKey, TYPENAME_FIELD_NAME } from './cache';
+import type { NormalizationAstNodes, NormalizationAst } from './entrypoint';
+import type { Variables } from './FragmentReference';
 import {
   assertLink,
-  DataId,
-  IsographEnvironment,
-  IsographStore,
-  StoreRecord,
+  type DataId,
+  type IsographEnvironment,
+  type StoreRecord,
+  type StoreLayerData,
   type StoreLink,
   type TypeName,
 } from './IsographEnvironment';
+import type { BaseStoreLayer } from './optimisticProxy';
+import {
+  NOT_SET,
+  type PromiseWrapper,
+  type PromiseWrapperOk,
+} from './PromiseWrapper';
 
 export type RetainedQuery = {
-  readonly normalizationAst: NormalizationAstNodes;
+  readonly normalizationAst: PromiseWrapper<NormalizationAst>;
   readonly variables: {};
   readonly root: StoreLink;
 };
 
+export interface RetainedQueryWithNormalizationAst extends RetainedQuery {
+  readonly normalizationAst: PromiseWrapperOk<NormalizationAst>;
+}
+
+function isRetainedQueryWithNormalizationAst(
+  query: RetainedQuery,
+): query is RetainedQueryWithNormalizationAst {
+  return (
+    query.normalizationAst.result !== NOT_SET &&
+    query.normalizationAst.result.kind === 'Ok'
+  );
+}
+
 export type DidUnretainSomeQuery = boolean;
 export function unretainQuery(
   environment: IsographEnvironment,
@@ -44,23 +63,46 @@ export function retainQuery(
 }
 
 export function garbageCollectEnvironment(environment: IsographEnvironment) {
-  const retainedIds: RetainedIds = {};
+  if (environment.store.kind !== 'BaseStoreLayer') {
+    return;
+  }
 
+  const retainedQueries: RetainedQueryWithNormalizationAst[] = [];
   for (const query of environment.retainedQueries) {
-    recordReachableIds(environment.store, query, retainedIds);
+    if (!isRetainedQueryWithNormalizationAst(query)) {
+      return;
+    }
+    retainedQueries.push(query);
   }
+
   for (const query of environment.gcBuffer) {
-    recordReachableIds(environment.store, query, retainedIds);
+    if (!isRetainedQueryWithNormalizationAst(query)) {
+      return;
+    }
+    retainedQueries.push(query);
   }
 
-  for (const typeName in environment.store) {
-    const dataById = environment.store[typeName];
+  garbageCollectBaseStoreLayer(retainedQueries, environment.store);
+}
+
+export function garbageCollectBaseStoreLayer(
+  retainedQueries: RetainedQueryWithNormalizationAst[],
+  baseStoreLayer: BaseStoreLayer,
+) {
+  const retainedIds: RetainedIds = {};
+
+  for (const query of retainedQueries) {
+    recordReachableIds(baseStoreLayer.data, query, retainedIds);
+  }
+
+  for (const typeName in baseStoreLayer.data) {
+    const dataById = baseStoreLayer.data[typeName];
     if (dataById == null) continue;
     const retainedTypeIds = retainedIds[typeName];
 
     // delete all objects
-    if (retainedTypeIds == undefined || retainedTypeIds.size == 0) {
-      delete environment.store[typeName];
+    if (retainedTypeIds === undefined || retainedTypeIds.size === 0) {
+      delete baseStoreLayer.data[typeName];
       continue;
     }
 
@@ -71,7 +113,7 @@ export function garbageCollectEnvironment(environment: IsographEnvironment) {
     }
 
     if (Object.keys(dataById).length === 0) {
-      delete environment.store[typeName];
+      delete baseStoreLayer.data[typeName];
     }
   }
 }
@@ -81,31 +123,31 @@ interface RetainedIds {
 }
 
 function recordReachableIds(
-  store: IsographStore,
-  retainedQuery: RetainedQuery,
+  dataLayer: StoreLayerData,
+  retainedQuery: RetainedQueryWithNormalizationAst,
   mutableRetainedIds: RetainedIds,
 ) {
   const record =
-    store[retainedQuery.root.__typename]?.[retainedQuery.root.__link];
+    dataLayer[retainedQuery.root.__typename]?.[retainedQuery.root.__link];
 
   const retainedRecordsIds = (mutableRetainedIds[
     retainedQuery.root.__typename
   ] ??= new Set());
   retainedRecordsIds.add(retainedQuery.root.__link);
 
-  if (record) {
+  if (record != null) {
     recordReachableIdsFromRecord(
-      store,
+      dataLayer,
       record,
       mutableRetainedIds,
-      retainedQuery.normalizationAst,
+      retainedQuery.normalizationAst.result.value.selections,
       retainedQuery.variables,
     );
   }
 }
 
 function recordReachableIdsFromRecord(
-  store: IsographStore,
+  dataLayer: StoreLayerData,
   currentRecord: StoreRecord,
   mutableRetainedIds: RetainedIds,
   selections: NormalizationAstNodes,
@@ -113,6 +155,17 @@ function recordReachableIdsFromRecord(
 ) {
   for (const selection of selections) {
     switch (selection.kind) {
+      case 'InlineFragment':
+        if (currentRecord[TYPENAME_FIELD_NAME] === selection.type) {
+          recordReachableIdsFromRecord(
+            dataLayer,
+            currentRecord,
+            mutableRetainedIds,
+            selection.selections,
+            variables,
+          );
+        }
+        continue;
       case 'Linked':
         const linkKey = getParentRecordKey(selection, variables ?? {});
         const linkedFieldOrFields = currentRecord[linkKey];
@@ -133,18 +186,18 @@ function recordReachableIdsFromRecord(
         }
 
         let typeStore =
-          selection.concreteType !== null
-            ? store[selection.concreteType]
+          selection.concreteType != null
+            ? dataLayer[selection.concreteType]
             : null;
 
-        if (typeStore == null && selection.concreteType !== null) {
+        if (typeStore == null && selection.concreteType != null) {
           continue;
         }
 
         for (const nextRecordLink of links) {
           let __typename = nextRecordLink.__typename;
 
-          const resolvedTypeStore = typeStore ?? store[__typename];
+          const resolvedTypeStore = typeStore ?? dataLayer[__typename];
 
           if (resolvedTypeStore == null) {
             continue;
@@ -156,7 +209,7 @@ function recordReachableIdsFromRecord(
               new Set());
             retainedRecordsIds.add(nextRecordLink.__link);
             recordReachableIdsFromRecord(
-              store,
+              dataLayer,
               nextRecord,
               mutableRetainedIds,
               selection.selections,

package/src/core/getOrCreateCacheForArtifact.ts

@@ -0,0 +1,86 @@
+import type { ItemCleanupPair } from '@isograph/isograph-disposable-types/dist';
+import type { ParentCache } from '@isograph/isograph-react-disposable-state/dist';
+import {
+  type NetworkResponseObject,
+  getOrCreateItemInSuspenseCache,
+} from './cache';
+import type { FetchOptions } from './check';
+import type {
+  IsographEntrypoint,
+  NormalizationAst,
+  NormalizationAstLoader,
+} from './entrypoint';
+import type {
+  ExtractParameters,
+  FragmentReference,
+  UnknownTReadFromStore,
+} from './FragmentReference';
+import {
+  type IsographEnvironment,
+  getOrLoadReaderWithRefetchQueries,
+  ROOT_ID,
+} from './IsographEnvironment';
+import { maybeMakeNetworkRequest } from './makeNetworkRequest';
+import { stableCopy } from './util';
+
+export function getOrCreateCacheForArtifact<
+  TReadFromStore extends UnknownTReadFromStore,
+  TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
+  TRawResponseType extends NetworkResponseObject,
+>(
+  environment: IsographEnvironment,
+  entrypoint: IsographEntrypoint<
+    TReadFromStore,
+    TClientFieldValue,
+    TNormalizationAst,
+    TRawResponseType
+  >,
+  variables: ExtractParameters<TReadFromStore>,
+  fetchOptions?: FetchOptions<TClientFieldValue, TRawResponseType>,
+): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
+  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 { fieldName, readerArtifactKind, readerWithRefetchQueries } =
+      getOrLoadReaderWithRefetchQueries(
+        environment,
+        entrypoint.readerWithRefetchQueries,
+      );
+    const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
+      environment,
+      entrypoint,
+      variables,
+      readerWithRefetchQueries,
+      fetchOptions ?? null,
+    );
+
+    const itemCleanupPair: ItemCleanupPair<
+      FragmentReference<TReadFromStore, TClientFieldValue>
+    > = [
+      {
+        kind: 'FragmentReference',
+        readerWithRefetchQueries,
+        fieldName,
+        readerArtifactKind,
+        root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
+        variables,
+        networkRequest: networkRequest,
+      },
+      disposeNetworkRequest,
+    ];
+    return itemCleanupPair;
+  };
+  return getOrCreateItemInSuspenseCache(environment, cacheKey, factory);
+}

package/src/core/logging.ts

@@ -1,21 +1,33 @@
-import { CleanupFn } from '@isograph/disposable-types';
-import { NetworkResponseObject, type EncounteredIds } from './cache';
-import { CheckResult } from './check';
-import {
+import type { CleanupFn } from '@isograph/disposable-types';
+import type { NetworkResponseObject, EncounteredIds } from './cache';
+import type { CheckResult } from './check';
+import type {
   IsographEntrypoint,
   RefetchQueryNormalizationArtifact,
-  type NormalizationAstNodes,
+  NormalizationAstNodes,
 } from './entrypoint';
-import { FragmentReference, Variables } from './FragmentReference';
-import {
+import type { FragmentReference, Variables } from './FragmentReference';
+import type {
   IsographEnvironment,
-  IsographStore,
   StoreRecord,
-  type StoreLink,
+  StoreLink,
 } from './IsographEnvironment';
-import { ReadDataResult } from './read';
-import { Arguments } from './util';
+import type { ReadDataResult } from './read';
+import type { Arguments } from './util';
+import type { StoreLayer } from './optimisticProxy';
 
+/**
+ * Note: these types are unstable. We will add and remove items from this enum
+ * and add and remove fields. Please do not rely on the specifics here (for now).
+ *
+ * Goals include:
+ * - convenient debugging for Isograph developers
+ * - eventual support for the Isograph devtools
+ *
+ * In some cases (e.g. in `AfterNormalization`), we include large objects and thus
+ * prevent them from getting garbage collected (if the log message is printed).
+ * Especially in cases like that, we intend to remove those!
+ */
 export type LogMessage =
   | {
       kind: 'AboutToNormalize';
@@ -25,7 +37,7 @@ export type LogMessage =
     }
   | {
       kind: 'AfterNormalization';
-      store: IsographStore;
+      store: StoreLayer;
       encounteredIds: EncounteredIds;
     }
   | {
@@ -44,7 +56,7 @@ export type LogMessage =
       kind: 'MakeNetworkRequest';
       artifact:
         | RefetchQueryNormalizationArtifact
-        | IsographEntrypoint<any, any, any>;
+        | IsographEntrypoint<any, any, any, any>;
       variables: Variables;
       networkRequestId: string;
     }