graphql-binding
Overview
The idea of GraphQL bindings is introduced in detail in this blog post: Reusing & Composing GraphQL APIs with GraphQL Bindings
Install
yarn add graphql-binding
API
Binding
constructor(options: BindingOptions): Binding
BindingOptions
has the following properties:
Key | Required | Type | Default | Note |
---|---|---|---|---|
schema |
Yes | GraphQLSchema |
- | The executable GraphQL schema for binding |
fragmentReplacements |
No | FragmentReplacements |
{} |
A list of GraphQL fragment definitions, specifying fields that are required for the resolver to function correctly |
before |
No | () => void |
(() => undefined) |
A function that will be executed before a query/mutation is sent to the GraphQL API |
handler |
No | any |
null |
The handler object from JS Proxy |
subscriptionHandler |
No | any |
null |
... |
binding.query.<rootField>(): Promise<any>
& binding.mutation.<rootField>(): Promise<any>
A binding object exposes two properties which can be used to send queries and mutations to the API: binding.query
and binding.mutation
.
Both are of type QueryMap
and will expose methods that are named after the schema's root fields on the Query
and Mutation
types.
These methods take three arguments:
Name | Required | Type | Note |
---|---|---|---|
args |
No | [key: string]: any |
An object that contains the arguments of the root field |
context |
No | [key: string]: any |
The context object that's passed down the GraphQL resolver chain; every resolver can read from and write to that object |
info |
No | GraphQLResolveInfo |
string |
Example
Assume the following schema:
type Query {
user(id: ID!): User
}
type Mutation {
createUser(): User!
}
If there is a binding
for a GraphQL API that implements this schema, you can invoke the following methods on it:
binding.query.user({ id: 'abc' })
binding.mutation.createUser()
When using the binding in a resolver implementation, it can be used as follows:
findUser(parent, args, context, info) {
return binding.user({ id: args.id }, context, info)
}
newUser(parent, args, context, info) {
return binding.createUser({}, context, info)
}
binding.subscription.<rootField>(...): AsyncIterator<any> | Promise<AsyncIterator<any>>
The binding.subscription
property follows the same idea as query
and mutation
, but rather than returning a single value using a Promise
, it returns a stream of values using AsyncIterator
.
It is of type SubscriptionMap
and will expose methods that are named after the schema's root fields on the Subscription
type.
These methods take same three arguments as the generated methods on query
and mutation
, see above for the details.
Example
Minimal example
const { makeExecutableSchema } = require('graphql-tools')
const { Binding } = require('graphql-binding')
const users = [
{
name: 'Alice',
},
{
name: 'Bob',
},
]
const typeDefs = `
type Query {
findUser(name: String!): User
}
type User {
name: String!
}
`
const resolvers = {
Query: {
findUser: (parent, { name }) => users.find(u => u.name === name),
},
}
const schema = makeExecutableSchema({ typeDefs, resolvers })
const findUserBinding = new Binding({
schema,
})
findUserBinding.findUser({ name: 'Bob' })
.then(result => console.log(result))
Public GraphQL bindings
You can find practical, production-ready examples here:
Note: If you've created your own GraphQL binding based on this package, please add it to this list via a PR
🙌
If you have any questions, share some ideas or just want to chat about GraphQL bindings, join the #graphql-bindings
channel in our Slack.