@isograph/react 0.3.0 → 0.4.0

package/isograph.config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "../isograph-compiler/isograph-config-schema.json",
   "project_root": "./src/tests",
   "schema": "./schema.graphql",
   "options": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -8,15 +8,15 @@
   "author": "Isograph Labs",
   "license": "MIT",
   "scripts": {
-    "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
+    "compile-libs": "rimraf dist && tsc -p tsconfig.pkg.json",
     "compile-watch": "tsc -p tsconfig.pkg.json --watch",
     "test": "vitest run",
     "test-watch": "vitest watch",
     "coverage": "vitest run --coverage",
-    "prepack": "pnpm run test && pnpm run compile",
+    "prepack": "pnpm run test && pnpm run compile-libs",
     "tsc": "tsc",
-    "iso": "../../target/debug/isograph_cli --config ./isograph.config.json",
-    "iso-watch": "../../target/debug/isograph_cli --config ./isograph.config.json --watch"
+    "tsc-force": "tsc --build --clean && tsc --build --force",
+    "iso": "cross-env ISO_PRINT_ABSOLUTE_FILEPATH=1 ../../target/debug/isograph_cli --config ./isograph.config.json"
   },
   "dependencies": {
     "@isograph/disposable-types": "*",
@@ -24,7 +24,7 @@
     "@isograph/reference-counted-pointer": "*"
   },
   "peerDependencies": {
-    "react": "18.3.1"
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.24.7",

package/src/core/FragmentReference.ts

@@ -1,12 +1,28 @@
-import { type Link } from './IsographEnvironment';
 import { ReaderWithRefetchQueries } from '../core/entrypoint';
+import { stableCopy } from './cache';
+import { type StoreLink } from './IsographEnvironment';
 import { PromiseWrapper } from './PromiseWrapper';
+import type { StartUpdate } from './reader';
 
 // TODO type this better
-export type VariableValue = string | number | boolean | null | object;
+export type VariableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | {
+      readonly [index: string]: VariableValue;
+    }
+  | VariableValue[];
 
 export type Variables = { readonly [index: string]: VariableValue };
 
+export type UnknownTReadFromStore = {
+  parameters: object;
+  data: object;
+  startUpdate?: StartUpdate<object>;
+};
+
 export type ExtractData<T> = T extends {
   data: infer D extends object;
 }
@@ -19,31 +35,39 @@ export type ExtractParameters<T> = T extends {
   ? P
   : Variables;
 
+export type ExtractStartUpdate<T extends UnknownTReadFromStore> =
+  T['startUpdate'];
+
+export type ExtractUpdatableData<T extends UnknownTReadFromStore> =
+  ExtractUpdatableDataFromStartUpdate<ExtractStartUpdate<T>>;
+
+export type ExtractUpdatableDataFromStartUpdate<T> =
+  T extends StartUpdate<infer D> ? D : never;
+
 export type FragmentReference<
-  TReadFromStore extends { parameters: object; data: object },
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 > = {
   readonly kind: 'FragmentReference';
   readonly readerWithRefetchQueries: PromiseWrapper<
     ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
   >;
-  readonly root: Link;
+  readonly root: StoreLink;
+  // TODO we potentially stably copy and stringify variables a lot!
+  // So, we should employ interior mutability: pretend that fragent reference
+  // is immutable, but actually store something like
+  // `Map<Variable, StablyCopiedStringifiedOutput>`
+  // and read or update that map when we would otherwise stably copy and
+  // stringify.
   readonly variables: ExtractParameters<TReadFromStore>;
   readonly networkRequest: PromiseWrapper<void, any>;
 };
 
+export type StableIdForFragmentReference = string;
+
 export function stableIdForFragmentReference(
   fragmentReference: FragmentReference<any, any>,
-): string {
-  return `${fragmentReference.root.__typename}/${fragmentReference.root.__link}/TODO_FRAGMENT_NAME/${serializeVariables(fragmentReference.variables ?? {})}`;
-}
-
-function serializeVariables(variables: Variables) {
-  let s = '';
-  const keys = Object.keys(variables);
-  keys.sort();
-  for (const key of keys) {
-    s += `${key}:${variables[key]},`;
-  }
-  return s;
+  fieldName: string,
+): StableIdForFragmentReference {
+  return `${fragmentReference.root.__typename}/${fragmentReference.root.__link}/${fieldName}/${JSON.stringify(stableCopy(fragmentReference.variables))}`;
 }

package/src/core/IsographEnvironment.ts

@@ -1,57 +1,66 @@
 import { ParentCache } from '@isograph/react-disposable-state';
+import {
+  IsographEntrypoint,
+  IsographOperation,
+  IsographPersistedOperation,
+} from './entrypoint';
+import {
+  FragmentReference,
+  Variables,
+  type StableIdForFragmentReference,
+  type UnknownTReadFromStore,
+} from './FragmentReference';
 import { RetainedQuery } from './garbageCollection';
-import { WithEncounteredRecords } from './read';
-import { FragmentReference, Variables } from './FragmentReference';
-import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
-import { IsographEntrypoint } from './entrypoint';
-import type { ReaderAst } from './reader';
 import { LogFunction, WrappedLogFunction } from './logging';
+import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
+import { WithEncounteredRecords } from './read';
+import type { ReaderAst, StartUpdate } from './reader';
+import type { Brand } from './brand';
 
 export type ComponentOrFieldName = string;
 export type StringifiedArgs = string;
-type ComponentCache = {
-  [key: DataId]: {
-    [key: ComponentOrFieldName]: { [key: StringifiedArgs]: React.FC<any> };
-  };
-};
 
-export type FragmentSubscription<
-  TReadFromStore extends { parameters: object; data: object },
-> = {
-  readonly kind: 'FragmentSubscription';
-  readonly callback: (
-    newEncounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
-  ) => void;
-  /** The value read out from the previous call to readButDoNotEvaluate */
-  readonly encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>;
-  readonly fragmentReference: FragmentReference<TReadFromStore, any>;
-  readonly readerAst: ReaderAst<TReadFromStore>;
+export type FieldCache<T> = {
+  [key: StableIdForFragmentReference]: T;
 };
 
-type AnyChangesToRecordSubscription = {
+export type FragmentSubscription<TReadFromStore extends UnknownTReadFromStore> =
+  {
+    readonly kind: 'FragmentSubscription';
+    readonly callback: (
+      newEncounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
+    ) => void;
+    /** The value read out from the previous call to readButDoNotEvaluate */
+    readonly encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>;
+    readonly fragmentReference: FragmentReference<TReadFromStore, any>;
+    readonly readerAst: ReaderAst<TReadFromStore>;
+  };
+
+export type AnyChangesToRecordSubscription = {
   readonly kind: 'AnyChangesToRecord';
   readonly callback: () => void;
-  readonly recordLink: Link;
+  readonly recordLink: StoreLink;
 };
 
-type AnyRecordSubscription = {
+export type AnyRecordSubscription = {
   readonly kind: 'AnyRecords';
   readonly callback: () => void;
 };
 
-type Subscription =
-  | FragmentSubscription<{ parameters: object; data: object }>
+export type Subscription =
+  | FragmentSubscription<any>
   | AnyChangesToRecordSubscription
   | AnyRecordSubscription;
-type Subscriptions = Set<Subscription>;
+export type Subscriptions = Set<Subscription>;
 // Should this be a map?
-type CacheMap<T> = { [index: string]: ParentCache<T> };
+export type CacheMap<T> = { [index: string]: ParentCache<T> };
 
 export type IsographEnvironment = {
   readonly store: IsographStore;
   readonly networkFunction: IsographNetworkFunction;
   readonly missingFieldHandler: MissingFieldHandler | null;
-  readonly componentCache: ComponentCache;
+  readonly componentCache: FieldCache<React.FC<any>>;
+  readonly eagerReaderCache: FieldCache<StartUpdate<any> | undefined>;
   readonly subscriptions: Subscriptions;
   // N.B. this must be <any, any>, but all *usages* of this should go through
   // a function that adds type parameters.
@@ -59,7 +68,7 @@ export type IsographEnvironment = {
   // TODO make this a CacheMap and add GC
   readonly entrypointArtifactCache: Map<
     string,
-    PromiseWrapper<IsographEntrypoint<any, any>>
+    PromiseWrapper<IsographEntrypoint<any, any, any>>
   >;
   readonly retainedQueries: Set<RetainedQuery>;
   readonly gcBuffer: Array<RetainedQuery>;
@@ -69,18 +78,23 @@ export type IsographEnvironment = {
 
 export type MissingFieldHandler = (
   storeRecord: StoreRecord,
-  root: Link,
+  root: StoreLink,
   fieldName: string,
   arguments_: { [index: string]: any } | null,
   variables: Variables | null,
-) => Link | undefined;
+) => StoreLink | undefined;
 
 export type IsographNetworkFunction = (
-  queryText: string,
+  operation: IsographOperation | IsographPersistedOperation,
   variables: Variables,
 ) => Promise<any>;
 
-export type Link = {
+export interface Link<T extends TypeName> extends StoreLink {
+  readonly __link: Brand<DataId, T>;
+  readonly __typename: T;
+}
+
+export type StoreLink = {
   readonly __link: DataId;
   readonly __typename: TypeName;
 };
@@ -95,7 +109,7 @@ export type DataTypeValue =
   | string
   | null
   // Singular linked fields:
-  | Link
+  | StoreLink
   // Plural scalar and linked fields:
   | DataTypeValue[];
 
@@ -127,11 +141,15 @@ export function createIsographEnvironment(
   missingFieldHandler?: MissingFieldHandler | null,
   logFunction?: LogFunction | null,
 ): IsographEnvironment {
+  logFunction?.({
+    kind: 'EnvironmentCreated',
+  });
   return {
     store,
     networkFunction,
     missingFieldHandler: missingFieldHandler ?? null,
     componentCache: {},
+    eagerReaderCache: {},
     subscriptions: new Set(),
     fragmentCache: {},
     entrypointArtifactCache: new Map(),
@@ -150,7 +168,7 @@ export function createIsographStore(): IsographStore {
   };
 }
 
-export function assertLink(link: DataTypeValue): Link | null | undefined {
+export function assertLink(link: DataTypeValue): StoreLink | null | undefined {
   if (Array.isArray(link)) {
     throw new Error('Unexpected array');
   }
@@ -163,7 +181,7 @@ export function assertLink(link: DataTypeValue): Link | null | undefined {
   throw new Error('Invalid link');
 }
 
-export function getLink(maybeLink: DataTypeValue): Link | null {
+export function getLink(maybeLink: DataTypeValue): StoreLink | null {
   if (
     maybeLink != null &&
     typeof maybeLink === 'object' &&
@@ -180,8 +198,8 @@ export function getLink(maybeLink: DataTypeValue): Link | null {
 export function getOrLoadIsographArtifact(
   environment: IsographEnvironment,
   key: string,
-  loader: () => Promise<IsographEntrypoint<any, any>>,
-): PromiseWrapper<IsographEntrypoint<any, any>> {
+  loader: () => Promise<IsographEntrypoint<any, any, any>>,
+): PromiseWrapper<IsographEntrypoint<any, any, any>> {
   const value = environment.entrypointArtifactCache.get(key);
   if (value != null) {
     return value;

package/src/core/PromiseWrapper.ts

@@ -1,9 +1,9 @@
 export type AnyError = any;
 
-const NOT_SET: Symbol = Symbol('NOT_SET');
-type NotSet = typeof NOT_SET;
+export const NOT_SET = Symbol('NOT_SET');
+export type NotSet = typeof NOT_SET;
 
-type Result<T, E> =
+export type Result<T, E> =
   | {
       kind: 'Ok';
       value: T;
@@ -18,31 +18,32 @@ type Result<T, E> =
  * Before the promise is resolved, value becomes non-null.
  */
 export type PromiseWrapper<T, E = any> = {
-  readonly promise: Promise<T>;
+  readonly promise: Promise<Exclude<T, NotSet>>;
   result: Result<Exclude<T, NotSet>, E> | NotSet;
 };
 
-export function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T, any> {
+export function wrapPromise<T>(
+  promise: Promise<Exclude<T, NotSet>>,
+): PromiseWrapper<T, unknown> {
   // TODO confirm suspense works if the promise is already resolved.
   const wrapper: PromiseWrapper<T, any> = { promise, result: NOT_SET };
   promise
     .then((v) => {
-      // v is assignable to Exclude<T, Symbol> | Symbol
-      wrapper.result = { kind: 'Ok', value: v as any };
+      wrapper.result = { kind: 'Ok', value: v };
     })
     .catch((e) => {
-      // e is assignable to Exclude<T, Symbol> | Symbol
-      wrapper.result = { kind: 'Err', error: e as any };
+      wrapper.result = { kind: 'Err', error: e };
     });
   return wrapper;
 }
 
-export function wrapResolvedValue<T>(value: T): PromiseWrapper<T, never> {
+export function wrapResolvedValue<T>(
+  value: Exclude<T, NotSet>,
+): PromiseWrapper<T, never> {
   return {
     promise: Promise.resolve(value),
     result: {
       kind: 'Ok',
-      // @ts-expect-error one should not call wrapResolvedValue with NOT_SET
       value,
     },
   };
@@ -51,8 +52,7 @@ export function wrapResolvedValue<T>(value: T): PromiseWrapper<T, never> {
 export function readPromise<T, E>(p: PromiseWrapper<T, E>): T {
   const { result } = p;
   if (result !== NOT_SET) {
-    // Safety: p.result is either NOT_SET or an actual value.
-    const resultKind = result as Result<T, any>;
+    const resultKind = result;
     if (resultKind.kind === 'Ok') {
       return resultKind.value;
     } else {
@@ -73,11 +73,8 @@ export type PromiseState<T, E> =
 export function getPromiseState<T, E>(
   p: PromiseWrapper<T, E>,
 ): PromiseState<T, E> {
-  const { result } = p;
-  if (result !== NOT_SET) {
-    // Safety: p.result is either NOT_SET or an actual value.
-    const resultKind = result as Result<T, any>;
-    return resultKind;
+  if (p.result !== NOT_SET) {
+    return p.result;
   }
   return {
     kind: 'Pending',

package/src/core/areEqualWithDeepComparison.ts

@@ -1,5 +1,7 @@
+import type { StoreLink } from './IsographEnvironment';
 import type { ReaderAst, ReaderLinkedField, ReaderScalarField } from './reader';
-export function mergeUsingReaderAst(
+
+function mergeUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItem: unknown,
   newItem: unknown,
@@ -38,7 +40,7 @@ export function mergeUsingReaderAst(
   }
 }
 
-export function mergeArraysUsingReaderAst(
+function mergeArraysUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItems: ReadonlyArray<unknown>,
   newItems: Array<unknown>,
@@ -96,6 +98,24 @@ export function mergeObjectsUsingReaderAst(
         }
         break;
       }
+      case 'Link': {
+        const key = field.alias;
+        // @ts-expect-error
+        const oldValue: StoreLink = oldItemObject[key];
+        // @ts-expect-error
+        const newValue: StoreLink = newItemObject[key];
+
+        if (
+          oldValue.__link !== newValue.__link ||
+          oldValue.__typename !== newValue.__typename
+        ) {
+          canRecycle = false;
+        } else {
+          // @ts-expect-error
+          newItemObject[key] = oldValue;
+        }
+        break;
+      }
       case 'ImperativelyLoadedField':
       case 'LoadablySelectedField':
         break;

package/src/core/brand.ts

@@ -0,0 +1,18 @@
+// Suppress the TypeScript compiler warning for this branded-type trick.
+// See discussion: https://github.com/microsoft/TypeScript/issues/202#issuecomment-436900738
+// Pattern: “Brand<BaseType, Brand>” leverages TypeScript conditional and `infer` types to create a pseudo-nominal type,
+// enabling BaseType to be treated as distinct only when tagged with Brand, even though Brand doesn't exist at runtime.
+//
+// Explanation:
+// - Brand extends `symbol | string` acts as a “brand” identifier.
+// - The type uses a conditional check `infer _ extends Brand ? BaseType : never` to strip out BaseType when the branding doesn't match.
+// - This yields a branded type system: `Brand<string, "UserId">` is not accidentally assignable to `Brand<string, "ProductId">`.
+//
+// Usage: Helps enforce semantic distinctions (e.g., distinguishing user IDs from product IDs) even when their runtime values are both strings.
+//
+// Caveat: This is purely a compile-time trick—Brand is erased in emitted JavaScript, so runtime checks must rely on other mechanisms.
+export type Brand<
+  BaseType,
+  Brand extends symbol | string,
+  // @ts-ignore
+> = infer _ extends Brand ? BaseType : never;