/graphql-genie

Simply pass in your GraphQL type defintions and get a fully featured GraphQL API with referential integrity, inverse updates, subscriptions and role based access control that can be used client side or server side.

Primary LanguageTypeScriptMIT LicenseMIT

GraphQL Genie Logo

GraphQL Genie

npm version Dependency Status devDependency Status npm

liberapay donate patreon paypal

Discord

Overview

Simply pass in your GraphQL type defintions and get a fully featured GraphQL API with referential integrity, inverse updates, subscriptions and role based access control 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 query/mutation fields and 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

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.getSchema() to get the GraphQLSchema
import indexedDBAdapter from 'fortune-mongodb';
import { GraphQLSchema } from 'graphql';
import { FortuneOptions, GraphQLGenie } from 'graphql-genie';

//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
});

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

Documentation and Features

Schema Defining, Altering and Migrations

Documentation in docs/sdl.md

Data Store Options

GraphQLGenie uses FortuneJS for accessing the data store. This means any fortune adapter will work, plugins currently exist for memory (example), localforage, 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)

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 or discussion feel free to ask on stack overflow (tag with graphql-genie) or chat on discord

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. Used in some examples to seed data or see examples in test case
  • Share GraphQL data model on server and client. import/export mutation/query fields will also be created.
  • 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

  • Genie Persistence Plugin - will work with apollo client to work offline and persist to the database when it's available
  • Performance improvements - send info for all necessary queries to fortune so it can handle in less requests, and make sure genie properly handles return of that additional data
  • Progressive Web App example
  • More advanced migration and build process features
  • Production Ready? I would not say Genie is production ready yet, there has not been a lot of actual use yet since it is so new. Almost to a point where I will share it more widely which will help. I plan on using it in a production (although low risk) project in late 2018.

Changelog

Contribute or Donate

  • Code Contributions
    • Fork
    • Make Changes
    • Run the following and make sure no failures or errors
      • npm run test
      • npm run lint
      • npm run build
      • npm run browser
      • npm run module
    • Open pull request
  • Donate
    • Genie and other genie-team products are outcomes of a hobby and receive no other funding, any and all support would be greatly appreciated if you find Genie products useful. Your support will encourage faster development of bug fixes, new features and new products.
    • donate (preferred)
    • patreon
    • paypal

Backers

[Your Name and link Here]

If you contribute and want a thanks callout on genie project READMEs let me know via twitter message (at least 1.00/month). Thanks so much!

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