@isograph/react 0.0.0-main-4adb5045 → 0.0.0-main-82400fb8

package/src/core/read.ts

@@ -1,4 +1,4 @@
-import { CleanupFn, type ItemCleanupPair } from '@isograph/disposable-types';
+import type { CleanupFn, ItemCleanupPair } from '@isograph/disposable-types';
 import {
   getParentRecordKey,
   insertEmptySetIfMissing,
@@ -7,16 +7,16 @@ import {
 } from './cache';
 import { FetchOptions } from './check';
 import { getOrCreateCachedComponent } from './componentCache';
-import {
+import type {
   IsographEntrypoint,
+  ReaderWithRefetchQueries,
   RefetchQueryNormalizationArtifactWrapper,
-  type ReaderWithRefetchQueries,
 } from './entrypoint';
-import {
+import type {
   ExtractData,
   FragmentReference,
+  UnknownTReadFromStore,
   Variables,
-  type UnknownTReadFromStore,
 } from './FragmentReference';
 import {
   assertLink,
@@ -38,17 +38,17 @@ import {
   wrapPromise,
   wrapResolvedValue,
 } from './PromiseWrapper';
-import {
+import type {
+  LoadablySelectedField,
   ReaderAst,
-  type LoadablySelectedField,
-  type ReaderClientPointer,
-  type ReaderImperativelyLoadedField,
-  type ReaderLinkedField,
-  type ReaderNonLoadableResolverField,
-  type ReaderScalarField,
+  ReaderClientPointer,
+  ReaderImperativelyLoadedField,
+  ReaderLinkedField,
+  ReaderNonLoadableResolverField,
+  ReaderScalarField,
 } from './reader';
 import { getOrCreateCachedStartUpdate } from './startUpdate';
-import { Arguments } from './util';
+import type { Arguments } from './util';
 
 export type WithEncounteredRecords<T> = {
   readonly encounteredRecords: EncounteredIds;

package/src/core/startUpdate.ts

@@ -1,5 +1,4 @@
 import {
-  callSubscriptions,
   getParentRecordKey,
   insertEmptySetIfMissing,
   type EncounteredIds,
@@ -37,6 +36,7 @@ import {
   type ReadDataResultSuccess,
 } from './read';
 import type { ReaderAst } from './reader';
+import { callSubscriptions } from './subscribe';
 
 export function getOrCreateCachedStartUpdate<
   TReadFromStore extends UnknownTReadFromStore,

package/src/core/subscribe.ts

@@ -0,0 +1,195 @@
+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;
+        }
+        default: {
+          // Ensure we have covered all variants
+          const _: never = subscription;
+          _;
+          throw new Error('Unexpected case');
+        }
+      }
+    }),
+  );
+}
+
+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,15 +18,14 @@ export {
   NOT_SET,
 } from './core/PromiseWrapper';
 export {
-  callSubscriptions,
-  subscribe,
   normalizeData,
-  writeData,
   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,
@@ -40,7 +39,6 @@ export {
   type Link,
   type StoreRecord,
   type CacheMap,
-  createIsographEnvironment,
   createIsographStore,
   type FieldCache,
   type Subscriptions,
@@ -159,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/useConnectionSpecPagination.ts

@@ -9,21 +9,21 @@ import {
 } from '@isograph/reference-counted-pointer';
 import { useState } from 'react';
 import { subscribeToAnyChange } from '../core/cache';
-import { FetchOptions } from '../core/check';
-import {
+import type { FetchOptions } from '../core/check';
+import type {
   FragmentReference,
-  type UnknownTReadFromStore,
+  UnknownTReadFromStore,
 } from '../core/FragmentReference';
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
 import {
   readButDoNotEvaluate,
   type WithEncounteredRecords,
 } from '../core/read';
-import { LoadableField, type ReaderAst } from '../core/reader';
+import type { LoadableField, ReaderAst } from '../core/reader';
 import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
+import { maybeUnwrapNetworkRequest } from '../react/maybeUnwrapNetworkRequest';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
-import { maybeUnwrapNetworkRequest } from '../react/useResult';
 
 export type UsePaginationReturnValue<
   TReadFromStore extends UnknownTReadFromStore,

package/src/loadable-hooks/useSkipLimitPagination.ts

@@ -9,21 +9,21 @@ import {
 } from '@isograph/reference-counted-pointer';
 import { useState } from 'react';
 import { subscribeToAnyChange } from '../core/cache';
-import { FetchOptions } from '../core/check';
-import {
+import type { FetchOptions } from '../core/check';
+import type {
   FragmentReference,
-  type UnknownTReadFromStore,
+  UnknownTReadFromStore,
 } from '../core/FragmentReference';
 import { getPromiseState, readPromise } from '../core/PromiseWrapper';
 import {
   readButDoNotEvaluate,
   type WithEncounteredRecords,
 } from '../core/read';
-import { LoadableField, type ReaderAst } from '../core/reader';
+import type { LoadableField, ReaderAst } from '../core/reader';
 import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
 import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
+import { maybeUnwrapNetworkRequest } from '../react/maybeUnwrapNetworkRequest';
 import { useSubscribeToMultiple } from '../react/useReadAndSubscribe';
-import { maybeUnwrapNetworkRequest } from '../react/useResult';
 
 export type UseSkipLimitReturnValue<
   TReadFromStore extends UnknownTReadFromStore,

package/src/react/createIsographEnvironment.ts

@@ -0,0 +1,23 @@
+import {
+  createIsographEnvironmentCore,
+  type BaseStoreLayerData,
+  type IsographNetworkFunction,
+  type MissingFieldHandler,
+} from '../core/IsographEnvironment';
+import type { LogFunction } from '../core/logging';
+import { componentFunction } from './useReadAndSubscribe';
+
+export function createIsographEnvironment(
+  baseStoreLayerData: BaseStoreLayerData,
+  networkFunction: IsographNetworkFunction,
+  missingFieldHandler?: MissingFieldHandler | null,
+  logFunction?: LogFunction | null,
+) {
+  return createIsographEnvironmentCore(
+    baseStoreLayerData,
+    networkFunction,
+    componentFunction,
+    missingFieldHandler,
+    logFunction,
+  );
+}

package/src/react/maybeUnwrapNetworkRequest.ts

@@ -0,0 +1,17 @@
+import { type PromiseWrapper, getPromiseState } from '../core/PromiseWrapper';
+import type { NetworkRequestReaderOptions } from '../core/read';
+
+export function maybeUnwrapNetworkRequest(
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+) {
+  const state = getPromiseState(networkRequest);
+  if (state.kind === 'Err' && networkRequestOptions.throwOnNetworkError) {
+    throw state.error;
+  } else if (
+    state.kind === 'Pending' &&
+    networkRequestOptions.suspendIfInFlight
+  ) {
+    throw state.promise;
+  }
+}

package/src/react/useLazyReference.ts

@@ -1,8 +1,5 @@
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
-import {
-  getOrCreateCacheForArtifact,
-  type NetworkResponseObject,
-} from '../core/cache';
+import { type NetworkResponseObject } from '../core/cache';
 import { FetchOptions, type RequiredFetchOptions } from '../core/check';
 import {
   IsographEntrypoint,
@@ -16,6 +13,7 @@ import {
 } from '../core/FragmentReference';
 import { logMessage } from '../core/logging';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { getOrCreateCacheForArtifact } from '../core/getOrCreateCacheForArtifact';
 
 export function useLazyReference<
   TReadFromStore extends UnknownTReadFromStore,

package/src/react/useReadAndSubscribe.ts

@@ -1,18 +1,22 @@
 import { useEffect, useState } from 'react';
-import { subscribe } from '../core/cache';
 import {
-  ExtractData,
-  FragmentReference,
+  type ExtractData,
+  type FragmentReference,
   stableIdForFragmentReference,
   type UnknownTReadFromStore,
 } from '../core/FragmentReference';
+import type { IsographComponentFunction } from '../core/IsographEnvironment';
+import { logMessage } from '../core/logging';
+import { readPromise } from '../core/PromiseWrapper';
 import {
-  NetworkRequestReaderOptions,
+  type NetworkRequestReaderOptions,
   readButDoNotEvaluate,
-  WithEncounteredRecords,
+  type WithEncounteredRecords,
 } from '../core/read';
 import type { ReaderAst } from '../core/reader';
+import { subscribe } from '../core/subscribe';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { maybeUnwrapNetworkRequest } from './maybeUnwrapNetworkRequest';
 import { useRerenderOnChange } from './useRerenderOnChange';
 
 /**
@@ -80,3 +84,47 @@ export function useSubscribeToMultiple<
     ],
   );
 }
+
+export const componentFunction: IsographComponentFunction = (
+  environment,
+  fragmentReference,
+  networkRequestOptions,
+  startUpdate,
+) => {
+  function Component(additionalRuntimeProps: { [key: string]: any }) {
+    maybeUnwrapNetworkRequest(
+      fragmentReference.networkRequest,
+      networkRequestOptions,
+    );
+    const readerWithRefetchQueries = readPromise(
+      fragmentReference.readerWithRefetchQueries,
+    );
+
+    const data = useReadAndSubscribe(
+      fragmentReference,
+      networkRequestOptions,
+      readerWithRefetchQueries.readerArtifact.readerAst,
+    );
+
+    logMessage(environment, () => ({
+      kind: 'ComponentRerendered',
+      componentName: fragmentReference.fieldName,
+      rootLink: fragmentReference.root,
+    }));
+
+    return readerWithRefetchQueries.readerArtifact.resolver(
+      // @ts-expect-error
+      {
+        data,
+        parameters: fragmentReference.variables,
+        startUpdate: readerWithRefetchQueries.readerArtifact.hasUpdatable
+          ? startUpdate
+          : undefined,
+      },
+      additionalRuntimeProps,
+    );
+  }
+  const idString = `(type: ${fragmentReference.root.__typename}, id: ${fragmentReference.root.__link})`;
+  Component.displayName = `${fragmentReference.fieldName} ${idString} @component`;
+  return Component;
+};

package/src/react/useRerenderOnChange.ts

@@ -1,8 +1,8 @@
 import { useEffect } from 'react';
-import { subscribe } from '../core/cache';
-import { FragmentReference } from '../core/FragmentReference';
-import { WithEncounteredRecords } from '../core/read';
+import type { FragmentReference } from '../core/FragmentReference';
+import type { WithEncounteredRecords } from '../core/read';
 import type { ReaderAst } from '../core/reader';
+import { subscribe } from '../core/subscribe';
 import { useIsographEnvironment } from './IsographEnvironmentProvider';
 
 // TODO add unit tests for this. Add integration tests that test

package/src/react/useResult.ts

@@ -1,19 +1,16 @@
 import { getOrCreateCachedComponent } from '../core/componentCache';
-import {
+import type {
   FragmentReference,
-  type UnknownTReadFromStore,
+  UnknownTReadFromStore,
 } from '../core/FragmentReference';
+import { readPromise } from '../core/PromiseWrapper';
 import {
-  getPromiseState,
-  PromiseWrapper,
-  readPromise,
-} from '../core/PromiseWrapper';
-import {
+  type NetworkRequestReaderOptions,
   getNetworkRequestOptionsWithDefaults,
-  NetworkRequestReaderOptions,
 } from '../core/read';
 import { getOrCreateCachedStartUpdate } from '../core/startUpdate';
-import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { maybeUnwrapNetworkRequest } from './maybeUnwrapNetworkRequest';
 import { useReadAndSubscribe } from './useReadAndSubscribe';
 
 export function useResult<
@@ -68,18 +65,3 @@ export function useResult<
     }
   }
 }
-
-export function maybeUnwrapNetworkRequest(
-  networkRequest: PromiseWrapper<void, any>,
-  networkRequestOptions: NetworkRequestReaderOptions,
-) {
-  const state = getPromiseState(networkRequest);
-  if (state.kind === 'Err' && networkRequestOptions.throwOnNetworkError) {
-    throw state.error;
-  } else if (
-    state.kind === 'Pending' &&
-    networkRequestOptions.suspendIfInFlight
-  ) {
-    throw state.promise;
-  }
-}

package/src/tests/garbageCollection.test.ts

@@ -1,18 +1,15 @@
+import { iso } from '@iso';
 import { describe, expect, test } from 'vitest';
 import {
   garbageCollectEnvironment,
   retainQuery,
   type RetainedQuery,
 } from '../core/garbageCollection';
-import {
-  createIsographEnvironment,
-  ROOT_ID,
-  type BaseStoreLayerData,
-} from '../core/IsographEnvironment';
+import { ROOT_ID, type BaseStoreLayerData } from '../core/IsographEnvironment';
 import { wrapResolvedValue } from '../core/PromiseWrapper';
-import { iso } from './__isograph/iso';
 import { meNameSuccessorRetainedQuery } from './meNameSuccessor';
 import { nodeFieldRetainedQuery } from './nodeQuery';
+import { createIsographEnvironment } from '../react/createIsographEnvironment';
 
 const getDefaultStore = (): BaseStoreLayerData => ({
   Query: {