@isograph/react 0.1.0 → 0.2.0

package/src/react/useReadAndSubscribe.ts

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+import {
+  FragmentReference,
+  stableIdForFragmentReference,
+} from '../core/FragmentReference';
+import {
+  NetworkRequestReaderOptions,
+  readButDoNotEvaluate,
+  WithEncounteredRecords,
+} from '../core/read';
+import { useRerenderOnChange } from './useRerenderOnChange';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+import { subscribe } from '../core/cache';
+
+/**
+ * Read the data from a fragment reference and subscribe to updates.
+ */
+export function useReadAndSubscribe<TReadFromStore extends Object>(
+  fragmentReference: FragmentReference<TReadFromStore, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+): TReadFromStore {
+  const environment = useIsographEnvironment();
+  const [readOutDataAndRecords, setReadOutDataAndRecords] = useState(() =>
+    readButDoNotEvaluate(environment, fragmentReference, networkRequestOptions),
+  );
+  useRerenderOnChange(
+    readOutDataAndRecords,
+    fragmentReference,
+    setReadOutDataAndRecords,
+  );
+  return readOutDataAndRecords.item;
+}
+
+export function useSubscribeToMultiple<TReadFromStore extends Object>(
+  items: ReadonlyArray<{
+    records: WithEncounteredRecords<TReadFromStore>;
+    callback: (updatedRecords: WithEncounteredRecords<TReadFromStore>) => void;
+    fragmentReference: FragmentReference<TReadFromStore, any>;
+  }>,
+) {
+  const environment = useIsographEnvironment();
+  useEffect(
+    () => {
+      const cleanupFns = items.map(
+        ({ records, callback, fragmentReference }) => {
+          return 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 }) =>
+          stableIdForFragmentReference(fragmentReference),
+        )
+        .join('.'),
+    ],
+  );
+}

package/src/react/useRerenderOnChange.ts

@@ -0,0 +1,33 @@
+import { useEffect } from 'react';
+import { subscribe } from '../core/cache';
+import { WithEncounteredRecords } from '../core/read';
+import { FragmentReference } from '../core/FragmentReference';
+import { useIsographEnvironment } from './IsographEnvironmentProvider';
+
+// TODO add unit tests for this. Add integration tests that test
+// behavior when the encounteredRecords underneath a fragment change.
+export function useRerenderOnChange<TReadFromStore extends Object>(
+  encounteredDataAndRecords: WithEncounteredRecords<TReadFromStore>,
+  fragmentReference: FragmentReference<any, any>,
+  setEncounteredDataAndRecords: (
+    data: WithEncounteredRecords<TReadFromStore>,
+  ) => void,
+) {
+  const environment = useIsographEnvironment();
+  useEffect(() => {
+    return 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
+  }, []);
+}

package/src/react/useResult.ts

@@ -0,0 +1,65 @@
+import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
+import { FragmentReference } from '../core/FragmentReference';
+import { getOrCreateCachedComponent } from '../core/componentCache';
+import { useReadAndSubscribe } from './useReadAndSubscribe';
+import {
+  getNetworkRequestOptionsWithDefaults,
+  NetworkRequestReaderOptions,
+} from '../core/read';
+import {
+  getPromiseState,
+  PromiseWrapper,
+  readPromise,
+} from '../core/PromiseWrapper';
+
+export function useResult<TReadFromStore extends Object, TClientFieldValue>(
+  fragmentReference: FragmentReference<TReadFromStore, TClientFieldValue>,
+  partialNetworkRequestOptions?: Partial<NetworkRequestReaderOptions> | void,
+): TClientFieldValue {
+  const environment = useIsographEnvironment();
+  const networkRequestOptions = getNetworkRequestOptionsWithDefaults(
+    partialNetworkRequestOptions,
+  );
+
+  maybeUnwrapNetworkRequest(
+    fragmentReference.networkRequest,
+    networkRequestOptions,
+  );
+  const readerWithRefetchQueries = readPromise(
+    fragmentReference.readerWithRefetchQueries,
+  );
+
+  switch (readerWithRefetchQueries.readerArtifact.kind) {
+    case 'ComponentReaderArtifact': {
+      // @ts-expect-error
+      return getOrCreateCachedComponent(
+        environment,
+        readerWithRefetchQueries.readerArtifact.componentName,
+        fragmentReference,
+        networkRequestOptions,
+      );
+    }
+    case 'EagerReaderArtifact': {
+      const data = useReadAndSubscribe(
+        fragmentReference,
+        networkRequestOptions,
+      );
+      return readerWithRefetchQueries.readerArtifact.resolver(data);
+    }
+  }
+}
+
+export function maybeUnwrapNetworkRequest(
+  networkRequest: PromiseWrapper<void, any>,
+  networkRequestOptions: NetworkRequestReaderOptions,
+) {
+  const state = getPromiseState(networkRequest);
+  if (state.kind === 'Err' && networkRequestOptions.throwOnNetworkError) {
+    throw state.error;
+  } else if (
+    state.kind === 'Pending' &&
+    networkRequestOptions.suspendIfInFlight
+  ) {
+    throw state.promise;
+  }
+}

package/src/tests/__isograph/Query/meName/entrypoint.ts

@@ -0,0 +1,47 @@
+import type {IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArtifactWrapper} from '@isograph/react';
+import {Query__meName__param} from './param_type';
+import {Query__meName__output_type} from './output_type';
+import readerResolver from './resolver_reader';
+const nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[] = [];
+
+const queryText = 'query meName  {\
+  me {\
+    id,\
+    name,\
+  },\
+}';
+
+const normalizationAst: NormalizationAst = [
+  {
+    kind: "Linked",
+    fieldName: "me",
+    arguments: null,
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "id",
+        arguments: null,
+      },
+      {
+        kind: "Scalar",
+        fieldName: "name",
+        arguments: null,
+      },
+    ],
+  },
+];
+const artifact: IsographEntrypoint<
+  Query__meName__param,
+  Query__meName__output_type
+> = {
+  kind: "Entrypoint",
+  queryText,
+  normalizationAst,
+  readerWithRefetchQueries: {
+    kind: "ReaderWithRefetchQueries",
+    nestedRefetchQueries,
+    readerArtifact: readerResolver,
+  },
+};
+
+export default artifact;

package/src/tests/__isograph/Query/meName/output_type.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import { meNameField as resolver } from '../../../garbageCollection.test';
+export type Query__meName__output_type = ReturnType<typeof resolver>;

package/src/tests/__isograph/Query/meName/param_type.ts

@@ -0,0 +1,6 @@
+
+export type Query__meName__param = {
+  me: {
+    name: string,
+  },
+};

package/src/tests/__isograph/Query/meName/resolver_reader.ts

@@ -0,0 +1,32 @@
+import type { EagerReaderArtifact, ReaderAst } from '@isograph/react';
+import { Query__meName__param } from './param_type';
+import { Query__meName__output_type } from './output_type';
+import { meNameField as resolver } from '../../../garbageCollection.test';
+
+const readerAst: ReaderAst<Query__meName__param> = [
+  {
+    kind: "Linked",
+    fieldName: "me",
+    alias: null,
+    arguments: null,
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "name",
+        alias: null,
+        arguments: null,
+      },
+    ],
+  },
+];
+
+const artifact: EagerReaderArtifact<
+  Query__meName__param,
+  Query__meName__output_type
+> = {
+  kind: "EagerReaderArtifact",
+  resolver,
+  readerAst,
+};
+
+export default artifact;

package/src/tests/__isograph/Query/meNameSuccessor/entrypoint.ts

@@ -0,0 +1,83 @@
+import type {IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArtifactWrapper} from '@isograph/react';
+import {Query__meNameSuccessor__param} from './param_type';
+import {Query__meNameSuccessor__output_type} from './output_type';
+import readerResolver from './resolver_reader';
+const nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[] = [];
+
+const queryText = 'query meNameSuccessor  {\
+  me {\
+    id,\
+    name,\
+    successor {\
+      id,\
+      successor {\
+        id,\
+        name,\
+      },\
+    },\
+  },\
+}';
+
+const normalizationAst: NormalizationAst = [
+  {
+    kind: "Linked",
+    fieldName: "me",
+    arguments: null,
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "id",
+        arguments: null,
+      },
+      {
+        kind: "Scalar",
+        fieldName: "name",
+        arguments: null,
+      },
+      {
+        kind: "Linked",
+        fieldName: "successor",
+        arguments: null,
+        selections: [
+          {
+            kind: "Scalar",
+            fieldName: "id",
+            arguments: null,
+          },
+          {
+            kind: "Linked",
+            fieldName: "successor",
+            arguments: null,
+            selections: [
+              {
+                kind: "Scalar",
+                fieldName: "id",
+                arguments: null,
+              },
+              {
+                kind: "Scalar",
+                fieldName: "name",
+                arguments: null,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+];
+const artifact: IsographEntrypoint<
+  Query__meNameSuccessor__param,
+  Query__meNameSuccessor__output_type
+> = {
+  kind: "Entrypoint",
+  queryText,
+  normalizationAst,
+  readerWithRefetchQueries: {
+    kind: "ReaderWithRefetchQueries",
+    nestedRefetchQueries,
+    readerArtifact: readerResolver,
+  },
+};
+
+export default artifact;

package/src/tests/__isograph/Query/meNameSuccessor/output_type.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import { meNameField as resolver } from '../../../meNameSuccessor';
+export type Query__meNameSuccessor__output_type = ReturnType<typeof resolver>;

package/src/tests/__isograph/Query/meNameSuccessor/param_type.ts

@@ -0,0 +1,11 @@
+
+export type Query__meNameSuccessor__param = {
+  me: {
+    name: string,
+    successor: ({
+      successor: ({
+        name: string,
+      } | null),
+    } | null),
+  },
+};

package/src/tests/__isograph/Query/meNameSuccessor/resolver_reader.ts

@@ -0,0 +1,54 @@
+import type { EagerReaderArtifact, ReaderAst } from '@isograph/react';
+import { Query__meNameSuccessor__param } from './param_type';
+import { Query__meNameSuccessor__output_type } from './output_type';
+import { meNameField as resolver } from '../../../meNameSuccessor';
+
+const readerAst: ReaderAst<Query__meNameSuccessor__param> = [
+  {
+    kind: "Linked",
+    fieldName: "me",
+    alias: null,
+    arguments: null,
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "name",
+        alias: null,
+        arguments: null,
+      },
+      {
+        kind: "Linked",
+        fieldName: "successor",
+        alias: null,
+        arguments: null,
+        selections: [
+          {
+            kind: "Linked",
+            fieldName: "successor",
+            alias: null,
+            arguments: null,
+            selections: [
+              {
+                kind: "Scalar",
+                fieldName: "name",
+                alias: null,
+                arguments: null,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const artifact: EagerReaderArtifact<
+  Query__meNameSuccessor__param,
+  Query__meNameSuccessor__output_type
+> = {
+  kind: "EagerReaderArtifact",
+  resolver,
+  readerAst,
+};
+
+export default artifact;

package/src/tests/__isograph/Query/nodeField/entrypoint.ts

@@ -0,0 +1,46 @@
+import type {IsographEntrypoint, NormalizationAst, RefetchQueryNormalizationArtifactWrapper} from '@isograph/react';
+import {Query__nodeField__param} from './param_type';
+import {Query__nodeField__output_type} from './output_type';
+import readerResolver from './resolver_reader';
+const nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[] = [];
+
+const queryText = 'query nodeField ($id: ID!) {\
+  node____id___v_id: node(id: $id) {\
+    id,\
+  },\
+}';
+
+const normalizationAst: NormalizationAst = [
+  {
+    kind: "Linked",
+    fieldName: "node",
+    arguments: [
+      [
+        "id",
+        { kind: "Variable", name: "id" },
+      ],
+    ],
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "id",
+        arguments: null,
+      },
+    ],
+  },
+];
+const artifact: IsographEntrypoint<
+  Query__nodeField__param,
+  Query__nodeField__output_type
+> = {
+  kind: "Entrypoint",
+  queryText,
+  normalizationAst,
+  readerWithRefetchQueries: {
+    kind: "ReaderWithRefetchQueries",
+    nestedRefetchQueries,
+    readerArtifact: readerResolver,
+  },
+};
+
+export default artifact;

package/src/tests/__isograph/Query/nodeField/output_type.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import { nodeField as resolver } from '../../../nodeQuery';
+export type Query__nodeField__output_type = ReturnType<typeof resolver>;

package/src/tests/__isograph/Query/nodeField/param_type.ts

@@ -0,0 +1,6 @@
+
+export type Query__nodeField__param = {
+  node: ({
+    id: string,
+  } | null),
+};

package/src/tests/__isograph/Query/nodeField/resolver_reader.ts

@@ -0,0 +1,37 @@
+import type { EagerReaderArtifact, ReaderAst } from '@isograph/react';
+import { Query__nodeField__param } from './param_type';
+import { Query__nodeField__output_type } from './output_type';
+import { nodeField as resolver } from '../../../nodeQuery';
+
+const readerAst: ReaderAst<Query__nodeField__param> = [
+  {
+    kind: "Linked",
+    fieldName: "node",
+    alias: null,
+    arguments: [
+      [
+        "id",
+        { kind: "Variable", name: "id" },
+      ],
+    ],
+    selections: [
+      {
+        kind: "Scalar",
+        fieldName: "id",
+        alias: null,
+        arguments: null,
+      },
+    ],
+  },
+];
+
+const artifact: EagerReaderArtifact<
+  Query__nodeField__param,
+  Query__nodeField__output_type
+> = {
+  kind: "EagerReaderArtifact",
+  resolver,
+  readerAst,
+};
+
+export default artifact;

package/src/tests/__isograph/iso.ts

@@ -0,0 +1,88 @@
+import type {IsographEntrypoint} from '@isograph/react';
+import { Query__meNameSuccessor__param } from './Query/meNameSuccessor/param_type';
+import { Query__meName__param } from './Query/meName/param_type';
+import { Query__nodeField__param } from './Query/nodeField/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';
+
+// 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> = <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> = <TClientFieldReturn, TComponentProps = Record<string, 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<'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(_isographLiteralText: string):
+  | IdentityWithParam<any>
+  | IdentityWithParamComponent<any>
+  | IsographEntrypoint<any, any>
+{
+  return function identity<TClientFieldReturn>(
+    clientFieldOrEntrypoint: (param: any) => TClientFieldReturn,
+  ): (param: any) => TClientFieldReturn {
+    return clientFieldOrEntrypoint;
+  };
+}