Roadmap for GraphQL

[resolritter]

I've seen mentions of GraphQL in the issue tracker and some other places throughout this repository.

I'd like to know what would take to get rest-hooks to an architecture/API which would support GraphQL as a first-class citizen, e.g.

• Do the internal components (e.g. the caching mechanism) need to change?
• Does the API surface need to change?

Another pertaining question would be if you're planning to implement a client directly or use an existing third-party library. I infer the latter might be possible since I've seen #201, or maybe it already is possible currently through some user-land implementation and I'm not aware of it.

Overall, the point of this issue is to

• List what's missing and what is the timeline for it
• Point at some modules of interest in the code base
• What good ideas for an implementation would be
• What the community could contribute to make GraphQL viable

I'm personally interested in using rest-hooks for everything (REST, WebSockets, ...) since I really like the design and how modern it is.

[ntucker]

Excellent question! Thanks for raising this issue, I'm sure there are many others who are interested.

Current status

Currently it's possible to use any transport protocol like graphql, websockets, etc with the core of rest hooks. All that is needed for pull/fetch style APIs is Entity and FetchShape/Endpoint definitions. For push/websocket style APIs one should define Entity and Managers.

However, the only convenience helpers are for CRUD-style fetch APIs (REST-like) in the Resource class. To support other protocols in a nice way, similar constructions should be made available that layer on top of rest hooks core.

At Coinbase we actually use both a legacy REST-like API using Resources, and also use protos to define a new RPC-style API that autogenerates the relevant Entities+FetchShape/Endpoints. Additionally we have two Managers for both websocket push as well as websocket http request (we call this one 'pusher').

For GraphQL one could simply define their own entities and FetchShape/Endpoint for a given request and it would work. However, this would not have the flexibility of arbitrary easy queries. For example (using new Endpoint style definitions).

// all GraphQL entities have an id field
class GQLEntity {
  readonly id: string = '';
  pk() { return this.id; }
}
class User extends GQLEntity {
  readonly username: string = '';
}

const UserList = new Endpoint(
  () => fetch('/query', { body: '{ users { id, username } }', method: 'POST' }),
  { schema: { data: [User] } }
);

However, this is not very convenient since we have to hand write our entities, we're repeating our query definition in both the schema and string payload, and we lose flexibility of which fields are returned. However, if you don't need the flexibility and just want it to work with existing APIs - this will totally work.

Roadmap for GraphQL

To build what we would consider a great GraphQL experience we'd want to have the following:

• GraphQL schema -> Entity + query schema autogenerator
• babel plugin that compiles gql strings to schema definitions
• Function to build dynamic endpoint definitions based on gql schema generation output

After building these it would look something like this:

const { users } = useResource(gql`{ users { id, username } }`, { });

const { hero } = useResource(gql`
{
  hero {
    name
    friends {
      name
      homeWorld {
        name
        climate
      }
      species {
        name
        lifespan
        origin {
          name
        }
      }
    }
  }
}
`,
{ id: 5 }
);

Timeline

We currently don't have this on our immediate radar - though that might change. However, we would be quite happy to assist and review community contributions.

[resolritter]

However, this is not very convenient since we have to hand write our entities, we're repeating our query definition in both the schema and string payload, and we lose flexibility of which fields are returned.

GraphQL schema -> Entity + query schema autogenerator

There are some powerful generators out there which provide similar functionality. One I'm using in one of my back-end experiments is called Prisma, more specifically coupled with the nexus-plugin-schema plugin, which is able to generate both the full GraphQL schema and the TypeScript typings from the Prisma DSL.

I've created this repository to showcase what I've been able to get out of it so far

https://github.com/resolritter/showcase-prisma-generation

It shows all the files you'd able to generate from that single schema.prisma file. Leveraging the generated types, one could instead do

useResource<UserInputParams>(GraphQLUserResource, userInputParams)

Where UserInputParams could be inferred from GraphQLUserResource's type, same as it's done for the REST resources.

For type-checking of the fragment literals at development time, one could use:

https://github.com/Quramy/ts-graphql-plugin

---

From the points you've raised, to my current understanding and according to how I envision my workflow, only this one seems far away at the moment

Function to build dynamic endpoint definitions based on gql schema generation output

This I'd rather do that ahead-of-time, though, with some CLI script watching the source code and automatically regenerating the Endpoint definitions on file changes, which would get recognized by TSServer (it's just code). I'm guessing it's different from what you described (function?).

Walking the TypeScript AST and outputting those Endpoint modules based on some custom-named tag should be simply enough, for example

https://github.com/beenotung/tsc-macro/blob/182737fe346ad379e244b74e2dd20495f311abad/src/scanner.ts#L17

I got the impression, from your response, that you're envisioning something more runtime-related. I'm not sure.

Anyways, glad to know it's already possible to interact with GraphQL! I'll try to incorporate it in some toy project I'm making and let you know if I have some news.

[atefBB]

Hi @ntucker! Any news about this issue?
graphql would be a great addition to the package!

[ntucker]

I agree it would be a great addition. I'm happy to provide assistance or design discussions around any additions - even as simple as starting @rest-hooks/graphql package with a GQLEntity member and some basic docs on getting the current form working. However, it's not a priority for the near term for me or the others primarily involved at this time.

We think GraphQL has some great use cases, so we'd be super happy with any level of contributions to the matter :)

[adsharma]

GraphQL schema -> Entity + query schema autogenerator

Why not Entity -> GraphQL schema generator? That is the approach taken by fquery a python based project with some similarities to rest-hooks.

https://adsharma.github.io/django-fquery/

GraphQL also doesn't have a good solution for more complex queries (filters, order by etc). Some extensions exist, but they don't work as well as a strongly typed method chaining solution.

[ntucker]

Why not Entity -> GraphQL schema generator?

Certainly that's a viable approach. Probably even better since Rest Hooks is more expressive than GraphQL. We're happy to take PRs for this approach :)

[ntucker]

Here's what I got so far

const gql = new GQLEndpoint('https://nosy-baritone.glitch.me');

const userList= gql.query(
`{
	users {
		id
		name
		email
	}
}`,
{ users: [User] }
)
const {users} = useResource(userList)

const userDetail = gql.query<{id: string}>(
`query UserDetail($id: ID) {
	users(id: $id) {
		id
		name
		email
	}
}`,
{ users: User },
)

const {users} = useResource(userDetail, { id: 5 })

This should be really easy, honestly less code than @rest-hooks/rest

[ntucker]

Docs
@rest-hooks/graphql

Happy to take input or PRs. This is basic implementation.