@cliquelabs/types

@cliquelabs/types

Schema generation for clique

Tools

• apollo-server - Used for the Mock GraphQL server.
• apollo-cli - Code Generation tool.
• merge-graphql-schemas - Combines multiple GraphQL Schemas into one Schema.
• GraphQL Binding - Auto-generated SDK for your GraphQL API.

Contributing Root Types

All new Root Types should be written in the src/Schemas directory. If the GraphQL Schema is backend only, place it in the backend folder. If you GraphQL is user-facing, place it in the presentation folder.

Contributing new types

All new types should be written in the src/typeDefs directory. All types are written in .graphql files.

Contributing Queries/Mutations/Subscription

All new queries should be written in the src/queries directory. All queries are written in .graphql files.

Mock Server

The types repo exports a mock resolver map. You can use this to explore the server.

To run the mock server:

npm run mock-server

Navigate to http://localhost:4000/graphql to access the GraphQL server.

Build Process

When types builds it runs these commands:

• generate-types — Takes all type definitions from the typeDefs folder and exports them to the typeDefintions file. This makes each type exportable by type name.

import { Note } from '@cliquelabs/types/lib/typeDefintions';

• generate-schema-exports — Takes all Root types from the Schemas folder and exports them to Schemas/index. This makes each Root type exportable by file name. The convention for Root Types is: __DOMAIN_NAME__RootType.graphql.

import { NoteRootType } from '@cliquelabs/types/lib/Schemas';

• merge-roottypes — Takes all Root types from the Schemas folder, merges them into a single Root type, and exports it to src/RootType. This can be used for the explorer-schema or even in a GraphQL gateway like Roxy.

import RootType from '@cliquelabs/types/lib/RootType';

• generate-schema-json — Runs the mock server and generates a schema.json file at src/queries/schema.json. This file is primarily used to generate types for iOS and Android. Additionally it can be used for local GraphQL tools like graphql-config or eslint-graphql.

• generate-ts — Takes schema generated by generate-schema-json and all queries in src/queries and generates TypeScript types in src/typescript.

• lint:graphql — Lint all GraphQL files with query/mutation/subscription in src/queries and ensure they are valid with the schema.json file generated by the build process.

• generate-service-bindings — Takes each Schema from the Schemas folder and creates a GraphQL Binding Factory. You can then import them in your service or pass it to Roxy to create a GraphQL gateway.

import createNoteBinding from '@clique/types/lib/ServiceBindings/NoteBinding';

const noteBinding = createNoteBinding({
  url: 'http://note-svc/graphql',
  headersToForward: ['userid']
});

const projection = `
      {
          id
      }
  `;

noteBinding.query.notes({}, projection);

Caveats

TypeScript types

Currently, apollo-cli can generate types for GraphQL fragments, but it will not use them to define types for queries with the fragment. Suppose you have the following query:

fragment TodoFragment on Todo {
  _id
  content
  status
}

mutation addTodo($content: String!) {
  addTodo(content: $content) {
    ...TodoFragment
  }
}

apollo-cli will generate the following types:

import { TodoStatus } from "./globalTypes";

export interface TodoFragment {
  __typename: "Todo";
  _id: string;
  content: string;
  status: TodoStatus | null;
}

export interface addTodo_addTodo {
  __typename: "Todo";
  _id: string;
  content: string;
  status: TodoStatus | null;
}

export interface addTodo {
  addTodo: addTodo_addTodo | null;
}

export interface addTodoVariables {
  content: string;
}

As you can see, TodoFragment is successfully generated, but it is not used by addTodo_addTodo interface.

Here's the thread on this issue.