graphql-genie

GraphQL Genie

Write a GraphQL Type Schema and GraphQL Genie automatically generates a fully featured GraphQL API with referential integrity and inverse updates that can be used client side or server side. You can use all the features of the type schema, including interfaces and unions. GraphQL Genie is easy to extend with plugins, ones already exist to add subscriptions and setup role based authentication.

The schema uses best practices and is compliant with the Relay GraphQL Server Specification.

In short GraphQL Genie handles creating the root Query, Mutation and Subscription types and resolvers for a variety of data stores. If that doesn't mean anything to you it may be good to read up on some graphql basics or learn by experimenting with the demo

Demo

See the fully featured demo. Create a schema (or use the default provided) and a fully featured api is created. Click the search icon to use GraphiQL to view docs and create or mock data. See graphql genie client on github for more info on the demo.

Or for a server demo see the graphql yoga redis example (no external db setup required as it uses a mock redis) or graphql yoga postgres example

Installation

npm install graphql-genie fortune graphql graphql-tools lodash

or

yarn add graphql-genie fortune graphql graphql-tools lodash

Getting started

1. Create your type definitions. These are GraphQL Type definitions, GraphQL Genie does have some additional directives which may be useful (unique, relations, timestamps, default values). Documentation in docs/sdl.md
2. Setup fortune options with your adapter and other settings. See example below or fortune docs and documentation for your adapter
3. Create the schema using genie.
   1. Create a new GraphQLGenie object
   2. call genie.init() (returns a promise)
   3. call genie.getSchema() to get the GraphQLSchema

import { FortuneOptions, GraphQLGenie } from 'graphql-genie';
import mongodbAdapter from 'fortune-mongodb';

//adapter: configuration array for the data store. The default type is the memory adapter. See below for other adapter options
const fortuneOptions: FortuneOptions = {
    adapter: [
        mongodbAdapter,
        {
            // options object, URL is mandatory.
            url: config.mongodbURL
        }
    ],
    settings: { enforceLinks: true }
};
// Instantiate Genie with your type defintions as a string
const typeDefs = `[TYPEDEFS]`
const genie = new GraphQLGenie({ 
    typeDefs: typeDefs, 
    fortuneOptions: fortuneOptions
});

// init genie, this sets up all the new types and resolvers, init returns a promise so use await or .then()
await genie.init();

// get the schema and use it with any other tools you want
const schema: GraphQLSchema = genie.getSchema();

Data Store

GraphQLGenie uses FortuneJS for accessing the data store. This means any fortune adapter will work, plugins currently exist for memory (example), IndexedDB (example), MongoDB (example), Postgres (example), Redis, Google Cloud Datastore, NeDB and File System. Or you could write your own.

Subscriptions

GraphQL Genie also supports subscriptions with the subscriptions plugin.

GraphQL Genie Schema API

• Queries
  • Type Queries

WIP

GraphQLGenie API

The api documentation can be found in the docs folder

Authentication

Checkout the authentication plugin to easily implement role based authentication down to individual fields.

See the yoga redis example for session authentication with users stored in the database. Would be simple to adapt to returning a JWT on login as well.

See the yoga redis firebase example for using firebase authentication to login and control access from an external JWT provider.

Of course Genie creates a normal schema so you can add authentication in any other way you want. (the authentication plugin uses a combination of all of these)

• At the schema level using the context function or addSchemaLevelResolveFunction from graphql-tools
• At the resolver level by wrapping the resolver functions that GraphQL Genie created in the schema, or use a tool like graphql-resolvers to combine resolver, with authentication logic.
• At the data level create an input hook and add it to the DataResolver (returned by getDataResolver) and throw an error if not authorized

How do I do/add [thing]

You can use the methods on the GraphQLSchemaBuilder (returned by getSchemaBuilder()) to add types and resolvers to the generated schema. Or since it is just a normal schema you can use any tool you want (such as graphql-tools) to alter the schema in any way. Including adding resolvers, mocking, stitching, transforming, etc.

If you want guidance feel free to open an issue and label it as a question.

See examples and tests for implementation examples.

Features/Advantages/Differences

GraphQL Genie is inspired by Prisma GraphQL and the resulting API has a lot of similarities but they have different goals. Because GraphQL Genie gives you a fully functioning graphql api but is not opinionated about anything else you have the flexibility to use that schema wherever you want and integrate it with any existing services you use.

• Bi-directional relationships in any database with a GraphQL API
• Portable storage options, use anywhere for any purpose which is essential for some applications.
• Export/Import/Merge data between data sources
• Share GraphQL data model on server and client
• You can use The Apollo Platform, Relay, GraphQL Bindings or any of the many other tools in the growing GraphQL ecosystem.
• You can use your existing authentication methods or one provided by an outside service.
• The api stays the same regardless of data source, so you are never locked into one database or even server/client side
• You can make your api logic completely serverless

TODO

• API Documentation

Thanks/Credit

Prisma GraphQL / Graphcool for inspiration

FortuneJS for CRUD adapters

Logo Icon made by Freepik from www.flaticon.com is licensed by CC 3.0 BY