@ttoss/graphql-api

This package provides an opinionated way to create an GraphQL API using ttoss ecosystem modules. The main goal of this package is to provide a resilient way to create a complex GraphQL API to meet the following goals:

1. Modular: you can create your GraphQL API using modules, so you can reduce the complexity of a big GraphQL API.
2. Relay: ttoss uses Relay as the main GraphQL client, so this package implements the Relay Server Specification.
3. Build Schema: as Relay needs an introspection query to work, this package provides a way to build the GraphQL schema by running ttoss-graphl-api build-schema.
4. AppSync Support: this package provides a way to create a GraphQL API that works with AWS AppSync, besides you can also create a local GraphQL API server.

Installation

pnpm add @ttoss/graphql-api graphql

Getting Started

This library uses graphql-compose to create the GraphQL schema. It re-export all the graphql-compose types and methods, so you can use it directly from this package.

Type Creation

For more examples about how to create types, check the graphql-compose documentation.

import { schemaComposer } from '@ttoss/graphql-api';

const UserTC = schemaComposer.createObjectTC({
  name: 'User',
  fields: {
    id: 'ID!',
    name: 'String!',
  },
});

Resolvers

Integrate All Modules

Once you've created all your types and resolvers, you can integrate all the modules to create the GraphQL schema.

// scr/schemaComposer.ts
import { schemaComposer } from '@ttoss/graphql-api';
import './modules/Module1/composer';
import './modules/Module3/composer';
import './modules/User/composer';

export { schemaComposer };

Relay Server Specification

As ttoss uses Relay as the main GraphQL client, this library implements the Relay Server Specification.

Object Identification

Method composeWithRelay will handle the object identification for your ObjectTypeComposer, it will return a globally unique ID among all types in the following format base64(TypeName + ':' + recordId).

Method composeWithRelay only works if ObjectTypeComposer meets the following requirements:

1. Has defined recordIdFn: returns the id for the globalId construction. For example, if you use DynamoDB, you could create id from hash and range keys:

   UserTC.setRecordIdFn((source) => {
     return `${source.hashKey}:${source.rangeKey}`;
   });

2. Have findById resolver: this resolver will be used by RootQuery.node to resolve the object by globalId. For example:

   UserTC.addResolver({
     name: 'findById',
     type: UserTC,
     args: {
       id: 'String!',
     },
     resolve: ({ args }) => {
       const { type, recordId } = fromGlobalId(args.id);
       // find object
     },
   });

Example

import {
  composeWithRelay,
  schemaComposer,
  fromGlobalId,
} from '@ttoss/graphql-api';

const UserTC = schemaComposer.createObjectTC({
  name: 'User',
  fields: {
    id: 'ID!',
    name: 'String!',
  },
});

/**
 * 1. Returns you id for the globalId construction.
 */
UserTC.setRecordIdFn((source) => {
  /**
   * If you use DynamoDB, you could create id from hash and range keys:
   * return `${source.hashKey}:${source.rangeKey}`;
   */
  return source.id;
});

/**
 * 2. Define `findById` resolver (that will be used by `RootQuery.node`).
 */
UserTC.addResolver({
  name: 'findById',
  type: UserTC,
  args: {
    id: 'String!',
  },
  resolve: ({ args }) => {
    const { type, recordId } = fromGlobalId(args.id);
    // find object
  },
});

/**
 * 3. This will add the `id` field and the `node` query.
 */
composeWithRelay(UserTC);

We inspired ourselves on graphql-compose-relay to create composeWithRelay.

Building Schema

As Relay needs an introspection query to work, this package provides a way to build the GraphQL schema by running ttoss-graphl-api build-schema.

ttoss-graphl-api build-schema

Server

This package provides a Koa server to run your GraphQL API. You can use the createServer method to create the server.

import { createServer } from '@ttoss/graphql-api/server';

const server = createServer({
  schemaComposer,
  graphiql: true,
});

server.listen(3000, () => {
  console.log('Server listening on port 3000');
});