graphql-genie

GraphQL Genie

• Overview
• Installation
• Demo
• Getting started
• Documentation and Features
  • Data Store Options
  • GraphQL Genie Schema API (queries and mutations)
  • GraphQLGenie API
  • Subscriptions
  • Authentication
• Examples
  • Client
  • Server
• Features/Advantages/Differences
• Roadmap

Overview

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.

• Full GraphQL Support You can use all the features of the type schema, including interfaces and unions.
• Feature Rich API including nested operations, filtered queries, pagination. Transactional if your adapter supports it.
• Easy to extend with plugins Ones already exist to add subscriptions and setup role based access control.
• Works with other GraphQL libraries like Relay(react) and Apollo Client(vanilla js or any framework)
• Portable data with a variety of data stores including client and server side support and Export/Import/Merge functions.
• FortuneJS Storage allows many storage options and the ability to easily create your own. See data store options

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]((https://genie-team.github.io/graphql-genie-client/)

Installation

npm install graphql-genie fortune graphql graphql-tools lodash

or

yarn add graphql-genie fortune graphql graphql-tools lodash

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 server examples.

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 = {
  // see the documentation for your specific adapter
  adapter: [    
    mongodbAdapter,
    {
      // options object, URL is mandatory.
      url: config.mongodbURL
    }
  ]
};
// Instantiate Genie with your type defintions as a string
const typeDefs = `
type City {
  id: ID! @unique
  name: String!
  neighborhoods: [String] @unique
  residents: [User] @relation(name: "city")
  founded: Date
  population: Int
}
type User {
  id: ID! @unique
  displayname: String @unique
  email: String! @unique
  location: City @relation(name: "city")
}`;
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();

Documentation and Features

Data Store Options

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), PostgreSQL (example), Redis (examples), Google Cloud Datastore, NeDB and File System. Or you could write your own adapter.

GraphQL Genie Schema API (queries and mutations)

• Type Queries
• Connection Queries
• Mutations
• Also see the subscriptions plugin

GraphQLGenie API

The api documentation can be found in the docs folder

Subscriptions

GraphQL Genie also supports subscriptions with the subscriptions plugin.

Authentication

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

See the apollo server 2 redis jwt example for JWT authentication with users stored in the database. Uses Apollo Server 2.

See the yoga redis example for session authentication with users stored in the database.

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, see the api documentation) 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.

Examples

Client

Memory

Sets up an API that stores data in browser memory

IndexedDB

Sets up an API that stores data in browser Indexed DB

Server

Apollo Server 2 Redis with JWT Authentication

Sets up a server using Apollo Server 2 and an api that stores to a mock Redis with json web token based signup and login. Uses the authentication plugin for role based access control.

GrapqhQL Yoga Redis with Session Authentication

Sets up a server using GrapqhQL Yoga and an api that stores to a mock Redis with session based signup and login. Uses the authentication plugin for role based access control.

GrapqhQL Yoga Redis with Firebase Authentication

Sets up a server using GrapqhQL Yoga and an api that stores to a mock Redis. Serves static html for firebase signup and login. Uses the authentication plugin for role based access control.

GraphQL Yoga PostgreSQL

Sets up a server using GrapqhQL Yoga and an API that stores to PostgreSQL.

Other

MongoDB

Creates a simple node script that uses the GraphQL Genie api to store in a MongoDB database

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, great for Progressive Web Apps. Use anywhere for any purpose.
• 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
• You can use all the features of the type schema, including interfaces and unions.
• Input and Output hooks against the actual data resolver add more possibilities for advanced functionality
• FortuneJS allows easy creation of new adapters

Roadmap

• Import/Export mutations (currently exist as function on GraphQLGenie object Export/Import/Merge)
• Progressive Web App example

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