feat(schema): add subscriptionType (#1191)

closes #447

Author: Jason Kuhrt

package.json

@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@nexus/logger": "^0.2.0",
-    "@nexus/schema": "^0.14.0",
+    "@nexus/schema": "^0.15.0-next.1",
     "@types/express": "^4.17.2",
     "@types/node-fetch": "^2.5.5",
     "@types/prompts": "^2.0.3",

src/lib/nexus-schema-stateful/stateful-nexus-schema.ts

@@ -1,7 +1,7 @@
 import * as NexusSchema from '@nexus/schema'
 import * as GraphQL from 'graphql'
-import * as CustomTypes from './custom-types'
 import * as Scalars from '../scalars'
+import * as CustomTypes from './custom-types'
 
 // todo use this as return type of constructor
 export interface StatefulNexusSchema {
@@ -16,6 +16,7 @@ export interface StatefulNexusSchema {
 export interface NexusSchemaStatefulBuilders {
   queryType: typeof NexusSchema.queryType
   mutationType: typeof NexusSchema.mutationType
+  subscriptionType: typeof NexusSchema.subscriptionType
   objectType: ReturnType<typeof createNexusSchemaStateful>['builders']['objectType']
   enumType: ReturnType<typeof createNexusSchemaStateful>['builders']['enumType']
   scalarType: ReturnType<typeof createNexusSchemaStateful>['builders']['scalarType']
@@ -80,6 +81,9 @@ type NexusSchemaTypeDef =
   | NexusSchema.core.NexusExtendInputTypeDef<any>
   | NexusSchema.core.NexusExtendTypeDef<any>
 
+/**
+ * Create an instance of Stateful Nexus Schema
+ */
 export function createNexusSchemaStateful() {
   const state: StatefulNexusSchema['state'] = {
     types: [],
@@ -145,6 +149,12 @@ export function createNexusSchemaStateful() {
     return typeDef
   }
 
+  const subscriptionType: typeof NexusSchema.subscriptionType = (config) => {
+    const typeDef = NexusSchema.subscriptionType(config)
+    state.types.push(typeDef)
+    return typeDef
+  }
+
   const extendType: typeof NexusSchema.extendType = (config) => {
     const typeDef = NexusSchema.extendType(config)
     state.types.push(typeDef)
@@ -172,17 +182,23 @@ export function createNexusSchemaStateful() {
   }
 
   const arg = NexusSchema.arg
+
   const intArg = NexusSchema.intArg
+
   const stringArg = NexusSchema.stringArg
+
   const idArg = NexusSchema.idArg
+
   const floatArg = NexusSchema.floatArg
+
   const booleanArg = NexusSchema.booleanArg
 
   return {
     state: state,
     builders: {
       queryType,
       mutationType,
+      subscriptionType,
       objectType,
       inputObjectType,
       unionType,

website/content/04-api/01-nexus/01-schema.mdx

@@ -557,7 +557,45 @@ Refer to `objectType`. This is a shorthand where `config.name` is assigned `Muta
 
 ## `subscriptionType`
 
-Not implemented, please see [#447](https://github.com/graphql-nexus/nexus/issues/447).
+[GraphQL Spec](https://spec.graphql.org/June2018/#sec-Subscription-Operation-Definitions)
+
+Similar to [`objectType`](#objecttype). However, there are a few differences with regard to field configuration. Here is an overview. For details see below.
+
+```ts
+schema.subscriptionType({
+  // rootTyping          // There is no rootTyping configuration
+  definition(t) {
+    t.field({            // This and all other field builders...
+      subscribe() {}     // ... uniquely have a subscribe method
+      resolve(event) {}  // ... have an adjustment to the Backing type
+    })
+  }
+})
+```
+
+### Signature
+
+<!-- prettier-ignore -->
+```ts
+(config: {
+  definition:        SubscriptionDefinitionBlock
+  description?:      string
+  nonNullDefaults?:  NonNullConfig
+}) => NexusInputObjectType
+```
+
+### Field Configuration
+
+Extends field configurations of those found in [`objectType`](#objecttype) like so:
+
+```ts
+subscribe(root, args, ctx, info): MaybePromise<AsyncIterator<...>>
+resolve(event, args, ctx, info): MaybePromise<...>
+```
+
+- `subscribe` Called once when the initial subscription request is sent by the client. It must return an `AsyncIterator`. The values emitted via it flow into the peer method `resolve`. The point of this method is to setup the data link between your streaming data source and a client subscription. It is not concerned with shaping the data coming off the streaming data source into something comforming to the GraphQL type assigned to the field. that is the job of the peer method `resolve`.
+
+- `resolve` Called for every value emitted by the `AsyncIterator` returned by `subscribe`. The value is the first argument to `resolve`, replacing the backing data parameter that is usuaully passed there. The point of this method is to receive the raw event data from your data source and make it conform to the GraphQL type assigned to the field––just like all resolvers do. The only difference is that the backing data aspect.
 
 ## `inputObjectType`
 
@@ -570,9 +608,10 @@ Defines an object which can be passed as an input value.
 <!-- prettier-ignore -->
 ```ts
 (config: {
+  name:              string
+  definition:        InputObjectDefinitionBlock
   description?:      string
   nonNullDefaults?:  NonNullConfig
-  definition:        InputObjectDefinitionBlock
 }) => NexusInputObjectType
 ```
 

website/content/06-components-standalone/01-schema/01-api/10-api-queryField.mdx

@@ -5,7 +5,7 @@ codeStyle: true
 
 ## queryField
 
-Often times you want to split up query fields into different domains of your application, and like [`mutationField`](api-mutationField) are another one of the most common use-cases for `extendType`. `queryField` exists as a shorthand for this common case:
+Often times you want to split up query fields into different domains of your application, and like [`mutationField`](/components-standalone/schema/api/api-mutationField) are another one of the most common use-cases for `extendType`. `queryField` exists as a shorthand for this common case:
 
 ```ts
 import { stringArg } from '@nexus/schema'

yarn.lock

@@ -529,10 +529,10 @@
     lodash "^4.17.15"
     strip-ansi "^6.0.0"
 
-"@nexus/schema@^0.14.0":
-  version "0.14.0"
-  resolved "https://registry.yarnpkg.com/@nexus/schema/-/schema-0.14.0.tgz#3242f4d02ec9458914deb638b434bcfbd5888d2e"
-  integrity sha512-niJFcOm1F2s3kwj+j3ips4sIIJaTNh5Auq+zcHwOsRBqSYsFJnA/8QUKMb1wjVIEqS+Jl71Sj4xFdg3/njlm9A==
+"@nexus/schema@^0.15.0-next.1":
+  version "0.15.0-next.1"
+  resolved "https://registry.yarnpkg.com/@nexus/schema/-/schema-0.15.0-next.1.tgz#39def5322a6cc821914a9f2dee40e1333257e9f8"
+  integrity sha512-PBml7hY5DgqTEEEk9jwczUvBcyMtX9HKR8qfbU1tc+kZ+8uRodnSOatMqN6Haz6QuZhkZBLw4gh2gnpOUYWjPw==
   dependencies:
     iterall "^1.2.2"
     tslib "^1.9.3"