Allow callable() as field deferring mechanism

composer.json

@@ -13,8 +13,8 @@
         "php": ">=8.1",
         "ext-json": "*",
         "composer/package-versions-deprecated": "^1.8",
-        "phpdocumentor/reflection-docblock": "^4.3 || ^5.0",
-        "phpdocumentor/type-resolver": "^1.4",
+        "phpdocumentor/reflection-docblock": "^5.4",
+        "phpdocumentor/type-resolver": "^1.7",
         "psr/container": "^1.1 || ^2",
         "psr/http-factory": "^1",
         "psr/http-message": "^1.0.1 || ^2.0",

src/Mappers/CannotMapTypeException.php

@@ -13,6 +13,7 @@
 use GraphQL\Type\Definition\Type;
 use phpDocumentor\Reflection\Type as PhpDocumentorType;
 use phpDocumentor\Reflection\Types\Array_;
+use phpDocumentor\Reflection\Types\Callable_;
 use phpDocumentor\Reflection\Types\Iterable_;
 use phpDocumentor\Reflection\Types\Mixed_;
 use phpDocumentor\Reflection\Types\Object_;
@@ -124,7 +125,7 @@ public static function extendTypeWithBadTargetedClass(string $className, ExtendT
         return new self('For ' . self::extendTypeToString($extendType) . ' annotation declared in class "' . $className . '", the pointed at GraphQL type cannot be extended. You can only target types extending the MutableObjectType (like types created with the @Type annotation).');
     }
 
-    /** @param Array_|Iterable_|Object_|Mixed_             $type */
+    /** @param Array_|Iterable_|Object_|Mixed_|Callable_             $type */
     public static function createForMissingPhpDoc(PhpDocumentorType $type, ReflectionMethod|ReflectionProperty $reflector, string|null $argumentName = null): self
     {
         $typeStr = '';
@@ -136,6 +137,8 @@ public static function createForMissingPhpDoc(PhpDocumentorType $type, Reflectio
             $typeStr = sprintf('object ("%s")', $type->getFqsen());
         } elseif ($type instanceof Mixed_) {
             $typeStr = 'mixed';
+        } elseif ($type instanceof Callable_) {
+            $typeStr = 'callable';
         }
         assert($typeStr !== '');
         if ($argumentName === null) {
@@ -177,4 +180,19 @@ public static function createForNonNullReturnByTypeMapper(): self
     {
         return new self('a type mapper returned a GraphQL\Type\Definition\NonNull instance. All instances returned by type mappers should be nullable. It is the role of the NullableTypeMapperAdapter class to make a GraphQL type in a "NonNull". Note: this is an error in the TypeMapper code or in GraphQLite itself. Please check your custom type mappers or open an issue on GitHub if you don\'t have any custom type mapper.');
     }
+
+    public static function createForUnexpectedCallableParameters(): self
+    {
+        return new self('callable() type-hint must not specify any parameters.');
+    }
+
+    public static function createForMissingCallableReturnType(): self
+    {
+        return new self('callable() type-hint must specify its return type. For instance: callable(): int');
+    }
+
+    public static function createForCallableAsInput(): self
+    {
+        return new self('callable() type-hint can only be used as output type.');
+    }
 }

src/Mappers/Parameters/TypeHandler.php

@@ -16,6 +16,7 @@
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver as PhpDocumentorTypeResolver;
 use phpDocumentor\Reflection\Types\Array_;
+use phpDocumentor\Reflection\Types\Callable_;
 use phpDocumentor\Reflection\Types\Collection;
 use phpDocumentor\Reflection\Types\Compound;
 use phpDocumentor\Reflection\Types\Iterable_;
@@ -375,6 +376,7 @@ private function mapType(
             $innerType instanceof Array_
             || $innerType instanceof Iterable_
             || $innerType instanceof Mixed_
+            || $innerType instanceof Callable_
             // Try to match generic phpdoc-provided iterables with non-generic return-type-provided iterables
             // Example: (return type `\ArrayObject`, phpdoc `\ArrayObject<string, TestObject>`)
             || ($innerType instanceof Object_

src/Mappers/Root/CallableTypeMapper.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Mappers\Root;
+
+use GraphQL\Type\Definition\InputType;
+use GraphQL\Type\Definition\NamedType;
+use GraphQL\Type\Definition\OutputType;
+use GraphQL\Type\Definition\Type as GraphQLType;
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\Types\Callable_;
+use ReflectionMethod;
+use ReflectionProperty;
+use TheCodingMachine\GraphQLite\Mappers\CannotMapTypeException;
+
+/**
+ * This mapper maps callable types into their return types, so that fields can defer their execution.
+ */
+class CallableTypeMapper implements RootTypeMapperInterface
+{
+    public function __construct(
+        private readonly RootTypeMapperInterface $next,
+        private readonly RootTypeMapperInterface $topRootTypeMapper,
+    ) {
+    }
+
+    public function toGraphQLOutputType(Type $type, OutputType|null $subType, ReflectionMethod|ReflectionProperty $reflector, DocBlock $docBlockObj): OutputType&GraphQLType
+    {
+        if (! $type instanceof Callable_) {
+            return $this->next->toGraphQLOutputType($type, $subType, $reflector, $docBlockObj);
+        }
+
+        if ($type->getParameters()) {
+            throw CannotMapTypeException::createForUnexpectedCallableParameters();
+        }
+
+        $returnType = $type->getReturnType();
+
+        if (! $returnType) {
+            throw CannotMapTypeException::createForMissingCallableReturnType();
+        }
+
+        return $this->topRootTypeMapper->toGraphQLOutputType($returnType, null, $reflector, $docBlockObj);
+    }
+
+    public function toGraphQLInputType(Type $type, InputType|null $subType, string $argumentName, ReflectionMethod|ReflectionProperty $reflector, DocBlock $docBlockObj): InputType&GraphQLType
+    {
+        if (! $type instanceof Callable_) {
+            return $this->next->toGraphQLInputType($type, $subType, $argumentName, $reflector, $docBlockObj);
+        }
+
+        throw CannotMapTypeException::createForCallableAsInput();
+    }
+
+    public function mapNameToType(string $typeName): NamedType&GraphQLType
+    {
+        return $this->next->mapNameToType($typeName);
+    }
+}

src/QueryField.php

@@ -5,6 +5,7 @@
 namespace TheCodingMachine\GraphQLite;
 
 use Closure;
+use GraphQL\Deferred;
 use GraphQL\Error\ClientAware;
 use GraphQL\Executor\Promise\Adapter\SyncPromise;
 use GraphQL\Language\AST\FieldDefinitionNode;
@@ -20,6 +21,8 @@
 use TheCodingMachine\GraphQLite\Parameters\ParameterInterface;
 use TheCodingMachine\GraphQLite\Parameters\SourceParameter;
 
+use function is_callable;
+
 /**
  * A GraphQL field that maps to a PHP method automatically.
  *
@@ -92,6 +95,13 @@ public function __construct(
 
     private function resolveWithPromise(mixed $result, ResolverInterface $originalResolver): mixed
     {
+        // Shorthand for deferring field execution. This does two things:
+        // - removes the dependency on `GraphQL\Deferred` from user land code
+        // - allows inferring the type from PHPDoc (callable(): Type), unlike Deferred, which is not generic
+        if (is_callable($result)) {
+            $result = new Deferred($result);
+        }
+
         if ($result instanceof SyncPromise) {
             return $result->then(fn ($resolvedValue) => $this->resolveWithPromise($resolvedValue, $originalResolver));
         }

src/SchemaFactory.php

@@ -35,6 +35,7 @@
 use TheCodingMachine\GraphQLite\Mappers\PorpaginasTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\RecursiveTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\BaseTypeMapper;
+use TheCodingMachine\GraphQLite\Mappers\Root\CallableTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\CompoundTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\EnumTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\FinalRootTypeMapper;
@@ -399,6 +400,7 @@ public function createSchema(): Schema
         $lastTopRootTypeMapper = new LastDelegatingTypeMapper();
         $topRootTypeMapper = new NullableTypeMapperAdapter($lastTopRootTypeMapper);
         $topRootTypeMapper = new VoidTypeMapper($topRootTypeMapper);
+        $topRootTypeMapper = new CallableTypeMapper($topRootTypeMapper, $lastTopRootTypeMapper);
 
         $errorRootTypeMapper = new FinalRootTypeMapper($recursiveTypeMapper);
         $rootTypeMapper = new BaseTypeMapper($errorRootTypeMapper, $recursiveTypeMapper, $topRootTypeMapper);

tests/AbstractQueryProvider.php

@@ -41,6 +41,7 @@
 use TheCodingMachine\GraphQLite\Mappers\Parameters\ResolveInfoParameterHandler;
 use TheCodingMachine\GraphQLite\Mappers\RecursiveTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\BaseTypeMapper;
+use TheCodingMachine\GraphQLite\Mappers\Root\CallableTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\CompoundTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\EnumTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\FinalRootTypeMapper;
@@ -359,6 +360,7 @@ protected function buildRootTypeMapper(): RootTypeMapperInterface
         $lastTopRootTypeMapper = new LastDelegatingTypeMapper();
         $topRootTypeMapper = new NullableTypeMapperAdapter($lastTopRootTypeMapper);
         $topRootTypeMapper = new VoidTypeMapper($topRootTypeMapper);
+        $topRootTypeMapper = new CallableTypeMapper($topRootTypeMapper, $lastTopRootTypeMapper);
 
         $errorRootTypeMapper = new FinalRootTypeMapper($this->getTypeMapper());
         $rootTypeMapper = new BaseTypeMapper(

tests/Fixtures/Integration/Models/Blog.php

@@ -36,13 +36,17 @@ public function getPosts(
         return $prefetchedPosts[$this->id];
     }
 
-    /** @param Blog[][] $prefetchedSubBlogs */
-    #[Field(outputType: '[Blog!]!')]
+    /**
+     * @param Blog[][] $prefetchedSubBlogs
+     *
+     * @return callable(): Blog[]
+     */
+    #[Field]
     public function getSubBlogs(
         #[Prefetch('prefetchSubBlogs')]
         array $prefetchedSubBlogs,
-    ): Deferred {
-        return new Deferred(fn () => $prefetchedSubBlogs[$this->id]);
+    ): callable {
+        return fn () => $prefetchedSubBlogs[$this->id];
     }
 
     /**

tests/Integration/IntegrationTestCase.php

@@ -41,6 +41,7 @@
 use TheCodingMachine\GraphQLite\Mappers\RecursiveTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\RecursiveTypeMapperInterface;
 use TheCodingMachine\GraphQLite\Mappers\Root\BaseTypeMapper;
+use TheCodingMachine\GraphQLite\Mappers\Root\CallableTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\CompoundTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\EnumTypeMapper;
 use TheCodingMachine\GraphQLite\Mappers\Root\FinalRootTypeMapper;
@@ -296,10 +297,13 @@ public function createContainer(array $overloadedServices = []): ContainerInterf
                 );
             },
             RootTypeMapperInterface::class => static function (ContainerInterface $container) {
-                return new VoidTypeMapper(
-                    new NullableTypeMapperAdapter(
-                        $container->get('topRootTypeMapper')
-                    )
+                return new CallableTypeMapper(
+                    new VoidTypeMapper(
+                        new NullableTypeMapperAdapter(
+                            $container->get('topRootTypeMapper')
+                        )
+                    ),
+                    $container->get('topRootTypeMapper')
                 );
             },
             'topRootTypeMapper' => static function () {

tests/Mappers/Root/CallableTypeMapperTest.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace TheCodingMachine\GraphQLite\Mappers\Root;
+
+use Generator;
+use GraphQL\Type\Definition\InputType;
+use GraphQL\Type\Definition\NamedType;
+use GraphQL\Type\Definition\NonNull;
+use GraphQL\Type\Definition\OutputType;
+use GraphQL\Type\Definition\StringType;
+use GraphQL\Type\Definition\Type as GraphQLType;
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\Types\Array_;
+use phpDocumentor\Reflection\Types\Callable_;
+use phpDocumentor\Reflection\Types\CallableParameter;
+use phpDocumentor\Reflection\Types\Nullable;
+use phpDocumentor\Reflection\Types\Object_;
+use phpDocumentor\Reflection\Types\String_;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use ReflectionMethod;
+use TheCodingMachine\GraphQLite\AbstractQueryProvider;
+use TheCodingMachine\GraphQLite\Fixtures\TestObject;
+use TheCodingMachine\GraphQLite\Fixtures\TestObject2;
+use TheCodingMachine\GraphQLite\Mappers\CannotMapTypeException;
+
+#[CoversClass(CallableTypeMapper::class)]
+#[CoversClass(CannotMapTypeException::class)]
+class CallableTypeMapperTest extends AbstractQueryProvider
+{
+    public function testMapsCallableReturnTypeUsingTopRootMapper(): void
+    {
+        $reflection = new ReflectionMethod(__CLASS__, 'testSkipsNonCallables');
+        $docBlock = new DocBlock();
+
+        $returnType = new String_();
+
+        $topRootMapper = $this->createMock(RootTypeMapperInterface::class);
+        $topRootMapper->expects($this->once())
+            ->method('toGraphQLOutputType')
+            ->with($returnType, null, $reflection, $docBlock)
+            ->willReturn(GraphQLType::string());
+
+        $mapper = new CallableTypeMapper(
+            $this->createMock(RootTypeMapperInterface::class),
+            $topRootMapper,
+        );
+
+        $result = $mapper->toGraphQLOutputType(new Callable_(returnType: $returnType), null, $reflection, $docBlock);
+
+        $this->assertSame(GraphQLType::string(), $result);
+    }
+
+    public function testThrowsWhenUsingCallableWithParameters(): void
+    {
+        $this->expectExceptionObject(CannotMapTypeException::createForUnexpectedCallableParameters());
+
+        $mapper = new CallableTypeMapper(
+            $this->createMock(RootTypeMapperInterface::class),
+            $this->createMock(RootTypeMapperInterface::class)
+        );
+
+        $type = new Callable_(
+            parameters: [
+                new CallableParameter(new String_())
+            ]
+        );
+
+        $mapper->toGraphQLOutputType($type, null, new ReflectionMethod(__CLASS__, 'testSkipsNonCallables'), new DocBlock());
+    }
+
+    public function testThrowsWhenUsingCallableWithoutReturnType(): void
+    {
+        $this->expectExceptionObject(CannotMapTypeException::createForMissingCallableReturnType());
+
+        $mapper = new CallableTypeMapper(
+            $this->createMock(RootTypeMapperInterface::class),
+            $this->createMock(RootTypeMapperInterface::class)
+        );
+
+        $mapper->toGraphQLOutputType(new Callable_(), null, new ReflectionMethod(__CLASS__, 'testSkipsNonCallables'), new DocBlock());
+    }
+
+    public function testThrowsWhenUsingCallableAsInputType(): void
+    {
+        $this->expectExceptionObject(CannotMapTypeException::createForCallableAsInput());
+
+        $mapper = new CallableTypeMapper(
+            $this->createMock(RootTypeMapperInterface::class),
+            $this->createMock(RootTypeMapperInterface::class)
+        );
+
+        $mapper->toGraphQLInputType(new Callable_(), null, 'arg1', new ReflectionMethod(__CLASS__, 'testSkipsNonCallables'), new DocBlock());
+    }
+
+    #[DataProvider('skipsNonCallablesProvider')]
+    public function testSkipsNonCallables(callable $createType): void
+    {
+        $type = $createType();
+        $reflection = new ReflectionMethod(__CLASS__, 'testSkipsNonCallables');
+        $docBlock = new DocBlock();
+
+        $next = $this->createMock(RootTypeMapperInterface::class);
+        $next->expects($this->once())
+            ->method('toGraphQLOutputType')
+            ->with($type, null, $reflection, $docBlock)
+            ->willReturn(GraphQLType::string());
+        $next->expects($this->once())
+            ->method('toGraphQLInputType')
+            ->with($type, null, 'arg1', $reflection, $docBlock)
+            ->willReturn(GraphQLType::int());
+        $next->expects($this->once())
+            ->method('mapNameToType')
+            ->with('Name')
+            ->willReturn(GraphQLType::float());
+
+        $mapper = new CallableTypeMapper($next, $this->createMock(RootTypeMapperInterface::class));
+
+        $this->assertSame(GraphQLType::string(), $mapper->toGraphQLOutputType($type, null, $reflection, $docBlock));
+        $this->assertSame(GraphQLType::int(), $mapper->toGraphQLInputType($type, null, 'arg1', $reflection, $docBlock));
+        $this->assertSame(GraphQLType::float(), $mapper->mapNameToType('Name'));
+    }
+
+    public static function skipsNonCallablesProvider(): iterable
+    {
+        yield [fn () => new Object_()];
+        yield [fn () => new Array_()];
+        yield [fn () => new String_()];
+    }
+}