@isograph/react 0.3.0 → 0.4.0

package/src/core/reader.ts

@@ -1,25 +1,25 @@
 import { Factory } from '@isograph/disposable-types';
+import { FetchOptions } from './check';
+import {
+  IsographEntrypoint,
+  IsographEntrypointLoader,
+  RefetchQueryNormalizationArtifact,
+  RefetchQueryNormalizationArtifactWrapper,
+} from './entrypoint';
 import {
-  FragmentReference,
   ExtractParameters,
-  ExtractData,
+  FragmentReference,
+  type UnknownTReadFromStore,
 } from './FragmentReference';
 import {
   ComponentOrFieldName,
   IsographEnvironment,
-  type Link,
+  type StoreLink,
 } from './IsographEnvironment';
-import {
-  IsographEntrypoint,
-  IsographEntrypointLoader,
-  RefetchQueryNormalizationArtifact,
-  RefetchQueryNormalizationArtifactWrapper,
-} from './entrypoint';
 import { Arguments } from './util';
-import { FetchOptions } from './check';
 
 export type TopLevelReaderArtifact<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
   TComponentProps extends Record<PropertyKey, never>,
 > =
@@ -27,35 +27,39 @@ export type TopLevelReaderArtifact<
   | ComponentReaderArtifact<TReadFromStore, TComponentProps>;
 
 export type EagerReaderArtifact<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 > = {
   readonly kind: 'EagerReaderArtifact';
+  readonly fieldName: string;
   readonly readerAst: ReaderAst<TReadFromStore>;
   readonly resolver: (
     data: ResolverFirstParameter<TReadFromStore>,
   ) => TClientFieldValue;
+  readonly hasUpdatable: boolean;
 };
 
 export type ComponentReaderArtifact<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TComponentProps extends Record<string, unknown> = Record<PropertyKey, never>,
 > = {
   readonly kind: 'ComponentReaderArtifact';
-  readonly componentName: ComponentOrFieldName;
+  readonly fieldName: ComponentOrFieldName;
   readonly readerAst: ReaderAst<TReadFromStore>;
   readonly resolver: (
     data: ResolverFirstParameter<TReadFromStore>,
     runtimeProps: TComponentProps,
   ) => React.ReactNode;
+  readonly hasUpdatable: boolean;
 };
 
 export type ResolverFirstParameter<
-  TReadFromStore extends { data: object; parameters: object },
-> = {
-  data: ExtractData<TReadFromStore>;
-  parameters: ExtractParameters<TReadFromStore>;
-};
+  TReadFromStore extends UnknownTReadFromStore,
+> = Pick<TReadFromStore, 'data' | 'parameters' | 'startUpdate'>;
+
+export type StartUpdate<UpdatableData> = (
+  updater: (updatableData: UpdatableData) => void,
+) => void;
 
 export type RefetchReaderArtifact = {
   readonly kind: 'RefetchReaderArtifact';
@@ -67,7 +71,7 @@ export type RefetchReaderArtifact = {
     variables: any,
     // TODO type this better
     filteredVariables: any,
-    rootLink: Link,
+    rootLink: StoreLink,
     readerArtifact: TopLevelReaderArtifact<any, any, any> | null,
     // TODO type this better
     nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
@@ -79,7 +83,8 @@ export type ReaderAstNode =
   | ReaderLinkedField
   | ReaderNonLoadableResolverField
   | ReaderImperativelyLoadedField
-  | ReaderLoadableField;
+  | LoadablySelectedField
+  | ReaderLinkField;
 
 // @ts-ignore
 export type ReaderAst<TReadFromStore> = ReadonlyArray<ReaderAstNode>;
@@ -89,7 +94,14 @@ export type ReaderScalarField = {
   readonly fieldName: string;
   readonly alias: string | null;
   readonly arguments: Arguments | null;
+  readonly isUpdatable: boolean;
+};
+
+export type ReaderLinkField = {
+  readonly kind: 'Link';
+  readonly alias: string;
 };
+
 export type ReaderLinkedField = {
   readonly kind: 'Linked';
   readonly fieldName: string;
@@ -97,9 +109,14 @@ export type ReaderLinkedField = {
   readonly selections: ReaderAst<unknown>;
   readonly arguments: Arguments | null;
   readonly condition: EagerReaderArtifact<
-    { data: object; parameters: object },
-    boolean | Link | null
+    { data: any; parameters: any; startUpdate?: StartUpdate<any> },
+    StoreLink | null
   > | null;
+  readonly isUpdatable: boolean;
+  /**
+   * If refetchQueryIndex != null, then the linked field is a client pointer.
+   */
+  readonly refetchQueryIndex: number | null;
 };
 
 export type ReaderNonLoadableResolverField = {
@@ -115,11 +132,11 @@ export type ReaderImperativelyLoadedField = {
   readonly kind: 'ImperativelyLoadedField';
   readonly alias: string;
   readonly refetchReaderArtifact: RefetchReaderArtifact;
-  readonly refetchQuery: number;
+  readonly refetchQueryIndex: number;
   readonly name: string;
 };
 
-export type ReaderLoadableField = {
+export type LoadablySelectedField = {
   readonly kind: 'LoadablySelectedField';
   readonly alias: string;
 
@@ -132,11 +149,11 @@ export type ReaderLoadableField = {
 
   // TODO we should not type these as any
   readonly entrypoint:
-    | IsographEntrypoint<any, any>
+    | IsographEntrypoint<any, any, any>
     | IsographEntrypointLoader<any, any>;
 };
 
-type StableId = string;
+export 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
@@ -147,7 +164,7 @@ type StableId = string;
 /// 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<
-  TReadFromStore extends { data: object; parameters: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TResult,
   TArgs = ExtractParameters<TReadFromStore>,
 > = (
@@ -156,5 +173,5 @@ export type LoadableField<
   // user-facing API. Users should only interact with LoadableFields via APIs
   // like useClientSideDefer. These APIs should have a nullable fetchOptions
   // parameter, and provide a default value ({}) to the LoadableField.
-  fetchOptions: FetchOptions,
+  fetchOptions: FetchOptions<TResult>,
 ) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];

package/src/core/startUpdate.ts

@@ -0,0 +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 {
+  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, unknown>,
+  eagerResolverName: string,
+  networkRequestOptions: NetworkRequestReaderOptions,
+): ExtractStartUpdate<TReadFromStore> {
+  return (environment.eagerReaderCache[
+    stableIdForFragmentReference(fragmentReference, eagerResolverName)
+  ] ??= createStartUpdate(
+    environment,
+    fragmentReference,
+    networkRequestOptions,
+  ));
+}
+
+export function createStartUpdate<TReadFromStore extends UnknownTReadFromStore>(
+  environment: IsographEnvironment,
+  fragmentReference: FragmentReference<TReadFromStore, unknown>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+): ExtractStartUpdate<TReadFromStore> {
+  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

@@ -24,4 +24,8 @@ export type ArgumentValue =
   | {
       readonly kind: 'Enum';
       readonly value: string;
+    }
+  | {
+      readonly kind: 'Object';
+      readonly value: Arguments;
     };

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   unretainQuery,
   type RetainedQuery,
   garbageCollectEnvironment,
+  type DidUnretainSomeQuery,
 } from './core/garbageCollection';
 export {
   type PromiseWrapper,
@@ -10,8 +11,21 @@ export {
   getPromiseState,
   wrapResolvedValue,
   wrapPromise,
+  type PromiseState,
+  type Result,
+  type AnyError,
+  type NotSet,
+  NOT_SET,
 } from './core/PromiseWrapper';
-export { subscribe, normalizeData } from './core/cache';
+export {
+  callSubscriptions,
+  subscribe,
+  normalizeData,
+  type NetworkResponseObject,
+  type NetworkResponseValue,
+  type NetworkResponseScalarValue,
+  type EncounteredIds,
+} from './core/cache';
 export { makeNetworkRequest } from './core/makeNetworkRequest';
 export {
   ROOT_ID,
@@ -20,10 +34,22 @@ export {
   type IsographEnvironment,
   type IsographNetworkFunction,
   type IsographStore,
+  type MissingFieldHandler,
+  type StoreLink,
   type Link,
   type StoreRecord,
+  type CacheMap,
   createIsographEnvironment,
   createIsographStore,
+  type FieldCache,
+  type Subscriptions,
+  type Subscription,
+  type TypeName,
+  type FragmentSubscription,
+  type AnyChangesToRecordSubscription,
+  type AnyRecordSubscription,
+  type ComponentOrFieldName,
+  type StringifiedArgs,
 } from './core/IsographEnvironment';
 export {
   type EagerReaderArtifact,
@@ -36,14 +62,24 @@ export {
   type ReaderScalarField,
   type TopLevelReaderArtifact,
   type LoadableField,
+  type StableId,
   type ResolverFirstParameter,
+  type ReaderImperativelyLoadedField,
+  type LoadablySelectedField as ReaderLoadableField,
+  type ReaderLinkField,
+  type StartUpdate,
 } from './core/reader';
 export {
   type NormalizationAst,
   type NormalizationAstNode,
+  type NormalizationAstNodes,
+  type NormalizationAstLoader,
   type NormalizationLinkedField,
   type NormalizationScalarField,
   type IsographEntrypoint,
+  type IsographOperation,
+  type IsographPersistedOperation,
+  type IsographPersistedOperationExtraInfo,
   assertIsEntrypoint,
   type RefetchQueryNormalizationArtifact,
   type RefetchQueryNormalizationArtifactWrapper,
@@ -51,8 +87,16 @@ export {
   type ExtractReadFromStore,
   type ExtractResolverResult,
   type NetworkRequestInfo,
+  type NormalizationInlineFragment,
+  type ReaderWithRefetchQueries,
+  type IsographEntrypointLoader,
 } from './core/entrypoint';
-export { readButDoNotEvaluate } from './core/read';
+export {
+  readButDoNotEvaluate,
+  type WithEncounteredRecords,
+  type NetworkRequestReaderOptions,
+  type ReadDataResult,
+} from './core/read';
 export {
   type ExtractSecondParam,
   type CombineWithIntrinsicAttributes,
@@ -66,23 +110,44 @@ export {
   type Variables,
   type ExtractParameters,
   type ExtractData,
+  type UnknownTReadFromStore,
   stableIdForFragmentReference,
+  type ExtractStartUpdate,
+  type VariableValue,
+  type StableIdForFragmentReference,
 } from './core/FragmentReference';
 export {
   type LogMessage,
   type LogFunction,
+  type WrappedLogFunction,
   logMessage,
   registerLogger,
 } from './core/logging';
-export { check, CheckResult, FetchOptions, ShouldFetch } from './core/check';
+export {
+  check,
+  type CheckResult,
+  type FetchOptions,
+  type RequiredFetchOptions,
+  type ShouldFetch,
+  type RequiredShouldFetch,
+} from './core/check';
 
 export {
   IsographEnvironmentProvider,
   useIsographEnvironment,
   type IsographEnvironmentProviderProps,
 } from './react/IsographEnvironmentProvider';
-export { useImperativeReference } from './react/useImperativeReference';
+export {
+  useImperativeReference,
+  type UseImperativeReferenceResult,
+} from './react/useImperativeReference';
+export {
+  FragmentRenderer,
+  type IsExactlyIntrinsicAttributes,
+} 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,
@@ -93,7 +158,23 @@ export { useRerenderOnChange } from './react/useRerenderOnChange';
 export { RenderAfterCommit__DO_NOT_USE } from './react/RenderAfterCommit__DO_NOT_USE';
 
 export { useClientSideDefer } from './loadable-hooks/useClientSideDefer';
-export { useImperativeExposedMutationField } from './loadable-hooks/useImperativeExposedMutationField';
-export { useSkipLimitPagination } from './loadable-hooks/useSkipLimitPagination';
-export { useConnectionSpecPagination } from './loadable-hooks/useConnectionSpecPagination';
-export { useImperativeLoadableField } from './loadable-hooks/useImperativeLoadableField';
+export {
+  useImperativeExposedMutationField,
+  type UseImperativeLoadableFieldReturn as UseImperativeExposedMutationFieldReturn,
+} from './loadable-hooks/useImperativeExposedMutationField';
+export {
+  useSkipLimitPagination,
+  type UseSkipLimitPaginationArgs,
+  type UseSkipLimitReturnValue,
+} from './loadable-hooks/useSkipLimitPagination';
+export {
+  useConnectionSpecPagination,
+  type Connection,
+  type PageInfo,
+  type UseConnectionSpecPaginationArgs,
+  type UsePaginationReturnValue,
+} from './loadable-hooks/useConnectionSpecPagination';
+export {
+  useImperativeLoadableField,
+  type UseImperativeLoadableFieldReturn,
+} from './loadable-hooks/useImperativeLoadableField';