@isograph/react 0.1.1 → 0.3.0

package/src/loadable-hooks/useImperativeLoadableField.ts

@@ -0,0 +1,52 @@
+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<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+  TProvidedArgs extends object,
+> = {
+  fragmentReference:
+    | FragmentReference<TReadFromStore, TResult>
+    | UnassignedState;
+  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,
+  ) => void;
+};
+
+export function useImperativeLoadableField<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+  TProvidedArgs extends object,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >,
+): UseImperativeLoadableFieldReturn<TReadFromStore, TResult, TProvidedArgs> {
+  const { state, setState } =
+    useUpdatableDisposableState<FragmentReference<TReadFromStore, TResult>>();
+
+  return {
+    loadField: (
+      args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
+      fetchOptions?: FetchOptions,
+    ) => {
+      const [_id, loader] = loadableField(args, fetchOptions ?? {});
+      setState(loader());
+    },
+    fragmentReference: state,
+  };
+}

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -0,0 +1,352 @@
+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,
+} from '@isograph/react-disposable-state';
+import {
+  createReferenceCountedPointer,
+  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 UseSkipLimitReturnValue<
+  TReadFromStore extends { data: object; parameters: object },
+  TItem,
+> =
+  | {
+      readonly kind: 'Complete';
+      readonly fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
+      readonly results: ReadonlyArray<TItem>;
+    }
+  | {
+      readonly kind: 'Pending';
+      readonly results: ReadonlyArray<TItem>;
+      readonly pendingFragment: FragmentReference<
+        TReadFromStore,
+        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 LoadedFragmentReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = ItemCleanupPair<
+  ReferenceCountedPointer<ArrayFragmentReference<TReadFromStore, TItem>>
+>;
+
+function flatten<T>(arr: ReadonlyArray<ReadonlyArray<T>>): ReadonlyArray<T> {
+  let outArray: Array<T> = [];
+  for (const subarr of arr) {
+    for (const item of subarr) {
+      outArray.push(item);
+    }
+  }
+  return outArray;
+}
+
+type UseSkipLimitPaginationArgs = {
+  skip: number;
+  limit: number;
+};
+
+export function useSkipLimitPagination<
+  TItem,
+  TReadFromStore extends {
+    parameters: object;
+    data: object;
+  },
+>(
+  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<TReadFromStore, TItem>
+    >();
+
+  const environment = useIsographEnvironment();
+
+  // TODO move this out of useSkipLimitPagination, and pass environment and networkRequestOptions
+  // as parameters (or recreate networkRequestOptions)
+  function readCompletedFragmentReferences(
+    completedReferences: ArrayFragmentReference<TReadFromStore, TItem>[],
+  ) {
+    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(
+          'Parameter data is unexpectedly null. This is indicative of a bug in Isograph.',
+        );
+      }
+
+      const firstParameter = {
+        data,
+        parameters: fragmentReference.variables,
+      };
+
+      if (
+        readerWithRefetchQueries.readerArtifact.kind !== 'EagerReaderArtifact'
+      ) {
+        throw new Error(
+          `@loadable field of kind "${readerWithRefetchQueries.readerArtifact.kind}" is not supported by useSkipLimitPagination`,
+        );
+      }
+
+      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) =>
+    (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.',
+          );
+        }
+        return clonedRefCountedPointer;
+      });
+      clonedPointers.push(newPointer);
+
+      const totalItemCleanupPair: ItemCleanupPair<
+        ReadonlyArray<
+          ItemCleanupPair<
+            ReferenceCountedPointer<
+              ArrayFragmentReference<TReadFromStore, TItem>
+            >
+          >
+        >
+      > = [
+        clonedPointers,
+        () => {
+          clonedPointers.forEach(([, dispose]) => {
+            dispose();
+          });
+        },
+      ];
+
+      setState(totalItemCleanupPair);
+    };
+
+  const [, rerender] = useState({});
+
+  const loadedReferences = state === UNASSIGNED_STATE ? [] : state;
+
+  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.',
+    );
+  }
+
+  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 unsubscribe = subscribeToAnyChange(environment, () => {
+        unsubscribe();
+        rerender({});
+      });
+
+      return {
+        kind: 'Pending',
+        pendingFragment: mostRecentFragmentReference,
+        results: readCompletedFragmentReferences(completedFragmentReferences),
+      };
+    }
+    case 'Err': {
+      throw networkRequestStatus.error;
+    }
+    case 'Ok': {
+      const results = readCompletedFragmentReferences(
+        completedFragmentReferences,
+      );
+      return {
+        kind: 'Complete',
+        results,
+        fetchMore: getFetchMore(results.length),
+      };
+    }
+  }
+}
+
+// @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

@@ -0,0 +1,43 @@
+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';
+
+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} />;
+}

package/src/react/IsographEnvironmentProvider.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { ReactNode, createContext, useContext } from 'react';
+import { type IsographEnvironment } from '../core/IsographEnvironment';
+
+export const IsographEnvironmentContext =
+  createContext<IsographEnvironment | null>(null);
+
+export type IsographEnvironmentProviderProps = {
+  readonly environment: IsographEnvironment;
+  readonly children: ReactNode;
+};
+
+export function IsographEnvironmentProvider({
+  environment,
+  children,
+}: IsographEnvironmentProviderProps): React.ReactElement {
+  return (
+    <IsographEnvironmentContext.Provider value={environment}>
+      {children}
+    </IsographEnvironmentContext.Provider>
+  );
+}
+
+export function useIsographEnvironment(): IsographEnvironment {
+  const context = useContext(IsographEnvironmentContext);
+  if (context == null) {
+    throw new Error(
+      'Unexpected null environment context. Make sure to render ' +
+        'this component within an IsographEnvironmentProvider component',
+    );
+  }
+  return context;
+}

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

@@ -0,0 +1,68 @@
+import {
+  UnassignedState,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import { IsographEntrypoint } from '../core/entrypoint';
+import {
+  FragmentReference,
+  ExtractParameters,
+} 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
+
+export function useImperativeReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+>(
+  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+): {
+  fragmentReference:
+    | FragmentReference<TReadFromStore, TClientFieldValue>
+    | UnassignedState;
+  loadFragmentReference: (
+    variables: ExtractParameters<TReadFromStore>,
+    fetchOptions?: FetchOptions,
+  ) => void;
+} {
+  const { state, setState } =
+    useUpdatableDisposableState<
+      FragmentReference<TReadFromStore, TClientFieldValue>
+    >();
+  const environment = useIsographEnvironment();
+  return {
+    fragmentReference: state,
+    loadFragmentReference: (
+      variables: ExtractParameters<TReadFromStore>,
+      fetchOptions?: FetchOptions,
+    ) => {
+      const [networkRequest, disposeNetworkRequest] = maybeMakeNetworkRequest(
+        environment,
+        entrypoint,
+        variables,
+        fetchOptions,
+      );
+      setState([
+        {
+          kind: 'FragmentReference',
+          readerWithRefetchQueries: wrapResolvedValue({
+            kind: 'ReaderWithRefetchQueries',
+            readerArtifact: entrypoint.readerWithRefetchQueries.readerArtifact,
+            nestedRefetchQueries:
+              entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
+          }),
+          root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
+          variables,
+          networkRequest,
+        },
+        () => {
+          disposeNetworkRequest();
+        },
+      ]);
+    },
+  };
+}

package/src/react/useLazyReference.ts

@@ -0,0 +1,42 @@
+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 { parameters: object; data: object },
+  TClientFieldValue,
+>(
+  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+  variables: ExtractParameters<TReadFromStore>,
+  fetchOptions?: FetchOptions,
+): {
+  fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
+} {
+  const environment = useIsographEnvironment();
+
+  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

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react';
+import {
+  FragmentReference,
+  stableIdForFragmentReference,
+  ExtractData,
+} from '../core/FragmentReference';
+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';
+
+/**
+ * Read the data from a fragment reference and subscribe to updates.
+ */
+export function useReadAndSubscribe<
+  TReadFromStore extends { parameters: object; data: object },
+>(
+  fragmentReference: FragmentReference<TReadFromStore, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  readerAst: ReaderAst<TReadFromStore>,
+): ExtractData<TReadFromStore> {
+  const environment = useIsographEnvironment();
+  const [readOutDataAndRecords, setReadOutDataAndRecords] = useState(() =>
+    readButDoNotEvaluate(environment, fragmentReference, networkRequestOptions),
+  );
+  useRerenderOnChange(
+    readOutDataAndRecords,
+    fragmentReference,
+    setReadOutDataAndRecords,
+    readerAst,
+  );
+  return readOutDataAndRecords.item;
+}
+
+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, readerAst }) => {
+          return subscribe(
+            environment,
+            records,
+            fragmentReference,
+            callback,
+            readerAst,
+          );
+        },
+      );
+      return () => {
+        cleanupFns.forEach((loader) => {
+          loader();
+        });
+      };
+    },
+    // By analogy to useReadAndSubscribe, we can have an empty dependency array?
+    // Maybe callback has to be depended on. I don't know!
+    // TODO find out
+    [
+      items
+        .map(({ fragmentReference }) =>
+          stableIdForFragmentReference(fragmentReference),
+        )
+        .join('.'),
+    ],
+  );
+}