graphql-lattice (www.graphql-lattice.com)

🚧 Work in Progress 🚨

Understand that GraphQL Lattice is still a work in progress and no assumptions about permanent usability should be made. Feedback and pull requests are welcome as is any desire to contribute. Documentation is noticeably sparse. It is a known issue, please be patient while this is worked on. Please feel free ask me or the contributors to the project should you have any specific questions. The source code should be well documented, as are the example apps listed below.

What is GraphQL?

Facebook's site on GraphQL states that GraphQL is, "A query language for your API." It goes on to say

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Facebook provides an excellent source of information on learning GraphQL and interfacing it with various server side language implementations that you might be using. To learn more about this, head over to their site.

What is Lattice?

Lattice for GraphQL is predominantly aimed to be a tool for managing and organizing your Schema and resolvers. It is somewhat Object Oriented but very much in same way that one might use class Component extends React.Component. Extensive inheritance and any over abundance of abstraction will likely lead you to a hole that will be hard to get out of, nor is the recommended way to use GraphQL Lattice.

The primary goals of Lattice are

• Provide a consistent method of logically keeping your Schema for a given type next to the resolvers and implementation that make it up.
• Provide an easy way to add documentation to every level of your Schema, programmatically, while still using GraphQL SDL/IDL to define the structure of your Schema.
• Prevent any manual labor involved in merging the Query or Mutation types you've defined for all the GraphQL Object types you've put together in your application.
  • Uses ASTs, not string parsing, in order to make this happen

Much of the newer Lattice code emphasizes the usage of ES7 Decorators and other advanced JavaScript features such as Proxies. While ES7 Decorators are not required, their usage reduces a lot of boilerplate and are the recommended way to write Lattice code.

Optionally Opininated Features

Some features of Lattice, while optional, are opininated and can make your life easier if you like the idea of how they work. One such feature is the ModuleParser. The ModuleParser, given a directory of GQLBase extended, or Lattice, classes, will automatically extract and build your Schema from this extraction. So, if you have a directory structure such as this

gql
├── enums
├── interfaces
└── types
    ├── Job.js
    └── Person.js

You could write code like like the following and no matter how many types, enums, interfaces or more that you ended up writing in the future, as long as that code was placed under the ./src/gql directory path passed to ModuleParser, it would automatically be loaded and ready for use going forward.

The idea of JavaScript dynamically loading this code on startup is contentious to some and this is why it is optional, but Lattice is focused on removing unnecessary boilerplate so that you can focus on getting your work done. This is one way that it can do so.

import { Router } from 'express'
import { GQLExpressMiddleware, ModuleParser } from 'graphql-lattice'

const router = Router();
const parser = new ModuleParser('./src/gql')
const lattice = new GQLExpressMiddleware(parser.parseSync())

router.use('/graphql', lattice.middleware)

Roadmap 🛣

GraphQL Lattice version map

|Version| 🚧 |Changes| |-------|---|-------| |2.13.0|✅|Support "lattice" package.json entries| ||✅| • ModuleParser file extensions and failOnError flag| ||✅| • Error handling; die or continue| ||✅|GQLBase| ||✅| • AutoProps - automatically apply @Properties for fields missing resolvers (1:1 type/model mapping)| ||✅|utils/getLatticePrefs fetches prefs from local package.json ||✅|ModuleParser| ||✅| • Capture errors as they occur decide whether to die or continue based on prefs| ||✅| • Process only registered extensions| ||✅| • Capture error for each file processed that throws for later processing| ||✅|Additional unit tests| ||✅|getProp in GQLBase to fetch property resolver regardless of type| ||✅|getResolver in GQLBase to fetch a resolver from class or instance| |2.13.1|✅|Fix overzealous auto-prop creation ||✅| • AutoProps were being created when they shouldn't due to how existing property existence was being tested| ||✅| • Fixed the usage of target[key] to descriptor.value for @resolver/@mutator/@subscriptor usage| |2.14.0|🔜|ModuleParser module import support| ||🔜| • Given 'gql-users' as a module name, ModuleParser should be able to find this module in your node_modules directory and import the files from that location for you so you do not have to worry about things like your current working directory and so on.|

Example projects

Until the new, under construction website is released, you can take a look at some of these quickstart boilerplate setups.

Server Only

https://github.com/nyteshade/lattice-quickstart

React Client with Lattice/Express Backend

https://github.com/nyteshade/lattice-markdown-server-client