@isograph/react 0.4.3 → 0.5.1

package/src/core/IsographEnvironment.ts

@@ -1,21 +1,30 @@
-import { ParentCache } from '@isograph/react-disposable-state';
-import {
+import type { ParentCache } from '@isograph/react-disposable-state';
+import type { Brand } from './brand';
+import type {
   IsographEntrypoint,
   IsographOperation,
   IsographPersistedOperation,
+  ReaderWithRefetchQueries,
+  ReaderWithRefetchQueriesLoader,
 } from './entrypoint';
-import {
+import type {
+  ExtractStartUpdate,
   FragmentReference,
+  StableIdForFragmentReference,
+  UnknownTReadFromStore,
   Variables,
-  type StableIdForFragmentReference,
-  type UnknownTReadFromStore,
 } from './FragmentReference';
-import { RetainedQuery } from './garbageCollection';
-import { LogFunction, WrappedLogFunction } from './logging';
-import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
-import { WithEncounteredRecords } from './read';
+import type { RetainedQuery } from './garbageCollection';
+import type { LogFunction, WrappedLogFunction } from './logging';
+import { type StoreLayer } from './optimisticProxy';
+import type { PromiseWrapper } from './PromiseWrapper';
+import { wrapPromise, wrapResolvedValue } from './PromiseWrapper';
+import type {
+  NetworkRequestReaderOptions,
+  WithEncounteredRecords,
+} from './read';
 import type { ReaderAst, StartUpdate } from './reader';
-import type { Brand } from './brand';
+import { isArray } from './util';
 
 export type ComponentOrFieldName = string;
 export type StringifiedArgs = string;
@@ -56,8 +65,9 @@ export type Subscriptions = Set<Subscription>;
 export type CacheMap<T> = { [index: string]: ParentCache<T> };
 
 export type IsographEnvironment = {
-  readonly store: IsographStore;
+  store: StoreLayer;
   readonly networkFunction: IsographNetworkFunction;
+  readonly componentFunction: IsographComponentFunction;
   readonly missingFieldHandler: MissingFieldHandler | null;
   readonly componentCache: FieldCache<React.FC<any>>;
   readonly eagerReaderCache: FieldCache<StartUpdate<any> | undefined>;
@@ -68,7 +78,7 @@ export type IsographEnvironment = {
   // TODO make this a CacheMap and add GC
   readonly entrypointArtifactCache: Map<
     string,
-    PromiseWrapper<IsographEntrypoint<any, any, any>>
+    PromiseWrapper<IsographEntrypoint<any, any, any, any>>
   >;
   readonly retainedQueries: Set<RetainedQuery>;
   readonly gcBuffer: Array<RetainedQuery>;
@@ -89,6 +99,15 @@ export type IsographNetworkFunction = (
   variables: Variables,
 ) => Promise<any>;
 
+export type IsographComponentFunction = <
+  TReadFromStore extends UnknownTReadFromStore = any,
+>(
+  environment: IsographEnvironment,
+  fragmentReference: FragmentReference<TReadFromStore, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+  startUpdate: ExtractStartUpdate<TReadFromStore>,
+) => React.FC<any>;
+
 export interface Link<T extends TypeName> extends StoreLink {
   readonly __link: Brand<DataId, T>;
   readonly __typename: T;
@@ -111,7 +130,7 @@ export type DataTypeValue =
   // Singular linked fields:
   | StoreLink
   // Plural scalar and linked fields:
-  | DataTypeValue[];
+  | readonly DataTypeValue[];
 
 export type StoreRecord = {
   [index: DataId | string]: DataTypeValue;
@@ -125,28 +144,39 @@ export type DataId = string;
 
 export const ROOT_ID: DataId & '__ROOT' = '__ROOT';
 
-export type IsographStore = {
+export type StoreLayerData = {
   [index: TypeName]: {
     [index: DataId]: StoreRecord | null;
   } | null;
+};
+
+export interface BaseStoreLayerData extends StoreLayerData {
   readonly Query: {
     readonly __ROOT: StoreRecord;
   };
-};
+}
 
 const DEFAULT_GC_BUFFER_SIZE = 10;
-export function createIsographEnvironment(
-  store: IsographStore,
+export function createIsographEnvironmentCore(
+  baseStoreLayerData: BaseStoreLayerData,
   networkFunction: IsographNetworkFunction,
+  componentFunction: IsographComponentFunction,
   missingFieldHandler?: MissingFieldHandler | null,
   logFunction?: LogFunction | null,
 ): IsographEnvironment {
   logFunction?.({
     kind: 'EnvironmentCreated',
   });
+  let store = {
+    kind: 'BaseStoreLayer',
+    data: baseStoreLayerData,
+    parentStoreLayer: null,
+    childStoreLayer: null,
+  } as const;
   return {
     store,
     networkFunction,
+    componentFunction,
     missingFieldHandler: missingFieldHandler ?? null,
     componentCache: {},
     eagerReaderCache: {},
@@ -160,7 +190,7 @@ export function createIsographEnvironment(
   };
 }
 
-export function createIsographStore(): IsographStore {
+export function createIsographStore(): BaseStoreLayerData {
   return {
     Query: {
       [ROOT_ID]: {},
@@ -169,7 +199,7 @@ export function createIsographStore(): IsographStore {
 }
 
 export function assertLink(link: DataTypeValue): StoreLink | null | undefined {
-  if (Array.isArray(link)) {
+  if (isArray(link)) {
     throw new Error('Unexpected array');
   }
   if (link == null) {
@@ -198,8 +228,8 @@ export function getLink(maybeLink: DataTypeValue): StoreLink | null {
 export function getOrLoadIsographArtifact(
   environment: IsographEnvironment,
   key: string,
-  loader: () => Promise<IsographEntrypoint<any, any, any>>,
-): PromiseWrapper<IsographEntrypoint<any, any, any>> {
+  loader: () => Promise<IsographEntrypoint<any, any, any, any>>,
+): PromiseWrapper<IsographEntrypoint<any, any, any, any>> {
   const value = environment.entrypointArtifactCache.get(key);
   if (value != null) {
     return value;
@@ -208,3 +238,32 @@ export function getOrLoadIsographArtifact(
   environment.entrypointArtifactCache.set(key, wrapped);
   return wrapped;
 }
+
+export function getOrLoadReaderWithRefetchQueries(
+  _environment: IsographEnvironment,
+  readerWithRefetchQueries:
+    | ReaderWithRefetchQueries<any, any>
+    | ReaderWithRefetchQueriesLoader<any, any>,
+): {
+  readerWithRefetchQueries: PromiseWrapper<ReaderWithRefetchQueries<any, any>>;
+  fieldName: string;
+  readerArtifactKind: 'EagerReaderArtifact' | 'ComponentReaderArtifact';
+} {
+  switch (readerWithRefetchQueries.kind) {
+    case 'ReaderWithRefetchQueries':
+      return {
+        readerWithRefetchQueries: wrapResolvedValue(readerWithRefetchQueries),
+        fieldName: readerWithRefetchQueries.readerArtifact.fieldName,
+        readerArtifactKind: readerWithRefetchQueries.readerArtifact.kind,
+      };
+    case 'ReaderWithRefetchQueriesLoader':
+      return {
+        // TODO: cache promise wrapper
+        readerWithRefetchQueries: wrapPromise(
+          readerWithRefetchQueries.loader(),
+        ),
+        fieldName: readerWithRefetchQueries.fieldName,
+        readerArtifactKind: readerWithRefetchQueries.readerArtifactKind,
+      };
+  }
+}

package/src/core/PromiseWrapper.ts

@@ -5,12 +5,12 @@ export type NotSet = typeof NOT_SET;
 
 export type Result<T, E> =
   | {
-      kind: 'Ok';
-      value: T;
+      readonly kind: 'Ok';
+      readonly value: T;
     }
   | {
-      kind: 'Err';
-      error: E;
+      readonly kind: 'Err';
+      readonly error: E;
     };
 
 /**
@@ -22,6 +22,13 @@ export type PromiseWrapper<T, E = any> = {
   result: Result<Exclude<T, NotSet>, E> | NotSet;
 };
 
+export interface PromiseWrapperOk<T, E = any> extends PromiseWrapper<T, E> {
+  result: {
+    readonly kind: 'Ok';
+    readonly value: Exclude<T, NotSet>;
+  };
+}
+
 export function wrapPromise<T>(
   promise: Promise<Exclude<T, NotSet>>,
 ): PromiseWrapper<T, unknown> {
@@ -39,7 +46,7 @@ export function wrapPromise<T>(
 
 export function wrapResolvedValue<T>(
   value: Exclude<T, NotSet>,
-): PromiseWrapper<T, never> {
+): PromiseWrapperOk<T, never> {
   return {
     promise: Promise.resolve(value),
     result: {
@@ -65,8 +72,8 @@ export function readPromise<T, E>(p: PromiseWrapper<T, E>): T {
 
 export type PromiseState<T, E> =
   | {
-      kind: 'Pending';
-      promise: Promise<T>;
+      readonly kind: 'Pending';
+      readonly promise: Promise<T>;
     }
   | Result<T, E>;
 

package/src/core/areEqualWithDeepComparison.ts

@@ -6,12 +6,8 @@ function mergeUsingReaderAst(
   oldItem: unknown,
   newItem: unknown,
 ): unknown {
-  if (newItem === null) {
-    return oldItem === null ? oldItem : newItem;
-  }
-
-  if (newItem === undefined) {
-    return oldItem === undefined ? oldItem : newItem;
+  if (newItem == null || oldItem == null) {
+    return newItem;
   }
 
   if (Array.isArray(newItem)) {
@@ -31,12 +27,6 @@ function mergeUsingReaderAst(
       }
 
       return mergeObjectsUsingReaderAst(field.selections, oldItem, newItem);
-    default: {
-      // Ensure we have covered all variants
-      let _: never = field;
-      _;
-      throw new Error('Unexpected case.');
-    }
   }
 }
 
@@ -124,12 +114,6 @@ export function mergeObjectsUsingReaderAst(
       case 'ImperativelyLoadedField':
       case 'LoadablySelectedField':
         break;
-      default: {
-        // Ensure we have covered all variants
-        let _: never = field;
-        _;
-        throw new Error('Unexpected case.');
-      }
     }
   }
 

package/src/core/brand.ts

@@ -16,3 +16,21 @@ export type Brand<
   Brand extends symbol | string,
   // @ts-ignore
 > = infer _ extends Brand ? BaseType : never;
+
+declare const PhantomDataBrand: unique symbol;
+/**
+ * A phantom data type is one that shouldn't show up at runtime, but is checked statically (and only) at compile time.
+ * Data types can use extra properties to act as markers or to perform type checking at compile time. These extra properties should hold no storage values, and have no runtime behavior.
+ *
+ * ```tsx
+ * type MyType<T> = {
+ *   readonly value: number;
+ *   readonly '~T'?: PhantomData<T>;
+ * }
+ * ```
+ */
+export type PhantomData<T> = Brand<T, typeof PhantomDataBrand>;
+
+export type Invariant<T> = (_: T) => T;
+export type Covariant<T> = (_: never) => T;
+export type Contravariant<T> = (_: T) => void;