relay-runtime 20.1.1 → 21.0.0

package/lib/store/RelayStoreSubscriptions.js

@@ -9,6 +9,7 @@ var RelayReader = require('./RelayReader');
 var RelayStoreSubscriptions = /*#__PURE__*/function () {
   function RelayStoreSubscriptions(log, resolverCache, resolverContext) {
     this._subscriptions = new Set();
+    this._staleSubscriptions = new Set();
     this.__log = log;
     this._resolverCache = resolverCache;
     this._resolverContext = resolverContext;
@@ -24,6 +25,9 @@ var RelayStoreSubscriptions = /*#__PURE__*/function () {
     };
     var dispose = function dispose() {
       _this._subscriptions["delete"](subscription);
+      if (RelayFeatureFlags.OPTIMIZE_NOTIFY && subscription.stale) {
+        _this._staleSubscriptions["delete"](subscription);
+      }
     };
     this._subscriptions.add(subscription);
     return {
@@ -38,39 +42,56 @@ var RelayStoreSubscriptions = /*#__PURE__*/function () {
         return;
       }
       var snapshot = subscription.snapshot;
-      var backup = RelayReader.read(source, snapshot.selector, _this2._resolverCache, _this2._resolverContext);
+      var backup = RelayReader.read(source, snapshot.selector, _this2.__log, _this2._resolverCache, _this2._resolverContext);
       var nextData = recycleNodesInto(snapshot.data, backup.data);
       backup.data = nextData;
       subscription.backup = backup;
     });
   };
   _proto.restoreSubscriptions = function restoreSubscriptions() {
+    var _this3 = this;
     this._subscriptions.forEach(function (subscription) {
       var backup = subscription.backup;
       subscription.backup = null;
       if (backup) {
         if (backup.data !== subscription.snapshot.data) {
           subscription.stale = true;
+          if (RelayFeatureFlags.OPTIMIZE_NOTIFY) {
+            _this3._staleSubscriptions.add(subscription);
+          }
         }
         subscription.snapshot = {
           data: subscription.snapshot.data,
+          fieldErrors: backup.fieldErrors,
           isMissingData: backup.isMissingData,
           missingClientEdges: backup.missingClientEdges,
           missingLiveResolverFields: backup.missingLiveResolverFields,
           seenRecords: backup.seenRecords,
-          selector: backup.selector,
-          fieldErrors: backup.fieldErrors
+          selector: backup.selector
         };
       } else {
         subscription.stale = true;
+        if (RelayFeatureFlags.OPTIMIZE_NOTIFY) {
+          _this3._staleSubscriptions.add(subscription);
+        }
       }
     });
   };
   _proto.updateSubscriptions = function updateSubscriptions(source, updatedRecordIDs, updatedOwners, sourceOperation) {
-    var _this3 = this;
+    var _this4 = this;
     var hasUpdatedRecords = updatedRecordIDs.size !== 0;
     this._subscriptions.forEach(function (subscription) {
-      var owner = _this3._updateSubscription(source, subscription, updatedRecordIDs, hasUpdatedRecords, sourceOperation);
+      var owner = _this4._updateSubscription(source, subscription, updatedRecordIDs, hasUpdatedRecords, sourceOperation);
+      if (owner != null) {
+        updatedOwners.push(owner);
+      }
+    });
+  };
+  _proto.updateStaleSubscriptions = function updateStaleSubscriptions(source, updatedRecordIDs, updatedOwners, sourceOperation) {
+    var _this5 = this;
+    var hasUpdatedRecords = updatedRecordIDs.size !== 0;
+    this._staleSubscriptions.forEach(function (subscription) {
+      var owner = _this5._updateSubscription(source, subscription, updatedRecordIDs, hasUpdatedRecords, sourceOperation);
       if (owner != null) {
         updatedOwners.push(owner);
       }
@@ -85,29 +106,32 @@ var RelayStoreSubscriptions = /*#__PURE__*/function () {
     if (!stale && !hasOverlappingUpdates) {
       return;
     }
-    var nextSnapshot = hasOverlappingUpdates || !backup ? RelayReader.read(source, snapshot.selector, this._resolverCache, this._resolverContext) : backup;
+    var nextSnapshot = hasOverlappingUpdates || !backup ? RelayReader.read(source, snapshot.selector, this.__log, this._resolverCache, this._resolverContext) : backup;
     var nextData = recycleNodesInto(snapshot.data, nextSnapshot.data);
     nextSnapshot = {
       data: nextData,
+      fieldErrors: nextSnapshot.fieldErrors,
       isMissingData: nextSnapshot.isMissingData,
       missingClientEdges: nextSnapshot.missingClientEdges,
       missingLiveResolverFields: nextSnapshot.missingLiveResolverFields,
       seenRecords: nextSnapshot.seenRecords,
-      selector: nextSnapshot.selector,
-      fieldErrors: nextSnapshot.fieldErrors
+      selector: nextSnapshot.selector
     };
     if (process.env.NODE_ENV !== "production") {
       deepFreeze(nextSnapshot);
     }
     subscription.snapshot = nextSnapshot;
     subscription.stale = false;
+    if (RelayFeatureFlags.OPTIMIZE_NOTIFY && stale) {
+      this._staleSubscriptions["delete"](subscription);
+    }
     if (nextSnapshot.data !== snapshot.data) {
       if (this.__log && RelayFeatureFlags.ENABLE_NOTIFY_SUBSCRIPTION) {
         this.__log({
           name: 'store.notify.subscription',
-          sourceOperation: sourceOperation,
+          nextSnapshot: nextSnapshot,
           snapshot: snapshot,
-          nextSnapshot: nextSnapshot
+          sourceOperation: sourceOperation
         });
       }
       callback(nextSnapshot);

package/lib/store/RelayStoreUtils.js

@@ -13,6 +13,7 @@ var VARIABLE = RelayConcreteNode.VARIABLE,
   OBJECT_VALUE = RelayConcreteNode.OBJECT_VALUE,
   LIST_VALUE = RelayConcreteNode.LIST_VALUE;
 var ERRORS_KEY = '__errors';
+var FIELD_GRANULAR_NOTIFICATIONS_KEY = '__fieldGranularNotifications';
 var MODULE_COMPONENT_KEY_PREFIX = '__module_component_';
 var MODULE_OPERATION_KEY_PREFIX = '__module_operation_';
 var RELAY_READ_TIME_RESOLVER_KEY_PREFIX = '$r:';
@@ -126,6 +127,9 @@ function getModuleComponentKey(documentName) {
 function getModuleOperationKey(documentName) {
   return "".concat(MODULE_OPERATION_KEY_PREFIX).concat(documentName);
 }
+function getFieldNotificationKey(dataID, storageKey) {
+  return "__fn:".concat(dataID, ":").concat(storageKey);
+}
 var RelayStoreUtils = {
   ACTOR_IDENTIFIER_KEY: '__actorIdentifier',
   CLIENT_EDGE_TRAVERSAL_PATH: '__clientEdgeTraversalPath',
@@ -135,6 +139,7 @@ var RelayStoreUtils = {
   FRAGMENT_PROP_NAME_KEY: '__fragmentPropName',
   MODULE_COMPONENT_KEY: '__module_component',
   ERRORS_KEY: ERRORS_KEY,
+  FIELD_GRANULAR_NOTIFICATIONS_KEY: FIELD_GRANULAR_NOTIFICATIONS_KEY,
   ID_KEY: '__id',
   REF_KEY: '__ref',
   REFS_KEY: '__refs',
@@ -147,6 +152,7 @@ var 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: RELAY_READ_TIME_RESOLVER_KEY_PREFIX,
   formatStorageKey: formatStorageKey,
   getArgumentValue: getArgumentValue,
@@ -156,6 +162,7 @@ var RelayStoreUtils = {
   getReadTimeResolverStorageKey: getReadTimeResolverStorageKey,
   getStableStorageKey: getStableStorageKey,
   getModuleComponentKey: getModuleComponentKey,
-  getModuleOperationKey: getModuleOperationKey
+  getModuleOperationKey: getModuleOperationKey,
+  getFieldNotificationKey: getFieldNotificationKey
 };
 module.exports = RelayStoreUtils;

package/lib/store/ResolverFragments.js

@@ -36,7 +36,7 @@ function readFragment(fragmentInput, fragmentKey) {
 }
 var RESOLVER_FRAGMENT_ERRORED_SENTINEL = {};
 module.exports = {
+  RESOLVER_FRAGMENT_ERRORED_SENTINEL: RESOLVER_FRAGMENT_ERRORED_SENTINEL,
   readFragment: readFragment,
-  withResolverContext: withResolverContext,
-  RESOLVER_FRAGMENT_ERRORED_SENTINEL: RESOLVER_FRAGMENT_ERRORED_SENTINEL
+  withResolverContext: withResolverContext
 };

package/lib/store/live-resolvers/LiveResolverCache.js

@@ -20,6 +20,7 @@ var _require5 = require('../RelayStoreUtils'),
   RELAY_RESOLVER_ERROR_KEY = _require5.RELAY_RESOLVER_ERROR_KEY,
   RELAY_RESOLVER_INVALIDATION_KEY = _require5.RELAY_RESOLVER_INVALIDATION_KEY,
   RELAY_RESOLVER_OUTPUT_TYPE_RECORD_IDS = _require5.RELAY_RESOLVER_OUTPUT_TYPE_RECORD_IDS,
+  RELAY_RESOLVER_RECORD_TYPENAME = _require5.RELAY_RESOLVER_RECORD_TYPENAME,
   RELAY_RESOLVER_SNAPSHOT_KEY = _require5.RELAY_RESOLVER_SNAPSHOT_KEY,
   RELAY_RESOLVER_VALUE_KEY = _require5.RELAY_RESOLVER_VALUE_KEY,
   getReadTimeResolverStorageKey = _require5.getReadTimeResolverStorageKey,
@@ -33,7 +34,6 @@ var warning = require("fbjs/lib/warning");
 var RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY = '__resolverLiveStateSubscription';
 var RELAY_RESOLVER_LIVE_STATE_VALUE = '__resolverLiveStateValue';
 var RELAY_RESOLVER_LIVE_STATE_DIRTY = '__resolverLiveStateDirty';
-var RELAY_RESOLVER_RECORD_TYPENAME = '__RELAY_RESOLVER__';
 var MODEL_PROPERTY_NAME = '__relay_model_instance';
 function addDependencyEdge(edges, from, to) {
   var set = edges.get(from);
@@ -204,6 +204,21 @@ var LiveResolverCache = /*#__PURE__*/function () {
       this._handlingBatch = false;
     }
   };
+  _proto.batchLiveStateUpdatesWithoutNotify = function batchLiveStateUpdatesWithoutNotify(callback) {
+    !!this._handlingBatch ? process.env.NODE_ENV !== "production" ? invariant(false, 'Unexpected nested call to batchLiveStateUpdates.') : invariant(false) : void 0;
+    this._handlingBatch = true;
+    try {
+      callback();
+    } finally {
+      var shouldPublish = this._liveResolverBatchRecordSource != null;
+      if (shouldPublish) {
+        this._store.publish(this._liveResolverBatchRecordSource);
+      }
+      this._liveResolverBatchRecordSource = null;
+      this._handlingBatch = false;
+      return shouldPublish;
+    }
+  };
   _proto._setLiveResolverValue = function _setLiveResolverValue(resolverRecord, liveValue, field, variables) {
     var value = null;
     var resolverError = null;
@@ -278,6 +293,7 @@ var LiveResolverCache = /*#__PURE__*/function () {
     } else {
       shallowFreeze(value);
       RelayModernRecord.setValue(resolverRecord, RELAY_RESOLVER_VALUE_KEY, value);
+      RelayModernRecord.setValue(resolverRecord, RELAY_RESOLVER_OUTPUT_TYPE_RECORD_IDS, new Set());
     }
     return updatedDataIDs;
   };
@@ -514,20 +530,20 @@ function unsubscribeFromLiveResolverRecordsImpl(recordSource, invalidatedDataIDs
   if (invalidatedDataIDs.size === 0) {
     return;
   }
-  var _iterator10 = (0, _createForOfIteratorHelper2["default"])(invalidatedDataIDs),
-    _step10;
+  var _iterator0 = (0, _createForOfIteratorHelper2["default"])(invalidatedDataIDs),
+    _step0;
   try {
-    for (_iterator10.s(); !(_step10 = _iterator10.n()).done;) {
-      var dataID = _step10.value;
+    for (_iterator0.s(); !(_step0 = _iterator0.n()).done;) {
+      var dataID = _step0.value;
       var record = recordSource.get(dataID);
       if (record != null && isResolverRecord(record)) {
         maybeUnsubscribeFromLiveState(record);
       }
     }
   } catch (err) {
-    _iterator10.e(err);
+    _iterator0.e(err);
   } finally {
-    _iterator10.f();
+    _iterator0.f();
   }
 }
 function isResolverRecord(record) {
@@ -555,6 +571,6 @@ function getConcreteTypename(normalizationInfo, currentValue) {
 }
 module.exports = {
   LiveResolverCache: LiveResolverCache,
-  getUpdatedDataIDs: getUpdatedDataIDs,
-  RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY: RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY
+  RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY: RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY,
+  getUpdatedDataIDs: getUpdatedDataIDs
 };

package/lib/store/observeFragmentExperimental.js

@@ -46,8 +46,8 @@ function observeFragment(environment, fragment, fragmentRef) {
   var _fragmentNode$metadat;
   var fragmentNode = getFragment(fragment);
   var fragmentSelector = getSelector(fragmentNode, fragmentRef);
-  !(((_fragmentNode$metadat = fragmentNode.metadata) === null || _fragmentNode$metadat === void 0 ? void 0 : _fragmentNode$metadat.hasClientEdges) == null) ? process.env.NODE_ENV !== "production" ? invariant(false, "Client edges aren't supported yet.") : invariant(false) : void 0;
   !(fragmentSelector != null) ? process.env.NODE_ENV !== "production" ? invariant(false, 'Expected a selector, got null.') : invariant(false) : void 0;
+  !(((_fragmentNode$metadat = fragmentNode.metadata) === null || _fragmentNode$metadat === void 0 ? void 0 : _fragmentNode$metadat.hasClientEdges) == null || fragmentSelectorUsesExecTimeResolver(fragmentSelector)) ? process.env.NODE_ENV !== "production" ? invariant(false, "Client edges aren't supported yet.") : invariant(false) : void 0;
   switch (fragmentSelector.kind) {
     case 'SingularReaderSelector':
       return observeSingularSelector(environment, fragment, fragmentSelector);
@@ -58,6 +58,22 @@ function observeFragment(environment, fragment, fragmentRef) {
   }
   !false ? process.env.NODE_ENV !== "production" ? invariant(false, 'Unsupported fragment selector kind') : invariant(false) : void 0;
 }
+function fragmentSelectorUsesExecTimeResolver(fragmentSelector) {
+  var _fragmentSelector$own, _fragmentSelector$own2, _fragmentSelector$own3, _fragmentSelector$own4;
+  switch (fragmentSelector === null || fragmentSelector === void 0 ? void 0 : fragmentSelector.kind) {
+    case 'SingularReaderSelector':
+      return ((_fragmentSelector$own = (_fragmentSelector$own2 = fragmentSelector.owner.node.operation) === null || _fragmentSelector$own2 === void 0 ? void 0 : _fragmentSelector$own2.use_exec_time_resolvers) !== null && _fragmentSelector$own !== void 0 ? _fragmentSelector$own : (_fragmentSelector$own3 = fragmentSelector.owner.node.operation) === null || _fragmentSelector$own3 === void 0 ? void 0 : (_fragmentSelector$own4 = _fragmentSelector$own3.exec_time_resolvers_enabled_provider) === null || _fragmentSelector$own4 === void 0 ? void 0 : _fragmentSelector$own4.get()) === true;
+    case 'PluralReaderSelector':
+      {
+        var _fragmentSelector$sel;
+        return (_fragmentSelector$sel = fragmentSelector.selectors) === null || _fragmentSelector$sel === void 0 ? void 0 : _fragmentSelector$sel.every(function (selector) {
+          var _selector$owner$node$, _selector$owner$node$2, _selector$owner$node$3;
+          return ((_selector$owner$node$ = selector.owner.node.operation.use_exec_time_resolvers) !== null && _selector$owner$node$ !== void 0 ? _selector$owner$node$ : (_selector$owner$node$2 = selector.owner.node.operation) === null || _selector$owner$node$2 === void 0 ? void 0 : (_selector$owner$node$3 = _selector$owner$node$2.exec_time_resolvers_enabled_provider) === null || _selector$owner$node$3 === void 0 ? void 0 : _selector$owner$node$3.get()) === true;
+        });
+      }
+  }
+  return false;
+}
 function observeSingularSelector(environment, fragmentNode, fragmentSelector) {
   var snapshot = environment.lookup(fragmentSelector);
   return Observable.create(function (sink) {

package/lib/store/observeQueryExperimental.js

@@ -9,9 +9,9 @@ var _require2 = require('./RelayModernOperationDescriptor'),
 function observeQuery(environment, gqlQuery, variables) {
   var operation = createOperationDescriptor(gqlQuery, variables);
   var rootFragmentRef = {
-    __id: operation.fragment.dataID,
+    __fragmentOwner: operation.request,
     __fragments: (0, _defineProperty2["default"])({}, operation.fragment.node.name, operation.request.variables),
-    __fragmentOwner: operation.request
+    __id: operation.fragment.dataID
   };
   var fragmentNode = operation.request.node.fragment;
   return observeFragment(environment, fragmentNode, rootFragmentRef);

package/lib/subscription/requestSubscription.js

@@ -27,6 +27,8 @@ function requestSubscription(environment, config) {
     operation: operation,
     updater: updater
   }).subscribe({
+    complete: onCompleted,
+    error: onError,
     next: function next(responses) {
       if (onNext != null) {
         var selector = operation.fragment;
@@ -44,9 +46,7 @@ function requestSubscription(environment, config) {
         var data = environment.lookup(selector).data;
         onNext(data);
       }
-    },
-    error: onError,
-    complete: onCompleted
+    }
   });
   return {
     dispose: sub.unsubscribe

package/lib/util/RelayError.js

@@ -1,6 +1,7 @@
 'use strict';
 
 function createError(type, name, messageFormat) {
+  var _messageParams$;
   for (var _len = arguments.length, messageParams = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++) {
     messageParams[_key - 3] = arguments[_key];
   }
@@ -9,11 +10,13 @@ function createError(type, name, messageFormat) {
     return String(messageParams[index++]);
   });
   var err = new Error(message);
+  var operation = (_messageParams$ = messageParams[2]) !== null && _messageParams$ !== void 0 ? _messageParams$ : null;
   var error = Object.assign(err, {
     name: name,
     messageFormat: messageFormat,
     messageParams: messageParams,
     type: type,
+    operation: operation,
     taalOpcodes: [2, 2]
   });
   if (error.stack === undefined) {

package/lib/util/RelayFeatureFlags.js

@@ -20,12 +20,16 @@ var RelayFeatureFlags = {
   PROCESS_OPTIMISTIC_UPDATE_BEFORE_SUBSCRIPTION: false,
   MARK_RESOLVER_VALUES_AS_CLEAN_AFTER_FRAGMENT_REREAD: false,
   ENABLE_CYLE_DETECTION_IN_VARIABLES: false,
-  ENABLE_ACTIVITY_COMPATIBILITY: false,
+  ENABLE_ACTIVITY_COMPATIBILITY: true,
   ENABLE_READ_TIME_RESOLVER_STORAGE_KEY_PREFIX: true,
   ENABLE_USE_PAGINATION_IS_LOADING_FIX: false,
   DISALLOW_NESTED_UPDATES: false,
   ENABLE_TYPENAME_PREFIXED_DATA_ID: false,
   ENABLE_UI_CONTEXT_ON_RELAY_LOGGER: false,
-  CHECK_ALL_FRAGMENTS_FOR_MISSING_CLIENT_EDGES: false
+  CHECK_ALL_FRAGMENTS_FOR_MISSING_CLIENT_EDGES: false,
+  FILTER_OUT_RELAY_RESOLVER_RECORDS: false,
+  OPTIMIZE_NOTIFY: false,
+  ENABLE_FIELD_GRANULAR_NOTIFICATIONS: false,
+  ENABLE_READER_FRAGMENTS_LOGGING: false
 };
 module.exports = RelayFeatureFlags;

package/lib/util/RelayReplaySubject.js

@@ -59,8 +59,8 @@ var RelayReplaySubject = /*#__PURE__*/function () {
     }
     this._complete = true;
     this._events.push({
-      kind: 'error',
-      error: _error
+      error: _error,
+      kind: 'error'
     });
     this._sinks.forEach(function (sink) {
       return sink.error(_error);
@@ -71,8 +71,8 @@ var RelayReplaySubject = /*#__PURE__*/function () {
       return;
     }
     this._events.push({
-      kind: 'next',
-      data: data
+      data: data,
+      kind: 'next'
     });
     this._sinks.forEach(function (sink) {
       return sink.next(data);

package/lib/util/handlePotentialSnapshotErrors.js

@@ -71,6 +71,6 @@ function handlePotentialSnapshotErrors(environment, fieldErrors, loggingContext)
   }
 }
 module.exports = {
-  handlePotentialSnapshotErrors: handlePotentialSnapshotErrors,
-  eventShouldThrow: eventShouldThrow
+  eventShouldThrow: eventShouldThrow,
+  handlePotentialSnapshotErrors: handlePotentialSnapshotErrors
 };

package/lib/util/stableCopy.js

@@ -30,6 +30,6 @@ function hasCycle(value) {
   });
 }
 module.exports = {
-  stableCopy: stableCopy,
-  hasCycle: hasCycle
+  hasCycle: hasCycle,
+  stableCopy: stableCopy
 };

package/llm-docs/api-reference/entrypoint-apis/entrypoint-container.mdx

@@ -0,0 +1,38 @@
+---
+id: entrypoint-container
+title: EntryPointContainer
+slug: /api-reference/entrypoint-container/
+description: API reference for EntryPointContainer, a React component used to render the root component of an entrypoint
+keywords:
+  - entrypoint
+  - container
+  - root
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `EntryPointContainer`
+
+<FbInternalOnly>
+
+For more information, see the [Defining EntryPoints](../../guides/entrypoints/using-entrypoints/#defining-entrypoints) and [Consuming EntryPoints](../../guides/entrypoints/using-entrypoints/#-entrypoints) guides.
+
+</FbInternalOnly>
+
+```js
+function EntryPointContainer({
+  entryPointReference,
+  props,
+}: {
+  +entryPointReference: PreloadedEntryPoint<TEntryPointComponent>,
+  +props: TRuntimeProps,
+}): ReactElement
+```
+
+A React component that renders a preloaded EntryPoint.
+
+* `entryPointReference`: the value returned from a call to `loadEntryPoint` or acquired from the `useEntryPointLoader` hook.
+* `props`: additional runtime props that will be passed to the `Component`
+
+<DocsRating />

package/llm-docs/api-reference/entrypoint-apis/load-entrypoint.mdx

@@ -0,0 +1,77 @@
+---
+id: load-entrypoint
+title: loadEntryPoint
+slug: /api-reference/load-entrypoint/
+description: API reference for loadEntryPoint, which imperatively loads an entrypoint and data for its queries
+keywords:
+  - entrypoint
+  - preload
+  - render-as-you-fetch
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `loadEntryPoint`
+
+This function is designed to be used with `EntryPointContainer` to implement the "render-as-you-fetch" pattern.
+
+EntryPoint references returned from `loadEntryPoint` will leak data to the Relay store (if they have associated queries) unless `.dispose()` is called on them once they are no longer referenced. As such, prefer using `useEntryPointLoader` when possible, which ensures that EntryPoint references are correctly disposed for you. See the [`useEntryPointLoader`](../use-entrypoint-loader) docs for a more complete example.
+
+<FbInternalOnly>
+
+For more information, see the [Loading EntryPoints](../../guides/entrypoints/using-entrypoints/#loading-entrypoints) guide.
+
+</FbInternalOnly>
+
+```js
+const EntryPoint = require('MyComponent.entrypoint.js');
+
+const {loadQuery} = require('react-relay');
+
+// Generally, your component should access the environment from the React context,
+// and pass that environment to this function.
+const getEntrypointReference = environment => loadEntryPoint(
+  { getEnvironment: () => environment },
+  EntryPoint,
+  {id: '4'},
+);
+
+// later: pass entryPointReference to EntryPointContainer
+// Note that EntryPoint references should have .dispose() called on them,
+// which is missing in this example.
+```
+
+### Arguments
+
+* `environmentProvider`: A provider for a Relay Environment instance on which to execute the request. If you're starting this request somewhere within a React component, you probably want to use the environment you obtain from using [`useRelayEnvironment`](../use-relay-environment/).
+* `EntryPoint`: EntryPoint to load.
+* `entryPointParams`: Parameters that will be passed to the EntryPoint's `getPreloadProps` method.
+
+### Flow Type Parameters
+
+* `TEntryPointParams`: Type parameter corresponding to the type of the first parameter of the `getPreloadProps` method of the EntryPoint.
+* `TPreloadedQueries`: the type of the `queries` parameter to the EntryPoint component.
+* `TPreloadedEntryPoints`: the type of the `entrypoints` parameter passed to the EntryPoint component.
+* `TRuntimeProps`: the type of the `props` prop passed to `EntryPointContainer`. This object is passed down to the EntryPoint component, also as `props`.
+* `TExtraProps`: if an EntryPoint's `getPreloadProps` method returns an object with an `extraProps` property, those extra props will be passed to the EntryPoint component as `extraProps`.
+* `TEntryPointComponent`: the type of the EntryPoint.
+* `TEntryPoint`: the type of the EntryPoint.
+
+### Return Value
+
+An EntryPoint reference with the following properties:
+
+* `dispose`: a method that will release any query references loaded by this EntryPoint (including indirectly, by way of other EntryPoints) from being retained by the store. This can cause the data referenced by these query reference to be garbage collected.
+
+The exact format of the return value is *unstable and highly likely to change*. We strongly recommend not using any other properties of the return value, as such code would be highly likely to break when upgrading to future versions of Relay. Instead, pass the result of `loadEntryPoint()` to `EntryPointContainer`.
+
+### Behavior
+
+* When `loadEntryPoint()` is called, each of an EntryPoint's associated queries (if it has any) will load their query data and query AST. Once both the query AST and the data are available, the data will be written to the store. This differs from the behavior of `prepareEntryPoint_DEPRECATED`, which would only write the data from an associated query to the store when that query was rendered with `usePreloadedQuery`.
+* The EntryPoint reference's associated query references will be retained by the Relay store, preventing the data from being garbage collected. Once you call `.dispose()` on the EntryPoint reference, the data from the associated queries is liable to be garbage collected.
+* `loadEntryPoint` may throw an error if it is called during React's render phase.
+
+
+
+<DocsRating />

package/llm-docs/api-reference/entrypoint-apis/use-entrypoint-loader.mdx

@@ -0,0 +1,99 @@
+---
+id: use-entrypoint-loader
+title: useEntryPointLoader
+slug: /api-reference/use-entrypoint-loader/
+description: API reference for useEntryPointLoader, a React hook used to load entrypoints in response to user events
+keywords:
+  - render-as-you-fetch
+  - entrypoint
+  - preload
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `useEntryPointLoader`
+
+Hook used to make it easy to safely work with EntryPoints, while avoiding data leaking into the Relay store. It will keep an EntryPoint reference in state, and dispose of it when it is no longer accessible via state.
+
+<FbInternalOnly>
+
+For more information, see the [Loading EntryPoints](https://www.internalfb.com/intern/wiki/Relay/Guides/entry-points/#loading-entrypoints) guide.
+
+</FbInternalOnly>
+
+```js
+const {useEntryPointLoader, EntryPointContainer} = require('react-relay');
+
+const ComponentEntryPoint = require('Component.entrypoint');
+
+function EntryPointRevealer(): React.MixedElement {
+  const environmentProvider = useMyEnvironmentProvider();
+  const [
+    entryPointReference,
+    loadEntryPoint,
+    disposeEntryPoint,
+  ] = useEntryPointLoader(environmentProvider, ComponentEntryPoint);
+
+  return (
+    <>
+      {
+        entryPointReference == null && (
+          <Button onClick={() => loadEntryPoint({})}>
+            Click to reveal the contents of the EntryPoint
+          </Button>
+        )
+      }
+      {
+        entryPointReference != null && (
+          <>
+            <Button onClick={disposeEntryPoint}>
+              Click to hide and dispose the EntryPoint.
+            </Button>
+            <Suspense fallback="Loading...">
+              <EntryPointContainer
+                entryPointReference={entryPointReference}
+                props={{}}
+              />
+            </Suspense>
+          </>
+        )
+      }
+    </>
+  );
+}
+```
+
+### Arguments
+
+* `environmentProvider`: an object with a `getEnvironment` method that returns a Relay environment.
+* `EntryPoint`: the EntryPoint, usually acquired by importing a `.entrypoint.js` file.
+
+### Flow Type Parameters
+
+* `TEntryPointParams`: the type of the first argument to the `getPreloadProps` method of the EntryPoint.
+* `TPreloadedQueries`: the type of the `queries` prop passed to the EntryPoint component.
+* `TPreloadedEntryPoints`: the type of the `entryPoints` prop passed to the EntryPoint component.
+* `TRuntimeProps`: the type of the `props` prop passed to `EntryPointContainer`. This object is passed down to the EntryPoint component, also as `props`.
+* `TExtraProps`: if an EntryPoint's `getPreloadProps` method returns an object with an `extraProps` property, those extra props will be passed to the EntryPoint component as `extraProps` and have type `TExtraProps`.
+* `TEntryPointComponent`: the type of the EntryPoint component.
+* `TEntryPoint`: the type of the EntryPoint.
+
+### Return value
+
+A tuple containing the following values:
+
+* `entryPointReference`: the EntryPoint reference, or `null`.
+* `loadEntryPoint`: a callback that, when executed, will load an EntryPoint, which will be accessible as `entryPointReference`. If a previous EntryPoint was loaded, it will dispose of it. It may throw an error if called during React's render phase.
+    * Parameters
+        * `params: TEntryPointParams`: the params passed to the EntryPoint's `getPreloadProps` method.
+* `disposeEntryPoint`: a callback that, when executed, will set `entryPointReference` to `null` and call `.dispose()` on it. It has type `() => void`. It should not be called during React's render phase.
+
+### Behavior
+
+* When the `loadEntryPoint` callback is called, each of an EntryPoint's associated queries (if it has any) will load their query data and query AST. Once both the query AST and the data are available, the data will be written to the store. This differs from the behavior of `prepareEntryPoint_DEPRECATED`, which would only write the data from an associated query to the store when that query was rendered with `usePreloadedQuery`.
+* The EntryPoint reference's associated query references will be retained by the Relay store, preventing the data from being garbage collected. Once you call `.dispose()` on the EntryPoint reference, the data from the associated queries is liable to be garbage collected.
+* The `loadEntryPoint` callback may throw an error if it is called during React's render phase.
+
+
+<DocsRating />