@isograph/react 0.2.0 → 0.3.0

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -1,9 +1,11 @@
-import { LoadableField } from '../core/reader';
+import { LoadableField, type ReaderAst } from '../core/reader';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 import { ItemCleanupPair } from '@isograph/disposable-types';
 import { FragmentReference } from '../core/FragmentReference';
 import { maybeUnwrapNetworkRequest } from '../react/useResult';
 import { readButDoNotEvaluate } from '../core/read';
+import { subscribeToAnyChange } from '../core/cache';
+import { useState } from 'react';
 import {
   UNASSIGNED_STATE,
   useUpdatableDisposableState,
@@ -13,31 +15,43 @@ import {
   ReferenceCountedPointer,
 } from '@isograph/reference-counted-pointer';
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
+import { type WithEncounteredRecords } from '../core/read';
+import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
+import { FetchOptions } from '../core/check';
 
-type SkipOrLimit = 'skip' | 'limit';
-type OmitSkipLimit<TArgs> = keyof Omit<TArgs, SkipOrLimit> extends never
-  ? void | Record<string, never>
-  : Omit<TArgs, SkipOrLimit>;
-
-type UseSkipLimitReturnValue<TArgs, TItem> =
+type UseSkipLimitReturnValue<
+  TReadFromStore extends { data: object; parameters: object },
+  TItem,
+> =
   | {
       readonly kind: 'Complete';
-      readonly fetchMore: (args: OmitSkipLimit<TArgs>, count: number) => void;
+      readonly fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
       readonly results: ReadonlyArray<TItem>;
     }
   | {
       readonly kind: 'Pending';
       readonly results: ReadonlyArray<TItem>;
-      readonly pendingFragment: FragmentReference<any, ReadonlyArray<TItem>>;
+      readonly pendingFragment: FragmentReference<
+        TReadFromStore,
+        ReadonlyArray<TItem>
+      >;
     };
 
-type ArrayFragmentReference<TItem> = FragmentReference<
-  any,
-  ReadonlyArray<TItem>
->;
+type ArrayFragmentReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = FragmentReference<TReadFromStore, ReadonlyArray<TItem>>;
+
+type LoadedFragmentReferences<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = ReadonlyArray<LoadedFragmentReference<TReadFromStore, TItem>>;
 
-type LoadedFragmentReferences<TItem> = ReadonlyArray<
-  ItemCleanupPair<ReferenceCountedPointer<ArrayFragmentReference<TItem>>>
+type LoadedFragmentReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = ItemCleanupPair<
+  ReferenceCountedPointer<ArrayFragmentReference<TReadFromStore, TItem>>
 >;
 
 function flatten<T>(arr: ReadonlyArray<ReadonlyArray<T>>): ReadonlyArray<T> {
@@ -50,95 +64,136 @@ function flatten<T>(arr: ReadonlyArray<ReadonlyArray<T>>): ReadonlyArray<T> {
   return outArray;
 }
 
-/**
- * accepts a loadableField that accepts skip and limit arguments
- * and returns:
- * - a fetchMore function that, when called, triggers a network
- *   request for additional data, and
- * - the data received so far.
- *
- * This hook will suspend if any network request is in flight.
- *
- * Calling fetchMore before the hook mounts is a no-op.
- *
- * NOTE: this hook does not subscribe to changes. This is a known
- * issue. If you are running into this issue, reach out on GitHub/
- * Twitter, and we'll fix the issue.
- */
+type UseSkipLimitPaginationArgs = {
+  skip: number;
+  limit: number;
+};
+
 export function useSkipLimitPagination<
-  TArgs extends {
-    skip: number | void | null;
-    limit: number | void | null;
-  },
   TItem,
+  TReadFromStore extends {
+    parameters: object;
+    data: object;
+  },
 >(
-  loadableField: LoadableField<TArgs, Array<TItem>>,
-): UseSkipLimitReturnValue<TArgs, TItem> {
+  loadableField: LoadableField<
+    TReadFromStore,
+    ReadonlyArray<TItem>,
+    UseSkipLimitPaginationArgs
+  >,
+  initialState?: {
+    skip?: number | void | null;
+  },
+): UseSkipLimitReturnValue<TReadFromStore, TItem> {
   const networkRequestOptions = {
     suspendIfInFlight: true,
     throwOnNetworkError: true,
   };
   const { state, setState } =
-    useUpdatableDisposableState<LoadedFragmentReferences<TItem>>();
+    useUpdatableDisposableState<
+      LoadedFragmentReferences<TReadFromStore, TItem>
+    >();
 
   const environment = useIsographEnvironment();
 
+  // TODO move this out of useSkipLimitPagination, and pass environment and networkRequestOptions
+  // as parameters (or recreate networkRequestOptions)
   function readCompletedFragmentReferences(
-    completedReferences: ReadonlyArray<
-      ItemCleanupPair<ReferenceCountedPointer<ArrayFragmentReference<TItem>>>
-    >,
+    completedReferences: ArrayFragmentReference<TReadFromStore, TItem>[],
   ) {
-    // In general, this will not suspend. But it could, if there is missing data.
-    // A better version of this hook would not do any reading here.
-    const results = completedReferences.map(([pointer]) => {
-      const fragmentReference = pointer.getItemIfNotDisposed();
-      if (fragmentReference == null) {
+    const results = completedReferences.map((fragmentReference, i) => {
+      const readerWithRefetchQueries = readPromise(
+        fragmentReference.readerWithRefetchQueries,
+      );
+
+      // invariant: readOutDataAndRecords.length === completedReferences.length
+      const data = readOutDataAndRecords[i]?.item;
+      if (data == null) {
         throw new Error(
-          'FragmentReference is unexpectedly disposed. \
-        This is indicative of a bug in Isograph.',
+          'Parameter data is unexpectedly null. This is indicative of a bug in Isograph.',
         );
       }
 
-      maybeUnwrapNetworkRequest(
-        fragmentReference.networkRequest,
-        networkRequestOptions,
-      );
-      const data = readButDoNotEvaluate(
-        environment,
-        fragmentReference,
-        networkRequestOptions,
-      );
+      const firstParameter = {
+        data,
+        parameters: fragmentReference.variables,
+      };
 
-      const readerWithRefetchQueries = readPromise(
-        fragmentReference.readerWithRefetchQueries,
-      );
+      if (
+        readerWithRefetchQueries.readerArtifact.kind !== 'EagerReaderArtifact'
+      ) {
+        throw new Error(
+          `@loadable field of kind "${readerWithRefetchQueries.readerArtifact.kind}" is not supported by useSkipLimitPagination`,
+        );
+      }
 
-      return readerWithRefetchQueries.readerArtifact.resolver(
-        data.item,
-        undefined,
-      ) as ReadonlyArray<any>;
+      return readerWithRefetchQueries.readerArtifact.resolver(firstParameter);
     });
 
     const items = flatten(results);
     return items;
   }
 
+  function subscribeCompletedFragmentReferences(
+    completedReferences: ArrayFragmentReference<TReadFromStore, TItem>[],
+  ) {
+    return completedReferences.map(
+      (
+        fragmentReference,
+        i,
+      ): {
+        records: WithEncounteredRecords<TReadFromStore>;
+        callback: (
+          updatedRecords: WithEncounteredRecords<TReadFromStore>,
+        ) => void;
+        fragmentReference: ArrayFragmentReference<TReadFromStore, TItem>;
+        readerAst: ReaderAst<TItem>;
+      } => {
+        maybeUnwrapNetworkRequest(
+          fragmentReference.networkRequest,
+          networkRequestOptions,
+        );
+
+        const readerWithRefetchQueries = readPromise(
+          fragmentReference.readerWithRefetchQueries,
+        );
+
+        const records = readOutDataAndRecords[i];
+        if (records == null) {
+          throw new Error(
+            'subscribeCompletedFragmentReferences records is unexpectedly null',
+          );
+        }
+
+        return {
+          fragmentReference,
+          readerAst: readerWithRefetchQueries.readerArtifact.readerAst,
+          records,
+          callback(_data) {
+            rerender({});
+          },
+        };
+      },
+    );
+  }
+
   const getFetchMore =
     (loadedSoFar: number) =>
-    (args: OmitSkipLimit<TArgs>, count: number): void => {
-      // @ts-expect-error
-      const loadedField = loadableField({
-        ...args,
-        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();
         if (clonedRefCountedPointer == null) {
           throw new Error(
             'This reference counted pointer has already been disposed. \
-              This is indicative of a bug in useSkipLimitPagination.',
+            This is indicative of a bug in useSkipLimitPagination.',
           );
         }
         return clonedRefCountedPointer;
@@ -148,7 +203,9 @@ export function useSkipLimitPagination<
       const totalItemCleanupPair: ItemCleanupPair<
         ReadonlyArray<
           ItemCleanupPair<
-            ReferenceCountedPointer<ArrayFragmentReference<TItem>>
+            ReferenceCountedPointer<
+              ArrayFragmentReference<TReadFromStore, TItem>
+            >
           >
         >
       > = [
@@ -163,33 +220,73 @@ export function useSkipLimitPagination<
       setState(totalItemCleanupPair);
     };
 
+  const [, rerender] = useState({});
+
   const loadedReferences = state === UNASSIGNED_STATE ? [] : state;
-  if (loadedReferences.length === 0) {
-    return {
-      kind: 'Complete',
-      fetchMore: getFetchMore(0),
-      results: [],
-    };
-  }
 
-  const mostRecentItem = loadedReferences[loadedReferences.length - 1];
-  const mostRecentFragmentReference = mostRecentItem[0].getItemIfNotDisposed();
-  if (mostRecentFragmentReference === null) {
+  const mostRecentItem:
+    | LoadedFragmentReference<TReadFromStore, TItem>
+    | undefined = loadedReferences[loadedReferences.length - 1];
+  const mostRecentFragmentReference =
+    mostRecentItem?.[0].getItemIfNotDisposed();
+
+  if (mostRecentItem && mostRecentFragmentReference === null) {
     throw new Error(
       'FragmentReference is unexpectedly disposed. \
-        This is indicative of a bug in Isograph.',
+      This is indicative of a bug in Isograph.',
     );
   }
 
-  const networkRequestStatus = getPromiseState(
-    mostRecentFragmentReference.networkRequest,
+  const networkRequestStatus =
+    mostRecentFragmentReference &&
+    getPromiseState(mostRecentFragmentReference.networkRequest);
+
+  const slicedFragmentReferences =
+    networkRequestStatus?.kind === 'Ok'
+      ? loadedReferences
+      : loadedReferences.slice(0, loadedReferences.length - 1);
+
+  const completedFragmentReferences = slicedFragmentReferences.map(
+    ([pointer]) => {
+      const fragmentReference = pointer.getItemIfNotDisposed();
+      if (fragmentReference == null) {
+        throw new Error(
+          'FragmentReference is unexpectedly disposed. \
+            This is indicative of a bug in Isograph.',
+        );
+      }
+      return fragmentReference;
+    },
+  );
+
+  const readOutDataAndRecords = completedFragmentReferences.map(
+    (fragmentReference) =>
+      readButDoNotEvaluate(
+        environment,
+        fragmentReference,
+        networkRequestOptions,
+      ),
   );
+
+  useSubscribeToMultiple<TReadFromStore>(
+    subscribeCompletedFragmentReferences(completedFragmentReferences),
+  );
+
+  if (!networkRequestStatus) {
+    return {
+      kind: 'Complete',
+      fetchMore: getFetchMore(initialState?.skip ?? 0),
+      results: [],
+    };
+  }
+
   switch (networkRequestStatus.kind) {
     case 'Pending': {
-      const completedFragmentReferences = loadedReferences.slice(
-        0,
-        loadedReferences.length - 1,
-      );
+      const unsubscribe = subscribeToAnyChange(environment, () => {
+        unsubscribe();
+        rerender({});
+      });
+
       return {
         kind: 'Pending',
         pendingFragment: mostRecentFragmentReference,
@@ -200,7 +297,9 @@ export function useSkipLimitPagination<
       throw networkRequestStatus.error;
     }
     case 'Ok': {
-      const results = readCompletedFragmentReferences(loadedReferences);
+      const results = readCompletedFragmentReferences(
+        completedFragmentReferences,
+      );
       return {
         kind: 'Complete',
         results,
@@ -209,3 +308,45 @@ export function useSkipLimitPagination<
     }
   }
 }
+
+// @ts-ignore
+function tsTests() {
+  type Parameters = {
+    readonly search: string;
+    readonly skip: number;
+    readonly limit: number;
+  };
+
+  let basicLoadable!: LoadableField<
+    {
+      readonly data: object;
+      readonly parameters: Omit<Parameters, 'search'>;
+    },
+    object[]
+  >;
+
+  useSkipLimitPagination(basicLoadable);
+  useSkipLimitPagination(basicLoadable, {});
+  useSkipLimitPagination(basicLoadable, { skip: 10 });
+
+  let unprovidedSearchLoadable!: LoadableField<
+    {
+      readonly data: object;
+      readonly parameters: Parameters;
+    },
+    object[]
+  >;
+  // @ts-expect-error
+  useSkipLimitPagination(unprovidedSearchLoadable);
+
+  let providedSearchLoadable!: LoadableField<
+    {
+      readonly data: object;
+      readonly parameters: Parameters;
+    },
+    object[],
+    Omit<Parameters, 'search'>
+  >;
+
+  useSkipLimitPagination(providedSearchLoadable);
+}

package/src/react/FragmentReader.tsx

@@ -4,17 +4,23 @@ import { FragmentReference } from '../core/FragmentReference';
 import { useResult } from './useResult';
 import { NetworkRequestReaderOptions } from '../core/read';
 
+type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes
+  ? JSX.IntrinsicAttributes extends T
+    ? true
+    : false
+  : false;
+
 export function FragmentReader<
   TProps extends Record<any, any>,
   TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>>,
 >(
-  props: TProps extends Record<string, never>
+  props: IsExactlyIntrinsicAttributes<TProps> extends true
     ? {
         fragmentReference: FragmentReference<
           ExtractReadFromStore<TEntrypoint>,
-          React.FC<{}>
+          React.FC<TProps>
         >;
-        additionalProps?: TProps;
+        additionalProps?: Record<PropertyKey, never>;
         networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
       }
     : {
@@ -22,7 +28,7 @@ export function FragmentReader<
           ExtractReadFromStore<TEntrypoint>,
           React.FC<TProps>
         >;
-        additionalProps: TProps;
+        additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
         networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
       },
 ): React.ReactNode {
@@ -30,5 +36,8 @@ export function FragmentReader<
     props.fragmentReference,
     props.networkRequestOptions,
   );
+  // TypeScript is not understanding that if additionalProps is Record<PropertyKey, never>,
+  // it means that TProps === JSX.IntrinsicAttributes.
+  // @ts-expect-error
   return <Component {...props.additionalProps} />;
 }

package/src/react/RenderAfterCommit__DO_NOT_USE.tsx

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * This is a function that will render a component only after it commits.
+ * It should not be used in production. It's useful as a way to debug issues
+ * with NextJS, where an indefinite suspense causes the server to hang
+ * forever and never complete the original request.
+ */
+export function RenderAfterCommit__DO_NOT_USE({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [show, setShow] = useState(false);
+  useEffect(() => setShow(true), []);
+  return show ? children : null;
+}

package/src/react/useImperativeReference.ts

@@ -3,16 +3,20 @@ import {
   useUpdatableDisposableState,
 } from '@isograph/react-disposable-state';
 import { IsographEntrypoint } from '../core/entrypoint';
-import { FragmentReference, Variables } from '../core/FragmentReference';
+import {
+  FragmentReference,
+  ExtractParameters,
+} from '../core/FragmentReference';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { ROOT_ID } from '../core/IsographEnvironment';
-import { makeNetworkRequest } from '../core/makeNetworkRequest';
+import { maybeMakeNetworkRequest } from '../core/makeNetworkRequest';
 import { wrapResolvedValue } from '../core/PromiseWrapper';
+import { FetchOptions } from '../core/check';
 
 // TODO rename this to useImperativelyLoadedEntrypoint
 
 export function useImperativeReference<
-  TReadFromStore extends Object,
+  TReadFromStore extends { parameters: object; data: object },
   TClientFieldValue,
 >(
   entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
@@ -20,7 +24,10 @@ export function useImperativeReference<
   fragmentReference:
     | FragmentReference<TReadFromStore, TClientFieldValue>
     | UnassignedState;
-  loadFragmentReference: (variables: Variables) => void;
+  loadFragmentReference: (
+    variables: ExtractParameters<TReadFromStore>,
+    fetchOptions?: FetchOptions,
+  ) => void;
 } {
   const { state, setState } =
     useUpdatableDisposableState<
@@ -29,11 +36,15 @@ export function useImperativeReference<
   const environment = useIsographEnvironment();
   return {
     fragmentReference: state,
-    loadFragmentReference: (variables: Variables) => {
-      const [networkRequest, disposeNetworkRequest] = makeNetworkRequest(
+    loadFragmentReference: (
+      variables: ExtractParameters<TReadFromStore>,
+      fetchOptions?: FetchOptions,
+    ) => {
+      const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
         environment,
         entrypoint,
         variables,
+        fetchOptions,
       );
       setState([
         {
@@ -44,7 +55,7 @@ export function useImperativeReference<
             nestedRefetchQueries:
               entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
           }),
-          root: ROOT_ID,
+          root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
           variables,
           networkRequest,
         },

package/src/react/useLazyReference.ts

@@ -1,20 +1,40 @@
-import { FragmentReference, Variables } from '../core/FragmentReference';
+import {
+  FragmentReference,
+  ExtractParameters,
+} 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';
 
 export function useLazyReference<
-  TReadFromStore extends Object,
+  TReadFromStore extends { parameters: object; data: object },
   TClientFieldValue,
 >(
   entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
-  variables: Variables,
+  variables: ExtractParameters<TReadFromStore>,
+  fetchOptions?: FetchOptions,
 ): {
   fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
 } {
   const environment = useIsographEnvironment();
-  const cache = getOrCreateCacheForArtifact(environment, entrypoint, variables);
+
+  if (entrypoint?.kind !== 'Entrypoint') {
+    // TODO have a separate error logger
+    logMessage(environment, {
+      kind: 'NonEntrypointReceived',
+      entrypoint,
+    });
+  }
+
+  const cache = getOrCreateCacheForArtifact(
+    environment,
+    entrypoint,
+    variables,
+    fetchOptions,
+  );
 
   return {
     fragmentReference: useLazyDisposableState(cache).state,

package/src/react/useReadAndSubscribe.ts

@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react';
 import {
   FragmentReference,
   stableIdForFragmentReference,
+  ExtractData,
 } from '../core/FragmentReference';
 import {
   NetworkRequestReaderOptions,
@@ -11,14 +12,18 @@ import {
 import { useRerenderOnChange } from './useRerenderOnChange';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { subscribe } from '../core/cache';
+import type { ReaderAst } from '../core/reader';
 
 /**
  * Read the data from a fragment reference and subscribe to updates.
  */
-export function useReadAndSubscribe<TReadFromStore extends Object>(
+export function useReadAndSubscribe<
+  TReadFromStore extends { parameters: object; data: object },
+>(
   fragmentReference: FragmentReference<TReadFromStore, any>,
   networkRequestOptions: NetworkRequestReaderOptions,
-): TReadFromStore {
+  readerAst: ReaderAst<TReadFromStore>,
+): ExtractData<TReadFromStore> {
   const environment = useIsographEnvironment();
   const [readOutDataAndRecords, setReadOutDataAndRecords] = useState(() =>
     readButDoNotEvaluate(environment, fragmentReference, networkRequestOptions),
@@ -27,23 +32,33 @@ export function useReadAndSubscribe<TReadFromStore extends Object>(
     readOutDataAndRecords,
     fragmentReference,
     setReadOutDataAndRecords,
+    readerAst,
   );
   return readOutDataAndRecords.item;
 }
 
-export function useSubscribeToMultiple<TReadFromStore extends Object>(
+export function useSubscribeToMultiple<
+  TReadFromStore extends { parameters: object; data: object },
+>(
   items: ReadonlyArray<{
     records: WithEncounteredRecords<TReadFromStore>;
     callback: (updatedRecords: WithEncounteredRecords<TReadFromStore>) => void;
     fragmentReference: FragmentReference<TReadFromStore, any>;
+    readerAst: ReaderAst<TReadFromStore>;
   }>,
 ) {
   const environment = useIsographEnvironment();
   useEffect(
     () => {
       const cleanupFns = items.map(
-        ({ records, callback, fragmentReference }) => {
-          return subscribe(environment, records, fragmentReference, callback);
+        ({ records, callback, fragmentReference, readerAst }) => {
+          return subscribe(
+            environment,
+            records,
+            fragmentReference,
+            callback,
+            readerAst,
+          );
         },
       );
       return () => {

package/src/react/useRerenderOnChange.ts

@@ -3,15 +3,19 @@ import { subscribe } from '../core/cache';
 import { WithEncounteredRecords } from '../core/read';
 import { FragmentReference } from '../core/FragmentReference';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import type { ReaderAst } from '../core/reader';
 
 // TODO add unit tests for this. Add integration tests that test
 // behavior when the encounteredRecords underneath a fragment change.
-export function useRerenderOnChange<TReadFromStore extends Object>(
+export function useRerenderOnChange<
+  TReadFromStore extends { parameters: object; data: object },
+>(
   encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
   fragmentReference: FragmentReference<any, any>,
   setEncounteredDataAndRecords: (
     data: WithEncounteredRecords<TReadFromStore>,
   ) => void,
+  readerAst: ReaderAst<TReadFromStore>,
 ) {
   const environment = useIsographEnvironment();
   useEffect(() => {
@@ -22,6 +26,7 @@ export function useRerenderOnChange<TReadFromStore extends Object>(
       (newEncounteredDataAndRecords) => {
         setEncounteredDataAndRecords(newEncounteredDataAndRecords);
       },
+      readerAst,
     );
     // Note: this is an empty array on purpose:
     // - the fragment reference is stable for the life of the component