@isograph/react 0.1.0 → 0.2.0

package/dist/loadable-hooks/useSkipLimitPagination.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSkipLimitPagination = void 0;
+const IsographEnvironmentProvider_1 = require("../react/IsographEnvironmentProvider");
+const useResult_1 = require("../react/useResult");
+const read_1 = require("../core/read");
+const react_disposable_state_1 = require("@isograph/react-disposable-state");
+const reference_counted_pointer_1 = require("@isograph/reference-counted-pointer");
+const PromiseWrapper_1 = require("../core/PromiseWrapper");
+function flatten(arr) {
+    let outArray = [];
+    for (const subarr of arr) {
+        for (const item of subarr) {
+            outArray.push(item);
+        }
+    }
+    return outArray;
+}
+/**
+ * accepts a loadableField that accepts skip and limit arguments
+ * and returns:
+ * - a fetchMore function that, when called, triggers a network
+ *   request for additional data, and
+ * - the data received so far.
+ *
+ * This hook will suspend if any network request is in flight.
+ *
+ * Calling fetchMore before the hook mounts is a no-op.
+ *
+ * NOTE: this hook does not subscribe to changes. This is a known
+ * issue. If you are running into this issue, reach out on GitHub/
+ * Twitter, and we'll fix the issue.
+ */
+function useSkipLimitPagination(loadableField) {
+    const networkRequestOptions = {
+        suspendIfInFlight: true,
+        throwOnNetworkError: true,
+    };
+    const { state, setState } = (0, react_disposable_state_1.useUpdatableDisposableState)();
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    function readCompletedFragmentReferences(completedReferences) {
+        // In general, this will not suspend. But it could, if there is missing data.
+        // A better version of this hook would not do any reading here.
+        const results = completedReferences.map(([pointer]) => {
+            const fragmentReference = pointer.getItemIfNotDisposed();
+            if (fragmentReference == null) {
+                throw new Error('FragmentReference is unexpectedly disposed. \
+        This is indicative of a bug in Isograph.');
+            }
+            (0, useResult_1.maybeUnwrapNetworkRequest)(fragmentReference.networkRequest, networkRequestOptions);
+            const data = (0, read_1.readButDoNotEvaluate)(environment, fragmentReference, networkRequestOptions);
+            const readerWithRefetchQueries = (0, PromiseWrapper_1.readPromise)(fragmentReference.readerWithRefetchQueries);
+            return readerWithRefetchQueries.readerArtifact.resolver(data.item, undefined);
+        });
+        const items = flatten(results);
+        return items;
+    }
+    const getFetchMore = (loadedSoFar) => (args, count) => {
+        // @ts-expect-error
+        const loadedField = loadableField(Object.assign(Object.assign({}, args), { skip: loadedSoFar, limit: count }))[1]();
+        const newPointer = (0, reference_counted_pointer_1.createReferenceCountedPointer)(loadedField);
+        const clonedPointers = loadedReferences.map(([refCountedPointer]) => {
+            const clonedRefCountedPointer = refCountedPointer.cloneIfNotDisposed();
+            if (clonedRefCountedPointer == null) {
+                throw new Error('This reference counted pointer has already been disposed. \
+              This is indicative of a bug in useSkipLimitPagination.');
+            }
+            return clonedRefCountedPointer;
+        });
+        clonedPointers.push(newPointer);
+        const totalItemCleanupPair = [
+            clonedPointers,
+            () => {
+                clonedPointers.forEach(([, dispose]) => {
+                    dispose();
+                });
+            },
+        ];
+        setState(totalItemCleanupPair);
+    };
+    const loadedReferences = state === react_disposable_state_1.UNASSIGNED_STATE ? [] : state;
+    if (loadedReferences.length === 0) {
+        return {
+            kind: 'Complete',
+            fetchMore: getFetchMore(0),
+            results: [],
+        };
+    }
+    const mostRecentItem = loadedReferences[loadedReferences.length - 1];
+    const mostRecentFragmentReference = mostRecentItem[0].getItemIfNotDisposed();
+    if (mostRecentFragmentReference === null) {
+        throw new Error('FragmentReference is unexpectedly disposed. \
+        This is indicative of a bug in Isograph.');
+    }
+    const networkRequestStatus = (0, PromiseWrapper_1.getPromiseState)(mostRecentFragmentReference.networkRequest);
+    switch (networkRequestStatus.kind) {
+        case 'Pending': {
+            const completedFragmentReferences = loadedReferences.slice(0, loadedReferences.length - 1);
+            return {
+                kind: 'Pending',
+                pendingFragment: mostRecentFragmentReference,
+                results: readCompletedFragmentReferences(completedFragmentReferences),
+            };
+        }
+        case 'Err': {
+            throw networkRequestStatus.error;
+        }
+        case 'Ok': {
+            const results = readCompletedFragmentReferences(loadedReferences);
+            return {
+                kind: 'Complete',
+                results,
+                fetchMore: getFetchMore(results.length),
+            };
+        }
+    }
+}
+exports.useSkipLimitPagination = useSkipLimitPagination;

package/dist/react/FragmentReader.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { ExtractReadFromStore, IsographEntrypoint } from '../core/entrypoint';
+import { FragmentReference } from '../core/FragmentReference';
+import { NetworkRequestReaderOptions } from '../core/read';
+export declare function FragmentReader<TProps extends Record<any, any>, TEntrypoint extends IsographEntrypoint<any, React.FC<TProps>>>(props: TProps extends Record<string, never> ? {
+    fragmentReference: FragmentReference<ExtractReadFromStore<TEntrypoint>, React.FC<{}>>;
+    additionalProps?: TProps;
+    networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+} : {
+    fragmentReference: FragmentReference<ExtractReadFromStore<TEntrypoint>, React.FC<TProps>>;
+    additionalProps: TProps;
+    networkRequestOptions?: Partial<NetworkRequestReaderOptions>;
+}): React.ReactNode;

package/dist/react/FragmentReader.js

@@ -0,0 +1,33 @@
+"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 = void 0;
+const React = __importStar(require("react"));
+const useResult_1 = require("./useResult");
+function FragmentReader(props) {
+    const Component = (0, useResult_1.useResult)(props.fragmentReference, props.networkRequestOptions);
+    return React.createElement(Component, Object.assign({}, props.additionalProps));
+}
+exports.FragmentReader = FragmentReader;

package/dist/react/IsographEnvironmentProvider.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { type IsographEnvironment } from '../core/IsographEnvironment';
+export declare const IsographEnvironmentContext: React.Context<IsographEnvironment | null>;
+export type IsographEnvironmentProviderProps = {
+    readonly environment: IsographEnvironment;
+    readonly children: ReactNode;
+};
+export declare function IsographEnvironmentProvider({ environment, children, }: IsographEnvironmentProviderProps): React.ReactElement;
+export declare function useIsographEnvironment(): IsographEnvironment;

package/dist/{IsographEnvironment.js → react/IsographEnvironmentProvider.js}

@@ -23,11 +23,10 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createIsographStore = exports.createIsographEnvironment = exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.ROOT_ID = exports.IsographEnvironmentContext = void 0;
-const react_1 = require("react");
+exports.useIsographEnvironment = exports.IsographEnvironmentProvider = exports.IsographEnvironmentContext = void 0;
 const React = __importStar(require("react"));
+const react_1 = require("react");
 exports.IsographEnvironmentContext = (0, react_1.createContext)(null);
-exports.ROOT_ID = '__ROOT';
 function IsographEnvironmentProvider({ environment, children, }) {
     return (React.createElement(exports.IsographEnvironmentContext.Provider, { value: environment }, children));
 }
@@ -41,20 +40,3 @@ function useIsographEnvironment() {
     return context;
 }
 exports.useIsographEnvironment = useIsographEnvironment;
-function createIsographEnvironment(store, networkFunction, missingFieldHandler) {
-    return {
-        store,
-        networkFunction,
-        missingFieldHandler: missingFieldHandler !== null && missingFieldHandler !== void 0 ? missingFieldHandler : null,
-        componentCache: {},
-        subscriptions: new Set(),
-        suspenseCache: {},
-    };
-}
-exports.createIsographEnvironment = createIsographEnvironment;
-function createIsographStore() {
-    return {
-        [exports.ROOT_ID]: {},
-    };
-}
-exports.createIsographStore = createIsographStore;

package/dist/react/useImperativeReference.d.ts

@@ -0,0 +1,7 @@
+import { UnassignedState } from '@isograph/react-disposable-state';
+import { IsographEntrypoint } from '../core/entrypoint';
+import { FragmentReference, Variables } from '../core/FragmentReference';
+export declare function useImperativeReference<TReadFromStore extends Object, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>): {
+    fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue> | UnassignedState;
+    loadFragmentReference: (variables: Variables) => void;
+};

package/dist/react/useImperativeReference.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useImperativeReference = void 0;
+const react_disposable_state_1 = require("@isograph/react-disposable-state");
+const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
+const IsographEnvironment_1 = require("../core/IsographEnvironment");
+const makeNetworkRequest_1 = require("../core/makeNetworkRequest");
+const PromiseWrapper_1 = require("../core/PromiseWrapper");
+// TODO rename this to useImperativelyLoadedEntrypoint
+function useImperativeReference(entrypoint) {
+    const { state, setState } = (0, react_disposable_state_1.useUpdatableDisposableState)();
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    return {
+        fragmentReference: state,
+        loadFragmentReference: (variables) => {
+            const [networkRequest, disposeNetworkRequest] = (0, makeNetworkRequest_1.makeNetworkRequest)(environment, entrypoint, variables);
+            setState([
+                {
+                    kind: 'FragmentReference',
+                    readerWithRefetchQueries: (0, PromiseWrapper_1.wrapResolvedValue)({
+                        kind: 'ReaderWithRefetchQueries',
+                        readerArtifact: entrypoint.readerWithRefetchQueries.readerArtifact,
+                        nestedRefetchQueries: entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
+                    }),
+                    root: IsographEnvironment_1.ROOT_ID,
+                    variables,
+                    networkRequest,
+                },
+                () => {
+                    disposeNetworkRequest();
+                },
+            ]);
+        },
+    };
+}
+exports.useImperativeReference = useImperativeReference;

package/dist/react/useLazyReference.d.ts

@@ -0,0 +1,5 @@
+import { FragmentReference, Variables } from '../core/FragmentReference';
+import { IsographEntrypoint } from '../core/entrypoint';
+export declare function useLazyReference<TReadFromStore extends Object, TClientFieldValue>(entrypoint: IsographEntrypoint<TReadFromStore, TClientFieldValue>, variables: Variables): {
+    fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>;
+};

package/dist/react/useLazyReference.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLazyReference = void 0;
+const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
+const cache_1 = require("../core/cache");
+const react_disposable_state_1 = require("@isograph/react-disposable-state");
+function useLazyReference(entrypoint, variables) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    const cache = (0, cache_1.getOrCreateCacheForArtifact)(environment, entrypoint, variables);
+    return {
+        fragmentReference: (0, react_disposable_state_1.useLazyDisposableState)(cache).state,
+    };
+}
+exports.useLazyReference = useLazyReference;

package/dist/react/useReadAndSubscribe.d.ts

@@ -0,0 +1,11 @@
+import { FragmentReference } from '../core/FragmentReference';
+import { NetworkRequestReaderOptions, WithEncounteredRecords } from '../core/read';
+/**
+ * Read the data from a fragment reference and subscribe to updates.
+ */
+export declare function useReadAndSubscribe<TReadFromStore extends Object>(fragmentReference: FragmentReference<TReadFromStore, any>, networkRequestOptions: NetworkRequestReaderOptions): TReadFromStore;
+export declare function useSubscribeToMultiple<TReadFromStore extends Object>(items: ReadonlyArray<{
+    records: WithEncounteredRecords<TReadFromStore>;
+    callback: (updatedRecords: WithEncounteredRecords<TReadFromStore>) => void;
+    fragmentReference: FragmentReference<TReadFromStore, any>;
+}>): void;

package/dist/react/useReadAndSubscribe.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSubscribeToMultiple = exports.useReadAndSubscribe = void 0;
+const react_1 = require("react");
+const FragmentReference_1 = require("../core/FragmentReference");
+const read_1 = require("../core/read");
+const useRerenderOnChange_1 = require("./useRerenderOnChange");
+const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
+const cache_1 = require("../core/cache");
+/**
+ * Read the data from a fragment reference and subscribe to updates.
+ */
+function useReadAndSubscribe(fragmentReference, networkRequestOptions) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    const [readOutDataAndRecords, setReadOutDataAndRecords] = (0, react_1.useState)(() => (0, read_1.readButDoNotEvaluate)(environment, fragmentReference, networkRequestOptions));
+    (0, useRerenderOnChange_1.useRerenderOnChange)(readOutDataAndRecords, fragmentReference, setReadOutDataAndRecords);
+    return readOutDataAndRecords.item;
+}
+exports.useReadAndSubscribe = useReadAndSubscribe;
+function useSubscribeToMultiple(items) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    (0, react_1.useEffect)(() => {
+        const cleanupFns = items.map(({ records, callback, fragmentReference }) => {
+            return (0, cache_1.subscribe)(environment, records, fragmentReference, callback);
+        });
+        return () => {
+            cleanupFns.forEach((loader) => {
+                loader();
+            });
+        };
+    }, 
+    // By analogy to useReadAndSubscribe, we can have an empty dependency array?
+    // Maybe callback has to be depended on. I don't know!
+    // TODO find out
+    [
+        items
+            .map(({ fragmentReference }) => (0, FragmentReference_1.stableIdForFragmentReference)(fragmentReference))
+            .join('.'),
+    ]);
+}
+exports.useSubscribeToMultiple = useSubscribeToMultiple;

package/dist/react/useRerenderOnChange.d.ts

@@ -0,0 +1,3 @@
+import { WithEncounteredRecords } from '../core/read';
+import { FragmentReference } from '../core/FragmentReference';
+export declare function useRerenderOnChange<TReadFromStore extends Object>(encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>, fragmentReference: FragmentReference<any, any>, setEncounteredDataAndRecords: (data: WithEncounteredRecords<TReadFromStore>) => void): void;

package/dist/react/useRerenderOnChange.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRerenderOnChange = void 0;
+const react_1 = require("react");
+const cache_1 = require("../core/cache");
+const IsographEnvironmentProvider_1 = require("./IsographEnvironmentProvider");
+// TODO add unit tests for this. Add integration tests that test
+// behavior when the encounteredRecords underneath a fragment change.
+function useRerenderOnChange(encounteredDataAndRecords, fragmentReference, setEncounteredDataAndRecords) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    (0, react_1.useEffect)(() => {
+        return (0, cache_1.subscribe)(environment, encounteredDataAndRecords, fragmentReference, (newEncounteredDataAndRecords) => {
+            setEncounteredDataAndRecords(newEncounteredDataAndRecords);
+        });
+        // Note: this is an empty array on purpose:
+        // - the fragment reference is stable for the life of the component
+        // - ownership of encounteredDataAndRecords is transferred into the
+        //   environment
+        // - though maybe we need to include setEncounteredDataAndRecords in
+        //   the dependency array
+    }, []);
+}
+exports.useRerenderOnChange = useRerenderOnChange;

package/dist/react/useResult.d.ts

@@ -0,0 +1,5 @@
+import { FragmentReference } from '../core/FragmentReference';
+import { NetworkRequestReaderOptions } from '../core/read';
+import { PromiseWrapper } from '../core/PromiseWrapper';
+export declare function useResult<TReadFromStore extends Object, TClientFieldValue>(fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>, partialNetworkRequestOptions?: Partial<NetworkRequestReaderOptions> | void): TClientFieldValue;
+export declare function maybeUnwrapNetworkRequest(networkRequest: PromiseWrapper<void, any>, networkRequestOptions: NetworkRequestReaderOptions): void;

package/dist/react/useResult.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeUnwrapNetworkRequest = exports.useResult = void 0;
+const IsographEnvironmentProvider_1 = require("../react/IsographEnvironmentProvider");
+const componentCache_1 = require("../core/componentCache");
+const useReadAndSubscribe_1 = require("./useReadAndSubscribe");
+const read_1 = require("../core/read");
+const PromiseWrapper_1 = require("../core/PromiseWrapper");
+function useResult(fragmentReference, partialNetworkRequestOptions) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    const networkRequestOptions = (0, read_1.getNetworkRequestOptionsWithDefaults)(partialNetworkRequestOptions);
+    maybeUnwrapNetworkRequest(fragmentReference.networkRequest, networkRequestOptions);
+    const readerWithRefetchQueries = (0, PromiseWrapper_1.readPromise)(fragmentReference.readerWithRefetchQueries);
+    switch (readerWithRefetchQueries.readerArtifact.kind) {
+        case 'ComponentReaderArtifact': {
+            // @ts-expect-error
+            return (0, componentCache_1.getOrCreateCachedComponent)(environment, readerWithRefetchQueries.readerArtifact.componentName, fragmentReference, networkRequestOptions);
+        }
+        case 'EagerReaderArtifact': {
+            const data = (0, useReadAndSubscribe_1.useReadAndSubscribe)(fragmentReference, networkRequestOptions);
+            return readerWithRefetchQueries.readerArtifact.resolver(data);
+        }
+    }
+}
+exports.useResult = useResult;
+function maybeUnwrapNetworkRequest(networkRequest, networkRequestOptions) {
+    const state = (0, PromiseWrapper_1.getPromiseState)(networkRequest);
+    if (state.kind === 'Err' && networkRequestOptions.throwOnNetworkError) {
+        throw state.error;
+    }
+    else if (state.kind === 'Pending' &&
+        networkRequestOptions.suspendIfInFlight) {
+        throw state.promise;
+    }
+}
+exports.maybeUnwrapNetworkRequest = maybeUnwrapNetworkRequest;

package/docs/how-useLazyReference-works.md

@@ -0,0 +1,117 @@
+# How does `useLazyReference` work, at an extremely detailed level?
+
+## High level explanation
+
+[`useLazyReference`](https://github.com/isographlabs/isograph/blob/main/libs/isograph-react/src/useLazyReference.ts) is the developer-facing API. From the user's perspective, they call this to make a network request during the initial render, and then receive a query reference that they can use to read out the data from that network request.
+
+Our goal is to only create a single network request, even if `useLazyReference` is called multiple times. We cannot always achieve this (it is impossible in React's programming model), but we can get pretty close.
+
+## Definitions
+
+First, some definitions. Don't worry about these, but refer back to them if necessary:
+
+- A `ParentCache` is initially empty, but can store a single `CacheItem`. The `ParentCache` must be stable across renders.
+- A `CacheItem` is an object storing some value and is in one of three states: `InParentCacheAndNotDisposed`, `NotInParentCacheAndNotDisposed`, and `NotInParentCacheAndDisposed`.
+  - An invariant is that these APIs will never return a disposed `CacheItem` to the user.
+- Creating the `CacheItem` is allowed to have side effects (e.g. making network requests in this example). We want to create as few `CacheItem`'s as possible.
+- A `CacheItem` can be disposed, at which point it can perform some cleanup. Another guarantee is that every `CacheItem` we create will be disposed (i.e. no memory leaks).
+- A `CacheItem` can also have (undisposed) temporary retains and permanent retains. If it has neither, it gets disposed.
+  - When a `CacheItem` has no more undisposed temporary retains, it removes itself from the parent cache.
+  - When a `CacheItem` has no more undisposed temporary retains **and** no more undisposed permanent retains, it disposes itself.
+- A **temporary retain** is a retain that last 5 seconds or until you explicitly dispose it.
+- A **permanent retain** is a retain that lasts until you explicitly dispose it.
+- If a `CacheItem` is in a `ParentCache`, it must have at least one temporary retain. (Permanent retains are irrelevant here!)
+
+## How it all works
+
+Okay, so now the actual description of how this all works:
+
+- When `useLazyReference` is called, we get-or-create a `ParentCache`.
+  - When the cache is filled with a `CacheItem`, we make a network request and return a query reference.
+- `useLazyReference` calls `useLazyDisposableState`, which calls `useCachedPrecommitValue` with that `ParentCache` and a callback (1).
+- When `useCachedPrecommitValue` is called and has not committed, it will:
+  - If that `ParentCache` is empty, fill the cache with a `CacheItem` and create a "temporary retain" (2), and return that query reference to to `useLazyDisposableState`. (3a)
+  - If that `ParentCache` is not empty, we create a "temporary retain" (2) on that `CacheItem`, and return the query reference already in the cache to `useLazyDisposableState`. (3b)
+- When `useCachedPrecommitValue` commits, it will:
+  - Check whether the `CacheItem` that we received during the render is disposed. If not disposed, we clear the temporary retain (2), permanently retain the item, and pass that value to the callback (1).
+  - If the item we received during the render is disposed, check whether the `ParentCache` is filled. (Another render might have filled the cache!) If so, permanently retain that `CacheItem` and pass the value to that callback (1).
+  - If that `ParentCache` is not filled, create a `CacheItem` **but not put it in the `ParentCache`**, permanently retain it, and pass it to the callback. (1)
+- When `useCachedPrecommitValue` is called after it has committed, it will return `null`.
+- So, at this point, we either have returned a value to `useLazyDisposableState` (3a and 3b), or we have committed and some callback has executed.
+- The callback (1) that `useLazyDisposableState` passed to `useCachedPrecommitValue` stores the permanently retained `CacheItem` in a ref.
+- `useLazyDisposableState` then returns either the value returned from `useCachedPrecommitValue` or the one in the ref.
+  - If we have some logic error and neither of these contain values, we throw an error.
+- When the `useLazyDisposableState` unmounts (i.e. which only occurs if it has committed), we dispose of the permanent retain.
+
+## What about these temporary and permanent retains?
+
+Let's go through some scenarios, in order to show how these temporary and permanent retains prevent us from making redundant network requests, and how they allow us to avoid memory leaks.
+
+### Happiest path with no suspense
+
+In the happiest path, `useLazyReference` is called once and commits in less than 5 seconds.
+
+- `useLazyReference` is called. The `ParentCache` becomes filled, triggering a network request. The `CacheItem` has one temporary retain.
+- `useLazyReference` commits. The temporary retain is cleared, causing the `ParentCache` to become empty. The `CacheItem` is permanently retained.
+- `useLazyReference` unmounts. The `CacheItem` is disposed.
+
+Subsequent calls to `useLazyReference` from unmounted components will see an empty cache and make new network requests.
+
+### Happy path with suspense
+
+In the happy path, we call `useLazyReference`, suspend, then call it again and commit.
+
+- `useLazyReference` is called (render 1). The `ParentCache` becomes filled, triggering a network request. The `CacheItem` has one temporary retain.
+- `useLazyReference` is called again (render 2). The `ParentCache` is already filled, so we simply create another temporary retain.
+- `useLazyReference` commits (from render 2). The temporary retain is cleared, but there is still a temporary retain outstanding, so we do not empty the `ParentCache`. The `CacheItem` is permanently retained.
+- After five seconds, the temporary retain clears itself, causing the `ParentCache` to become empty.
+- `useLazyReference` unmounts. The `CacheItem` is disposed.
+
+A key thing to note here is that, in the presence of suspense, we are never informed that render 1 will never commit! Hence, the temporary retain is important.
+
+### Multiple components making the same network request
+
+Another thing to note is that we cannot distinguish between the same component rendering multiple times (due to suspense) from two identical components rendering. That is, the user must help us distinguish these two possibilities; library code cannot do it. So, let's consider two components rendering and mounting.
+
+- `useLazyReference` is called (render 1). The `ParentCache` becomes filled, triggering a network request. The `CacheItem` has one temporary retain.
+- `useLazyReference` is called again (render 2). The `ParentCache` is already filled, so we simply create another temporary retain.
+- `useLazyReference` commits (from render 1 or 2). The temporary retain is cleared, but there is still a temporary retain outstanding, so we do not empty the `ParentCache`. The `CacheItem` is permanently retained.
+- `useLazyReference` commits (from the other render). The last temporary retain is cleared, so we empty the `ParentCache`. The `CacheItem` is permanently retained.
+- When both of these components unmount, the `CacheItem` is finally disposed.
+
+### A component that renders multiple times, but never mounts
+
+Another scenario we must handle is a component rendering multiple times without mounting. For example, a component might render, something suspends, then a parent component unmounts. So, our component never commits. In scenarios like this, we do not want memory leaks!
+
+- `useLazyReference` is called initially. The `ParentCache` becomes filled, triggering a network request. The `CacheItem` has one temporary retain.
+- `useLazyReference` is potentially called again (potentially multiple times). The `ParentCache` is already filled, so we simply create another temporary retain for each render.
+- Some parent component unmounts, so none of these renders will ever commit.
+- 5 seconds after the last render, we clean up the last temporary retain and remove the item from the `ParentCache`.
+
+### A component that takes too long to commit
+
+A scenario we must face is a component that takes too long to commit (e.g. >5 seconds.) I don't know whether 5 seconds is the optimal amount of time to wait, maybe 30 seconds is more reasonable!
+
+- `useLazyReference` is called initially. The `ParentCache` becomes filled, triggering a network request. The `CacheItem` has one temporary retain.
+- For whatever reason, React is slow. After 5 seconds, the temporary retain is cleared, and the `ParentCache` is cleared.
+- The render commits. We find that the item we created is disposed **and** the `ParentCache` is empty. So, we create a new `CacheItem` and permanently retain it.
+
+## Conclusion: why?
+
+The reason we go through this much effort is because we must deal with several facts:
+
+- We have no guarantee that a render will be followed by a commit.
+- If a render is not followed by a commit, we will never be informed.
+- We cannot distinguish between a render that will never commit from a render that will commit in the future.
+
+In light of these, the best we can do is to create temporary retains during render, and permanent retains only when a component commits.
+
+### Why clean stuff up?
+
+There are two reasons that we dispose of `CacheItem`s.
+
+First is that we do not want the memory usage of the app to grow without bound as the user uses our app.
+
+Second, consider a `CacheItem` that makes a network request during initial render of a page. If the user loaded the data for that page, then navigated away, then navigated back after a long time, then we would want to make a new network request for that data. If we do not clean up after ourselves, we would be locked into forever re-using the existing network response.
+
+Note that avoiding that network request (which is reasonable if e.g. the user navigates back after 10 seconds) can be done by, when the `CacheItem` is created, choosing to re-use cached data and not make a network request.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@isograph/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Use Isograph with React",
+  "homepage": "https://isograph.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Isograph Labs",
@@ -9,15 +10,19 @@
   "scripts": {
     "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
     "compile-watch": "tsc -p tsconfig.pkg.json --watch",
-    "test": "echo no tests yet",
+    "test": "vitest run",
     "test-watch": "vitest watch",
     "coverage": "vitest run --coverage",
-    "prepack": "yarn run test && yarn run compile"
+    "prepack": "yarn run test && yarn run compile",
+    "tsc": "tsc"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.1.0",
+    "@isograph/disposable-types": "0.2.0",
     "@isograph/react-disposable-state": "*",
-    "react": "^18.2.0"
+    "@isograph/reference-counted-pointer": "*"
+  },
+  "peerDependencies": {
+    "react": "18.2.0"
   },
   "devDependencies": {
     "@types/react": "^18.0.31",
@@ -29,5 +34,6 @@
     "type": "git",
     "url": "git+https://github.com/isographlabs/isograph.git",
     "directory": "libs/isograph-react"
-  }
+  },
+  "sideEffects": false
 }

package/src/core/FragmentReference.ts

@@ -0,0 +1,37 @@
+import { DataId } from './IsographEnvironment';
+import { ReaderWithRefetchQueries } from '../core/entrypoint';
+import { PromiseWrapper } from './PromiseWrapper';
+
+// TODO type this better
+export type VariableValue = string | number | boolean | null | object;
+
+export type Variables = { readonly [index: string]: VariableValue };
+
+export type FragmentReference<
+  TReadFromStore extends Object,
+  TClientFieldValue,
+> = {
+  readonly kind: 'FragmentReference';
+  readonly readerWithRefetchQueries: PromiseWrapper<
+    ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
+  >;
+  readonly root: DataId;
+  readonly variables: Variables | null;
+  readonly networkRequest: PromiseWrapper<void, any>;
+};
+
+export function stableIdForFragmentReference(
+  fragmentReference: FragmentReference<any, any>,
+): string {
+  return `${fragmentReference.root}/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;
+}