Add directive `@void` to unify the definition of fields with no return value #1992

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

spawnia wants to merge 26 commits into master from void

CHANGELOG.md

-Original file line number
+Diff line change
@@ Expand Up @@
     - Support Laravel 10 https://github.com/nuwave/lighthouse/pull/2287
     - Add `GraphQLContext:: setUser(?Authenticatable $user): void`
     - Add directive `@whereKey` to filter Models by their primary key https://github.com/nuwave/lighthouse/pull/2289
+    - Add directive `@void` to unify the definition of fields with no return value https://github.com/nuwave/lighthouse/pull/1992
     - Allow directive `@where` on fields https://github.com/nuwave/lighthouse/pull/2306
     ### Removed
@@ Expand Down @@

docs/master/api-reference/directives.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -3557,6 +3557,51 @@ directive @validator( @@
     Read more in the [validation docs](../security/validation.md#validator-classes).
+    ## @void
+    ```graphql
+    """
+    Mark a field that returns no value.
+    The return type of the field will be changed to `Unit!`, defined as `enum Unit { UNIT }`.
+    Whatever result is returned from the resolver will be replaced with `UNIT`.
+    """
+    directive @void on FIELD_DEFINITION
+    ```
+    To enable this directive, add the service provider to your `config/app.php`:
+    ```php
+    'providers' => [
+        \Nuwave\Lighthouse\Void\VoidServiceProvider::class,
+    ],
+    ```
+    Lighthouse will register the following type in your schema:
+    ```graphql
+    """
+    Allows only one value and thus can hold no information.
+    https://en.wikipedia.org/wiki/Unit_type
+    """
+    enum Unit {
+      "The only possible value."
+      UNIT
+    }
+    ```
+    Use this directive on mutations that return no value, see [motivation](https://github.com/graphql/graphql-spec/issues/906).
+    ```graphql
+    type Mutation {
+      fireAndForget: _ @void
+    }
+    ```
+    Lighthouse will modify the definition of your field and have it return `Unit!`.
+    No matter what your resolver returns, the resulting value will always be `UNIT`.
     ## @where
     ```graphql
@@ Expand Down @@

src/Void/VoidDirective.php

-Original file line number
+Diff line change
@@ -0,0 +1,40 @@
+    <?php
+    namespace Nuwave\Lighthouse\Void;
+    use GraphQL\Language\AST\FieldDefinitionNode;
+    use GraphQL\Language\AST\InterfaceTypeDefinitionNode;
+    use GraphQL\Language\AST\ObjectTypeDefinitionNode;
+    use GraphQL\Language\Parser;
+    use Nuwave\Lighthouse\Schema\AST\DocumentAST;
+    use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+    use Nuwave\Lighthouse\Schema\Values\FieldValue;
+    use Nuwave\Lighthouse\Support\Contracts\FieldManipulator;
+    use Nuwave\Lighthouse\Support\Contracts\FieldMiddleware;
+    class VoidDirective extends BaseDirective implements FieldManipulator, FieldMiddleware
+    {
+        public static function definition(): string
+        {
+            return /** @lang GraphQL */ <<<'GRAPHQL'
+    """
+    Mark a field that returns no value.
+    The return type of the field will be changed to `Unit!`, defined as `enum Unit { UNIT }`.
+    Whatever result is returned from the resolver will be replaced with `UNIT`.
+    """
+    directive @void on FIELD_DEFINITION
+    GRAPHQL;
+        }
+        public function manipulateFieldDefinition(DocumentAST &$documentAST, FieldDefinitionNode &$fieldDefinition, ObjectTypeDefinitionNode|InterfaceTypeDefinitionNode &$parentType)
+        {
+            $fieldDefinition->type = Parser::typeReference(/** @lang GraphQL */ 'Unit!');
+        }
+        public function handleField(FieldValue $fieldValue): void
+        {
+            // Just ignore whatever the original resolver is doing and always return a singular value
+            $fieldValue->resultHandler(static fn (): string => VoidServiceProvider::UNIT);
+        }
+    }

src/Void/VoidServiceProvider.php

-Original file line number
+Diff line change
@@ -0,0 +1,48 @@
+    <?php
+    namespace Nuwave\Lighthouse\Void;
+    use GraphQL\Language\Parser;
+    use Illuminate\Contracts\Events\Dispatcher;
+    use Illuminate\Support\ServiceProvider;
+    use Nuwave\Lighthouse\Events\ManipulateAST;
+    use Nuwave\Lighthouse\Events\RegisterDirectiveNamespaces;
+    /**
+     * TODO include by default in v6.
+     */
+    class VoidServiceProvider extends ServiceProvider
+    {
+        public const UNIT = 'UNIT';
+        public function boot(Dispatcher $dispatcher): void
+        {
+            $dispatcher->listen(
+                ManipulateAST::class,
+                static function (ManipulateAST $manipulateAST): void {
+                    $unit = self::UNIT;
+                    $manipulateAST->documentAST->setTypeDefinition(
+                        Parser::enumTypeDefinition(/** @lang GraphQL */ <<<GRAPHQL
+    """
+    Allows only one value and thus can hold no information.
+    https://en.wikipedia.org/wiki/Unit_type
+    """
+    enum Unit {
+      "The only possible value."
+      {$unit}
+    }
+    GRAPHQL
+                        )
+                    );
+                }
+            );
+            $dispatcher->listen(
+                RegisterDirectiveNamespaces::class,
+                static function (): string {
+                    return __NAMESPACE__;
+                }
+            );
+        }
+    }

tests/TestCase.php

-Original file line number
+Diff line change
@@ Expand Up / @@ -26,6 +26,7 @@ @@
     use Nuwave\Lighthouse\Testing\TestingServiceProvider;
     use Nuwave\Lighthouse\Testing\UsesTestSchema;
     use Nuwave\Lighthouse\Validation\ValidationServiceProvider;
+    use Nuwave\Lighthouse\Void\VoidServiceProvider;
     use Orchestra\Testbench\TestCase as BaseTestCase;
     use Symfony\Component\Console\Tester\CommandTester;
     use Tests\Utils\Policies\AuthServiceProvider;
@@ Expand Down Expand Up / @@ -89,6 +90,7 @@ protected function getPackageProviders($app): array @@
                 SoftDeletesServiceProvider::class,
                 TestingServiceProvider::class,
                 ValidationServiceProvider::class,
+                VoidServiceProvider::class,
             ];
         }
@@ Expand Down @@

tests/Unit/Void/VoidDirectiveTest.php

-Original file line number
+Diff line change
@@ -0,0 +1,28 @@
+    <?php
+    namespace Tests\Unit\Void;
+    use Nuwave\Lighthouse\Void\VoidServiceProvider;
+    use Tests\TestCase;
+    final class VoidDirectiveTest extends TestCase
+    {
+        public function testVoid(): void
+        {
+            $this->schema = /** @lang GraphQL */ '
+            type Query {
+                foo: _ @void
+            }
+            ';
+            $this->graphQL(/** @lang GraphQL */ '
+            {
+                foo
+            }
+            ')->assertJson([
+                'data' => [
+                    'foo' => VoidServiceProvider::UNIT,
+                ],
+            ]);
+        }
+    }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add directive `@void` to unify the definition of fields with no return value #1992

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Add directive @void to unify the definition of fields with no return value #1992

Are you sure you want to change the base?

Uh oh!

Add directive @void to unify the definition of fields with no return value #1992

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Add directive `@void` to unify the definition of fields with no return value #1992

Add directive `@void` to unify the definition of fields with no return value #1992