Simple Graphql

Introduction

A simplified version of graphql package that saves you from all the boilerplate code. Cheers 🍻!

• Simple Graphql
  • Introduction
  • Get started
    • Create a query
    • Create a mutation
• Advanced usage
  • Authentication and custom headers
  • Custom policies

Get started

Like the name implies, using this package is simple. Just import the package, and create a new SimpleGraphQl instance with your custom URL.

import 'package:simple_graphql/simple_graphql.dart';

final client = SimpleGraphQl(apiUrl: 'https://api.myapi.example/graphql');

Note: API URLs must specify the graphql path at the end.

Create a query

To execute a query, just call the query() method.

final client = SimpleGraphQl(apiUrl: 'https://api.myapi.example/graphql');

final result = client.query(
  query: "<Your query goes here>",
  resultBuilder: (data) {
    // Here is where you would want to serialize the result.
    return data;
  },
);

The resultBuilder parameter is a handy builder that returns a Map with the decoded result. You may serialize the result to a concrete object, or handle it as a Map.

When serializing to concrete classes, it is recommended to specify the type of the class, like so:

final result = client.query<User>(
  query: '''
    query ExampleQuery() {
      getUser {
        id,
        name,
        email
      }
    }
  
  ''',
  resultBuilder: (data) {
    return User.fromMap(data['getUser']);
  },
);

The first layer of the Map parameter of resultBuilder will always be named like the query or mutation being called. In the example above, the query is named getUser.

Create a mutation

Similar to executing queries, to execute a mutation, call the mutate() method.

final client = SimpleGraphQl(apiUrl: 'https://api.myapi.example/graphql');

final result = client.mutation(
  query: "<Your mutation goes here>",
  resultBuilder: (data) {
    // Here is where you would want to serialize the result.
    return data;
  },
);

Advanced usage

Authentication and custom headers

To set custom headers and authentication tokens for all your petitions, you must declare them when creating a SimpleGraphQl instance.

final client = SimpleGraphQl(
  apiUrl: 'https://api.myapi.example/graphql',
  headers: {
    'customHeaderKey': 'Custom value',
  },
  token: 'Bearer $token',
);

By default, the token's header key is Authorization, but you can override it by setting the headerKey parameter when creating a new instance of SimpleGraphQl.

Custom policies

Like the original package, you can define the policies for your petition.

The available policies are to be defined are fetching, error and cache re-read policies. Todo do so, you can set the policies for both query() and mutation() methods via parameter, with the same Policies class from graphql package. Example below:

final client = SimpleGraphQl()

final result = client.mutation(
  fetchPolicy: FetchPolicy.noCache,
  cacheRereadPolicy: CacheRereadPolicy.mergeOptimistic,
  errorPolicy: ErrorPolicy.ignore,
  mutation: ...,
  resultBuilder: (data) => ...,
);