Support for root field tags (#162) (#163)

* Support for root field tags (#162)

* Support for root field tags

Right now the mechanism for defining root fields is just too cumbersome. It requires defining a type `type Query = unknown` is nonsensicle _and_ is part of the very first hello world.

Additionally, it requires defining functions with unused initial arguments:

```typescript
/** @gqlField */
export function greeting(_: Query): string {
  return "Hello";
}
```

This is confusing and nonsensicle, but also prevents these fields being reused for non-GraphQL use cases which goes aginst the goals of Grats, which includes lettting people expose thier _existing_ TypeScript code.

This PR adds three new tags to let you define Query/Mutation/Subscription fields without needing to explictly define or reference these types.

[ghstack-poisoned]

* Update on "Support for root field tags"


Right now the mechanism for defining root fields is just too cumbersome. It requires defining a type `type Query = unknown` is nonsensicle _and_ is part of the very first hello world.

Additionally, it requires defining functions with unused initial arguments:

```typescript
/** gqlField */
export function greeting(_: Query): string {
  return "Hello";
}
```

This is confusing and nonsensicle, but also prevents these fields being reused for non-GraphQL use cases which goes aginst the goals of Grats, which includes lettting people expose thier _existing_ TypeScript code.

This PR adds three new tags to let you define Query/Mutation/Subscription fields without needing to explictly define or reference these types.

[ghstack-poisoned]

* Update on "Support for root field tags"


Right now the mechanism for defining root fields is just too cumbersome. It requires defining a type `type Query = unknown` is nonsensicle _and_ is part of the very first hello world.

Additionally, it requires defining functions with unused initial arguments:

```typescript
/** gqlField */
export function greeting(_: Query): string {
  return "Hello";
}
```

This is confusing and nonsensicle, but also prevents these fields being reused for non-GraphQL use cases which goes against the goals of Grats, which includes lettting people expose their _existing_ TypeScript code.

Now such fields can be defined using:

```typescript
/** gqlQueryField */
export function greeting(): string {
  return "Hello";
}
```

This PR adds three new tags to let you define Query/Mutation/Subscription fields without needing to explictly define or reference these types.

[ghstack-poisoned]

* Clean up source in docs generated ts

CHANGELOG.md

@@ -4,6 +4,17 @@
 
 Changes in this section are not yet released. If you need access to these changes before we cut a release, check out our `@main` NPM releases. Each commit on the main branch is [published to NPM](https://www.npmjs.com/package/grats?activeTab=versions) under the `main` tag.
 
+### Root Field Tags
+
+Fields on `Query`, `Mutation` and `Subscription` may now be defined using the new docblock tags `@gqlQueryField`, `@gqlMutationField` and `@gqlSubscriptionField`. These tags can be added to functions or static methods.
+
+```typescript
+/** @gqlQueryField */
+export function greeting(): string {
+  return "Hello world";
+}
+```
+
 - **Features**
   - Custom error messages when types or interfaces are missing fields which suggests adding a `@gqlField` docblock tag.
   - Custom error message when your project has no types defined. Intended to help guide new users.

examples/apollo-server/Query.ts

@@ -1,14 +1,7 @@
 import IPerson from "./interfaces/IPerson";
 import User from "./models/User";
 
-/** @gqlType */
-export type Query = unknown;
-
-/** @gqlField */
-export function me(_: Query): User {
-  return new User();
-}
-/** @gqlField */
-export function person(_: Query): IPerson {
+/** @gqlQueryField */
+export function person(): IPerson {
   return new User();
 }

examples/apollo-server/models/User.ts

@@ -1,5 +1,4 @@
 import IPerson from "../interfaces/IPerson";
-import { Query } from "../Query";
 import Group from "./Group";
 
 /** @gqlType User */
@@ -12,9 +11,14 @@ export default class UserResolver implements IPerson {
   groups(): Group[] {
     return [new Group()];
   }
-}
 
-/** @gqlField */
-export function allUsers(_: Query): UserResolver[] {
-  return [new UserResolver(), new UserResolver()];
+  /** @gqlQueryField */
+  static me(): UserResolver {
+    return new UserResolver();
+  }
+
+  /** @gqlQueryField */
+  static allUsers(): UserResolver[] {
+    return [new UserResolver(), new UserResolver()];
+  }
 }

examples/apollo-server/schema.ts

@@ -3,8 +3,8 @@
  * Do not manually edit. Regenerate by running `npx grats`.
  */
 import UserClass from "./models/User";
-import { allUsers as queryAllUsersResolver } from "./models/User";
-import { me as queryMeResolver } from "./Query";
+import queryAllUsersResolver from "./models/User";
+import queryMeResolver from "./models/User";
 import { person as queryPersonResolver } from "./Query";
 import { GraphQLSchema, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLString, GraphQLInterfaceType } from "graphql";
 export function getSchema(): GraphQLSchema {
@@ -64,22 +64,22 @@ export function getSchema(): GraphQLSchema {
                 allUsers: {
                     name: "allUsers",
                     type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(UserType))),
-                    resolve(source) {
-                        return queryAllUsersResolver(source);
+                    resolve() {
+                        return queryAllUsersResolver.allUsers();
                     }
                 },
                 me: {
                     name: "me",
                     type: new GraphQLNonNull(UserType),
-                    resolve(source) {
-                        return queryMeResolver(source);
+                    resolve() {
+                        return queryMeResolver.me();
                     }
                 },
                 person: {
                     name: "person",
                     type: new GraphQLNonNull(IPersonType),
-                    resolve(source) {
-                        return queryPersonResolver(source);
+                    resolve() {
+                        return queryPersonResolver();
                     }
                 }
             };

examples/express-graphql-http/interfaces/IPerson.ts

@@ -1,5 +1,12 @@
+import User from "../models/User";
+
 /** @gqlInterface */
 export default interface IPerson {
   /** @gqlField */
   name(): string;
 }
+
+/** @gqlQueryField */
+export function person(): IPerson {
+  return new User();
+}

examples/express-graphql-http/models/User.ts

@@ -1,9 +1,8 @@
 import IPerson from "../interfaces/IPerson";
-import { Query } from "../Query";
 import Group from "./Group";
 
-/** @gqlType User */
-export default class UserResolver implements IPerson {
+/** @gqlType */
+export default class User implements IPerson {
   /** @gqlField */
   name(): string {
     return "Alice";
@@ -12,9 +11,13 @@ export default class UserResolver implements IPerson {
   groups(): Group[] {
     return [new Group()];
   }
-}
+  /** @gqlQueryField */
+  static allUsers(): User[] {
+    return [new User(), new User()];
+  }
 
-/** @gqlField */
-export function allUsers(_: Query): UserResolver[] {
-  return [new UserResolver(), new UserResolver()];
+  /** @gqlQueryField */
+  static me(): User {
+    return new User();
+  }
 }

examples/express-graphql-http/schema.ts

@@ -3,9 +3,9 @@
  * Do not manually edit. Regenerate by running `npx grats`.
  */
 import UserClass from "./models/User";
-import { allUsers as queryAllUsersResolver } from "./models/User";
-import { me as queryMeResolver } from "./Query";
-import { person as queryPersonResolver } from "./Query";
+import queryAllUsersResolver from "./models/User";
+import queryMeResolver from "./models/User";
+import { person as queryPersonResolver } from "./interfaces/IPerson";
 import { GraphQLSchema, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLString, GraphQLInterfaceType } from "graphql";
 export function getSchema(): GraphQLSchema {
     const GroupType: GraphQLObjectType = new GraphQLObjectType({
@@ -64,22 +64,22 @@ export function getSchema(): GraphQLSchema {
                 allUsers: {
                     name: "allUsers",
                     type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(UserType))),
-                    resolve(source) {
-                        return queryAllUsersResolver(source);
+                    resolve() {
+                        return queryAllUsersResolver.allUsers();
                     }
                 },
                 me: {
                     name: "me",
                     type: new GraphQLNonNull(UserType),
-                    resolve(source) {
-                        return queryMeResolver(source);
+                    resolve() {
+                        return queryMeResolver.me();
                     }
                 },
                 person: {
                     name: "person",
                     type: new GraphQLNonNull(IPersonType),
-                    resolve(source) {
-                        return queryPersonResolver(source);
+                    resolve() {
+                        return queryPersonResolver();
                     }
                 }
             };

examples/express-graphql/interfaces/IPerson.ts

@@ -1,5 +1,12 @@
+import User from "../models/User";
+
 /** @gqlInterface */
 export default interface IPerson {
   /** @gqlField */
   name(): string;
 }
+
+/** @gqlQueryField */
+export function person(): IPerson {
+  return new User();
+}

examples/express-graphql/models/User.ts

@@ -1,5 +1,4 @@
 import IPerson from "../interfaces/IPerson";
-import { Query } from "../Query";
 import Group from "./Group";
 
 /** @gqlType User */
@@ -12,9 +11,13 @@ export default class UserResolver implements IPerson {
   groups(): Group[] {
     return [new Group()];
   }
-}
+  /** @gqlQueryField */
+  static allUsers(): UserResolver[] {
+    return [new UserResolver(), new UserResolver()];
+  }
 
-/** @gqlField */
-export function allUsers(_: Query): UserResolver[] {
-  return [new UserResolver(), new UserResolver()];
+  /** @gqlQueryField */
+  static me(): UserResolver {
+    return new UserResolver();
+  }
 }

examples/express-graphql/schema.ts

@@ -3,9 +3,9 @@
  * Do not manually edit. Regenerate by running `npx grats`.
  */
 import UserClass from "./models/User";
-import { allUsers as queryAllUsersResolver } from "./models/User";
-import { me as queryMeResolver } from "./Query";
-import { person as queryPersonResolver } from "./Query";
+import queryAllUsersResolver from "./models/User";
+import queryMeResolver from "./models/User";
+import { person as queryPersonResolver } from "./interfaces/IPerson";
 import { GraphQLSchema, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLString, GraphQLInterfaceType } from "graphql";
 export function getSchema(): GraphQLSchema {
     const GroupType: GraphQLObjectType = new GraphQLObjectType({
@@ -64,22 +64,22 @@ export function getSchema(): GraphQLSchema {
                 allUsers: {
                     name: "allUsers",
                     type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(UserType))),
-                    resolve(source) {
-                        return queryAllUsersResolver(source);
+                    resolve() {
+                        return queryAllUsersResolver.allUsers();
                     }
                 },
                 me: {
                     name: "me",
                     type: new GraphQLNonNull(UserType),
-                    resolve(source) {
-                        return queryMeResolver(source);
+                    resolve() {
+                        return queryMeResolver.me();
                     }
                 },
                 person: {
                     name: "person",
                     type: new GraphQLNonNull(IPersonType),
-                    resolve(source) {
-                        return queryPersonResolver(source);
+                    resolve() {
+                        return queryPersonResolver();
                     }
                 }
             };

examples/incremental-migration/models.ts

@@ -14,11 +14,8 @@ faker.seed(123);
  * - User.id
  */
 
-/** @gqlType */
-type Query = unknown;
-
-/** @gqlField */
-export function user(_: Query, id: ID): User | undefined {
+/** @gqlQueryField */
+export function user(id: ID): User | undefined {
   return Users.get(id);
 }
 

examples/incremental-migration/schemas/gratsGeneratedSchema.ts

@@ -38,8 +38,8 @@ export function getSchema(): GraphQLSchema {
                             type: new GraphQLNonNull(GraphQLID)
                         }
                     },
-                    resolve(source, args) {
-                        return queryUserResolver(source, args.id);
+                    resolve(_source, args) {
+                        return queryUserResolver(args.id);
                     }
                 }
             };

examples/next-js/app/api/graphql/Query.ts

@@ -6,14 +6,11 @@
 import IPerson from "./interfaces/IPerson";
 import User from "./models/User";
 
-/** @gqlType */
-export type Query = unknown;
-
-/** @gqlField */
-export function me(_: Query): User {
+/** @gqlQueryField */
+export function me(): User {
   return new User();
 }
-/** @gqlField */
-export function person(_: Query): IPerson {
+/** @gqlQueryField */
+export function person(): IPerson {
   return new User();
 }

examples/next-js/app/api/graphql/models/User.ts

@@ -1,5 +1,4 @@
 import IPerson from "../interfaces/IPerson";
-import { Query } from "../Query";
 import Group from "./Group";
 
 /** @gqlType User */
@@ -12,9 +11,9 @@ export default class UserResolver implements IPerson {
   groups(): Group[] {
     return [new Group()];
   }
-}
 
-/** @gqlField */
-export function allUsers(_: Query): UserResolver[] {
-  return [new UserResolver(), new UserResolver()];
+  /** @gqlQueryField */
+  static allUsers(): UserResolver[] {
+    return [new UserResolver(), new UserResolver()];
+  }
 }