@isograph/react 0.1.1 → 0.3.0

package/src/core/reader.ts

@@ -0,0 +1,160 @@
+import { Factory } from '@isograph/disposable-types';
+import {
+  FragmentReference,
+  ExtractParameters,
+  ExtractData,
+} from './FragmentReference';
+import {
+  ComponentOrFieldName,
+  IsographEnvironment,
+  type Link,
+} from './IsographEnvironment';
+import {
+  IsographEntrypoint,
+  IsographEntrypointLoader,
+  RefetchQueryNormalizationArtifact,
+  RefetchQueryNormalizationArtifactWrapper,
+} from './entrypoint';
+import { Arguments } from './util';
+import { FetchOptions } from './check';
+
+export type TopLevelReaderArtifact<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+  TComponentProps extends Record<PropertyKey, never>,
+> =
+  | EagerReaderArtifact<TReadFromStore, TClientFieldValue>
+  | ComponentReaderArtifact<TReadFromStore, TComponentProps>;
+
+export type EagerReaderArtifact<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+> = {
+  readonly kind: 'EagerReaderArtifact';
+  readonly readerAst: ReaderAst<TReadFromStore>;
+  readonly resolver: (
+    data: ResolverFirstParameter<TReadFromStore>,
+  ) => TClientFieldValue;
+};
+
+export type ComponentReaderArtifact<
+  TReadFromStore extends { parameters: object; data: object },
+  TComponentProps extends Record<string, unknown> = Record<PropertyKey, never>,
+> = {
+  readonly kind: 'ComponentReaderArtifact';
+  readonly componentName: ComponentOrFieldName;
+  readonly readerAst: ReaderAst<TReadFromStore>;
+  readonly resolver: (
+    data: ResolverFirstParameter<TReadFromStore>,
+    runtimeProps: TComponentProps,
+  ) => React.ReactNode;
+};
+
+export type ResolverFirstParameter<
+  TReadFromStore extends { data: object; parameters: object },
+> = {
+  data: ExtractData<TReadFromStore>;
+  parameters: ExtractParameters<TReadFromStore>;
+};
+
+export type RefetchReaderArtifact = {
+  readonly kind: 'RefetchReaderArtifact';
+  readonly readerAst: ReaderAst<unknown>;
+  readonly resolver: (
+    environment: IsographEnvironment,
+    artifact: RefetchQueryNormalizationArtifact,
+    // TODO type this better
+    variables: any,
+    // TODO type this better
+    filteredVariables: any,
+    rootLink: Link,
+    readerArtifact: TopLevelReaderArtifact<any, any, any> | null,
+    // TODO type this better
+    nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  ) => () => void;
+};
+
+export type ReaderAstNode =
+  | ReaderScalarField
+  | ReaderLinkedField
+  | ReaderNonLoadableResolverField
+  | ReaderImperativelyLoadedField
+  | ReaderLoadableField;
+
+// @ts-ignore
+export type ReaderAst<TReadFromStore> = ReadonlyArray<ReaderAstNode>;
+
+export type ReaderScalarField = {
+  readonly kind: 'Scalar';
+  readonly fieldName: string;
+  readonly alias: string | null;
+  readonly arguments: Arguments | null;
+};
+export type ReaderLinkedField = {
+  readonly kind: 'Linked';
+  readonly fieldName: string;
+  readonly alias: string | null;
+  readonly selections: ReaderAst<unknown>;
+  readonly arguments: Arguments | null;
+  readonly condition: EagerReaderArtifact<
+    { data: object; parameters: object },
+    boolean | Link | null
+  > | null;
+};
+
+export type ReaderNonLoadableResolverField = {
+  readonly kind: 'Resolver';
+  readonly alias: string;
+  // TODO don't type this as any
+  readonly readerArtifact: TopLevelReaderArtifact<any, any, any>;
+  readonly arguments: Arguments | null;
+  readonly usedRefetchQueries: number[];
+};
+
+export type ReaderImperativelyLoadedField = {
+  readonly kind: 'ImperativelyLoadedField';
+  readonly alias: string;
+  readonly refetchReaderArtifact: RefetchReaderArtifact;
+  readonly refetchQuery: number;
+  readonly name: string;
+};
+
+export type ReaderLoadableField = {
+  readonly kind: 'LoadablySelectedField';
+  readonly alias: string;
+
+  // To generate a stable id, we need the parent id + the name + the args that
+  // we pass to the field, which come from: queryArgs, refetchReaderAst
+  // (technically, but in practice that is always "id") and the user-provided args.
+  readonly name: string;
+  readonly queryArguments: Arguments | null;
+  readonly refetchReaderAst: ReaderAst<any>;
+
+  // TODO we should not type these as any
+  readonly entrypoint:
+    | IsographEntrypoint<any, any>
+    | IsographEntrypointLoader<any, any>;
+};
+
+type StableId = string;
+/// Why is LoadableField the way it is? Let's work backwards.
+///
+/// We ultimately need a stable id (for deduplication) and a way to produce a
+/// FragmentReference (i.e. a Factory). However, this stable id depends on the
+/// arguments that we pass in, hence we get the current form of LoadableField.
+///
+/// Passing TArgs to the LoadableField should be cheap and do no "actual" work,
+/// except to stringify the args or whatnot. Calling the factory can be
+/// expensive. For example, doing so will probably trigger a network request.
+export type LoadableField<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+  TArgs = ExtractParameters<TReadFromStore>,
+> = (
+  args: TArgs | void,
+  // Note: fetchOptions is not nullable here because a LoadableField is not a
+  // user-facing API. Users should only interact with LoadableFields via APIs
+  // like useClientSideDefer. These APIs should have a nullable fetchOptions
+  // parameter, and provide a default value ({}) to the LoadableField.
+  fetchOptions: FetchOptions,
+) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];

package/src/core/util.ts

@@ -0,0 +1,27 @@
+export type ExtractSecondParam<T extends (arg1: any, arg2: any) => any> =
+  T extends (arg1: any, arg2: infer P) => any ? P : never;
+export type CombineWithIntrinsicAttributes<T> =
+  T extends Record<PropertyKey, never>
+    ? JSX.IntrinsicAttributes
+    : T & JSX.IntrinsicAttributes;
+
+export type Arguments = Argument[];
+export type Argument = [ArgumentName, ArgumentValue];
+export type ArgumentName = string;
+export type ArgumentValue =
+  | {
+      readonly kind: 'Variable';
+      readonly name: string;
+    }
+  | {
+      readonly kind: 'Literal';
+      readonly value: any;
+    }
+  | {
+      readonly kind: 'String';
+      readonly value: string;
+    }
+  | {
+      readonly kind: 'Enum';
+      readonly value: string;
+    };

package/src/index.ts

@@ -0,0 +1,99 @@
+export {
+  retainQuery,
+  unretainQuery,
+  type RetainedQuery,
+  garbageCollectEnvironment,
+} from './core/garbageCollection';
+export {
+  type PromiseWrapper,
+  readPromise,
+  getPromiseState,
+  wrapResolvedValue,
+  wrapPromise,
+} from './core/PromiseWrapper';
+export { subscribe, normalizeData } from './core/cache';
+export { makeNetworkRequest } from './core/makeNetworkRequest';
+export {
+  ROOT_ID,
+  type DataId,
+  type DataTypeValue,
+  type IsographEnvironment,
+  type IsographNetworkFunction,
+  type IsographStore,
+  type Link,
+  type StoreRecord,
+  createIsographEnvironment,
+  createIsographStore,
+} from './core/IsographEnvironment';
+export {
+  type EagerReaderArtifact,
+  type ComponentReaderArtifact,
+  type RefetchReaderArtifact,
+  type ReaderAst,
+  type ReaderAstNode,
+  type ReaderLinkedField,
+  type ReaderNonLoadableResolverField,
+  type ReaderScalarField,
+  type TopLevelReaderArtifact,
+  type LoadableField,
+  type ResolverFirstParameter,
+} from './core/reader';
+export {
+  type NormalizationAst,
+  type NormalizationAstNode,
+  type NormalizationLinkedField,
+  type NormalizationScalarField,
+  type IsographEntrypoint,
+  assertIsEntrypoint,
+  type RefetchQueryNormalizationArtifact,
+  type RefetchQueryNormalizationArtifactWrapper,
+  type ExtractProps,
+  type ExtractReadFromStore,
+  type ExtractResolverResult,
+  type NetworkRequestInfo,
+} from './core/entrypoint';
+export { readButDoNotEvaluate } from './core/read';
+export {
+  type ExtractSecondParam,
+  type CombineWithIntrinsicAttributes,
+  type Argument,
+  type ArgumentName,
+  type ArgumentValue,
+  type Arguments,
+} from './core/util';
+export {
+  type FragmentReference,
+  type Variables,
+  type ExtractParameters,
+  type ExtractData,
+  stableIdForFragmentReference,
+} from './core/FragmentReference';
+export {
+  type LogMessage,
+  type LogFunction,
+  logMessage,
+  registerLogger,
+} from './core/logging';
+export { check, CheckResult, FetchOptions, ShouldFetch } from './core/check';
+
+export {
+  IsographEnvironmentProvider,
+  useIsographEnvironment,
+  type IsographEnvironmentProviderProps,
+} from './react/IsographEnvironmentProvider';
+export { useImperativeReference } from './react/useImperativeReference';
+export { FragmentReader } from './react/FragmentReader';
+export { useResult } from './react/useResult';
+export {
+  useReadAndSubscribe,
+  useSubscribeToMultiple,
+} from './react/useReadAndSubscribe';
+export { useLazyReference } from './react/useLazyReference';
+export { useRerenderOnChange } from './react/useRerenderOnChange';
+export { RenderAfterCommit__DO_NOT_USE } from './react/RenderAfterCommit__DO_NOT_USE';
+
+export { useClientSideDefer } from './loadable-hooks/useClientSideDefer';
+export { useImperativeExposedMutationField } from './loadable-hooks/useImperativeExposedMutationField';
+export { useSkipLimitPagination } from './loadable-hooks/useSkipLimitPagination';
+export { useConnectionSpecPagination } from './loadable-hooks/useConnectionSpecPagination';
+export { useImperativeLoadableField } from './loadable-hooks/useImperativeLoadableField';

package/src/loadable-hooks/useClientSideDefer.ts

@@ -0,0 +1,58 @@
+import {
+  ExtractParameters,
+  FragmentReference,
+} 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';
+
+export function useClientSideDefer<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    ExtractParameters<TReadFromStore>
+  >,
+  args?: Record<PropertyKey, never>,
+  fetchOptions?: FetchOptions,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
+
+export function useClientSideDefer<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+  TProvidedArgs extends object,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >,
+  args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
+
+export function useClientSideDefer<
+  TReadFromStore extends { data: object; parameters: object },
+  TResult,
+  TProvidedArgs extends object,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >,
+  args?: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> } {
+  const [id, loader] = loadableField(args, fetchOptions ?? {});
+  const environment = useIsographEnvironment();
+  const cache = getOrCreateItemInSuspenseCache(environment, id, loader);
+
+  const fragmentReference = useLazyDisposableState(cache).state;
+
+  return { fragmentReference };
+}

package/src/loadable-hooks/useConnectionSpecPagination.ts

@@ -0,0 +1,331 @@
+import { ItemCleanupPair } from '@isograph/disposable-types';
+import {
+  UNASSIGNED_STATE,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import {
+  createReferenceCountedPointer,
+  ReferenceCountedPointer,
+} from '@isograph/reference-counted-pointer';
+import { useState } from 'react';
+import { subscribeToAnyChange } from '../core/cache';
+import { FragmentReference } from '../core/FragmentReference';
+import { getPromiseState, readPromise } from '../core/PromiseWrapper';
+import {
+  readButDoNotEvaluate,
+  type WithEncounteredRecords,
+} from '../core/read';
+import { LoadableField, type ReaderAst } from '../core/reader';
+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 },
+  TItem,
+> =
+  | {
+      kind: 'Pending';
+      pendingFragment: FragmentReference<TReadFromStore, Connection<TItem>>;
+      results: ReadonlyArray<TItem>;
+    }
+  | {
+      kind: 'Complete';
+      fetchMore: (count: number, fetchOptions?: FetchOptions) => void;
+      results: ReadonlyArray<TItem>;
+      hasNextPage: boolean;
+    };
+
+type LoadedFragmentReferences<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = ReadonlyArray<LoadedFragmentReference<TReadFromStore, TItem>>;
+
+type LoadedFragmentReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TItem,
+> = ItemCleanupPair<
+  ReferenceCountedPointer<FragmentReference<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 PageInfo = {
+  readonly hasNextPage: boolean;
+  readonly endCursor: string | null;
+};
+
+type Connection<T> = {
+  readonly edges: ReadonlyArray<T> | null;
+  readonly pageInfo: PageInfo;
+};
+
+type NonNullConnection<T> = {
+  readonly edges: ReadonlyArray<T>;
+  readonly pageInfo: PageInfo;
+};
+
+type UseConnectionSpecPaginationArgs = {
+  first: number;
+  after: string | null;
+};
+
+export function useConnectionSpecPagination<
+  TReadFromStore extends {
+    parameters: object;
+    data: object;
+  },
+  TItem,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    Connection<TItem>,
+    UseConnectionSpecPaginationArgs
+  >,
+  initialState?: PageInfo,
+): UsePaginationReturnValue<TReadFromStore, TItem> {
+  const networkRequestOptions = {
+    suspendIfInFlight: true,
+    throwOnNetworkError: true,
+  };
+  const { state, setState } =
+    useUpdatableDisposableState<
+      LoadedFragmentReferences<TReadFromStore, Connection<TItem>>
+    >();
+
+  const environment = useIsographEnvironment();
+
+  // TODO move this out of useSkipLimitPagination, and pass environment and networkRequestOptions
+  // as parameters (or recreate networkRequestOptions)
+  function readCompletedFragmentReferences(
+    completedReferences: FragmentReference<TReadFromStore, Connection<TItem>>[],
+  ): NonNullConnection<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.map((result) => result.edges ?? []));
+
+    return {
+      edges: items,
+      pageInfo: results[results.length - 1]?.pageInfo ?? {
+        endCursor: null,
+        hasNextPage: true,
+      },
+    };
+  }
+
+  function subscribeCompletedFragmentReferences(
+    completedReferences: FragmentReference<TReadFromStore, Connection<TItem>>[],
+  ) {
+    return completedReferences.map(
+      (
+        fragmentReference,
+        i,
+      ): {
+        records: WithEncounteredRecords<TReadFromStore>;
+        callback: (
+          updatedRecords: WithEncounteredRecords<TReadFromStore>,
+        ) => void;
+        fragmentReference: FragmentReference<TReadFromStore, Connection<TItem>>;
+        readerAst: ReaderAst<Connection<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 =
+    (after: string | null) =>
+    (count: number, fetchOptions?: FetchOptions): void => {
+      const loadedField = loadableField(
+        {
+          after: after,
+          first: 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<
+              FragmentReference<TReadFromStore, Connection<TItem>>
+            >
+          >
+        >
+      > = [
+        clonedPointers,
+        () => {
+          clonedPointers.forEach(([, dispose]) => {
+            dispose();
+          });
+        },
+      ];
+
+      setState(totalItemCleanupPair);
+    };
+
+  const [, rerender] = useState({});
+
+  const loadedReferences = state === UNASSIGNED_STATE ? [] : state;
+
+  const mostRecentItem:
+    | LoadedFragmentReference<TReadFromStore, Connection<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?.endCursor ?? null),
+      results: [],
+      hasNextPage: initialState?.hasNextPage ?? true,
+    };
+  }
+
+  switch (networkRequestStatus.kind) {
+    case 'Pending': {
+      const unsubscribe = subscribeToAnyChange(environment, () => {
+        unsubscribe();
+        rerender({});
+      });
+
+      const results = readCompletedFragmentReferences(
+        completedFragmentReferences,
+      );
+      return {
+        results: results.edges,
+        kind: 'Pending',
+        pendingFragment: mostRecentFragmentReference,
+      };
+    }
+    case 'Err': {
+      throw networkRequestStatus.error;
+    }
+    case 'Ok': {
+      const results = readCompletedFragmentReferences(
+        completedFragmentReferences,
+      );
+
+      return {
+        results: results.edges,
+        hasNextPage: results.pageInfo.hasNextPage,
+        kind: 'Complete',
+        fetchMore: getFetchMore(results.pageInfo.endCursor),
+      };
+    }
+  }
+}

package/src/loadable-hooks/useImperativeExposedMutationField.ts

@@ -0,0 +1,17 @@
+type UseImperativeLoadableFieldReturn<TArgs> = {
+  loadField: (args: TArgs) => void;
+};
+
+// Note: this function doesn't seem to work if there are additional arguments,
+// e.g. with set_pet_tagline. Why? This seems to straightforwardly call
+// exposedField(args)[1](); Odd.
+export function useImperativeExposedMutationField<TArgs>(
+  exposedField: (args: TArgs) => [string, () => void],
+): UseImperativeLoadableFieldReturn<TArgs> {
+  return {
+    loadField: (args: TArgs) => {
+      const [_id, loader] = exposedField(args);
+      loader();
+    },
+  };
+}