@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:

Key	Type	Default	Note
typeDefs	String or Function or DocumentNode or array of previous	null	Contains GraphQL type definitions in SDL or file path to type definitions (required if schema is not provided *)
resolvers	Object	null	Contains resolvers for the fields specified in typeDefs (required if schema is not provided *)
resolverValidationOptions	Object	null	Object which controls the resolver validation behaviour (see "Generating a schema") for more information
schema	Object	null	An instance of GraphQLSchema (required if typeDefs and resolvers are not provided *)
mocks	Object or Boolean	null	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.
context	Object or Function	{}	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 **
schemaDirectives	Object	null	Apollo Server schema directives that allow for transforming schema types, fields, and arguments
middlewares	array of Middleware	[]	A list of GraphQLMiddleware middleware.

(*) !! 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:

Key	Type	Default	Note
cors	Object	null	Contains configuration options for cors
tracing	Boolean or TracingOptions	'http-header'	Indicates whether Apollo Tracing should be enabled or disabled for your server (if a string is provided, accepted values are: 'enabled', 'disabled', 'http-header')
port	Number or String	4000	Determines the port your server will be listening on (note that you can also specify the port by setting the PORT environment variable)
endpoint	String	'/'	Defines the HTTP endpoint of your server
subscriptions	Object or String or false	'/'	Defines the subscriptions (websocket) endpoint for your server; accepts an object with subscription server options path, keepAlive, onConnect and onDisconnect; setting to false disables subscriptions completely
playground	String or false	'/'	Defines the endpoint where you can invoke the Playground; setting to false disables the playground endpoint
defaultPlaygroundQuery	String	undefined	Defines default query displayed in Playground.
uploads	UploadOptions or false or undefined	null	Provides information about upload limits; the object can have any combination of the following three keys: maxFieldSize, maxFileSize, maxFiles; each of these have values of type Number; setting to false disables file uploading
https	HttpsOptions or undefined	undefined	Enables HTTPS support with a key/cert
getEndpoint	String or Boolean	false	Adds a graphql HTTP GET endpoint to your server (defaults to endpoint if true). Used for leveraging CDN level caching.
deduplicator	Boolean	true	Enables graphql-deduplicator. Once enabled sending the header X-GraphQL-Deduplicate will deduplicate the data.
bodyParserOptions	BodyParserJSONOptions	BodyParserJSONOptions Defaults	Allows pass through of body-parser options

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

Key	Type	Note
cacheControl	Boolean	Enable extension that returns Cache Control data in the response
formatError	Number	A function to apply to every error before sending the response to clients. See [API Reference: apollo-server
](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#parameters). Please beware, that if you override this, requestId and code on errors won't automatically be propagated to your @apollo-waterline/server server
logFunction	LogFunction	A function called for logging events such as execution times
rootValue	any	RootValue passed to GraphQL execution
validationRules	Array of functions	Additional GraphQL validation rules to be applied to client-specified queries
fieldResolver	GraphQLFieldResolver	Specify a custom default field resolver function
formatParams	Function	A function applied to each query in a batch to format parameters before execution
formatResponse	Function	A function applied to each response after execution
debug	boolean	Print additional debug logging if execution errors occur