Add explicit interface implements

Author: zth

CHANGELOG.md

@@ -1,5 +1,10 @@
 # ResGraph Changelog
 
+## 1.2.0
+
+- Add repeatable `@gql.implements("InterfaceName")` for declaring object and interface implementations without spreading fields into the ReScript record.
+- Validate GraphQL interface implementation parity during schema generation, including missing interfaces, missing fields, output field type compatibility, required field arguments, argument type mismatches, and extra required arguments.
+
 ## 1.1.6
 
 - Support escaped resolver argument labels for reserved ReScript names, allowing GraphQL arguments like `constraint` while using ReScript-safe local bindings.

README.md

@@ -113,6 +113,24 @@ enum TextFormat {
 
 [Check out the docs on getting started](https://zth.github.io/resgraph/docs/getting-started).
 
+Interfaces can be implemented by spreading the interface record into the
+implementing record, or explicitly with repeatable `@gql.implements(...)`
+attributes when the implementing type declares the shared fields itself:
+
+```rescript
+@gql.interface
+type hasName = {
+  @gql.field name: string,
+}
+
+@gql.implements("HasName")
+@gql.type
+type user = {
+  @gql.field name: string,
+  @gql.field age: int,
+}
+```
+
 ## Introduction
 
 ResGraph lets you build _implementation first_ GraphQL servers, where your types and code is the source of truth for the schema.

docs/docs/interfaces.md

@@ -68,6 +68,44 @@ type User implements HasName {
 }
 ```
 
+You can also implement interfaces explicitly with `@gql.implements("InterfaceName")`.
+This is useful when the implementing type already declares the fields itself, or
+when spreading the interface record would not fit the ReScript type shape you
+want.
+
+```rescript
+/** An entity with a name. */
+@gql.interface
+type hasName = {
+  /** The name of the thing. */
+  @gql.field name: string
+}
+
+/** An entity with a stable rank. */
+@gql.interface
+type ranked = {
+  @gql.field rank: int
+}
+
+/** A user in the system. */
+@gql.implements("HasName")
+@gql.implements("Ranked")
+@gql.type
+type user = {
+  @gql.field name: string,
+  @gql.field rank: int,
+  @gql.field age: int
+}
+```
+
+```graphql
+type User implements HasName & Ranked {
+  name: String!
+  rank: Int!
+  age: Int!
+}
+```
+
 ## Exposing fields from the interface
 
 Just like with [fields on object types](object-types#fields), you can expose fields on interfaces either directly via `@gql.field`, or by defining a function with `@gql.field`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "resgraph",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "Build GraphQL servers in ReScript.",
   "main": "index.js",
   "scripts": {

src/ml/GenerateSchema.ml

@@ -226,6 +226,25 @@ let rec findGraphQLType ~(env : SharedTypes.QueryEnv.t)
           let gqlAttribute =
             item.attributes |> extractGqlAttribute ~env ~schemaState
           in
+          let gqlImplementsAttributes =
+            item.attributes |> extractGqlImplementsAttributes ~schemaState ~env
+          in
+          (if List.length gqlImplementsAttributes > 0 then
+             match (gqlAttribute, item) with
+             | Some ObjectType, {kind = Record _}
+             | Some Interface, {kind = Record _} ->
+               ()
+             | _ ->
+               schemaState
+               |> addDiagnostic
+                    ~diagnostic:
+                      {
+                        loc = item.decl.type_loc;
+                        fileUri = env.file.uri;
+                        message =
+                          "`@gql.implements` can only be used on @gql.type or \
+                           @gql.interface records.";
+                      });
           match (gqlAttribute, item) with
           | ( Some ObjectType,
               {
@@ -247,6 +266,7 @@ let rec findGraphQLType ~(env : SharedTypes.QueryEnv.t)
             noticeObjectType id ~displayName ~schemaState ~env
               ?description:
                 (GenerateSchemaUtils.attributesToDocstring attributes)
+              ~explicitInterfaces:gqlImplementsAttributes
               ~makeFields:(fun () ->
                 fields
                 |> objectTypeFieldsOfRecordFields ~objectTypeName:displayName
@@ -290,6 +310,7 @@ let rec findGraphQLType ~(env : SharedTypes.QueryEnv.t)
                   id;
                   displayName;
                   interfaces = [];
+                  explicitInterfaces = gqlImplementsAttributes;
                   fields =
                     objectTypeFieldsOfRecordFields fields
                       ~objectTypeName:displayName ~env ~full ~schemaState ~debug;
@@ -1175,6 +1196,23 @@ and traverseStructure ?(modulePath = []) ?implStructure ?originModule
         let gqlAttribute =
           attributes |> extractGqlAttribute ~schemaState ~env
         in
+        let gqlImplementsAttributes =
+          attributes |> extractGqlImplementsAttributes ~schemaState ~env
+        in
+        (if List.length gqlImplementsAttributes > 0 then
+           match (item.kind, gqlAttribute) with
+           | Type ({kind = Record _}, _), Some (ObjectType | Interface) -> ()
+           | _ ->
+             schemaState
+             |> addDiagnostic
+                  ~diagnostic:
+                    {
+                      loc = item.loc;
+                      fileUri = env.file.uri;
+                      message =
+                        "`@gql.implements` can only be used on @gql.type or \
+                         @gql.interface records.";
+                    });
         match (item.kind, gqlAttribute) with
         | Module {type_ = Structure structure; _}, _ ->
           (* Continue into modules (ignore module aliases etc) *)
@@ -1219,7 +1257,7 @@ and traverseStructure ?(modulePath = []) ?implStructure ?originModule
           let displayName = capitalizeFirstChar item.name in
           noticeObjectType ~env ~loc:decl.type_loc ~schemaState
             ?description:(attributesToDocstring attributes)
-            ~displayName
+            ~displayName ~explicitInterfaces:gqlImplementsAttributes
             ~makeFields:(fun () ->
               objectTypeFieldsOfRecordFields fields ~objectTypeName:displayName
                 ~env ~full ~schemaState ~debug)
@@ -1256,6 +1294,7 @@ and traverseStructure ?(modulePath = []) ?implStructure ?originModule
                     ~objectTypeName:displayName ~env ~full ~schemaState ~debug;
                 description = attributesToDocstring attributes;
                 interfaces = [];
+                explicitInterfaces = gqlImplementsAttributes;
                 typeLocation =
                   findTypeLocation item.name ~env ~schemaState
                     ~loc:decl.type_loc ~expectedType:Interface;

src/ml/GenerateSchemaTypes.ml

@@ -50,6 +50,12 @@ type gqlArg = {
 
 type gqlInterfaceIdentifier = {id: string; displayName: string}
 
+type explicitInterfaceImplementation = {
+  interfaceName: string;
+  loc: Location.t;
+  fileUri: Uri.t;
+}
+
 type gqlEnumValue = {
   value: string;
   description: string option;
@@ -119,6 +125,7 @@ type gqlObjectType = {
   typeLocation: typeLocation option;
   syntheticTypeLocation: syntheticTypeLocation option;
   interfaces: string list;
+  explicitInterfaces: explicitInterfaceImplementation list;
 }
 
 type gqlInterface = {
@@ -128,6 +135,7 @@ type gqlInterface = {
   description: string option;
   typeLocation: typeLocationLoc;
   interfaces: string list;
+  explicitInterfaces: explicitInterfaceImplementation list;
 }
 
 type gqlInputObjectType = {