@isograph/react 0.1.1 → 0.3.0

package/src/core/check.ts

@@ -0,0 +1,207 @@
+import { getParentRecordKey } from './cache';
+import { NormalizationAst } from './entrypoint';
+import { Variables } from './FragmentReference';
+import {
+  getLink,
+  IsographEnvironment,
+  Link,
+  StoreRecord,
+} from './IsographEnvironment';
+import { logMessage } from './logging';
+
+export type ShouldFetch = 'Yes' | 'No' | 'IfNecessary';
+
+export const DEFAULT_SHOULD_FETCH_VALUE: ShouldFetch = 'IfNecessary';
+
+export type FetchOptions = {
+  shouldFetch?: ShouldFetch;
+  onComplete?: () => void;
+  onError?: () => void;
+};
+
+export type CheckResult =
+  | {
+      kind: 'EnoughData';
+    }
+  | {
+      kind: 'MissingData';
+      record: Link;
+    };
+
+export function check(
+  environment: IsographEnvironment,
+  normalizationAst: NormalizationAst,
+  variables: Variables,
+  root: Link,
+): CheckResult {
+  const recordsById = (environment.store[root.__typename] ??= {});
+  const newStoreRecord = (recordsById[root.__link] ??= {});
+
+  const checkResult = checkFromRecord(
+    environment,
+    normalizationAst,
+    variables,
+    newStoreRecord,
+    root,
+  );
+  logMessage(environment, {
+    kind: 'EnvironmentCheck',
+    result: checkResult,
+  });
+  return checkResult;
+}
+
+function checkFromRecord(
+  environment: IsographEnvironment,
+  normalizationAst: NormalizationAst,
+  variables: Variables,
+  record: StoreRecord,
+  recordLink: Link,
+): CheckResult {
+  normalizationAstLoop: for (const normalizationAstNode of normalizationAst) {
+    switch (normalizationAstNode.kind) {
+      case 'Scalar': {
+        const parentRecordKey = getParentRecordKey(
+          normalizationAstNode,
+          variables,
+        );
+        const scalarValue = record[parentRecordKey];
+
+        // null means the value is known to be missing, so it must
+        // be exactly undefined
+        if (scalarValue === undefined) {
+          return {
+            kind: 'MissingData',
+            record: recordLink,
+          };
+        }
+        continue normalizationAstLoop;
+      }
+      case 'Linked': {
+        const parentRecordKey = getParentRecordKey(
+          normalizationAstNode,
+          variables,
+        );
+
+        const linkedValue = record[parentRecordKey];
+
+        if (linkedValue === undefined) {
+          return {
+            kind: 'MissingData',
+            record: recordLink,
+          };
+        } else if (linkedValue === null) {
+          continue;
+        } else if (Array.isArray(linkedValue)) {
+          arrayItemsLoop: for (const item of linkedValue) {
+            const link = getLink(item);
+            if (link === null) {
+              throw new Error(
+                'Unexpected non-link in the Isograph store. ' +
+                  'This is indicative of a bug in Isograph.',
+              );
+            }
+
+            const linkedRecord =
+              environment.store[link.__typename]?.[link.__link];
+
+            if (linkedRecord === undefined) {
+              return {
+                kind: 'MissingData',
+                record: link,
+              };
+            } else if (linkedRecord === null) {
+              continue arrayItemsLoop;
+            } else {
+              // TODO in __DEV__ assert linkedRecord is an object
+              const result = checkFromRecord(
+                environment,
+                normalizationAstNode.selections,
+                variables,
+                linkedRecord,
+                link,
+              );
+
+              if (result.kind === 'MissingData') {
+                return result;
+              }
+            }
+          }
+        } else {
+          const link = getLink(linkedValue);
+          if (link === null) {
+            throw new Error(
+              'Unexpected non-link in the Isograph store. ' +
+                'This is indicative of a bug in Isograph.',
+            );
+          }
+
+          const linkedRecord =
+            environment.store[link.__typename]?.[link.__link];
+
+          if (linkedRecord === undefined) {
+            return {
+              kind: 'MissingData',
+              record: link,
+            };
+          } else if (linkedRecord === null) {
+            continue normalizationAstLoop;
+          } else {
+            // TODO in __DEV__ assert linkedRecord is an object
+            const result = checkFromRecord(
+              environment,
+              normalizationAstNode.selections,
+              variables,
+              linkedRecord,
+              link,
+            );
+
+            if (result.kind === 'MissingData') {
+              return result;
+            }
+          }
+        }
+
+        continue normalizationAstLoop;
+      }
+      case 'InlineFragment': {
+        const existingRecordTypename = record['__typename'];
+
+        if (
+          existingRecordTypename == null ||
+          existingRecordTypename !== normalizationAstNode.type
+        ) {
+          return {
+            kind: 'MissingData',
+            record: recordLink,
+          };
+        }
+
+        const result = checkFromRecord(
+          environment,
+          normalizationAstNode.selections,
+          variables,
+          record,
+          recordLink,
+        );
+
+        if (result.kind === 'MissingData') {
+          return result;
+        }
+
+        continue normalizationAstLoop;
+      }
+      default: {
+        let _: never = normalizationAstNode;
+        _;
+        throw new Error(
+          'Unexpected case. This is indicative of a bug in Isograph.',
+        );
+      }
+    }
+  }
+
+  return {
+    kind: 'EnoughData',
+  };
+}

package/src/core/componentCache.ts

@@ -0,0 +1,62 @@
+import { stableCopy } from './cache';
+import { IsographEnvironment } from './IsographEnvironment';
+import { FragmentReference } from './FragmentReference';
+import { useReadAndSubscribe } from '../react/useReadAndSubscribe';
+import { NetworkRequestReaderOptions } from './read';
+import { readPromise } from './PromiseWrapper';
+import { logMessage } from './logging';
+
+export function getOrCreateCachedComponent(
+  environment: IsographEnvironment,
+  componentName: string,
+  fragmentReference: FragmentReference<any, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+): React.FC<any> {
+  // cachedComponentsById is a three layer cache: id, then component name, then
+  // stringified args. These three, together, uniquely identify a read at a given
+  // time.
+  const cachedComponentsById = environment.componentCache;
+
+  const recordLink = fragmentReference.root.__link;
+
+  const componentsByName = (cachedComponentsById[recordLink] ??= {});
+
+  componentsByName[componentName] = componentsByName[componentName] ?? {};
+  const byArgs = componentsByName[componentName];
+
+  const stringifiedArgs = JSON.stringify(
+    stableCopy(fragmentReference.variables),
+  );
+  byArgs[stringifiedArgs] =
+    byArgs[stringifiedArgs] ??
+    (() => {
+      function Component(additionalRuntimeProps: { [key: string]: any }) {
+        const readerWithRefetchQueries = readPromise(
+          fragmentReference.readerWithRefetchQueries,
+        );
+
+        const data = useReadAndSubscribe(
+          fragmentReference,
+          networkRequestOptions,
+          readerWithRefetchQueries.readerArtifact.readerAst,
+        );
+
+        logMessage(environment, {
+          kind: 'ComponentRerendered',
+          componentName,
+          rootLink: fragmentReference.root,
+        });
+
+        return readerWithRefetchQueries.readerArtifact.resolver(
+          {
+            data,
+            parameters: fragmentReference.variables,
+          },
+          additionalRuntimeProps,
+        );
+      }
+      Component.displayName = `${componentName} (id: ${fragmentReference.root}) @component`;
+      return Component;
+    })();
+  return byArgs[stringifiedArgs];
+}

package/src/core/entrypoint.ts

@@ -0,0 +1,106 @@
+import type { TypeName } from './IsographEnvironment';
+import { TopLevelReaderArtifact } from './reader';
+import { Arguments } from './util';
+
+export type ReaderWithRefetchQueries<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+> = {
+  readonly kind: 'ReaderWithRefetchQueries';
+  readonly readerArtifact: TopLevelReaderArtifact<
+    TReadFromStore,
+    TClientFieldValue,
+    // TODO don't type this as any
+    any
+  >;
+  readonly nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[];
+};
+
+export type NetworkRequestInfo = {
+  readonly kind: 'NetworkRequestInfo';
+  readonly queryText: string;
+  readonly normalizationAst: NormalizationAst;
+};
+// This type should be treated as an opaque type.
+export type IsographEntrypoint<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+> = {
+  readonly kind: 'Entrypoint';
+  readonly networkRequestInfo: NetworkRequestInfo;
+  readonly readerWithRefetchQueries: ReaderWithRefetchQueries<
+    TReadFromStore,
+    TClientFieldValue
+  >;
+  readonly concreteType: TypeName;
+};
+
+export type IsographEntrypointLoader<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+> = {
+  readonly kind: 'EntrypointLoader';
+  readonly typeAndField: string;
+  readonly loader: () => Promise<
+    IsographEntrypoint<TReadFromStore, TClientFieldValue>
+  >;
+};
+
+export type NormalizationAstNode =
+  | NormalizationScalarField
+  | NormalizationLinkedField
+  | NormalizationInlineFragment;
+export type NormalizationAst = ReadonlyArray<NormalizationAstNode>;
+
+export type NormalizationScalarField = {
+  readonly kind: 'Scalar';
+  readonly fieldName: string;
+  readonly arguments: Arguments | null;
+};
+
+export type NormalizationLinkedField = {
+  readonly kind: 'Linked';
+  readonly fieldName: string;
+  readonly arguments: Arguments | null;
+  readonly selections: NormalizationAst;
+  readonly concreteType: TypeName | null;
+};
+
+export type NormalizationInlineFragment = {
+  readonly kind: 'InlineFragment';
+  readonly type: string;
+  readonly selections: NormalizationAst;
+};
+
+// This is more like an entrypoint, but one specifically for a refetch query/mutation
+export type RefetchQueryNormalizationArtifact = {
+  readonly kind: 'RefetchQuery';
+  readonly networkRequestInfo: NetworkRequestInfo;
+  readonly concreteType: TypeName;
+};
+
+// TODO rename
+export type RefetchQueryNormalizationArtifactWrapper = {
+  readonly artifact: RefetchQueryNormalizationArtifact;
+  readonly allowedVariables: string[];
+};
+
+export function assertIsEntrypoint<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+>(
+  value:
+    | IsographEntrypoint<TReadFromStore, TClientFieldValue>
+    | ((_: any) => any)
+    // Temporarily, allow any here. Once we automatically provide
+    // types to entrypoints, we probably don't need this.
+    | any,
+): asserts value is IsographEntrypoint<TReadFromStore, TClientFieldValue> {
+  if (typeof value === 'function') throw new Error('Not a string');
+}
+
+export type ExtractReadFromStore<Type> =
+  Type extends IsographEntrypoint<infer X, any> ? X : never;
+export type ExtractResolverResult<Type> =
+  Type extends IsographEntrypoint<any, infer X> ? X : never;
+export type ExtractProps<Type> = Type extends React.FC<infer X> ? X : never;

package/src/core/garbageCollection.ts

@@ -0,0 +1,173 @@
+import { Variables } from './FragmentReference';
+import {
+  DataId,
+  IsographEnvironment,
+  IsographStore,
+  StoreRecord,
+  assertLink,
+  type Link,
+  type TypeName,
+} from './IsographEnvironment';
+import { getParentRecordKey } from './cache';
+import { NormalizationAst } from './entrypoint';
+
+export type RetainedQuery = {
+  readonly normalizationAst: NormalizationAst;
+  readonly variables: {};
+  readonly root: Link;
+};
+
+type DidUnretainSomeQuery = boolean;
+export function unretainQuery(
+  environment: IsographEnvironment,
+  retainedQuery: RetainedQuery,
+): DidUnretainSomeQuery {
+  environment.retainedQueries.delete(retainedQuery);
+  environment.gcBuffer.push(retainedQuery);
+
+  if (environment.gcBuffer.length > environment.gcBufferSize) {
+    environment.gcBuffer.shift();
+    return true;
+  }
+
+  return false;
+}
+
+export function retainQuery(
+  environment: IsographEnvironment,
+  queryToRetain: RetainedQuery,
+) {
+  environment.retainedQueries.add(queryToRetain);
+  // TODO can we remove this query from the buffer somehow?
+  // We are relying on === equality, but we really should be comparing
+  // id + variables
+}
+
+export function garbageCollectEnvironment(environment: IsographEnvironment) {
+  const retainedIds: RetainedIds = {};
+
+  for (const query of environment.retainedQueries) {
+    recordReachableIds(environment.store, query, retainedIds);
+  }
+  for (const query of environment.gcBuffer) {
+    recordReachableIds(environment.store, query, retainedIds);
+  }
+
+  for (const typeName in environment.store) {
+    const dataById = environment.store[typeName];
+    if (dataById == null) continue;
+    const retainedTypeIds = retainedIds[typeName];
+
+    // delete all objects
+    if (retainedTypeIds == undefined || retainedTypeIds.size == 0) {
+      delete environment.store[typeName];
+      continue;
+    }
+
+    for (const dataId in dataById) {
+      if (!retainedTypeIds.has(dataId)) {
+        delete dataById[dataId];
+      }
+    }
+
+    if (Object.keys(dataById).length === 0) {
+      delete environment.store[typeName];
+    }
+  }
+}
+
+interface RetainedIds {
+  [typeName: TypeName]: Set<DataId>;
+}
+
+function recordReachableIds(
+  store: IsographStore,
+  retainedQuery: RetainedQuery,
+  mutableRetainedIds: RetainedIds,
+) {
+  const record =
+    store[retainedQuery.root.__typename]?.[retainedQuery.root.__link];
+
+  const retainedRecordsIds = (mutableRetainedIds[
+    retainedQuery.root.__typename
+  ] ??= new Set());
+  retainedRecordsIds.add(retainedQuery.root.__link);
+
+  if (record) {
+    recordReachableIdsFromRecord(
+      store,
+      record,
+      mutableRetainedIds,
+      retainedQuery.normalizationAst,
+      retainedQuery.variables,
+    );
+  }
+}
+
+function recordReachableIdsFromRecord(
+  store: IsographStore,
+  currentRecord: StoreRecord,
+  mutableRetainedIds: RetainedIds,
+  selections: NormalizationAst,
+  variables: Variables | null,
+) {
+  for (const selection of selections) {
+    switch (selection.kind) {
+      case 'Linked':
+        const linkKey = getParentRecordKey(selection, variables ?? {});
+        const linkedFieldOrFields = currentRecord[linkKey];
+
+        const links: Link[] = [];
+        if (Array.isArray(linkedFieldOrFields)) {
+          for (const maybeLink of linkedFieldOrFields) {
+            const link = assertLink(maybeLink);
+            if (link != null) {
+              links.push(link);
+            }
+          }
+        } else {
+          const link = assertLink(linkedFieldOrFields);
+          if (link != null) {
+            links.push(link);
+          }
+        }
+
+        let typeStore =
+          selection.concreteType !== null
+            ? store[selection.concreteType]
+            : null;
+
+        if (typeStore == null && selection.concreteType !== null) {
+          continue;
+        }
+
+        for (const nextRecordLink of links) {
+          let __typename = nextRecordLink.__typename;
+
+          const resolvedTypeStore = typeStore ?? store[__typename];
+
+          if (resolvedTypeStore == null) {
+            continue;
+          }
+
+          const nextRecord = resolvedTypeStore[nextRecordLink.__link];
+          if (nextRecord != null) {
+            const retainedRecordsIds = (mutableRetainedIds[__typename] ??=
+              new Set());
+            retainedRecordsIds.add(nextRecordLink.__link);
+            recordReachableIdsFromRecord(
+              store,
+              nextRecord,
+              mutableRetainedIds,
+              selection.selections,
+              variables,
+            );
+          }
+        }
+
+        continue;
+      case 'Scalar':
+        continue;
+    }
+  }
+}

package/src/core/logging.ts

@@ -0,0 +1,116 @@
+import { CleanupFn } from '@isograph/disposable-types';
+import {
+  IsographEnvironment,
+  IsographStore,
+  StoreRecord,
+  type Link,
+} from './IsographEnvironment';
+import {
+  IsographEntrypoint,
+  NormalizationAst,
+  RefetchQueryNormalizationArtifact,
+} from './entrypoint';
+import { FragmentReference, Variables } from './FragmentReference';
+import { NetworkResponseObject, type EncounteredIds } from './cache';
+import { Arguments } from './util';
+import { ReadDataResult } from './read';
+import { CheckResult } from './check';
+
+export type LogMessage =
+  | {
+      kind: 'GettingSuspenseCacheItem';
+      index: string;
+      availableCacheItems: ReadonlyArray<string>;
+      found: boolean;
+    }
+  | {
+      kind: 'AboutToNormalize';
+      normalizationAst: NormalizationAst;
+      networkResponse: NetworkResponseObject;
+      variables: Variables;
+    }
+  | {
+      kind: 'AfterNormalization';
+      store: IsographStore;
+      encounteredIds: EncounteredIds;
+    }
+  | {
+      kind: 'DeepEqualityCheck';
+      fragmentReference: FragmentReference<any, any>;
+      old: object;
+      new: object;
+      deeplyEqual: boolean;
+    }
+  | {
+      kind: 'ComponentRerendered';
+      componentName: string;
+      rootLink: Link;
+    }
+  | {
+      kind: 'MakeNetworkRequest';
+      artifact:
+        | RefetchQueryNormalizationArtifact
+        | IsographEntrypoint<any, any>;
+      variables: Variables;
+      networkRequestId: string;
+    }
+  | {
+      kind: 'ReceivedNetworkResponse';
+      // TODO should be object
+      networkResponse: any;
+      networkRequestId: string;
+    }
+  | {
+      kind: 'ReceivedNetworkError';
+      error: any;
+      networkRequestId: string;
+    }
+  | {
+      kind: 'MissingFieldHandlerCalled';
+      root: Link;
+      storeRecord: StoreRecord;
+      fieldName: string;
+      arguments: Arguments | null;
+      variables: Variables;
+    }
+  | {
+      kind: 'DoneReading';
+      response: ReadDataResult<any>;
+    }
+  | {
+      kind: 'NonEntrypointReceived';
+      entrypoint: any;
+    }
+  | {
+      kind: 'EnvironmentCheck';
+      result: CheckResult;
+    };
+
+export type LogFunction = (logMessage: LogMessage) => void;
+
+// wrapped so that items in the loggers set are unique.
+export type WrappedLogFunction = {
+  log: LogFunction;
+};
+
+export function logMessage(
+  environment: IsographEnvironment,
+  message: LogMessage,
+) {
+  for (const logger of environment.loggers) {
+    try {
+      logger.log(message);
+    } catch {}
+  }
+}
+
+export function registerLogger(
+  environment: IsographEnvironment,
+  log: LogFunction,
+): CleanupFn {
+  const wrapped = { log };
+  environment.loggers.add(wrapped);
+  return () => {
+    environment.loggers.delete(wrapped);
+  };
+}