@isograph/react 0.1.1 → 0.2.0

package/src/core/reader.ts

@@ -0,0 +1,133 @@
+import { Factory } from '@isograph/disposable-types';
+import { FragmentReference } from './FragmentReference';
+import {
+  ComponentOrFieldName,
+  DataId,
+  IsographEnvironment,
+} from './IsographEnvironment';
+import {
+  IsographEntrypoint,
+  IsographEntrypointLoader,
+  RefetchQueryNormalizationArtifact,
+  RefetchQueryNormalizationArtifactWrapper,
+} from './entrypoint';
+import { Arguments } from './util';
+
+export type TopLevelReaderArtifact<
+  TReadFromStore extends Object,
+  TClientFieldValue,
+  TComponentProps extends Record<string, never>,
+> =
+  | EagerReaderArtifact<TReadFromStore, TClientFieldValue>
+  | ComponentReaderArtifact<TReadFromStore, TComponentProps>;
+
+export type EagerReaderArtifact<
+  TReadFromStore extends Object,
+  TClientFieldValue,
+> = {
+  readonly kind: 'EagerReaderArtifact';
+  readonly readerAst: ReaderAst<TReadFromStore>;
+  readonly resolver: (data: TReadFromStore) => TClientFieldValue;
+};
+
+export type ComponentReaderArtifact<
+  TReadFromStore extends Object,
+  TComponentProps extends Record<string, unknown> = Record<string, never>,
+> = {
+  readonly kind: 'ComponentReaderArtifact';
+  readonly componentName: ComponentOrFieldName;
+  readonly readerAst: ReaderAst<TReadFromStore>;
+  readonly resolver: (
+    data: TReadFromStore,
+    runtimeProps: TComponentProps,
+  ) => React.ReactNode;
+};
+
+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,
+    rootId: DataId,
+    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;
+};
+
+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<TArgs, TResult> = (
+  args: TArgs,
+) => [StableId, Factory<FragmentReference<any, TResult>>];

package/src/core/util.ts

@@ -0,0 +1,23 @@
+export type ExtractSecondParam<T extends (arg1: any, arg2: any) => any> =
+  T extends (arg1: any, arg2: infer P) => any ? P : never;
+
+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,86 @@
+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,
+  defaultMissingFieldHandler,
+} from './core/IsographEnvironment';
+export {
+  type EagerReaderArtifact,
+  type ComponentReaderArtifact,
+  type RefetchReaderArtifact,
+  type ReaderAst,
+  type ReaderAstNode,
+  type ReaderLinkedField,
+  type ReaderNonLoadableResolverField,
+  type ReaderScalarField,
+  type TopLevelReaderArtifact,
+  type LoadableField,
+} 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,
+} from './core/entrypoint';
+export { readButDoNotEvaluate } from './core/read';
+export {
+  type ExtractSecondParam,
+  type Argument,
+  type ArgumentName,
+  type ArgumentValue,
+  type Arguments,
+} from './core/util';
+export {
+  type FragmentReference,
+  type Variables,
+  stableIdForFragmentReference,
+} from './core/FragmentReference';
+
+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 { useClientSideDefer } from './loadable-hooks/useClientSideDefer';
+export { useImperativeExposedMutationField } from './loadable-hooks/useImperativeExposedMutationField';
+export { useSkipLimitPagination } from './loadable-hooks/useSkipLimitPagination';
+export { useImperativeLoadableField } from './loadable-hooks/useImperativeLoadableField';

package/src/loadable-hooks/useClientSideDefer.ts

@@ -0,0 +1,28 @@
+import { 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';
+
+export function useClientSideDefer<TResult>(
+  loadableField: LoadableField<void, TResult>,
+): FragmentReference<Record<string, never>, TResult>;
+
+export function useClientSideDefer<TArgs extends Object, TResult>(
+  loadableField: LoadableField<TArgs, TResult>,
+  args: TArgs,
+): FragmentReference<TArgs, TResult>;
+
+export function useClientSideDefer<TArgs extends Object, TResult>(
+  loadableField: LoadableField<TArgs, TResult>,
+  args?: TArgs,
+): FragmentReference<TArgs, TResult> {
+  // @ts-expect-error args is missing iff it has the type void
+  const [id, loader] = loadableField(args);
+  const environment = useIsographEnvironment();
+  const cache = getOrCreateItemInSuspenseCache(environment, id, loader);
+
+  const fragmentReference = useLazyDisposableState(cache).state;
+
+  return fragmentReference;
+}

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();
+    },
+  };
+}

package/src/loadable-hooks/useImperativeLoadableField.ts

@@ -0,0 +1,26 @@
+import { FragmentReference } from '../core/FragmentReference';
+import {
+  UnassignedState,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import { LoadableField } from '../core/reader';
+
+type UseImperativeLoadableFieldReturn<TArgs, TResult> = {
+  fragmentReference: FragmentReference<any, TResult> | UnassignedState;
+  loadField: (args: TArgs) => void;
+};
+
+export function useImperativeLoadableField<TArgs, TResult>(
+  loadableField: LoadableField<TArgs, TResult>,
+): UseImperativeLoadableFieldReturn<TArgs, TResult> {
+  const { state, setState } =
+    useUpdatableDisposableState<FragmentReference<any, TResult>>();
+
+  return {
+    loadField: (args: TArgs) => {
+      const [_id, loader] = loadableField(args);
+      setState(loader());
+    },
+    fragmentReference: state,
+  };
+}

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -0,0 +1,211 @@
+import { LoadableField } 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 {
+  UNASSIGNED_STATE,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import {
+  createReferenceCountedPointer,
+  ReferenceCountedPointer,
+} from '@isograph/reference-counted-pointer';
+import { getPromiseState, readPromise } from '../core/PromiseWrapper';
+
+type SkipOrLimit = 'skip' | 'limit';
+type OmitSkipLimit<TArgs> = keyof Omit<TArgs, SkipOrLimit> extends never
+  ? void | Record<string, never>
+  : Omit<TArgs, SkipOrLimit>;
+
+type UseSkipLimitReturnValue<TArgs, TItem> =
+  | {
+      readonly kind: 'Complete';
+      readonly fetchMore: (args: OmitSkipLimit<TArgs>, count: number) => void;
+      readonly results: ReadonlyArray<TItem>;
+    }
+  | {
+      readonly kind: 'Pending';
+      readonly results: ReadonlyArray<TItem>;
+      readonly pendingFragment: FragmentReference<any, ReadonlyArray<TItem>>;
+    };
+
+type ArrayFragmentReference<TItem> = FragmentReference<
+  any,
+  ReadonlyArray<TItem>
+>;
+
+type LoadedFragmentReferences<TItem> = ReadonlyArray<
+  ItemCleanupPair<ReferenceCountedPointer<ArrayFragmentReference<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;
+}
+
+/**
+ * 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.
+ */
+export function useSkipLimitPagination<
+  TArgs extends {
+    skip: number | void | null;
+    limit: number | void | null;
+  },
+  TItem,
+>(
+  loadableField: LoadableField<TArgs, Array<TItem>>,
+): UseSkipLimitReturnValue<TArgs, TItem> {
+  const networkRequestOptions = {
+    suspendIfInFlight: true,
+    throwOnNetworkError: true,
+  };
+  const { state, setState } =
+    useUpdatableDisposableState<LoadedFragmentReferences<TItem>>();
+
+  const environment = useIsographEnvironment();
+
+  function readCompletedFragmentReferences(
+    completedReferences: ReadonlyArray<
+      ItemCleanupPair<ReferenceCountedPointer<ArrayFragmentReference<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) {
+        throw new Error(
+          'FragmentReference is unexpectedly disposed. \
+        This is indicative of a bug in Isograph.',
+        );
+      }
+
+      maybeUnwrapNetworkRequest(
+        fragmentReference.networkRequest,
+        networkRequestOptions,
+      );
+      const data = readButDoNotEvaluate(
+        environment,
+        fragmentReference,
+        networkRequestOptions,
+      );
+
+      const readerWithRefetchQueries = readPromise(
+        fragmentReference.readerWithRefetchQueries,
+      );
+
+      return readerWithRefetchQueries.readerArtifact.resolver(
+        data.item,
+        undefined,
+      ) as ReadonlyArray<any>;
+    });
+
+    const items = flatten(results);
+    return items;
+  }
+
+  const getFetchMore =
+    (loadedSoFar: number) =>
+    (args: OmitSkipLimit<TArgs>, count: number): void => {
+      // @ts-expect-error
+      const loadedField = loadableField({
+        ...args,
+        skip: loadedSoFar,
+        limit: count,
+      })[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<TItem>>
+          >
+        >
+      > = [
+        clonedPointers,
+        () => {
+          clonedPointers.forEach(([, dispose]) => {
+            dispose();
+          });
+        },
+      ];
+
+      setState(totalItemCleanupPair);
+    };
+
+  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) {
+    throw new Error(
+      'FragmentReference is unexpectedly disposed. \
+        This is indicative of a bug in Isograph.',
+    );
+  }
+
+  const networkRequestStatus = getPromiseState(
+    mostRecentFragmentReference.networkRequest,
+  );
+  switch (networkRequestStatus.kind) {
+    case 'Pending': {
+      const completedFragmentReferences = loadedReferences.slice(
+        0,
+        loadedReferences.length - 1,
+      );
+      return {
+        kind: 'Pending',
+        pendingFragment: mostRecentFragmentReference,
+        results: readCompletedFragmentReferences(completedFragmentReferences),
+      };
+    }
+    case 'Err': {
+      throw networkRequestStatus.error;
+    }
+    case 'Ok': {
+      const results = readCompletedFragmentReferences(loadedReferences);
+      return {
+        kind: 'Complete',
+        results,
+        fetchMore: getFetchMore(results.length),
+      };
+    }
+  }
+}

package/src/react/FragmentReader.tsx

@@ -0,0 +1,34 @@
+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';
+
+export function FragmentReader<
+  TProps extends Record<any, any>,
+  TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>>,
+>(
+  props: TProps extends Record<string, never>
+    ? {
+        fragmentReference: FragmentReference<
+          ExtractReadFromStore<TEntrypoint>,
+          React.FC<{}>
+        >;
+        additionalProps?: TProps;
+        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+      }
+    : {
+        fragmentReference: FragmentReference<
+          ExtractReadFromStore<TEntrypoint>,
+          React.FC<TProps>
+        >;
+        additionalProps: TProps;
+        networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+      },
+): React.ReactNode {
+  const Component = useResult(
+    props.fragmentReference,
+    props.networkRequestOptions,
+  );
+  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/useImperativeReference.ts

@@ -0,0 +1,57 @@
+import {
+  UnassignedState,
+  useUpdatableDisposableState,
+} from '@isograph/react-disposable-state';
+import { IsographEntrypoint } from '../core/entrypoint';
+import { FragmentReference, Variables } from '../core/FragmentReference';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { ROOT_ID } from '../core/IsographEnvironment';
+import { makeNetworkRequest } from '../core/makeNetworkRequest';
+import { wrapResolvedValue } from '../core/PromiseWrapper';
+
+// TODO rename this to useImperativelyLoadedEntrypoint
+
+export function useImperativeReference<
+  TReadFromStore extends Object,
+  TClientFieldValue,
+>(
+  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+): {
+  fragmentReference:
+    | FragmentReference<TReadFromStore, TClientFieldValue>
+    | UnassignedState;
+  loadFragmentReference: (variables: Variables) => void;
+} {
+  const { state, setState } =
+    useUpdatableDisposableState<
+      FragmentReference<TReadFromStore, TClientFieldValue>
+    >();
+  const environment = useIsographEnvironment();
+  return {
+    fragmentReference: state,
+    loadFragmentReference: (variables: Variables) => {
+      const [networkRequest, disposeNetworkRequest] = makeNetworkRequest(
+        environment,
+        entrypoint,
+        variables,
+      );
+      setState([
+        {
+          kind: 'FragmentReference',
+          readerWithRefetchQueries: wrapResolvedValue({
+            kind: 'ReaderWithRefetchQueries',
+            readerArtifact: entrypoint.readerWithRefetchQueries.readerArtifact,
+            nestedRefetchQueries:
+              entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
+          }),
+          root: ROOT_ID,
+          variables,
+          networkRequest,
+        },
+        () => {
+          disposeNetworkRequest();
+        },
+      ]);
+    },
+  };
+}

package/src/react/useLazyReference.ts

@@ -0,0 +1,22 @@
+import { FragmentReference, Variables } from '../core/FragmentReference';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { IsographEntrypoint } from '../core/entrypoint';
+import { getOrCreateCacheForArtifact } from '../core/cache';
+import { useLazyDisposableState } from '@isograph/react-disposable-state';
+
+export function useLazyReference<
+  TReadFromStore extends Object,
+  TClientFieldValue,
+>(
+  entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>,
+  variables: Variables,
+): {
+  fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
+} {
+  const environment = useIsographEnvironment();
+  const cache = getOrCreateCacheForArtifact(environment, entrypoint, variables);
+
+  return {
+    fragmentReference: useLazyDisposableState(cache).state,
+  };
+}