@isograph/react 0.3.0 → 0.3.1

package/src/core/cache.ts

@@ -3,56 +3,53 @@ import {
   ItemCleanupPair,
   ParentCache,
 } from '@isograph/react-disposable-state';
-import {
-  DataId,
-  Link,
-  ROOT_ID,
-  StoreRecord,
-  type IsographEnvironment,
-  DataTypeValue,
-  getLink,
-  FragmentSubscription,
-  type TypeName,
-} from './IsographEnvironment';
 import {
   IsographEntrypoint,
-  NormalizationAst,
   NormalizationInlineFragment,
   NormalizationLinkedField,
   NormalizationScalarField,
   RefetchQueryNormalizationArtifactWrapper,
+  type NormalizationAst,
+  type NormalizationAstLoader,
+  type NormalizationAstNodes,
 } from '../core/entrypoint';
-import { ReaderLinkedField, ReaderScalarField, type ReaderAst } from './reader';
-import { Argument, ArgumentValue } from './util';
-import { WithEncounteredRecords, readButDoNotEvaluate } from './read';
+import { mergeObjectsUsingReaderAst } from './areEqualWithDeepComparison';
+import { FetchOptions } from './check';
 import {
+  ExtractParameters,
   FragmentReference,
   Variables,
-  ExtractParameters,
+  type UnknownTReadFromStore,
+  type VariableValue,
 } from './FragmentReference';
-import { mergeObjectsUsingReaderAst } from './areEqualWithDeepComparison';
+import {
+  DataId,
+  DataTypeValue,
+  FragmentSubscription,
+  getLink,
+  Link,
+  ROOT_ID,
+  StoreRecord,
+  type IsographEnvironment,
+  type TypeName,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
 import { maybeMakeNetworkRequest } from './makeNetworkRequest';
 import { wrapResolvedValue } from './PromiseWrapper';
-import { logMessage } from './logging';
-import { FetchOptions } from './check';
+import { readButDoNotEvaluate, WithEncounteredRecords } from './read';
+import { ReaderLinkedField, ReaderScalarField, type ReaderAst } from './reader';
+import { Argument, ArgumentValue } from './util';
 
 export const TYPENAME_FIELD_NAME = '__typename';
 
 export function getOrCreateItemInSuspenseCache<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 >(
   environment: IsographEnvironment,
   index: string,
   factory: Factory<FragmentReference<TReadFromStore, TClientFieldValue>>,
 ): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
-  // TODO this is probably a useless message, we should remove it
-  logMessage(environment, {
-    kind: 'GettingSuspenseCacheItem',
-    index,
-    availableCacheItems: Object.keys(environment.fragmentCache),
-    found: !!environment.fragmentCache[index],
-  });
   if (environment.fragmentCache[index] == null) {
     environment.fragmentCache[index] = new ParentCache(factory);
   }
@@ -83,13 +80,18 @@ export function stableCopy<T>(value: T): T {
 }
 
 export function getOrCreateCacheForArtifact<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
 >(
   environment: IsographEnvironment,
-  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+  entrypoint: IsographEntrypoint<
+    TReadFromStore,
+    TClientFieldValue,
+    TNormalizationAst
+  >,
   variables: ExtractParameters<TReadFromStore>,
-  fetchOptions?: FetchOptions,
+  fetchOptions?: FetchOptions<TClientFieldValue>,
 ): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
   const cacheKey =
     entrypoint.networkRequestInfo.queryText +
@@ -124,8 +126,8 @@ export function getOrCreateCacheForArtifact<
   return getOrCreateItemInSuspenseCache(environment, cacheKey, factory);
 }
 
-type NetworkResponseScalarValue = string | number | boolean;
-type NetworkResponseValue =
+export type NetworkResponseScalarValue = string | number | boolean;
+export type NetworkResponseValue =
   | NetworkResponseScalarValue
   | null
   | NetworkResponseObject
@@ -142,7 +144,7 @@ export type NetworkResponseObject = {
 
 export function normalizeData(
   environment: IsographEnvironment,
-  normalizationAst: NormalizationAst,
+  normalizationAst: NormalizationAstNodes,
   networkResponse: NetworkResponseObject,
   variables: Variables,
   nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
@@ -150,12 +152,12 @@ export function normalizeData(
 ): EncounteredIds {
   const encounteredIds: EncounteredIds = new Map();
 
-  logMessage(environment, {
+  logMessage(environment, () => ({
     kind: 'AboutToNormalize',
     normalizationAst,
     networkResponse,
     variables,
-  });
+  }));
 
   const recordsById = (environment.store[root.__typename] ??= {});
   const newStoreRecord = (recordsById[root.__link] ??= {});
@@ -171,11 +173,11 @@ export function normalizeData(
     encounteredIds,
   );
 
-  logMessage(environment, {
+  logMessage(environment, () => ({
     kind: 'AfterNormalization',
     store: environment.store,
     encounteredIds,
-  });
+  }));
 
   callSubscriptions(environment, encounteredIds);
   return encounteredIds;
@@ -208,9 +210,7 @@ export function subscribeToAnyChangesToRecord(
 }
 
 // TODO we should re-read and call callback if the value has changed
-export function subscribe<
-  TReadFromStore extends { parameters: object; data: object },
->(
+export function subscribe<TReadFromStore extends UnknownTReadFromStore>(
   environment: IsographEnvironment,
   encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
   fragmentReference: FragmentReference<TReadFromStore, any>,
@@ -303,14 +303,14 @@ function callSubscriptions(
               newEncounteredDataAndRecords.item,
             );
 
-            logMessage(environment, {
+            logMessage(environment, () => ({
               kind: 'DeepEqualityCheck',
               fragmentReference: subscription.fragmentReference,
               old: subscription.encounteredDataAndRecords.item,
               new: newEncounteredDataAndRecords.item,
               deeplyEqual:
                 mergedItem === subscription.encounteredDataAndRecords.item,
-            });
+            }));
 
             if (mergedItem !== subscription.encounteredDataAndRecords.item) {
               subscription.callback(newEncounteredDataAndRecords);
@@ -376,7 +376,7 @@ export type EncounteredIds = Map<TypeName, Set<DataId>>;
  */
 function normalizeDataIntoRecord(
   environment: IsographEnvironment,
-  normalizationAst: NormalizationAst,
+  normalizationAst: NormalizationAstNodes,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
   targetParentRecordLink: Link,
@@ -724,8 +724,19 @@ export function getParentRecordKey(
 function getStoreKeyChunkForArgumentValue(
   argumentValue: ArgumentValue,
   variables: Variables,
-) {
+): VariableValue {
   switch (argumentValue.kind) {
+    case 'Object': {
+      return Object.fromEntries(
+        argumentValue.value.map(([argumentName, argumentValue]) => {
+          return [
+            argumentName,
+            //  substitute variables
+            getStoreKeyChunkForArgumentValue(argumentValue, variables),
+          ];
+        }),
+      );
+    }
     case 'Literal': {
       return argumentValue.value;
     }
@@ -749,7 +760,12 @@ function getStoreKeyChunkForArgumentValue(
 }
 
 function getStoreKeyChunkForArgument(argument: Argument, variables: Variables) {
-  const chunk = getStoreKeyChunkForArgumentValue(argument[1], variables);
+  let chunk = getStoreKeyChunkForArgumentValue(argument[1], variables);
+
+  if (typeof chunk === 'object') {
+    chunk = JSON.stringify(stableCopy(chunk));
+  }
+
   return `${FIRST_SPLIT_KEY}${argument[0]}${SECOND_SPLIT_KEY}${chunk}`;
 }
 
@@ -758,43 +774,60 @@ function getNetworkResponseKey(
 ): string {
   let networkResponseKey = astNode.fieldName;
   const fieldParameters = astNode.arguments;
+
   if (fieldParameters != null) {
-    for (const fieldParameter of fieldParameters) {
-      const [argumentName, argumentValue] = fieldParameter;
-      let argumentValueChunk;
-      switch (argumentValue.kind) {
-        case 'Literal': {
-          argumentValueChunk = 'l_' + argumentValue.value;
-          break;
-        }
-        case 'Variable': {
-          argumentValueChunk = 'v_' + argumentValue.name;
-          break;
-        }
-        case 'String': {
-          argumentValueChunk = 's_' + argumentValue.value;
-          break;
-        }
-        case 'Enum': {
-          argumentValueChunk = 'e_' + argumentValue.value;
-          break;
-        }
-        default: {
-          // Ensure we have covered all variants
-          let _: never = argumentValue;
-          _;
-          throw new Error('Unexpected case');
-        }
-      }
+    for (const [argumentName, argumentValue] of fieldParameters) {
+      let argumentValueChunk = getArgumentValueChunk(argumentValue);
       networkResponseKey += `${FIRST_SPLIT_KEY}${argumentName}${SECOND_SPLIT_KEY}${argumentValueChunk}`;
     }
   }
+
   return networkResponseKey;
 }
 
+function getArgumentValueChunk(argumentValue: ArgumentValue): string {
+  switch (argumentValue.kind) {
+    case 'Object': {
+      return (
+        'o_' +
+        argumentValue.value
+          .map(([argumentName, argumentValue]) => {
+            return (
+              argumentName +
+              THIRD_SPLIT_KEY +
+              getArgumentValueChunk(argumentValue)
+            );
+          })
+          .join('_') +
+        '_c'
+      );
+    }
+    case 'Literal': {
+      return 'l_' + argumentValue.value;
+    }
+    case 'Variable': {
+      return 'v_' + argumentValue.name;
+    }
+    case 'String': {
+      // replace all non-word characters (alphanumeric & underscore) with underscores
+      return 's_' + argumentValue.value.replaceAll(/\W/g, '_');
+    }
+    case 'Enum': {
+      return 'e_' + argumentValue.value;
+    }
+    default: {
+      // Ensure we have covered all variants
+      let _: never = argumentValue;
+      _;
+      throw new Error('Unexpected case');
+    }
+  }
+}
+
 // an alias might be pullRequests____first___first____after___cursor
 export const FIRST_SPLIT_KEY = '____';
 export const SECOND_SPLIT_KEY = '___';
+export const THIRD_SPLIT_KEY = '__';
 
 // Returns a key to look up an item in the store
 function getDataIdOfNetworkResponse(

package/src/core/check.ts

@@ -1,5 +1,5 @@
 import { getParentRecordKey } from './cache';
-import { NormalizationAst } from './entrypoint';
+import { NormalizationAstNodes } from './entrypoint';
 import { Variables } from './FragmentReference';
 import {
   getLink,
@@ -9,16 +9,21 @@ import {
 } from './IsographEnvironment';
 import { logMessage } from './logging';
 
-export type ShouldFetch = 'Yes' | 'No' | 'IfNecessary';
+export type ShouldFetch = RequiredShouldFetch | 'IfNecessary';
+export type RequiredShouldFetch = 'Yes' | 'No';
 
 export const DEFAULT_SHOULD_FETCH_VALUE: ShouldFetch = 'IfNecessary';
 
-export type FetchOptions = {
+export type FetchOptions<TReadOutData> = {
   shouldFetch?: ShouldFetch;
-  onComplete?: () => void;
+  onComplete?: (data: TReadOutData) => void;
   onError?: () => void;
 };
 
+export type RequiredFetchOptions<TReadOutData> = {
+  shouldFetch: RequiredShouldFetch;
+} & FetchOptions<TReadOutData>;
+
 export type CheckResult =
   | {
       kind: 'EnoughData';
@@ -30,7 +35,7 @@ export type CheckResult =
 
 export function check(
   environment: IsographEnvironment,
-  normalizationAst: NormalizationAst,
+  normalizationAst: NormalizationAstNodes,
   variables: Variables,
   root: Link,
 ): CheckResult {
@@ -44,16 +49,16 @@ export function check(
     newStoreRecord,
     root,
   );
-  logMessage(environment, {
+  logMessage(environment, () => ({
     kind: 'EnvironmentCheck',
     result: checkResult,
-  });
+  }));
   return checkResult;
 }
 
 function checkFromRecord(
   environment: IsographEnvironment,
-  normalizationAst: NormalizationAst,
+  normalizationAst: NormalizationAstNodes,
   variables: Variables,
   record: StoreRecord,
   recordLink: Link,

package/src/core/componentCache.ts

@@ -1,10 +1,13 @@
-import { stableCopy } from './cache';
-import { IsographEnvironment } from './IsographEnvironment';
-import { FragmentReference } from './FragmentReference';
 import { useReadAndSubscribe } from '../react/useReadAndSubscribe';
-import { NetworkRequestReaderOptions } from './read';
-import { readPromise } from './PromiseWrapper';
+import {
+  FragmentReference,
+  stableIdForFragmentReference,
+} from './FragmentReference';
+import { IsographEnvironment } from './IsographEnvironment';
 import { logMessage } from './logging';
+import { readPromise } from './PromiseWrapper';
+import { NetworkRequestReaderOptions } from './read';
+import { createStartUpdate } from './startUpdate';
 
 export function getOrCreateCachedComponent(
   environment: IsographEnvironment,
@@ -12,51 +15,41 @@ export function getOrCreateCachedComponent(
   fragmentReference: FragmentReference<any, any>,
   networkRequestOptions: NetworkRequestReaderOptions,
 ): React.FC<any> {
-  // cachedComponentsById is a three layer cache: id, then component name, then
-  // stringified args. These three, together, uniquely identify a read at a given
-  // time.
-  const cachedComponentsById = environment.componentCache;
-
-  const recordLink = fragmentReference.root.__link;
-
-  const componentsByName = (cachedComponentsById[recordLink] ??= {});
-
-  componentsByName[componentName] = componentsByName[componentName] ?? {};
-  const byArgs = componentsByName[componentName];
-
-  const stringifiedArgs = JSON.stringify(
-    stableCopy(fragmentReference.variables),
-  );
-  byArgs[stringifiedArgs] =
-    byArgs[stringifiedArgs] ??
-    (() => {
-      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,
-          },
-          additionalRuntimeProps,
-        );
-      }
-      Component.displayName = `${componentName} (id: ${fragmentReference.root}) @component`;
-      return Component;
-    })();
-  return byArgs[stringifiedArgs];
+  // We create startUpdate outside of component to make it stable
+  const startUpdate = createStartUpdate(environment, fragmentReference);
+
+  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,
+      );
+    }
+    Component.displayName = `${componentName} (id: ${fragmentReference.root}) @component`;
+    return Component;
+  })());
 }

package/src/core/entrypoint.ts

@@ -1,9 +1,10 @@
+import type { UnknownTReadFromStore } from './FragmentReference';
 import type { TypeName } from './IsographEnvironment';
 import { TopLevelReaderArtifact } from './reader';
 import { Arguments } from './util';
 
 export type ReaderWithRefetchQueries<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 > = {
   readonly kind: 'ReaderWithRefetchQueries';
@@ -16,18 +17,19 @@ export type ReaderWithRefetchQueries<
   readonly nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[];
 };
 
-export type NetworkRequestInfo = {
+export type NetworkRequestInfo<TNormalizationAst> = {
   readonly kind: 'NetworkRequestInfo';
   readonly queryText: string;
-  readonly normalizationAst: NormalizationAst;
+  readonly normalizationAst: TNormalizationAst;
 };
 // This type should be treated as an opaque type.
 export type IsographEntrypoint<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
 > = {
   readonly kind: 'Entrypoint';
-  readonly networkRequestInfo: NetworkRequestInfo;
+  readonly networkRequestInfo: NetworkRequestInfo<TNormalizationAst>;
   readonly readerWithRefetchQueries: ReaderWithRefetchQueries<
     TReadFromStore,
     TClientFieldValue
@@ -36,13 +38,13 @@ export type IsographEntrypoint<
 };
 
 export type IsographEntrypointLoader<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 > = {
   readonly kind: 'EntrypointLoader';
   readonly typeAndField: string;
   readonly loader: () => Promise<
-    IsographEntrypoint<TReadFromStore, TClientFieldValue>
+    IsographEntrypoint<TReadFromStore, TClientFieldValue, NormalizationAst>
   >;
 };
 
@@ -50,7 +52,18 @@ export type NormalizationAstNode =
   | NormalizationScalarField
   | NormalizationLinkedField
   | NormalizationInlineFragment;
-export type NormalizationAst = ReadonlyArray<NormalizationAstNode>;
+
+export type NormalizationAstNodes = ReadonlyArray<NormalizationAstNode>;
+
+export type NormalizationAst = {
+  readonly kind: 'NormalizationAst';
+  readonly selections: NormalizationAstNodes;
+};
+
+export type NormalizationAstLoader = {
+  readonly kind: 'NormalizationAstLoader';
+  readonly loader: () => Promise<NormalizationAst>;
+};
 
 export type NormalizationScalarField = {
   readonly kind: 'Scalar';
@@ -62,20 +75,20 @@ export type NormalizationLinkedField = {
   readonly kind: 'Linked';
   readonly fieldName: string;
   readonly arguments: Arguments | null;
-  readonly selections: NormalizationAst;
+  readonly selections: NormalizationAstNodes;
   readonly concreteType: TypeName | null;
 };
 
 export type NormalizationInlineFragment = {
   readonly kind: 'InlineFragment';
   readonly type: string;
-  readonly selections: NormalizationAst;
+  readonly selections: NormalizationAstNodes;
 };
 
 // This is more like an entrypoint, but one specifically for a refetch query/mutation
 export type RefetchQueryNormalizationArtifact = {
   readonly kind: 'RefetchQuery';
-  readonly networkRequestInfo: NetworkRequestInfo;
+  readonly networkRequestInfo: NetworkRequestInfo<NormalizationAst>;
   readonly concreteType: TypeName;
 };
 
@@ -86,21 +99,26 @@ export type RefetchQueryNormalizationArtifactWrapper = {
 };
 
 export function assertIsEntrypoint<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
 >(
   value:
-    | IsographEntrypoint<TReadFromStore, TClientFieldValue>
+    | IsographEntrypoint<TReadFromStore, TClientFieldValue, TNormalizationAst>
     | ((_: any) => any)
     // Temporarily, allow any here. Once we automatically provide
     // types to entrypoints, we probably don't need this.
     | any,
-): asserts value is IsographEntrypoint<TReadFromStore, TClientFieldValue> {
+): asserts value is IsographEntrypoint<
+  TReadFromStore,
+  TClientFieldValue,
+  TNormalizationAst
+> {
   if (typeof value === 'function') throw new Error('Not a string');
 }
 
 export type ExtractReadFromStore<Type> =
-  Type extends IsographEntrypoint<infer X, any> ? X : never;
+  Type extends IsographEntrypoint<infer X, any, any> ? X : never;
 export type ExtractResolverResult<Type> =
-  Type extends IsographEntrypoint<any, infer X> ? X : never;
+  Type extends IsographEntrypoint<any, infer X, any> ? X : never;
 export type ExtractProps<Type> = Type extends React.FC<infer X> ? X : never;

package/src/core/garbageCollection.ts

@@ -1,23 +1,23 @@
+import { getParentRecordKey } from './cache';
+import { NormalizationAstNodes } from './entrypoint';
 import { Variables } from './FragmentReference';
 import {
+  assertLink,
   DataId,
   IsographEnvironment,
   IsographStore,
   StoreRecord,
-  assertLink,
   type Link,
   type TypeName,
 } from './IsographEnvironment';
-import { getParentRecordKey } from './cache';
-import { NormalizationAst } from './entrypoint';
 
 export type RetainedQuery = {
-  readonly normalizationAst: NormalizationAst;
+  readonly normalizationAst: NormalizationAstNodes;
   readonly variables: {};
   readonly root: Link;
 };
 
-type DidUnretainSomeQuery = boolean;
+export type DidUnretainSomeQuery = boolean;
 export function unretainQuery(
   environment: IsographEnvironment,
   retainedQuery: RetainedQuery,
@@ -108,7 +108,7 @@ function recordReachableIdsFromRecord(
   store: IsographStore,
   currentRecord: StoreRecord,
   mutableRetainedIds: RetainedIds,
-  selections: NormalizationAst,
+  selections: NormalizationAstNodes,
   variables: Variables | null,
 ) {
   for (const selection of selections) {