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

.changeset/twenty-olives-applaud.md

@@ -0,0 +1,20 @@
+---
+'@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`. This name was
+previously confusing as `operationName` was effectively referring to two different things. You can
+safely upgrade to this new version, however to mute all deprecation warnings you will have to
+**upgrade** all `urql` packages you use. If you have custom exchanges that spread operations, please
+use [the new `makeOperation` helper
+function](https://formidable.com/open-source/urql/docs/api/core/#makeoperation) instead.

docs/advanced/authentication.md

@@ -82,7 +82,7 @@ const getAuth = async ({ authState }) => {
   }
 
   return null;
-}
+};
 ```
 
 We check that the `authState` doesn't already exist (this indicates that it is the first time this exchange is executed and not an auth failure) and fetch the auth state from
@@ -104,7 +104,7 @@ const getAuth = async ({ authState, mutate }) => {
   }
 
   return null;
-}
+};
 ```
 
 ### Configuring `addAuthToOperation`
@@ -113,10 +113,9 @@ The purpose of `addAuthToOperation` is to take apply your auth state to each req
 you've returned from `getAuth` and not at all constrained by the exchange:
 
 ```js
-const addAuthToOperation = ({
-  authState,
-  operation,
-}) => {
+import { makeOperation } from '@urql/core';
+
+const addAuthToOperation = ({ authState, operation }) => {
   if (!authState || !authState.token) {
     return operation;
   }
@@ -126,20 +125,17 @@ const addAuthToOperation = ({
       ? operation.context.fetchOptions()
       : operation.context.fetchOptions || {};
 
-  return {
-    ...operation,
-    context: {
-      ...operation.context,
-      fetchOptions: {
-        ...fetchOptions,
-        headers: {
-          ...fetchOptions.headers,
-          "Authorization": authState.token,
-        },
+  return makeOperation(operation.kind, operation, {
+    ...operation.context,
+    fetchOptions: {
+      ...fetchOptions,
+      headers: {
+        ...fetchOptions.headers,
+        Authorization: authState.token,
       },
     },
-  };
-}
+  });
+};
 ```
 
 First we check that we have an `authState` and a `token`. Then we apply it to the request `fetchOptions` as an `Authorization` header.
@@ -174,10 +170,8 @@ is the recommended approach. We'll be able to determine whether any of the Graph
 
 ```js
 const didAuthError = ({ error }) => {
-  return error.graphQLErrors.some(
-    e => e.extensions?.code === 'FORBIDDEN',
-  );
-}
+  return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
+};
 ```
 
 For some GraphQL APIs, the auth error is communicated via an 401 HTTP response as is common in RESTful APIs:
@@ -225,7 +219,7 @@ const getAuth = async ({ authState }) => {
   logout();
 
   return null;
-}
+};
 ```
 
 Here, `logout()` is a placeholder that is called when we got an error, so that we can redirect to a login page again and clear our tokens from local storage or otherwise.
@@ -299,14 +293,12 @@ const client = createClient({
     cacheExchange,
     errorExchange({
       onError: error => {
-        const isAuthError = error.graphQLErrors.some(
-          e => e.extensions?.code === 'FORBIDDEN',
-        );
+        const isAuthError = error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
 
         if (isAuthError) {
           logout();
         }
-      }
+      },
     }),
     authExchange({
       /* config */
@@ -331,14 +323,14 @@ const App = ({ isLoggedIn }: { isLoggedIn: boolean | null }) => {
     if (isLoggedIn === null) {
       return null;
     }
-  
+
     return createClient({ /* config */ });
   }, [isLoggedIn]);
 
   if (!client) {
     return null;
   }
-  
+
   return {
     <GraphQLProvider value={client}>
       {/* app content  */}

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.
 
@@ -168,16 +168,15 @@ received.
 ### Operation
 
 The input for every exchange that informs GraphQL requests.
-It extends the [GraphQLRequest](#graphqlrequest) type and contains these additional properties:
+It extends the [`GraphQLRequest` type](#graphqlrequest) and contains these additional properties:
 
-| Prop            | Type               | Description                                   |
-| --------------- | ------------------ | --------------------------------------------- |
-| `operationName` | `OperationType`    | The type of GraphQL operation being executed. |
-| `context`       | `OperationContext` | Additional metadata passed to exchange.       |
+| Prop      | Type               | Description                                   |
+| --------- | ------------------ | --------------------------------------------- |
+| `kind`    | `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'`
+An `Operation` also contains the `operationName` property, which is a deprecated alias of the `kind`
+property and outputs a deprecation warning if it's used.
 
 ### RequestPolicy
 
@@ -379,6 +378,36 @@ Additionally, this utility will ensure that the `query` reference will remain st
 that if the same `query` will be passed in as a string or as a fresh `DocumentNode`, then the output
 will always have the same `DocumentNode` reference.
 
+### makeOperation
+
+This utility is used to either turn a [`GraphQLRequest` object](#graphqlrequest) into a new
+[`Operation` object](#operation) or to copy an `Operation`. It adds the `kind` property and the
+`operationName` alias that outputs a deprecation warning.
+
+It accepts three arguments:
+
+- An `Operation`'s `kind` (See [`OperationType`](#operationtype)
+- A [`GraphQLRequest` object](#graphqlrequest) or another [`Operation`](#operation) that should be
+  copied.
+- and; optionally a [partial `OperationContext` object.](#operationcontext). This argument may be
+  left out if the context is to be copied from the operation that may be passed as a second argument.
+
+Hence some valid uses of the utility are:
+
+```js
+// Create a new operation from scratch
+makeOperation('query', createRequest(query, variables), client.createOperationContext(opts));
+
+// Turn an operation into a 'teardown' operation
+makeOperation('teardown', operation);
+
+// Copy an existing operation while modifying its context
+makeOperation(operation.kind, operation, {
+  ...operation.context,
+  preferGetMethod: true,
+});
+```
+
 ### makeResult
 
 This is a helper function that converts a GraphQL API result to an

docs/common-questions.md

@@ -10,17 +10,21 @@ order: 6
 If you need `async fetchOptions` you can add an exchange that looks like this:
 
 ```js
+import { makeOperation } from '@urql/core';
+
 export const fetchOptionsExchange = (fn: any): Exchange => ({ forward }) => ops$ => {
   return pipe(
     ops$,
     mergeMap((operation: Operation) => {
       const result = fn(operation.context.fetchOptions);
       return pipe(
         typeof result.then === 'function' ? fromPromise(result) : fromValue(result),
-        map((fetchOptions: RequestInit | (() => RequestInit)) => ({
-          ...operation,
-          context: { ...operation.context, fetchOptions },
-        }))
+        map((fetchOptions: RequestInit | (() => RequestInit)) => {
+          return makeOperation(operation.kind, operation, {
+            ...operation.context,
+            fetchOptions,
+          });
+        })
       );
     }),
     forward

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/README.md

@@ -18,6 +18,7 @@ You'll then need to add the `authExchange`, that this package exposes to your `u
 
 ```js
 import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';
+import { makeOperation } from '@urql/core';
 import { authExchange } from '@urql/exchange-auth';
 
 const client = createClient({
@@ -41,9 +42,10 @@ const client = createClient({
             ? operation.context.fetchOptions()
             : operation.context.fetchOptions || {};
 
-        return {
-          ...operation,
-          context: {
+        return makeOperation(
+          operation.kind,
+          operation,
+          {
             ...operation.context,
             fetchOptions: {
               ...fetchOptions,
@@ -53,7 +55,7 @@ const client = createClient({
               },
             },
           },
-        };
+        );
       },
       willAuthError: ({ authState }) => {
         if (!authState) return true;