Add handling of argument "resolvable" of directive @key

Author: a-melnikov

README.md

@@ -22,7 +22,7 @@ use GraphQL\Type\Definition\Type;
 
 $userType = new EntityObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id'], ['fields' => 'email']],
     'fields' => [
         'id' => ['type' => Type::int()],
         'email' => ['type' => Type::string()],
@@ -35,7 +35,7 @@ $userType = new EntityObjectType([
 ]);
 ```
 
-* `keyFields` — defines the entity's primary key, which consists of one or more of the fields. An entity's key cannot include fields that return a union or interface.
+* `keys` — defines the entity's primary key, which consists of one or more of the fields. An entity's key cannot include fields that return a union or interface.
 
 * `__resolveReference` — resolves the representation of the entity from the provided reference. Subgraphs use representations to reference entities from other subgraphs. A representation requires only an explicit __typename definition and values for the entity's primary key fields.
 
@@ -50,7 +50,7 @@ use Apollo\Federation\Types\EntityRefObjectType;
 
 $userType = new EntityRefObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id'], ['fields' => 'email']],
     'fields' => [
         'id' => ['type' => Type::int()],
         'email' => ['type' => Type::string()]
@@ -69,16 +69,12 @@ use Apollo\Federation\Types\EntityRefObjectType;
 
 $userType = new EntityRefObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id', 'resolvable' => false]],
     'fields' => [
         'id' => [
             'type' => Type::int(),
             'isExternal' => true
         ],
-        'email' => [
-            'type' => Type::string(),
-            'isExternal' => true
-        ]
     ]
 ]);
 ```

src/Directives/KeyDirective.php

@@ -11,19 +11,28 @@
 /**
  * The `@key` directive is used to indicate a combination of fields that can be used to uniquely
  * identify and fetch an object or interface.
+ *
+ * @see https://www.apollographql.com/docs/federation/federated-types/federated-directives/#key
  */
 class KeyDirective extends Directive
 {
+    public const ARGUMENT_FIELDS = 'fields';
+    public const ARGUMENT_RESOLVABLE = 'resolvable';
+
     public function __construct()
     {
         parent::__construct([
             'name' => DirectiveEnum::KEY,
             'locations' => [DirectiveLocation::OBJECT, DirectiveLocation::IFACE],
             'args' => [
                 new FieldArgument([
-                    'name' => 'fields',
+                    'name' => self::ARGUMENT_FIELDS,
                     'type' => Type::nonNull(Type::string()),
                 ]),
+                new FieldArgument([
+                    'name' => self::ARGUMENT_RESOLVABLE,
+                    'type' => Type::boolean(),
+                ]),
             ],
         ]);
     }

src/FederatedSchema.php

@@ -36,7 +36,7 @@
  *         'firstName' => [...],
  *         'lastName' => [...],
  *       ],
- *       'keyFields' => ['id', 'email']
+ *       'keys' => [['fields' => 'id'], ['fields' => 'email']]
  *     ]);
  *
  *     $queryType = new GraphQL\Type\Definition\ObjectType([

src/Types/EntityObjectType.php

@@ -22,7 +22,7 @@
  * <code>
  *     $userType = new Apollo\Federation\Types\EntityObjectType([
  *       'name' => 'User',
- *       'keyFields' => ['id', 'email'],
+ *       'keys' => [['fields' => 'id'], ['fields' => 'email']],
  *       'fields' => [...]
  *     ]);
  * </code>
@@ -31,7 +31,7 @@
  * <code>
  *     $userType = new Apollo\Federation\Types\EntityObjectType([
  *       'name' => 'User',
- *       'keyFields' => ['id', 'email'],
+ *       'keys' => [['fields' => 'id', 'resolvable': false ]],
  *       'fields' => [
  *         'id' => [
  *           'type' => Types::int(),
@@ -43,7 +43,7 @@
  */
 class EntityObjectType extends ObjectType
 {
-    public const FIELD_KEY_FIELDS = 'keyFields';
+    public const FIELD_KEYS = 'keys';
     public const FIELD_REFERENCE_RESOLVER = '__resolveReference';
 
     public const FIELD_DIRECTIVE_IS_EXTERNAL = 'isExternal';
@@ -54,16 +54,22 @@ class EntityObjectType extends ObjectType
     public $referenceResolver = null;
 
     /**
-     * @var array<int,string>|array<int|string,string|array<int|string,mixed>>
+     * @var array<int,array{fields: array<int,string>|array<int|string,string|array<int|string,mixed>>, resolvable: bool }>
      */
-    private array $keyFields;
+    private array $keys;
 
     /**
      * @param array<string,mixed> $config
      */
     public function __construct(array $config)
     {
-        $this->keyFields = $config[self::FIELD_KEY_FIELDS];
+        Utils::invariant(
+            !(\array_key_exists(self::FIELD_KEYS, $config) && \array_key_exists('keyFields', $config)),
+            'Use only one way to define directives @key.'
+        );
+
+        $this->keys = $config[self::FIELD_KEYS]
+            ?? array_map(static fn ($x): array => ['fields' => $x], $config['keyFields']);
 
         if (isset($config[self::FIELD_REFERENCE_RESOLVER])) {
             self::validateResolveReference($config);
@@ -76,11 +82,30 @@ public function __construct(array $config)
     /**
      * Gets the fields that serve as the unique key or identifier of the entity.
      *
+     * @deprecated Use {@see getKeys()}
+     *
      * @return array<int,string>|array<int|string,string|array<int|string,mixed>>
      */
     public function getKeyFields(): array
     {
-        return $this->keyFields;
+        @trigger_error(
+            'Since skillshare/apollo-federation-php 2.0.0: '
+            . 'Method \Apollo\Federation\Types\EntityObjectType::getKeyFields() is deprecated. '
+            . 'Use \Apollo\Federation\Types\EntityObjectType::getKeys() instead of it.',
+            \E_USER_DEPRECATED
+        );
+
+        return array_map(static fn(array $x) => $x['fields'], $this->keys);
+    }
+
+    /**
+     * Gets the fields that serve as the unique key or identifier of the entity.
+     *
+     * @return array<int,array{fields: array<int,string>|array<int|string,string|array<int|string,mixed>>, resolvable: bool }>
+     */
+    public function getKeys(): array
+    {
+        return $this->keys;
     }
 
     /**

src/Utils/FederatedSchemaPrinter.php

@@ -31,6 +31,7 @@
 
 namespace Apollo\Federation\Utils;
 
+use Apollo\Federation\Directives\KeyDirective;
 use Apollo\Federation\Enum\DirectiveEnum;
 use Apollo\Federation\FederatedSchema;
 use Apollo\Federation\Types\EntityObjectType;
@@ -192,8 +193,12 @@ protected static function printKeyDirective(EntityObjectType $type): string
     {
         $keyDirective = '';
 
-        foreach ($type->getKeyFields() as $keyField) {
-            $keyDirective .= sprintf(' @key(fields: "%s")', static::printKeyFields($keyField));
+        foreach ($type->getKeys() as $keyField) {
+            $arguments = [sprintf('%s: "%s"', KeyDirective::ARGUMENT_FIELDS, static::printKeyFields($keyField['fields']))];
+            if (\array_key_exists('resolvable', $keyField)) {
+                $arguments[] = sprintf('%s: %s', KeyDirective::ARGUMENT_RESOLVABLE, $keyField['resolvable'] ? 'true' : 'false');
+            }
+            $keyDirective .= sprintf(' @key(%s)', implode(', ', $arguments));
         }
 
         return $keyDirective;

test/EntitiesTest.php

@@ -16,11 +16,11 @@ class EntitiesTest extends TestCase
 
     public function testCreatingEntityType(): void
     {
-        $expectedKeyFields = ['id', 'email'];
+        $expectedKeys = [['fields' => 'id'], ['fields' => 'email']];
 
         $userType = new EntityObjectType([
             'name' => 'User',
-            'keyFields' => $expectedKeyFields,
+            'keys' => $expectedKeys,
             'fields' => [
                 'id' => ['type' => Type::int()],
                 'email' => ['type' => Type::string()],
@@ -29,17 +29,17 @@ public function testCreatingEntityType(): void
             ],
         ]);
 
-        $this->assertEqualsCanonicalizing($expectedKeyFields, $userType->getKeyFields());
+        $this->assertEqualsCanonicalizing($expectedKeys, $userType->getKeys());
         $this->assertMatchesSnapshot($userType->config);
     }
 
     public function testCreatingEntityTypeWithCallable(): void
     {
-        $expectedKeyFields = ['id', 'email'];
+        $expectedKeys = [['fields' => 'id'], ['fields' => 'email']];
 
         $userType = new EntityObjectType([
             'name' => 'User',
-            'keyFields' => $expectedKeyFields,
+            'keys' => $expectedKeys,
             'fields' => function () {
                 return [
                     'id' => ['type' => Type::int()],
@@ -50,7 +50,7 @@ public function testCreatingEntityTypeWithCallable(): void
             },
         ]);
 
-        $this->assertEqualsCanonicalizing($expectedKeyFields, $userType->getKeyFields());
+        $this->assertEqualsCanonicalizing($expectedKeys, $userType->getKeys());
         $this->assertMatchesSnapshot($userType->config);
     }
 
@@ -66,7 +66,7 @@ public function testResolvingEntityReference(): void
 
         $userType = new EntityObjectType([
             'name' => 'User',
-            'keyFields' => ['id', 'email'],
+            'keys' => [['fields' => 'id'], ['fields' => 'email']],
             'fields' => [
                 'id' => ['type' => Type::int()],
                 'email' => ['type' => Type::string()],
@@ -85,18 +85,18 @@ public function testResolvingEntityReference(): void
 
     public function testCreatingEntityRefType(): void
     {
-        $expectedKeyFields = ['id', 'email'];
+        $expectedKeys = [['fields' => 'id', 'resolvable' => false]];
 
         $userType = new EntityRefObjectType([
             'name' => 'User',
-            'keyFields' => $expectedKeyFields,
+            'keys' => $expectedKeys,
             'fields' => [
                 'id' => ['type' => Type::int()],
                 'email' => ['type' => Type::string()],
             ],
         ]);
 
-        $this->assertEqualsCanonicalizing($expectedKeyFields, $userType->getKeyFields());
+        $this->assertEqualsCanonicalizing($expectedKeys, $userType->getKeys());
         $this->assertMatchesSnapshot($userType->config);
     }
 }

test/StarWarsSchema.php

@@ -83,7 +83,7 @@ private static function getEpisodeType(): EntityObjectType
                     'provides' => 'name',
                 ],
             ],
-            EntityObjectType::FIELD_KEY_FIELDS => ['id'],
+            EntityObjectType::FIELD_KEYS => ['fields' => 'id'],
             EntityObjectType::FIELD_REFERENCE_RESOLVER => static function (array $ref): array {
                 $entity = StarWarsData::getEpisodeById($ref['id']);
                 $entity['__typename'] = 'Episode';
@@ -113,7 +113,7 @@ private static function getCharacterType(): EntityRefObjectType
                     'requires' => 'name',
                 ],
             ],
-            EntityObjectType::FIELD_KEY_FIELDS => ['id'],
+            EntityObjectType::FIELD_KEYS => ['fields' => 'id'],
         ]);
     }
 
@@ -132,7 +132,7 @@ private static function getLocationType(): EntityRefObjectType
                     'isExternal' => true,
                 ],
             ],
-            EntityObjectType::FIELD_KEY_FIELDS => ['id'],
+            EntityObjectType::FIELD_KEYS => ['fields' => 'id'],
         ]);
     }
 }

test/__snapshots__/DirectivesTest__testItAddsDirectivesToSchema__1.txt

@@ -2,7 +2,7 @@ directive @external on FIELD_DEFINITION
 
 directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
 
-directive @key(fields: String!) on OBJECT | INTERFACE
+directive @key(fields: String!, resolvable: Boolean) on OBJECT | INTERFACE
 
 directive @link(url: String!, as: String, for: String, import: [link_Import!]) repeatable on SCHEMA
 

test/__snapshots__/EntitiesTest__testCreatingEntityRefType__1.yml

@@ -1,7 +1,6 @@
 name: User
-keyFields:
-    - id
-    - email
+keys:
+    - { fields: id, resolvable: false }
 fields:
     id: { type: { name: Int, description: "The `Int` scalar type represents non-fractional signed whole numeric\nvalues. Int can represent values between -(2^31) and 2^31 - 1. ", astNode: null, extensionASTNodes: null, config: {  } } }
     email: { type: { name: String, description: "The `String` scalar type represents textual data, represented as UTF-8\ncharacter sequences. The String type is most often used by GraphQL to\nrepresent free-form human-readable text.", astNode: null, extensionASTNodes: null, config: {  } } }

test/__snapshots__/EntitiesTest__testCreatingEntityTypeWithCallable__1.yml

@@ -1,5 +1,5 @@
 name: User
-keyFields:
-    - id
-    - email
+keys:
+    - { fields: id }
+    - { fields: email }
 fields: {  }