@isograph/react 0.0.0-main-5da1ab92 → 0.0.0-main-6bd3135f

package/dist/core/IsographEnvironment.d.ts

@@ -5,6 +5,7 @@ import { FragmentReference, Variables } from './FragmentReference';
 import { PromiseWrapper } from './PromiseWrapper';
 import { IsographEntrypoint } from './entrypoint';
 import type { ReaderAst } from './reader';
+import { LogFunction, WrappedLogFunction } from './logging';
 export type ComponentOrFieldName = string;
 export type StringifiedArgs = string;
 type ComponentCache = {
@@ -53,6 +54,7 @@ export type IsographEnvironment = {
     readonly retainedQueries: Set<RetainedQuery>;
     readonly gcBuffer: Array<RetainedQuery>;
     readonly gcBufferSize: number;
+    readonly loggers: Set<WrappedLogFunction>;
 };
 export type MissingFieldHandler = (storeRecord: StoreRecord, root: DataId, fieldName: string, arguments_: {
     [index: string]: any;
@@ -73,7 +75,7 @@ export type IsographStore = {
     [index: DataId]: StoreRecord | null;
     readonly __ROOT: StoreRecord;
 };
-export declare function createIsographEnvironment(store: IsographStore, networkFunction: IsographNetworkFunction, missingFieldHandler?: MissingFieldHandler): IsographEnvironment;
+export declare function createIsographEnvironment(store: IsographStore, networkFunction: IsographNetworkFunction, missingFieldHandler?: MissingFieldHandler | null, logFunction?: LogFunction | null): IsographEnvironment;
 export declare function createIsographStore(): IsographStore;
 export declare function defaultMissingFieldHandler(_storeRecord: StoreRecord, _root: DataId, fieldName: string, arguments_: {
     [index: string]: any;

package/dist/core/IsographEnvironment.js

@@ -10,7 +10,7 @@ exports.getOrLoadIsographArtifact = getOrLoadIsographArtifact;
 const PromiseWrapper_1 = require("./PromiseWrapper");
 exports.ROOT_ID = '__ROOT';
 const DEFAULT_GC_BUFFER_SIZE = 10;
-function createIsographEnvironment(store, networkFunction, missingFieldHandler) {
+function createIsographEnvironment(store, networkFunction, missingFieldHandler, logFunction) {
     return {
         store,
         networkFunction,
@@ -22,6 +22,7 @@ function createIsographEnvironment(store, networkFunction, missingFieldHandler)
         retainedQueries: new Set(),
         gcBuffer: [],
         gcBufferSize: DEFAULT_GC_BUFFER_SIZE,
+        loggers: logFunction != null ? new Set([{ log: logFunction }]) : new Set(),
     };
 }
 function createIsographStore() {

package/dist/core/cache.d.ts

@@ -20,7 +20,7 @@ export declare function getOrCreateCacheForArtifact<TReadFromStore extends {
 }, TClientFieldValue>(environment: IsographEnvironment, entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: ExtractParameters<TReadFromStore>): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>>;
 type NetworkResponseScalarValue = string | number | boolean;
 type NetworkResponseValue = NetworkResponseScalarValue | null | NetworkResponseObject | NetworkResponseObject[] | NetworkResponseScalarValue[];
-type NetworkResponseObject = {
+export type NetworkResponseObject = {
     [index: string]: undefined | NetworkResponseValue;
     id?: DataId;
 };

package/dist/core/cache.js

@@ -16,16 +16,16 @@ const read_1 = require("./read");
 const areEqualWithDeepComparison_1 = require("./areEqualWithDeepComparison");
 const makeNetworkRequest_1 = require("./makeNetworkRequest");
 const PromiseWrapper_1 = require("./PromiseWrapper");
+const logging_1 = require("./logging");
 const TYPENAME_FIELD_NAME = '__typename';
 function getOrCreateItemInSuspenseCache(environment, index, factory) {
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('getting cache for', {
-            index,
-            cache: Object.keys(environment.fragmentCache),
-            found: !!environment.fragmentCache[index],
-        });
-    }
+    // TODO this is probably a useless message, we should remove it
+    (0, logging_1.logMessage)(environment, {
+        kind: 'GettingSuspenseCacheItem',
+        index,
+        availableCacheItems: Object.keys(environment.fragmentCache),
+        found: !!environment.fragmentCache[index],
+    });
     if (environment.fragmentCache[index] == null) {
         environment.fragmentCache[index] = new react_disposable_state_1.ParentCache(factory);
     }
@@ -76,19 +76,18 @@ function getOrCreateCacheForArtifact(environment, entrypoint, variables) {
 }
 function normalizeData(environment, normalizationAst, networkResponse, variables, nestedRefetchQueries) {
     const encounteredIds = new Set();
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('about to normalize', normalizationAst, networkResponse, variables);
-    }
+    (0, logging_1.logMessage)(environment, {
+        kind: 'AboutToNormalize',
+        normalizationAst,
+        networkResponse,
+        variables,
+    });
     normalizeDataIntoRecord(environment, normalizationAst, networkResponse, environment.store.__ROOT, IsographEnvironment_1.ROOT_ID, variables, nestedRefetchQueries, encounteredIds);
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('after normalization', {
-            store: environment.store,
-            encounteredIds,
-            environment,
-        });
-    }
+    (0, logging_1.logMessage)(environment, {
+        kind: 'AfterNormalization',
+        store: environment.store,
+        encounteredIds,
+    });
     callSubscriptions(environment, encounteredIds);
     return encounteredIds;
 }
@@ -168,26 +167,16 @@ function callSubscriptions(environment, recordsEncounteredWhenNormalizing) {
                         throwOnNetworkError: false,
                     });
                     const mergedItem = (0, areEqualWithDeepComparison_1.mergeObjectsUsingReaderAst)(subscription.readerAst, subscription.encounteredDataAndRecords.item, newEncounteredDataAndRecords.item);
+                    (0, logging_1.logMessage)(environment, {
+                        kind: 'DeepEqualityCheck',
+                        fragmentReference: subscription.fragmentReference,
+                        old: subscription.encounteredDataAndRecords.item,
+                        new: newEncounteredDataAndRecords.item,
+                        deeplyEqual: mergedItem === subscription.encounteredDataAndRecords.item,
+                    });
                     if (mergedItem !== subscription.encounteredDataAndRecords.item) {
-                        // @ts-expect-error
-                        if (typeof window !== 'undefined' && window.__LOG) {
-                            console.log('Deep equality - No', {
-                                fragmentReference: subscription.fragmentReference,
-                                old: subscription.encounteredDataAndRecords.item,
-                                new: newEncounteredDataAndRecords.item,
-                            });
-                        }
                         subscription.callback(newEncounteredDataAndRecords);
                     }
-                    else {
-                        // @ts-expect-error
-                        if (typeof window !== 'undefined' && window.__LOG) {
-                            console.log('Deep equality - Yes', {
-                                fragmentReference: subscription.fragmentReference,
-                                old: subscription.encounteredDataAndRecords.item,
-                            });
-                        }
-                    }
                 }
                 return;
             }

package/dist/core/componentCache.js

@@ -4,6 +4,7 @@ exports.getOrCreateCachedComponent = getOrCreateCachedComponent;
 const cache_1 = require("./cache");
 const useReadAndSubscribe_1 = require("../react/useReadAndSubscribe");
 const PromiseWrapper_1 = require("./PromiseWrapper");
+const logging_1 = require("./logging");
 function getOrCreateCachedComponent(environment, componentName, fragmentReference, networkRequestOptions) {
     var _a, _b, _c;
     // cachedComponentsById is a three layer cache: id, then component name, then
@@ -21,13 +22,11 @@ function getOrCreateCachedComponent(environment, componentName, fragmentReferenc
             function Component(additionalRuntimeProps) {
                 const readerWithRefetchQueries = (0, PromiseWrapper_1.readPromise)(fragmentReference.readerWithRefetchQueries);
                 const data = (0, useReadAndSubscribe_1.useReadAndSubscribe)(fragmentReference, networkRequestOptions, readerWithRefetchQueries.readerArtifact.readerAst);
-                // @ts-expect-error
-                if (typeof window !== 'undefined' && window.__LOG) {
-                    console.log('Component re-rendered: ' +
-                        componentName +
-                        ' ' +
-                        fragmentReference.root);
-                }
+                (0, logging_1.logMessage)(environment, {
+                    kind: 'ComponentRerendered',
+                    componentName,
+                    rootId: fragmentReference.root,
+                });
                 const firstParameter = {
                     data,
                     parameters: fragmentReference.variables,

package/dist/core/logging.d.ts

@@ -0,0 +1,60 @@
+import { CleanupFn } from '@isograph/disposable-types';
+import { DataId, IsographEnvironment, IsographStore, StoreRecord } from './IsographEnvironment';
+import { IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArtifact } from './entrypoint';
+import { FragmentReference, Variables } from './FragmentReference';
+import { NetworkResponseObject } from './cache';
+import { Arguments } from './util';
+import { ReadDataResult } from './read';
+export type LogMessage = {
+    kind: 'GettingSuspenseCacheItem';
+    index: string;
+    availableCacheItems: ReadonlyArray<string>;
+    found: boolean;
+} | {
+    kind: 'AboutToNormalize';
+    normalizationAst: NormalizationAst;
+    networkResponse: NetworkResponseObject;
+    variables: Variables;
+} | {
+    kind: 'AfterNormalization';
+    store: IsographStore;
+    encounteredIds: Set<string>;
+} | {
+    kind: 'DeepEqualityCheck';
+    fragmentReference: FragmentReference<any, any>;
+    old: object;
+    new: object;
+    deeplyEqual: boolean;
+} | {
+    kind: 'ComponentRerendered';
+    componentName: string;
+    rootId: DataId;
+} | {
+    kind: 'MakeNetworkRequest';
+    artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>;
+    variables: Variables;
+    networkRequestId: string;
+} | {
+    kind: 'ReceivedNetworkResponse';
+    networkResponse: any;
+    networkRequestId: string;
+} | {
+    kind: 'MissingFieldHandlerCalled';
+    root: DataId;
+    storeRecord: StoreRecord;
+    fieldName: string;
+    arguments: Arguments | null;
+    variables: Variables;
+} | {
+    kind: 'DoneReading';
+    response: ReadDataResult<any>;
+} | {
+    kind: 'NonEntrypointReceived';
+    entrypoint: any;
+};
+export type LogFunction = (logMessage: LogMessage) => void;
+export type WrappedLogFunction = {
+    log: LogFunction;
+};
+export declare function logMessage(environment: IsographEnvironment, message: LogMessage): void;
+export declare function registerLogger(environment: IsographEnvironment, log: LogFunction): CleanupFn;

package/dist/core/logging.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logMessage = logMessage;
+exports.registerLogger = registerLogger;
+function logMessage(environment, message) {
+    for (const logger of environment.loggers) {
+        try {
+            logger.log(message);
+        }
+        catch (_a) { }
+    }
+}
+function registerLogger(environment, log) {
+    const wrapped = { log };
+    environment.loggers.add(wrapped);
+    return () => {
+        environment.loggers.delete(wrapped);
+    };
+}

package/dist/core/makeNetworkRequest.js

@@ -4,11 +4,18 @@ exports.makeNetworkRequest = makeNetworkRequest;
 const garbageCollection_1 = require("./garbageCollection");
 const PromiseWrapper_1 = require("./PromiseWrapper");
 const cache_1 = require("./cache");
+const logging_1 = require("./logging");
+let networkRequestId = 0;
 function makeNetworkRequest(environment, artifact, variables) {
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('make network request', artifact, variables);
-    }
+    // TODO this should be a DataId and stored in the store
+    const myNetworkRequestId = networkRequestId + '';
+    networkRequestId++;
+    (0, logging_1.logMessage)(environment, {
+        kind: 'MakeNetworkRequest',
+        artifact,
+        variables,
+        networkRequestId: myNetworkRequestId,
+    });
     let status = {
         kind: 'UndisposedIncomplete',
     };
@@ -17,10 +24,11 @@ function makeNetworkRequest(environment, artifact, variables) {
         .networkFunction(artifact.queryText, variables)
         .then((networkResponse) => {
         var _a;
-        // @ts-expect-error
-        if (typeof window !== 'undefined' && window.__LOG) {
-            console.log('network response', artifact, networkResponse);
-        }
+        (0, logging_1.logMessage)(environment, {
+            kind: 'ReceivedNetworkResponse',
+            networkResponse,
+            networkRequestId: myNetworkRequestId,
+        });
         if (networkResponse.errors != null) {
             // @ts-expect-error Why are we getting the wrong constructor here?
             throw new Error('GraphQL network response had errors', {

package/dist/core/read.d.ts

@@ -8,6 +8,16 @@ export declare function readButDoNotEvaluate<TReadFromStore extends {
     parameters: object;
     data: object;
 }>(environment: IsographEnvironment, fragmentReference: FragmentReference<TReadFromStore, unknown>, networkRequestOptions: NetworkRequestReaderOptions): WithEncounteredRecords<TReadFromStore>;
+export type ReadDataResult<TReadFromStore> = {
+    readonly kind: 'Success';
+    readonly data: ExtractData<TReadFromStore>;
+    readonly encounteredRecords: Set<DataId>;
+} | {
+    readonly kind: 'MissingData';
+    readonly reason: string;
+    readonly nestedReason?: ReadDataResult<unknown>;
+    readonly recordId: DataId;
+};
 export type NetworkRequestReaderOptions = {
     suspendIfInFlight: boolean;
     throwOnNetworkError: boolean;

package/dist/core/read.js

@@ -7,15 +7,16 @@ const componentCache_1 = require("./componentCache");
 const IsographEnvironment_1 = require("./IsographEnvironment");
 const makeNetworkRequest_1 = require("./makeNetworkRequest");
 const PromiseWrapper_1 = require("./PromiseWrapper");
+const logging_1 = require("./logging");
 function readButDoNotEvaluate(environment, fragmentReference, networkRequestOptions) {
     var _a;
     const mutableEncounteredRecords = new Set();
     const readerWithRefetchQueries = (0, PromiseWrapper_1.readPromise)(fragmentReference.readerWithRefetchQueries);
     const response = readData(environment, readerWithRefetchQueries.readerArtifact.readerAst, fragmentReference.root, (_a = fragmentReference.variables) !== null && _a !== void 0 ? _a : {}, readerWithRefetchQueries.nestedRefetchQueries, fragmentReference.networkRequest, networkRequestOptions, mutableEncounteredRecords);
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('done reading: ' + response.kind, { response });
-    }
+    (0, logging_1.logMessage)(environment, {
+        kind: 'DoneReading',
+        response,
+    });
     if (response.kind === 'MissingData') {
         // There are two cases here that we care about:
         // 1. the network request is in flight, we haven't suspend on it, and we want
@@ -126,6 +127,14 @@ function readData(environment, ast, root, variables, nestedRefetchQueries, netwo
                     // TODO make this configurable, and also generated and derived from the schema
                     const missingFieldHandler = (_c = environment.missingFieldHandler) !== null && _c !== void 0 ? _c : IsographEnvironment_1.defaultMissingFieldHandler;
                     const altLink = missingFieldHandler(storeRecord, root, field.fieldName, field.arguments, variables);
+                    (0, logging_1.logMessage)(environment, {
+                        kind: 'MissingFieldHandlerCalled',
+                        root,
+                        storeRecord,
+                        fieldName: field.fieldName,
+                        arguments: field.arguments,
+                        variables,
+                    });
                     if (altLink === undefined) {
                         return {
                             kind: 'MissingData',

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { type NormalizationAst, type NormalizationAstNode, type NormalizationLin
 export { readButDoNotEvaluate } from './core/read';
 export { type ExtractSecondParam, type Argument, type ArgumentName, type ArgumentValue, type Arguments, } from './core/util';
 export { type FragmentReference, type Variables, type ExtractParameters, type ExtractData, stableIdForFragmentReference, } from './core/FragmentReference';
+export { type LogMessage, type LogFunction, logMessage, registerLogger, } from './core/logging';
 export { IsographEnvironmentProvider, useIsographEnvironment, type IsographEnvironmentProviderProps, } from './react/IsographEnvironmentProvider';
 export { useImperativeReference } from './react/useImperativeReference';
 export { FragmentReader } from './react/FragmentReader';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useImperativeLoadableField = exports.useConnectionSpecPagination = exports.useSkipLimitPagination = exports.useImperativeExposedMutationField = exports.useClientSideDefer = exports.RenderAfterCommit__DO_NOT_USE = exports.useRerenderOnChange = exports.useLazyReference = exports.useSubscribeToMultiple = exports.useReadAndSubscribe = exports.useResult = exports.FragmentReader = exports.useImperativeReference = exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.stableIdForFragmentReference = exports.readButDoNotEvaluate = exports.assertIsEntrypoint = exports.defaultMissingFieldHandler = exports.createIsographStore = exports.createIsographEnvironment = exports.ROOT_ID = exports.makeNetworkRequest = exports.normalizeData = exports.subscribe = exports.wrapPromise = exports.wrapResolvedValue = exports.getPromiseState = exports.readPromise = exports.garbageCollectEnvironment = exports.unretainQuery = exports.retainQuery = void 0;
+exports.useImperativeLoadableField = exports.useConnectionSpecPagination = exports.useSkipLimitPagination = exports.useImperativeExposedMutationField = exports.useClientSideDefer = exports.RenderAfterCommit__DO_NOT_USE = exports.useRerenderOnChange = exports.useLazyReference = exports.useSubscribeToMultiple = exports.useReadAndSubscribe = exports.useResult = exports.FragmentReader = exports.useImperativeReference = exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.registerLogger = exports.logMessage = exports.stableIdForFragmentReference = exports.readButDoNotEvaluate = exports.assertIsEntrypoint = exports.defaultMissingFieldHandler = exports.createIsographStore = exports.createIsographEnvironment = exports.ROOT_ID = exports.makeNetworkRequest = exports.normalizeData = exports.subscribe = exports.wrapPromise = exports.wrapResolvedValue = exports.getPromiseState = exports.readPromise = exports.garbageCollectEnvironment = exports.unretainQuery = exports.retainQuery = void 0;
 var garbageCollection_1 = require("./core/garbageCollection");
 Object.defineProperty(exports, "retainQuery", { enumerable: true, get: function () { return garbageCollection_1.retainQuery; } });
 Object.defineProperty(exports, "unretainQuery", { enumerable: true, get: function () { return garbageCollection_1.unretainQuery; } });
@@ -26,6 +26,9 @@ var read_1 = require("./core/read");
 Object.defineProperty(exports, "readButDoNotEvaluate", { enumerable: true, get: function () { return read_1.readButDoNotEvaluate; } });
 var FragmentReference_1 = require("./core/FragmentReference");
 Object.defineProperty(exports, "stableIdForFragmentReference", { enumerable: true, get: function () { return FragmentReference_1.stableIdForFragmentReference; } });
+var logging_1 = require("./core/logging");
+Object.defineProperty(exports, "logMessage", { enumerable: true, get: function () { return logging_1.logMessage; } });
+Object.defineProperty(exports, "registerLogger", { enumerable: true, get: function () { return logging_1.registerLogger; } });
 var IsographEnvironmentProvider_1 = require("./react/IsographEnvironmentProvider");
 Object.defineProperty(exports, "IsographEnvironmentProvider", { enumerable: true, get: function () { return IsographEnvironmentProvider_1.IsographEnvironmentProvider; } });
 Object.defineProperty(exports, "useIsographEnvironment", { enumerable: true, get: function () { return IsographEnvironmentProvider_1.useIsographEnvironment; } });

package/dist/react/useLazyReference.js

@@ -4,15 +4,16 @@ exports.useLazyReference = useLazyReference;
 const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
 const cache_1 = require("../core/cache");
 const react_disposable_state_1 = require("@isograph/react-disposable-state");
+const logging_1 = require("../core/logging");
 function useLazyReference(entrypoint, variables) {
-    // @ts-expect-error
-    if (typeof window !== 'undefined' && window.__LOG) {
-        if ((entrypoint === null || entrypoint === void 0 ? void 0 : entrypoint.kind) !== 'Entrypoint') {
-            console.warn('useLazyReference was passed an unexpected or invalid object as the first parameter. ' +
-                'Is the babel plugin correctly configured? Received=', entrypoint);
-        }
-    }
     const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    if ((entrypoint === null || entrypoint === void 0 ? void 0 : entrypoint.kind) !== 'Entrypoint') {
+        // TODO have a separate error logger
+        (0, logging_1.logMessage)(environment, {
+            kind: 'NonEntrypointReceived',
+            entrypoint,
+        });
+    }
     const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables);
     return {
         fragmentReference: (0, react_disposable_state_1.useLazyDisposableState)(cache).state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.0.0-main-5da1ab92",
+  "version": "0.0.0-main-6bd3135f",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -17,9 +17,9 @@
     "tsc": "tsc"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-5da1ab92",
-    "@isograph/react-disposable-state": "0.0.0-main-5da1ab92",
-    "@isograph/reference-counted-pointer": "0.0.0-main-5da1ab92"
+    "@isograph/disposable-types": "0.0.0-main-6bd3135f",
+    "@isograph/react-disposable-state": "0.0.0-main-6bd3135f",
+    "@isograph/reference-counted-pointer": "0.0.0-main-6bd3135f"
   },
   "peerDependencies": {
     "react": "18.3.1"

package/src/core/IsographEnvironment.ts

@@ -5,6 +5,7 @@ import { FragmentReference, Variables } from './FragmentReference';
 import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
 import { IsographEntrypoint } from './entrypoint';
 import type { ReaderAst } from './reader';
+import { LogFunction, WrappedLogFunction } from './logging';
 
 export type ComponentOrFieldName = string;
 export type StringifiedArgs = string;
@@ -63,6 +64,7 @@ export type IsographEnvironment = {
   readonly retainedQueries: Set<RetainedQuery>;
   readonly gcBuffer: Array<RetainedQuery>;
   readonly gcBufferSize: number;
+  readonly loggers: Set<WrappedLogFunction>;
 };
 
 export type MissingFieldHandler = (
@@ -117,7 +119,8 @@ const DEFAULT_GC_BUFFER_SIZE = 10;
 export function createIsographEnvironment(
   store: IsographStore,
   networkFunction: IsographNetworkFunction,
-  missingFieldHandler?: MissingFieldHandler,
+  missingFieldHandler?: MissingFieldHandler | null,
+  logFunction?: LogFunction | null,
 ): IsographEnvironment {
   return {
     store,
@@ -130,6 +133,7 @@ export function createIsographEnvironment(
     retainedQueries: new Set(),
     gcBuffer: [],
     gcBufferSize: DEFAULT_GC_BUFFER_SIZE,
+    loggers: logFunction != null ? new Set([{ log: logFunction }]) : new Set(),
   };
 }
 

package/src/core/cache.ts

@@ -32,6 +32,7 @@ import {
 import { mergeObjectsUsingReaderAst } from './areEqualWithDeepComparison';
 import { makeNetworkRequest } from './makeNetworkRequest';
 import { wrapResolvedValue } from './PromiseWrapper';
+import { logMessage } from './logging';
 
 const TYPENAME_FIELD_NAME = '__typename';
 
@@ -43,14 +44,13 @@ export function getOrCreateItemInSuspenseCache<
   index: string,
   factory: Factory<FragmentReference<TReadFromStore, TClientFieldValue>>,
 ): ParentCache<FragmentReference<TReadFromStore, TClientFieldValue>> {
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    console.log('getting cache for', {
-      index,
-      cache: Object.keys(environment.fragmentCache),
-      found: !!environment.fragmentCache[index],
-    });
-  }
+  // TODO this is probably a useless message, we should remove it
+  logMessage(environment, {
+    kind: 'GettingSuspenseCacheItem',
+    index,
+    availableCacheItems: Object.keys(environment.fragmentCache),
+    found: !!environment.fragmentCache[index],
+  });
   if (environment.fragmentCache[index] == null) {
     environment.fragmentCache[index] = new ParentCache(factory);
   }
@@ -124,7 +124,8 @@ type NetworkResponseValue =
   | NetworkResponseObject
   | NetworkResponseObject[]
   | NetworkResponseScalarValue[];
-type NetworkResponseObject = {
+
+export type NetworkResponseObject = {
   // N.B. undefined is here to support optional id's, but
   // undefined should not *actually* be present in the network response.
   [index: string]: undefined | NetworkResponseValue;
@@ -140,15 +141,12 @@ export function normalizeData(
 ): Set<DataId> {
   const encounteredIds = new Set<DataId>();
 
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    console.log(
-      'about to normalize',
-      normalizationAst,
-      networkResponse,
-      variables,
-    );
-  }
+  logMessage(environment, {
+    kind: 'AboutToNormalize',
+    normalizationAst,
+    networkResponse,
+    variables,
+  });
   normalizeDataIntoRecord(
     environment,
     normalizationAst,
@@ -159,14 +157,13 @@ export function normalizeData(
     nestedRefetchQueries,
     encounteredIds,
   );
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    console.log('after normalization', {
-      store: environment.store,
-      encounteredIds,
-      environment,
-    });
-  }
+
+  logMessage(environment, {
+    kind: 'AfterNormalization',
+    store: environment.store,
+    encounteredIds,
+  });
+
   callSubscriptions(environment, encounteredIds);
   return encounteredIds;
 }
@@ -292,24 +289,18 @@ function callSubscriptions(
               subscription.encounteredDataAndRecords.item,
               newEncounteredDataAndRecords.item,
             );
+
+            logMessage(environment, {
+              kind: 'DeepEqualityCheck',
+              fragmentReference: subscription.fragmentReference,
+              old: subscription.encounteredDataAndRecords.item,
+              new: newEncounteredDataAndRecords.item,
+              deeplyEqual:
+                mergedItem === subscription.encounteredDataAndRecords.item,
+            });
+
             if (mergedItem !== subscription.encounteredDataAndRecords.item) {
-              // @ts-expect-error
-              if (typeof window !== 'undefined' && window.__LOG) {
-                console.log('Deep equality - No', {
-                  fragmentReference: subscription.fragmentReference,
-                  old: subscription.encounteredDataAndRecords.item,
-                  new: newEncounteredDataAndRecords.item,
-                });
-              }
               subscription.callback(newEncounteredDataAndRecords);
-            } else {
-              // @ts-expect-error
-              if (typeof window !== 'undefined' && window.__LOG) {
-                console.log('Deep equality - Yes', {
-                  fragmentReference: subscription.fragmentReference,
-                  old: subscription.encounteredDataAndRecords.item,
-                });
-              }
             }
           }
           return;

package/src/core/componentCache.ts

@@ -4,6 +4,7 @@ import { FragmentReference } from './FragmentReference';
 import { useReadAndSubscribe } from '../react/useReadAndSubscribe';
 import { NetworkRequestReaderOptions } from './read';
 import { readPromise } from './PromiseWrapper';
+import { logMessage } from './logging';
 
 export function getOrCreateCachedComponent(
   environment: IsographEnvironment,
@@ -40,15 +41,11 @@ export function getOrCreateCachedComponent(
           readerWithRefetchQueries.readerArtifact.readerAst,
         );
 
-        // @ts-expect-error
-        if (typeof window !== 'undefined' && window.__LOG) {
-          console.log(
-            'Component re-rendered: ' +
-              componentName +
-              ' ' +
-              fragmentReference.root,
-          );
-        }
+        logMessage(environment, {
+          kind: 'ComponentRerendered',
+          componentName,
+          rootId: fragmentReference.root,
+        });
 
         const firstParameter = {
           data,

package/src/core/logging.ts

@@ -0,0 +1,106 @@
+import { CleanupFn } from '@isograph/disposable-types';
+import {
+  DataId,
+  IsographEnvironment,
+  IsographStore,
+  StoreRecord,
+} from './IsographEnvironment';
+import {
+  IsographEntrypoint,
+  NormalizationAst,
+  RefetchQueryNormalizationArtifact,
+} from './entrypoint';
+import { FragmentReference, Variables } from './FragmentReference';
+import { NetworkResponseObject } from './cache';
+import { Arguments } from './util';
+import { ReadDataResult } from './read';
+
+export type LogMessage =
+  | {
+      kind: 'GettingSuspenseCacheItem';
+      index: string;
+      availableCacheItems: ReadonlyArray<string>;
+      found: boolean;
+    }
+  | {
+      kind: 'AboutToNormalize';
+      normalizationAst: NormalizationAst;
+      networkResponse: NetworkResponseObject;
+      variables: Variables;
+    }
+  | {
+      kind: 'AfterNormalization';
+      store: IsographStore;
+      encounteredIds: Set<string>;
+    }
+  | {
+      kind: 'DeepEqualityCheck';
+      fragmentReference: FragmentReference<any, any>;
+      old: object;
+      new: object;
+      deeplyEqual: boolean;
+    }
+  | {
+      kind: 'ComponentRerendered';
+      componentName: string;
+      rootId: DataId;
+    }
+  | {
+      kind: 'MakeNetworkRequest';
+      artifact:
+        | RefetchQueryNormalizationArtifact
+        | IsographEntrypoint<any, any>;
+      variables: Variables;
+      networkRequestId: string;
+    }
+  | {
+      kind: 'ReceivedNetworkResponse';
+      // TODO should be object
+      networkResponse: any;
+      networkRequestId: string;
+    }
+  | {
+      kind: 'MissingFieldHandlerCalled';
+      root: DataId;
+      storeRecord: StoreRecord;
+      fieldName: string;
+      arguments: Arguments | null;
+      variables: Variables;
+    }
+  | {
+      kind: 'DoneReading';
+      response: ReadDataResult<any>;
+    }
+  | {
+      kind: 'NonEntrypointReceived';
+      entrypoint: any;
+    };
+
+export type LogFunction = (logMessage: LogMessage) => void;
+
+// wrapped so that items in the loggers set are unique.
+export type WrappedLogFunction = {
+  log: LogFunction;
+};
+
+export function logMessage(
+  environment: IsographEnvironment,
+  message: LogMessage,
+) {
+  for (const logger of environment.loggers) {
+    try {
+      logger.log(message);
+    } catch {}
+  }
+}
+
+export function registerLogger(
+  environment: IsographEnvironment,
+  log: LogFunction,
+): CleanupFn {
+  const wrapped = { log };
+  environment.loggers.add(wrapped);
+  return () => {
+    environment.loggers.delete(wrapped);
+  };
+}

package/src/core/makeNetworkRequest.ts

@@ -13,16 +13,26 @@ import {
 import { IsographEnvironment } from './IsographEnvironment';
 import { AnyError, PromiseWrapper, wrapPromise } from './PromiseWrapper';
 import { normalizeData } from './cache';
+import { logMessage } from './logging';
+
+let networkRequestId = 0;
 
 export function makeNetworkRequest(
   environment: IsographEnvironment,
   artifact: RefetchQueryNormalizationArtifact | IsographEntrypoint<any, any>,
   variables: Variables,
 ): ItemCleanupPair<PromiseWrapper<void, AnyError>> {
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    console.log('make network request', artifact, variables);
-  }
+  // TODO this should be a DataId and stored in the store
+  const myNetworkRequestId = networkRequestId + '';
+  networkRequestId++;
+
+  logMessage(environment, {
+    kind: 'MakeNetworkRequest',
+    artifact,
+    variables,
+    networkRequestId: myNetworkRequestId,
+  });
+
   let status: NetworkRequestStatus = {
     kind: 'UndisposedIncomplete',
   };
@@ -30,10 +40,11 @@ export function makeNetworkRequest(
   const promise = environment
     .networkFunction(artifact.queryText, variables)
     .then((networkResponse) => {
-      // @ts-expect-error
-      if (typeof window !== 'undefined' && window.__LOG) {
-        console.log('network response', artifact, networkResponse);
-      }
+      logMessage(environment, {
+        kind: 'ReceivedNetworkResponse',
+        networkResponse,
+        networkRequestId: myNetworkRequestId,
+      });
 
       if (networkResponse.errors != null) {
         // @ts-expect-error Why are we getting the wrong constructor here?

package/src/core/read.ts

@@ -28,6 +28,7 @@ import {
 } from './PromiseWrapper';
 import { ReaderAst } from './reader';
 import { Arguments } from './util';
+import { logMessage } from './logging';
 
 export type WithEncounteredRecords<T> = {
   readonly encounteredRecords: Set<DataId>;
@@ -57,10 +58,12 @@ export function readButDoNotEvaluate<
     networkRequestOptions,
     mutableEncounteredRecords,
   );
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    console.log('done reading: ' + response.kind, { response });
-  }
+
+  logMessage(environment, {
+    kind: 'DoneReading',
+    response,
+  });
+
   if (response.kind === 'MissingData') {
     // There are two cases here that we care about:
     // 1. the network request is in flight, we haven't suspend on it, and we want
@@ -90,7 +93,7 @@ export function readButDoNotEvaluate<
   }
 }
 
-type ReadDataResult<TReadFromStore> =
+export type ReadDataResult<TReadFromStore> =
   | {
       readonly kind: 'Success';
       readonly data: ExtractData<TReadFromStore>;
@@ -207,6 +210,7 @@ function readData<TReadFromStore>(
           // TODO make this configurable, and also generated and derived from the schema
           const missingFieldHandler =
             environment.missingFieldHandler ?? defaultMissingFieldHandler;
+
           const altLink = missingFieldHandler(
             storeRecord,
             root,
@@ -214,6 +218,15 @@ function readData<TReadFromStore>(
             field.arguments,
             variables,
           );
+          logMessage(environment, {
+            kind: 'MissingFieldHandlerCalled',
+            root,
+            storeRecord,
+            fieldName: field.fieldName,
+            arguments: field.arguments,
+            variables,
+          });
+
           if (altLink === undefined) {
             return {
               kind: 'MissingData',

package/src/index.ts

@@ -67,6 +67,12 @@ export {
   type ExtractData,
   stableIdForFragmentReference,
 } from './core/FragmentReference';
+export {
+  type LogMessage,
+  type LogFunction,
+  logMessage,
+  registerLogger,
+} from './core/logging';
 
 export {
   IsographEnvironmentProvider,

package/src/react/useLazyReference.ts

@@ -6,6 +6,7 @@ import { useIsographEnvironment } from './IsographEnvironmentProvider';
 import { IsographEntrypoint } from '../core/entrypoint';
 import { getOrCreateCacheForArtifact } from '../core/cache';
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
+import { logMessage } from '../core/logging';
 
 export function useLazyReference<
   TReadFromStore extends { parameters: object; data: object },
@@ -16,18 +17,16 @@ export function useLazyReference<
 ): {
   fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
 } {
-  // @ts-expect-error
-  if (typeof window !== 'undefined' && window.__LOG) {
-    if (entrypoint?.kind !== 'Entrypoint') {
-      console.warn(
-        'useLazyReference was passed an unexpected or invalid object as the first parameter. ' +
-          'Is the babel plugin correctly configured? Received=',
-        entrypoint,
-      );
-    }
+  const environment = useIsographEnvironment();
+
+  if (entrypoint?.kind !== 'Entrypoint') {
+    // TODO have a separate error logger
+    logMessage(environment, {
+      kind: 'NonEntrypointReceived',
+      entrypoint,
+    });
   }
 
-  const environment = useIsographEnvironment();
   const cache = getOrCreateCacheForArtifact(environment, entrypoint, variables);
 
   return {