Subscriptions (#36)

* subscriptions

* subs docs

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## main
 
 - Disallow inferring input objects. It's not worth the complexity right now.
+- Add support for subscriptions.
 
 ## 0.12.0
 

README.md

@@ -121,7 +121,7 @@ ResGraph lets you build _implementation first_ GraphQL servers, where your types
 
 - [x] Query
 - [x] Mutations
-- [ ] Subscriptions
+- [x] Subscriptions
 - [x] Context
 - [x] Object types
 - [x] Input types
@@ -130,7 +130,7 @@ ResGraph lets you build _implementation first_ GraphQL servers, where your types
 - [x] Unions
 - [x] Custom scalars (including custom serializers/parsers)
 - [ ] Directives
-- [ ] Relay helpers (coming very soon)
+- [x] Relay helpers (coming very soon)
 
 ## Development notes
 

docs/docs/subscriptions.md

@@ -4,4 +4,45 @@ sidebar_position: 9
 
 # Subscriptions
 
-Subscriptions are not yet a thing in ResGraph, but they will be eventually.
+You can add a subscription to your schema by defining a `subscription` type and then attaching resolvers to it. All subscription resolvers _must return an [`AsyncIterator.t`](https://rescript-lang.org/docs/manual/latest/api/core/asynciterator)_ with a valid GraphQL type.
+
+Let's look at an example:
+
+```rescript
+// Define the subscription type
+@gql.type
+type subscription
+
+let wait = ms => {
+  Promise.make((resolve, _) => {
+    let _ = setTimeout(() => resolve(), ms)
+  })
+}
+
+@gql.field
+let countdown = (_: subscription, ~from: int) => {
+  let countdown = ref(from)
+  let iterator = AsyncIterator.make(async () => {
+    await wait(500)
+    let current = countdown.contents
+    countdown := current - 1
+
+    if current > 0 {
+      AsyncIterator.value(current)
+    } else {
+      AsyncIterator.done(~finalValue=current)
+    }
+  })
+
+  iterator
+}
+
+```
+
+This would produce the following schema:
+
+```graphql
+type Subscription {
+  countdown(from: Int!): Int!
+}
+```

example/src/schema/GraphQLSchema.res

@@ -63,3 +63,47 @@ let shop = (_: query, ~input: findShopInput) => {
   | ByCoordinates(_) => Some("Coordinates")
   }
 }
+
+@gql.type
+type subscription
+
+let wait = ms => {
+  Promise.make((resolve, _) => {
+    let _ = setTimeout(() => resolve(), ms)
+  })
+}
+
+let makeAsyncIterator: (unit => promise<AsyncIterator.value<'value>>) => AsyncIterator.t<
+  'value,
+> = %raw(`function makeAsyncIterator(next) {
+  return {
+    next,
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  }
+}`)
+
+@gql.field
+let countdown = (_: subscription) => {
+  let countdown = ref(10)
+  let iterator = makeAsyncIterator(async () => {
+    await wait(500)
+    let current = countdown.contents
+    countdown := current - 1
+
+    if current > 0 {
+      {
+        AsyncIterator.done: false,
+        value: Some(current),
+      }
+    } else {
+      {
+        AsyncIterator.done: true,
+        value: Some(current),
+      }
+    }
+  })
+
+  iterator
+}