graphql-compose

Toolkit for generating complex GraphQL Schemas on Node.js

GraphQL
graphql-compose/graphql-composegraphql-compose.github.io/graphql-compose

README


graphql-compose

undefined codecov coverage Travis npm Commitizen friendly
TypeScript compatible Backers on Open Collective Sponsors on Open Collective

graphql-compose – provides a type registry with a bunch of methods for programmatic schema construction. It allows not only to extend types but also remove fields, interfaces, args. If you want to write your graphql schema generator – graphql-compose is a good instrument for you.

provides methods for editing GraphQL output/input types (add/remove fields/args/interfaces)
introduces Resolver's – the named graphql fieldConfigs, which can be used for finding, updating, removing records
provides an easy way for creating relations between types via Resolver's
provides converter from OutputType to InputType
provides projection parser from AST
provides GraphQL schema language for defining simple types
adds additional types Date, Json

And a little bit more


graphql-compose-[plugin] – are _declarative generators/plugins_ built on top of graphql-compose, which take some ORMs, schema definitions and create GraphQL Models from them or modify existing GraphQL Types.

Type generators built on top graphql-compose


graphql-compose-json - generates GraphQL type from JSON (a good helper for wrapping REST APIs)
graphql-compose-mongoose - generates GraphQL types from mongoose (MongoDB models) with Resolvers.
graphql-compose-elasticsearch - generates GraphQL types from elastic mappings; ElasticSearch REST API proxy via GraphQL.
graphql-compose-aws - expose AWS Cloud API via GraphQL

Utility plugins:


graphql-compose-relay - reassemble GraphQL types withRelay specific things, like Node type and interface, globalId, clientMutationId.
graphql-compose-connection - generatesconnection Resolver from findMany and count Resolvers.
graphql-compose-dataloader - adds DataLoader to graphql-composer resolvers.

Documentation


graphql-compose.github.io

Live Demos


graphql-compose.herokuapp.com - Live demo of GraphQL Server (9 models, 14 files, ~750 LOC)
nodkz.github.io/relay-northwind - Live demo of Relay client working with the server above (8 crazy pages, 47 files, ~3000 LOC)

Examples


Please follow Quick Start Guide for the complete example.

Here is just a demo of ambiguity ways of types definitions:

  1. ``` js
  2. import { schemaComposer} from 'graphql-compose';

  4. // You may use SDL format for type definition
  5. const CityTC = schemaComposer.createObjectTC(`
  6.   type City {
  7.     code: String!
  8.     name: String!
  9.     population: Number
  10.     countryCode: String
  11.     tz: String
  12.   }
  13. `);

  15. // Define type via Config object
  16. const CountryTC = schemaComposer.createObjectTC({
  17.   name: 'Country',
  18.   fields: {
  19.     title: 'String',
  20.     geo: `type LonLat { lon: Float, lat: Float }`,
  21.     hoisting: {
  22.       type: () => AnotherTC,
  23.       description: `
  24.         You may wrap type in thunk for solving
  25.         hoisting problems when two types cross reference
  26.         each other.
  27.       `,
  28.     }
  29.   }
  30. });

  32. // Or via declarative methods define some additional fields
  33. CityTC.addFields({
  34.   country: CountryTC, // some another Type
  35.   ucName: { // standard GraphQL like field definition
  36.     type: GraphQLString,
  37.     resolve: (source) => source.name.toUpperCase(),
  38.   },
  39.   currentLocalTime: { // extended GraphQL Compose field definition
  40.     type: 'Date',
  41.     resolve: (source) => moment().tz(source.tz).format(),
  42.     projection: { tz: true }, // load `tz` from database, when requested only `localTime` field
  43.   },
  44.   counter: 'Int', // shortening for only type definition for field
  45.   complex: `type ComplexType {
  46.     subField1: String
  47.     subField2: Float
  48.     subField3: Boolean
  49.     subField4: ID
  50.     subField5: JSON
  51.     subField6: Date
  52.   }`,
  53.   list0: {
  54.     type: '[String]',
  55.     description: 'Array of strings',
  56.   },
  57.   list1: '[String]',
  58.   list2: ['String'],
  59.   list3: [new GraphQLOutputType(...)],
  60.   list4: [`type Complex2Type { f1: Float, f2: Int }`],
  61. });

  63. // Add resolver method
  64. CityTC.addResolver({
  65.   kind: 'query',
  66.   name: 'findMany',
  67.   args: {
  68.     filter: `input CityFilterInput {
  69.       code: String!
  70.     }`,
  71.     limit: {
  72.       type: 'Int',
  73.       defaultValue: 20,
  74.     },
  75.     skip: 'Int',
  76.     // ... other args if needed
  77.   },
  78.   type: [CityTC], // array of cities
  79.   resolve: async ({ args, context }) => {
  80.     return context.someCityDB
  81.       .findMany(args.filter)
  82.       .limit(args.limit)
  83.       .skip(args.skip);
  84.   },
  85. });

  87. // Remove `tz` field from schema
  88. CityTC.removeField('tz');

  90. // Add description to field
  91. CityTC.extendField('name', {
  92.   description: 'City name',
  93. });

  95. schemaComposer.Query.addFields({
  96.   cities: CityTC.getResolver('findMany'),
  97.   currentTime: {
  98.     type: 'Date',
  99.     resolve: () => Date.now(),
  100.   },
  101. });

  103. schemaComposer.Mutation.addFields({
  104.   createCity: CityTC.getResolver('createOne'),
  105.   updateCity: CityTC.getResolver('updateById'),
  106.   ...adminAccess({
  107.     removeCity: CityTC.getResolver('removeById'),
  108.   }),
  109. });

  111. function adminAccess(resolvers) {
  112.   Object.keys(resolvers).forEach(k => {
  113.     resolvers[k] = resolvers[k].wrapResolve(next => rp => {
  114.       // rp = resolveParams = { source, args, context, info }
  115.       if (!rp.context.isAdmin) {
  116.         throw new Error('You should be admin, to have access to this action.');
  117.       }
  118.       return next(rp);
  119.     });
  120.   });
  121.   return resolvers;
  122. }

  124. // construct schema which can be passed to express-graphql, apollo-server or graphql-yoga
  125. export const schema = schemaComposer.buildSchema();
  126. ```

Contributors


This project exists thanks to all the people who contribute.

Backers


Thank you to all our backers! 🙏 [Become a backer]


Sponsors


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]


License


MIT