@isograph/react 0.0.0-main-0eb53a17 → 0.0.0-main-cddcd660

package/dist/react/FragmentReader.js

@@ -1,35 +1,8 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FragmentReader = FragmentReader;
-const React = __importStar(require("react"));
 const useResult_1 = require("./useResult");
-function FragmentReader(props) {
-    const Component = (0, useResult_1.useResult)(props.fragmentReference, props.networkRequestOptions);
-    // TypeScript is not understanding that if additionalProps is Record<PropertyKey, never>,
-    // it means that TProps === JSX.IntrinsicAttributes.
-    // @ts-expect-error
-    return React.createElement(Component, Object.assign({}, props.additionalProps));
+function FragmentReader({ fragmentReference, networkRequestOptions, children, }) {
+    const result = (0, useResult_1.useResult)(fragmentReference, networkRequestOptions);
+    return children(result);
 }

package/dist/react/FragmentRenderer.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { type ExtractReadFromStore, type IsographEntrypoint } from '../core/entrypoint';
+import { type FragmentReference } from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
+export type IsExactlyIntrinsicAttributes<T> = T extends JSX.IntrinsicAttributes ? JSX.IntrinsicAttributes extends T ? true : false : false;
+export declare function FragmentRenderer<TProps extends Record<any, any>, TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>, any>>(props: IsExactlyIntrinsicAttributes<TProps> extends true ? {
+    fragmentReference: FragmentReference<ExtractReadFromStore<TEntrypoint>, React.FC<TProps>>;
+    additionalProps?: Record<PropertyKey, never>;
+    networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+} : {
+    fragmentReference: FragmentReference<ExtractReadFromStore<TEntrypoint>, React.FC<TProps>>;
+    additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
+    networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+}): React.ReactNode;
+//# sourceMappingURL=FragmentRenderer.d.ts.map

package/dist/react/FragmentRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FragmentRenderer.d.ts","sourceRoot":"","sources":["../../src/react/FragmentRenderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAGhE,MAAM,MAAM,4BAA4B,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,mBAAmB,GAC3E,GAAG,CAAC,mBAAmB,SAAS,CAAC,GAC/B,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEV,wBAAgB,gBAAgB,CAC9B,MAAM,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAC/B,WAAW,SAAS,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAElE,KAAK,EAAE,4BAA4B,CAAC,MAAM,CAAC,SAAS,IAAI,GACpD;IACE,iBAAiB,EAAE,iBAAiB,CAClC,oBAAoB,CAAC,WAAW,CAAC,EACjC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CACjB,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAC7C,qBAAqB,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAC9D,GACD;IACE,iBAAiB,EAAE,iBAAiB,CAClC,oBAAoB,CAAC,WAAW,CAAC,EACjC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CACjB,CAAC;IACF,eAAe,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7D,qBAAqB,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAC9D,GACJ,KAAK,CAAC,SAAS,CASjB"}

package/dist/react/FragmentRenderer.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FragmentRenderer = FragmentRenderer;
+const React = __importStar(require("react"));
+const useResult_1 = require("./useResult");
+function FragmentRenderer(props) {
+    const Component = (0, useResult_1.useResult)(props.fragmentReference, props.networkRequestOptions);
+    // TypeScript is not understanding that if additionalProps is Record<PropertyKey, never>,
+    // it means that TProps === JSX.IntrinsicAttributes.
+    // @ts-expect-error
+    return React.createElement(Component, Object.assign({}, props.additionalProps));
+}

package/dist/react/LoadableFieldReader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LoadableFieldReader.d.ts","sourceRoot":"","sources":["../../src/react/LoadableFieldReader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD,wBAAgB,mBAAmB,CACjC,cAAc,SAAS,qBAAqB,EAC5C,OAAO,EACP,aAAa,SAAS,MAAM,EAC5B,eAAe,EACf,KAAK,EAAE;IACP,aAAa,EAAE,aAAa,CAC1B,cAAc,EACd,OAAO,EACP,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAC7D,CAAC;IAEF,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,qBAAqB,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7D,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,eAAe,CAAC;CAC7C,GAAG,eAAe,CAalB"}
+{"version":3,"file":"LoadableFieldReader.d.ts","sourceRoot":"","sources":["../../src/react/LoadableFieldReader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,wBAAgB,mBAAmB,CACjC,cAAc,SAAS,qBAAqB,EAC5C,OAAO,EACP,aAAa,SAAS,MAAM,EAC5B,eAAe,EACf,KAAK,EAAE;IACP,aAAa,EAAE,aAAa,CAC1B,cAAc,EACd,OAAO,EACP,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAC7D,CAAC;IAEF,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,qBAAqB,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7D,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,eAAe,CAAC;CAC7C,GAAG,eAAe,CAalB"}

package/dist/react/LoadableFieldReader.js

@@ -3,9 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LoadableFieldReader = LoadableFieldReader;
 const useClientSideDefer_1 = require("../loadable-hooks/useClientSideDefer");
 const useResult_1 = require("./useResult");
-// TODO
-// - LoadableFieldRenderer, which works for @loadable fields that are components,
-//   i.e. just renders the resulting component
 function LoadableFieldReader(props) {
     const { fragmentReference } = (0, useClientSideDefer_1.useClientSideDefer)(props.loadableField, props.args, props.fetchOptions);
     const readOutFragmentData = (0, useResult_1.useResult)(fragmentReference, props.networkRequestOptions);

package/dist/react/LoadableFieldRenderer.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { type FetchOptions } from '../core/check';
+import { ExtractParameters, type UnknownTReadFromStore } from '../core/FragmentReference';
+import { type NetworkRequestReaderOptions } from '../core/read';
+import { type LoadableField } from '../core/reader';
+export declare function LoadableFieldRenderer<TReadFromStore extends UnknownTReadFromStore, TProvidedArgs extends object, TChildrenResult, TProps>(props: {
+    loadableField: LoadableField<TReadFromStore, React.FC<TProps>, Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>>;
+    args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>;
+    fetchOptions?: FetchOptions<React.FC<TProps>>;
+    networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+    additionalProps: Omit<TProps, keyof JSX.IntrinsicAttributes>;
+}): TChildrenResult;
+//# sourceMappingURL=LoadableFieldRenderer.d.ts.map

package/dist/react/LoadableFieldRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadableFieldRenderer.d.ts","sourceRoot":"","sources":["../../src/react/LoadableFieldRenderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,wBAAgB,qBAAqB,CACnC,cAAc,SAAS,qBAAqB,EAC5C,aAAa,SAAS,MAAM,EAC5B,eAAe,EACf,MAAM,EACN,KAAK,EAAE;IACP,aAAa,EAAE,aAAa,CAC1B,cAAc,EACd,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,EAChB,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAC7D,CAAC;IAEF,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,qBAAqB,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7D,eAAe,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,mBAAmB,CAAC,CAAC;CAC9D,GAAG,eAAe,CAalB"}

package/dist/react/LoadableFieldRenderer.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoadableFieldRenderer = LoadableFieldRenderer;
+const React = __importStar(require("react"));
+const useClientSideDefer_1 = require("../loadable-hooks/useClientSideDefer");
+const useResult_1 = require("./useResult");
+function LoadableFieldRenderer(props) {
+    const { fragmentReference } = (0, useClientSideDefer_1.useClientSideDefer)(props.loadableField, props.args, props.fetchOptions);
+    const Component = (0, useResult_1.useResult)(fragmentReference, props.networkRequestOptions);
+    // TODO we probably can figure out a way to convince TypeScript of
+    // the validity of this.
+    // @ts-expect-error
+    return React.createElement(Component, Object.assign({}, props.additionalProps));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.0.0-main-0eb53a17",
+  "version": "0.0.0-main-cddcd660",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -19,9 +19,9 @@
     "iso": "cross-env ISO_PRINT_ABSOLUTE_FILEPATH=1 ../../target/debug/isograph_cli --config ./isograph.config.json"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-0eb53a17",
-    "@isograph/react-disposable-state": "0.0.0-main-0eb53a17",
-    "@isograph/reference-counted-pointer": "0.0.0-main-0eb53a17"
+    "@isograph/disposable-types": "0.0.0-main-cddcd660",
+    "@isograph/react-disposable-state": "0.0.0-main-cddcd660",
+    "@isograph/reference-counted-pointer": "0.0.0-main-cddcd660"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"

package/src/core/FragmentReference.ts

@@ -1,6 +1,6 @@
 import { ReaderWithRefetchQueries } from '../core/entrypoint';
 import { stableCopy } from './cache';
-import { type Link } from './IsographEnvironment';
+import { type StoreLink } from './IsographEnvironment';
 import { PromiseWrapper } from './PromiseWrapper';
 import type { StartUpdate } from './reader';
 
@@ -52,7 +52,7 @@ export type 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

package/src/core/IsographEnvironment.ts

@@ -15,6 +15,7 @@ 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;
@@ -38,7 +39,7 @@ export type FragmentSubscription<TReadFromStore extends UnknownTReadFromStore> =
 export type AnyChangesToRecordSubscription = {
   readonly kind: 'AnyChangesToRecord';
   readonly callback: () => void;
-  readonly recordLink: Link;
+  readonly recordLink: StoreLink;
 };
 
 export type AnyRecordSubscription = {
@@ -77,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 = (
   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;
 };
@@ -103,7 +109,7 @@ export type DataTypeValue =
   | string
   | null
   // Singular linked fields:
-  | Link
+  | StoreLink
   // Plural scalar and linked fields:
   | DataTypeValue[];
 
@@ -162,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');
   }
@@ -175,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' &&

package/src/core/areEqualWithDeepComparison.ts

@@ -1,7 +1,7 @@
-import type { Link } from './IsographEnvironment';
+import type { StoreLink } from './IsographEnvironment';
 import type { ReaderAst, ReaderLinkedField, ReaderScalarField } from './reader';
 
-export function mergeUsingReaderAst(
+function mergeUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItem: unknown,
   newItem: unknown,
@@ -40,7 +40,7 @@ export function mergeUsingReaderAst(
   }
 }
 
-export function mergeArraysUsingReaderAst(
+function mergeArraysUsingReaderAst(
   field: ReaderScalarField | ReaderLinkedField,
   oldItems: ReadonlyArray<unknown>,
   newItems: Array<unknown>,
@@ -101,9 +101,9 @@ export function mergeObjectsUsingReaderAst(
       case 'Link': {
         const key = field.alias;
         // @ts-expect-error
-        const oldValue: Link = oldItemObject[key];
+        const oldValue: StoreLink = oldItemObject[key];
         // @ts-expect-error
-        const newValue: Link = newItemObject[key];
+        const newValue: StoreLink = newItemObject[key];
 
         if (
           oldValue.__link !== newValue.__link ||

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;

package/src/core/cache.ts

@@ -26,8 +26,8 @@ import {
   DataTypeValue,
   FragmentSubscription,
   getLink,
-  Link,
   ROOT_ID,
+  StoreLink,
   StoreRecord,
   type IsographEnvironment,
   type TypeName,
@@ -157,7 +157,7 @@ export function normalizeData(
   normalizationAst: NormalizationAstNodes,
   networkResponse: NetworkResponseObject,
   variables: Variables,
-  root: Link,
+  root: StoreLink,
 ): EncounteredIds {
   const encounteredIds: EncounteredIds = new Map();
 
@@ -205,7 +205,7 @@ export function subscribeToAnyChange(
 
 export function subscribeToAnyChangesToRecord(
   environment: IsographEnvironment,
-  recordLink: Link,
+  recordLink: StoreLink,
   callback: () => void,
 ): () => void {
   const subscription = {
@@ -240,7 +240,7 @@ export function subscribe<TReadFromStore extends UnknownTReadFromStore>(
 
 export function onNextChangeToRecord(
   environment: IsographEnvironment,
-  recordLink: Link,
+  recordLink: StoreLink,
 ): Promise<void> {
   return new Promise((resolve) => {
     const unsubscribe = subscribeToAnyChangesToRecord(
@@ -259,11 +259,19 @@ export function onNextChangeToRecord(
 //
 // That's probably okay to ignore. We don't, however, want to prevent
 // updating other subscriptions if one subscription had missing data.
-function withErrorHandling<T>(f: (t: T) => void): (t: T) => void {
+function withErrorHandling<T>(
+  environment: IsographEnvironment,
+  f: (t: T) => void,
+): (t: T) => void {
   return (t) => {
     try {
       return f(t);
-    } catch {}
+    } catch (e) {
+      logMessage(environment, () => ({
+        kind: 'ErrorEncounteredInWithErrorHandling',
+        error: e,
+      }));
+    }
   };
 }
 
@@ -272,7 +280,7 @@ export function callSubscriptions(
   recordsEncounteredWhenNormalizing: EncounteredIds,
 ) {
   environment.subscriptions.forEach(
-    withErrorHandling((subscription) => {
+    withErrorHandling(environment, (subscription) => {
       switch (subscription.kind) {
         case 'FragmentSubscription': {
           // TODO if there are multiple components subscribed to the same
@@ -387,7 +395,7 @@ function normalizeDataIntoRecord(
   normalizationAst: NormalizationAstNodes,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
@@ -492,7 +500,7 @@ function normalizeLinkedField(
   astNode: NormalizationLinkedField,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
@@ -517,7 +525,7 @@ function normalizeLinkedField(
 
   if (Array.isArray(networkResponseData)) {
     // TODO check astNode.plural or the like
-    const dataIds: (Link | null)[] = [];
+    const dataIds: (StoreLink | null)[] = [];
     for (let i = 0; i < networkResponseData.length; i++) {
       const networkResponseObject = networkResponseData[i];
       if (networkResponseObject == null) {
@@ -588,7 +596,7 @@ function normalizeInlineFragment(
   astNode: NormalizationInlineFragment,
   networkResponseParentRecord: NetworkResponseObject,
   targetParentRecord: StoreRecord,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
   mutableEncounteredIds: EncounteredIds,
 ): RecordHasBeenUpdated {
@@ -610,7 +618,7 @@ function normalizeInlineFragment(
 
 function dataIdsAreTheSame(
   existingValue: DataTypeValue,
-  newDataIds: (Link | null)[],
+  newDataIds: (StoreLink | null)[],
 ): boolean {
   if (Array.isArray(existingValue)) {
     if (newDataIds.length !== existingValue.length) {
@@ -635,7 +643,7 @@ function normalizeNetworkResponseObject(
   environment: IsographEnvironment,
   astNode: NormalizationLinkedField,
   networkResponseData: NetworkResponseObject,
-  targetParentRecordLink: Link,
+  targetParentRecordLink: StoreLink,
   variables: Variables,
   index: number | null,
   mutableEncounteredIds: EncounteredIds,
@@ -830,7 +838,7 @@ export const THIRD_SPLIT_KEY = '__';
 
 // Returns a key to look up an item in the store
 function getDataIdOfNetworkResponse(
-  parentRecordLink: Link,
+  parentRecordLink: StoreLink,
   dataToNormalize: NetworkResponseObject,
   astNode: NormalizationLinkedField,
   variables: Variables,

package/src/core/check.ts

@@ -4,7 +4,7 @@ import { Variables } from './FragmentReference';
 import {
   getLink,
   IsographEnvironment,
-  Link,
+  StoreLink,
   StoreRecord,
 } from './IsographEnvironment';
 import { logMessage } from './logging';
@@ -30,14 +30,14 @@ export type CheckResult =
     }
   | {
       kind: 'MissingData';
-      record: Link;
+      record: StoreLink;
     };
 
 export function check(
   environment: IsographEnvironment,
   normalizationAst: NormalizationAstNodes,
   variables: Variables,
-  root: Link,
+  root: StoreLink,
 ): CheckResult {
   const recordsById = (environment.store[root.__typename] ??= {});
   const newStoreRecord = (recordsById[root.__link] ??= {});
@@ -61,7 +61,7 @@ function checkFromRecord(
   normalizationAst: NormalizationAstNodes,
   variables: Variables,
   record: StoreRecord,
-  recordLink: Link,
+  recordLink: StoreLink,
 ): CheckResult {
   normalizationAstLoop: for (const normalizationAstNode of normalizationAst) {
     switch (normalizationAstNode.kind) {

package/src/core/garbageCollection.ts

@@ -7,14 +7,14 @@ import {
   IsographEnvironment,
   IsographStore,
   StoreRecord,
-  type Link,
+  type StoreLink,
   type TypeName,
 } from './IsographEnvironment';
 
 export type RetainedQuery = {
   readonly normalizationAst: NormalizationAstNodes;
   readonly variables: {};
-  readonly root: Link;
+  readonly root: StoreLink;
 };
 
 export type DidUnretainSomeQuery = boolean;
@@ -117,7 +117,7 @@ function recordReachableIdsFromRecord(
         const linkKey = getParentRecordKey(selection, variables ?? {});
         const linkedFieldOrFields = currentRecord[linkKey];
 
-        const links: Link[] = [];
+        const links: StoreLink[] = [];
         if (Array.isArray(linkedFieldOrFields)) {
           for (const maybeLink of linkedFieldOrFields) {
             const link = assertLink(maybeLink);

package/src/core/logging.ts

@@ -11,7 +11,7 @@ import {
   IsographEnvironment,
   IsographStore,
   StoreRecord,
-  type Link,
+  type StoreLink,
 } from './IsographEnvironment';
 import { ReadDataResult } from './read';
 import { Arguments } from './util';
@@ -38,7 +38,7 @@ export type LogMessage =
   | {
       kind: 'ComponentRerendered';
       componentName: string;
-      rootLink: Link;
+      rootLink: StoreLink;
     }
   | {
       kind: 'MakeNetworkRequest';
@@ -61,7 +61,7 @@ export type LogMessage =
     }
   | {
       kind: 'MissingFieldHandlerCalled';
-      root: Link;
+      root: StoreLink;
       storeRecord: StoreRecord;
       fieldName: string;
       arguments: Arguments | null;
@@ -71,7 +71,7 @@ export type LogMessage =
       kind: 'DoneReading';
       response: ReadDataResult<any>;
       fieldName: string;
-      root: Link;
+      root: StoreLink;
     }
   | {
       kind: 'NonEntrypointReceived';
@@ -83,6 +83,18 @@ export type LogMessage =
     }
   | {
       kind: 'EnvironmentCreated';
+    }
+  | {
+      kind: 'StartUpdateError';
+      error: any;
+    }
+  | {
+      kind: 'StartUpdateComplete';
+      updatedIds: EncounteredIds;
+    }
+  | {
+      kind: 'ErrorEncounteredInWithErrorHandling';
+      error: any;
     };
 
 export type LogFunction = (logMessage: LogMessage) => void;

package/src/core/makeNetworkRequest.ts

@@ -20,7 +20,7 @@ import {
   retainQuery,
   unretainQuery,
 } from './garbageCollection';
-import { IsographEnvironment, Link, ROOT_ID } from './IsographEnvironment';
+import { IsographEnvironment, ROOT_ID, StoreLink } from './IsographEnvironment';
 import { logMessage } from './logging';
 import {
   AnyError,
@@ -260,7 +260,7 @@ function readDataForOnComplete<
 >(
   artifact: TArtifact,
   environment: IsographEnvironment,
-  root: Link,
+  root: StoreLink,
   variables: ExtractParameters<TReadFromStore>,
   readerWithRefetchQueries:
     | ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>