relay-compiler 19.0.0 → 20.0.0

package/README.md

@@ -1,127 +1,3 @@
 # Relay Compiler
 
-Relay-Compiler is a code-generation toolkit for GraphQL. It contains the core
-functionalities of GraphQL code-gen, including file parsing, validation, syntax
-tree parsing and transformation.
-
-## Configuration in package.json
-
-The simplest way to configure relay is to add a new `relay` section to your
-`package.json` that contains the relay config.
-
-At minimum, the relay config must specify where to find source files (i.e. files
-containing `graphql` literals) and the GraphQL schema for the project.
-
-```
-// adding new section to package json
-{
-  ...
- "scripts": {
-    "relay": "relay-compiler"
- },
- ...
- // relay configuration
- "relay": {
-    "src": "./src",
-    "schema": "./src/schema/app_schema.graphql"
-  }
-}
-```
-
-Relay Compiler will automatically discover the config if:
-
-- There is a `relay.config.json`, `relay.config.js` file at the root of the
-  project (i.e. in the same folder as the `package.json` file).
-- The `package.json` file contains a `"relay"` key.
-
-Alternatively, the path to a configuration file can be specified as an argument:
-
-```shell
-npm run relay ./relay.json
-```
-
-or with yarn
-
-```shell
-yarn relay ./relay.json
-```
-
-Please note, in this case you'll need to provide a separate configuration for
-the [babel plugin](https://www.npmjs.com/package/babel-plugin-relay).
-
-## File Finder
-
-Relay compiler uses [`watchman`](https://facebook.github.io/watchman/) to find
-file sources, and "listen" to the file changes in the "watch" mode. If
-`watchman` is not available, the compiler will use
-[glob](https://docs.rs/glob/latest/glob/) to query the filesystem for files.
-
-## Configuration
-
-### Supported compiler configuration options
-
-- `src` Root directory of application code. [string] [required]
-- `schema` Relative path to the file with GraphQL SDL file. [string] [required]
-- `language` The name of the language used for input files and generated
-  artifacts. ["javascript" | "typescript" | "flow"] [required].
-- `artifactDirectory` A specific directory to output all artifacts to. When
-  enabling this the babel plugin needs `artifactDirectory` to be set as well.
-  [string]
-- `excludes` Directories to ignore under `src`. [array] [default:
-  ["\*\*/node_modules/\*\*", "\*\*/__mocks__/\*\*", "\*\*/__generated__/\*\*"]]
-- `schemaExtensions` List of files or directories with schema extensions. [array]
-- `schemaConfig`
-  - `nodeInterfaceIdField` Configure the name of the globally unique ID field on
-    the Node interface. Useful if you can't use the default `id` field name.
-  - `nodeInterfaceIdVariableName` Specifies the name of the variable expected by the `node` query to pass the Node id.
-    [string][default: "id"]
-  - `nonNodeIdFields` Restricts the type of all fields named `id` to `ID`.
-    - `allowedIdTypes` Mappings from types in your schema to allowed types
-      for their fields named `id` (e.g. "ObjectType": "CustomIdType"). [object]
-- `noFutureProofEnums` This option controls whether or not a
-  catch-all entry is added to enum type definitions values that may be added in
-  the future. Enabling this means you will have to update your application
-  whenever the GraphQL server schema adds new enum values to prevent it from
-  breaking. [boolean][default: false]
-- `customScalarTypes` Mappings from custom scalars in your schema to built-in
-  GraphQL types, for type emission purposes (eg. {"GqlScalar": "TStype"}). [object]
-- `eagerEsModules` This option enables emitting ES modules artifacts.
-  [boolean][default: false]
-- `persistConfig` Relay supports two versions of the config:
-- - **Remote Persisting:**
-
-  - `url` String, URL to send a POST request to to persist. This field is
-    required in `persistConfig` [string]
-  - `params` The document will be in a `POST` parameter `text`. This map can
-    contain additional parameters to send. [object]
-  - `concurrency` The maximum number concurrent requests that will be made to
-    `url`. Use a value greater than 0. [number]
-  - `include_query_text` Boolean, whether to include the query text in the
-    generated files. [boolean] [default: false]
-- - **Local Persisting:**
-  - `file` Path for the JSON file that will contain operations map. Compiler
-    will write queries in the format: { "md5(queryText) => "queryText", ...}.
-    [string]
-  - `include_query_text` Boolean, whether to include the query text in the
-    generated files. [boolean] [default: false]
-
-- `codegenCommand` Command name that for relay compiler. [string]
-
-- `isDevVariableName` Name of the global variable for dev mode (`__DEV__`).
-  [string]
-- `jsModuleFormat` Formatting style for generated files. `commonjs` or `haste`.
-  Default is `commonjs`. [string]
-- `diagnosticReportConfig` Options for configuring the output of compiler
-  diagnostics. [object]
-  - `criticalLevel` The severity level of diagnostics that will cause the
-    compiler to error out on. ["error" | "warning" | "info"]
-
-### CLI Arguments
-
-- `--repersist` Run the persister even if the query has not changed.
-- `--watch` Run compiler in `watch` mode. Requires
-  [`watchman`](https://facebook.github.io/watchman/) to be installed.
-- `--output` Output format of the compiler. Supported options: `debug` |
-  `verbose` | `quiet` | `quietWithErrors`. The default value is `verbose`.
-- `--validate` Looks for pending changes and exits with non-zero code instead of
-  writing to disk.
+See https://relay.dev/docs/next/guides/compiler/

package/package.json

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

package/relay-compiler-config-schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "ConfigFile",
+  "description": "Relay's configuration file. Supports a single project config for simple use cases and a multi-project config for cases where multiple projects live in the same repository.\n\nIn general, start with the SingleProjectConfigFile.",
   "anyOf": [
     {
       "description": "Base case configuration (mostly of OSS) where the project have single schema, and single source directory",
@@ -42,6 +43,7 @@
           ]
         },
         "codegenCommand": {
+          "description": "Name of the command that runs the relay compiler. This will be added at the top of generated code to let readers know how to regenerate the file.",
           "default": null,
           "type": [
             "string",
@@ -68,6 +70,7 @@
           }
         },
         "diagnosticReportConfig": {
+          "description": "Threshold for diagnostics to be critical to the compiler's execution. All diagnostic with severities at and below this level will cause the compiler to fatally exit.",
           "default": {
             "criticalLevel": "error"
           },
@@ -112,6 +115,7 @@
           ]
         },
         "featureFlags": {
+          "description": "Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.",
           "default": null,
           "anyOf": [
             {
@@ -123,6 +127,7 @@
           ]
         },
         "jsModuleFormat": {
+          "description": "Import/export style to use in generated JavaScript modules.",
           "default": "commonjs",
           "allOf": [
             {
@@ -139,6 +144,7 @@
           ]
         },
         "moduleImportConfig": {
+          "description": "Configuration for the @module GraphQL directive.",
           "default": {
             "dynamicModuleProvider": null,
             "operationModuleProvider": null,
@@ -184,6 +190,7 @@
           ]
         },
         "relativizeJsModulePaths": {
+          "description": "Whether to treat all JS module names as relative to './' (true) or not. default: true",
           "default": true,
           "type": "boolean"
         },
@@ -193,7 +200,7 @@
           "type": "boolean"
         },
         "resolverContextType": {
-          "description": "Indicates the type to import and use as the context for live resolvers.",
+          "description": "Indicates the type to import and use as the context for Relay Resolvers.",
           "default": null,
           "anyOf": [
             {
@@ -232,6 +239,7 @@
           ]
         },
         "schemaConfig": {
+          "description": "Extra configuration for the GraphQL schema itself.",
           "default": {
             "connectionInterface": {
               "cursor": "cursor",
@@ -371,16 +379,28 @@
       "additionalProperties": false
     },
     "CustomType": {
+      "description": "Defines a custom GraphQL descrbing a custom scalar.",
       "anyOf": [
         {
-          "$ref": "#/definitions/StringKey"
+          "description": "A string representing the name of a custom type. e.g. \"string\" or \"number\"",
+          "allOf": [
+            {
+              "$ref": "#/definitions/StringKey"
+            }
+          ]
         },
         {
-          "$ref": "#/definitions/CustomTypeImport"
+          "description": "A module which defines the custom type. e.g. { \"name\": \"MyCustomType\", \"path\": \"./Types.ts\" }",
+          "allOf": [
+            {
+              "$ref": "#/definitions/CustomTypeImport"
+            }
+          ]
         }
       ]
     },
     "CustomTypeImport": {
+      "description": "Defines a module path and export name of the Flow or TypeScript type descrbing a GraphQL custom scalar.",
       "type": "object",
       "required": [
         "name",
@@ -388,9 +408,15 @@
       ],
       "properties": {
         "name": {
-          "$ref": "#/definitions/StringKey"
+          "description": "The name under which the type is exported from the module",
+          "allOf": [
+            {
+              "$ref": "#/definitions/StringKey"
+            }
+          ]
         },
         "path": {
+          "description": "The path to the module relative to the project root",
           "type": "string"
         }
       }
@@ -607,6 +633,17 @@
             }
           ]
         },
+        "allow_output_type_resolvers": {
+          "description": "@outputType resolvers are a discontinued experimental feature. This flag allows users to allowlist old uses of this feature while they work to remove them. Weak types (types without an `id` field) returned by a Relay Resolver should be limited to types defined using `@RelayResolver` with `@weak`.\n\nIf using the \"limited\" feature flag variant, users can allowlist a specific list of field names.\n\nhttps://relay.dev/docs/next/guides/relay-resolvers/defining-types/#defining-a-weak-type",
+          "default": {
+            "kind": "disabled"
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/FeatureFlag"
+            }
+          ]
+        },
         "allow_required_in_mutation_response": {
           "description": "@required with an action of THROW is read-time feature that is not compatible with our mutation APIs. We are in the process of removing any existing examples, but this flag is part of a process of removing any existing examples.",
           "default": {
@@ -773,6 +810,7 @@
           "type": "boolean"
         },
         "relay_resolver_enable_interface_output_type": {
+          "description": "Enable returning interfaces from Relay Resolvers without @outputType",
           "default": {
             "kind": "disabled"
           },
@@ -985,10 +1023,14 @@
           }
         },
         "featureFlags": {
+          "description": "Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.",
           "default": {
             "actor_change_support": {
               "kind": "disabled"
             },
+            "allow_output_type_resolvers": {
+              "kind": "disabled"
+            },
             "allow_required_in_mutation_response": {
               "kind": "disabled"
             },
@@ -1229,12 +1271,23 @@
       "additionalProperties": false
     },
     "ResolverContextTypeInput": {
+      "description": "Describes the type to import and use as the context for Relay Resolvers.",
       "anyOf": [
         {
-          "$ref": "#/definitions/ResolverContextTypeInputPath"
+          "description": "The type imported using a relative path",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ResolverContextTypeInputPath"
+            }
+          ]
         },
         {
-          "$ref": "#/definitions/ResolverContextTypeInputPackage"
+          "description": "The type imported using a named package",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ResolverContextTypeInputPackage"
+            }
+          ]
         }
       ]
     },
@@ -1480,7 +1533,7 @@
           ]
         },
         "codegenCommand": {
-          "description": "Name of the command that runs the relay compiler",
+          "description": "Name of the command that runs the relay compiler. This will be added at the top of generated code to let readers know how to regenerate the file.",
           "default": null,
           "type": [
             "string",
@@ -1532,6 +1585,7 @@
           }
         },
         "featureFlags": {
+          "description": "Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.",
           "default": null,
           "anyOf": [
             {
@@ -1551,7 +1605,7 @@
           ]
         },
         "jsModuleFormat": {
-          "description": "Formatting style for generated files.",
+          "description": "Import/export style to use in generated JavaScript modules.",
           "default": "commonjs",
           "allOf": [
             {
@@ -1625,7 +1679,7 @@
           "type": "boolean"
         },
         "resolverContextType": {
-          "description": "Indicates the type to import and use as the context for live resolvers.",
+          "description": "Indicates the type to import and use as the context for Relay Resolvers.",
           "default": null,
           "anyOf": [
             {
@@ -1653,7 +1707,7 @@
           "type": "string"
         },
         "schemaConfig": {
-          "description": "Extra configuration for the schema itself.",
+          "description": "Extra configuration for the GraphQL schema itself.",
           "default": {
             "connectionInterface": {
               "cursor": "cursor",
@@ -1698,10 +1752,6 @@
           "default": "",
           "type": "string"
         },
-        "typegenPhase": {
-          "description": "Added in 13.1.1 to customize Final/Compat mode in the single project config file Removed in 14.0.0",
-          "default": null
-        },
         "typescriptExcludeUndefinedFromNullableUnion": {
           "description": "Keep the previous compiler behavior by outputting an union of the raw type and null, and not the **correct** behavior of an union with the raw type, null and undefined.",
           "default": false,

package/relay-extensions.graphql

@@ -26,7 +26,7 @@ directive @no_inline(raw_response_type: Boolean) on FRAGMENT_DEFINITION
 
 A directive added to queries and fragments which causes the Relay client to throw
 if reading a field that has an error. Relay will also honor the @semanticNonNull
-direcitve on fields read from that query or fragment. Emitted types for such
+directive on fields read from that query or fragment. Emitted types for such
 fields will be non-null. Requires the `experimental_emit_semantic_nullability_types`
 typegen configuration to be enabled.