relay-runtime 0.0.0-main-d112a76d → 0.0.0-main-e186ff01

package/experimental.js

@@ -1,5 +1,5 @@
 /**
- * Relay v0.0.0-main-d112a76d
+ * Relay v0.0.0-main-e186ff01
  *
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *

package/index.js

@@ -1,5 +1,5 @@
 /**
- * Relay v0.0.0-main-d112a76d
+ * Relay v0.0.0-main-e186ff01
  *
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *

package/lib/store/RelayReader.js

@@ -186,7 +186,7 @@ var RelayReader = /*#__PURE__*/function () {
     !this._variables.hasOwnProperty(name) ? process.env.NODE_ENV !== "production" ? invariant(false, 'RelayReader(): Undefined variable `%s`.', name) : invariant(false) : void 0;
     return this._variables[name];
   };
-  _proto._maybeReportUnexpectedNull = function _maybeReportUnexpectedNull(selection) {
+  _proto._maybeReportUnexpectedNull = function _maybeReportUnexpectedNull(selection, fieldValue) {
     if (selection.action === 'NONE') {
       return;
     }
@@ -202,10 +202,19 @@ var RelayReader = /*#__PURE__*/function () {
       var _selection$field$alia;
       fieldName = (_selection$field$alia = selection.field.alias) !== null && _selection$field$alia !== void 0 ? _selection$field$alia : selection.field.name;
     }
+    var fieldError = null;
+    if (fieldValue === null && this._fieldErrors.length > 0) {
+      var lastError = this._fieldErrors[this._fieldErrors.length - 1];
+      if (lastError.kind === 'relay_field_payload.error') {
+        fieldError = lastError.error;
+      }
+    }
     switch (selection.action) {
       case 'THROW':
         this._fieldErrors.push({
+          fieldError: fieldError,
           fieldPath: fieldName,
+          fieldValue: fieldValue,
           handled: false,
           kind: 'missing_required_field.throw',
           owner: owner,
@@ -214,7 +223,9 @@ var RelayReader = /*#__PURE__*/function () {
         return;
       case 'LOG':
         this._fieldErrors.push({
+          fieldError: fieldError,
           fieldPath: fieldName,
+          fieldValue: fieldValue,
           kind: 'missing_required_field.log',
           owner: owner,
           uiContext: undefined
@@ -226,7 +237,7 @@ var RelayReader = /*#__PURE__*/function () {
   };
   _proto._handleRequiredFieldValue = function _handleRequiredFieldValue(selection, value) {
     if (value == null) {
-      this._maybeReportUnexpectedNull(selection);
+      this._maybeReportUnexpectedNull(selection, value);
       return false;
     }
     return true;
@@ -281,9 +292,17 @@ var RelayReader = /*#__PURE__*/function () {
             message: "Relay: Error in resolver for field at ".concat(error.fieldPath, " in ").concat(error.owner)
           };
         case 'missing_required_field.throw':
-          return {
-            message: "Relay: Missing @required value at path '".concat(error.fieldPath, "' in '").concat(error.owner, "'.")
-          };
+          {
+            var reason;
+            if (error.fieldValue === null) {
+              reason = error.fieldError != null ? "the server returned null with an error: ".concat(error.fieldError.message) : 'the server returned null';
+            } else {
+              reason = 'the field was missing in the store (data may not have been fetched, or was removed by a graph relationship change: https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change)';
+            }
+            return {
+              message: "Relay: Missing @required value at path '".concat(error.fieldPath, "' in '").concat(error.owner, "': ").concat(reason, ".")
+            };
+          }
         case 'missing_required_field.log':
           return null;
         default:

package/lib/util/handlePotentialSnapshotErrors.js

@@ -29,11 +29,19 @@ function handleFieldErrors(environment, fieldErrors, loggingContext) {
           case 'relay_resolver.error':
             throw new Error("Relay: Resolver error at path '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "'. Message: ").concat(_fieldError.error.message));
           case 'relay_field_payload.error':
-            throw new Error("Relay: Unexpected response payload - check server logs for details.");
+            throw new Error("Relay: Received a field error in the server response for field '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "'. Message: ").concat(_fieldError.error.message));
           case 'missing_expected_data.throw':
-            throw new Error("Relay: Missing expected data at path '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "'."));
+            throw new Error("Relay: Missing expected data at path '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "'. See https://relay.dev/docs/next/debugging/why-null/ for likely causes."));
           case 'missing_required_field.throw':
-            throw new Error("Relay: Missing @required value at path '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "'."));
+            {
+              var reason = void 0;
+              if (_fieldError.fieldValue === null) {
+                reason = _fieldError.fieldError != null ? "the server returned null with an error: ".concat(_fieldError.fieldError.message) : 'the server returned null';
+              } else {
+                reason = 'the field was missing in the store (data may not have been fetched, or was removed by a graph relationship change: https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change)';
+              }
+              throw new Error("Relay: Missing @required value at path '".concat(_fieldError.fieldPath, "' in '").concat(_fieldError.owner, "': ").concat(reason, "."));
+            }
           case 'missing_required_field.log':
           case 'missing_expected_data.log':
             break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relay-runtime",
   "description": "A core runtime for building GraphQL-driven applications.",
-  "version": "0.0.0-main-d112a76d",
+  "version": "0.0.0-main-e186ff01",
   "keywords": [
     "graphql",
     "relay"

package/store/RelayReader.js.flow

@@ -353,7 +353,10 @@ class RelayReader {
     return this._variables[name];
   }
 
-  _maybeReportUnexpectedNull(selection: ReaderRequiredField) {
+  _maybeReportUnexpectedNull(
+    selection: ReaderRequiredField,
+    fieldValue: null | void,
+  ) {
     if (selection.action === 'NONE') {
       return;
     }
@@ -371,10 +374,24 @@ class RelayReader {
       fieldName = selection.field.alias ?? selection.field.name;
     }
 
+    // When the field was null (not missing from the store), check whether the
+    // server also attached a field error to it. _maybeAddFieldErrors runs in
+    // the same call stack just before this method, so any companion error for
+    // this field is always the last entry pushed to this._fieldErrors.
+    let fieldError = null;
+    if (fieldValue === null && this._fieldErrors.length > 0) {
+      const lastError = this._fieldErrors[this._fieldErrors.length - 1];
+      if (lastError.kind === 'relay_field_payload.error') {
+        fieldError = lastError.error;
+      }
+    }
+
     switch (selection.action) {
       case 'THROW':
         this._fieldErrors.push({
+          fieldError,
           fieldPath: fieldName,
+          fieldValue,
           handled: false,
           kind: 'missing_required_field.throw',
           owner,
@@ -385,7 +402,9 @@ class RelayReader {
         return;
       case 'LOG':
         this._fieldErrors.push({
+          fieldError,
           fieldPath: fieldName,
+          fieldValue,
           kind: 'missing_required_field.log',
           owner,
           // the uiContext is always undefined here.
@@ -403,7 +422,7 @@ class RelayReader {
     value: unknown,
   ): boolean /*should continue to siblings*/ {
     if (value == null) {
-      this._maybeReportUnexpectedNull(selection);
+      this._maybeReportUnexpectedNull(selection, value);
       // We are going to throw, or our parent is going to get nulled out.
       // Either way, sibling values are going to be ignored, so we can
       // bail early here as an optimization.
@@ -499,12 +518,23 @@ class RelayReader {
             return {
               message: `Relay: Error in resolver for field at ${error.fieldPath} in ${error.owner}`,
             };
-          case 'missing_required_field.throw':
+          case 'missing_required_field.throw': {
             // If we have a nested @required(THROW) that will throw,
             // we want to catch that error and provide it
+            let reason: string;
+            if (error.fieldValue === null) {
+              reason =
+                error.fieldError != null
+                  ? `the server returned null with an error: ${error.fieldError.message}`
+                  : 'the server returned null';
+            } else {
+              reason =
+                'the field was missing in the store (data may not have been fetched, or was removed by a graph relationship change: https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change)';
+            }
             return {
-              message: `Relay: Missing @required value at path '${error.fieldPath}' in '${error.owner}'.`,
+              message: `Relay: Missing @required value at path '${error.fieldPath}' in '${error.owner}': ${reason}.`,
             };
+          }
           case 'missing_required_field.log':
             // For backwards compatibility, we don't surface log level missing required fields
             return null;

package/store/RelayStoreTypes.js.flow

@@ -1411,6 +1411,22 @@ export type MissingRequiredFieldLogEvent = {
   readonly kind: 'missing_required_field.log',
   readonly owner: string,
   fieldPath: string, // Purposefully mutable to allow lazy construction in RelayReader
+  /**
+   * The value that was read for the @required field:
+   * - `null`: the server returned null for this field. If `fieldError` is also
+   *   set, the server attached an error explaining why.
+   * - `undefined` (void): the field was absent from the Relay store entirely.
+   *   This is commonly caused by a graph relationship change observed by another
+   *   query/mutation, or by an imperative store update that omitted this field.
+   *   See https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change
+   */
+  readonly fieldValue: null | void,
+  /**
+   * When `fieldValue` is `null` and the server attached a field error to this
+   * field in the GraphQL response, this contains that error. This is the most
+   * likely explanation for why the field was null.
+   */
+  readonly fieldError: ?TRelayFieldError,
   // To populate this, you should pass the value to a ReactRelayLoggingContext
   readonly uiContext: unknown | void,
 };
@@ -1431,6 +1447,22 @@ export type MissingRequiredFieldThrowEvent = {
   readonly owner: string,
   fieldPath: string, // Purposefully mutable to allow lazy construction in RelayReader
   readonly handled: boolean,
+  /**
+   * The value that was read for the @required field:
+   * - `null`: the server returned null for this field. If `fieldError` is also
+   *   set, the server attached an error explaining why.
+   * - `undefined` (void): the field was absent from the Relay store entirely.
+   *   This is commonly caused by a graph relationship change observed by another
+   *   query/mutation, or by an imperative store update that omitted this field.
+   *   See https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change
+   */
+  readonly fieldValue: null | void,
+  /**
+   * When `fieldValue` is `null` and the server attached a field error to this
+   * field in the GraphQL response, this contains that error. This is the most
+   * likely explanation for why the field was null.
+   */
+  readonly fieldError: ?TRelayFieldError,
   // To populate this, you should pass the value to a ReactRelayLoggingContext
   readonly uiContext: unknown | void,
 };

package/util/handlePotentialSnapshotErrors.js.flow

@@ -50,16 +50,27 @@ function handleFieldErrors(
           );
         case 'relay_field_payload.error':
           throw new Error(
-            `Relay: Unexpected response payload - check server logs for details.`,
+            `Relay: Received a field error in the server response for field '${fieldError.fieldPath}' in '${fieldError.owner}'. Message: ${fieldError.error.message}`,
           );
         case 'missing_expected_data.throw':
           throw new Error(
-            `Relay: Missing expected data at path '${fieldError.fieldPath}' in '${fieldError.owner}'.`,
+            `Relay: Missing expected data at path '${fieldError.fieldPath}' in '${fieldError.owner}'. See https://relay.dev/docs/next/debugging/why-null/ for likely causes.`,
           );
-        case 'missing_required_field.throw':
+        case 'missing_required_field.throw': {
+          let reason: string;
+          if (fieldError.fieldValue === null) {
+            reason =
+              fieldError.fieldError != null
+                ? `the server returned null with an error: ${fieldError.fieldError.message}`
+                : 'the server returned null';
+          } else {
+            reason =
+              'the field was missing in the store (data may not have been fetched, or was removed by a graph relationship change: https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change)';
+          }
           throw new Error(
-            `Relay: Missing @required value at path '${fieldError.fieldPath}' in '${fieldError.owner}'.`,
+            `Relay: Missing @required value at path '${fieldError.fieldPath}' in '${fieldError.owner}': ${reason}.`,
           );
+        }
         case 'missing_required_field.log':
         case 'missing_expected_data.log':
           // These should have already been filtered out. Sadly, Flow Type