relay-runtime 20.1.1 → 21.0.1

package/store/RelayStoreUtils.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 {NormalizationArgument, NormalizationField, NormalizationHandle} from '../util/NormalizationNode';
+import {ReaderArgument, ReaderField} from '../util/ReaderNode';
+import { Variables } from '../util/RelayRuntimeTypes';
+
+export interface Arguments {
+    [key: string]: any;
+}
+
+/**
+ * Returns the values of field/fragment arguments as an object keyed by argument
+ * names. Guaranteed to return a result with stable ordered nested values.
+ */
+export function getArgumentValues(
+    args: ReadonlyArray<NormalizationArgument | ReaderArgument>,
+    variables: Variables,
+): Arguments;
+
+/**
+ * Given a handle field and variable values, returns a key that can be used to
+ * uniquely identify the combination of the handle name and argument values.
+ *
+ * Note: the word "storage" here refers to the fact this key is primarily used
+ * when writing the results of a key in a normalized graph or "store". This
+ * name was used in previous implementations of Relay internals and is also
+ * used here for consistency.
+ */
+export function getHandleStorageKey(handleField: NormalizationHandle, variables: Variables): string;
+
+/**
+ * Given a field and variable values, returns a key that can be used to
+ * uniquely identify the combination of the field name and argument values.
+ *
+ * Note: the word "storage" here refers to the fact this key is primarily used
+ * when writing the results of a key in a normalized graph or "store". This
+ * name was used in previous implementations of Relay internals and is also
+ * used here for consistency.
+ */
+export function getStorageKey(
+    field: NormalizationField | NormalizationHandle | ReaderField,
+    variables: Variables,
+): string;
+
+/**
+ * Given a `name` (eg. "foo") and an object representing argument values
+ * (eg. `{orberBy: "name", first: 10}`) returns a unique storage key
+ * (ie. `foo{"first":10,"orderBy":"name"}`).
+ *
+ * This differs from getStorageKey which requires a ConcreteNode where arguments
+ * are assumed to already be sorted into a stable order.
+ */
+export function getStableStorageKey(name: string, args: Arguments): string;
+
+/**
+ * Given a name and argument values, format a storage key.
+ *
+ * Arguments and the values within them are expected to be ordered in a stable
+ * alphabetical ordering.
+ */
+export function formatStorageKey(name: string, argValues: Arguments): string;
+
+/**
+ * Given Variables and a variable name, return a variable value with
+ * all values in a stable order.
+ */
+export function getStableVariableValue(name: string, variables: Variables): unknown;
+
+export function getModuleComponentKey(documentName: string): string;
+export function getModuleOperationKey(documentName: string): string;
+
+export const FRAGMENTS_KEY: string;
+export const FRAGMENT_OWNER_KEY: string;
+export const FRAGMENT_PROP_NAME_KEY: string;
+export const MODULE_COMPONENT_KEY: string; // alias returned by Reader
+export const ID_KEY: string;
+export const REF_KEY: string;
+export const REFS_KEY: string;
+export const ROOT_ID: string;
+export const ROOT_TYPE: string;
+export const TYPENAME_KEY: string;

package/store/RelayStoreUtils.js.flow

@@ -35,13 +35,14 @@ const {stableCopy} = require('../util/stableCopy');
 const invariant = require('invariant');
 
 export type Arguments = {
-  +FRAGMENT_POINTER_IS_WITHIN_UNMATCHED_TYPE_REFINEMENT?: boolean,
-  +[string]: mixed,
+  readonly FRAGMENT_POINTER_IS_WITHIN_UNMATCHED_TYPE_REFINEMENT?: boolean,
+  readonly [string]: unknown,
 };
 
 const {VARIABLE, LITERAL, OBJECT_VALUE, LIST_VALUE} = RelayConcreteNode;
 
 const ERRORS_KEY: '__errors' = '__errors';
+const FIELD_GRANULAR_NOTIFICATIONS_KEY = '__fieldGranularNotifications';
 const MODULE_COMPONENT_KEY_PREFIX = '__module_component_';
 const MODULE_OPERATION_KEY_PREFIX = '__module_operation_';
 
@@ -50,7 +51,7 @@ const RELAY_READ_TIME_RESOLVER_KEY_PREFIX = '$r:';
 function getArgumentValue(
   arg: NormalizationArgument | ReaderArgument,
   variables: Variables,
-): mixed {
+): unknown {
   if (arg.kind === VARIABLE) {
     // Variables are provided at runtime and are not guaranteed to be stable.
     return getStableVariableValue(arg.variableName, variables);
@@ -58,7 +59,7 @@ function getArgumentValue(
     // The Relay compiler generates stable ConcreteArgument values.
     return arg.value;
   } else if (arg.kind === OBJECT_VALUE) {
-    const value: {[string]: mixed} = {};
+    const value: {[string]: unknown} = {};
     arg.fields.forEach(field => {
       value[field.name] = getArgumentValue(field, variables);
     });
@@ -77,13 +78,13 @@ function getArgumentValue(
  * names. Guaranteed to return a result with stable ordered nested values.
  */
 function getArgumentValues(
-  args?: ?$ReadOnlyArray<NormalizationArgument | ReaderArgument>,
+  args?: ?ReadonlyArray<NormalizationArgument | ReaderArgument>,
   variables: Variables,
   isWithinUnmatchedTypeRefinement?: boolean,
 ): Arguments {
   const values: {
     FRAGMENT_POINTER_IS_WITHIN_UNMATCHED_TYPE_REFINEMENT?: boolean,
-    [string]: mixed,
+    [string]: unknown,
   } = {};
   if (isWithinUnmatchedTypeRefinement) {
     values[
@@ -204,7 +205,7 @@ function getArguments(
     | NormalizationHandle
     | ReaderField
     | ReaderActorChange,
-): ?$ReadOnlyArray<NormalizationArgument | ReaderArgument> {
+): ?ReadonlyArray<NormalizationArgument | ReaderArgument> {
   if (field.kind === 'RelayResolver' || field.kind === 'RelayLiveResolver') {
     if (field.args == null) {
       return field.fragment?.args;
@@ -256,7 +257,7 @@ function formatStorageKey(name: string, argValues: ?Arguments): string {
  * Given Variables and a variable name, return a variable value with
  * all values in a stable order.
  */
-function getStableVariableValue(name: string, variables: Variables): mixed {
+function getStableVariableValue(name: string, variables: Variables): unknown {
   invariant(
     variables.hasOwnProperty(name),
     'getVariableValue(): Undefined variable `%s`.',
@@ -273,6 +274,10 @@ function getModuleOperationKey(documentName: string): string {
   return `${MODULE_OPERATION_KEY_PREFIX}${documentName}`;
 }
 
+function getFieldNotificationKey(dataID: string, storageKey: string): string {
+  return `__fn:${dataID}:${storageKey}`;
+}
+
 /**
  * Constants shared by all implementations of RecordSource/MutableRecordSource/etc.
  */
@@ -286,6 +291,7 @@ const RelayStoreUtils = {
   FRAGMENT_PROP_NAME_KEY: '__fragmentPropName',
   MODULE_COMPONENT_KEY: '__module_component', // alias returned by Reader
   ERRORS_KEY,
+  FIELD_GRANULAR_NOTIFICATIONS_KEY,
   ID_KEY: '__id',
   REF_KEY: '__ref',
   REFS_KEY: '__refs',
@@ -298,6 +304,7 @@ const RelayStoreUtils = {
   RELAY_RESOLVER_SNAPSHOT_KEY: '__resolverSnapshot',
   RELAY_RESOLVER_ERROR_KEY: '__resolverError',
   RELAY_RESOLVER_OUTPUT_TYPE_RECORD_IDS: '__resolverOutputTypeRecordIDs',
+  RELAY_RESOLVER_RECORD_TYPENAME: '__RELAY_RESOLVER__',
   RELAY_READ_TIME_RESOLVER_KEY_PREFIX,
 
   formatStorageKey,
@@ -309,6 +316,7 @@ const RelayStoreUtils = {
   getStableStorageKey,
   getModuleComponentKey,
   getModuleOperationKey,
+  getFieldNotificationKey,
 } as const;
 
 module.exports = RelayStoreUtils;

package/store/ResolverCache.js.flow

@@ -32,8 +32,8 @@ export type EvaluationResult<T> = {
   error: ?Error,
 };
 
-export type ResolverFragmentResult = $ReadOnly<{
-  data: mixed,
+export type ResolverFragmentResult = Readonly<{
+  data: unknown,
   isMissingData: boolean,
   fieldErrors: ?FieldErrors,
 }>;

package/store/ResolverFragments.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { GraphQLTaggedNode } from '../query/GraphQLTag';
+import type {ArrayKeyType, ArrayKeyTypeData, FragmentType, KeyType, KeyTypeData, SingularReaderSelector} from './RelayStoreTypes';
+
+export interface ResolverContext {
+    getDataForResolverFragment: (
+        arg0: SingularReaderSelector,
+        arg1: FragmentType,
+    ) => {
+        data: unknown;
+        isMissingData: boolean;
+    };
+}
+
+export const RESOLVER_FRAGMENT_MISSING_DATA_SENTINEL: unknown;
+
+export function withResolverContext<T>(context: ResolverContext, cb: () => T): T;
+
+export function readFragment<TKey extends KeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): KeyTypeData<TKey>;
+
+export function readFragment<TKey extends KeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey | null,
+): KeyTypeData<TKey> | null;
+
+export function readFragment<TKey extends ArrayKeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): ArrayKeyTypeData<TKey>;
+
+export function readFragment<TKey extends ArrayKeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey | null,
+): ArrayKeyTypeData<TKey> | null;

package/store/ResolverFragments.js.flow

@@ -52,34 +52,42 @@ function withResolverContext<T>(context: ResolverContext, cb: () => T): T {
 //   - array of nullable if the provided ref type is an array of nullable refs
 
 declare function readFragment<
-  TKey: {+$data?: mixed, +$fragmentSpreads: FragmentType, ...},
+  TKey extends {
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
+    ...
+  },
 >(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: TKey,
-): $NonMaybeType<TKey['$data']>;
+): NonNullable<TKey['$data']>;
 
 declare function readFragment<
-  TKey: ?{+$data?: mixed, +$fragmentSpreads: FragmentType, ...},
+  TKey extends ?{
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
+    ...
+  },
 >(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: TKey,
 ): ?TKey?.['$data'];
 
 declare function readFragment<
-  TKey: $ReadOnlyArray<{
-    +$data?: mixed,
-    +$fragmentSpreads: FragmentType,
+  TKey extends ReadonlyArray<{
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
     ...
   }>,
 >(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: TKey,
-): $NonMaybeType<TKey[number]['$data']>;
+): NonNullable<TKey[number]['$data']>;
 
 declare function readFragment<
-  TKey: ?$ReadOnlyArray<{
-    +$data?: mixed,
-    +$fragmentSpreads: FragmentType,
+  TKey extends ?ReadonlyArray<{
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
     ...
   }>,
 >(
@@ -87,7 +95,7 @@ declare function readFragment<
   fragmentKey: TKey,
 ): ?TKey?.[number]['$data'];
 
-declare function readFragment<TKey: FragmentType, TData>(
+declare function readFragment<TKey extends FragmentType, TData>(
   fragmentInput: Fragment<TKey, TData>,
   fragmentKey: TKey,
 ): TData;
@@ -95,7 +103,7 @@ declare function readFragment<TKey: FragmentType, TData>(
 function readFragment(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: FragmentType,
-): mixed {
+): unknown {
   if (!contextStack.length) {
     throw new Error(
       'readFragment should be called only from within a Relay Resolver function.',
@@ -127,10 +135,10 @@ function readFragment(
   return data;
 }
 
-const RESOLVER_FRAGMENT_ERRORED_SENTINEL: mixed = {};
+const RESOLVER_FRAGMENT_ERRORED_SENTINEL: unknown = {};
 
 module.exports = {
+  RESOLVER_FRAGMENT_ERRORED_SENTINEL,
   readFragment,
   withResolverContext,
-  RESOLVER_FRAGMENT_ERRORED_SENTINEL,
 };

package/store/StoreInspector.js.flow

@@ -13,7 +13,7 @@
 
 import type {IEnvironment, RecordSource} from '../store/RelayStoreTypes';
 
-type InspectFn = (environment: IEnvironment, dataID?: ?string) => mixed;
+type InspectFn = (environment: IEnvironment, dataID?: ?string) => unknown;
 
 let inspect: InspectFn = () => {};
 
@@ -80,9 +80,9 @@ if (__DEV__) {
     const isRecord = (o: $FlowFixMe) => o != null && typeof o.__id === 'string';
 
     class RecordEntry {
-      +key: string;
-      +value: mixed;
-      constructor(key: string, value: mixed) {
+      readonly key: string;
+      readonly value: unknown;
+      constructor(key: string, value: unknown) {
         this.key = key;
         this.value = value;
       }
@@ -138,14 +138,13 @@ if (__DEV__) {
   const getWrappedRecord = (
     source: RecordSource,
     dataID: string,
-  ): ?{[string]: mixed} => {
+  ): ?{[string]: unknown} => {
     const record = source.get(dataID);
     if (record == null) {
-      // $FlowFixMe[incompatible-return]
+      // $FlowFixMe[incompatible-type]
       return record;
     }
     return new Proxy(
-      // $FlowFixMe: Do not assume that record is an object
       {...record},
       {
         get(target, prop) {
@@ -159,7 +158,7 @@ if (__DEV__) {
               return getWrappedRecord(source, value.__ref);
             }
             if (Array.isArray(value.__refs)) {
-              // $FlowFixMe[incompatible-call]
+              // $FlowFixMe[incompatible-type]
               return value.__refs.map((ref: string) =>
                 getWrappedRecord(source, ref),
               );

package/store/ViewerPattern.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 type { DataID } from '../util/RelayRuntimeTypes';
+
+export const VIEWER_ID: DataID;
+export const VIEWER_TYPE = 'Viewer';

package/store/cloneRelayHandleSourceField.js.flow

@@ -32,7 +32,7 @@ const invariant = require('invariant');
  */
 function cloneRelayHandleSourceField(
   handleField: NormalizationLinkedHandle,
-  selections: $ReadOnlyArray<NormalizationSelection>,
+  selections: ReadonlyArray<NormalizationSelection>,
   variables: Variables,
 ): NormalizationLinkedField {
   const sourceField = selections.find(

package/store/cloneRelayScalarHandleSourceField.js.flow

@@ -31,7 +31,7 @@ const invariant = require('invariant');
  */
 function cloneRelayScalarHandleSourceField(
   handleField: NormalizationScalarHandle,
-  selections: $ReadOnlyArray<NormalizationSelection>,
+  selections: ReadonlyArray<NormalizationSelection>,
   variables: Variables,
 ): NormalizationScalarField {
   const sourceField = selections.find(

package/store/createFragmentSpecResolver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 {FragmentMap, FragmentSpecResolver, Props, RelayContext} from './RelayStoreTypes';
+
+export function createFragmentSpecResolver(
+    context: RelayContext,
+    containerName: string,
+    fragments: FragmentMap,
+    props: Props,
+    callback?: () => void,
+): FragmentSpecResolver;

package/store/createRelayContext.js.flow

@@ -19,7 +19,7 @@ const invariant = require('invariant');
 
 // Ideally, we'd just import the type of the react module, but this causes Flow
 // problems.
-type React = $ReadOnly<{
+type React = Readonly<{
   createContext: createContext<RelayContext | null>,
   version: string,
   ...

package/store/createRelayLoggingContext.js.flow

@@ -18,16 +18,16 @@ const invariant = require('invariant');
 
 // Ideally, we'd just import the type of the react module, but this causes Flow
 // problems.
-type React = $ReadOnly<{
-  createContext: createContext<mixed | null>,
+type React = Readonly<{
+  createContext: createContext<unknown | null>,
   version: string,
   ...
 }>;
 
-let relayLoggingContext: ?Context<mixed | null>;
+let relayLoggingContext: ?Context<unknown | null>;
 let firstReact: ?React;
 
-function createRelayLoggingContext(react: React): Context<mixed | null> {
+function createRelayLoggingContext(react: React): Context<unknown | null> {
   if (!relayLoggingContext) {
     relayLoggingContext = react.createContext(null);
     if (__DEV__) {

package/store/defaultGetDataID.js.flow

@@ -14,9 +14,9 @@
 const {VIEWER_ID, VIEWER_TYPE} = require('./ViewerPattern');
 
 function defaultGetDataID(
-  fieldValue: {+[string]: mixed},
+  fieldValue: {readonly [string]: unknown},
   typeName: string,
-): mixed {
+): unknown {
   if (typeName === VIEWER_TYPE) {
     return fieldValue.id == null ? VIEWER_ID : fieldValue.id;
   }

package/store/isRelayModernEnvironment.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export function isRelayModernEnvironment(environment: any): boolean;

package/store/isRelayModernEnvironment.js.flow

@@ -19,8 +19,10 @@
  * aid in module tree-shaking to avoid requiring all of RelayRuntime just to
  * detect its environment.
  */
-function isRelayModernEnvironment(environment: mixed): boolean {
-  return Boolean(environment && (environment: any)['@@RelayModernEnvironment']);
+function isRelayModernEnvironment(environment: unknown): boolean {
+  return Boolean(
+    environment && (environment as any)['@@RelayModernEnvironment'],
+  );
 }
 
 module.exports = isRelayModernEnvironment;