Skip to content

Commit

Permalink
Write about @oneOf in the graphql-js documentation (graphql#4290)
Browse files Browse the repository at this point in the history
Currently input-unions and by extension the `@oneOf` directive aren't
present in the documentation. I have opted to put this into the advanced
section. The copy might be up for improvement, honestly fire away if
there's more cases to cover, just wanted to get the ball rolling here.

CC @benjie

---------

Co-authored-by: Benjie <benjie@jemjie.com>
  • Loading branch information
2 people authored and yaacovCR committed Dec 3, 2024
1 parent 0a88274 commit c3ccd53
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 0 deletions.
1 change: 1 addition & 0 deletions cspell.yml
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ words:
- tailwindcss
- svgr
- ruru
- oneof

# used as href anchors
- graphqlerror
Expand Down
1 change: 1 addition & 0 deletions website/pages/_meta.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ const meta = {
title: 'Advanced Guides',
},
'constructing-types': '',
'oneof-input-objects': 'OneOf input objects',
'defer-stream': '',
'-- 3': {
type: 'separator',
Expand Down
91 changes: 91 additions & 0 deletions website/pages/oneof-input-objects.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
title: OneOf input objects
---

import { Tabs } from 'nextra/components';

Some inputs will behave differently depending on what input we choose. Let's look at the case for
a field named `product`, we can fetch a `Product` by either its `id` or its `name`. Currently we'd
make a tradeoff for this by introducing two arguments that are both nullable, now if both are passed
as null (or both non-null) we'd have to handle that in code - the type system wouldn't indicate that exactly one was required. To fix this, the `@oneOf` directive was introduced so we
can create this "exactly one option" constraint without sacrificing the strictly typed nature of our GraphQL Schema.

<Tabs items={['SDL', 'Code']}>
<Tabs.Tab>
```js
const schema = buildSchema(`
type Product {
id: ID!
name: String!
}
input ProductLocation {
aisleNumber: Int!
shelfNumber: Int!
positionOnShelf: Int!
}
input ProductSpecifier @oneOf {
id: ID
name: String
location: ProductLocation
}
type Query {
product(by: ProductSpecifier!): Product
}
`);
```
</Tabs.Tab>
<Tabs.Tab>
```js
const Product = new GraphQLObjectType({
name: 'Product',
fields: {
id: {
type: new GraphQLNonNull(GraphQLID),
},
name: {
type: new GraphQLNonNull(GraphQLString),
},
},
});

const ProductLocation = new GraphQLInputObjectType({
name: 'ProductLocation',
isOneOf: true,
fields: {
aisleNumber: { type: GraphQLInt },
shelfNumber: { type: GraphQLInt },
positionOnShelf: { type: GraphQLInt },
},
});

const ProductSpecifier = new GraphQLInputObjectType({
name: 'ProductSpecifier',
isOneOf: true,
fields: {
id: { type: GraphQLID },
name: { type: GraphQLString },
location: { type: ProductLocation },
},
});

const schema = new GraphQLSchema({
query: new GraphQLObjectType({
name: 'Query',
fields: {
product: {
type: Product,
args: { by: { type: ProductSpecifier } },
},
},
}),
});
```
</Tabs.Tab>
</Tabs>

It doesn't matter whether you have 2 or more inputs here, all that matters is
that your user will have to specify one, and only one, for this input to be valid.
The values are not limited to scalars, lists and other input object types are also allowed.

0 comments on commit c3ccd53

Please sign in to comment.