@isograph/react 0.3.1 → 0.4.1

package/src/core/startUpdate.ts

@@ -1,28 +1,334 @@
+import {
+  callSubscriptions,
+  getParentRecordKey,
+  insertEmptySetIfMissing,
+  type EncounteredIds,
+} from './cache';
+import type { RefetchQueryNormalizationArtifactWrapper } from './entrypoint';
 import {
   stableIdForFragmentReference,
+  type ExtractParameters,
   type ExtractStartUpdate,
+  type ExtractUpdatableData,
   type FragmentReference,
   type UnknownTReadFromStore,
 } from './FragmentReference';
-import type { IsographEnvironment } from './IsographEnvironment';
+import {
+  assertLink,
+  type IsographEnvironment,
+  type StoreLink,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
+import { readPromise, type PromiseWrapper } from './PromiseWrapper';
+import {
+  readImperativelyLoadedField,
+  readLinkedFieldData,
+  readLoadablySelectedFieldData,
+  readResolverFieldData,
+  readScalarFieldData,
+  type NetworkRequestReaderOptions,
+  type ReadDataResultSuccess,
+} from './read';
+import type { ReaderAst } from './reader';
 
 export function getOrCreateCachedStartUpdate<
   TReadFromStore extends UnknownTReadFromStore,
 >(
   environment: IsographEnvironment,
-  fragmentReference: FragmentReference<TReadFromStore, any>,
+  fragmentReference: FragmentReference<TReadFromStore, unknown>,
   eagerResolverName: string,
+  networkRequestOptions: NetworkRequestReaderOptions,
 ): ExtractStartUpdate<TReadFromStore> {
   return (environment.eagerReaderCache[
     stableIdForFragmentReference(fragmentReference, eagerResolverName)
-  ] ??= createStartUpdate(environment, fragmentReference));
+  ] ??= createStartUpdate(
+    environment,
+    fragmentReference,
+    networkRequestOptions,
+  ));
 }
 
 export function createStartUpdate<TReadFromStore extends UnknownTReadFromStore>(
-  _environment: IsographEnvironment,
-  _fragmentReference: FragmentReference<TReadFromStore, any>,
+  environment: IsographEnvironment,
+  fragmentReference: FragmentReference<TReadFromStore, unknown>,
+  networkRequestOptions: NetworkRequestReaderOptions,
 ): ExtractStartUpdate<TReadFromStore> {
-  return (_updater) => {
-    // TODO start update
+  return (updater) => {
+    let mutableUpdatedIds: EncounteredIds = new Map();
+
+    let data = createUpdatableProxy(
+      environment,
+      fragmentReference,
+      networkRequestOptions,
+      mutableUpdatedIds,
+    );
+
+    try {
+      updater(data);
+    } catch (e) {
+      logMessage(environment, () => ({
+        kind: 'StartUpdateError',
+        error: e,
+      }));
+      throw e;
+    } finally {
+      logMessage(environment, () => ({
+        kind: 'StartUpdateComplete',
+        updatedIds: mutableUpdatedIds,
+      }));
+      callSubscriptions(environment, mutableUpdatedIds);
+    }
+  };
+}
+
+export function createUpdatableProxy<
+  TReadFromStore extends UnknownTReadFromStore,
+>(
+  environment: IsographEnvironment,
+  fragmentReference: FragmentReference<TReadFromStore, unknown>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  mutableUpdatedIds: EncounteredIds,
+): ExtractUpdatableData<TReadFromStore> {
+  const readerWithRefetchQueries = readPromise(
+    fragmentReference.readerWithRefetchQueries,
+  );
+
+  return readUpdatableData(
+    environment,
+    readerWithRefetchQueries.readerArtifact.readerAst,
+    fragmentReference.root,
+    fragmentReference.variables ?? {},
+    readerWithRefetchQueries.nestedRefetchQueries,
+    fragmentReference.networkRequest,
+    networkRequestOptions,
+    {
+      lastInvalidated: 0,
+    },
+    mutableUpdatedIds,
+  ).data;
+}
+
+type MutableInvalidationState = {
+  lastInvalidated: number;
+};
+
+function defineCachedProperty<T>(
+  target: T,
+  property: PropertyKey,
+  mutableState: MutableInvalidationState,
+  get: () => any,
+  set?: (v: any) => void,
+) {
+  let value:
+    | { kind: 'Set'; value: T; validatedAt: number }
+    | {
+        kind: 'NotSet';
+      } = {
+    kind: 'NotSet',
+  };
+
+  Object.defineProperty(target, property, {
+    configurable: false,
+    enumerable: true,
+    get: () => {
+      if (
+        value.kind === 'NotSet' ||
+        value.validatedAt < mutableState.lastInvalidated
+      ) {
+        value = {
+          kind: 'Set',
+          value: get(),
+          validatedAt: mutableState.lastInvalidated,
+        };
+      }
+      return value.value;
+    },
+    ...(set && {
+      set: (newValue) => {
+        set(newValue);
+        mutableState.lastInvalidated++;
+      },
+    }),
+  });
+}
+
+function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
+  environment: IsographEnvironment,
+  ast: ReaderAst<TReadFromStore>,
+  root: StoreLink,
+  variables: ExtractParameters<TReadFromStore>,
+  nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  mutableState: MutableInvalidationState,
+  mutableUpdatedIds: EncounteredIds,
+): ReadDataResultSuccess<ExtractUpdatableData<TReadFromStore>> {
+  let storeRecord = environment.store[root.__typename]?.[root.__link];
+  if (storeRecord == null) {
+    return {
+      kind: 'Success',
+      data: null as any,
+    };
+  }
+
+  let target: { [index: string]: any } = {};
+
+  for (const field of ast) {
+    switch (field.kind) {
+      case 'Scalar': {
+        const storeRecordName = getParentRecordKey(field, variables);
+
+        defineCachedProperty(
+          target,
+          field.alias ?? field.fieldName,
+          mutableState,
+          () => {
+            const data = readScalarFieldData(
+              field,
+              storeRecord,
+              root,
+              variables,
+            );
+            if (data.kind === 'MissingData') {
+              throw new Error(data.reason);
+            }
+            return data.data;
+          },
+          field.isUpdatable
+            ? (newValue) => {
+                storeRecord[storeRecordName] = newValue;
+                const updatedIds = insertEmptySetIfMissing(
+                  mutableUpdatedIds,
+                  root.__typename,
+                );
+                updatedIds.add(root.__link);
+              }
+            : undefined,
+        );
+        break;
+      }
+      case 'Linked': {
+        const storeRecordName = getParentRecordKey(field, variables);
+        defineCachedProperty(
+          target,
+          field.alias ?? field.fieldName,
+          mutableState,
+          () => {
+            const data = readLinkedFieldData(
+              environment,
+              field,
+              storeRecord,
+              root,
+              variables,
+              nestedRefetchQueries,
+              networkRequest,
+              networkRequestOptions,
+              (ast, root) =>
+                readUpdatableData(
+                  environment,
+                  ast,
+                  root,
+                  variables,
+                  nestedRefetchQueries,
+                  networkRequest,
+                  networkRequestOptions,
+                  mutableState,
+                  mutableUpdatedIds,
+                ),
+            );
+            if (data.kind === 'MissingData') {
+              throw new Error(data.reason);
+            }
+            return data.data;
+          },
+          'isUpdatable' in field && field.isUpdatable
+            ? (newValue) => {
+                if (Array.isArray(newValue)) {
+                  storeRecord[storeRecordName] = newValue.map((node) =>
+                    assertLink(node?.link),
+                  );
+                } else {
+                  storeRecord[storeRecordName] = assertLink(newValue?.link);
+                }
+                const updatedIds = insertEmptySetIfMissing(
+                  mutableUpdatedIds,
+                  root.__typename,
+                );
+                updatedIds.add(root.__link);
+              }
+            : undefined,
+        );
+        break;
+      }
+      case 'ImperativelyLoadedField': {
+        defineCachedProperty(target, field.alias, mutableState, () => {
+          const data = readImperativelyLoadedField(
+            environment,
+            field,
+            root,
+            variables,
+            nestedRefetchQueries,
+            networkRequest,
+            networkRequestOptions,
+            new Map(),
+          );
+          if (data.kind === 'MissingData') {
+            throw new Error(data.reason);
+          }
+          return data.data;
+        });
+        break;
+      }
+      case 'Resolver': {
+        defineCachedProperty(target, field.alias, mutableState, () => {
+          const data = readResolverFieldData(
+            environment,
+            field,
+            root,
+            variables,
+            nestedRefetchQueries,
+            networkRequest,
+            networkRequestOptions,
+            new Map(),
+          );
+          if (data.kind === 'MissingData') {
+            throw new Error(data.reason);
+          }
+          return data.data;
+        });
+        break;
+      }
+      case 'LoadablySelectedField': {
+        defineCachedProperty(target, field.alias, mutableState, () => {
+          const data = readLoadablySelectedFieldData(
+            environment,
+            field,
+            root,
+            variables,
+            networkRequest,
+            networkRequestOptions,
+            new Map(),
+          );
+          if (data.kind === 'MissingData') {
+            throw new Error(data.reason);
+          }
+          return data.data;
+        });
+        break;
+      }
+      case 'Link': {
+        target[field.alias] = root;
+        break;
+      }
+      default: {
+        field satisfies never;
+        throw new Error('Unexpected case.');
+      }
+    }
+  }
+
+  return {
+    kind: 'Success',
+    data: target as any,
   };
 }

package/src/core/util.ts

@@ -1,9 +1,11 @@
+import type React from 'react';
+
 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;
+    ? React.JSX.IntrinsicAttributes
+    : T & React.JSX.IntrinsicAttributes;
 
 export type Arguments = Argument[];
 export type Argument = [ArgumentName, ArgumentValue];

package/src/index.ts

@@ -18,6 +18,7 @@ export {
   NOT_SET,
 } from './core/PromiseWrapper';
 export {
+  callSubscriptions,
   subscribe,
   normalizeData,
   type NetworkResponseObject,
@@ -34,6 +35,7 @@ export {
   type IsographNetworkFunction,
   type IsographStore,
   type MissingFieldHandler,
+  type StoreLink,
   type Link,
   type StoreRecord,
   type CacheMap,
@@ -63,7 +65,7 @@ export {
   type StableId,
   type ResolverFirstParameter,
   type ReaderImperativelyLoadedField,
-  type ReaderLoadableField,
+  type LoadablySelectedField as ReaderLoadableField,
   type ReaderLinkField,
   type StartUpdate,
 } from './core/reader';
@@ -75,6 +77,9 @@ export {
   type NormalizationLinkedField,
   type NormalizationScalarField,
   type IsographEntrypoint,
+  type IsographOperation,
+  type IsographPersistedOperation,
+  type IsographPersistedOperationExtraInfo,
   assertIsEntrypoint,
   type RefetchQueryNormalizationArtifact,
   type RefetchQueryNormalizationArtifactWrapper,
@@ -137,9 +142,12 @@ export {
   type UseImperativeReferenceResult,
 } from './react/useImperativeReference';
 export {
-  FragmentReader,
+  FragmentRenderer,
   type IsExactlyIntrinsicAttributes,
-} from './react/FragmentReader';
+} from './react/FragmentRenderer';
+export { FragmentReader } from './react/FragmentReader';
+export { LoadableFieldReader } from './react/LoadableFieldReader';
+export { LoadableFieldRenderer } from './react/LoadableFieldRenderer';
 export { useResult } from './react/useResult';
 export {
   useReadAndSubscribe,

package/src/loadable-hooks/useConnectionSpecPagination.ts

@@ -135,6 +135,7 @@ export function useConnectionSpecPagination<
                 environment,
                 fragmentReference,
                 readerWithRefetchQueries.readerArtifact.fieldName,
+                networkRequestOptions,
               ),
             }
           : undefined),

package/src/loadable-hooks/useImperativeExposedMutationField.ts

@@ -1,5 +1,5 @@
 export type UseImperativeLoadableFieldReturn<TArgs> = {
-  loadField: (args: TArgs) => void;
+  loadFragmentReference: (args: TArgs) => void;
 };
 
 // Note: this function doesn't seem to work if there are additional arguments,
@@ -9,7 +9,7 @@ export function useImperativeExposedMutationField<TArgs>(
   exposedField: (args: TArgs) => [string, () => void],
 ): UseImperativeLoadableFieldReturn<TArgs> {
   return {
-    loadField: (args: TArgs) => {
+    loadFragmentReference: (args: TArgs) => {
       const [_id, loader] = exposedField(args);
       loader();
     },

package/src/loadable-hooks/useImperativeLoadableField.ts

@@ -15,7 +15,7 @@ export type UseImperativeLoadableFieldReturn<
   TProvidedArgs extends object,
 > = {
   fragmentReference: FragmentReference<TReadFromStore, TResult> | null;
-  loadField: (
+  loadFragmentReference: (
     // TODO this should be void iff all args are provided by the query, like in
     // useClientSideDefer.
     args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
@@ -38,7 +38,7 @@ export function useImperativeLoadableField<
     useUpdatableDisposableState<FragmentReference<TReadFromStore, TResult>>();
 
   return {
-    loadField: (
+    loadFragmentReference: (
       args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs> | void,
       fetchOptions?: FetchOptions<TResult>,
     ) => {

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -129,6 +129,7 @@ export function useSkipLimitPagination<
                 environment,
                 fragmentReference,
                 readerWithRefetchQueries.readerArtifact.kind,
+                networkRequestOptions,
               ),
             }
           : undefined),

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 { NetworkRequestReaderOptions } from '../core/read';
+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 FragmentReader<
-  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} />;
+  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/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

@@ -15,7 +15,7 @@ import {
 } from '../core/FragmentReference';
 import { ROOT_ID } from '../core/IsographEnvironment';
 import { maybeMakeNetworkRequest } from '../core/makeNetworkRequest';
-import { wrapResolvedValue } from '../core/PromiseWrapper';
+import { wrapPromise, wrapResolvedValue } from '../core/PromiseWrapper';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
 
 export type UseImperativeReferenceResult<
@@ -61,21 +61,22 @@ export function useImperativeReference<
       variables: ExtractParameters<TReadFromStore>,
       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,