@isograph/react 0.1.0 → 0.2.0

package/src/core/IsographEnvironment.ts

@@ -0,0 +1,183 @@
+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';
+
+export type ComponentOrFieldName = string;
+export type StringifiedArgs = string;
+type ComponentCache = {
+  [key: DataId]: {
+    [key: ComponentOrFieldName]: { [key: StringifiedArgs]: React.FC<any> };
+  };
+};
+
+export type FragmentSubscription<TReadFromStore extends 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>;
+};
+type AnyRecordSubscription = {
+  readonly kind: 'AnyRecords';
+  readonly callback: () => void;
+};
+
+type Subscription = FragmentSubscription<Object> | 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;
+};
+
+export type MissingFieldHandler = (
+  storeRecord: StoreRecord,
+  root: DataId,
+  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;
+};
+
+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 DataId = string;
+
+export const ROOT_ID: DataId & '__ROOT' = '__ROOT';
+
+export type IsographStore = {
+  [index: DataId]: StoreRecord | null;
+  readonly __ROOT: StoreRecord;
+};
+
+const DEFAULT_GC_BUFFER_SIZE = 10;
+export function createIsographEnvironment(
+  store: IsographStore,
+  networkFunction: IsographNetworkFunction,
+  missingFieldHandler?: MissingFieldHandler,
+): IsographEnvironment {
+  return {
+    store,
+    networkFunction,
+    missingFieldHandler: missingFieldHandler ?? null,
+    componentCache: {},
+    subscriptions: new Set(),
+    fragmentCache: {},
+    entrypointArtifactCache: new Map(),
+    retainedQueries: new Set(),
+    gcBuffer: [],
+    gcBufferSize: DEFAULT_GC_BUFFER_SIZE,
+  };
+}
+
+export function createIsographStore(): IsographStore {
+  return {
+    [ROOT_ID]: {},
+  };
+}
+
+export function defaultMissingFieldHandler(
+  _storeRecord: StoreRecord,
+  _root: DataId,
+  fieldName: string,
+  arguments_: { [index: string]: any } | null,
+  variables: Variables | null,
+): Link | undefined {
+  if (fieldName === 'node' || fieldName === 'user') {
+    const variable = arguments_?.['id'];
+    const value = variables?.[variable];
+
+    // TODO can we handle explicit nulls here too? Probably, after wrapping in objects
+    if (value != null) {
+      // @ts-expect-error
+      return { __link: value };
+    }
+  }
+}
+
+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' &&
+    // @ts-expect-error this is safe
+    maybeLink.__link != null
+  ) {
+    return maybeLink as any;
+  }
+  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;
+}

package/src/core/PromiseWrapper.ts

@@ -0,0 +1,86 @@
+export type AnyError = any;
+
+const NOT_SET: Symbol = Symbol('NOT_SET');
+type NotSet = typeof NOT_SET;
+
+type Result<T, E> =
+  | {
+      kind: 'Ok';
+      value: T;
+    }
+  | {
+      kind: 'Err';
+      error: E;
+    };
+
+/**
+ * Invariant:
+ * Before the promise is resolved, value becomes non-null.
+ */
+export type PromiseWrapper<T, E = any> = {
+  readonly promise: Promise<T>;
+  result: Result<Exclude<T, NotSet>, E> | NotSet;
+};
+
+export function wrapPromise<T>(promise: Promise<T>): PromiseWrapper<T, any> {
+  // TODO confirm suspense works if the promise is already resolved.
+  const wrapper: PromiseWrapper<T, any> = { promise, result: NOT_SET };
+  promise
+    .then((v) => {
+      // v is assignable to Exclude<T, Symbol> | Symbol
+      wrapper.result = { kind: 'Ok', value: v as any };
+    })
+    .catch((e) => {
+      // e is assignable to Exclude<T, Symbol> | Symbol
+      wrapper.result = { kind: 'Err', error: e as any };
+    });
+  return wrapper;
+}
+
+export function wrapResolvedValue<T>(value: T): PromiseWrapper<T, never> {
+  return {
+    promise: Promise.resolve(value),
+    result: {
+      kind: 'Ok',
+      // @ts-expect-error one should not call wrapResolvedValue with NOT_SET
+      value,
+    },
+  };
+}
+
+export function readPromise<T, E>(p: PromiseWrapper<T, E>): T {
+  const { result } = p;
+  if (result !== NOT_SET) {
+    // Safety: p.result is either NOT_SET or an actual value.
+    const resultKind = result as Result<T, any>;
+    if (resultKind.kind === 'Ok') {
+      return resultKind.value;
+    } else {
+      throw resultKind.error;
+    }
+  }
+
+  throw p.promise;
+}
+
+export type PromiseState<T, E> =
+  | {
+      kind: 'Pending';
+      promise: Promise<T>;
+    }
+  | Result<T, E>;
+
+export function getPromiseState<T, E>(
+  p: PromiseWrapper<T, E>,
+): PromiseState<T, E> {
+  const { result } = p;
+  if (result !== NOT_SET) {
+    // Safety: p.result is either NOT_SET or an actual value.
+    const resultKind = result as Result<T, any>;
+    return resultKind;
+  }
+  return {
+    kind: 'Pending',
+    promise: p.promise,
+  };
+}

package/src/core/areEqualWithDeepComparison.ts

@@ -0,0 +1,78 @@
+export function areEqualWithDeepComparison(
+  oldItem: unknown,
+  newItem: unknown,
+): boolean {
+  if (newItem === null) {
+    return oldItem === null;
+  }
+
+  if (newItem === undefined) {
+    return oldItem === undefined;
+  }
+
+  if (Array.isArray(newItem)) {
+    if (!Array.isArray(oldItem)) {
+      return false;
+    }
+
+    return areEqualArraysWithDeepComparison(oldItem, newItem);
+  }
+
+  if (typeof newItem === 'object') {
+    if (typeof oldItem !== 'object') {
+      return false;
+    }
+
+    if (oldItem === null) {
+      return false;
+    }
+
+    return areEqualObjectsWithDeepComparison(oldItem, newItem);
+  }
+
+  return newItem === oldItem;
+}
+
+export function areEqualArraysWithDeepComparison(
+  oldItems: ReadonlyArray<unknown>,
+  newItems: ReadonlyArray<unknown>,
+): boolean {
+  if (newItems.length !== oldItems.length) {
+    return false;
+  }
+
+  for (let i = 0; i < newItems.length; i++) {
+    if (!areEqualWithDeepComparison(oldItems[i], newItems[i])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function areEqualObjectsWithDeepComparison(
+  oldItemObject: object,
+  newItemObject: object,
+): boolean {
+  const oldKeys = Object.keys(oldItemObject);
+  const newKeys = Object.keys(newItemObject);
+
+  if (oldKeys.length !== newKeys.length) {
+    return false;
+  }
+
+  for (const oldKey of oldKeys) {
+    if (!(oldKey in newItemObject)) {
+      return false;
+    }
+    // @ts-expect-error
+    const oldValue = oldItemObject[oldKey];
+    // @ts-expect-error
+    const newValue = newItemObject[oldKey];
+
+    if (!areEqualWithDeepComparison(oldValue, newValue)) {
+      return false;
+    }
+  }
+  return true;
+}