@isograph/react 0.1.1 → 0.3.0

package/src/tests/__isograph/iso.ts

@@ -0,0 +1,99 @@
+import type { IsographEntrypoint } from '@isograph/react';
+import { type Query__meNameSuccessor__param } from './Query/meNameSuccessor/param_type';
+import { type Query__meName__param } from './Query/meName/param_type';
+import { type Query__nodeField__param } from './Query/nodeField/param_type';
+import { type Query__subquery__param } from './Query/subquery/param_type';
+import entrypoint_Query__meNameSuccessor from '../__isograph/Query/meNameSuccessor/entrypoint';
+import entrypoint_Query__meName from '../__isograph/Query/meName/entrypoint';
+import entrypoint_Query__nodeField from '../__isograph/Query/nodeField/entrypoint';
+import entrypoint_Query__subquery from '../__isograph/Query/subquery/entrypoint';
+
+// This is the type given to regular client fields.
+// This means that the type of the exported iso literal is exactly
+// the type of the passed-in function, which takes one parameter
+// of type TParam.
+type IdentityWithParam<TParam extends object> = <TClientFieldReturn>(
+  clientField: (param: TParam) => TClientFieldReturn
+) => (param: TParam) => TClientFieldReturn;
+
+// This is the type given it to client fields with @component.
+// This means that the type of the exported iso literal is exactly
+// the type of the passed-in function, which takes two parameters.
+// The first has type TParam, and the second has type TComponentProps.
+//
+// TComponentProps becomes the types of the props you must pass
+// whenever the @component field is rendered.
+type IdentityWithParamComponent<TParam extends object> = <
+  TClientFieldReturn,
+  TComponentProps = Record<PropertyKey, never>,
+>(
+  clientComponentField: (data: TParam, componentProps: TComponentProps) => TClientFieldReturn
+) => (data: TParam, componentProps: TComponentProps) => TClientFieldReturn;
+
+type WhitespaceCharacter = ' ' | '\t' | '\n';
+type Whitespace<In> = In extends `${WhitespaceCharacter}${infer In}`
+  ? Whitespace<In>
+  : In;
+
+// This is a recursive TypeScript type that matches strings that
+// start with whitespace, followed by TString. So e.g. if we have
+// ```
+// export function iso<T>(
+//   isographLiteralText: T & MatchesWhitespaceAndString<'field Query.foo', T>
+// ): Bar;
+// ```
+// then, when you call
+// ```
+// const x = iso(`
+//   field Query.foo ...
+// `);
+// ```
+// then the type of `x` will be `Bar`, both in VSCode and when running
+// tsc. This is how we achieve type safety — you can only use fields
+// that you have explicitly selected.
+type MatchesWhitespaceAndString<
+  TString extends string,
+  T
+> = Whitespace<T> extends `${TString}${string}` ? T : never;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'field Query.meNameSuccessor', T>
+): IdentityWithParam<Query__meNameSuccessor__param>;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'field Query.meName', T>
+): IdentityWithParam<Query__meName__param>;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'field Query.nodeField', T>
+): IdentityWithParam<Query__nodeField__param>;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'field Query.subquery', T>
+): IdentityWithParam<Query__subquery__param>;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'entrypoint Query.meNameSuccessor', T>
+): typeof entrypoint_Query__meNameSuccessor;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'entrypoint Query.meName', T>
+): typeof entrypoint_Query__meName;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'entrypoint Query.nodeField', T>
+): typeof entrypoint_Query__nodeField;
+
+export function iso<T>(
+  param: T & MatchesWhitespaceAndString<'entrypoint Query.subquery', T>
+): typeof entrypoint_Query__subquery;
+
+export function iso(_isographLiteralText: string):
+  | IdentityWithParam<any>
+  | IdentityWithParamComponent<any>
+  | IsographEntrypoint<any, any>
+{
+  throw new Error('iso: Unexpected invocation at runtime. Either the Babel transform ' +
+      'was not set up, or it failed to identify this call site. Make sure it ' +
+      'is being used verbatim as `iso`.');
+}

package/src/tests/garbageCollection.test.ts

@@ -0,0 +1,142 @@
+import { describe, test, expect } from 'vitest';
+import {
+  ROOT_ID,
+  createIsographEnvironment,
+  type IsographStore,
+} from '../core/IsographEnvironment';
+import {
+  garbageCollectEnvironment,
+  retainQuery,
+} from '../core/garbageCollection';
+import { iso } from './__isograph/iso';
+import { nodeFieldRetainedQuery } from './nodeQuery';
+
+const getDefaultStore = (): IsographStore => ({
+  Query: {
+    [ROOT_ID]: {
+      me: { __link: '0', __typename: 'Economist' },
+      you: { __link: '1', __typename: 'Economist' },
+      node____id___0: {
+        __link: '0',
+        __typename: 'Economist',
+      },
+    },
+  },
+  Economist: {
+    0: {
+      __typename: 'Economist',
+      id: '0',
+      name: 'Jeremy Bentham',
+      successor: { __link: '1', __typename: 'Economist' },
+    },
+    1: {
+      __typename: 'Economist',
+      id: '1',
+      name: 'John Stuart Mill',
+      predecessor: { __link: '0', __typename: 'Economist' },
+      successor: { __link: '2', __typename: 'Economist' },
+    },
+    2: {
+      __typename: 'Economist',
+      id: '2',
+      name: 'Henry Sidgwick',
+      predecessor: { __link: '1', __typename: 'Economist' },
+    },
+  },
+});
+
+export const meNameField = iso(`
+  field Query.meName {
+    me {
+      name
+    }
+  }
+`)(() => {});
+import { meNameSuccessorRetainedQuery } from './meNameSuccessor';
+const meNameEntrypoint = iso(`entrypoint Query.meName`);
+const meNameRetainedQuery = {
+  normalizationAst: meNameEntrypoint.networkRequestInfo.normalizationAst,
+  variables: {},
+  root: { __link: ROOT_ID, __typename: 'Query' },
+};
+
+describe('garbage collection', () => {
+  test('Unreferenced records should be garbage collected', () => {
+    const store = getDefaultStore();
+    const environment = createIsographEnvironment(
+      store,
+      null as any,
+      null as any,
+    );
+
+    expect(store.Economist?.[1]).not.toBe(undefined);
+
+    // TODO enable babel so we don't have to do this
+    retainQuery(environment, meNameRetainedQuery);
+    garbageCollectEnvironment(environment);
+
+    expect(store.Economist?.[1]).toBe(undefined);
+  });
+
+  test('Referenced records should not be garbage collected', () => {
+    const store = getDefaultStore();
+    const environment = createIsographEnvironment(
+      store,
+      null as any,
+      null as any,
+    );
+
+    expect(store.Economist?.[0]).not.toBe(undefined);
+
+    // TODO enable babel so we don't have to do this
+    retainQuery(environment, meNameRetainedQuery);
+    garbageCollectEnvironment(environment);
+
+    expect(store.Economist?.[0]).not.toBe(undefined);
+  });
+
+  test('Referenced records should not be garbage collected, and this should work with variables', () => {
+    const store = getDefaultStore();
+    const environment = createIsographEnvironment(
+      store,
+      null as any,
+      null as any,
+    );
+
+    expect(store.Economist?.[0]).not.toBe(undefined);
+
+    retainQuery(environment, nodeFieldRetainedQuery);
+    garbageCollectEnvironment(environment);
+
+    expect(store.Economist?.[0]).not.toBe(undefined);
+  });
+
+  test('Referenced records should not be garbage collected, and this should work through multiple levels', () => {
+    const store = getDefaultStore();
+    const environment = createIsographEnvironment(
+      store,
+      null as any,
+      null as any,
+    );
+
+    retainQuery(environment, meNameSuccessorRetainedQuery);
+    garbageCollectEnvironment(environment);
+
+    expect(store.Economist?.[0]).not.toBe(undefined);
+    expect(store.Economist?.[1]).not.toBe(undefined);
+    expect(store.Economist?.[2]).not.toBe(undefined);
+  });
+
+  test('ROOT_ID should be garbage collected, if there are no retained queries', () => {
+    const store = getDefaultStore();
+    const environment = createIsographEnvironment(
+      store,
+      null as any,
+      null as any,
+    );
+    garbageCollectEnvironment(environment);
+
+    expect(store.Query?.[ROOT_ID]).toBe(undefined);
+    expect(store.Economist?.[0]).toBe(undefined);
+  });
+});

package/src/tests/meNameSuccessor.ts

@@ -0,0 +1,25 @@
+import { ROOT_ID } from '../core/IsographEnvironment';
+import { iso } from './__isograph/iso';
+
+export const meNameField = iso(`
+  field Query.meNameSuccessor {
+    me {
+      name
+      successor {
+        successor {
+          name
+        }
+      }
+    }
+  }
+`)(() => {});
+const meNameSuccessorEntrypoint = iso(`entrypoint Query.meNameSuccessor`);
+export const meNameSuccessorRetainedQuery = {
+  normalizationAst:
+    meNameSuccessorEntrypoint.networkRequestInfo.normalizationAst,
+  variables: {},
+  root: {
+    __link: ROOT_ID,
+    __typename: 'Query',
+  },
+};

package/src/tests/nodeQuery.ts

@@ -0,0 +1,19 @@
+import { RetainedQuery } from '../core/garbageCollection';
+import { ROOT_ID } from '../core/IsographEnvironment';
+import { iso } from './__isograph/iso';
+
+// TODO investigate why this can't be in garbageCollection.test.ts without
+// typescript incorrectly thinking it is referenced in its own initializer
+export const nodeField = iso(`
+  field Query.nodeField($id: ID!) {
+    node(id: $id) {
+      id
+    }
+  }
+`)(() => {});
+const nodeFieldEntrypoint = iso(`entrypoint Query.nodeField`);
+export const nodeFieldRetainedQuery: RetainedQuery = {
+  normalizationAst: nodeFieldEntrypoint.networkRequestInfo.normalizationAst,
+  variables: { id: 0 },
+  root: { __link: ROOT_ID, __typename: 'Query' },
+};

package/src/tests/normalizeData.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test, vi } from 'vitest';
+import { getOrCreateCacheForArtifact, normalizeData } from '../core/cache';
+import {
+  createIsographEnvironment,
+  createIsographStore,
+  ROOT_ID,
+  type IsographStore,
+} from '../core/IsographEnvironment';
+import {
+  readButDoNotEvaluate,
+  type WithEncounteredRecords,
+} from '../core/read';
+import { iso } from './__isograph/iso';
+import type { Query__subquery__param } from './__isograph/Query/subquery/param_type';
+
+export const subquery = iso(`
+  field Query.subquery($id: ID!) {
+    query {
+      node(id: $id) {
+        id
+      }
+    }
+  }
+`)(() => {});
+
+const entrypoint = iso(`entrypoint Query.subquery`);
+
+describe('normalizeData', () => {
+  test('nested Query should be normalized', () => {
+    const store = createIsographStore();
+    const networkFunction = vi
+      .fn()
+      .mockRejectedValue(new Error('Fetch failed'));
+    const environment = createIsographEnvironment(store, networkFunction);
+
+    normalizeData(
+      environment,
+      entrypoint.networkRequestInfo.normalizationAst,
+      {
+        query: { node____id___v_id: { __typename: 'Economist', id: '1' } },
+      },
+      { id: '1' },
+      entrypoint.readerWithRefetchQueries.nestedRefetchQueries,
+      { __link: ROOT_ID, __typename: entrypoint.concreteType },
+    );
+
+    expect(store).toStrictEqual({
+      Economist: {
+        '1': {
+          __typename: 'Economist',
+          id: '1',
+        },
+      },
+      Query: {
+        [ROOT_ID]: {
+          node____id___1: {
+            __typename: 'Economist',
+            __link: '1',
+          },
+          query: {
+            __link: ROOT_ID,
+            __typename: 'Query',
+          },
+        },
+      },
+    } satisfies IsographStore);
+  });
+});
+
+describe('readData', () => {
+  test('nested Query should be read', () => {
+    const store: IsographStore = {
+      Economist: {
+        '1': {
+          __typename: 'Economist',
+          id: '1',
+        },
+      },
+      Query: {
+        [ROOT_ID]: {
+          node____id___1: {
+            __typename: 'Economist',
+            __link: '1',
+          },
+          query: {
+            __link: ROOT_ID,
+            __typename: 'Query',
+          },
+        },
+      },
+    };
+    const networkFunction = vi
+      .fn()
+      .mockRejectedValue(new Error('Fetch failed'));
+    const environment = createIsographEnvironment(store, networkFunction);
+    const [_cacheItem, item, _disposeOfTemporaryRetain] =
+      getOrCreateCacheForArtifact(environment, entrypoint, {
+        id: '1',
+      }).getOrPopulateAndTemporaryRetain();
+
+    const data = readButDoNotEvaluate(environment, item, {
+      suspendIfInFlight: true,
+      throwOnNetworkError: false,
+    });
+
+    expect(data).toStrictEqual({
+      encounteredRecords: new Map([
+        ['Economist', new Set(['1'])],
+        ['Query', new Set([ROOT_ID])],
+      ]),
+      item: {
+        query: {
+          node: {
+            id: '1',
+          },
+        },
+      },
+    } satisfies WithEncounteredRecords<Query__subquery__param>);
+  });
+});

package/src/tests/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "allowImportingTsExtensions": true,
+    "paths": {
+      "@isograph/react": ["../index.ts"]
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.pkg.json",
+  "compilerOptions": {
+    "noEmit": true
+  }
+}

package/tsconfig.pkg.json

@@ -7,5 +7,11 @@
     "jsx": "react",
     "lib": ["es2017", "DOM"]
   },
-  "include": ["./**/*.ts", "./**/*.tsx"]
+  "include": ["./**/*.ts", "./**/*.tsx"],
+  "exclude": [
+    "./src/tests/**/*",
+    "./vitest.config.ts",
+    "**/node_modules",
+    "**/dist"
+  ]
 }

package/vitest.config.ts

@@ -0,0 +1,20 @@
+import babel from 'vite-plugin-babel';
+import commonjs from 'vite-plugin-commonjs';
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  plugins: [
+    babel({
+      filter: /\.[jt]sx?$/,
+      babelConfig: {
+        presets: ['@babel/preset-typescript'],
+        plugins: [require('../isograph-babel-plugin/BabelPluginIsograph')],
+      },
+    }),
+    commonjs({
+      advanced: {
+        importRules: 'merge',
+      },
+    }),
+  ],
+});

package/dist/EntrypointReader.d.ts

@@ -1,6 +0,0 @@
-import * as React from 'react';
-import { ExtractReadFromStore, IsographEntrypoint, type FragmentReference } from './index';
-export declare function EntrypointReader<TEntrypoint extends IsographEntrypoint<any, React.FC<any>>>(props: {
-    queryReference: FragmentReference<ExtractReadFromStore<TEntrypoint>, React.FC<any>>;
-    additionalProps?: any | void;
-}): ReturnType<React.FC<any>>;

package/dist/IsographEnvironment.d.ts

@@ -1,56 +0,0 @@
-import { ReactNode } from 'react';
-import * as React from 'react';
-import { ParentCache } from '@isograph/isograph-react-disposable-state';
-export declare const IsographEnvironmentContext: React.Context<IsographEnvironment | null>;
-type ComponentName = string;
-type StringifiedArgs = string;
-type ComponentCache = {
-    [key: DataId]: {
-        [key: ComponentName]: {
-            [key: StringifiedArgs]: React.FC<any>;
-        };
-    };
-};
-export type Subscriptions = Set<() => void>;
-type SuspenseCache = {
-    [index: string]: ParentCache<any>;
-};
-export type IsographEnvironment = {
-    store: IsographStore;
-    networkFunction: IsographNetworkFunction;
-    missingFieldHandler: MissingFieldHandler | null;
-    componentCache: ComponentCache;
-    subscriptions: Subscriptions;
-    suspenseCache: SuspenseCache;
-};
-export type MissingFieldHandler = (storeRecord: StoreRecord, root: DataId, fieldName: string, arguments_: {
-    [index: string]: any;
-} | null, variables: {
-    [index: string]: any;
-} | null) => Link | undefined;
-export type IsographNetworkFunction = (queryText: string, variables: object) => Promise<any>;
-export type Link = {
-    __link: DataId;
-};
-export type DataTypeValue = undefined | number | boolean | string | null | Link | DataTypeValue[];
-export type StoreRecord = {
-    [index: DataId | string]: DataTypeValue;
-    id?: DataId;
-};
-export type DataId = string;
-export declare const ROOT_ID: DataId & '__ROOT';
-export type IsographStore = {
-    [index: DataId]: StoreRecord | null;
-    __ROOT: StoreRecord;
-};
-export type IsographEnvironmentProviderProps = {
-    environment: IsographEnvironment;
-    children: ReactNode;
-};
-export declare function IsographEnvironmentProvider({ environment, children, }: IsographEnvironmentProviderProps): React.JSX.Element;
-export declare function useIsographEnvironment(): IsographEnvironment;
-export declare function createIsographEnvironment(store: IsographStore, networkFunction: IsographNetworkFunction, missingFieldHandler?: MissingFieldHandler): IsographEnvironment;
-export declare function createIsographStore(): {
-    __ROOT: {};
-};
-export {};

package/dist/PromiseWrapper.d.ts

@@ -1,13 +0,0 @@
-declare const NOT_SET: Symbol;
-type NotSet = typeof NOT_SET;
-/**
- * Invariant:
- * Before the promise is resolved, value becomes non-null.
- */
-export type PromiseWrapper<T> = {
-    promise: Promise<T>;
-    value: Exclude<T, NotSet> | NotSet;
-};
-export declare function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T>;
-export declare function useReadPromise<T>(p: PromiseWrapper<T>): T;
-export {};

package/dist/PromiseWrapper.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useReadPromise = exports.wrapPromise = void 0;
-const NOT_SET = Symbol('NOT_SET');
-function wrapPromise(promise) {
-    // TODO confirm suspense works if the promise is already resolved.
-    const wrapper = { promise, value: NOT_SET };
-    promise.then((v) => {
-        // T is assignable to Exclude<T, Symbol> | Symbol
-        wrapper.value = v;
-    });
-    return wrapper;
-}
-exports.wrapPromise = wrapPromise;
-function useReadPromise(p) {
-    if (p.value !== NOT_SET) {
-        // Safety: p.value is either NOT_SET or an actual value.
-        return p.value;
-    }
-    throw p.promise;
-}
-exports.useReadPromise = useReadPromise;

package/dist/cache.d.ts

@@ -1,26 +0,0 @@
-import { ItemCleanupPair, ParentCache } from '@isograph/react-disposable-state';
-import { PromiseWrapper } from './PromiseWrapper';
-import { IsographEntrypoint, NormalizationLinkedField, NormalizationScalarField, ReaderLinkedField, ReaderScalarField } from './index';
-import { type IsographEnvironment } from './IsographEnvironment';
-declare global {
-    interface Window {
-        __LOG: boolean;
-    }
-}
-/**
- * Creates a copy of the provided value, ensuring any nested objects have their
- * keys sorted such that equivalent values would have identical JSON.stringify
- * results.
- */
-export declare function stableCopy<T>(value: T): T;
-type IsoResolver = IsographEntrypoint<any, any>;
-export declare function getOrCreateCacheForArtifact<T>(environment: IsographEnvironment, artifact: IsographEntrypoint<any, T>, variables: object): ParentCache<PromiseWrapper<T>>;
-export declare function makeNetworkRequest<T>(environment: IsographEnvironment, artifact: IsoResolver, variables: object): ItemCleanupPair<PromiseWrapper<T>>;
-export declare function subscribe(environment: IsographEnvironment, callback: () => void): () => void;
-export declare function onNextChange(environment: IsographEnvironment): Promise<void>;
-export declare function getParentRecordKey(astNode: NormalizationLinkedField | NormalizationScalarField | ReaderLinkedField | ReaderScalarField, variables: {
-    [index: string]: string;
-}): string;
-export declare const FIRST_SPLIT_KEY = "____";
-export declare const SECOND_SPLIT_KEY = "___";
-export {};