relay-runtime 20.1.1 → 21.0.1

package/store/RelayModernRecord.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { DataID } from '../util/RelayRuntimeTypes';
+import { Record } from './RelayStoreTypes';
+
+export class RelayModernRecord {
+    /**
+     * Clone a record.
+     */
+    clone(record: Record): Record;
+
+    /**
+     * Copies all fields from `source` to `sink`, excluding `__id` and `__typename`.
+     *
+     * NOTE: This function does not treat `id` specially. To preserve the id,
+     * manually reset it after calling this function. Also note that values are
+     * copied by reference and not value; callers should ensure that values are
+     * copied on write.
+     */
+    copyFields(source: Record, sink: Record): void;
+
+    /**
+     * Create a new record.
+     */
+    create(dataID: DataID, typeName: string): Record;
+
+    /**
+     * Get the record's `id` if available or the client-generated identifier.
+     */
+    getDataID(record: Record): DataID;
+
+    /**
+     * Get the concrete type of the record.
+     */
+    getType(record: Record): string;
+
+    /**
+     * Get a scalar (non-link) field value.
+     */
+    getValue(record: Record, storageKey: string): unknown;
+
+    /**
+     * Get the value of a field as a reference to another record. Throws if the
+     * field has a different type.
+     */
+    getLinkedRecordID(record: Record, storageKey: string): DataID | null;
+
+    /**
+     * Get the value of a field as a list of references to other records. Throws if
+     * the field has a different type.
+     */
+    getLinkedRecordIDs(record: Record, storageKey: string): DataID[] | null;
+
+    /**
+     * Compares the fields of a previous and new record, returning either the
+     * previous record if all fields are equal or a new record (with merged fields)
+     * if any fields have changed.
+     */
+    update(prevRecord: Record, nextRecord: Record): Record;
+
+    /**
+     * Returns a new record with the contents of the given records. Fields in the
+     * second record will overwrite identical fields in the first record.
+     */
+    merge(record1: Record, record2: Record): Record;
+
+    /**
+     * Prevent modifications to the record. Attempts to call `set*` functions on a
+     * frozen record will fatal at runtime.
+     */
+    freeze(record: Record): void;
+
+    /**
+     * Set the value of a storageKey to a scalar.
+     */
+    setValue(record: Record, storageKey: string, value: any): void;
+
+    /**
+     * Set the value of a field to a reference to another record.
+     */
+    setLinkedRecordID(record: Record, storageKey: string, linkedID: DataID): void;
+
+    /**
+     * Set the value of a field to a list of references other records.
+     */
+    setLinkedRecordIDs(record: Record, storageKey: string, linkedIDs: DataID[] | null): void;
+}

package/store/RelayModernRecord.js.flow

@@ -37,7 +37,7 @@ const warning = require('warning');
 
 export type StorageKey = Exclude<string, typeof ERRORS_KEY>;
 
-type RelayFieldErrors = {[StorageKey]: $ReadOnlyArray<TRelayFieldError>};
+type RelayFieldErrors = {[StorageKey]: ReadonlyArray<TRelayFieldError>};
 
 export type RecordJSON = {
   /**
@@ -45,7 +45,7 @@ export type RecordJSON = {
    * not support types with multiple indexers.
    */
   __errors?: RelayFieldErrors,
-  [StorageKey]: mixed,
+  [StorageKey]: unknown,
   ...
 };
 
@@ -147,7 +147,7 @@ function create(dataID: DataID, typeName: string): Record {
  *
  * Convert the JSON representation of a record into a record.
  */
-function fromObject<TMaybe: ?empty = empty>(
+function fromObject<TMaybe extends ?empty = empty>(
   json: RecordJSON | TMaybe,
 ): Record | TMaybe {
   return json;
@@ -159,7 +159,7 @@ function fromObject<TMaybe: ?empty = empty>(
  * Get the record's `id` if available or the client-generated identifier.
  */
 function getDataID(record: Record): DataID {
-  return (record[ID_KEY]: any);
+  return record[ID_KEY] as any;
 }
 
 /**
@@ -180,7 +180,7 @@ function getFields(record: Record): Array<StorageKey> {
  * Get the concrete type of the record.
  */
 function getType(record: Record): string {
-  return (record[TYPENAME_KEY]: any);
+  return record[TYPENAME_KEY] as any;
 }
 
 /**
@@ -191,7 +191,7 @@ function getType(record: Record): string {
 function getErrors(
   record: Record,
   storageKey: StorageKey,
-): $ReadOnlyArray<TRelayFieldError> | void {
+): ReadonlyArray<TRelayFieldError> | void {
   return record[ERRORS_KEY]?.[storageKey];
 }
 
@@ -200,7 +200,7 @@ function getErrors(
  *
  * Get a scalar (non-link) field value.
  */
-function getValue(record: Record, storageKey: StorageKey): mixed {
+function getValue(record: Record, storageKey: StorageKey): unknown {
   const value = record[storageKey];
   if (value && typeof value === 'object') {
     invariant(
@@ -252,7 +252,7 @@ function getLinkedRecordID(record: Record, storageKey: StorageKey): ?DataID {
           'getLinkedRecords() instead of getLinkedRecord()?'
       : '',
   );
-  // $FlowFixMe[incompatible-return]
+  // $FlowFixMe[incompatible-type]
   return link[REF_KEY];
 }
 
@@ -297,7 +297,7 @@ function getLinkedRecordIDs(
       : '',
   );
   // assume items of the array are ids
-  return (links[REFS_KEY]: any);
+  return links[REFS_KEY] as any;
 }
 
 /**
@@ -488,7 +488,7 @@ function freeze(record: Record): void {
 function setErrors(
   record: Record,
   storageKey: StorageKey,
-  errors?: $ReadOnlyArray<TRelayFieldError>,
+  errors?: ReadonlyArray<TRelayFieldError>,
 ): void {
   if (__DEV__) {
     warning(
@@ -523,7 +523,11 @@ function setErrors(
  *
  * Set the value of a storageKey to a scalar.
  */
-function setValue(record: Record, storageKey: StorageKey, value: mixed): void {
+function setValue(
+  record: Record,
+  storageKey: StorageKey,
+  value: unknown,
+): void {
   if (__DEV__) {
     const prevID = getDataID(record);
     if (storageKey === ID_KEY) {
@@ -629,7 +633,7 @@ function getActorLinkedRecordID(
     JSON.stringify(link),
   );
 
-  return [(link[ACTOR_IDENTIFIER_KEY]: any), (link[REF_KEY]: any)];
+  return [link[ACTOR_IDENTIFIER_KEY] as any, link[REF_KEY] as any];
 }
 
 function getResolverLinkedRecordID(record: Record, typeName: string): ?DataID {
@@ -682,12 +686,31 @@ function getResolverLinkedRecordIDs(
   });
 }
 
+/**
+ * @public
+ *
+ * Returns true if the value of a field differs between two records.
+ * Unlike getValue(), this works for all field types (scalar, linked, plural linked).
+ */
+function hasFieldChanged(
+  prevRecord: Record,
+  nextRecord: Record,
+  storageKey: StorageKey,
+): boolean {
+  if (!areEqual(prevRecord[storageKey], nextRecord[storageKey])) {
+    return true;
+  }
+  const prevErrors = prevRecord[ERRORS_KEY]?.[storageKey];
+  const nextErrors = nextRecord[ERRORS_KEY]?.[storageKey];
+  return !areEqual(prevErrors, nextErrors);
+}
+
 /**
  * @public
  *
  * Convert a record to JSON.
  */
-function toJSON<TMaybe: ?empty = empty>(
+function toJSON<TMaybe extends ?empty = empty>(
   record: Record | TMaybe,
 ): RecordJSON | TMaybe {
   return record;
@@ -699,26 +722,27 @@ module.exports = {
   create,
   freeze,
   fromObject,
+  getActorLinkedRecordID,
   getDataID,
   getErrors,
   getFields,
   getInvalidationEpoch,
   getLinkedRecordID,
   getLinkedRecordIDs,
+  getResolverLinkedRecordID,
+  getResolverLinkedRecordIDs,
   getType,
   getValue,
-  hasValue,
+  hasFieldChanged,
   hasLinkedRecordID,
   hasLinkedRecordIDs,
+  hasValue,
   merge,
+  setActorLinkedRecordID,
   setErrors,
-  setValue,
   setLinkedRecordID,
   setLinkedRecordIDs,
-  update,
-  getActorLinkedRecordID,
-  setActorLinkedRecordID,
-  getResolverLinkedRecordID,
-  getResolverLinkedRecordIDs,
+  setValue,
   toJSON,
+  update,
 };

package/store/RelayModernSelector.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { NormalizationSelectableNode } from '../util/NormalizationNode';
+import { ReaderFragment } from '../util/ReaderNode';
+import {DataID, Variables} from '../util/RelayRuntimeTypes';
+import {
+  NormalizationSelector,
+  PluralReaderSelector,
+  ReaderSelector,
+  RequestDescriptor,
+  SingularReaderSelector,
+} from './RelayStoreTypes';
+
+/**
+ * Given the result `item` from a parent that fetched `fragment`, creates a
+ * selector that can be used to read the results of that fragment for that item.
+ *
+ * Example:
+ *
+ * Given two fragments as follows:
+ *
+ * ```
+ * fragment Parent on User {
+ *   id
+ *   ...Child
+ * }
+ * fragment Child on User {
+ *   name
+ * }
+ * ```
+ *
+ * And given some object `parent` that is the results of `Parent` for id "4",
+ * the results of `Child` can be accessed by first getting a selector and then
+ * using that selector to `lookup()` the results against the environment:
+ *
+ * ```
+ * const childSelector = getSingularSelector(queryVariables, Child, parent);
+ * const childData = environment.lookup(childSelector).data;
+ * ```
+ */
+export function getSingularSelector(fragment: ReaderFragment, item: unknown): SingularReaderSelector;
+
+/**
+ * Given the result `items` from a parent that fetched `fragment`, creates a
+ * selector that can be used to read the results of that fragment on those
+ * items. This is similar to `getSingularSelector` but for "plural" fragments that
+ * expect an array of results and therefore return an array of selectors.
+ */
+export function getPluralSelector(fragment: ReaderFragment, items: unknown[]): PluralReaderSelector;
+
+export function getSelector(fragment: ReaderFragment, item: unknown | unknown[]): ReaderSelector;
+
+/**
+ * Given a mapping of keys -> results and a mapping of keys -> fragments,
+ * extracts the selectors for those fragments from the results.
+ *
+ * The canonical use-case for this function is ReactRelayFragmentContainer, which
+ * uses this function to convert (props, fragments) into selectors so that it
+ * can read the results to pass to the inner component.
+ */
+export function getSelectorsFromObject(
+    fragments: { [key: string]: ReaderFragment },
+    object: { [key: string]: any },
+): { [key: string]: ReaderSelector };
+
+/**
+ * Given a mapping of keys -> results and a mapping of keys -> fragments,
+ * extracts a mapping of keys -> id(s) of the results.
+ *
+ * Similar to `getSelectorsFromObject()`, this function can be useful in
+ * determining the "identity" of the props passed to a component.
+ */
+export function getDataIDsFromObject(
+    fragments: { [key: string]: ReaderFragment },
+    object: { [key: string]: any },
+): { [key: string]: DataID | DataID[] };
+
+export function getDataIDsFromFragment(fragment: ReaderFragment, item: unknown | unknown[]): DataID | DataID[];
+
+/**
+ * Given a mapping of keys -> results and a mapping of keys -> fragments,
+ * extracts the merged variables that would be in scope for those
+ * fragments/results.
+ *
+ * This can be useful in determing what varaibles were used to fetch the data
+ * for a Relay container, for example.
+ */
+export function getVariablesFromObject(
+    fragments: { [key: string]: ReaderFragment },
+    object: { [key: string]: any },
+): Variables;
+
+export function getVariablesFromFragment(fragment: ReaderFragment, item: unknown | unknown[]): Variables;
+
+export function getVariablesFromSingularFragment(fragment: ReaderFragment, item: unknown): Variables;
+
+export function getVariablesFromPluralFragment(fragment: ReaderFragment, items: unknown[]): Variables;
+
+/**
+ * Determine if two selectors are equal (represent the same selection). Note
+ * that this function returns `false` when the two queries/fragments are
+ * different objects, even if they select the same fields.
+ */
+export function areEqualSelectors(thisSelector: SingularReaderSelector, thatSelector: SingularReaderSelector): boolean;
+
+export function createReaderSelector(
+    fragment: ReaderFragment,
+    dataID: DataID,
+    variables: Variables,
+    request: RequestDescriptor,
+    isWithinUnmatchedTypeRefinement?: boolean, // default: `false`
+): SingularReaderSelector;
+
+export function createNormalizationSelector(
+    node: NormalizationSelectableNode,
+    dataID: DataID,
+    variables: Variables,
+): NormalizationSelector;

package/store/RelayModernSelector.js.flow

@@ -66,7 +66,7 @@ const warning = require('warning');
  */
 function getSingularSelector(
   fragment: ReaderFragment,
-  item: mixed,
+  item: unknown,
 ): ?SingularReaderSelector {
   invariant(
     typeof item === 'object' && item !== null && !Array.isArray(item),
@@ -90,9 +90,9 @@ function getSingularSelector(
     (mixedClientEdgeTraversalPath == null ||
       Array.isArray(mixedClientEdgeTraversalPath))
   ) {
-    const owner: RequestDescriptor = (mixedOwner: $FlowFixMe);
+    const owner: RequestDescriptor = mixedOwner as $FlowFixMe;
     const clientEdgeTraversalPath: ?ClientEdgeTraversalPath =
-      (mixedClientEdgeTraversalPath: $FlowFixMe);
+      mixedClientEdgeTraversalPath as $FlowFixMe;
 
     const argumentVariables = fragments[fragment.name];
     const fragmentVariables = getFragmentVariables(
@@ -146,7 +146,7 @@ function getSingularSelector(
  */
 function getPluralSelector(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): ?PluralReaderSelector {
   let selectors: null | Array<SingularReaderSelector> = null;
   items.forEach((item, ii) => {
@@ -168,7 +168,7 @@ function getPluralSelector(
 
 function getSelector(
   fragment: ReaderFragment,
-  item: mixed | Array<mixed>,
+  item: unknown | Array<unknown>,
 ): ?ReaderSelector {
   if (item == null) {
     return item;
@@ -207,7 +207,7 @@ function getSelector(
  */
 function getSelectorsFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): {[key: string]: ?ReaderSelector, ...} {
   const selectors: {[string]: ?ReaderSelector} = {};
   for (const key in fragments) {
@@ -231,7 +231,7 @@ function getSelectorsFromObject(
  */
 function getDataIDsFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): {[key: string]: ?(DataID | Array<DataID>), ...} {
   const ids: {[string]: ?(DataID | Array<DataID>)} = {};
   for (const key in fragments) {
@@ -246,7 +246,7 @@ function getDataIDsFromObject(
 
 function getDataIDsFromFragment(
   fragment: ReaderFragment,
-  item: mixed | Array<mixed>,
+  item: unknown | Array<unknown>,
 ): ?DataID | ?Array<DataID> {
   if (item == null) {
     return item;
@@ -278,7 +278,7 @@ function getDataIDsFromFragment(
  */
 function getDataIDs(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): ?Array<DataID> {
   let ids: null | Array<DataID> = null;
   items.forEach(item => {
@@ -294,7 +294,7 @@ function getDataIDs(
 /**
  * @internal
  */
-function getDataID(fragment: ReaderFragment, item: mixed): ?DataID {
+function getDataID(fragment: ReaderFragment, item: unknown): ?DataID {
   invariant(
     typeof item === 'object' && item !== null && !Array.isArray(item),
     'RelayModernSelector: Expected value for fragment `%s` to be an object, got ' +
@@ -332,7 +332,7 @@ function getDataID(fragment: ReaderFragment, item: mixed): ?DataID {
  */
 function getVariablesFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): Variables {
   const variables = {};
   for (const key in fragments) {
@@ -349,7 +349,7 @@ function getVariablesFromObject(
 
 function getVariablesFromFragment(
   fragment: ReaderFragment,
-  item: mixed | $ReadOnlyArray<mixed>,
+  item: unknown | ReadonlyArray<unknown>,
 ): Variables {
   if (item == null) {
     return {};
@@ -380,7 +380,7 @@ function getVariablesFromFragment(
 
 function getVariablesFromSingularFragment(
   fragment: ReaderFragment,
-  item: mixed,
+  item: unknown,
 ): ?Variables {
   const selector = getSingularSelector(fragment, item);
   if (!selector) {
@@ -391,7 +391,7 @@ function getVariablesFromSingularFragment(
 
 function getVariablesFromPluralFragment(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): Variables {
   const variables = {};
   items.forEach((value, ii) => {
@@ -519,13 +519,13 @@ function createReaderSelector(
   clientEdgeTraversalPath: ?ClientEdgeTraversalPath,
 ): SingularReaderSelector {
   return {
-    kind: 'SingularReaderSelector',
+    clientEdgeTraversalPath: clientEdgeTraversalPath ?? null,
     dataID,
     isWithinUnmatchedTypeRefinement,
-    clientEdgeTraversalPath: clientEdgeTraversalPath ?? null,
+    kind: 'SingularReaderSelector',
     node: fragment,
-    variables,
     owner: request,
+    variables,
   };
 }
 
@@ -539,16 +539,16 @@ function createNormalizationSelector(
 
 module.exports = {
   areEqualSelectors,
-  createReaderSelector,
   createNormalizationSelector,
+  createReaderSelector,
   getDataIDsFromFragment,
   getDataIDsFromObject,
-  getSingularSelector,
   getPluralSelector,
   getSelector,
   getSelectorsFromObject,
-  getVariablesFromSingularFragment,
-  getVariablesFromPluralFragment,
+  getSingularSelector,
   getVariablesFromFragment,
   getVariablesFromObject,
+  getVariablesFromPluralFragment,
+  getVariablesFromSingularFragment,
 };

package/store/RelayModernStore.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {DataID, Disposable} from '../util/RelayRuntimeTypes';
+import {
+  CheckOptions,
+  LogFunction,
+  MutableRecordSource,
+  OperationAvailability,
+  OperationDescriptor,
+  OperationLoader,
+  RecordSource,
+  RequestDescriptor,
+  ResolverContext,
+  Scheduler,
+  SingularReaderSelector,
+  Snapshot,
+  Store,
+} from './RelayStoreTypes';
+
+export interface InvalidationState {
+    dataIDs: readonly DataID[];
+    invalidations: Map<DataID, number | undefined | null>;
+}
+
+export default class RelayModernStore implements Store {
+    constructor(
+        source: MutableRecordSource,
+        options?: {
+            gcScheduler?: Scheduler | null | undefined;
+            log?: LogFunction | null | undefined;
+            operationLoader?: OperationLoader | null | undefined;
+            gcReleaseBufferSize?: number | null | undefined;
+            queryCacheExpirationTime?: number | null | undefined;
+            resolverContext?: ResolverContext;
+        },
+    );
+    getSource(): RecordSource;
+    check(operation: OperationDescriptor, options?: CheckOptions): OperationAvailability;
+    retain(operation: OperationDescriptor): Disposable;
+    lookup(selector: SingularReaderSelector): Snapshot;
+    notify(sourceOperation?: OperationDescriptor, invalidateStore?: boolean): readonly RequestDescriptor[];
+    publish(source: RecordSource, idsMarkedForInvalidation?: Set<DataID>): void;
+    subscribe(snapshot: Snapshot, callback: (snapshot: Snapshot) => void): Disposable;
+    holdGC(): Disposable;
+    lookupInvalidationState(dataIDs: readonly DataID[]): InvalidationState;
+    checkInvalidationState(previousInvalidationState: InvalidationState): boolean;
+    subscribeToInvalidationState(invalidationState: InvalidationState, callback: () => void): Disposable;
+    toJSON(): unknown;
+    snapshot(): void;
+    restore(): void;
+    scheduleGC(): void;
+}