@isograph/react 0.1.1 → 0.3.0

package/dist/react/useLazyReference.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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, fetchOptions) {
+    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, fetchOptions);
+    return {
+        fragmentReference: (0, react_disposable_state_1.useLazyDisposableState)(cache).state,
+    };
+}

package/dist/react/useReadAndSubscribe.d.ts

@@ -0,0 +1,20 @@
+import { FragmentReference, ExtractData } from '../core/FragmentReference';
+import { NetworkRequestReaderOptions, WithEncounteredRecords } from '../core/read';
+import type { ReaderAst } from '../core/reader';
+/**
+ * Read the data from a fragment reference and subscribe to updates.
+ */
+export declare function useReadAndSubscribe<TReadFromStore extends {
+    parameters: object;
+    data: object;
+}>(fragmentReference: FragmentReference<TReadFromStore, any>, networkRequestOptions: NetworkRequestReaderOptions, readerAst: ReaderAst<TReadFromStore>): ExtractData<TReadFromStore>;
+export declare function useSubscribeToMultiple<TReadFromStore extends {
+    parameters: object;
+    data: object;
+}>(items: ReadonlyArray<{
+    records: WithEncounteredRecords<TReadFromStore>;
+    callback: (updatedRecords: WithEncounteredRecords<TReadFromStore>) => void;
+    fragmentReference: FragmentReference<TReadFromStore, any>;
+    readerAst: ReaderAst<TReadFromStore>;
+}>): void;
+//# sourceMappingURL=useReadAndSubscribe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useReadAndSubscribe.d.ts","sourceRoot":"","sources":["../../src/react/useReadAndSubscribe.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EAEjB,WAAW,EACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAE3B,sBAAsB,EACvB,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAE3D,iBAAiB,EAAE,iBAAiB,CAAC,cAAc,EAAE,GAAG,CAAC,EACzD,qBAAqB,EAAE,2BAA2B,EAClD,SAAS,EAAE,SAAS,CAAC,cAAc,CAAC,GACnC,WAAW,CAAC,cAAc,CAAC,CAY7B;AAED,wBAAgB,sBAAsB,CACpC,cAAc,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAE3D,KAAK,EAAE,aAAa,CAAC;IACnB,OAAO,EAAE,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAChD,QAAQ,EAAE,CAAC,cAAc,EAAE,sBAAsB,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAC3E,iBAAiB,EAAE,iBAAiB,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IAC1D,SAAS,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;CACtC,CAAC,QAiCH"}

package/dist/react/useReadAndSubscribe.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useReadAndSubscribe = useReadAndSubscribe;
+exports.useSubscribeToMultiple = useSubscribeToMultiple;
+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, readerAst) {
+    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, readerAst);
+    return readOutDataAndRecords.item;
+}
+function useSubscribeToMultiple(items) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    (0, react_1.useEffect)(() => {
+        const cleanupFns = items.map(({ records, callback, fragmentReference, readerAst }) => {
+            return (0, cache_1.subscribe)(environment, records, fragmentReference, callback, readerAst);
+        });
+        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('.'),
+    ]);
+}

package/dist/react/useRerenderOnChange.d.ts

@@ -0,0 +1,8 @@
+import { WithEncounteredRecords } from '../core/read';
+import { FragmentReference } from '../core/FragmentReference';
+import type { ReaderAst } from '../core/reader';
+export declare function useRerenderOnChange<TReadFromStore extends {
+    parameters: object;
+    data: object;
+}>(encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>, fragmentReference: FragmentReference<any, any>, setEncounteredDataAndRecords: (data: WithEncounteredRecords<TReadFromStore>) => void, readerAst: ReaderAst<TReadFromStore>): void;
+//# sourceMappingURL=useRerenderOnChange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useRerenderOnChange.d.ts","sourceRoot":"","sources":["../../src/react/useRerenderOnChange.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,wBAAgB,mBAAmB,CACjC,cAAc,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAE3D,yBAAyB,EAAE,sBAAsB,CAAC,cAAc,CAAC,EACjE,iBAAiB,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC9C,4BAA4B,EAAE,CAC5B,IAAI,EAAE,sBAAsB,CAAC,cAAc,CAAC,KACzC,IAAI,EACT,SAAS,EAAE,SAAS,CAAC,cAAc,CAAC,QAoBrC"}

package/dist/react/useRerenderOnChange.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRerenderOnChange = useRerenderOnChange;
+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, readerAst) {
+    const environment = (0, IsographEnvironmentProvider_1.useIsographEnvironment)();
+    (0, react_1.useEffect)(() => {
+        return (0, cache_1.subscribe)(environment, encounteredDataAndRecords, fragmentReference, (newEncounteredDataAndRecords) => {
+            setEncounteredDataAndRecords(newEncounteredDataAndRecords);
+        }, readerAst);
+        // 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
+    }, []);
+}

package/dist/react/useResult.d.ts

@@ -0,0 +1,9 @@
+import { FragmentReference } from '../core/FragmentReference';
+import { NetworkRequestReaderOptions } from '../core/read';
+import { PromiseWrapper } from '../core/PromiseWrapper';
+export declare function useResult<TReadFromStore extends {
+    parameters: object;
+    data: object;
+}, TClientFieldValue>(fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>, partialNetworkRequestOptions?: Partial<NetworkRequestReaderOptions> | void): TClientFieldValue;
+export declare function maybeUnwrapNetworkRequest(networkRequest: PromiseWrapper<void, any>, networkRequestOptions: NetworkRequestReaderOptions): void;
+//# sourceMappingURL=useResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useResult.d.ts","sourceRoot":"","sources":["../../src/react/useResult.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAEL,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,cAAc,EAEf,MAAM,wBAAwB,CAAC;AAEhC,wBAAgB,SAAS,CACvB,cAAc,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC3D,iBAAiB,EAEjB,iBAAiB,EAAE,iBAAiB,CAAC,cAAc,EAAE,iBAAiB,CAAC,EACvE,4BAA4B,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAAG,IAAI,GACzE,iBAAiB,CAqCnB;AAED,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,EACzC,qBAAqB,EAAE,2BAA2B,QAWnD"}

package/dist/react/useResult.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useResult = useResult;
+exports.maybeUnwrapNetworkRequest = maybeUnwrapNetworkRequest;
+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, readerWithRefetchQueries.readerArtifact.readerAst);
+            const param = {
+                data: data,
+                parameters: fragmentReference.variables,
+            };
+            return readerWithRefetchQueries.readerArtifact.resolver(param);
+        }
+    }
+}
+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;
+    }
+}

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/isograph.config.json

@@ -0,0 +1,7 @@
+{
+  "project_root": "./src/tests",
+  "schema": "./schema.graphql",
+  "options": {
+    "on_invalid_id_type": "error"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Use Isograph with React",
   "homepage": "https://isograph.dev",
   "main": "dist/index.js",
@@ -10,25 +10,34 @@
   "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": "pnpm run test && pnpm run compile",
+    "tsc": "tsc",
+    "iso": "../../target/debug/isograph_cli --config ./isograph.config.json",
+    "iso-watch": "../../target/debug/isograph_cli --config ./isograph.config.json --watch"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.1.1",
+    "@isograph/disposable-types": "*",
     "@isograph/react-disposable-state": "*",
-    "react": "^18.2.0"
+    "@isograph/reference-counted-pointer": "*"
+  },
+  "peerDependencies": {
+    "react": "18.3.1"
   },
   "devDependencies": {
-    "@types/react": "^18.0.31",
+    "@babel/preset-typescript": "^7.24.7",
+    "@types/react": "18.3.1",
     "react-test-renderer": "^18.2.0",
-    "vitest": "^0.29.8",
-    "typescript": "^5.0.3"
+    "typescript": "5.6.3",
+    "vite-plugin-babel": "^1.2.0",
+    "vite-plugin-commonjs": "^0.10.1"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/isographlabs/isograph.git",
     "directory": "libs/isograph-react"
-  }
+  },
+  "sideEffects": false
 }

package/schema.graphql

@@ -0,0 +1,17 @@
+type Query {
+  me: Economist!
+  you: Economist!
+  node(id: ID!): Node
+  query: Query!
+}
+
+type Economist implements Node {
+  id: ID!
+  name: String!
+  predecessor: Economist
+  successor: Economist
+}
+
+interface Node {
+  id: ID!
+}

package/src/core/FragmentReference.ts

@@ -0,0 +1,49 @@
+import { type Link } 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 ExtractData<T> = T extends {
+  data: infer D extends object;
+}
+  ? D
+  : never;
+
+export type ExtractParameters<T> = T extends {
+  parameters: infer P extends Variables;
+}
+  ? P
+  : Variables;
+
+export type FragmentReference<
+  TReadFromStore extends { parameters: object; data: object },
+  TClientFieldValue,
+> = {
+  readonly kind: 'FragmentReference';
+  readonly readerWithRefetchQueries: PromiseWrapper<
+    ReaderWithRefetchQueries<TReadFromStore, TClientFieldValue>
+  >;
+  readonly root: Link;
+  readonly variables: ExtractParameters<TReadFromStore>;
+  readonly networkRequest: PromiseWrapper<void, any>;
+};
+
+export function stableIdForFragmentReference(
+  fragmentReference: FragmentReference<any, any>,
+): string {
+  return `${fragmentReference.root.__typename}/${fragmentReference.root.__link}/TODO_FRAGMENT_NAME/${serializeVariables(fragmentReference.variables ?? {})}`;
+}
+
+function serializeVariables(variables: Variables) {
+  let s = '';
+  const keys = Object.keys(variables);
+  keys.sort();
+  for (const key of keys) {
+    s += `${key}:${variables[key]},`;
+  }
+  return s;
+}

package/src/core/IsographEnvironment.ts

@@ -0,0 +1,192 @@
+import { ParentCache } from '@isograph/react-disposable-state';
+import { RetainedQuery } from './garbageCollection';
+import { WithEncounteredRecords } from './read';
+import { FragmentReference, Variables } from './FragmentReference';
+import { PromiseWrapper, wrapPromise } from './PromiseWrapper';
+import { IsographEntrypoint } from './entrypoint';
+import type { ReaderAst } from './reader';
+import { LogFunction, WrappedLogFunction } from './logging';
+
+export type ComponentOrFieldName = string;
+export type StringifiedArgs = string;
+type ComponentCache = {
+  [key: DataId]: {
+    [key: ComponentOrFieldName]: { [key: StringifiedArgs]: React.FC<any> };
+  };
+};
+
+export type FragmentSubscription<
+  TReadFromStore extends { parameters: object; data: object },
+> = {
+  readonly kind: 'FragmentSubscription';
+  readonly callback: (
+    newEncounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
+  ) => void;
+  /** The value read out from the previous call to readButDoNotEvaluate */
+  readonly encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>;
+  readonly fragmentReference: FragmentReference<TReadFromStore, any>;
+  readonly readerAst: ReaderAst<TReadFromStore>;
+};
+
+type AnyChangesToRecordSubscription = {
+  readonly kind: 'AnyChangesToRecord';
+  readonly callback: () => void;
+  readonly recordLink: Link;
+};
+
+type AnyRecordSubscription = {
+  readonly kind: 'AnyRecords';
+  readonly callback: () => void;
+};
+
+type Subscription =
+  | FragmentSubscription<{ parameters: object; data: object }>
+  | AnyChangesToRecordSubscription
+  | AnyRecordSubscription;
+type Subscriptions = Set<Subscription>;
+// Should this be a map?
+type CacheMap<T> = { [index: string]: ParentCache<T> };
+
+export type IsographEnvironment = {
+  readonly store: IsographStore;
+  readonly networkFunction: IsographNetworkFunction;
+  readonly missingFieldHandler: MissingFieldHandler | null;
+  readonly componentCache: ComponentCache;
+  readonly subscriptions: Subscriptions;
+  // N.B. this must be <any, any>, but all *usages* of this should go through
+  // a function that adds type parameters.
+  readonly fragmentCache: CacheMap<FragmentReference<any, any>>;
+  // TODO make this a CacheMap and add GC
+  readonly entrypointArtifactCache: Map<
+    string,
+    PromiseWrapper<IsographEntrypoint<any, any>>
+  >;
+  readonly retainedQueries: Set<RetainedQuery>;
+  readonly gcBuffer: Array<RetainedQuery>;
+  readonly gcBufferSize: number;
+  readonly loggers: Set<WrappedLogFunction>;
+};
+
+export type MissingFieldHandler = (
+  storeRecord: StoreRecord,
+  root: Link,
+  fieldName: string,
+  arguments_: { [index: string]: any } | null,
+  variables: Variables | null,
+) => Link | undefined;
+
+export type IsographNetworkFunction = (
+  queryText: string,
+  variables: Variables,
+) => Promise<any>;
+
+export type Link = {
+  readonly __link: DataId;
+  readonly __typename: TypeName;
+};
+
+export type DataTypeValue =
+  // N.B. undefined is here to support optional id's, but
+  // undefined should not *actually* be present in the store.
+  | undefined
+  // Singular scalar fields:
+  | number
+  | boolean
+  | string
+  | null
+  // Singular linked fields:
+  | Link
+  // Plural scalar and linked fields:
+  | DataTypeValue[];
+
+export type StoreRecord = {
+  [index: DataId | string]: DataTypeValue;
+  // TODO __typename?: T, which is restricted to being a concrete string
+  // TODO this shouldn't always be named id
+  readonly id?: DataId;
+};
+
+export type TypeName = string;
+export type DataId = string;
+
+export const ROOT_ID: DataId & '__ROOT' = '__ROOT';
+
+export type IsographStore = {
+  [index: TypeName]: {
+    [index: DataId]: StoreRecord | null;
+  } | null;
+  readonly Query: {
+    readonly __ROOT: StoreRecord;
+  };
+};
+
+const DEFAULT_GC_BUFFER_SIZE = 10;
+export function createIsographEnvironment(
+  store: IsographStore,
+  networkFunction: IsographNetworkFunction,
+  missingFieldHandler?: MissingFieldHandler | null,
+  logFunction?: LogFunction | null,
+): IsographEnvironment {
+  return {
+    store,
+    networkFunction,
+    missingFieldHandler: missingFieldHandler ?? null,
+    componentCache: {},
+    subscriptions: new Set(),
+    fragmentCache: {},
+    entrypointArtifactCache: new Map(),
+    retainedQueries: new Set(),
+    gcBuffer: [],
+    gcBufferSize: DEFAULT_GC_BUFFER_SIZE,
+    loggers: logFunction != null ? new Set([{ log: logFunction }]) : new Set(),
+  };
+}
+
+export function createIsographStore(): IsographStore {
+  return {
+    Query: {
+      [ROOT_ID]: {},
+    },
+  };
+}
+
+export function assertLink(link: DataTypeValue): Link | null | undefined {
+  if (Array.isArray(link)) {
+    throw new Error('Unexpected array');
+  }
+  if (link == null) {
+    return link;
+  }
+  if (typeof link === 'object') {
+    return link;
+  }
+  throw new Error('Invalid link');
+}
+
+export function getLink(maybeLink: DataTypeValue): Link | null {
+  if (
+    maybeLink != null &&
+    typeof maybeLink === 'object' &&
+    '__link' in maybeLink &&
+    maybeLink.__link != null &&
+    '__typename' in maybeLink &&
+    maybeLink.__typename != null
+  ) {
+    return maybeLink;
+  }
+  return null;
+}
+
+export function getOrLoadIsographArtifact(
+  environment: IsographEnvironment,
+  key: string,
+  loader: () => Promise<IsographEntrypoint<any, any>>,
+): PromiseWrapper<IsographEntrypoint<any, any>> {
+  const value = environment.entrypointArtifactCache.get(key);
+  if (value != null) {
+    return value;
+  }
+  const wrapped = wrapPromise(loader());
+  environment.entrypointArtifactCache.set(key, wrapped);
+  return wrapped;
+}