(core) - Expose client.subscription shortcut method (#838)

* Export client.subscription shortcut

* Update packages/core/src/client.ts

* Update docs/api/core.md

* Apply suggestions from code review

Co-authored-by: Phil Plückthun <phil@kitten.sh>

.changeset/hot-dryers-drive.md

@@ -0,0 +1,5 @@
+---
+'@urql/core': minor
+---
+
+Expose a `client.subscription`shortcut method, similar to `client.query` and `client.mutation`

docs/advanced/subscriptions.md

@@ -48,10 +48,7 @@ package](https://github.com/apollographql/subscriptions-transport-ws).
 import { Client, defaultExchanges, subscriptionExchange } from 'urql';
 import { SubscriptionClient } from 'subscriptions-transport-ws';
 
-const subscriptionClient = new SubscriptionClient(
-  'wss://localhost/graphql',
-  { reconnect: true }
-);
+const subscriptionClient = new SubscriptionClient('wss://localhost/graphql', { reconnect: true });
 
 const client = new Client({
   url: '/graphql',
@@ -132,3 +129,29 @@ As we can see, the `result.data` is being updated and transformed by
 the `handleSubscription` function. This works over time, so as
 new messages come in, we will append them to the list of previous
 messages.
+
+## One-off Subscriptions
+
+Whe you're using subscriptions directly without `urql`'s framework bindings, you can use the `Client`'s `subscription` method for one-off subscriptions. This method is similar to the ones for mutations and subscriptions [that we've seen before on the "Core Package" page.](../concepts/core-package.md#one-off-queries-and-mutations)
+
+This method will always [returns a Wonka stream](../concepts/stream-patterns.md#the-wonka-library) and doesn't have a `.toPromise()` shortcut method, since promises won't return the multiple values that a subscription may deliver. Let's convert the above example to one without framework code, as we may use subscriptions in a Node.js environment.
+
+```js
+import { pipe, subscribe } from 'wonka';
+
+const newMessages = `
+  subscription MessageSub {
+    newMessages {
+      id
+      from
+      text
+    }
+  }
+`;
+
+const { unsubscribe } = pipe(
+  client.subscription(MessageSub),
+  subscribe(result => {
+    console.log(result); // { data: ... }
+  })
+);

docs/api/core.md

@@ -53,7 +53,7 @@ repeatedly in the interval you pass.
 ### client.executeSubscription
 
 This is functionally the same as `client.executeQuery`, but creates operations for subscriptions
-instead, with `operationName` set to `'mutation'`.
+instead, with `operationName` set to `'subscription'`.
 
 ### client.executeMutation
 
@@ -103,6 +103,12 @@ This is similar to [`client.query`](#clientquery), but dispatches mutations inst
 [Read more about how to use this API on the "Core Package"
 page.](../concepts/core-package.md#one-off-queries-and-mutations)
 
+### client.subscription
+
+This is similar to [`client.query`](#clientquery), but does not provide a `toPromise()` helper method on the streams it returns.
+
+[Read more about how to use this API on the "Subscriptions" page.](../advanced/subscriptions.md)
+
 #### client.reexecuteOperation
 
 This method is commonly used in _Exchanges_ to reexecute an [`Operation`](#operation) on the

packages/core/src/client.ts

@@ -309,6 +309,14 @@ export class Client {
     return response$;
   };
 
+  subscription<Data = any, Variables extends object = {}>(
+    query: DocumentNode | string,
+    variables?: Variables,
+    context?: Partial<OperationContext>
+  ): Source<OperationResult<Data>> {
+    return this.executeSubscription(createRequest(query, variables), context);
+  }
+
   executeSubscription = (
     query: GraphQLRequest,
     opts?: Partial<OperationContext>