@apollo-waterline/server v0.3.4

@apollo-waterline/server

Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience

Breaking changes

This library is shifted to Apollo Server 2.0 and is not using graphql-yoga by prisma anymore, because of their usage of Apollo Server 1.0. Apollo Server 2.0 is much improved in many ways and took over some best practices from graphql-yoga. As an example of the Apollo Server 2.0, the error handling is much improoved. So you can create Error Codes, you may pass along to the client to generate i18n language depeneded Error Message. Apollo Error Handling

Actually, this Application now is also capable to be used with Apollo 2.0 Gateway, to create one API Gateway to hook together multiple Graphql Services (Micro Services), according to use the federated Schema ( What is Apollo Federation? ). You are also able to use Managed federation: Announcing managed federation.

Full Documentation of Apollo you may find here: Apollo Docs

Overview

An easy implementation of the Apollo Server 2.x server, but enhanced with an super easy usage of the great Waterline ORM.

Features

Build your Models as used with Sails.JS. Auto Generation auf Model Schemas during Boot Resolver Context is enhanced with Waterline ORM instance ctx.db Usage or Waterline Adapters (Official and Community)

Officially-supported database adapters

• MySQL
• PostgreSQL
• MongoDB
• Local disk / memory
• ...see more here

Community-supported database adapters:

Is your database not supported by one of the core adapters? Good news! There are many different community database adapters for Sails.js and Waterline available on NPM.

Here are a few highlights:

• Redis
• MS SQL Server
• OrientDB
• Oracle
• Oracle (AnyPresence)
• Oracle (stored procedures)
• SAP HANA DB
• SAP HANA (AnyPresence)
• IBM DB2
• ServiceNow SOAP
• Cassandra
• Solr
• FileMaker Database
• Apache Derby
• REST API (Generic)
• ...see more here

Injection of Waterline ORM in Resolver Context

// a resolver example with injected Waterline ORM
Query = {
 myResolver = async (_, args, ctx) => {
     const UserModel = ctx.db.model("User");
     return await UserModel.find();
  }
}

Auto generation of Model Schemas based on your Waterline Models

During the fist boot of the app, a folder structure ist created in your project root.

root/
  api/
    models/
    policies/
    resolvers/
      index.js
    schema/
      models.graphql
      schema.graphql

  config/
    adapter.js
    bootstrap.js
    datastores.js
    models.js
    settings.js

  yourApp.js // this file is not generated

Usage

The module returns a Promise. So it is easy to imolement in an asynchronus stack. Event with async / await. the promise is resolved with: {server, db, express}. So you have access to the server-instsance, de Waterline ORM and the express-application.

const yogaServer = require("@apollo-waterline/server");

// use async / await for more easy reading
(async () => {
  // config für gql
  const graphQLServerOpts = {};

  // config für server
  const bootOpts = {
    endpoint: "/graphql",
    port: 4000,
    playground: false
  };
  const server = await yogaServer(graphQLServerOpts);

  // get express instance
  const express = server.express;

  // modify express instance
  express.use("/myEndpoint", (req, res) => {
    res.send("OK");
  });

  // boot the server and thet the result
  const { port } = await server.boot(bootOpts);
  console.log(`Server is running on port: ${port}`);
})();

graphQlServerConfig

var aContextServiceProcvoder = requrie("my-service-provider");

// for furthor information see: https://www.apollographql.com/docs/apollo-server/api/apollo-server/

let graphQLServerOpts = {
  // typeDefs: Contains GraphQL type definitions in SDL or file
  // path to type definitions (required if schema is not provided *)
  // @url: https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51
  typeDefs: undefined, // String | Function | DocumentNode or array of previous

  // resolvers: Contains resolvers for the fields specified in
  // typeDefs (required if schema is not provided *)
  resolvers: undefined, // Object

  // Object which controls the resolver validation behaviour for more information
  // @url: https://www.apollographql.com/docs/graphql-tools/generate-schema.html#makeExecutableSchema
  resolverValidationOptions: undefined,

  // Applies mocks to schema. Setting this to true will apply a default mock,
  // however you can pass an object to customize the mocks similar to the resolvers map.
  // @url: https://github.com/apollographql/graphql-tools/blob/master/docs/source/mocking.md
  mocks: undefined, // Object | Boolean

  // Contains custom data being passed through your resolver chain.
  // This can be passed in as an object, or as a Function with the
  // signature (req: ContextParameters) => any *
  // IMPORTANT: db is passed to the context, as an insance of the
  // waterline ORM.
  //
  // so e.g:
  // myResolver = async (_, args, ctx) => {
  //    const UserModel = ctx.db.model("User");
  //    return await UserModel.find();
  // }
  context: req => {
    return {
      ...req,
      aContextServiceProvoder
    };
  },

  // schemaDirectives: Apollo Server schema directives that allow for
  // transforming schema types, fields, and arguments
  // @url: https://www.apollographql.com/docs/graphql-tools/schema-directives.html
  schemaDirectives: undefined, // Object

  // middlewares: A list of GraphQLMiddleware middleware.
  // @url: https://github.com/prisma/graphql-middleware
  middlewares: [] // array of Middleware
};

The props argument accepts the following fields:

(*) !! YET NOT SUPPORTED !! , but when supported, there are two major ways of providing the schema information to the constructor:

1. Provide typeDefs and resolvers and omit the schema, in this case @apollo-waterline/server will construct the GraphQLSchema instance using buildFederatedSchema from @apollo/federation.
2. Provide the schema directly and omit typeDefs and resolvers. We recommend to use buildFederatedSchema to be able to use it in an API Gateway with Apollo Gateway

(**) Notice that the req argument is an object of the shape { request, response, connection } which either carries a request: Request property (when it's a Query/Mutation resolver), response: Response property (when it's a Query/Mutation resolver), or a connection: SubscriptionOptions property (when it's a Subscription resolver). Request is imported from Express.js. Response is imported from Express.js aswell. SubscriptionOptions is from the graphql-subscriptions package. SubscriptionOptions are getting the connectionParams automatically injected under SubscriptionOptions.context.[CONNECTION_PARAMETER_NAME]

bootOpts

The bootOpts object has the following fields:

Additionally, the options object exposes these apollo-server options: