@isograph/react 0.4.3 → 0.5.0

package/package.json

@@ -1,27 +1,16 @@
 {
   "name": "@isograph/react",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Isograph Labs",
   "license": "MIT",
-  "scripts": {
-    "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-libs",
-    "tsc": "tsc",
-    "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": "*",
-    "@isograph/react-disposable-state": "*",
-    "@isograph/reference-counted-pointer": "*"
+    "@isograph/disposable-types": "0.5.0",
+    "@isograph/react-disposable-state": "0.5.0",
+    "@isograph/reference-counted-pointer": "0.5.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -39,5 +28,15 @@
     "url": "git+https://github.com/isographlabs/isograph.git",
     "directory": "libs/isograph-react"
   },
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "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",
+    "tsc": "tsc",
+    "tsc-force": "tsc --build --clean && tsc --build --force",
+    "iso": "cross-env ISO_PRINT_ABSOLUTE_FILEPATH=1 ../../target/debug/isograph_cli --config ./isograph.config.json"
+  }
+}

package/src/core/FragmentReference.ts

@@ -1,6 +1,9 @@
 import { ReaderWithRefetchQueries } from '../core/entrypoint';
 import { stableCopy } from './cache';
-import { type StoreLink } from './IsographEnvironment';
+import {
+  type ComponentOrFieldName,
+  type StoreLink,
+} from './IsographEnvironment';
 import { PromiseWrapper } from './PromiseWrapper';
 import type { StartUpdate } from './reader';
 
@@ -53,8 +56,12 @@ export type FragmentReference<
     ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
   >;
   readonly root: StoreLink;
+  readonly fieldName: ComponentOrFieldName;
+  readonly readerArtifactKind:
+    | 'EagerReaderArtifact'
+    | 'ComponentReaderArtifact';
   // TODO we potentially stably copy and stringify variables a lot!
-  // So, we should employ interior mutability: pretend that fragent reference
+  // So, we should employ interior mutability: pretend that fragment reference
   // is immutable, but actually store something like
   // `Map<Variable, StablyCopiedStringifiedOutput>`
   // and read or update that map when we would otherwise stably copy and
@@ -67,7 +74,6 @@ export type StableIdForFragmentReference = string;
 
 export function stableIdForFragmentReference(
   fragmentReference: FragmentReference<any, any>,
-  fieldName: string,
 ): StableIdForFragmentReference {
-  return `${fragmentReference.root.__typename}/${fragmentReference.root.__link}/${fieldName}/${JSON.stringify(stableCopy(fragmentReference.variables))}`;
+  return `${fragmentReference.root.__typename}/${fragmentReference.root.__link}/${fragmentReference.fieldName}/${JSON.stringify(stableCopy(fragmentReference.variables))}`;
 }

package/src/core/IsographEnvironment.ts

@@ -1,8 +1,12 @@
 import { ParentCache } from '@isograph/react-disposable-state';
+import type { Brand } from './brand';
+import { isArray } from './cache';
 import {
   IsographEntrypoint,
   IsographOperation,
   IsographPersistedOperation,
+  type ReaderWithRefetchQueries,
+  type ReaderWithRefetchQueriesLoader,
 } from './entrypoint';
 import {
   FragmentReference,
@@ -10,12 +14,16 @@ import {
   type StableIdForFragmentReference,
   type UnknownTReadFromStore,
 } from './FragmentReference';
-import { RetainedQuery } from './garbageCollection';
+import type { RetainedQuery } from './garbageCollection';
 import { LogFunction, WrappedLogFunction } from './logging';
-import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
+import { type StoreLayer } from './optimisticProxy';
+import {
+  PromiseWrapper,
+  wrapPromise,
+  wrapResolvedValue,
+} 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;
@@ -56,7 +64,7 @@ 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 missingFieldHandler: MissingFieldHandler | null;
   readonly componentCache: FieldCache<React.FC<any>>;
@@ -68,7 +76,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>;
@@ -111,7 +119,7 @@ export type DataTypeValue =
   // Singular linked fields:
   | StoreLink
   // Plural scalar and linked fields:
-  | DataTypeValue[];
+  | readonly DataTypeValue[];
 
 export type StoreRecord = {
   [index: DataId | string]: DataTypeValue;
@@ -125,18 +133,21 @@ 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,
+  baseStoreLayerData: BaseStoreLayerData,
   networkFunction: IsographNetworkFunction,
   missingFieldHandler?: MissingFieldHandler | null,
   logFunction?: LogFunction | null,
@@ -144,6 +155,12 @@ export function createIsographEnvironment(
   logFunction?.({
     kind: 'EnvironmentCreated',
   });
+  let store = {
+    kind: 'BaseStoreLayer',
+    data: baseStoreLayerData,
+    parentStoreLayer: null,
+    childStoreLayer: null,
+  } as const;
   return {
     store,
     networkFunction,
@@ -160,7 +177,7 @@ export function createIsographEnvironment(
   };
 }
 
-export function createIsographStore(): IsographStore {
+export function createIsographStore(): BaseStoreLayerData {
   return {
     Query: {
       [ROOT_ID]: {},
@@ -169,7 +186,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 +215,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 +225,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/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;