react-relay 20.1.1 → 21.0.0

package/relay-hooks/readFragmentInternal.js.flow

@@ -41,10 +41,10 @@ type FragmentQueryOptions = {
   networkCacheConfig?: ?CacheConfig,
 };
 
-type FragmentState = $ReadOnly<
+type FragmentState = Readonly<
   | {kind: 'bailout'}
   | {kind: 'singular', snapshot: Snapshot, epoch: number}
-  | {kind: 'plural', snapshots: $ReadOnlyArray<Snapshot>, epoch: number},
+  | {kind: 'plural', snapshots: ReadonlyArray<Snapshot>, epoch: number},
 >;
 
 function isMissingData(state: FragmentState): boolean {
@@ -59,7 +59,7 @@ function isMissingData(state: FragmentState): boolean {
 
 function getMissingClientEdges(
   state: FragmentState,
-): $ReadOnlyArray<MissingClientEdgeRequestInfo> | null {
+): ReadonlyArray<MissingClientEdgeRequestInfo> | null {
   if (state.kind === 'bailout') {
     return null;
   } else if (state.kind === 'singular') {
@@ -94,7 +94,7 @@ function handlePotentialSnapshotErrorsForState(
 function handleMissingClientEdge(
   environment: IEnvironment,
   parentFragmentNode: ReaderFragment,
-  parentFragmentRef: mixed,
+  parentFragmentRef: unknown,
   missingClientEdgeRequestInfo: MissingClientEdgeRequestInfo,
   queryOptions?: FragmentQueryOptions,
 ): QueryResult {
@@ -134,16 +134,16 @@ function getFragmentState(
       return {kind: 'bailout'};
     } else {
       return {
+        epoch: environment.getStore().getEpoch(),
         kind: 'plural',
         snapshots: fragmentSelector.selectors.map(s => environment.lookup(s)),
-        epoch: environment.getStore().getEpoch(),
       };
     }
   } else {
     return {
+      epoch: environment.getStore().getEpoch(),
       kind: 'singular',
       snapshot: environment.lookup(fragmentSelector),
-      epoch: environment.getStore().getEpoch(),
     };
   }
 }
@@ -152,7 +152,7 @@ function getFragmentState(
 function readFragmentInternal(
   environment: IEnvironment,
   fragmentNode: ReaderFragment,
-  fragmentRef: mixed,
+  fragmentRef: unknown,
   hookDisplayName: string,
   queryOptions?: FragmentQueryOptions,
   fragmentKey?: string,
@@ -220,7 +220,7 @@ function readFragmentInternal(
   ) {
     const missingClientEdges = getMissingClientEdges(state);
     if (missingClientEdges?.length) {
-      clientEdgeQueries = ([]: Array<QueryResult>);
+      clientEdgeQueries = [] as Array<QueryResult>;
       for (const edge of missingClientEdges) {
         clientEdgeQueries.push(
           handleMissingClientEdge(
@@ -288,7 +288,7 @@ function readFragmentInternal(
     }
   }
 
-  return {data, clientEdgeQueries};
+  return {clientEdgeQueries, data};
 }
 
 module.exports = readFragmentInternal;

package/relay-hooks/rsc/serverFetchQuery.js.flow

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall relay
+ */
+
+'use strict';
+
+import type {IEnvironment, Query, Variables} from 'relay-runtime';
+
+const {fetchQuery} = require('relay-runtime');
+
+async function serverFetchQuery<TVariables extends Variables, TData>(
+  environment: IEnvironment,
+  query: Query<TVariables, TData>,
+  variables: TVariables,
+): Promise<TData> {
+  const observable = fetchQuery(environment, query, variables);
+  const result = await observable.toPromise();
+  if (result == null) {
+    throw new Error('Unexpected null response from fetchQuery');
+  }
+  return result;
+}
+
+module.exports = serverFetchQuery;

package/relay-hooks/rsc/serverPreloadQuery.js.flow

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall relay
+ */
+
+'use strict';
+
+import type {IEnvironment, PayloadError, Query, Variables} from 'relay-runtime';
+
+const invariant = require('invariant');
+const {createOperationDescriptor, getRequest} = require('relay-runtime');
+
+export type PreloadedQueryResponse<TData> = {
+  +data: TData,
+  +errors?: ReadonlyArray<PayloadError>,
+};
+
+export type PreloadedQueryRef<TVariables, TData> = {
+  +kind: 'PreloadedQueryRef',
+  +queryId: string,
+  +variables: TVariables,
+  +_response: Promise<PreloadedQueryResponse<TData>>,
+  +fetchedAt: number,
+};
+
+function serverPreloadQuery<TVariables extends Variables, TData>(
+  environment: IEnvironment,
+  query: Query<TVariables, TData>,
+  variables: TVariables,
+): PreloadedQueryRef<TVariables, TData> {
+  const request = getRequest(query);
+  const operationDescriptor = createOperationDescriptor(request, variables);
+
+  const observable = environment.execute({operation: operationDescriptor});
+
+  const queryId =
+    request.params.id ?? request.params.cacheID ?? request.params.name;
+
+  const response: Promise<PreloadedQueryResponse<TData>> =
+    // $FlowFixMe[incompatible-type] PayloadData -> TData; shape validated by the Relay compiler
+    observable.toPromise().then(rawResponse => {
+      invariant(rawResponse != null, 'Unexpected null response from execute');
+      // TODO: @defer returns batched responses; this only handles the first payload
+      invariant(
+        !Array.isArray(rawResponse),
+        '@defer is not yet supported in serverPreloadQuery',
+      );
+      return {
+        data: rawResponse.data,
+        errors: rawResponse.errors,
+      };
+    });
+
+  return {
+    kind: 'PreloadedQueryRef',
+    queryId,
+    variables,
+    _response: response,
+    fetchedAt: Date.now(),
+  };
+}
+
+module.exports = serverPreloadQuery;

package/relay-hooks/rsc/serverReadFragment.js.flow

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall relay
+ */
+
+'use strict';
+
+import type {Fragment, FragmentType, IEnvironment} from 'relay-runtime';
+
+const {waitForFragmentData} = require('relay-runtime/experimental');
+
+type HasSpread<TFragmentType> = {
+  +$fragmentSpreads: TFragmentType,
+  ...
+};
+
+async function serverReadFragment<TFragmentType extends FragmentType, TData>(
+  environment: IEnvironment,
+  fragment: Fragment<TFragmentType, TData>,
+  fragmentRef:
+    | HasSpread<TFragmentType>
+    | ReadonlyArray<HasSpread<TFragmentType>>,
+): Promise<TData> {
+  return waitForFragmentData(environment, fragment, fragmentRef);
+}
+
+module.exports = serverReadFragment;

package/relay-hooks/rsc/useQueryFromServer.js.flow

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall relay
+ */
+
+'use client';
+'use strict';
+
+import type {
+  PreloadedQueryRef,
+  PreloadedQueryResponse,
+} from './serverPreloadQuery';
+import type {Query, Variables} from 'relay-runtime';
+
+const usePreloadedQuery = require('../usePreloadedQuery');
+const useRelayEnvironment = require('../useRelayEnvironment');
+// $FlowFixMe[missing-export] React.use is available in React 19+
+const {use, useMemo} = require('react');
+const {
+  __internal,
+  ROOT_TYPE,
+  createOperationDescriptor,
+  getRequest,
+} = require('relay-runtime');
+
+const {defaultGetDataID, normalizeResponse} = __internal;
+
+// $FlowFixMe[unclear-type] WeakSet used for identity-based dedup only
+const committedRefs: WeakSet<any> = new WeakSet();
+
+const DEFAULT_STALE_MS = 30_000;
+
+function useQueryFromServer<TVariables extends Variables, TData>(
+  query: Query<TVariables, TData>,
+  queryRef: PreloadedQueryRef<TVariables, TData>,
+  options?: {staleThresholdMs?: number},
+): TData {
+  const environment = useRelayEnvironment();
+  const request = getRequest(query);
+  const threshold = options?.staleThresholdMs ?? DEFAULT_STALE_MS;
+  // TODO: Add a method to IEnvironment for server-side publish so custom
+  // IEnvironment implementations don't need to access _getDataID.
+  // $FlowFixMe[prop-missing] _getDataID is not on IEnvironment
+  // $FlowFixMe[unclear-type]
+  const getDataID: any = environment._getDataID ?? defaultGetDataID;
+
+  const response: PreloadedQueryResponse<TData> = use(queryRef._response);
+
+  const isFresh =
+    response.data != null && Date.now() - queryRef.fetchedAt <= threshold;
+
+  const shouldCommit = isFresh && !committedRefs.has(queryRef);
+
+  // Publish server data to the Relay store without notifying subscribers.
+  // This avoids the React "Cannot update a component while rendering a
+  // different component" error that occurs when store.notify() triggers
+  // setState in other mounted components that subscribe to overlapping records.
+  if (shouldCommit) {
+    committedRefs.add(queryRef);
+
+    const operation = createOperationDescriptor(request, queryRef.variables);
+
+    // $FlowFixMe[unclear-type]
+    const responsePayload: any = {
+      data: response.data,
+      errors: response.errors,
+    };
+    const relayPayload = normalizeResponse(
+      responsePayload,
+      operation.root,
+      ROOT_TYPE,
+      {
+        getDataID,
+        treatMissingFieldsAsNull: false,
+        deferDeduplicatedFields: false,
+        // $FlowFixMe[prop-missing]
+        log: environment.__log ?? null,
+        path: [],
+        shouldProcessClientComponents: false,
+      },
+      false,
+    );
+
+    environment.getStore().publish(relayPayload.source);
+  }
+
+  // Build a PreloadedQuery shim. Fresh data was committed to the store
+  // above, so source is null and fetchPolicy is "store-or-network".
+  // Stale path uses "network-only" to trigger a client-side refetch.
+  const preloadedQuery = useMemo(() => {
+    const isFreshAtMemo =
+      response.data != null && Date.now() - queryRef.fetchedAt <= threshold;
+
+    // If this queryRef was already committed to the store by a previous
+    // component instance, read from the store even if the server timestamp
+    // is past the staleness threshold. This prevents a network refetch
+    // from overwriting store mutations made after the initial commit.
+    const useStore = isFreshAtMemo || committedRefs.has(queryRef);
+
+    return {
+      kind: 'PreloadedQuery_DEPRECATED',
+      environment,
+      fetchKey: queryRef.fetchedAt,
+      fetchPolicy: useStore ? 'store-or-network' : 'network-only',
+      id: request.params.id ?? request.params.name,
+      name: request.params.name,
+      source: null,
+      variables: queryRef.variables,
+    };
+  }, [
+    environment,
+    queryRef.fetchedAt,
+    response.data,
+    queryRef.variables,
+    request.params.id,
+    request.params.name,
+    threshold,
+  ]);
+
+  // usePreloadedQuery expects an opaque PreloadedQuery that can only be
+  // created via loadQuery/useQueryLoader. There's no public API to create
+  // one from server-fetched data, so we construct a plain object with the
+  // fields usePreloadedQuery reads internally.
+  // $FlowFixMe[incompatible-call]
+  // $FlowFixMe[incompatible-type]
+  return usePreloadedQuery(query, preloadedQuery);
+}
+
+module.exports = useQueryFromServer;

package/relay-hooks/useClientQuery.js.flow

@@ -20,9 +20,9 @@ const useLazyLoadQuery = require('./useLazyLoadQuery');
  * These queries are consist of queries for client-only data,
  * schematized via local schema extensions and/or Relay resolvers.
  */
-hook useClientQuery<TVariables: Variables, TData, TRawResponse>(
+hook useClientQuery<TVariables extends Variables, TData, TRawResponse>(
   gqlQuery: ClientQuery<TVariables, TData, TRawResponse>,
-  variables: TVariables,
+  variables: NoInfer<TVariables>,
   options?: {
     UNSTABLE_renderPolicy?: RenderPolicy,
   },

package/relay-hooks/useEntryPointLoader.js.flow

@@ -25,12 +25,12 @@ const useIsMountedRef = require('./useIsMountedRef');
 const {useCallback, useEffect, useRef, useState} = require('react');
 
 type UseEntryPointLoaderHookReturnType<
-  TEntryPointParams: {...},
-  TPreloadedQueries: {...},
-  TPreloadedEntryPoints: {...},
-  TRuntimeProps: {...},
+  TEntryPointParams extends {...},
+  TPreloadedQueries extends {...},
+  TPreloadedEntryPoints extends {...},
+  TRuntimeProps extends {...},
   TExtraProps,
-  TEntryPointComponent: EntryPointComponent<
+  TEntryPointComponent extends EntryPointComponent<
     TPreloadedQueries,
     TPreloadedEntryPoints,
     TRuntimeProps,
@@ -53,19 +53,19 @@ const initialNullEntryPointReferenceState: NullEntryPointReference = {
 };
 
 hook useLoadEntryPoint<
-  TEntryPointParams: {...},
+  TEntryPointParams extends {...},
   // $FlowExpectedError[unclear-type] Need any to make it supertype of all PreloadedQuery
-  TPreloadedQueries: {+[string]: PreloadedQuery<any>},
-  TPreloadedEntryPoints: {...},
-  TRuntimeProps: {...},
+  TPreloadedQueries extends {+[string]: PreloadedQuery<any>},
+  TPreloadedEntryPoints extends {...},
+  TRuntimeProps extends {...},
   TExtraProps,
-  TEntryPointComponent: EntryPointComponent<
+  TEntryPointComponent extends EntryPointComponent<
     TPreloadedQueries,
     TPreloadedEntryPoints,
     TRuntimeProps,
     TExtraProps,
   >,
-  TEntryPoint: EntryPoint<TEntryPointParams, TEntryPointComponent>,
+  TEntryPoint extends EntryPoint<TEntryPointParams, TEntryPointComponent>,
 >(
   environmentProvider: IEnvironmentProvider<EnvironmentProviderOptions>,
   entryPoint: TEntryPoint,

package/relay-hooks/useFragment.js.flow

@@ -24,30 +24,30 @@ type HasSpread<TFragmentType> = {
 };
 
 // if the key is non-nullable, return non-nullable value
-declare hook useFragment<TFragmentType: FragmentType, TData>(
+declare hook useFragment<TFragmentType extends FragmentType, TData>(
   fragment: Fragment<TFragmentType, TData>,
   key: HasSpread<TFragmentType>,
 ): TData;
 
 // if the key is nullable, return nullable value
-declare hook useFragment<TFragmentType: FragmentType, TData>(
+declare hook useFragment<TFragmentType extends FragmentType, TData>(
   fragment: Fragment<TFragmentType, TData>,
   key: ?HasSpread<TFragmentType>,
 ): ?TData;
 
 // if the key is a non-nullable array of keys, return non-nullable array
-declare hook useFragment<TFragmentType: FragmentType, TData>(
+declare hook useFragment<TFragmentType extends FragmentType, TData>(
   fragment: Fragment<TFragmentType, TData>,
-  key: $ReadOnlyArray<HasSpread<TFragmentType>>,
+  key: ReadonlyArray<HasSpread<TFragmentType>>,
 ): TData;
 
 // if the key is a nullable array of keys, return nullable array
-declare hook useFragment<TFragmentType: FragmentType, TData>(
+declare hook useFragment<TFragmentType extends FragmentType, TData>(
   fragment: Fragment<TFragmentType, TData>,
-  key: ?$ReadOnlyArray<HasSpread<TFragmentType>>,
+  key: ?ReadonlyArray<HasSpread<TFragmentType>>,
 ): ?TData;
 
-hook useFragment(fragment: GraphQLTaggedNode, key: mixed): mixed {
+hook useFragment(fragment: GraphQLTaggedNode, key: unknown): unknown {
   const fragmentNode = getFragment(fragment);
   useStaticFragmentNodeWarning(fragmentNode, 'first argument of useFragment()');
   const data = useFragmentInternal(fragmentNode, key, 'useFragment()');

package/relay-hooks/useFragmentInternal.js.flow

@@ -20,7 +20,7 @@ import {RelayFeatureFlags} from 'relay-runtime';
 
 hook useFragmentInternal(
   fragmentNode: ReaderFragment,
-  fragmentRef: mixed,
+  fragmentRef: unknown,
   hookDisplayName: string,
   queryOptions?: FragmentQueryOptions,
 ): ?SelectorData | Array<?SelectorData> {