Fix callable type mapping to be Closure mapping

Author: oprypkhantc

src/Mappers/Root/CallableTypeMapper.php

@@ -42,6 +42,16 @@ public function toGraphQLOutputType(Type $type, OutputType|null $subType, Reflec
             throw CannotMapTypeException::createForMissingCallableReturnType();
         }
 
+        // It would also be a good idea to check if the type-hint is actually `Closure(): something`,
+        // not `callable(): something`, because the latter is currently not supported. But to do so,
+        // `phpDocumentor` would need to pass in the type of callable, which it doesn't. All
+        // types that look like callables - are reported as `callable` by phpDocumentor.
+        // The reason for such a check is that any string may be a callable (referring to a global function),
+        // so if a string that looks like a callable is returned from a resolver, it will get wrapped
+        // in `Deferred`, even though it wasn't supposed to be a deferred value. This could be fixed
+        // by combining `QueryField`'s resolver and `CallableTypeMapper` into one place, but
+        // that's not currently possible with GraphQLite's design.
+
         return $this->topRootTypeMapper->toGraphQLOutputType($returnType, null, $reflector, $docBlockObj);
     }
 

src/QueryField.php

@@ -97,8 +97,8 @@ private function resolveWithPromise(mixed $result, ResolverInterface $originalRe
     {
         // 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)) {
+        // - allows inferring the type from PHPDoc (Closure(): Type), unlike Deferred, which is not generic
+        if ($result instanceof Closure) {
             $result = new Deferred($result);
         }
 

tests/Fixtures/Integration/Models/Blog.php

@@ -4,6 +4,7 @@
 
 namespace TheCodingMachine\GraphQLite\Fixtures\Integration\Models;
 
+use Closure;
 use GraphQL\Deferred;
 use TheCodingMachine\GraphQLite\Annotations\Field;
 use TheCodingMachine\GraphQLite\Annotations\Prefetch;
@@ -81,9 +82,9 @@ public static function prefetchSubBlogs(iterable $blogs): array
         return $subBlogs;
     }
 
-    /** @return callable(): User  */
+    /** @return Closure(): User  */
     #[Field]
-    public function author(): callable {
+    public function author(): Closure {
         return fn () => new User('Author', 'author@graphqlite');
     }
 }

tests/QueryFieldTest.php

@@ -49,7 +49,7 @@ public function testParametersDescription(): void
         $this->assertEquals('Foo argument', $queryField->args[0]->description);
     }
 
-    public function testWrapsCallableInDeferred(): void
+    public function testWrapsClosureInDeferred(): void
     {
         $sourceResolver = new ServiceResolver(static fn () => function () {
             return 123;

website/docs/type-mapping.mdx

@@ -332,8 +332,22 @@ query {
 
 ## Promise mapping
 
-You can defer execution of fields by returning a callable. To specify the field type, add a `@return` PHPDoc annotation
-with a return type, like so: `@return callable(): YourTypeHere`. The callable must not have any parameters.
+You can defer execution of fields by returning a `Closure`. To specify the field type, add a `@return` PHPDoc annotation
+with a return type, like so: `@return Closure(): YourTypeHere`. The closure must not have any parameters.
+
+:::caution
+
+Only `Closure` type is supported, which means that all of the following will work:
+- arrow functions: `fn () => 123`
+- anonymous functions: `function () { return 123; }`
+- first-class callables: `random_int(...)`, `Integer::random(...)` etc
+
+But other callables **will not**:
+- callable strings: `'random_int'`, `'Integer::random'`
+- callable arrays: `[Integer::class, 'random']`, `[$object, 'method']`
+- invokable objects: `new class { function __invoke() { return 123; } }`
+
+:::
 
 An alternative way is to return `\GraphQL\Deferred` instances, along with specifying the type through the
 `outputType` parameter of field attributes: `#[Field(outputType: SomeGQLType)]`.
@@ -348,10 +362,10 @@ class Product
     // ...
 
     /**
-     * @return callable(): string
+     * @return Closure(): string
      */
     #[Field]
-    public function getName(): callable
+    public function getName(): Closure
     {
         return fn() => $this->name;
     }