refactor(graphql)!: API Improvements (#130)

packages/graphql/README.md

@@ -124,16 +124,16 @@ For Implicit type, the following rules are applied (in this order; concrete dire
     * Otherwise - include
 * Ignored (if supported)? - exclude
 
-# Builder property name
+# Builder field/column name
 
-By default `@searchBy`/`@sortBy` will convert nested/related properties into dot string: eg `{user: {name: asc}}` will be converted into `user.name`. You can redefine this behavior by [`BuilderPropertyResolver`](./src/Builder/Contracts/BuilderPropertyResolver.php):
+By default `@searchBy`/`@sortBy` will convert nested/related fields into dot string: eg `{user: {name: asc}}` will be converted into `user.name`. You can redefine this behavior by [`BuilderFieldResolver`](./src/Builder/Contracts/BuilderFieldResolver.php):
 
 ```php
 // AppProvider
 
 $this->app->bind(
-    LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderPropertyResolver::class,
-    MyBuilderPropertyResolver::class,
+    LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderFieldResolver::class,
+    MyBuilderFieldResolver::class,
 );
 ```
 
@@ -349,7 +349,7 @@ on
     | SCALAR
 
 """
-Available conditions for `type User` (only one property allowed at a time).
+Available conditions for `type User` (only one field allowed at a time).
 """
 input SearchByConditionUser {
     """

packages/graphql/UPGRADE.md

@@ -91,7 +91,7 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 
 * [ ] If you are testing generated queries, you need to update `sort_by_*` alias to `lara_asp_graphql__sort_by__*`.
 
-* [ ] If you are overriding Extra operators, you may need to add `SortByOperators::Extra` to use new built-in:
+* [ ] If you are overriding Extra operators, you should to add `SortByOperators::Extra` to use new built-in:
 
   ```php
   $settings = [
@@ -106,7 +106,7 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
   ];
   ```
 
-* [ ] If you are using `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scout\FieldResolver`, use `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderPropertyResolver` instead. 🤝
+* [ ] If you are using `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scout\FieldResolver`, use `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderFieldResolver` instead. 🤝
 
 * [ ] 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:
 
@@ -133,6 +133,8 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
   );
   ```
 
+* [ ] `@sortByOperatorRandom` cannot be added to `FIELD_DEFINITION` anymore.
+
 ## API
 
 This section is actual only if you are extending the package. Please review and update (listed the most significant changes only):
@@ -147,19 +149,23 @@ This section is actual only if you are extending the package. Please review and
 
 * [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\TypeSource`
 
+* [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionTooManyProperties` => `LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionTooManyFields`
+
+* [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Property` => `LastDragon_ru\LaraASP\GraphQL\Builder\Field`
+
 * [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Manipulator`
 
-  * [ ] Removed `BuilderInfo`. To get `BuilderInfo` instance within Operator the `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Context` should be used instead
+  * [ ] `BuilderInfo` removed. To get `BuilderInfo` instance within Operator the `LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Context` should be used instead
 
     ```php
     $context->get(LastDragon_ru\LaraASP\GraphQL\Builder\Context\HandlerContextBuilderInfo::class)?->value
     ```
 
-  * [ ] Removed `getPlaceholderTypeDefinitionNode()` => `LastDragon_ru\LaraASP\GraphQL\Utils\AstManipulator::getOriginType()`
+  * [ ] `getPlaceholderTypeDefinitionNode()` removed => `LastDragon_ru\LaraASP\GraphQL\Utils\AstManipulator::getOriginType()`
 
 * [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Directives\HandlerDirective`
 
-* [ ] Removed `LastDragon_ru\LaraASP\GraphQL\Builder\Directives\PropertyDirective`
+* [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Directives\PropertyDirective` removed
 
 * [ ] `LastDragon_ru\LaraASP\GraphQL\Builder\Sources\*`
 

packages/graphql/src/Builder/Contracts/BuilderFieldResolver.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts;
+
+use LastDragon_ru\LaraASP\GraphQL\Builder\Field;
+
+/**
+ * Convert {@see Field} into builder field/column/etc.
+ */
+interface BuilderFieldResolver {
+    public function getField(object $builder, Field $field): string;
+}

packages/graphql/src/Builder/Contracts/Handler.php

@@ -2,7 +2,7 @@
 
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts;
 
-use LastDragon_ru\LaraASP\GraphQL\Builder\Property;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Field;
 use Nuwave\Lighthouse\Execution\Arguments\ArgumentSet;
 
 interface Handler {
@@ -13,5 +13,5 @@ interface Handler {
      *
      * @return TBuilder
      */
-    public function handle(object $builder, Property $property, ArgumentSet $conditions, Context $context): object;
+    public function handle(object $builder, Field $field, ArgumentSet $conditions, Context $context): object;
 }

packages/graphql/src/Builder/Contracts/Ignored.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts;
+
+/**
+ * Marks that field/definition/type should be excluded. Each directive must use
+ * own interface!
+ */
+interface Ignored {
+    // empty
+}

packages/graphql/src/Builder/Contracts/Operator.php

@@ -3,7 +3,7 @@
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts;
 
 use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\OperatorUnsupportedBuilder;
-use LastDragon_ru\LaraASP\GraphQL\Builder\Property;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Field;
 use Nuwave\Lighthouse\Execution\Arguments\Argument;
 use Nuwave\Lighthouse\Support\Contracts\Directive;
 
@@ -13,14 +13,11 @@ interface Operator extends Directive {
      */
     public static function getName(): string;
 
-    public function getFieldType(TypeProvider $provider, TypeSource $source, Context $context): string;
+    public function isAvailable(TypeProvider $provider, TypeSource $source, Context $context): bool;
 
-    public function getFieldDescription(): string;
+    public function getFieldType(TypeProvider $provider, TypeSource $source, Context $context): ?string;
 
-    /**
-     * @param class-string $builder
-     */
-    public function isAvailable(string $builder, Context $context): bool;
+    public function getFieldDescription(): ?string;
 
     /**
      * @template TBuilder of object
@@ -34,7 +31,7 @@ public function isAvailable(string $builder, Context $context): bool;
     public function call(
         Handler $handler,
         object $builder,
-        Property $property,
+        Field $field,
         Argument $argument,
         Context $context,
     ): object;

packages/graphql/src/Builder/Contracts/Scout/FieldResolver.php

@@ -3,15 +3,15 @@
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scout;
 
 use Illuminate\Database\Eloquent\Model;
-use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderPropertyResolver;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderFieldResolver;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Property;
 
 /**
  * Convert nested property into Scout field.
  *
- * @deprecated 5.4.0 Please use {@see BuilderPropertyResolver} instead.
+ * @deprecated 5.4.0 Please use {@see BuilderFieldResolver} instead.
  *
- * @see BuilderPropertyResolver
+ * @see BuilderFieldResolver
  */
 interface FieldResolver {
     public function getField(Model $model, Property $property): string;

packages/graphql/src/Builder/Contracts/TypeProvider.php

@@ -2,11 +2,9 @@
 
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Contracts;
 
-use GraphQL\Language\AST\ListTypeNode;
-use GraphQL\Language\AST\NamedTypeNode;
 use GraphQL\Language\AST\Node;
-use GraphQL\Language\AST\NonNullTypeNode;
 use GraphQL\Language\AST\TypeDefinitionNode;
+use GraphQL\Language\AST\TypeNode;
 use GraphQL\Type\Definition\Type;
 
 interface TypeProvider {
@@ -16,7 +14,7 @@ interface TypeProvider {
     public function getType(string $definition, TypeSource $source, Context $context): string;
 
     /**
-     * @param (TypeDefinitionNode&Node)|NamedTypeNode|ListTypeNode|NonNullTypeNode|Type $type
+     * @param (TypeDefinitionNode&Node)|(TypeNode&Node)|Type $type
      */
-    public function getTypeSource(TypeDefinitionNode|NamedTypeNode|ListTypeNode|NonNullTypeNode|Type $type): TypeSource;
+    public function getTypeSource(TypeDefinitionNode|TypeNode|Type $type): TypeSource;
 }

packages/graphql/src/Builder/Defaults/BuilderPropertyResolver.php → packages/graphql/src/Builder/Defaults/BuilderFieldResolver.php

@@ -3,8 +3,9 @@
 namespace LastDragon_ru\LaraASP\GraphQL\Builder\Defaults;
 
 use Laravel\Scout\Builder as ScoutBuilder;
-use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderPropertyResolver as BuilderPropertyResolverContract;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\BuilderFieldResolver as BuilderFieldResolverContract;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scout\FieldResolver as ScoutFieldResolver;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Field;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Property;
 use Override;
 
@@ -13,17 +14,17 @@
 /**
  * @internal
  */
-final class BuilderPropertyResolver implements BuilderPropertyResolverContract {
+final class BuilderFieldResolver implements BuilderFieldResolverContract {
     public function __construct(
         private readonly ?ScoutFieldResolver $resolver = null,
     ) {
         // empty
     }
 
     #[Override]
-    public function getProperty(object $builder, Property $property): string {
+    public function getField(object $builder, Field $field): string {
         return $builder instanceof ScoutBuilder && $this->resolver
-            ? $this->resolver->getField($builder->model, $property)
-            : implode('.', $property->getPath());
+            ? $this->resolver->getField($builder->model, new Property(...$field->getPath()))
+            : implode('.', $field->getPath());
     }
 }

packages/graphql/src/Builder/Directives/HandlerDirective.php

@@ -24,11 +24,11 @@
 use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Operator;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\Scope;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionEmpty;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionTooManyFields;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionTooManyOperators;
-use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\Client\ConditionTooManyProperties;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Exceptions\HandlerInvalidConditions;
+use LastDragon_ru\LaraASP\GraphQL\Builder\Field;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Manipulator;
-use LastDragon_ru\LaraASP\GraphQL\Builder\Property;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Sources\InterfaceFieldArgumentSource;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Sources\ObjectFieldArgumentSource;
 use LastDragon_ru\LaraASP\GraphQL\Builder\Traits\WithManipulator;
@@ -107,7 +107,7 @@ protected function handleAnyBuilder(object $builder, mixed $value, ContextContra
 
             foreach ($conditions as $condition) {
                 if ($condition instanceof ArgumentSet) {
-                    $builder = $this->handle($builder, new Property(), $condition, $context ?? new Context());
+                    $builder = $this->handle($builder, new Field(), $condition, $context ?? new Context());
                 } else {
                     throw new HandlerInvalidConditions($this);
                 }
@@ -127,7 +127,7 @@ protected function handleAnyBuilder(object $builder, mixed $value, ContextContra
     #[Override]
     public function handle(
         object $builder,
-        Property $property,
+        Field $field,
         ArgumentSet $conditions,
         ContextContract $context,
     ): object {
@@ -138,13 +138,13 @@ public function handle(
 
         // Valid?
         if (count($conditions->arguments) !== 1) {
-            throw new ConditionTooManyProperties(
+            throw new ConditionTooManyFields(
                 ArgumentFactory::getArgumentsNames($conditions),
             );
         }
 
         // Call
-        return $this->call($builder, $property, $conditions, $context);
+        return $this->call($builder, $field, $conditions, $context);
     }
 
     /**
@@ -156,7 +156,7 @@ public function handle(
      */
     protected function call(
         object $builder,
-        Property $property,
+        Field $field,
         ArgumentSet $operator,
         ContextContract $context,
     ): object {
@@ -180,9 +180,9 @@ protected function call(
                 }
             }
 
-            $property = $property->getChild($name);
-            $value    = $argument;
-            $op       = reset($operators);
+            $field = $field->getChild($name);
+            $value = $argument;
+            $op    = reset($operators);
 
             if (count($operators) > 1) {
                 throw new ConditionTooManyOperators(
@@ -202,7 +202,7 @@ static function (Operator $operator): string {
         }
 
         // Return
-        return $op->call($this, $builder, $property, $value, $context);
+        return $op->call($this, $builder, $field, $value, $context);
     }
     // </editor-fold>
 
@@ -264,10 +264,9 @@ protected function getArgumentTypeDefinitionNode(
         string $operator,
     ): ListTypeNode|NamedTypeNode|NonNullTypeNode|null {
         // Supported?
-        $operator = $manipulator->getOperator(static::getScope(), $operator);
-        $builder  = $context->get(HandlerContextBuilderInfo::class)?->value->getBuilder();
+        $operator = $manipulator->getOperator($operator, static::getScope(), $argument, $context);
 
-        if (!$builder || !$operator->isAvailable($builder, $context)) {
+        if (!$operator) {
             return null;
         }
 
@@ -277,7 +276,7 @@ protected function getArgumentTypeDefinitionNode(
             : $argument->getTypeDefinition();
         $source     = $manipulator->getTypeSource($definition);
         $type       = $operator->getFieldType($manipulator, $source, $context);
-        $type       = Parser::typeReference($type);
+        $type       = $type ? Parser::typeReference($type) : null;
 
         return $type;
     }