relay-compiler 20.1.1 → 21.0.1

package/index.js

@@ -9,6 +9,10 @@
  * @oncall relay
  */
 
+/**
+ * LLM/AI Agent: Relay documentation is available in node_modules/relay-runtime/llm-docs/
+ */
+
 'use strict';
 
 const path = require('path');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relay-compiler",
   "description": "A compiler tool for building GraphQL-driven applications.",
-  "version": "20.1.1",
+  "version": "21.0.1",
   "keywords": [
     "graphql",
     "relay"

package/relay-compiler-config-schema.json

@@ -134,6 +134,11 @@
           "type": "boolean",
           "default": false
         },
+        "oneOfType": {
+          "description": "How to generate a type for an input object marked as @oneOf.\nDefaults to \"strict\", which is to generate a union type which\npermits only a single property being set at a time. \"ignore\"\ngenerates the type as if the @oneOf annotation does not exist.",
+          "$ref": "#/$defs/OneOfGeneration",
+          "default": "strict"
+        },
         "optionalInputFields": {
           "title": "For Flow type generation",
           "description": "When set, generated input types will have the listed fields optional\neven if the schema defines them as required.",
@@ -207,6 +212,12 @@
             "null"
           ]
         },
+        "schemaCompact": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "schemaConfig": {
           "description": "Extra configuration for the GraphQL schema itself.",
           "$ref": "#/$defs/SchemaConfig",
@@ -243,7 +254,7 @@
           ]
         },
         "schemaExtensions": {
-          "description": "Directory containing *.graphql files with schema extensions.",
+          "description": "File or directory containing *.graphql files with schema extensions.",
           "type": "array",
           "default": [],
           "items": {
@@ -306,7 +317,7 @@
       ]
     },
     "ConnectionInterface": {
-      "description": "Configuration where Relay should expect some fields in the schema.",
+      "description": "Configuration where Relay should expect some fields in the schema.\n\n**Important**: When you configure this option in the compiler, you must also configure\nthe Relay runtime to match by calling `ConnectionInterface.inject()` with the same values.\nSee: <https://relay.dev/docs/api-reference/runtime-config/#connectioninterface>",
       "type": "object",
       "properties": {
         "cursor": {
@@ -553,7 +564,8 @@
     "FeatureFlags": {
       "type": "object",
       "properties": {
-        "actor_change_support": {
+        "allow_legacy_relay_resolver_tag": {
+          "description": "When enabled for a given name, allows `@RelayResolver` as a legacy\nalias for `@relayType` / `@relayField`.",
           "$ref": "#/$defs/FeatureFlag",
           "default": {
             "kind": "disabled"
@@ -615,6 +627,13 @@
             "kind": "disabled"
           }
         },
+        "disable_more_precise_abstract_selection_raw_response_type": {
+          "description": "Disable the generation of a more precise raw response type\nfor selections on abstract types.",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
         "disable_resolver_reader_ast": {
           "description": "Mirror of `enable_resolver_normalization_ast`\nexcludes resolver metadata from reader ast",
           "type": "boolean",
@@ -625,6 +644,20 @@
           "type": "boolean",
           "default": false
         },
+        "disallow_required_action_throw_on_semantically_nullable_fields": {
+          "description": "Disallow @required action THROW on semantically nullable fields.\nWhen enabled, this will prevent the use of THROW action on fields\nthat are semantically nullable (e.g., fields that can legitimately\nbe null in normal operation).",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
+        "emit_nogrep_annotation": {
+          "description": "When enabled, the `@nogrep` annotation is included in the docblock\nheader of generated artifacts. This annotation was historically always\nemitted but is no longer needed. This flag allows incremental removal\nacross projects using the rollout variant keyed on the artifact name.",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
         "enable_3d_branch_arg_generation": {
           "type": "boolean",
           "default": false
@@ -649,6 +682,13 @@
           "type": "boolean",
           "default": false
         },
+        "enable_shadow_resolvers": {
+          "description": "Enable experimental support for shadow resolvers. Shadow resolvers allow\ndefining a Relay Resolver that \"shadows\" an existing server field,\nproviding an alternative implementation that can be used during\nmigration or for client-side overrides.",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
         "enable_strict_custom_scalars": {
           "description": "Perform strict validations when custom scalar types are used",
           "type": "boolean",
@@ -661,6 +701,18 @@
             "kind": "enabled"
           }
         },
+        "enforce_module_name_prefix_for_non_haste": {
+          "description": "Enforce that GraphQL operation and fragment names start with the file\nname. Haste projects have this enforcement automatically; this flag\nis only needed for non-Haste projects that want the same validation.",
+          "type": "boolean",
+          "default": false
+        },
+        "flow_modern_syntax": {
+          "description": "Use modern Flow syntax for generated object types.\nThis enables gradual rollout of exact object type syntax and readonly\nproperties across files.",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
         "legacy_include_path_in_required_reader_nodes": {
           "description": "The `path` field in `@required` Reader AST nodes is no longer used. But\nremoving them in one diff is too large of a change to ship at once.\n\nThis flag will allow us to use the rollout FeatureFlag to remove them\nacross a number of diffs.",
           "$ref": "#/$defs/FeatureFlag",
@@ -694,6 +746,13 @@
             "kind": "disabled"
           }
         },
+        "shard_extra_artifacts": {
+          "description": "Shard generated extra artifacts into subdirectories under\n`extraArtifactsOutput` that mirror the source file's relative path,\nhonoring `shardOutput` / `shardStripRegex`.",
+          "$ref": "#/$defs/FeatureFlag",
+          "default": {
+            "kind": "disabled"
+          }
+        },
         "skip_printing_nulls": {
           "$ref": "#/$defs/FeatureFlag",
           "default": {
@@ -872,7 +931,7 @@
           "description": "Enable and disable experimental or legacy behaviors.\nWARNING! These are not stable and may change at any time.",
           "$ref": "#/$defs/FeatureFlags",
           "default": {
-            "actor_change_support": {
+            "allow_legacy_relay_resolver_tag": {
               "kind": "disabled"
             },
             "allow_output_type_resolvers": {
@@ -899,15 +958,31 @@
             "disable_full_argument_type_validation": {
               "kind": "disabled"
             },
+            "disable_more_precise_abstract_selection_raw_response_type": {
+              "kind": "disabled"
+            },
             "disable_resolver_reader_ast": false,
             "disable_schema_validation": false,
+            "disallow_required_action_throw_on_semantically_nullable_fields": {
+              "kind": "disabled"
+            },
+            "emit_nogrep_annotation": {
+              "kind": "disabled"
+            },
             "enable_3d_branch_arg_generation": false,
             "enable_exec_time_resolvers_directive": false,
             "enable_fragment_argument_transform": false,
             "enable_relay_resolver_mutations": false,
             "enable_resolver_normalization_ast": false,
+            "enable_shadow_resolvers": {
+              "kind": "disabled"
+            },
             "enable_strict_custom_scalars": false,
             "enforce_fragment_alias_where_ambiguous": {
+              "kind": "enabled"
+            },
+            "enforce_module_name_prefix_for_non_haste": false,
+            "flow_modern_syntax": {
               "kind": "disabled"
             },
             "legacy_include_path_in_required_reader_nodes": {
@@ -923,6 +998,9 @@
             "relay_resolver_enable_interface_output_type": {
               "kind": "disabled"
             },
+            "shard_extra_artifacts": {
+              "kind": "disabled"
+            },
             "skip_printing_nulls": {
               "kind": "disabled"
             },
@@ -1026,6 +1104,20 @@
       },
       "additionalProperties": false
     },
+    "OneOfGeneration": {
+      "oneOf": [
+        {
+          "description": "Will generate a union type, which can have only a single property set",
+          "type": "string",
+          "const": "strict"
+        },
+        {
+          "description": "Will exhibit previous behaviour, where @oneOf types would generate a\npermissive object type that may include all, none, or some of the\nproperties set",
+          "type": "string",
+          "const": "ignore"
+        }
+      ]
+    },
     "PersistConfig": {
       "description": "Configuration for how the Relay Compiler should persist GraphQL queries.",
       "anyOf": [
@@ -1161,7 +1253,7 @@
       ]
     },
     "ResolversSchemaModuleConfig": {
-      "description": "Configuration for resolvers_schema_module generation",
+      "description": "Configuration for resolvers_schema_module generation.\n\nWhen `path` is provided, a monolithic resolver map file is generated at that\npath. When `path` is omitted, the map file is not generated but root\nfragment normalization split operations are still produced.",
       "type": "object",
       "properties": {
         "applyToNormalizationAst": {
@@ -1169,8 +1261,11 @@
           "default": false
         },
         "path": {
-          "type": "string",
-          "default": ""
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null
         }
       },
       "additionalProperties": false
@@ -1230,6 +1325,7 @@
       "type": "object",
       "properties": {
         "connectionInterface": {
+          "description": "Configuration for connection field names in the schema.\n\n**Important**: When you configure this option in the compiler, you must also configure\nthe Relay runtime to match by calling `ConnectionInterface.inject()` with the same values.\nSee: <https://relay.dev/docs/api-reference/runtime-config/#connectioninterface>",
           "$ref": "#/$defs/ConnectionInterface",
           "default": {
             "cursor": "cursor",
@@ -1440,6 +1536,11 @@
           ],
           "default": null
         },
+        "oneOfType": {
+          "description": "How to generate a type for an input object marked as @oneOf.\nDefaults to \"strict\", which is to generate a union type which\npermits only a single property being set at a time. \"ignore\"\ngenerates the type as if the @oneOf annotation does not exist.",
+          "$ref": "#/$defs/OneOfGeneration",
+          "default": "strict"
+        },
         "optionalInputFields": {
           "title": "For Flow type generation",
           "description": "When set, generated input types will have the listed fields optional\neven if the schema defines them as required.",
@@ -1529,7 +1630,7 @@
           }
         },
         "schemaExtensions": {
-          "description": "List of directories with schema extensions.",
+          "description": "List of files or directories with schema extensions.",
           "type": "array",
           "default": [],
           "items": {

package/relay-extensions.graphql

@@ -154,10 +154,59 @@ directive @stream_connection(
 ) on FIELD
 
 # RequiredTransform
+"""
+(Relay Only)
+
+Actions that can be taken when a @required field is null at runtime.
+These actions correspond to your expectations about the data and how
+your application should handle missing values.
+
+[Read More](https://relay.dev/docs/guides/required-directive/)
+"""
 enum RequiredFieldAction {
+  """
+  This data is expected to be null sometimes.
+
+  The field's nullability will "bubble up" to make the parent field null if this
+  field is missing, allowing the component to check the parent field instead of
+  this specific field.
+  """
   NONE
+
+  """
+  This data should always be present. We can recover if it is null but want to
+  report that something unexpected happened.
+
+  A event will be logged to the `relayFieldLogger` and the field's nullability
+  will "bubble up" to make the parent field null if this field is missing,
+  allowing the component to check the parent field instead of this specific
+  field.
+  """
   LOG
+
+  """
+  This data should always be present. We cannot recover if it is null.
+
+  Use THROW when the data is absolutely critical and your application cannot
+  function without it. This will throw an error at runtime if the field is null.
+
+  Note: If you have opted into the optional 'disallow_required_action_throw_on_semantically_nullable_fields'
+  feature flag, this can only be used on fields that are non-nullable or marked
+  with @semanticNonNull (an optional semantic nullability feature that indicates
+  fields should never be null in normal operation).
+  """
   THROW
+
+  """
+  This data should always be present. We cannot recover if it is null.
+  This action bypasses semantic nullability validation.
+
+  This action behaves identically to THROW but can be used on fields that are
+  nullable. This is only needed when the optional compiler feature flag
+  'disallow_required_action_throw_on_semantically_nullable_fields' is enabled,
+  which prevents using THROW on (semantically) nullable fields.
+  """
+  DANGEROUSLY_THROW_ON_SEMANTICALLY_NULLABLE_FIELD
 }
 
 # CatchTransform
@@ -368,4 +417,7 @@ If added to a query, resolvers in that query to run at exec-time, rather than re
 This means the resolvers are run when the query data is requested rather than when the
 query is used (i.e. when the network request is made instead of at render time).
 """
-directive @exec_time_resolvers(enabledProvider: String) on QUERY
+directive @exec_time_resolvers(
+  enabledProvider: String
+  useExperimentalProvider: String
+) on QUERY