@isograph/react 0.4.3 → 0.5.1

package/src/core/startUpdate.ts

@@ -1,5 +1,4 @@
 import {
-  callSubscriptions,
   getParentRecordKey,
   insertEmptySetIfMissing,
   type EncounteredIds,
@@ -19,6 +18,13 @@ import {
   type StoreLink,
 } from './IsographEnvironment';
 import { logMessage } from './logging';
+import {
+  addStartUpdateStoreLayer,
+  getMutableStoreRecordProxy,
+  getOrInsertRecord,
+  type StartUpdateStoreLayer,
+  type StoreLayer,
+} from './optimisticProxy';
 import { readPromise, type PromiseWrapper } from './PromiseWrapper';
 import {
   readImperativelyLoadedField,
@@ -30,17 +36,17 @@ import {
   type ReadDataResultSuccess,
 } from './read';
 import type { ReaderAst } from './reader';
+import { callSubscriptions } from './subscribe';
 
 export function getOrCreateCachedStartUpdate<
   TReadFromStore extends UnknownTReadFromStore,
 >(
   environment: IsographEnvironment,
   fragmentReference: FragmentReference<TReadFromStore, unknown>,
-  eagerResolverName: string,
   networkRequestOptions: NetworkRequestReaderOptions,
 ): ExtractStartUpdate<TReadFromStore> {
   return (environment.eagerReaderCache[
-    stableIdForFragmentReference(fragmentReference, eagerResolverName)
+    stableIdForFragmentReference(fragmentReference)
   ] ??= createStartUpdate(
     environment,
     fragmentReference,
@@ -56,28 +62,38 @@ export function createStartUpdate<TReadFromStore extends UnknownTReadFromStore>(
   return (updater) => {
     let mutableUpdatedIds: EncounteredIds = new Map();
 
-    let updatableData = createUpdatableProxy(
-      environment,
-      fragmentReference,
-      networkRequestOptions,
-      mutableUpdatedIds,
+    const startUpdate: StartUpdateStoreLayer['startUpdate'] = (storeLayer) => {
+      mutableUpdatedIds.clear();
+      let updatableData = createUpdatableProxy(
+        environment,
+        storeLayer,
+        fragmentReference,
+        networkRequestOptions,
+        mutableUpdatedIds,
+      );
+
+      try {
+        updater({ updatableData });
+      } catch (e) {
+        logMessage(environment, () => ({
+          kind: 'StartUpdateError',
+          error: e,
+        }));
+        throw e;
+      }
+    };
+
+    environment.store = addStartUpdateStoreLayer(
+      environment.store,
+      startUpdate,
     );
 
-    try {
-      updater({ updatableData });
-    } catch (e) {
-      logMessage(environment, () => ({
-        kind: 'StartUpdateError',
-        error: e,
-      }));
-      throw e;
-    } finally {
-      logMessage(environment, () => ({
-        kind: 'StartUpdateComplete',
-        updatedIds: mutableUpdatedIds,
-      }));
-      callSubscriptions(environment, mutableUpdatedIds);
-    }
+    logMessage(environment, () => ({
+      kind: 'StartUpdateComplete',
+      updatedIds: mutableUpdatedIds,
+    }));
+
+    callSubscriptions(environment, mutableUpdatedIds);
   };
 }
 
@@ -85,6 +101,7 @@ export function createUpdatableProxy<
   TReadFromStore extends UnknownTReadFromStore,
 >(
   environment: IsographEnvironment,
+  storeLayer: StoreLayer,
   fragmentReference: FragmentReference<TReadFromStore, unknown>,
   networkRequestOptions: NetworkRequestReaderOptions,
   mutableUpdatedIds: EncounteredIds,
@@ -95,6 +112,7 @@ export function createUpdatableProxy<
 
   return readUpdatableData(
     environment,
+    storeLayer,
     readerWithRefetchQueries.readerArtifact.readerAst,
     fragmentReference.root,
     fragmentReference.variables ?? {},
@@ -143,7 +161,7 @@ function defineCachedProperty<T>(
       }
       return value.value;
     },
-    ...(set && {
+    ...(set != null && {
       set: (newValue) => {
         set(newValue);
         mutableState.lastInvalidated++;
@@ -154,6 +172,7 @@ function defineCachedProperty<T>(
 
 function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
   environment: IsographEnvironment,
+  storeLayer: StoreLayer,
   ast: ReaderAst<TReadFromStore>,
   root: StoreLink,
   variables: ExtractParameters<TReadFromStore>,
@@ -163,14 +182,7 @@ function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
   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,
-    };
-  }
-
+  const storeRecord = getMutableStoreRecordProxy(storeLayer, root);
   let target: { [index: string]: any } = {};
 
   for (const field of ast) {
@@ -196,6 +208,7 @@ function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
           },
           field.isUpdatable
             ? (newValue) => {
+                const storeRecord = getOrInsertRecord(storeLayer.data, root);
                 storeRecord[storeRecordName] = newValue;
                 const updatedIds = insertEmptySetIfMissing(
                   mutableUpdatedIds,
@@ -226,6 +239,7 @@ function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
               (ast, root) =>
                 readUpdatableData(
                   environment,
+                  storeLayer,
                   ast,
                   root,
                   variables,
@@ -243,6 +257,7 @@ function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
           },
           'isUpdatable' in field && field.isUpdatable
             ? (newValue) => {
+                const storeRecord = getOrInsertRecord(storeLayer.data, root);
                 if (Array.isArray(newValue)) {
                   storeRecord[storeRecordName] = newValue.map((node) =>
                     assertLink(node?.__link),
@@ -320,10 +335,6 @@ function readUpdatableData<TReadFromStore extends UnknownTReadFromStore>(
         target[field.alias] = root;
         break;
       }
-      default: {
-        field satisfies never;
-        throw new Error('Unexpected case.');
-      }
     }
   }
 

package/src/core/subscribe.ts

@@ -0,0 +1,189 @@
+import { mergeObjectsUsingReaderAst } from './areEqualWithDeepComparison';
+import type { EncounteredIds } from './cache';
+import type {
+  FragmentReference,
+  UnknownTReadFromStore,
+} from './FragmentReference';
+import type {
+  FragmentSubscription,
+  IsographEnvironment,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
+import { type WithEncounteredRecords, readButDoNotEvaluate } from './read';
+import type { ReaderAst } from './reader';
+
+export function subscribe<TReadFromStore extends UnknownTReadFromStore>(
+  environment: IsographEnvironment,
+  encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
+  fragmentReference: FragmentReference<TReadFromStore, any>,
+  callback: (
+    newEncounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
+  ) => void,
+  readerAst: ReaderAst<TReadFromStore>,
+): () => void {
+  const fragmentSubscription: FragmentSubscription<TReadFromStore> = {
+    kind: 'FragmentSubscription',
+    callback,
+    encounteredDataAndRecords,
+    fragmentReference,
+    readerAst,
+  };
+
+  // subscribe is called in an effect. (We should actually subscribe during the
+  // initial render.) Because it's called in an effect, we might have missed some
+  // changes since the initial render! So, at this point, we re-read and call the
+  // subscription (i.e. re-render) if the fragment data has changed.
+  callSubscriptionIfDataChanged(environment, fragmentSubscription);
+
+  environment.subscriptions.add(fragmentSubscription);
+  return () => environment.subscriptions.delete(fragmentSubscription);
+}
+
+// Calls to readButDoNotEvaluate can suspend (i.e. throw a promise).
+// Maybe in the future, they will be able to throw errors.
+//
+// That's probably okay to ignore. We don't, however, want to prevent
+// updating other subscriptions if one subscription had missing data.
+function logAnyError(
+  environment: IsographEnvironment,
+  context: any,
+  f: () => void,
+) {
+  try {
+    f();
+  } catch (e) {
+    logMessage(environment, () => ({
+      kind: 'ErrorEncounteredInWithErrorHandling',
+      error: e,
+      context,
+    }));
+  }
+}
+
+export function callSubscriptions(
+  environment: IsographEnvironment,
+  recordsEncounteredWhenNormalizing: EncounteredIds,
+) {
+  environment.subscriptions.forEach((subscription) =>
+    logAnyError(environment, { situation: 'calling subscriptions' }, () => {
+      switch (subscription.kind) {
+        case 'FragmentSubscription': {
+          // TODO if there are multiple components subscribed to the same
+          // fragment, we will call readButNotEvaluate multiple times. We
+          // should fix that.
+          if (
+            hasOverlappingIds(
+              recordsEncounteredWhenNormalizing,
+              subscription.encounteredDataAndRecords.encounteredRecords,
+            )
+          ) {
+            callSubscriptionIfDataChanged(environment, subscription);
+          }
+          return;
+        }
+        case 'AnyRecords': {
+          logAnyError(
+            environment,
+            { situation: 'calling AnyRecords callback' },
+            () => subscription.callback(),
+          );
+          return;
+        }
+        case 'AnyChangesToRecord': {
+          if (
+            recordsEncounteredWhenNormalizing
+              .get(subscription.recordLink.__typename)
+              ?.has(subscription.recordLink.__link) != null
+          ) {
+            logAnyError(
+              environment,
+              { situation: 'calling AnyChangesToRecord callback' },
+              () => subscription.callback(),
+            );
+          }
+          return;
+        }
+      }
+    }),
+  );
+}
+
+function callSubscriptionIfDataChanged<
+  TReadFromStore extends UnknownTReadFromStore,
+>(
+  environment: IsographEnvironment,
+  subscription: FragmentSubscription<TReadFromStore>,
+) {
+  const newEncounteredDataAndRecords = readButDoNotEvaluate(
+    environment,
+    subscription.fragmentReference,
+    // Is this wrong?
+    // Reasons to think no:
+    // - we are only updating the read-out value, and the network
+    //   options only affect whether we throw.
+    // - the component will re-render, and re-throw on its own, anyway.
+    //
+    // Reasons to think not:
+    // - it seems more efficient to suspend here and not update state,
+    //   if we expect that the component will just throw anyway
+    // - consistency
+    // - it's also weird, this is called from makeNetworkRequest, where
+    //   we don't currently pass network request options
+    {
+      suspendIfInFlight: false,
+      throwOnNetworkError: false,
+    },
+  );
+
+  const mergedItem = mergeObjectsUsingReaderAst(
+    subscription.readerAst,
+    subscription.encounteredDataAndRecords.item,
+    newEncounteredDataAndRecords.item,
+  );
+
+  logMessage(environment, () => ({
+    kind: 'DeepEqualityCheck',
+    fragmentReference: subscription.fragmentReference,
+    old: subscription.encounteredDataAndRecords.item,
+    new: newEncounteredDataAndRecords.item,
+    deeplyEqual: mergedItem === subscription.encounteredDataAndRecords.item,
+  }));
+
+  if (mergedItem !== subscription.encounteredDataAndRecords.item) {
+    logAnyError(
+      environment,
+      { situation: 'calling FragmentSubscription callback' },
+      () => {
+        subscription.callback(newEncounteredDataAndRecords);
+      },
+    );
+    subscription.encounteredDataAndRecords = newEncounteredDataAndRecords;
+  }
+}
+
+function hasOverlappingIds(
+  ids1: EncounteredIds,
+  ids2: EncounteredIds,
+): boolean {
+  for (const [typeName, set1] of ids1.entries()) {
+    const set2 = ids2.get(typeName);
+    if (set2 === undefined) {
+      continue;
+    }
+
+    if (isNotDisjointFrom(set1, set2)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// TODO use a polyfill library
+function isNotDisjointFrom<T>(set1: Set<T>, set2: Set<T>): boolean {
+  for (const id of set1) {
+    if (set2.has(id)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/core/util.ts

@@ -31,3 +31,29 @@ export type ArgumentValue =
       readonly kind: 'Object';
       readonly value: Arguments;
     };
+
+export function isArray(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}
+
+/**
+ * Creates a copy of the provided value, ensuring any nested objects have their
+ * keys sorted such that equivalent values would have identical JSON.stringify
+ * results.
+ */
+export function stableCopy<T>(value: T): T {
+  if (value == null || typeof value !== 'object') {
+    return value;
+  }
+  if (isArray(value)) {
+    // @ts-ignore
+    return value.map(stableCopy);
+  }
+  const keys = Object.keys(value).sort();
+  const stable: { [index: string]: any } = {};
+  for (let i = 0; i < keys.length; i++) {
+    // @ts-ignore
+    stable[keys[i]] = stableCopy(value[keys[i]]);
+  }
+  return stable as any;
+}

package/src/core/writeData.ts

@@ -0,0 +1,79 @@
+import type { ItemCleanupPair } from '@isograph/isograph-disposable-types/dist';
+import { callSubscriptions } from './subscribe';
+import {
+  type NetworkResponseObject,
+  type EncounteredIds,
+  normalizeData,
+} from './cache';
+import type { IsographEntrypoint, NormalizationAst } from './entrypoint';
+import type {
+  UnknownTReadFromStore,
+  ExtractParameters,
+  FragmentReference,
+} from './FragmentReference';
+import {
+  type IsographEnvironment,
+  ROOT_ID,
+  getOrLoadReaderWithRefetchQueries,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
+import { retainQueryWithoutMakingNetworkRequest } from './makeNetworkRequest';
+import { addNetworkResponseStoreLayer } from './optimisticProxy';
+
+export function writeData<
+  TReadFromStore extends UnknownTReadFromStore,
+  TRawResponseType extends NetworkResponseObject,
+  TClientFieldValue,
+>(
+  environment: IsographEnvironment,
+  entrypoint: IsographEntrypoint<
+    TReadFromStore,
+    TClientFieldValue,
+    NormalizationAst,
+    TRawResponseType
+  >,
+  data: TRawResponseType,
+  variables: ExtractParameters<TReadFromStore>,
+): ItemCleanupPair<FragmentReference<TReadFromStore, TClientFieldValue>> {
+  const encounteredIds: EncounteredIds = new Map();
+  environment.store = addNetworkResponseStoreLayer(environment.store);
+  normalizeData(
+    environment,
+    environment.store,
+    entrypoint.networkRequestInfo.normalizationAst.selections,
+    data,
+    variables,
+    { __link: ROOT_ID, __typename: entrypoint.concreteType },
+    encounteredIds,
+  );
+  logMessage(environment, () => ({
+    kind: 'AfterNormalization',
+    store: environment.store,
+    encounteredIds,
+  }));
+
+  callSubscriptions(environment, encounteredIds);
+
+  const { fieldName, readerArtifactKind, readerWithRefetchQueries } =
+    getOrLoadReaderWithRefetchQueries(
+      environment,
+      entrypoint.readerWithRefetchQueries,
+    );
+  const [networkRequest, disposeNetworkRequest] =
+    retainQueryWithoutMakingNetworkRequest(environment, entrypoint, variables);
+
+  return [
+    {
+      kind: 'FragmentReference',
+      readerWithRefetchQueries,
+      fieldName,
+      readerArtifactKind,
+      root: { __link: ROOT_ID, __typename: entrypoint.concreteType },
+      variables,
+      networkRequest,
+    },
+    () => {
+      disposeNetworkRequest();
+    },
+  ];
+}

package/src/index.ts

@@ -18,14 +18,14 @@ export {
   NOT_SET,
 } from './core/PromiseWrapper';
 export {
-  callSubscriptions,
-  subscribe,
   normalizeData,
   type NetworkResponseObject,
   type NetworkResponseValue,
   type NetworkResponseScalarValue,
   type EncounteredIds,
 } from './core/cache';
+export { callSubscriptions, subscribe } from './core/subscribe';
+export { writeData } from './core/writeData';
 export { makeNetworkRequest } from './core/makeNetworkRequest';
 export {
   ROOT_ID,
@@ -33,13 +33,12 @@ export {
   type DataTypeValue,
   type IsographEnvironment,
   type IsographNetworkFunction,
-  type IsographStore,
+  type BaseStoreLayerData as IsographStore,
   type MissingFieldHandler,
   type StoreLink,
   type Link,
   type StoreRecord,
   type CacheMap,
-  createIsographEnvironment,
   createIsographStore,
   type FieldCache,
   type Subscriptions,
@@ -85,7 +84,9 @@ export {
   type RefetchQueryNormalizationArtifactWrapper,
   type ExtractProps,
   type ExtractReadFromStore,
+  type ExtractClientFieldValue,
   type ExtractResolverResult,
+  type FragmentReferenceOfEntrypoint,
   type NetworkRequestInfo,
   type NormalizationInlineFragment,
   type ReaderWithRefetchQueries,
@@ -156,6 +157,7 @@ export {
 export { useLazyReference } from './react/useLazyReference';
 export { useRerenderOnChange } from './react/useRerenderOnChange';
 export { RenderAfterCommit__DO_NOT_USE } from './react/RenderAfterCommit__DO_NOT_USE';
+export { createIsographEnvironment } from './react/createIsographEnvironment';
 
 export { useClientSideDefer } from './loadable-hooks/useClientSideDefer';
 export {

package/src/loadable-hooks/useClientSideDefer.ts

@@ -1,40 +1,18 @@
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
 import { getOrCreateItemInSuspenseCache } from '../core/cache';
-import { FetchOptions } from '../core/check';
-import {
+import type { FetchOptions } from '../core/check';
+import type {
   ExtractParameters,
   FragmentReference,
-  type UnknownTReadFromStore,
 } from '../core/FragmentReference';
-import { LoadableField } from '../core/reader';
+import { type UnknownTReadFromStore } from '../core/FragmentReference';
+import type { LoadableField } from '../core/reader';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 
-export function useClientSideDefer<
+type ArgsWithoutProvidedArgs<
   TReadFromStore extends UnknownTReadFromStore,
-  TResult,
->(
-  loadableField: LoadableField<
-    TReadFromStore,
-    TResult,
-    ExtractParameters<TReadFromStore>
-  >,
-  args?: Record<PropertyKey, never>,
-  fetchOptions?: FetchOptions<TResult>,
-): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
-
-export function useClientSideDefer<
-  TReadFromStore extends UnknownTReadFromStore,
-  TResult,
   TProvidedArgs extends object,
->(
-  loadableField: LoadableField<
-    TReadFromStore,
-    TResult,
-    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
-  >,
-  args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
-  fetchOptions?: FetchOptions<TResult>,
-): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
+> = Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>;
 
 export function useClientSideDefer<
   TReadFromStore extends UnknownTReadFromStore,
@@ -46,9 +24,21 @@ export function useClientSideDefer<
     TResult,
     Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
   >,
-  args?: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
-  fetchOptions?: FetchOptions<TResult>,
+  ...maybeRequiredArgs: {} extends ArgsWithoutProvidedArgs<
+    TReadFromStore,
+    TProvidedArgs
+  >
+    ? [
+        args?: ArgsWithoutProvidedArgs<TReadFromStore, TProvidedArgs>,
+        fetchOptions?: FetchOptions<TResult, never>,
+      ]
+    : [
+        args: ArgsWithoutProvidedArgs<TReadFromStore, TProvidedArgs>,
+        fetchOptions?: FetchOptions<TResult, never>,
+      ]
 ): { fragmentReference: FragmentReference<TReadFromStore, TResult> } {
+  const [args, fetchOptions] = maybeRequiredArgs;
+
   const [id, loader] = loadableField(args, fetchOptions ?? {});
   const environment = useIsographEnvironment();
   const cache = getOrCreateItemInSuspenseCache(environment, id, loader);
@@ -57,3 +47,63 @@ export function useClientSideDefer<
 
   return { fragmentReference };
 }
+
+// @ts-ignore
+function tsTests() {
+  let neverArgs!: LoadableField<
+    {
+      parameters: Record<string, never>;
+      data: {};
+    },
+    unknown
+  >;
+
+  let optionalArgs!: LoadableField<
+    {
+      parameters: {
+        foo?: string;
+      };
+      data: {};
+    },
+    unknown
+  >;
+
+  let requiredArgs!: LoadableField<
+    {
+      parameters: {
+        foo: string;
+      };
+      data: {};
+    },
+    unknown
+  >;
+
+  useClientSideDefer(neverArgs);
+  useClientSideDefer(neverArgs, {});
+  useClientSideDefer(neverArgs, {
+    // @ts-expect-error
+    foo: 'bar',
+  });
+
+  useClientSideDefer(optionalArgs);
+  useClientSideDefer(optionalArgs, {});
+  useClientSideDefer(optionalArgs, {
+    foo: 'bar',
+  });
+  useClientSideDefer(optionalArgs, {
+    // @ts-expect-error
+    foo: 12,
+  });
+
+  // @ts-expect-error
+  useClientSideDefer(requiredArgs);
+  // @ts-expect-error
+  useClientSideDefer(requiredArgs, {});
+  useClientSideDefer(requiredArgs, {
+    foo: 'bar',
+  });
+  useClientSideDefer(requiredArgs, {
+    // @ts-expect-error
+    foo: 12,
+  });
+}