@isograph/react 0.3.0 → 0.4.0

package/src/loadable-hooks/useClientSideDefer.ts

@@ -1,15 +1,16 @@
+import { useLazyDisposableState } from '@isograph/react-disposable-state';
+import { getOrCreateItemInSuspenseCache } from '../core/cache';
+import { FetchOptions } from '../core/check';
 import {
   ExtractParameters,
   FragmentReference,
+  type UnknownTReadFromStore,
 } from '../core/FragmentReference';
-import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
-import { getOrCreateItemInSuspenseCache } from '../core/cache';
-import { useLazyDisposableState } from '@isograph/react-disposable-state';
 import { LoadableField } from '../core/reader';
-import { FetchOptions } from '../core/check';
+import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 
 export function useClientSideDefer<
-  TReadFromStore extends { data: object; parameters: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TResult,
 >(
   loadableField: LoadableField<
@@ -18,11 +19,11 @@ export function useClientSideDefer<
     ExtractParameters<TReadFromStore>
   >,
   args?: Record<PropertyKey, never>,
-  fetchOptions?: FetchOptions,
+  fetchOptions?: FetchOptions<TResult>,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
 export function useClientSideDefer<
-  TReadFromStore extends { data: object; parameters: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TResult,
   TProvidedArgs extends object,
 >(
@@ -32,11 +33,11 @@ export function useClientSideDefer<
     Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
   >,
   args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
-  fetchOptions?: FetchOptions,
+  fetchOptions?: FetchOptions<TResult>,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
 export function useClientSideDefer<
-  TReadFromStore extends { data: object; parameters: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TResult,
   TProvidedArgs extends object,
 >(
@@ -46,7 +47,7 @@ export function useClientSideDefer<
     Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
   >,
   args?: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
-  fetchOptions?: FetchOptions,
+  fetchOptions?: FetchOptions<TResult>,
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> } {
   const [id, loader] = loadableField(args, fetchOptions ?? {});
   const environment = useIsographEnvironment();

package/src/loadable-hooks/useConnectionSpecPagination.ts

@@ -9,20 +9,24 @@ import {
 } from '@isograph/reference-counted-pointer';
 import { useState } from 'react';
 import { subscribeToAnyChange } from '../core/cache';
-import { FragmentReference } from '../core/FragmentReference';
+import { FetchOptions } from '../core/check';
+import {
+  FragmentReference,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
 import {
   readButDoNotEvaluate,
   type WithEncounteredRecords,
 } from '../core/read';
 import { LoadableField, type ReaderAst } from '../core/reader';
+import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
 import { maybeUnwrapNetworkRequest } from '../react/useResult';
-import { FetchOptions } from '../core/check';
 
-type UsePaginationReturnValue<
-  TReadFromStore extends { parameters: object; data: object },
+export type UsePaginationReturnValue<
+  TReadFromStore extends UnknownTReadFromStore,
   TItem,
 > =
   | {
@@ -32,7 +36,10 @@ type UsePaginationReturnValue<
     }
   | {
       kind: 'Complete';
-      fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
+      fetchMore: (
+        count: number,
+        fetchOptions?: FetchOptions<Connection<TItem>>,
+      ) => void;
       results: ReadonlyArray<TItem>;
       hasNextPage: boolean;
     };
@@ -59,12 +66,12 @@ function flatten<T>(arr: ReadonlyArray<ReadonlyArray<T>>): ReadonlyArray<T> {
   return outArray;
 }
 
-type PageInfo = {
+export type PageInfo = {
   readonly hasNextPage: boolean;
   readonly endCursor: string | null;
 };
 
-type Connection<T> = {
+export type Connection<T> = {
   readonly edges: ReadonlyArray<T> | null;
   readonly pageInfo: PageInfo;
 };
@@ -74,16 +81,13 @@ type NonNullConnection<T> = {
   readonly pageInfo: PageInfo;
 };
 
-type UseConnectionSpecPaginationArgs = {
+export type UseConnectionSpecPaginationArgs = {
   first: number;
   after: string | null;
 };
 
 export function useConnectionSpecPagination<
-  TReadFromStore extends {
-    parameters: object;
-    data: object;
-  },
+  TReadFromStore extends UnknownTReadFromStore,
   TItem,
 >(
   loadableField: LoadableField<
@@ -125,6 +129,16 @@ export function useConnectionSpecPagination<
       const firstParameter = {
         data,
         parameters: fragmentReference.variables,
+        ...(readerWithRefetchQueries.readerArtifact.hasUpdatable
+          ? {
+              startUpdate: getOrCreateCachedStartUpdate(
+                environment,
+                fragmentReference,
+                readerWithRefetchQueries.readerArtifact.fieldName,
+                networkRequestOptions,
+              ),
+            }
+          : undefined),
       };
 
       if (
@@ -194,7 +208,7 @@ export function useConnectionSpecPagination<
 
   const getFetchMore =
     (after: string | null) =>
-    (count: number, fetchOptions?: FetchOptions): void => {
+    (count: number, fetchOptions?: FetchOptions<Connection<TItem>>): void => {
       const loadedField = loadableField(
         {
           after: after,

package/src/loadable-hooks/useImperativeExposedMutationField.ts

@@ -1,4 +1,4 @@
-type UseImperativeLoadableFieldReturn<TArgs> = {
+export type UseImperativeLoadableFieldReturn<TArgs> = {
   loadField: (args: TArgs) => void;
 };
 

package/src/loadable-hooks/useImperativeLoadableField.ts

@@ -1,27 +1,25 @@
+import {
+  UNASSIGNED_STATE,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import { FetchOptions } from '../core/check';
 import {
   ExtractParameters,
   FragmentReference,
 } from '../core/FragmentReference';
-import {
-  UnassignedState,
-  useUpdatableDisposableState,
-} from '@isograph/react-disposable-state';
 import { LoadableField } from '../core/reader';
-import { FetchOptions } from '../core/check';
 
-type UseImperativeLoadableFieldReturn<
+export type UseImperativeLoadableFieldReturn<
   TReadFromStore extends { data: object; parameters: object },
   TResult,
   TProvidedArgs extends object,
 > = {
-  fragmentReference:
-    | FragmentReference<TReadFromStore, TResult>
-    | UnassignedState;
+  fragmentReference: FragmentReference<TReadFromStore, TResult> | null;
   loadField: (
     // TODO this should be void iff all args are provided by the query, like in
     // useClientSideDefer.
     args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
-    fetchOptions?: FetchOptions,
+    fetchOptions?: FetchOptions<TResult>,
   ) => void;
 };
 
@@ -42,11 +40,11 @@ export function useImperativeLoadableField<
   return {
     loadField: (
       args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
-      fetchOptions?: FetchOptions,
+      fetchOptions?: FetchOptions<TResult>,
     ) => {
       const [_id, loader] = loadableField(args, fetchOptions ?? {});
       setState(loader());
     },
-    fragmentReference: state,
+    fragmentReference: state !== UNASSIGNED_STATE ? state : null,
   };
 }

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -1,11 +1,4 @@
-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,
@@ -14,18 +7,34 @@ import {
   createReferenceCountedPointer,
   ReferenceCountedPointer,
 } from '@isograph/reference-counted-pointer';
+import { useState } from 'react';
+import { subscribeToAnyChange } from '../core/cache';
+import { FetchOptions } from '../core/check';
+import {
+  FragmentReference,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
-import { type WithEncounteredRecords } from '../core/read';
+import {
+  readButDoNotEvaluate,
+  type WithEncounteredRecords,
+} from '../core/read';
+import { LoadableField, type ReaderAst } from '../core/reader';
+import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
+import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
-import { FetchOptions } from '../core/check';
+import { maybeUnwrapNetworkRequest } from '../react/useResult';
 
-type UseSkipLimitReturnValue<
-  TReadFromStore extends { data: object; parameters: object },
+export type UseSkipLimitReturnValue<
+  TReadFromStore extends UnknownTReadFromStore,
   TItem,
 > =
   | {
       readonly kind: 'Complete';
-      readonly fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
+      readonly fetchMore: (
+        count: number,
+        fetchOptions?: FetchOptions<ReadonlyArray<TItem>>,
+      ) => void;
       readonly results: ReadonlyArray<TItem>;
     }
   | {
@@ -38,7 +47,7 @@ type UseSkipLimitReturnValue<
     };
 
 type ArrayFragmentReference<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TItem,
 > = FragmentReference<TReadFromStore, ReadonlyArray<TItem>>;
 
@@ -64,17 +73,14 @@ function flatten<T>(arr: ReadonlyArray<ReadonlyArray<T>>): ReadonlyArray<T> {
   return outArray;
 }
 
-type UseSkipLimitPaginationArgs = {
+export type UseSkipLimitPaginationArgs = {
   skip: number;
   limit: number;
 };
 
 export function useSkipLimitPagination<
   TItem,
-  TReadFromStore extends {
-    parameters: object;
-    data: object;
-  },
+  TReadFromStore extends UnknownTReadFromStore,
 >(
   loadableField: LoadableField<
     TReadFromStore,
@@ -117,6 +123,16 @@ export function useSkipLimitPagination<
       const firstParameter = {
         data,
         parameters: fragmentReference.variables,
+        ...(readerWithRefetchQueries.readerArtifact.hasUpdatable
+          ? {
+              startUpdate: getOrCreateCachedStartUpdate(
+                environment,
+                fragmentReference,
+                readerWithRefetchQueries.readerArtifact.kind,
+                networkRequestOptions,
+              ),
+            }
+          : undefined),
       };
 
       if (
@@ -179,7 +195,10 @@ export function useSkipLimitPagination<
 
   const getFetchMore =
     (loadedSoFar: number) =>
-    (count: number, fetchOptions?: FetchOptions): void => {
+    (
+      count: number,
+      fetchOptions?: FetchOptions<ReadonlyArray<TItem>>,
+    ): void => {
       const loadedField = loadableField(
         {
           skip: loadedSoFar,

package/src/react/FragmentReader.tsx

@@ -1,43 +1,27 @@
-import * as React from 'react';
-import { ExtractReadFromStore, IsographEntrypoint } from '../core/entrypoint';
-import { FragmentReference } from '../core/FragmentReference';
+import {
+  type ExtractReadFromStore,
+  type IsographEntrypoint,
+} from '../core/entrypoint';
+import { type FragmentReference } from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
 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: IsExactlyIntrinsicAttributes<TProps> extends true
-    ? {
-        fragmentReference: FragmentReference<
-          ExtractReadFromStore<TEntrypoint>,
-          React.FC<TProps>
-        >;
-        additionalProps?: Record<PropertyKey, never>;
-        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
-      }
-    : {
-        fragmentReference: FragmentReference<
-          ExtractReadFromStore<TEntrypoint>,
-          React.FC<TProps>
-        >;
-        additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
-        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
-      },
-): React.ReactNode {
-  const Component = useResult(
-    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} />;
+  TResult,
+  TEntrypoint extends IsographEntrypoint<any, TResult, any>,
+  TChildrenResult,
+>({
+  fragmentReference,
+  networkRequestOptions,
+  children,
+}: {
+  fragmentReference: FragmentReference<
+    ExtractReadFromStore<TEntrypoint>,
+    TResult
+  >;
+  networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+  children: (data: TResult) => TChildrenResult;
+}): TChildrenResult {
+  const result = useResult(fragmentReference, networkRequestOptions);
+  return children(result);
 }

package/src/react/FragmentRenderer.tsx

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import {
+  type ExtractReadFromStore,
+  type IsographEntrypoint,
+} from '../core/entrypoint';
+import { type FragmentReference } from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
+import { useResult } from './useResult';
+
+export type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes
+  ? JSX.IntrinsicAttributes extends T
+    ? true
+    : false
+  : false;
+
+export function FragmentRenderer<
+  TProps extends Record<any, any>,
+  TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>, any>,
+>(
+  props: IsExactlyIntrinsicAttributes<TProps> extends true
+    ? {
+        fragmentReference: FragmentReference<
+          ExtractReadFromStore<TEntrypoint>,
+          React.FC<TProps>
+        >;
+        additionalProps?: Record<PropertyKey, never>;
+        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+      }
+    : {
+        fragmentReference: FragmentReference<
+          ExtractReadFromStore<TEntrypoint>,
+          React.FC<TProps>
+        >;
+        additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
+        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+      },
+): React.ReactNode {
+  const Component = useResult(
+    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/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/LoadableFieldReader.tsx

@@ -0,0 +1,40 @@
+import { type FetchOptions } from '../core/check';
+import {
+  ExtractParameters,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
+import { type LoadableField } from '../core/reader';
+import { useClientSideDefer } from '../loadable-hooks/useClientSideDefer';
+import { useResult } from './useResult';
+
+export function LoadableFieldReader<
+  TReadFromStore extends UnknownTReadFromStore,
+  TResult,
+  TProvidedArgs extends object,
+  TChildrenResult,
+>(props: {
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >;
+  // TODO we can improve this to not require args if its an empty object
+  args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>;
+  fetchOptions?: FetchOptions<TResult>;
+  networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+  children: (arg: TResult) => TChildrenResult;
+}): TChildrenResult {
+  const { fragmentReference } = useClientSideDefer(
+    props.loadableField,
+    props.args,
+    props.fetchOptions,
+  );
+
+  const readOutFragmentData = useResult(
+    fragmentReference,
+    props.networkRequestOptions,
+  );
+
+  return props.children(readOutFragmentData);
+}

package/src/react/LoadableFieldRenderer.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { type FetchOptions } from '../core/check';
+import {
+  ExtractParameters,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
+import { type LoadableField } from '../core/reader';
+import { useClientSideDefer } from '../loadable-hooks/useClientSideDefer';
+import { useResult } from './useResult';
+
+export function LoadableFieldRenderer<
+  TReadFromStore extends UnknownTReadFromStore,
+  TProvidedArgs extends object,
+  TChildrenResult,
+  TProps,
+>(props: {
+  loadableField: LoadableField<
+    TReadFromStore,
+    React.FC<TProps>,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >;
+  // TODO we can improve this to not require args if its an empty object
+  args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>;
+  fetchOptions?: FetchOptions<React.FC<TProps>>;
+  networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+  additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
+}): TChildrenResult {
+  const { fragmentReference } = useClientSideDefer(
+    props.loadableField,
+    props.args,
+    props.fetchOptions,
+  );
+
+  const Component = useResult(fragmentReference, props.networkRequestOptions);
+
+  // TODO we probably can figure out a way to convince TypeScript of
+  // the validity of this.
+  // @ts-expect-error
+  return <Component {...props.additionalProps} />;
+}

package/src/react/useImperativeReference.ts

@@ -1,60 +1,82 @@
 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 { wrapPromise, wrapResolvedValue } from '../core/PromiseWrapper';
+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 readerWithRefetchQueries =
+        entrypoint.readerWithRefetchQueries.kind ===
+        'ReaderWithRefetchQueriesLoader'
+          ? wrapPromise(entrypoint.readerWithRefetchQueries.loader())
+          : wrapResolvedValue(entrypoint.readerWithRefetchQueries);
       const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
         environment,
         entrypoint,
         variables,
-        fetchOptions,
+        readerWithRefetchQueries,
+        fetchOptions ?? null,
       );
       setState([
         {
           kind: 'FragmentReference',
-          readerWithRefetchQueries: wrapResolvedValue({
-            kind: 'ReaderWithRefetchQueries',
-            readerArtifact: entrypoint.readerWithRefetchQueries.readerArtifact,
-            nestedRefetchQueries:
-              entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
-          }),
+          readerWithRefetchQueries,
           root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
           variables,
           networkRequest,