(core) - Deprecate the "operationName" property and move to "kind"

.changeset/twenty-olives-applaud.md

@@ -0,0 +1,15 @@
+---
+'@urql/exchange-auth': patch
+'@urql/exchange-execute': patch
+'@urql/exchange-graphcache': patch
+'@urql/exchange-multipart-fetch': patch
+'@urql/exchange-persisted-fetch': patch
+'@urql/exchange-populate': patch
+'@urql/exchange-refocus': patch
+'@urql/exchange-retry': patch
+'@urql/exchange-suspense': patch
+'@urql/core': minor
+'urql': patch
+---
+
+Deprecate the "Operation.operationName" property in favor of "Operation.kind"

docs/advanced/testing.md

@@ -191,17 +191,15 @@ If you prefer to have more control on when the new data is arriving you can use
 Here's an example of testing a list component which uses a subscription.
 
 ```tsx
+import { OperationContext, makeOperation } from '@urql/core';
+
 const mockClient = {
   executeSubscription: jest.fn(query =>
     pipe(
       interval(200),
       map((i: number) => ({
         // To mock a full result, we need to pass a mock operation back as well
-        operation: {
-          operationName: 'subscription,
-          context: {},
-          ...query,
-        },
+        operation: makeOperation('subscription', query, {} as OperationContext),
         data: { posts: { id: i, title: 'Post title', content: 'This is a post' } },
       }))
     )

docs/api/core.md

@@ -37,7 +37,7 @@ Accepts a [`GraphQLRequest`](#graphqlrequest) and optionally `Partial<OperationC
 [`Source<OperationResult>`](#operationresult) — a stream of query results that can be subscribed to.
 
 Internally, subscribing to the returned source will create an [`Operation`](#operation), with
-`operationName` set to `'query'`, and dispatch it on the
+`kind` set to `'query'`, and dispatch it on the
 exchanges pipeline. If no subscribers are listening to this operation anymore and unsubscribe from
 the query sources, the `Client` will dispatch a "teardown" operation.
 
@@ -53,12 +53,12 @@ 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 `'subscription'`.
+instead, with `kind` set to `'subscription'`.
 
 ### client.executeMutation
 
 This is functionally the same as `client.executeQuery`, but creates operations for mutations
-instead, with `operationName` set to `'mutation'`.
+instead, with `kind` set to `'mutation'`.
 
 A mutation source is always guaranteed to only respond with a single [`OperationResult`](#operationresult) and then complete.
 
@@ -170,14 +170,10 @@ received.
 The input for every exchange that informs GraphQL requests.
 It extends the [GraphQLRequest](#graphqlrequest) type and contains these additional properties:
 
-| Prop            | Type               | Description                                   |
-| --------------- | ------------------ | --------------------------------------------- |
-| `operationName` | `OperationType`    | The type of GraphQL operation being executed. |
-| `context`       | `OperationContext` | Additional metadata passed to exchange.       |
-
-> **Note:** In `urql` the `operationName` on the `Operation` isn't the actual name of an operation
-> and derived from the GraphQL `DocumentNode`, but instead a type of operation, like `'query'` or
-> `'teardown'`
+| Prop      | Type               | Description                                   |
+| --------- | ------------------ | --------------------------------------------- |
+| `kind`    | `OperationType`    | The type of GraphQL operation being executed. |
+| `context` | `OperationContext` | Additional metadata passed to exchange.       |
 
 ### RequestPolicy
 

docs/concepts/exchanges.md

@@ -190,11 +190,11 @@ import { pipe, filter, merge, share } from 'wonka';
   // <-- The ExchangeIO function (inline)
   const queries = pipe(
     operations$,
-    filter(op => op.operationName === 'query')
+    filter(op => op.kind === 'query')
   );
   const others = pipe(
     operations$,
-    filter(op => op.operationName !== 'query')
+    filter(op => op.kind !== 'query')
   );
   return forward(merge([queries, others]));
 };
@@ -205,11 +205,11 @@ import { pipe, filter, merge, share } from 'wonka';
   const shared = pipe(operations$, share);
   const queries = pipe(
     shared,
-    filter(op => op.operationName === 'query')
+    filter(op => op.kind === 'query')
   );
   const others = pipe(
     shared,
-    filter(op => op.operationName !== 'query')
+    filter(op => op.kind !== 'query')
   );
   return forward(merge([queries, others]));
 };
@@ -221,7 +221,7 @@ import { pipe, filter, merge, share } from 'wonka';
   pipe(
     operations$,
     map(op => {
-      if (op.operationName === 'query') {
+      if (op.kind === 'query') {
         /* ... */
       } else {
         /* ... */
@@ -252,7 +252,7 @@ import { pipe, filter, merge, share } from 'wonka';
   // This doesn't handle operations that aren't queries
   const queries = pipe(
     operations$,
-    filter(op => op.operationName === 'query')
+    filter(op => op.kind === 'query')
   );
   return forward(queries);
 };
@@ -262,11 +262,11 @@ import { pipe, filter, merge, share } from 'wonka';
   const shared = pipe(operations$, share);
   const queries = pipe(
     shared,
-    filter(op => op.operationName === 'query')
+    filter(op => op.kind === 'query')
   );
   const rest = pipe(
     shared,
-    filter(op => op.operationName !== 'query')
+    filter(op => op.kind !== 'query')
   );
   return forward(merge([queries, rest]));
 };

exchanges/auth/src/authExchange.ts

@@ -130,14 +130,14 @@ export function authExchange<T>({
       const teardownOps$ = pipe(
         sharedOps$,
         filter((operation: Operation) => {
-          return operation.operationName === 'teardown';
+          return operation.kind === 'teardown';
         })
       );
 
       const pendingOps$ = pipe(
         sharedOps$,
         filter((operation: Operation) => {
-          return operation.operationName !== 'teardown';
+          return operation.kind !== 'teardown';
         })
       );
 
@@ -160,9 +160,7 @@ export function authExchange<T>({
               const teardown$ = pipe(
                 sharedOps$,
                 filter(op => {
-                  return (
-                    op.operationName === 'teardown' && op.key === operation.key
-                  );
+                  return op.kind === 'teardown' && op.key === operation.key;
                 })
               );
 

exchanges/execute/src/execute.test.ts

@@ -1,7 +1,7 @@
 jest.mock('graphql');
 
 import { fetchExchange } from 'urql';
-import { executeExchange, getOperationName } from './execute';
+import { executeExchange } from './execute';
 import { execute, print } from 'graphql';
 import {
   pipe,
@@ -13,8 +13,9 @@ import {
   Source,
 } from 'wonka';
 import { mocked } from 'ts-jest/utils';
+import { getOperationName } from '@urql/core/utils';
 import { queryOperation } from '@urql/core/test-utils';
-import { makeErrorResult } from '@urql/core';
+import { makeErrorResult, makeOperation } from '@urql/core';
 import { Client } from '@urql/core/client';
 import { OperationResult } from '@urql/core/types';
 
@@ -179,10 +180,11 @@ describe('on thrown error', () => {
 });
 
 describe('on unsupported operation', () => {
-  const operation = {
-    ...queryOperation,
-    operationName: 'teardown',
-  } as const;
+  const operation = makeOperation(
+    'teardown',
+    queryOperation,
+    queryOperation.context
+  );
 
   it('returns operation result', async () => {
     const { source, next } = makeSubject<any>();

exchanges/execute/src/execute.ts

@@ -10,24 +10,14 @@ import {
 } from 'wonka';
 
 import {
-  DocumentNode,
-  Kind,
   GraphQLSchema,
   GraphQLFieldResolver,
   GraphQLTypeResolver,
   execute,
 } from 'graphql';
 
 import { Exchange, makeResult, makeErrorResult, Operation } from '@urql/core';
-
-export const getOperationName = (query: DocumentNode): string | undefined => {
-  for (let i = 0, l = query.definitions.length; i < l; i++) {
-    const node = query.definitions[i];
-    if (node.kind === Kind.OPERATION_DEFINITION && node.name) {
-      return node.name.value;
-    }
-  }
-};
+import { getOperationName } from '@urql/core/utils';
 
 interface ExecuteExchangeArgs {
   schema: GraphQLSchema;
@@ -51,16 +41,13 @@ export const executeExchange = ({
     const executedOps$ = pipe(
       sharedOps$,
       filter((operation: Operation) => {
-        return (
-          operation.operationName === 'query' ||
-          operation.operationName === 'mutation'
-        );
+        return operation.kind === 'query' || operation.kind === 'mutation';
       }),
       mergeMap((operation: Operation) => {
         const { key } = operation;
         const teardown$ = pipe(
           sharedOps$,
-          filter(op => op.operationName === 'teardown' && op.key === key)
+          filter(op => op.kind === 'teardown' && op.key === key)
         );
 
         const calculatedContext =
@@ -99,10 +86,7 @@ export const executeExchange = ({
     const forwardedOps$ = pipe(
       sharedOps$,
       filter((operation: Operation) => {
-        return (
-          operation.operationName !== 'query' &&
-          operation.operationName !== 'mutation'
-        );
+        return operation.kind !== 'query' && operation.kind !== 'mutation';
       }),
       forward
     );

exchanges/graphcache/src/cacheExchange.test.ts

@@ -775,7 +775,7 @@ describe('optimistic updates', () => {
 
     pipe(
       cacheExchange({ optimistic })({ forward, client, dispatchDebug })(ops$),
-      filter(x => x.operation.operationName === 'mutation'),
+      filter(x => x.operation.kind === 'mutation'),
       tap(result),
       publish
     );
@@ -862,7 +862,7 @@ describe('optimistic updates', () => {
       pipe(
         ops$,
         delay(1),
-        filter(x => x.operationName !== 'mutation'),
+        filter(x => x.kind !== 'mutation'),
         map(response)
       );
 
@@ -1518,7 +1518,7 @@ describe('commutativity', () => {
     const forward = (ops$: Source<Operation>): Source<OperationResult> =>
       pipe(
         ops$,
-        filter(op => op.operationName !== 'teardown'),
+        filter(op => op.kind !== 'teardown'),
         mergeMap(result)
       );
 
@@ -1597,7 +1597,7 @@ describe('commutativity', () => {
     pipe(
       cacheExchange({ optimistic })({ forward, client, dispatchDebug })(ops$),
       tap(result => {
-        if (result.operation.operationName === 'query') {
+        if (result.operation.kind === 'query') {
           data = result.data;
         }
       }),
@@ -1691,7 +1691,7 @@ describe('commutativity', () => {
     pipe(
       cacheExchange()({ forward, client, dispatchDebug })(ops$),
       tap(result => {
-        if (result.operation.operationName === 'query') {
+        if (result.operation.kind === 'query') {
           data = result.data;
         }
       }),
@@ -1803,7 +1803,7 @@ describe('commutativity', () => {
     pipe(
       cacheExchange({ optimistic })({ forward, client, dispatchDebug })(ops$),
       tap(result => {
-        if (result.operation.operationName === 'query') {
+        if (result.operation.kind === 'query') {
           data = result.data;
         }
       }),
@@ -1888,7 +1888,7 @@ describe('commutativity', () => {
     pipe(
       cacheExchange()({ forward, client, dispatchDebug })(ops$),
       tap(result => {
-        if (result.operation.operationName === 'query') {
+        if (result.operation.kind === 'query') {
           data = result.data;
         }
       }),
@@ -1979,7 +1979,7 @@ describe('commutativity', () => {
     pipe(
       cacheExchange()({ forward, client, dispatchDebug })(ops$),
       tap(result => {
-        if (result.operation.operationName === 'query') {
+        if (result.operation.kind === 'query') {
           data = result.data;
         }
       }),

exchanges/graphcache/src/cacheExchange.ts

@@ -127,16 +127,16 @@ export const cacheExchange = (opts?: CacheExchangeOpts): Exchange => ({
 
   // This registers queries with the data layer to ensure commutativity
   const prepareForwardedOperation = (operation: Operation) => {
-    if (operation.operationName === 'query') {
+    if (operation.kind === 'query') {
       // Pre-reserve the position of the result layer
       reserveLayer(store.data, operation.key);
-    } else if (operation.operationName === 'teardown') {
+    } else if (operation.kind === 'teardown') {
       // Delete reference to operation if any exists to release it
       ops.delete(operation.key);
       // Mark operation layer as done
       noopDataState(store.data, operation.key);
     } else if (
-      operation.operationName === 'mutation' &&
+      operation.kind === 'mutation' &&
       operation.context.requestPolicy !== 'network-only'
     ) {
       // This executes an optimistic update for mutations and registers it if necessary
@@ -207,7 +207,7 @@ export const cacheExchange = (opts?: CacheExchangeOpts): Exchange => ({
     const { operation, error, extensions } = result;
     const { key } = operation;
 
-    if (operation.operationName === 'mutation') {
+    if (operation.kind === 'mutation') {
       // Collect previous dependencies that have been written for optimistic updates
       const dependencies = optimisticKeysToDependencies.get(key);
       collectPendingOperations(pendingOperations, dependencies);
@@ -226,7 +226,7 @@ export const cacheExchange = (opts?: CacheExchangeOpts): Exchange => ({
 
       const queryResult = query(store, operation, result.data);
       result.data = queryResult.data;
-      if (operation.operationName === 'query') {
+      if (operation.kind === 'query') {
         // Collect the query's dependencies for future pending operation updates
         queryDependencies = queryResult.dependencies;
         collectPendingOperations(pendingOperations, queryDependencies);
@@ -269,8 +269,7 @@ export const cacheExchange = (opts?: CacheExchangeOpts): Exchange => ({
       inputOps$,
       filter(op => {
         return (
-          op.operationName === 'query' &&
-          op.context.requestPolicy !== 'network-only'
+          op.kind === 'query' && op.context.requestPolicy !== 'network-only'
         );
       }),
       map(operationResultFromCache),
@@ -281,8 +280,7 @@ export const cacheExchange = (opts?: CacheExchangeOpts): Exchange => ({
       inputOps$,
       filter(op => {
         return (
-          op.operationName !== 'query' ||
-          op.context.requestPolicy === 'network-only'
+          op.kind !== 'query' || op.context.requestPolicy === 'network-only'
         );
       })
     );