feat(graphql)!: Root types for @searchBy and @sortBy (#129)

Closes: #118

packages/graphql/UPGRADE.md

@@ -53,14 +53,36 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 
 * [ ] `@searchByOperatorRelation` => `@searchByOperatorRelationship` (and class too; generated types will be named as `SearchByRelationship*` instead of `SearchByComplex*`).
 
-* [ ] `@searchByOperatorProperty` => `@searchByOperatorField` (and class too)
-
-* [ ] `@searchByOperatorCondition` => `@searchByOperatorFieldObject`
-
 * [ ] `LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators::Condition` => `LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators::Object`.
 
 * [ ] `scalar SearchByCondition` => `scalar SearchByObject`.
 
+* [ ] Added the root type that will contain only extra operators and newly added `field` operator (always present and cannot be removed). The new query syntax is:
+
+  ```graphql
+  query {
+      # WHERE name = "LastDragon"
+      users(where: {
+          field: { name: {equal: "LastDragon"} }
+      }) {
+          id
+      }
+  }
+  ```
+
+  If you want to use old query syntax, you can add following bindings into application provider:
+
+  ```php
+  $this->app->bind(
+      LastDragon_ru\LaraASP\GraphQL\SearchBy\Types\Condition\Root::class,
+      LastDragon_ru\LaraASP\GraphQL\SearchBy\Types\Condition\V5::class,
+  );
+  $this->app->bind(
+      LastDragon_ru\LaraASP\GraphQL\SearchBy\Types\Condition\Condition::class,
+      LastDragon_ru\LaraASP\GraphQL\SearchBy\Types\Condition\V5::class,
+  );
+  ```
+
 ## `@sortBy`
 
 * [ ] `enum SortByTypeFlag { yes }` => `enum SortByTypeFlag { Yes }`. 🤝
@@ -71,22 +93,45 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 
 * [ ] If you are overriding Extra operators, you may need to add `SortByOperators::Extra` to use new built-in:
 
-    ```php
-    $settings = [
-        'sort_by'   => [
-            'operators' => [
-                SortByOperators::Extra => [
-                    SortByOperators::Extra,
-                    SortByOperatorRandomDirective::class,
-                ],
-            ],
-        ],
-    ];
-    ```
+  ```php
+  $settings = [
+      'sort_by'   => [
+          'operators' => [
+              SortByOperators::Extra => [
+                  SortByOperators::Extra,
+                  SortByOperatorRandomDirective::class,
+              ],
+          ],
+      ],
+  ];
+  ```
 
 * [ ] If you are using `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scout\FieldResolver`, use `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderPropertyResolver` instead. 🤝
 
-* [ ] `@sortByOperatorProperty` => `@sortByOperatorFieldObject` (and class too)
+* [ ] Added the root type that will contain only extra operators and newly added `field` operator (always present and cannot be removed). The new query syntax is:
+
+  ```graphql
+  query {
+      # ORDER BY user.name ASC, text DESC
+      comments(order: [
+          {field: {user: {name: asc}}}
+          {field: {text: desc}}
+      ])
+  }
+  ```
+
+  If you want to use old query syntax, you can add following bindings into application provider:
+
+  ```php
+  $this->app->bind(
+      LastDragon_ru\LaraASP\GraphQL\SortBy\Types\Clause\Root::class,
+      LastDragon_ru\LaraASP\GraphQL\SortBy\Types\Clause\V5::class,
+  );
+  $this->app->bind(
+      LastDragon_ru\LaraASP\GraphQL\SortBy\Types\Clause\Clause::class,
+      LastDragon_ru\LaraASP\GraphQL\SortBy\Types\Clause\V5::class,
+  );
+  ```
 
 ## API
 
@@ -129,3 +174,11 @@ This section is actual only if you are extending the package. Please review and
 * [ ] `LastDragon_ru\LaraASP\GraphQL\SortBy\Operators\BaseOperator` => `LastDragon_ru\LaraASP\GraphQL\SortBy\Operators\Operator`
 
 * [ ] `LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators\Traits\ScoutSupport` => `LastDragon_ru\LaraASP\GraphQL\Builder\Traits\WithScoutSupport`
+
+* [ ] `@searchByOperatorCondition` => `@searchByOperatorChild` (and class too)
+
+* [ ] `@searchByOperatorProperty` => `@searchByOperatorCondition` (and class too)
+
+* [ ] `@sortByOperatorProperty` => `@sortByOperatorChild` (and class too)
+
+* [ ] `@sortByOperatorField` => `@sortByOperatorSort` (and class too)

packages/graphql/docs/Directives/@searchBy.md

@@ -75,23 +75,23 @@ That's all, just search 😃 (or look at [generated GraphQL schema](../../src/Se
 query {
     # WHERE name = "LastDragon"
     users(where: {
-        name: {equal: "LastDragon"}
+        field: { name: { equal: "LastDragon" } }
     }) {
         id
     }
 
     # WHERE name != "LastDragon"
     users(where: {
-        name: {notEqual: "LastDragon"}
+        field: { name: { notEqual: "LastDragon" } }
     }) {
         id
     }
 
     # WHERE name = "LastDragon" or name = "Aleksei"
     users(where: {
         anyOf: [
-            {name: {equal: "LastDragon"}}
-            {name: {equal: "Aleksei"}}
+            { field: { name: { equal: "LastDragon" } } }
+            { field: { name: { equal: "Aleksei" } } }
         ]
     }) {
         id
@@ -101,8 +101,8 @@ query {
     users(where: {
         not: {
             anyOf: [
-                {name: {equal: "LastDragon"}}
-                {name: {equal: "Aleksei"}}
+                { field: { name: { equal: "LastDragon" } } }
+                { field: { name: { equal: "Aleksei" } } }
             ]
         }
     }) {
@@ -111,16 +111,20 @@ query {
 
     # WHERE date IS NULL
     users(where: {
-        date: {isNull: yes}
+        field: { date: { isNull: Yes } }
     }) {
         id
     }
 
     # Relationship: WHERE EXIST (related table)
     comments(where: {
-        user: {
-            where: {
-                date: {between: {min: "2021-01-01", max: "2021-04-01"}}
+        field: {
+            user: {
+                where: {
+                    field: {
+                        date: { between: { min: "2021-01-01", max: "2021-04-01" } }
+                    }
+                }
             }
         }
     }) {
@@ -129,12 +133,16 @@ query {
 
     # Relationship: WHERE COUNT (related table) = 2
     comments(where: {
-        user: {
-            where: {
-                date: {between: {min: "2021-01-01", max: "2021-04-01"}}
-            }
-            count: {
-                equal: 2
+        field: {
+            user: {
+                where: {
+                    field: {
+                        date: { between: { min: "2021-01-01", max: "2021-04-01"} }
+                    }
+                }
+                count: {
+                    equal: 2
+                }
             }
         }
     }) {

packages/graphql/docs/Directives/@sortBy.md

@@ -58,8 +58,8 @@ And:
 query {
     # ORDER BY user.name ASC, text DESC
     comments(order: [
-        {user: {name: asc}}
-        {text: desc}
+        {field: {user: {name: asc}}}
+        {field: {text: desc}}
     ])
 }
 ```
@@ -216,7 +216,7 @@ query {
     # ORDER BY user.name ASC NULLS FIRST, text DESC
     comments(order: [
         {nullsFirst: {user: {name: asc}}}
-        {text: desc}
+        {field: {text: desc}}
     ])
 }
 ```

packages/graphql/docs/Directives/@stream.md

@@ -108,8 +108,8 @@ Query:
 query example(
     $limit: Int!,
     $offset: StreamOffset,
-    $where: SearchByConditionObject,
-    $order: [SortByClauseObject!],
+    $where: SearchByRootObject,
+    $order: [SortByRootObject!],
 ) {
     objects(where: $where, order: $order, limit: $limit, offset: $offset) {
         items {

packages/graphql/src/Builder/Types/InputObject.php

@@ -3,11 +3,14 @@
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Types;
 
 use GraphQL\Language\AST\DirectiveNode;
+use GraphQL\Language\AST\FieldDefinitionNode;
 use GraphQL\Language\AST\InputValueDefinitionNode;
 use GraphQL\Language\AST\StringValueNode;
 use GraphQL\Language\AST\TypeDefinitionNode;
 use GraphQL\Language\BlockString;
 use GraphQL\Language\Parser;
+use GraphQL\Type\Definition\FieldDefinition;
+use GraphQL\Type\Definition\InputObjectField;
 use GraphQL\Type\Definition\Type;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Context\HandlerContextBuilderInfo;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Context\HandlerContextImplicit;
@@ -87,10 +90,7 @@ public function getTypeDefinition(
         );
 
         // Add searchable fields
-        $object = $source->getType();
-        $fields = $object instanceof Type
-            ? $object->getFields()
-            : $object->fields;
+        $fields = $this->getFields($manipulator, $source, $context);
 
         foreach ($fields as $field) {
             // Name should be unique (may conflict with Type's operators)
@@ -143,6 +143,22 @@ protected function getOperators(
         return $operators;
     }
 
+    /**
+     * @return iterable<array-key, FieldDefinition|FieldDefinitionNode|InputObjectField|InputValueDefinitionNode>
+     */
+    protected function getFields(
+        Manipulator $manipulator,
+        InterfaceSource|InputSource|ObjectSource $source,
+        Context $context,
+    ): iterable {
+        $object = $source->getType();
+        $fields = $object instanceof Type
+            ? $object->getFields()
+            : $object->fields;
+
+        return $fields;
+    }
+
     /**
      * Determines if the field can be converted or not.
      *

packages/graphql/src/SearchBy/Definitions/SearchByOperatorFieldObjectDirective.php → packages/graphql/src/SearchBy/Definitions/SearchByOperatorChildDirective.php

@@ -2,9 +2,9 @@
 
 namespace LastDragon_ru\LaraASP\GraphQL\SearchBy\Definitions;
 
-use LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators\FieldObject;
+use LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators\Child;
 
-class SearchByOperatorFieldObjectDirective extends FieldObject {
+class SearchByOperatorChildDirective extends Child {
     // Lighthouse loads all classes from directive namespace this leads to
     // 'Class "Orchestra\Testbench\TestCase" not found' error for our *Test
     // classes. This class required to avoid this error.

packages/graphql/src/SearchBy/Definitions/SearchByOperatorConditionDirective.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\GraphQL\SearchBy\Definitions;
+
+use LastDragon_ru\LaraASP\GraphQL\SearchBy\Operators\Condition;
+
+class SearchByOperatorConditionDirective extends Condition {
+    // Lighthouse loads all classes from directive namespace this leads to
+    // 'Class "Orchestra\Testbench\TestCase" not found' error for our *Test
+    // classes. This class required to avoid this error.
+}