@isograph/react 0.3.0 → 0.3.1

package/src/react/FragmentReader.tsx

@@ -1,10 +1,10 @@
 import * as React from 'react';
 import { ExtractReadFromStore, IsographEntrypoint } from '../core/entrypoint';
 import { FragmentReference } from '../core/FragmentReference';
-import { useResult } from './useResult';
 import { NetworkRequestReaderOptions } from '../core/read';
+import { useResult } from './useResult';
 
-type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes
+export type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes
   ? JSX.IntrinsicAttributes extends T
     ? true
     : false
@@ -12,7 +12,7 @@ type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes
 
 export function FragmentReader<
   TProps extends Record<any, any>,
-  TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>>,
+  TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>, any>,
 >(
   props: IsExactlyIntrinsicAttributes<TProps> extends true
     ? {

package/src/react/IsographEnvironmentProvider.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { ReactNode, createContext, useContext } from 'react';
+import { createContext, ReactNode, useContext } from 'react';
 import { type IsographEnvironment } from '../core/IsographEnvironment';
 
 export const IsographEnvironmentContext =

package/src/react/useImperativeReference.ts

@@ -1,44 +1,65 @@
 import {
-  UnassignedState,
+  UNASSIGNED_STATE,
   useUpdatableDisposableState,
 } from '@isograph/react-disposable-state';
-import { IsographEntrypoint } from '../core/entrypoint';
+import { FetchOptions, type RequiredFetchOptions } from '../core/check';
+import {
+  IsographEntrypoint,
+  type NormalizationAst,
+  type NormalizationAstLoader,
+} from '../core/entrypoint';
 import {
-  FragmentReference,
   ExtractParameters,
+  FragmentReference,
+  type UnknownTReadFromStore,
 } from '../core/FragmentReference';
-import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { ROOT_ID } from '../core/IsographEnvironment';
 import { maybeMakeNetworkRequest } from '../core/makeNetworkRequest';
 import { wrapResolvedValue } from '../core/PromiseWrapper';
-import { FetchOptions } from '../core/check';
-
-// TODO rename this to useImperativelyLoadedEntrypoint
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
 
-export function useImperativeReference<
-  TReadFromStore extends { parameters: object; data: object },
+export type UseImperativeReferenceResult<
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
->(
-  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
-): {
-  fragmentReference:
-    | FragmentReference<TReadFromStore, TClientFieldValue>
-    | UnassignedState;
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
+> = {
+  fragmentReference: FragmentReference<
+    TReadFromStore,
+    TClientFieldValue
+  > | null;
   loadFragmentReference: (
     variables: ExtractParameters<TReadFromStore>,
-    fetchOptions?: FetchOptions,
+    ...[fetchOptions]: NormalizationAstLoader extends TNormalizationAst
+      ? [fetchOptions: RequiredFetchOptions<TClientFieldValue>]
+      : [fetchOptions?: FetchOptions<TClientFieldValue>]
   ) => void;
-} {
+};
+
+export function useImperativeReference<
+  TReadFromStore extends UnknownTReadFromStore,
+  TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
+>(
+  entrypoint: IsographEntrypoint<
+    TReadFromStore,
+    TClientFieldValue,
+    TNormalizationAst
+  >,
+): UseImperativeReferenceResult<
+  TReadFromStore,
+  TClientFieldValue,
+  TNormalizationAst
+> {
   const { state, setState } =
     useUpdatableDisposableState<
       FragmentReference<TReadFromStore, TClientFieldValue>
     >();
   const environment = useIsographEnvironment();
   return {
-    fragmentReference: state,
+    fragmentReference: state !== UNASSIGNED_STATE ? state : null,
     loadFragmentReference: (
       variables: ExtractParameters<TReadFromStore>,
-      fetchOptions?: FetchOptions,
+      fetchOptions?: FetchOptions<TClientFieldValue>,
     ) => {
       const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
         environment,

package/src/react/useLazyReference.ts

@@ -1,32 +1,46 @@
+import { useLazyDisposableState } from '@isograph/react-disposable-state';
+import { getOrCreateCacheForArtifact } from '../core/cache';
+import { FetchOptions, type RequiredFetchOptions } from '../core/check';
+import {
+  IsographEntrypoint,
+  type NormalizationAst,
+  type NormalizationAstLoader,
+} from '../core/entrypoint';
 import {
-  FragmentReference,
   ExtractParameters,
+  FragmentReference,
+  type UnknownTReadFromStore,
 } from '../core/FragmentReference';
-import { useIsographEnvironment } from './IsographEnvironmentProvider';
-import { IsographEntrypoint } from '../core/entrypoint';
-import { getOrCreateCacheForArtifact } from '../core/cache';
-import { useLazyDisposableState } from '@isograph/react-disposable-state';
 import { logMessage } from '../core/logging';
-import { FetchOptions } from '../core/check';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
 
 export function useLazyReference<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
+  TNormalizationAst extends NormalizationAst | NormalizationAstLoader,
 >(
-  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+  entrypoint: IsographEntrypoint<
+    TReadFromStore,
+    TClientFieldValue,
+    TNormalizationAst
+  >,
   variables: ExtractParameters<TReadFromStore>,
-  fetchOptions?: FetchOptions,
-): {
-  fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
-} {
+  ...[fetchOptions]: TNormalizationAst extends NormalizationAstLoader
+    ? [fetchOptions: RequiredFetchOptions<TClientFieldValue>]
+    : [fetchOptions?: FetchOptions<TClientFieldValue>]
+): NormalizationAst | NormalizationAstLoader extends TNormalizationAst
+  ? unknown
+  : {
+      fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
+    } {
   const environment = useIsographEnvironment();
 
   if (entrypoint?.kind !== 'Entrypoint') {
     // TODO have a separate error logger
-    logMessage(environment, {
+    logMessage(environment, () => ({
       kind: 'NonEntrypointReceived',
       entrypoint,
-    });
+    }));
   }
 
   const cache = getOrCreateCacheForArtifact(
@@ -40,3 +54,37 @@ export function useLazyReference<
     fragmentReference: useLazyDisposableState(cache).state,
   };
 }
+
+// @ts-ignore
+function tsTests() {
+  let withAst!: IsographEntrypoint<any, unknown, NormalizationAst>;
+  let withAstLoader!: IsographEntrypoint<any, unknown, NormalizationAstLoader>;
+  let withAstOrLoader!: IsographEntrypoint<
+    any,
+    unknown,
+    NormalizationAst | NormalizationAstLoader
+  >;
+
+  useLazyReference(withAst, {}) satisfies {};
+  useLazyReference(withAst, {}, { shouldFetch: 'Yes' }) satisfies {};
+  useLazyReference(withAst, {}, { shouldFetch: 'IfNecessary' }) satisfies {};
+
+  // @ts-expect-error if there's no ast, require `shouldFetch` to be specified
+  useLazyReference(withAstLoader, {});
+  useLazyReference(withAstLoader, {}, { shouldFetch: 'Yes' }) satisfies {};
+  // @ts-expect-error if there's no ast, `shouldFetch` can't be `IfNecessary`
+  useLazyReference(withAstLoader, {}, { shouldFetch: 'IfNecessary' });
+
+  // if the type is unknown there can be no ast so we should use the same rules
+  // but because of TS bugs with inference we just return unknown
+  // @ts-expect-error this returns unknown which doesn't satisfy the constraint
+  useLazyReference(withAstOrLoader, {}) satisfies {};
+  // @ts-expect-error this returns unknown which doesn't satisfy the constraint
+  useLazyReference(withAstOrLoader, {}, { shouldFetch: 'Yes' }) satisfies {};
+  useLazyReference(
+    withAstOrLoader,
+    {},
+    { shouldFetch: 'IfNecessary' },
+    // @ts-expect-error this returns unknown which doesn't satisfy the constraint
+  ) satisfies {};
+}

package/src/react/useReadAndSubscribe.ts

@@ -1,24 +1,26 @@
 import { useEffect, useState } from 'react';
+import { subscribe } from '../core/cache';
 import {
+  ExtractData,
   FragmentReference,
   stableIdForFragmentReference,
-  ExtractData,
+  type UnknownTReadFromStore,
 } from '../core/FragmentReference';
+import { readPromise } from '../core/PromiseWrapper';
 import {
   NetworkRequestReaderOptions,
   readButDoNotEvaluate,
   WithEncounteredRecords,
 } from '../core/read';
-import { useRerenderOnChange } from './useRerenderOnChange';
-import { useIsographEnvironment } from './IsographEnvironmentProvider';
-import { subscribe } from '../core/cache';
 import type { ReaderAst } from '../core/reader';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { useRerenderOnChange } from './useRerenderOnChange';
 
 /**
  * Read the data from a fragment reference and subscribe to updates.
  */
 export function useReadAndSubscribe<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
 >(
   fragmentReference: FragmentReference<TReadFromStore, any>,
   networkRequestOptions: NetworkRequestReaderOptions,
@@ -38,7 +40,7 @@ export function useReadAndSubscribe<
 }
 
 export function useSubscribeToMultiple<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
 >(
   items: ReadonlyArray<{
     records: WithEncounteredRecords<TReadFromStore>;
@@ -72,9 +74,15 @@ export function useSubscribeToMultiple<
     // TODO find out
     [
       items
-        .map(({ fragmentReference }) =>
-          stableIdForFragmentReference(fragmentReference),
-        )
+        .map(({ fragmentReference }) => {
+          const readerWithRefetchQueries = readPromise(
+            fragmentReference.readerWithRefetchQueries,
+          );
+          stableIdForFragmentReference(
+            fragmentReference,
+            readerWithRefetchQueries.readerArtifact.fieldName,
+          );
+        })
         .join('.'),
     ],
   );

package/src/react/useRerenderOnChange.ts

@@ -1,9 +1,9 @@
 import { useEffect } from 'react';
 import { subscribe } from '../core/cache';
-import { WithEncounteredRecords } from '../core/read';
 import { FragmentReference } from '../core/FragmentReference';
-import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { WithEncounteredRecords } from '../core/read';
 import type { ReaderAst } from '../core/reader';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
 
 // TODO add unit tests for this. Add integration tests that test
 // behavior when the encounteredRecords underneath a fragment change.

package/src/react/useResult.ts

@@ -1,19 +1,23 @@
-import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
-import { FragmentReference } from '../core/FragmentReference';
 import { getOrCreateCachedComponent } from '../core/componentCache';
-import { useReadAndSubscribe } from './useReadAndSubscribe';
 import {
-  getNetworkRequestOptionsWithDefaults,
-  NetworkRequestReaderOptions,
-} from '../core/read';
+  FragmentReference,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
 import {
   getPromiseState,
   PromiseWrapper,
   readPromise,
 } from '../core/PromiseWrapper';
+import {
+  getNetworkRequestOptionsWithDefaults,
+  NetworkRequestReaderOptions,
+} from '../core/read';
+import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
+import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
+import { useReadAndSubscribe } from './useReadAndSubscribe';
 
 export function useResult<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 >(
   fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>,
@@ -37,7 +41,7 @@ export function useResult<
       // @ts-expect-error
       return getOrCreateCachedComponent(
         environment,
-        readerWithRefetchQueries.readerArtifact.componentName,
+        readerWithRefetchQueries.readerArtifact.fieldName,
         fragmentReference,
         networkRequestOptions,
       );
@@ -51,6 +55,15 @@ export function useResult<
       const param = {
         data: data,
         parameters: fragmentReference.variables,
+        ...(readerWithRefetchQueries.readerArtifact.hasUpdatable
+          ? {
+              startUpdate: getOrCreateCachedStartUpdate(
+                environment,
+                fragmentReference,
+                readerWithRefetchQueries.readerArtifact.fieldName,
+              ),
+            }
+          : undefined),
       };
       return readerWithRefetchQueries.readerArtifact.resolver(param);
     }

package/src/tests/__isograph/Query/meName/entrypoint.ts

@@ -2,38 +2,14 @@ import type {IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArti
 import {Query__meName__param} from './param_type';
 import {Query__meName__output_type} from './output_type';
 import readerResolver from './resolver_reader';
+import queryText from './query_text';
+import normalizationAst from './normalization_ast';
 const nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[] = [];
 
-const queryText = 'query meName  {\
-  me {\
-    id,\
-    name,\
-  },\
-}';
-
-const normalizationAst: NormalizationAst = [
-  {
-    kind: "Linked",
-    fieldName: "me",
-    arguments: null,
-    concreteType: "Economist",
-    selections: [
-      {
-        kind: "Scalar",
-        fieldName: "id",
-        arguments: null,
-      },
-      {
-        kind: "Scalar",
-        fieldName: "name",
-        arguments: null,
-      },
-    ],
-  },
-];
 const artifact: IsographEntrypoint<
   Query__meName__param,
-  Query__meName__output_type
+  Query__meName__output_type,
+  NormalizationAst
 > = {
   kind: "Entrypoint",
   networkRequestInfo: {

package/src/tests/__isograph/Query/meName/normalization_ast.ts

@@ -0,0 +1,25 @@
+import type {NormalizationAst} from '@isograph/react';
+const normalizationAst: NormalizationAst = {
+  kind: "NormalizationAst",
+  selections: [
+    {
+      kind: "Linked",
+      fieldName: "me",
+      arguments: null,
+      concreteType: "Economist",
+      selections: [
+        {
+          kind: "Scalar",
+          fieldName: "id",
+          arguments: null,
+        },
+        {
+          kind: "Scalar",
+          fieldName: "name",
+          arguments: null,
+        },
+      ],
+    },
+  ],
+};
+export default normalizationAst;

package/src/tests/__isograph/Query/meName/query_text.ts

@@ -0,0 +1,6 @@
+export default 'query meName  {\
+  me {\
+    id,\
+    name,\
+  },\
+}';

package/src/tests/__isograph/Query/meName/resolver_reader.ts

@@ -10,12 +10,14 @@ const readerAst: ReaderAst<Query__meName__param> = [
     alias: null,
     arguments: null,
     condition: null,
+    isUpdatable: false,
     selections: [
       {
         kind: "Scalar",
         fieldName: "name",
         alias: null,
         arguments: null,
+        isUpdatable: false,
       },
     ],
   },
@@ -26,8 +28,10 @@ const artifact: EagerReaderArtifact<
   Query__meName__output_type
 > = {
   kind: "EagerReaderArtifact",
+  fieldName: "Query.meName",
   resolver,
   readerAst,
+  hasUpdatable: false,
 };
 
 export default artifact;

package/src/tests/__isograph/Query/meNameSuccessor/entrypoint.ts

@@ -2,76 +2,14 @@ import type {IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArti
 import {Query__meNameSuccessor__param} from './param_type';
 import {Query__meNameSuccessor__output_type} from './output_type';
 import readerResolver from './resolver_reader';
+import queryText from './query_text';
+import normalizationAst from './normalization_ast';
 const nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[] = [];
 
-const queryText = 'query meNameSuccessor  {\
-  me {\
-    id,\
-    name,\
-    successor {\
-      id,\
-      successor {\
-        id,\
-        name,\
-      },\
-    },\
-  },\
-}';
-
-const normalizationAst: NormalizationAst = [
-  {
-    kind: "Linked",
-    fieldName: "me",
-    arguments: null,
-    concreteType: "Economist",
-    selections: [
-      {
-        kind: "Scalar",
-        fieldName: "id",
-        arguments: null,
-      },
-      {
-        kind: "Scalar",
-        fieldName: "name",
-        arguments: null,
-      },
-      {
-        kind: "Linked",
-        fieldName: "successor",
-        arguments: null,
-        concreteType: "Economist",
-        selections: [
-          {
-            kind: "Scalar",
-            fieldName: "id",
-            arguments: null,
-          },
-          {
-            kind: "Linked",
-            fieldName: "successor",
-            arguments: null,
-            concreteType: "Economist",
-            selections: [
-              {
-                kind: "Scalar",
-                fieldName: "id",
-                arguments: null,
-              },
-              {
-                kind: "Scalar",
-                fieldName: "name",
-                arguments: null,
-              },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-];
 const artifact: IsographEntrypoint<
   Query__meNameSuccessor__param,
-  Query__meNameSuccessor__output_type
+  Query__meNameSuccessor__output_type,
+  NormalizationAst
 > = {
   kind: "Entrypoint",
   networkRequestInfo: {

package/src/tests/__isograph/Query/meNameSuccessor/normalization_ast.ts

@@ -0,0 +1,56 @@
+import type {NormalizationAst} from '@isograph/react';
+const normalizationAst: NormalizationAst = {
+  kind: "NormalizationAst",
+  selections: [
+    {
+      kind: "Linked",
+      fieldName: "me",
+      arguments: null,
+      concreteType: "Economist",
+      selections: [
+        {
+          kind: "Scalar",
+          fieldName: "id",
+          arguments: null,
+        },
+        {
+          kind: "Scalar",
+          fieldName: "name",
+          arguments: null,
+        },
+        {
+          kind: "Linked",
+          fieldName: "successor",
+          arguments: null,
+          concreteType: "Economist",
+          selections: [
+            {
+              kind: "Scalar",
+              fieldName: "id",
+              arguments: null,
+            },
+            {
+              kind: "Linked",
+              fieldName: "successor",
+              arguments: null,
+              concreteType: "Economist",
+              selections: [
+                {
+                  kind: "Scalar",
+                  fieldName: "id",
+                  arguments: null,
+                },
+                {
+                  kind: "Scalar",
+                  fieldName: "name",
+                  arguments: null,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+export default normalizationAst;

package/src/tests/__isograph/Query/meNameSuccessor/query_text.ts

@@ -0,0 +1,13 @@
+export default 'query meNameSuccessor  {\
+  me {\
+    id,\
+    name,\
+    successor {\
+      id,\
+      successor {\
+        id,\
+        name,\
+      },\
+    },\
+  },\
+}';

package/src/tests/__isograph/Query/meNameSuccessor/resolver_reader.ts

@@ -10,12 +10,14 @@ const readerAst: ReaderAst<Query__meNameSuccessor__param> = [
     alias: null,
     arguments: null,
     condition: null,
+    isUpdatable: false,
     selections: [
       {
         kind: "Scalar",
         fieldName: "name",
         alias: null,
         arguments: null,
+        isUpdatable: false,
       },
       {
         kind: "Linked",
@@ -23,6 +25,7 @@ const readerAst: ReaderAst<Query__meNameSuccessor__param> = [
         alias: null,
         arguments: null,
         condition: null,
+        isUpdatable: false,
         selections: [
           {
             kind: "Linked",
@@ -30,12 +33,14 @@ const readerAst: ReaderAst<Query__meNameSuccessor__param> = [
             alias: null,
             arguments: null,
             condition: null,
+            isUpdatable: false,
             selections: [
               {
                 kind: "Scalar",
                 fieldName: "name",
                 alias: null,
                 arguments: null,
+                isUpdatable: false,
               },
             ],
           },
@@ -50,8 +55,10 @@ const artifact: EagerReaderArtifact<
   Query__meNameSuccessor__output_type
 > = {
   kind: "EagerReaderArtifact",
+  fieldName: "Query.meNameSuccessor",
   resolver,
   readerAst,
+  hasUpdatable: false,
 };
 
 export default artifact;