feat(graphcache): local directives

docs/graphcache/cache-updates.md

@@ -1,6 +1,6 @@
 ---
 title: Cache Updates
-order: 3
+order: 4
 ---
 
 # Cache Updates

docs/graphcache/errors.md

@@ -1,6 +1,6 @@
 ---
 title: Errors
-order: 7
+order: 8
 ---
 
 # Help!
@@ -411,3 +411,8 @@ write to the cache when it's being queried.
 
 Please make sure that you're not calling `cache.updateQuery`,
 `cache.writeFragment`, or `cache.link` inside `resolvers`.
+
+## (28) Resolver and directive match the same field
+
+When you have a resolver defined on a field you shouln't be combining it with a directive as the directive
+will apply and the resolver will be void.

docs/graphcache/local-directives.md

@@ -0,0 +1,35 @@
+---
+title: Local Directives
+order: 3
+---
+
+# Local Directives
+
+Graphcache supports adding directives to GraphQL Documents, when we prefix a
+directive with an underscore (`_`) it will be stripped from the document and stored
+on the `_directives` property on the AST-node.
+
+> Ensure you prefix directives with `_` if you only want to alter local behavior.
+
+By default graphcache will add two directives `@_optional` and `@_required` which
+allow you to mark fields as being optional or mandatory.
+
+If you want to add directives yourself you can do so by performing
+
+```js
+cacheExchange({
+  directives: {
+    // If you now add `@_pagination` to your document we will execute this
+    pagination: directiveArguments => () => {
+      /* Resolver */
+    },
+  },
+});
+```
+
+The function signature of a directive is a function which receives the arguments the directive is called with in the document.
+That function should returns a [Resolver](./local-directives.md).
+
+### Reading on
+
+[On the next page we'll learn about "Cache Updates".](./cache-updates.md)

docs/graphcache/local-resolvers.md

@@ -565,4 +565,4 @@ cannot be stiched together.
 
 ### Reading on
 
-[On the next page we'll learn about "Cache Updates".](./cache-updates.md)
+[On the next page we'll learn about "Cache Directives".](./local-directives.md)

docs/graphcache/offline.md

@@ -1,6 +1,6 @@
 ---
 title: Offline Support
-order: 6
+order: 7
 ---
 
 # Offline Support

docs/graphcache/schema-awareness.md

@@ -1,6 +1,6 @@
 ---
 title: Schema Awareness
-order: 4
+order: 5
 ---
 
 # Schema Awareness
@@ -19,9 +19,9 @@ on `cacheExchange` allows us to pass an introspected schema to Graphcache:
 ```js
 const introspectedSchema = {
   __schema: {
-    queryType: { name: 'Query', },
-    mutationType: { name: 'Mutation', },
-    subscriptionType: { name: 'Subscription', },
+    queryType: { name: 'Query' },
+    mutationType: { name: 'Mutation' },
+    subscriptionType: { name: 'Subscription' },
   },
 };
 

exchanges/graphcache/src/ast/variables.ts

@@ -1,5 +1,6 @@
 import {
   FieldNode,
+  DirectiveNode,
   OperationDefinitionNode,
   valueFromASTUntyped,
 } from '@0no-co/graphql.web';
@@ -10,7 +11,7 @@ import { Variables } from '../types';
 
 /** Evaluates a fields arguments taking vars into account */
 export const getFieldArguments = (
-  node: FieldNode,
+  node: FieldNode | DirectiveNode,
   vars: Variables
 ): null | Variables => {
   let args: null | Variables = null;

exchanges/graphcache/src/cacheExchange.test.ts

@@ -6,6 +6,7 @@ import {
   OperationResult,
   CombinedError,
 } from '@urql/core';
+import { print, stripIgnoredCharacters } from 'graphql';
 
 import { vi, expect, it, describe } from 'vitest';
 
@@ -677,6 +678,147 @@ describe('data dependencies', () => {
   });
 });
 
+describe('directives', () => {
+  it('returns optional fields as partial', () => {
+    const client = createClient({
+      url: 'http://0.0.0.0',
+      exchanges: [],
+    });
+    const { source: ops$, next } = makeSubject<Operation>();
+
+    const query = gql`
+      {
+        todos {
+          id
+          text
+          completed @_optional
+        }
+      }
+    `;
+
+    const operation = client.createRequestOperation('query', {
+      key: 1,
+      query,
+      variables: undefined,
+    });
+
+    const queryResult: OperationResult = {
+      ...queryResponse,
+      operation,
+      data: {
+        __typename: 'Query',
+        todos: [
+          {
+            id: '1',
+            text: 'learn urql',
+            __typename: 'Todo',
+          },
+        ],
+      },
+    };
+
+    const reexecuteOperation = vi
+      .spyOn(client, 'reexecuteOperation')
+      .mockImplementation(next);
+
+    const response = vi.fn((forwardOp: Operation): OperationResult => {
+      if (forwardOp.key === 1) return queryResult;
+      return undefined as any;
+    });
+
+    const result = vi.fn();
+    const forward: ExchangeIO = ops$ => pipe(ops$, map(response), share);
+
+    pipe(
+      cacheExchange({})({ forward, client, dispatchDebug })(ops$),
+      tap(result),
+      publish
+    );
+
+    next(operation);
+
+    expect(response).toHaveBeenCalledTimes(1);
+    expect(result).toHaveBeenCalledTimes(1);
+    expect(reexecuteOperation).toHaveBeenCalledTimes(0);
+    expect(result.mock.calls[0][0].data).toEqual({
+      todos: [
+        {
+          completed: null,
+          id: '1',
+          text: 'learn urql',
+        },
+      ],
+    });
+  });
+
+  it('does not return missing required fields', () => {
+    const client = createClient({
+      url: 'http://0.0.0.0',
+      exchanges: [],
+    });
+    const { source: ops$, next } = makeSubject<Operation>();
+
+    const query = gql`
+      {
+        todos {
+          id
+          text
+          completed @_required
+        }
+      }
+    `;
+
+    const operation = client.createRequestOperation('query', {
+      key: 1,
+      query,
+      variables: undefined,
+    });
+
+    const queryResult: OperationResult = {
+      ...queryResponse,
+      operation,
+      data: {
+        __typename: 'Query',
+        todos: [
+          {
+            id: '1',
+            text: 'learn urql',
+            __typename: 'Todo',
+          },
+        ],
+      },
+    };
+
+    const reexecuteOperation = vi
+      .spyOn(client, 'reexecuteOperation')
+      .mockImplementation(next);
+
+    const response = vi.fn((forwardOp: Operation): OperationResult => {
+      if (forwardOp.key === 1) return queryResult;
+      return undefined as any;
+    });
+
+    const result = vi.fn();
+    const forward: ExchangeIO = ops$ => pipe(ops$, map(response), share);
+
+    pipe(
+      cacheExchange({})({ forward, client, dispatchDebug })(ops$),
+      tap(result),
+      publish
+    );
+
+    next(operation);
+
+    expect(response).toHaveBeenCalledTimes(1);
+    expect(result).toHaveBeenCalledTimes(1);
+    expect(
+      stripIgnoredCharacters(print(response.mock.calls[0][0].query))
+    ).toEqual('{todos{id text completed __typename}}');
+    expect(reexecuteOperation).toHaveBeenCalledTimes(0);
+    expect(result.mock.calls[0][0].data).toEqual(null);
+  });
+});
+
 describe('optimistic updates', () => {
   it('writes optimistic mutations to the cache', () => {
     vi.useFakeTimers();