Add descriptions and disableDescriptions option (#68)

* Add descriptions

* Update docs and change log

Author: zhouzi

changelog.md

@@ -4,6 +4,8 @@
 
 - Add `maybeValueDefault` option to customize the nullable fields' default value
 - Add `inputMaybeValueDefault` option to customize the nullable inputs' fields' default value
+- Add objects' and inputs' description above the factory functions
+- Add `disableDescriptions` option to toggle on/off objects and inputs' description added above the factory functions
 
 ## 1.0.0 - 2022-05-07
 

docs/docs/configuration/schema.mdx

@@ -419,3 +419,49 @@ export function createPostInputMock(props: Partial<PostInput> = {}): PostInput {
 
 </div>
 </details>
+
+## `config.disableDescriptions`
+
+By default, objects' and inputs' description is added above the factory function.
+
+You can turn it off by setting `disableDescriptions` to `true`:
+
+```yml
+overwrite: true
+schema: ./schema.graphql
+generates:
+  ./types.ts:
+    plugins:
+      - typescript
+      - graphql-codegen-factories/schema
+    config:
+      # highlight-start
+      disableDescriptions: true
+      # highlight-end
+```
+
+<details>
+<summary>Example</summary>
+
+<div className="codeBlocks">
+
+```graphql title="schema.graphql"
+"""
+Description of a Post object.
+"""
+type Post {
+  title: String
+}
+```
+
+```typescript title="types.ts"
+export function createPostInputMock(props: Partial<PostInput> = {}): PostInput {
+  return {
+    title: undefined,
+    ...props,
+  };
+}
+```
+
+</div>
+</details>

packages/graphql-codegen-factories/src/schema/FactoriesSchemaVisitor.ts

@@ -53,6 +53,7 @@ export interface FactoriesSchemaVisitorRawConfig
 
   maybeValueDefault?: string;
   inputMaybeValueDefault?: string;
+  disableDescriptions?: boolean;
 }
 
 export interface FactoriesSchemaVisitorParsedConfig
@@ -64,6 +65,7 @@ export interface FactoriesSchemaVisitorParsedConfig
   importTypesNamespace?: string;
   maybeValueDefault: string;
   inputMaybeValueDefault: string;
+  disableDescriptions: boolean;
 }
 
 interface VisitedTypeNode {
@@ -129,6 +131,7 @@ export class FactoriesSchemaVisitor extends FactoriesBaseVisitor<
       ),
       maybeValueDefault,
       inputMaybeValueDefault,
+      disableDescriptions: getConfigValue(config.disableDescriptions, false),
     } as FactoriesSchemaVisitorParsedConfig;
 
     if (parsedConfig.typesPath && parsedConfig.namespacedImportName == null) {
@@ -205,6 +208,7 @@ export class FactoriesSchemaVisitor extends FactoriesBaseVisitor<
           node.name.value
         )}> = {}): ${this.convertNameWithTypesNamespace(node.name.value)}`
       )
+      .withComment(node.description ?? null, this.config.disableDescriptions)
       .withBlock(
         [
           indent("return {"),

packages/graphql-codegen-factories/src/schema/__tests__/__snapshots__/plugin.ts.snap

@@ -1,5 +1,28 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`plugin should add descriptions 1`] = `
+Object {
+  "content": "/** This is a description with /* characters that need to be escaped *\\\\/. */
+export function createPostMock(props: Partial<Post> = {}): Post {
+  return {
+    __typename: \\"Post\\",
+    title: null,
+    ...props,
+  };
+}
+
+/** This is a description for an input. */
+export function createPostInputMock(props: Partial<PostInput> = {}): PostInput {
+  return {
+    title: null,
+    ...props,
+  };
+}
+",
+  "prepend": Array [],
+}
+`;
+
 exports[`plugin should create factories for Query and Mutation 1`] = `
 Object {
   "content": "export function createUserMock(props: Partial<User> = {}): User {
@@ -191,6 +214,27 @@ export function createPostInputMock(props: Partial<PostInput> = {}): PostInput {
 }
 `;
 
+exports[`plugin should disable descriptions 1`] = `
+Object {
+  "content": "export function createPostMock(props: Partial<Post> = {}): Post {
+  return {
+    __typename: \\"Post\\",
+    title: null,
+    ...props,
+  };
+}
+
+export function createPostInputMock(props: Partial<PostInput> = {}): PostInput {
+  return {
+    title: null,
+    ...props,
+  };
+}
+",
+  "prepend": Array [],
+}
+`;
+
 exports[`plugin should import types from other file 1`] = `
 Object {
   "content": "export function createUserMock(props: Partial<SharedTypes.User> = {}): SharedTypes.User {

packages/graphql-codegen-factories/src/schema/__tests__/plugin.ts

@@ -3,7 +3,7 @@ import { plugin } from "../plugin";
 
 describe("plugin", () => {
   it("should create factories with built-in types", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         id: ID!
         organizationId: ID
@@ -45,7 +45,7 @@ describe("plugin", () => {
   });
 
   it("should use enums as types", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         status: UserStatus!
       }
@@ -61,7 +61,7 @@ describe("plugin", () => {
   });
 
   it("should use the custom scalar defaults", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         createdAt: Date!
       }
@@ -76,7 +76,7 @@ describe("plugin", () => {
   });
 
   it("should create factories for inputs", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       input PostInput {
         id: ID
         title: String!
@@ -88,7 +88,7 @@ describe("plugin", () => {
   });
 
   it("should create factories for Query and Mutation", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         id: ID!
       }
@@ -107,7 +107,7 @@ describe("plugin", () => {
   });
 
   it("should customize the factory name", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         id: ID!
       }
@@ -118,7 +118,7 @@ describe("plugin", () => {
   });
 
   it("should customize the maybe value default", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type Post {
         title: String
       }
@@ -134,7 +134,7 @@ describe("plugin", () => {
   });
 
   it("should customize the maybe value default and input maybe value default independently", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type Post {
         title: String
       }
@@ -151,7 +151,7 @@ describe("plugin", () => {
   });
 
   it("should customize the input maybe value default", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       input PostInput {
         title: String
       }
@@ -164,7 +164,7 @@ describe("plugin", () => {
   });
 
   it("should support enums with an underscore", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       enum UserRole {
         SUPER_ADMIN
         ADMIN
@@ -179,7 +179,7 @@ describe("plugin", () => {
   });
 
   it("should support directives", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       directive @test on FIELD_DEFINITION
 
       type User {
@@ -192,7 +192,7 @@ describe("plugin", () => {
   });
 
   it("should import types from other file", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         id: ID!
       }
@@ -206,7 +206,7 @@ describe("plugin", () => {
   });
 
   it("should create factories for unions", async () => {
-    const schema = buildSchema(`
+    const schema = buildSchema(/* GraphQL */ `
       type User {
         firstName: String!
         lastName: String!
@@ -237,4 +237,48 @@ describe("plugin", () => {
     const output = await plugin(schema, [], {});
     expect(output).toMatchSnapshot();
   });
+
+  it("should add descriptions", async () => {
+    const schema = buildSchema(/* GraphQL */ `
+      """
+      This is a description with /* characters that need to be escaped */.
+      """
+      type Post {
+        title: String
+      }
+
+      """
+      This is a description for an input.
+      """
+      input PostInput {
+        title: String
+      }
+    `);
+
+    const output = await plugin(schema, [], {});
+    expect(output).toMatchSnapshot();
+  });
+
+  it("should disable descriptions", async () => {
+    const schema = buildSchema(/* GraphQL */ `
+      """
+      This is a description with /* characters that need to be escaped */.
+      """
+      type Post {
+        title: String
+      }
+
+      """
+      This is a description for an input.
+      """
+      input PostInput {
+        title: String
+      }
+    `);
+
+    const output = await plugin(schema, [], {
+      disableDescriptions: true,
+    });
+    expect(output).toMatchSnapshot();
+  });
 });