diff --git a/CHANGELOG.md b/CHANGELOG.md index 3420f40d..6e0289a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # master +- Add support for `@exhaustive` - a directive to trigger exhaustiveness checks for unions at the GraphQL operation level. + # 3.3.0 - Add support for top level `@catch` on fragments on unions. diff --git a/packages/relay b/packages/relay index 2e50d955..7b4b18a3 160000 --- a/packages/relay +++ b/packages/relay @@ -1 +1 @@ -Subproject commit 2e50d955f631a8b70a668ecda8545798f9dd020f +Subproject commit 7b4b18a331cba0673e9dd22fd6735353fcd75ac4 diff --git a/rescript-relay-documentation/docs/getting-started.md b/rescript-relay-documentation/docs/getting-started.md index 660f3cbc..d981dae1 100644 --- a/rescript-relay-documentation/docs/getting-started.md +++ b/rescript-relay-documentation/docs/getting-started.md @@ -82,6 +82,9 @@ module.exports = { schema: "./schema.graphql", // Path to the schema.graphql you've exported from your API. Don't know what this is? It's a saved introspection of what your schema looks like. You can run `npx get-graphql-schema http://path/to/my/graphql/server > schema.graphql` in your root to generate it artifactDirectory: "./src/__generated__", // The directory where all generated files will be emitted + // Enable this if you want mutations that return unions to always force selecting all union members. Read more in the docs on unions. + autoExhaustiveMutations: true, + // You can add type definitions for custom scalars here. // Whenever a custom scalar is encountered, the type emitted will correspond to the definition defined here. You can then deal with the type as needed when accessing the data. customScalarTypes: { diff --git a/rescript-relay-documentation/docs/unions.md b/rescript-relay-documentation/docs/unions.md index 50970b42..e9886124 100644 --- a/rescript-relay-documentation/docs/unions.md +++ b/rescript-relay-documentation/docs/unions.md @@ -83,9 +83,83 @@ Let's break down what's going on here: 2. We fetch our query data, and we switch on `roomOwner` to make sure it's actually there in the data. 3. We then switch again, but this time on the variant representing the union. This polymorphic variant will have each possible type of the union, and the fields selected on that type. It also adds `UnselectedUnionMember(string)` to every union, which will force you to handle _what happens if there's another member added to the union before you have time to update your app_. The `string` payload is the `__typename` of the retrieved member that wasn't selected. This is pretty neat way to ensure you gracefully handle your schema evolving. +## Exhaustiveness Checking with `@exhaustive` + +RescriptRelay provides an `@exhaustive` directive that helps ensure you've selected all available union members in your GraphQL queries. This directive can be applied to fields or fragment definitions and will trigger exhaustiveness checks at compile time. +This is useful when you there are unions in your schema where you'll want to be alerted at compile time that the server added new possible return values. This makes unions work just like enums in this regard. + +### Usage + +The `@exhaustive` directive is defined as: + +```graphql +@exhaustive(ignore: [String!], disabled: Boolean) on FIELD | FRAGMENT_DEFINITION +``` + +Here's how to use it with our previous example: + +```rescript +/* RoomOwner.res */ +module Query = %relay( + ` + query RoomOwnerQuery($roomId: ID!) { + roomOwner(roomId: $roomId) @exhaustive { + __typename + + ... on User { + firstName + lastName + } + + ... on Group { + name + } + } + } +` +) +``` + +When you use `@exhaustive`, RescriptRelay will check that you've included fragments for all possible union members. If you're missing any, you'll get a compile-time error telling you which union members you haven't selected. + +### Parameters + +- **`ignore: [String!]`** - An array of union member type names to ignore during exhaustiveness checking. Use this when you intentionally don't want to handle certain union members. + +```rescript +/* Ignore the Group type in exhaustiveness checking */ +roomOwner(roomId: $roomId) @exhaustive(ignore: ["Group"]) { + __typename + + ... on User { + firstName + lastName + } +} +``` + +- **`disabled: Boolean`** - Set to `true` to completely disable exhaustiveness checking for this field while keeping the directive for documentation purposes. + +```rescript +/* Temporarily disable exhaustiveness checking */ +roomOwner(roomId: $roomId) @exhaustive(disabled: true) { + __typename + + ... on User { + firstName + lastName + } +} +``` + +### Auto-enabling for Mutations + +You can also configure RescriptRelay to automatically apply exhaustiveness checking to mutation fields that return unions. Add `autoExhaustiveMutations: true` to your Relay configuration to enable this behavior for any top-level mutation field that returns a union type. + ## Wrapping up And that's that! Keep the following in mind about unions and everything will be fine: - Remember to select `__typename` - Remember to handle `UnselectedUnionMember` +- Consider using `@exhaustive` to ensure you handle all union members