@homebound/graphql-typescript-factories

graphql-typescript-factories

This project is a plugin for graphql-code-generator that generates new<Foo> factory methods for use in client-side GraphQL tests that are stubbing/mocking out GraphQL responses.

I.e. for a given schema like:

type Author {
  name: String!
  summary: AuthorSummary!
  popularity: Popularity!
  working: Working
  birthday: Date
}

# A DTO that is just some fields
type AuthorSummary {
  author: Author!
  numberOfBooks: Int!
  amountOfSales: Float
}

You'll get a factory method (generated in your regular graphql-types.ts output file) that let's you "one liner" create an Author with sane defaults:

const author = newAuthor();

expect(author.__typename).toEqual("Author")
expect(author.name).toEqual("name")
expect(author.summary.author).toStrictEqual(author);
expect(author.summary.numberOfBooks).toEqual(0);

You can also override properties that are specific to your use case:

const author = newAuthor({ name: "long name" });

expect(author.__typename).toEqual("Author")
expect(author.name).toEqual("name")

Install

npm -i @homebound/graphql-typescript-factories

Use

Since this is a plugin, make sure you have graphql-codegen installed prior to using this package

Include the plugin in your graphql-codegen.yml config file:

overwrite: true
schema: ./schema.json
generates:
  src/generated/graphql-types.tsx:
    config:
      withHOC: false
      withHooks: true
      avoidOptionals: true
    plugins:
      - typescript
      - "@homebound/graphql-typescript-factories"

Note: The factories created by this plugin use the Author/etc. types generated by the regular typescript plugin, so you should have that included too.

Putting Factories in a Separate File

The above configuration will include the factories in the same graphql-types.tsx file as the regular typescript types.

If you want to have the factories in a separate file, you can add a new output file, i.e. graphql-factories.tsx, specifically for this graphql-typescript-factories plugin, and set the typesFilePath, i.e. files:

overwrite: true
schema: ./schema.json
generates:
  src/generated/graphql-types.tsx:
    config:
      withHOC: false
      withHooks: true
      avoidOptionals: true
    plugins:
      - typescript
  src/generated/graphql-factories.tsx:
    config:
      withHOC: false
      withHooks: true
      avoidOptionals: true
      typesFilePath: "./graphql-types"
    plugins:
      - "@homebound/graphql-typescript-factories"

Things to note:

• If your project requires extensionless imports, please leave out the .ts(x) extensions out of typesFilePath. Otherwise, for projects that want the file extensions, i.e. to be fully ESM compliant, please keep the file extensions in the path.

Enum Details Pattern

Somewhat tangentially, we've added first-class handling of our Homebound-specific "Enum Detail" pattern, where instead of returning enum values directly, we wrap the enum with a detail object that adds the string name, so that the client doesn't have to have its own boilerplate "enum to name" mapping. I.e. this schema:

enum EmployeeStatus { FULL_TIME, PART_TIME }
  
type EmployeeStatusDetail {
  code: EmployeeStatus!
  name: String!
}

type Employee {
  status: EmployeeStatusDetail
}

Allows a client to use the "enum detail" object to get other information than just the code.

(Currently we only support an additional name field, but the intent would be to add more business-logic-y things to the detail object that is information the client might need, without having to hard-code switch statements on the client-side).

Currently, any GraphQL object that has exactly two fields, named code and name, is assumed to be an Enum Detail wrapper.

Once these wrapper types are recognized, we add some syntax sugar that allows creating objects with the enum itself as a shortcut, i.e.:

const employee = newEmployee({
  status: EmployeeStatus.FULL_TIME,
});

Will work even though status is technically a EmployeeStatusDetail object and not the EmployeeStatus enum directly.

If this feature/pattern is problematic for users who don't use it, we can add a config flag to disable it.

Contributing

In order to develop changes for this package, follow these steps:

1. Make your desired changes in the src directory

2. Adjust the example files under the integration directory to use your new feature.

3. Run yarn build, to create a build with your changes

4. Run yarn graphql-codegen, and verify the output

Todo

• Support "number of children"
• Support customizations like "if building DAG, reuse same project vs. make new project teach time"
• Support providing a level of the DAG N-levels away (i.e. "create project but use this for the task")

License

MIT