Docs and typing improvements

Signed-off-by: Alan Cha <[email protected]>

Author: Alan-Cha

docs/tutorials/watson.md

@@ -15,13 +15,13 @@ The following code shows all that's needed to create and run a GraphQL wrapper a
 ```javascript
 const express = require('express')
 const graphqlHTTP = require('express-graphql')
-const OTG = require('openapi-to-graphql')
+const OtG = require('openapi-to-graphql')
 const bodyParser = require('body-parser')
 
 async function startServer () {
   // use OpenAPI-to-GraphQL to create a GraphQL schema:
   const oas = require('path/to/language-translator-v2.json')
-  const {schema} = await OTG.createGraphQLSchema(oas)
+  const {schema} = await OtG.createGraphQLSchema(oas)
 
   // setup Express.js app and serve the schema:
   const app = express()

packages/openapi-to-graphql/README.md

@@ -160,9 +160,9 @@ Schema options:
 
 - `genericPayloadArgName` (type: `boolean`, default: `false`): Set the default argument name for the payload of a mutation to `requestBody`. Otherwise, the name will default to the camelCased pathname.
 
-- `simpleNames` (type: `boolean`, default: `false`): By default, field names are sanitized to conform with GraphQL conventions, i.e. types should be in PascalCase, fields should be in camelCase, and enum values should be in ALL_CAPS. This option will prevent OTG from enforcing camelCase field names and PascalCase type names, only removing illegal characters and staying as true to the provided names in the OAS as possible. 
+- `simpleNames` (type: `boolean`, default: `false`): By default, field names are sanitized to conform with GraphQL conventions, i.e. types should be in PascalCase, fields should be in camelCase, and enum values should be in ALL_CAPS. This option will prevent OpenAPI-to-GraphQL from enforcing camelCase field names and PascalCase type names, only removing illegal characters and staying as true to the provided names in the OAS as possible. 
 
-- `singularNames` (type: `boolean`, default: `false`): Experimental feature that will try to create more meaningful names from the operation path than the response object by leveraging common conventions. For example, given the operation `GET /users/{userId}/car`, OtG will create a `Query` field `userCar`. Note that because `users` is followed by the parameter `userId`, it insinuates that this operation will get the car that belongs to a singular user. Hence, the name `userCar` is more fitting than `usersCar` so the pluralizing 's' is dropped. This option will also consider irregular plural forms.
+- `singularNames` (type: `boolean`, default: `false`): Experimental feature that will try to create more meaningful names from the operation path than the response object by leveraging common conventions. For example, given the operation `GET /users/{userId}/car`, OpenAPI-to-GraphQL will create a `Query` field `userCar`. Note that because `users` is followed by the parameter `userId`, it insinuates that this operation will get the car that belongs to a singular user. Hence, the name `userCar` is more fitting than `usersCar` so the pluralizing 's' is dropped. This option will also consider irregular plural forms.
 
 - `createSubscriptionsFromCallbacks` (type: `boolean`, default: `false`): Generates subscription fields from [callback objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#CallbackObject). The keys ([runtime expressions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#runtimeExpression)) of the callback objects will be interpolated as the topic of a publish/subscription connection using [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions). Read the [doc](./docs/subscriptions.md) for explanations and examples regarding its usage.
 

packages/openapi-to-graphql/lib/index.js

@@ -22,205 +22,14 @@ export declare type Report = {
 export declare type ConnectOptions = {
     [key: string]: boolean | number | string;
 };
-export declare type Options = {
-    /**
-     * Adhere to the OAS as closely as possible. If set to true, any deviation
-     * from the OAS will lead OpenAPI-to-GraphQL to throw.
-     */
-    strict?: boolean;
-    /**
-     * Field names can only be sanitized operationIds
-     *
-     * By default, query field names are based on the return type type name and
-     * mutation field names are based on the operationId, which may be generated
-     * if it does not exist.
-     *
-     * This option forces OpenAPI-to-GraphQL to only create field names based on the
-     * operationId.
-     */
-    operationIdFieldNames?: boolean;
-    /**
-     * Under certain circumstances (such as response code 204), some RESTful
-     * operations should not return any data. However, GraphQL objects must have
-     * a data structure. Normally, these operations would be ignored but for the
-     * sake of completeness, the following option will give these operations a
-     * placeholder data structure. Even though the data structure will not have
-     * any practical use, at least the operations will show up in the schema.
-     */
-    fillEmptyResponses?: boolean;
-    /**
-     * Auto-generate a 'limit' argument for all fields that return lists of
-     * objects, including ones produced by links
-     *
-     * Allows to constrain the return size of lists of objects
-     *
-     * Returns the first n number of elements in the list
-     */
-    addLimitArgument?: boolean;
-    /**
-     * If a schema is of type string and has format UUID, it will be translated
-     * into a GraphQL ID type. To allow for more customzation, this option allows
-     * users to specify other formats that should be interpreted as ID types.
-     */
-    idFormats?: string[];
-    /**
-     * Allows to define the root operation type (Query or Mutation type) of any
-     * OAS operation explicitly.
-     *
-     * OtG will by default make all GET operations Query fields and all other
-     * operations into Mutation fields.
-     *
-     * The field is identifed first by the title of the OAS, then the path of the
-     * operation, and lastly the method of the operation.
-     */
-    selectQueryOrMutationField?: selectQueryOrMutationFieldType;
-    /**
-     * Sets argument name for the payload of a mutation to 'requestBody'
-     */
-    genericPayloadArgName?: boolean;
-    /**
-     * By default, field names are sanitized to conform with GraphQL conventions,
-     * i.e. types should be in PascalCase, fields should be in camelCase, and
-     * enum values should be in ALL_CAPS.
-     *
-     * This option will prevent OtG from enforcing camelCase field names and
-     * PascalCase type names, only removing illegal characters and staying as true
-     * to the provided names in the OAS as possible.
-     */
-    simpleNames?: boolean;
-    /**
-     * Experimental feature that will try to create more meaningful names from
-     * the operation path than the response object by leveraging common
-     * conventions.
-     *
-     * For example, given the operation 'GET /users/{userId}/car', OtG will
-     * create a Query field 'userCar'. Note that because 'users' is followed by
-     * the parameter 'userId', it insinuates that this operation will get the car
-     * that belongs to a singular user. Hence, the name 'userCar' is more fitting
-     * than 'usersCar' so the pluralizing 's' is dropped.
-     *
-     * This option will also consider irregular plural forms.
-     */
-    singularNames?: boolean;
-    /**
-     * Allow to generate subscription fields from callback objects in the OAS.
-     *
-     * The keys (runtime expressions) of the callback object will be interpolated
-     * as the topic of publish/subscription connection.
-     */
-    createSubscriptionsFromCallbacks?: boolean;
-    /**
-     * Custom headers to send with every request made by a resolve function.
-     */
-    headers?: {
-        [key: string]: string;
-    };
-    /**
-     * Custom query parameters to send with every reqeust by a resolve function.
-     */
-    qs?: {
-        [key: string]: string;
-    };
-    /**
-     * Allows to override or add options to the node's request object used to make
-     * calls to the API backend.
-     * e.g. Setup the web proxy to use.
-     */
-    requestOptions?: NodeRequest.OptionsWithUrl;
-    /**
-     * Allows to override or add options to the PubSub connect object used to make
-     * publish/subscribe to the API backend.
-     * e.g. Setup the web proxy to use.
-     */
-    connectOptions?: ConnectOptions;
-    /**
-     * Specifies the URL on which all paths will be based on.
-     * Overrides the server object in the OAS.
-     */
-    baseUrl?: string;
-    /**
-     * Allows to define custom resolvers for fields on the Query/Mutation root
-     * operation type.
-     *
-     * In other words, instead of resolving on an operation (REST call) defined in
-     * the OAS, the field will resolve on the custom resolver. Note that this will
-     * also affect the behavior of links.
-     *
-     * The field is identifed first by the title of the OAS, then the path of the
-     * operation, and lastly the method of the operation.
-     *
-     * Use cases include the resolution of complex relationships between types,
-     * implementing performance improvements like caching, or dealing with
-     * non-standard authentication requirements.
-     */
-    customResolvers?: {
-        [title: string]: {
-            [path: string]: {
-                [method: string]: ResolveFunction;
-            };
-        };
-    };
-    /**
-     * Allows to define custom resolvers and subscribe functions for fields on the
-     * Subscription root operation type.
-     *
-     * In other words, instead of resolving on an operation (REST call) defined in
-     * the OAS, the field will resolve on the custom resolver. Note that this will
-     * also affect the behavior of links.
-     *
-     * The field is identifed first by the title of the OAS, then the path of the
-     * operation, and lastly the method of the operation.
-     *
-     * Use cases include the resolution of complex relationships between types,
-     * implementing performance improvements like caching, or dealing with
-     * non-standard authentication requirements.
-     *
-     * Note: Subscription fields will only be generated if the
-     * createSubscriptionsFromCallbacks option is enabled.
-     */
-    customSubscriptionResolvers?: {
-        [title: string]: {
-            [path: string]: {
-                [method: string]: ResolveObject;
-            };
+export declare type OasTitlePathMethodObject<T> = {
+    [title: string]: {
+        [path: string]: {
+            [method: string]: T;
         };
     };
-    /**
-     * Determines whether OpenAPI-to-GraphQL should create viewers that allow users to pass
-     * basic auth and API key credentials.
-     */
-    viewer?: boolean;
-    /**
-     * JSON path to OAuth 2 token contained in GraphQL context. Tokens will per
-     * default be sent in "Authorization" header.
-     */
-    tokenJSONpath?: string;
-    /**
-     * Determines whether to send OAuth 2 token as query parameter instead of in
-     * header.
-     */
-    sendOAuthTokenInQuery?: boolean;
-    /**
-     * The error extensions is part of the GraphQLErrors that will be returned if
-     * the query cannot be fulfilled. It provides information about the failed
-     * REST call(e.g. the method, path, status code, response
-     * headers, and response body). It can be useful for debugging but may
-     * unintentionally leak information.
-     *
-     * This option prevents the extensions from being created.
-     */
-    provideErrorExtensions?: boolean;
-    /**
-     * Appends a small statement to the end of field description that clarifies
-     * the operation that the field will trigger.
-     *
-     * Will affect query and mutation fields as well as fields created from links
-     *
-     * In the form of: 'Equivalent to {title of OAS} {method in ALL_CAPS} {path}'
-     * Will forgo the title is only one OAS is provided
-     */
-    equivalentToMessages?: boolean;
 };
+export declare type Options = Partial<InternalOptions>;
 export declare type InternalOptions = {
     /**
      * Adhere to the OAS as closely as possible. If set to true, any deviation
@@ -270,13 +79,13 @@ export declare type InternalOptions = {
      * Allows to define the root operation type (Query or Mutation type) of any
      * OAS operation explicitly.
      *
-     * OtG will by default make all GET operations Query fields and all other
+     * OpenAPI-to-GraphQL will by default make all GET operations Query fields and all other
      * operations into Mutation fields.
      *
      * The field is identifed first by the title of the OAS, then the path of the
      * operation, and lastly the method of the operation.
      */
-    selectQueryOrMutationField?: selectQueryOrMutationFieldType;
+    selectQueryOrMutationField?: OasTitlePathMethodObject<GraphQLOperationType>;
     /**
      * Sets argument name for the payload of a mutation to 'requestBody'
      */
@@ -286,7 +95,7 @@ export declare type InternalOptions = {
      * i.e. types should be in PascalCase, fields should be in camelCase, and
      * enum values should be in ALL_CAPS.
      *
-     * This option will prevent OtG from enforcing camelCase field names and
+     * This option will prevent OpenAPI-to-GraphQL from enforcing camelCase field names and
      * PascalCase type names, only removing illegal characters and staying as true
      * to the provided names in the OAS as possible.
      */
@@ -296,7 +105,7 @@ export declare type InternalOptions = {
      * the operation path than the response object by leveraging common
      * conventions.
      *
-     * For example, given the operation 'GET /users/{userId}/car', OtG will
+     * For example, given the operation 'GET /users/{userId}/car', OpenAPI-to-GraphQL will
      * create a Query field 'userCar'. Note that because 'users' is followed by
      * the parameter 'userId', it insinuates that this operation will get the car
      * that belongs to a singular user. Hence, the name 'userCar' is more fitting
@@ -356,13 +165,7 @@ export declare type InternalOptions = {
      * implementing performance improvements like caching, or dealing with
      * non-standard authentication requirements.
      */
-    customResolvers?: {
-        [title: string]: {
-            [path: string]: {
-                [method: string]: ResolveFunction;
-            };
-        };
-    };
+    customResolvers?: OasTitlePathMethodObject<ResolveFunction>;
     /**
      * Allows to define custom resolvers and subscribe functions for fields on the
      * Subscription root operation type.
@@ -381,13 +184,7 @@ export declare type InternalOptions = {
      * Note: Subscription fields will only be generated if the
      * createSubscriptionsFromCallbacks option is enabled.
      */
-    customSubscriptionResolvers?: {
-        [title: string]: {
-            [path: string]: {
-                [method: string]: ResolveObject;
-            };
-        };
-    };
+    customSubscriptionResolvers?: OasTitlePathMethodObject<ResolveObject>;
     /**
      * Determines whether OpenAPI-to-GraphQL should create viewers that allow users to pass
      * basic auth and API key credentials.
@@ -424,10 +221,3 @@ export declare type InternalOptions = {
      */
     equivalentToMessages: boolean;
 };
-export declare type selectQueryOrMutationFieldType = {
-    [title: string]: {
-        [path: string]: {
-            [method: string]: GraphQLOperationType;
-        };
-    };
-};

packages/openapi-to-graphql/lib/index.js.map

@@ -326,12 +326,8 @@ function createOrReuseUnion({
       types,
       resolveType: (source, context, info) => {
         const properties = Object.keys(source)
-
-        // Remove custom _openAPIToGraphQL property used to pass data
-        const otgIndex = properties.indexOf('_openAPIToGraphQL')
-        if (otgIndex !== -1) {
-          properties.splice(otgIndex, 1)
-        }
+          // Remove custom _openAPIToGraphQL property used to pass data
+          .filter(property => property !== '_openAPIToGraphQL')
 
         /**
          * Find appropriate member type
@@ -347,13 +343,9 @@ function createOrReuseUnion({
         return types.find(type => {
           const typeFields = Object.keys(type.getFields())
 
+          // The type should be a superset of the properties
           if (properties.length <= typeFields.length) {
-            for (let i = 0; i < properties.length; i++) {
-              if (!typeFields.includes(properties[i])) {
-                return false
-              }
-            }
-            return true
+            return properties.every(property => typeFields.includes(property))
           }
 
           return false