relay-runtime 21.0.0 → 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,8 +35,8 @@ const {stableCopy} = require('../util/stableCopy');
 const invariant = require('invariant');
 
 export type Arguments = {
-  +FRAGMENT_POINTER_IS_WITHIN_UNMATCHED_TYPE_REFINEMENT?: boolean,
-  +[string]: unknown,
+  readonly FRAGMENT_POINTER_IS_WITHIN_UNMATCHED_TYPE_REFINEMENT?: boolean,
+  readonly [string]: unknown,
 };
 
 const {VARIABLE, LITERAL, OBJECT_VALUE, LIST_VALUE} = RelayConcreteNode;

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,14 +52,22 @@ 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 extends {+$data?: unknown, +$fragmentSpreads: FragmentType, ...},
+  TKey extends {
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
+    ...
+  },
 >(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: TKey,
 ): NonNullable<TKey['$data']>;
 
 declare function readFragment<
-  TKey extends ?{+$data?: unknown, +$fragmentSpreads: FragmentType, ...},
+  TKey extends ?{
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
+    ...
+  },
 >(
   fragmentInput: GraphQLTaggedNode,
   fragmentKey: TKey,
@@ -67,8 +75,8 @@ declare function readFragment<
 
 declare function readFragment<
   TKey extends ReadonlyArray<{
-    +$data?: unknown,
-    +$fragmentSpreads: FragmentType,
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
     ...
   }>,
 >(
@@ -78,8 +86,8 @@ declare function readFragment<
 
 declare function readFragment<
   TKey extends ?ReadonlyArray<{
-    +$data?: unknown,
-    +$fragmentSpreads: FragmentType,
+    readonly $data?: unknown,
+    readonly $fragmentSpreads: FragmentType,
     ...
   }>,
 >(

package/store/StoreInspector.js.flow

@@ -80,8 +80,8 @@ if (__DEV__) {
     const isRecord = (o: $FlowFixMe) => o != null && typeof o.__id === 'string';
 
     class RecordEntry {
-      +key: string;
-      +value: unknown;
+      readonly key: string;
+      readonly value: unknown;
       constructor(key: string, value: unknown) {
         this.key = key;
         this.value = value;

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/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/defaultGetDataID.js.flow

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

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/live-resolvers/LiveResolverCache.js.flow

@@ -772,7 +772,7 @@ class LiveResolverCache implements ResolverCache {
   // containing only "weak" records.
   _normalizeOutputTypeValue(
     outputTypeDataID: DataID,
-    value: {+[key: string]: unknown},
+    value: {readonly [key: string]: unknown},
     variables: Variables,
     normalizationInfo: ResolverNormalizationInfo,
     fieldPath: Array<string>,

package/store/live-resolvers/resolverDataInjector.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { FragmentType } from '../RelayStoreTypes';
+
+/**
+ * This a higher order function that returns a relay resolver that can read the data for
+ * the fragment`.
+ *
+ * - fragment: contains fragment Reader AST with resolver's data dependencies.
+ * - resolverFn: original resolver function that expects a data from the fragment
+ * - (optional) fieldName: individual field that needs to be read out of the fragment.
+ *
+ * This will not call the `resolverFn` if the fragment data for it is null/undefined.
+ * The compiler generates calls to this function, ensuring the correct set of arguments.
+ */
+export function resolverDataInjector(
+    fragment: GraphQLTaggedNode,
+    _resolverFn: unknown,
+    fieldName?: string,
+    isRequiredField?: boolean,
+): (fragmentKey: FragmentType, args: unknown) => unknown;

package/store/observeFragmentExperimental.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { RelayObservable as Observable } from '../network/RelayObservable';
+import type { GraphQLTaggedNode } from '../query/GraphQLTag';
+import type {ArrayKeyType, ArrayKeyTypeData, Environment as IEnvironment, FragmentState, KeyType, KeyTypeData} from './RelayStoreTypes';
+
+/**
+ * EXPERIMENTAL: This API is experimental and does not yet support all Relay
+ * features. Notably, it does not correctly handle some features of Relay Resolvers.
+ *
+ * Given a fragment and a fragment reference, returns an observable that emits
+ * the state of the fragment over time. The observable will emit the following
+ * values:
+ * - 'ok': The fragment has a value
+ * - 'error': The fragment has an error, this could be due to a network error or
+ *  a field error due to @required(action: THROW) or @throwOnFieldError
+ * - 'loading': The fragment is still in flight and is still expected to resolver.
+ */
+export function observeFragment<TKey extends KeyType>(
+    environment: IEnvironment,
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): Observable<FragmentState<KeyTypeData<TKey>>>;
+
+/**
+ * EXPERIMENTAL: This API is experimental and does not yet support all Relay
+ * features. Notably, it does not correctly handle some features of Relay Resolvers.
+ *
+ * Given a fragment and a fragment reference, returns an observable that emits
+ * the state of the fragment over time. The observable will emit the following
+ * values:
+ * - 'ok': The fragment has a value
+ * - 'error': The fragment has an error, this could be due to a network error or
+ *  a field error due to @required(action: THROW) or @throwOnFieldError
+ * - 'loading': The fragment is still in flight and is still expected to resolver.
+ */
+export function observeFragment<TKey extends ArrayKeyType>(
+    environment: IEnvironment,
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): Observable<FragmentState<ArrayKeyTypeData<TKey>>>;

package/store/observeFragmentExperimental.js.flow

@@ -45,7 +45,7 @@ export type FragmentState<T> =
   | {state: 'loading'};
 
 export type HasSpread<TFragmentType> = {
-  +$fragmentSpreads: TFragmentType,
+  readonly $fragmentSpreads: TFragmentType,
   ...
 };
 

package/store/observeQueryExperimental.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { RelayObservable as Observable } from '../network/RelayObservable';
+import type { GraphQLTaggedNode } from '../query/GraphQLTag';
+import type { OperationType } from '../util/RelayRuntimeTypes';
+import type {Environment as IEnvironment, FragmentState} from './RelayStoreTypes';
+
+/**
+ * This function returns an observable that can be used to subscribe to the data
+ * contained in a query. It does not return the full response shape, but rather
+ * the contents of the query body minus any fragment spreads.  If you wish to
+ * read the contents of a fragment spread into this query you may pass the
+ * object into which the fragment was spread to `observeFragment`.
+ *
+ * NOTE: `observeQuery` assumes that you have already fetched and retained the
+ * query via some other means, such as `fetchQuery`.
+ *
+ * This feature is still experimental and does not properly handle some resolver
+ * features such as client-to-server edges.
+ */
+export function observeQuery<T extends OperationType>(
+    environment: IEnvironment,
+    gqlQuery: GraphQLTaggedNode,
+    variables: T['variables'],
+): Observable<FragmentState<T['response']>>;

package/store/readInlineData.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 {KeyType, KeyTypeData} from './RelayStoreTypes';
+
+export function readInlineData<TKey extends KeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): KeyTypeData<TKey>;
+
+export function readInlineData<TKey extends KeyType>(
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey | null | undefined,
+): KeyTypeData<TKey> | null | undefined;

package/store/readInlineData.js.flow

@@ -20,7 +20,7 @@ const {FRAGMENTS_KEY} = require('./RelayStoreUtils');
 const invariant = require('invariant');
 
 type HasSpread<TFragmentType> = {
-  +$fragmentSpreads: TFragmentType,
+  readonly $fragmentSpreads: TFragmentType,
   ...
 };
 

package/store/waitForFragmentExperimental.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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, Environment as IEnvironment, KeyType, KeyTypeData} from './RelayStoreTypes';
+
+/**
+ * EXPERIMENTAL: This API is experimental and does not yet support all Relay
+ * features. Notably, it does not correctly handle some features of Relay Resolvers.
+ *
+ * Given a fragment and a fragment reference, returns a promise that resolves
+ * once the fragment data is available, or rejects if the fragment has an error.
+ * Errors include both network errors and field errors due to @required(action:
+ * THROW) or @throwOnFieldError.
+
+ * This API is intended for use when consuming data outside of a UI framework, or
+ * when you need to imperatively access data inside an event handler. For example,
+ * you might choose to @defer a fragment that you only need to access inside an
+ * event handler and then await its value inside the handler if/when it is triggered.
+ */
+export function waitForFragmentData<TKey extends KeyType>(
+    environment: IEnvironment,
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): Promise<KeyTypeData<TKey>>;
+
+/**
+ * EXPERIMENTAL: This API is experimental and does not yet support all Relay
+ * features. Notably, it does not correctly handle some features of Relay Resolvers.
+ *
+ * Given a fragment and a fragment reference, returns a promise that resolves
+ * once the fragment data is available, or rejects if the fragment has an error.
+ * Errors include both network errors and field errors due to @required(action:
+ * THROW) or @throwOnFieldError.
+
+ * This API is intended for use when consuming data outside of a UI framework, or
+ * when you need to imperatively access data inside an event handler. For example,
+ * you might choose to @defer a fragment that you only need to access inside an
+ * event handler and then await its value inside the handler if/when it is triggered.
+ */
+export function waitForFragmentData<TKey extends ArrayKeyType>(
+    environment: IEnvironment,
+    fragmentInput: GraphQLTaggedNode,
+    fragmentRef: TKey,
+): Promise<ArrayKeyTypeData<TKey>>;

package/subscription/requestSubscription.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { DeclarativeMutationConfig } from '../mutations/RelayDeclarativeMutationConfig';
+import { GraphQLTaggedNode } from '../query/GraphQLTag';
+import {Environment, SelectorStoreUpdater} from '../store/RelayStoreTypes';
+import {CacheConfig, Disposable, OperationType} from '../util/RelayRuntimeTypes';
+
+export interface GraphQLSubscriptionConfig<TSubscription extends OperationType> {
+    cacheConfig?: CacheConfig | undefined;
+    configs?: readonly DeclarativeMutationConfig[] | undefined;
+    subscription: GraphQLTaggedNode;
+    variables: TSubscription['variables'];
+    onCompleted?: (() => void) | undefined;
+    onError?: ((error: Error) => void) | undefined;
+    onNext?: ((response: TSubscription['response'] | null | undefined) => void) | undefined;
+    updater?: SelectorStoreUpdater<TSubscription['response']> | undefined;
+}
+
+export function requestSubscription<TSubscription extends OperationType = OperationType>(
+    environment: Environment,
+    config: GraphQLSubscriptionConfig<TSubscription>,
+): Disposable;

package/subscription/requestSubscription.js.flow

@@ -32,9 +32,9 @@ const {createReaderSelector} = require('../store/RelayModernSelector');
 const warning = require('warning');
 
 export type SubscriptionParameters = {
-  +response: {...},
-  +variables: {...},
-  +rawResponse?: {...},
+  readonly response: {...},
+  readonly variables: {...},
+  readonly rawResponse?: {...},
 };
 
 /**

package/util/JSResourceTypes.flow.js.flow

@@ -11,8 +11,8 @@
 
 'use strict';
 
-export interface JSResourceReference<+T> {
-  +getModuleId: () => string;
-  +getModuleIfRequired: () => ?T;
-  +load: () => Promise<T>;
+export interface JSResourceReference<out T> {
+  readonly getModuleId: () => string;
+  readonly getModuleIfRequired: () => ?T;
+  readonly load: () => Promise<T>;
 }