ReasonQL is a type-safe and simple GraphQL library for ReasonML developers.
ReasonQL does 2 things for you:
- fetch GraphQL data from server.
- and decode that data and error messages from JSON to ReasonML record.
You might think it's too simple and you're now finding cool features like cache, "fetch more", reload, auth, etc. ==> If so, please check "Why I started this project".
You need 2 packages: @reasonql/core and @reasonql/compiler. Install it with npm like below:
npm i @reasonql/core
npm i -D @reasonql/compiler
or with yarn
yarn add @reasonql/core
yarn add @reasonql/compiler --dev
And add @reasonql/core in bs-dependencies under bsconfig.json.
"bs-dependencies": [
"@reasonql/core",
"reason-react",
]This document assumes that you're familiar with ReasonML and GraphQL. If you're not sure what GraphQL is, check the offical documentation.
let query = ReasonQL.gql({|
query AppQuery {
hello {
message
}
}
|})Don't forget to use ReasonQL.gql function and {||} multiline string. ReasonQL compiler uses them to find if a file has graphql code or not.
WARNING: The query name (AppQuery above) is used for the name of the file generated by the compiler. So, do not use duplicate query names. Compiler doesn't warn this and multiple queries will try to overwrite a single type file.
To compile GraphQL queries, we need the path to the GraphQL schema file. Create reasonql.config.js at the project root and fill it like below:
module.exports = {
schema: "path/to/schema.js",
}Add the below command to package.json:
"scripts": {
"reasonql": "reasonql-compiler"
}And run the command with npm run reasonql.
You can find AppQuery.re under src/.reasonql.
Note: As the files under src/.reasonql are generated by the ReasonQL Compiler, it is recommended to ignore the folder in .gitignore.
Note2: It is a really tedious job to type in npm run reasonql each time when queries are changed. So, when in development, use the option, -w, like below:
"scripts": {
"reasonql": "reasonql-compiler",
"reasonql:dev": "reasonql-compiler -w"
}It watches reason files and regenerate files only when the GraphQL queries are changed.
module Request = ReasonQL.MakeRequest(AppQuery, {
let url = "http://localhost:4000";
});MakeRequest functor receives 2 arguments: a module generated by the ReasonQL compiler and a module that contains the link to the server.
Request.send(Js.Dict.empty())
->Request.finished(data => {
Js.log("Data fetched.");
})
Js.log("Loading data...");All you need to remember are these 3 functions:
send(argumentRecord)finished(promise, data => unit)finishedWithError(promise, (data, option(error)) => unit)
As send returns a Js.Promise and finished and finishedWithError have promise as their first argument, we can use the pipe syntax here.
You learned the basics of ReasonQL. Unlike other libraries like Apollo or Relay, you don't need to create React components to use GraphQL.
If you want to know how to make "hello world" with ReasonQL, check the example.
If you want to see the working examples, check the snippets folder.
5 scalar types (ID, Int, Float, String, Boolean) of GraphQL are converted into appropriate ReasonML types(string, int, float, string, bool). (By definition, ID type is serialized into STRING.)
Object types are compiled into ReasonML types.
# Schema
type Greeting {
hello: String!
}
type Test1 {
a: Greeting!
}
# Query
query AppQuery {
a {
hello
}
}type a = {
hello: string,
};
type queryResult = {
a: a,
};Note: As you can see, object type name doesn't follow the actual name(greeting) in the type definition, but uses the variable name(a) to avoid type name conflict. More about name conflict below.
In GraphQL, the field types without ! are nullable. So, they're translated into option-ed types in ReasonML.
Example:
# Schema
type Query {
a: String
b: String!
}
# Query
query Test1 {
a
b
}type queryResult = {
a: option(string),
b: string,
}Note: When a type is an option, we need to use pattern matching to cover all cases. In ReasonML, it's tedious and sometimes meaningless. So, when you define the schema for your app, always consider when null should be used. If you cannot find the meaningful case, add !. (Unlike many JavaScript examples, you'll find yourself adding many non-null types in ReasonML apps.)
Conventionally, GraphQL enum values are written in all capital with underscores like EXTRA_LARGE. And they're strings internally.
However, ReasonML uses camel case with the first letter capital-cased. And they're compiled into numbers.
ReasonQL compiler translates that perfectly.
enum PatchSize {
SMALL
MEDIUM
LARGE
EXTRA_LARGE
}type patchSize =
| Small
| Medium
| Large
| ExtraLarge
;Unlike other types, encoders and decoders of enum types are defined in EnumTypes.re file. And the functions are imported to each type file.
Sometimes, field names of object types can conflict like below:
# Schema
type Query {
hero: Person!
villain: Person!
}
type Person {
name: Name!
ship: Ship
}
type Name {
first: String!
last: String
}
type Ship {
name: String!
}
# Query
query AppQuery {
hero {
name @reasontype(name:"heroName") {
first
last
}
ship {
name
}
}
villain {
name {
first
}
ship @reasontype(name:"villainShip") {
name
}
}
}type heroName = {
first: string,
last: option(string),
};
type hero_ship_Ship = {
name: string,
};
type hero = {
name: heroName,
ship: option(hero_ship_Ship),
};
type villain_name_Name = {
first: string,
};
type villainShip = {
name: string,
};
type villain = {
name: villain_name_Name,
ship: option(villainShip),
};
type queryResult = {
hero: hero,
villain: villain,
};Both hero and villain have name and ship. In those cases, the type names are generated with the list of the names in the path and schema type name(i.e. hero_ship_Ship, villain_name_Name).
To avoid this, you can use @reasontype directive like @reasontype(name:"villainShip").
Sometimes, it is logical to name a variable in plural and its type in singular like below:
# Schema
type Query {
posts: [Post!]!
}
type Post {
title: String!
slug: String!
content: String!
summary: String
}
# Query
query AppQuery {
posts @singular(name:"post") {
title
slug
content
summary
}
}type post = {
title: string,
slug: string,
content: string,
summary: option(string),
};
type queryResult = {
posts: array(post),
};Borrowed the idea from Relay. When writing code, it is always a good idea to put related things together in one place. With fragments, you can define the data a component needs in the same file like below:
let query = ReasonQL.gql({|
fragment PostFragment_post on Post {
title
summary
slug
...ButtonFragment_post
}
|})
let component = ReasonReact.statelessComponent("Post")
let make = (
~post: PostFragment.post,
_children
) => {
...component,
/* Code here */
}You can read the full code here.
Then, ReasonQL compiler magically merges fragments into the main query.
Mutations work in the same way like queries. Use MakeRequest functor and send, finished functions. But in mutations, you need to use arguments a lot.
When there are arguments, the type of the argument of send function changes from Js.Dict to a specific variables.
So, we need to write code like below:
let saveTweet = ReasonQL.gql({|
mutation SaveTweetMutation($tweet: TweetInput!) {
saveTweet(tweet: $tweet) {
success
id
tempId
text
}
}
|})
module SaveTweet = ReasonQL.MakeRequest(SaveTweetMutation, Client);
SaveTweet.send({
tweet: {
text: tweet.text,
tempId: tweet.id,
}
})
->SaveTweet.finished(data => {
Js.log("data recieved");
})You can read the full code here.
Apollo Server provides a lot of error types. Among them, you need to provide your own type definition for UserInputError. So, we need decoders for those errors.
To do so, create special GraphQL schema file: errors.graphql.
And write down error types like below:
type LoginFormError {
code: String!
email: String
password: String
}And add the path to errors.graphql to reasonql.config.js like below:
module.exports = {
schema: "../server/src/schema.js",
errors: "../server/src/errors.graphql",
}Then, the decoder will be generated at .reasonql/QueryErrors.re. Now, you can decode error contents like below:
Login.send({ email, password })
->Login.finishedWithError((result, errors) => {
switch(errors) {
| None => {
login(Belt.Option.getExn(result.login));
ReasonReact.Router.push("/");
}
| Some(errors) => {
let {email, password}: QueryErrors.loginFormError
= QueryErrors.decodeLoginFormError(errors[0].extensions);
self.send(ShowError(email, password));
}
}
})-w,--watch: watch reason files and generate reasonql type files only when query code changes.
schema: required. The path to the GraphQL schema file.errors: The path to the error schema file.src: The root path of the reasonml files. Default:./src.include: The files should be included from compilation. Default:**.exclude: The files should be excluded from compilation. Default:[ '**/node_modules/**', '**/__mocks__/**', '**/__tests__/**', '**/.*/**', ]watch: Watch files. Default:false.
Helps are always welcome. If you want to check how to contribute to the project, check this document.