@isograph/react 0.2.0 → 0.3.1

package/src/core/reader.ts

@@ -1,48 +1,66 @@
 import { Factory } from '@isograph/disposable-types';
-import { FragmentReference } from './FragmentReference';
-import {
-  ComponentOrFieldName,
-  DataId,
-  IsographEnvironment,
-} from './IsographEnvironment';
+import { FetchOptions } from './check';
 import {
   IsographEntrypoint,
   IsographEntrypointLoader,
   RefetchQueryNormalizationArtifact,
   RefetchQueryNormalizationArtifactWrapper,
 } from './entrypoint';
+import {
+  ExtractParameters,
+  FragmentReference,
+  type UnknownTReadFromStore,
+} from './FragmentReference';
+import {
+  ComponentOrFieldName,
+  IsographEnvironment,
+  type Link,
+} from './IsographEnvironment';
 import { Arguments } from './util';
 
 export type TopLevelReaderArtifact<
-  TReadFromStore extends Object,
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
-  TComponentProps extends Record<string, never>,
+  TComponentProps extends Record<PropertyKey, never>,
 > =
   | EagerReaderArtifact<TReadFromStore, TClientFieldValue>
   | ComponentReaderArtifact<TReadFromStore, TComponentProps>;
 
 export type EagerReaderArtifact<
-  TReadFromStore extends Object,
+  TReadFromStore extends UnknownTReadFromStore,
   TClientFieldValue,
 > = {
   readonly kind: 'EagerReaderArtifact';
+  readonly fieldName: string;
   readonly readerAst: ReaderAst<TReadFromStore>;
-  readonly resolver: (data: TReadFromStore) => TClientFieldValue;
+  readonly resolver: (
+    data: ResolverFirstParameter<TReadFromStore>,
+  ) => TClientFieldValue;
+  readonly hasUpdatable: boolean;
 };
 
 export type ComponentReaderArtifact<
-  TReadFromStore extends Object,
-  TComponentProps extends Record<string, unknown> = Record<string, never>,
+  TReadFromStore extends UnknownTReadFromStore,
+  TComponentProps extends Record<string, unknown> = Record<PropertyKey, never>,
 > = {
   readonly kind: 'ComponentReaderArtifact';
-  readonly componentName: ComponentOrFieldName;
+  readonly fieldName: ComponentOrFieldName;
   readonly readerAst: ReaderAst<TReadFromStore>;
   readonly resolver: (
-    data: TReadFromStore,
+    data: ResolverFirstParameter<TReadFromStore>,
     runtimeProps: TComponentProps,
   ) => React.ReactNode;
+  readonly hasUpdatable: boolean;
 };
 
+export type ResolverFirstParameter<
+  TReadFromStore extends UnknownTReadFromStore,
+> = Pick<TReadFromStore, 'data' | 'parameters' | 'startUpdate'>;
+
+export type StartUpdate<UpdatableData> = (
+  updater: (updatableData: UpdatableData) => void,
+) => void;
+
 export type RefetchReaderArtifact = {
   readonly kind: 'RefetchReaderArtifact';
   readonly readerAst: ReaderAst<unknown>;
@@ -53,7 +71,7 @@ export type RefetchReaderArtifact = {
     variables: any,
     // TODO type this better
     filteredVariables: any,
-    rootId: DataId,
+    rootLink: Link,
     readerArtifact: TopLevelReaderArtifact<any, any, any> | null,
     // TODO type this better
     nestedRefetchQueries: RefetchQueryNormalizationArtifactWrapper[],
@@ -65,7 +83,8 @@ export type ReaderAstNode =
   | ReaderLinkedField
   | ReaderNonLoadableResolverField
   | ReaderImperativelyLoadedField
-  | ReaderLoadableField;
+  | ReaderLoadableField
+  | ReaderLinkField;
 
 // @ts-ignore
 export type ReaderAst<TReadFromStore> = ReadonlyArray<ReaderAstNode>;
@@ -75,13 +94,25 @@ export type ReaderScalarField = {
   readonly fieldName: string;
   readonly alias: string | null;
   readonly arguments: Arguments | null;
+  readonly isUpdatable: boolean;
 };
+
+export type ReaderLinkField = {
+  readonly kind: 'Link';
+  readonly alias: string;
+};
+
 export type ReaderLinkedField = {
   readonly kind: 'Linked';
   readonly fieldName: string;
   readonly alias: string | null;
   readonly selections: ReaderAst<unknown>;
   readonly arguments: Arguments | null;
+  readonly condition: EagerReaderArtifact<
+    { data: object; parameters: any; startUpdate?: StartUpdate<object> },
+    boolean | Link | null
+  > | null;
+  readonly isUpdatable: boolean;
 };
 
 export type ReaderNonLoadableResolverField = {
@@ -114,11 +145,11 @@ export type ReaderLoadableField = {
 
   // TODO we should not type these as any
   readonly entrypoint:
-    | IsographEntrypoint<any, any>
+    | IsographEntrypoint<any, any, any>
     | IsographEntrypointLoader<any, any>;
 };
 
-type StableId = string;
+export type StableId = string;
 /// Why is LoadableField the way it is? Let's work backwards.
 ///
 /// We ultimately need a stable id (for deduplication) and a way to produce a
@@ -128,6 +159,15 @@ type StableId = string;
 /// Passing TArgs to the LoadableField should be cheap and do no "actual" work,
 /// except to stringify the args or whatnot. Calling the factory can be
 /// expensive. For example, doing so will probably trigger a network request.
-export type LoadableField<TArgs, TResult> = (
-  args: TArgs,
-) => [StableId, Factory<FragmentReference<any, TResult>>];
+export type LoadableField<
+  TReadFromStore extends UnknownTReadFromStore,
+  TResult,
+  TArgs = ExtractParameters<TReadFromStore>,
+> = (
+  args: TArgs | void,
+  // Note: fetchOptions is not nullable here because a LoadableField is not a
+  // user-facing API. Users should only interact with LoadableFields via APIs
+  // like useClientSideDefer. These APIs should have a nullable fetchOptions
+  // parameter, and provide a default value ({}) to the LoadableField.
+  fetchOptions: FetchOptions<TResult>,
+) => [StableId, Factory<FragmentReference<TReadFromStore, TResult>>];

package/src/core/startUpdate.ts

@@ -0,0 +1,28 @@
+import {
+  stableIdForFragmentReference,
+  type ExtractStartUpdate,
+  type FragmentReference,
+  type UnknownTReadFromStore,
+} from './FragmentReference';
+import type { IsographEnvironment } from './IsographEnvironment';
+
+export function getOrCreateCachedStartUpdate<
+  TReadFromStore extends UnknownTReadFromStore,
+>(
+  environment: IsographEnvironment,
+  fragmentReference: FragmentReference<TReadFromStore, any>,
+  eagerResolverName: string,
+): ExtractStartUpdate<TReadFromStore> {
+  return (environment.eagerReaderCache[
+    stableIdForFragmentReference(fragmentReference, eagerResolverName)
+  ] ??= createStartUpdate(environment, fragmentReference));
+}
+
+export function createStartUpdate<TReadFromStore extends UnknownTReadFromStore>(
+  _environment: IsographEnvironment,
+  _fragmentReference: FragmentReference<TReadFromStore, any>,
+): ExtractStartUpdate<TReadFromStore> {
+  return (_updater) => {
+    // TODO start update
+  };
+}

package/src/core/util.ts

@@ -1,5 +1,9 @@
 export type ExtractSecondParam<T extends (arg1: any, arg2: any) => any> =
   T extends (arg1: any, arg2: infer P) => any ? P : never;
+export type CombineWithIntrinsicAttributes<T> =
+  T extends Record<PropertyKey, never>
+    ? JSX.IntrinsicAttributes
+    : T & JSX.IntrinsicAttributes;
 
 export type Arguments = Argument[];
 export type Argument = [ArgumentName, ArgumentValue];
@@ -20,4 +24,8 @@ export type ArgumentValue =
   | {
       readonly kind: 'Enum';
       readonly value: string;
+    }
+  | {
+      readonly kind: 'Object';
+      readonly value: Arguments;
     };

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   unretainQuery,
   type RetainedQuery,
   garbageCollectEnvironment,
+  type DidUnretainSomeQuery,
 } from './core/garbageCollection';
 export {
   type PromiseWrapper,
@@ -10,8 +11,20 @@ export {
   getPromiseState,
   wrapResolvedValue,
   wrapPromise,
+  type PromiseState,
+  type Result,
+  type AnyError,
+  type NotSet,
+  NOT_SET,
 } from './core/PromiseWrapper';
-export { subscribe, normalizeData } from './core/cache';
+export {
+  subscribe,
+  normalizeData,
+  type NetworkResponseObject,
+  type NetworkResponseValue,
+  type NetworkResponseScalarValue,
+  type EncounteredIds,
+} from './core/cache';
 export { makeNetworkRequest } from './core/makeNetworkRequest';
 export {
   ROOT_ID,
@@ -20,11 +33,21 @@ export {
   type IsographEnvironment,
   type IsographNetworkFunction,
   type IsographStore,
+  type MissingFieldHandler,
   type Link,
   type StoreRecord,
+  type CacheMap,
   createIsographEnvironment,
   createIsographStore,
-  defaultMissingFieldHandler,
+  type FieldCache,
+  type Subscriptions,
+  type Subscription,
+  type TypeName,
+  type FragmentSubscription,
+  type AnyChangesToRecordSubscription,
+  type AnyRecordSubscription,
+  type ComponentOrFieldName,
+  type StringifiedArgs,
 } from './core/IsographEnvironment';
 export {
   type EagerReaderArtifact,
@@ -37,10 +60,18 @@ export {
   type ReaderScalarField,
   type TopLevelReaderArtifact,
   type LoadableField,
+  type StableId,
+  type ResolverFirstParameter,
+  type ReaderImperativelyLoadedField,
+  type ReaderLoadableField,
+  type ReaderLinkField,
+  type StartUpdate,
 } from './core/reader';
 export {
   type NormalizationAst,
   type NormalizationAstNode,
+  type NormalizationAstNodes,
+  type NormalizationAstLoader,
   type NormalizationLinkedField,
   type NormalizationScalarField,
   type IsographEntrypoint,
@@ -50,10 +81,20 @@ export {
   type ExtractProps,
   type ExtractReadFromStore,
   type ExtractResolverResult,
+  type NetworkRequestInfo,
+  type NormalizationInlineFragment,
+  type ReaderWithRefetchQueries,
+  type IsographEntrypointLoader,
 } from './core/entrypoint';
-export { readButDoNotEvaluate } from './core/read';
+export {
+  readButDoNotEvaluate,
+  type WithEncounteredRecords,
+  type NetworkRequestReaderOptions,
+  type ReadDataResult,
+} from './core/read';
 export {
   type ExtractSecondParam,
+  type CombineWithIntrinsicAttributes,
   type Argument,
   type ArgumentName,
   type ArgumentValue,
@@ -62,16 +103,43 @@ export {
 export {
   type FragmentReference,
   type Variables,
+  type ExtractParameters,
+  type ExtractData,
+  type UnknownTReadFromStore,
   stableIdForFragmentReference,
+  type ExtractStartUpdate,
+  type VariableValue,
+  type StableIdForFragmentReference,
 } from './core/FragmentReference';
+export {
+  type LogMessage,
+  type LogFunction,
+  type WrappedLogFunction,
+  logMessage,
+  registerLogger,
+} from './core/logging';
+export {
+  check,
+  type CheckResult,
+  type FetchOptions,
+  type RequiredFetchOptions,
+  type ShouldFetch,
+  type RequiredShouldFetch,
+} from './core/check';
 
 export {
   IsographEnvironmentProvider,
   useIsographEnvironment,
   type IsographEnvironmentProviderProps,
 } from './react/IsographEnvironmentProvider';
-export { useImperativeReference } from './react/useImperativeReference';
-export { FragmentReader } from './react/FragmentReader';
+export {
+  useImperativeReference,
+  type UseImperativeReferenceResult,
+} from './react/useImperativeReference';
+export {
+  FragmentReader,
+  type IsExactlyIntrinsicAttributes,
+} from './react/FragmentReader';
 export { useResult } from './react/useResult';
 export {
   useReadAndSubscribe,
@@ -79,8 +147,26 @@ export {
 } from './react/useReadAndSubscribe';
 export { useLazyReference } from './react/useLazyReference';
 export { useRerenderOnChange } from './react/useRerenderOnChange';
+export { RenderAfterCommit__DO_NOT_USE } from './react/RenderAfterCommit__DO_NOT_USE';
 
 export { useClientSideDefer } from './loadable-hooks/useClientSideDefer';
-export { useImperativeExposedMutationField } from './loadable-hooks/useImperativeExposedMutationField';
-export { useSkipLimitPagination } from './loadable-hooks/useSkipLimitPagination';
-export { useImperativeLoadableField } from './loadable-hooks/useImperativeLoadableField';
+export {
+  useImperativeExposedMutationField,
+  type UseImperativeLoadableFieldReturn as UseImperativeExposedMutationFieldReturn,
+} from './loadable-hooks/useImperativeExposedMutationField';
+export {
+  useSkipLimitPagination,
+  type UseSkipLimitPaginationArgs,
+  type UseSkipLimitReturnValue,
+} from './loadable-hooks/useSkipLimitPagination';
+export {
+  useConnectionSpecPagination,
+  type Connection,
+  type PageInfo,
+  type UseConnectionSpecPaginationArgs,
+  type UsePaginationReturnValue,
+} from './loadable-hooks/useConnectionSpecPagination';
+export {
+  useImperativeLoadableField,
+  type UseImperativeLoadableFieldReturn,
+} from './loadable-hooks/useImperativeLoadableField';

package/src/loadable-hooks/useClientSideDefer.ts

@@ -1,28 +1,59 @@
-import { FragmentReference } from '../core/FragmentReference';
-import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
-import { getOrCreateItemInSuspenseCache } from '../core/cache';
 import { useLazyDisposableState } from '@isograph/react-disposable-state';
+import { getOrCreateItemInSuspenseCache } from '../core/cache';
+import { FetchOptions } from '../core/check';
+import {
+  ExtractParameters,
+  FragmentReference,
+  type UnknownTReadFromStore,
+} from '../core/FragmentReference';
 import { LoadableField } from '../core/reader';
+import { useIsographEnvironment } from '../react/IsographEnvironmentProvider';
 
-export function useClientSideDefer<TResult>(
-  loadableField: LoadableField<void, TResult>,
-): FragmentReference<Record<string, never>, TResult>;
+export function useClientSideDefer<
+  TReadFromStore extends UnknownTReadFromStore,
+  TResult,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    ExtractParameters<TReadFromStore>
+  >,
+  args?: Record<PropertyKey, never>,
+  fetchOptions?: FetchOptions<TResult>,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
-export function useClientSideDefer<TArgs extends Object, TResult>(
-  loadableField: LoadableField<TArgs, TResult>,
-  args: TArgs,
-): FragmentReference<TArgs, TResult>;
+export function useClientSideDefer<
+  TReadFromStore extends UnknownTReadFromStore,
+  TResult,
+  TProvidedArgs extends object,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >,
+  args: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions<TResult>,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> };
 
-export function useClientSideDefer<TArgs extends Object, TResult>(
-  loadableField: LoadableField<TArgs, TResult>,
-  args?: TArgs,
-): FragmentReference<TArgs, TResult> {
-  // @ts-expect-error args is missing iff it has the type void
-  const [id, loader] = loadableField(args);
+export function useClientSideDefer<
+  TReadFromStore extends UnknownTReadFromStore,
+  TResult,
+  TProvidedArgs extends object,
+>(
+  loadableField: LoadableField<
+    TReadFromStore,
+    TResult,
+    Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>
+  >,
+  args?: Omit<ExtractParameters<TReadFromStore>, keyof TProvidedArgs>,
+  fetchOptions?: FetchOptions<TResult>,
+): { fragmentReference: FragmentReference<TReadFromStore, TResult> } {
+  const [id, loader] = loadableField(args, fetchOptions ?? {});
   const environment = useIsographEnvironment();
   const cache = getOrCreateItemInSuspenseCache(environment, id, loader);
 
   const fragmentReference = useLazyDisposableState(cache).state;
 
-  return fragmentReference;
+  return { fragmentReference };
 }