README

graphq-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 @tmikeschu/graphql-typescript-factories

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
      - "@tmikeschu/graphql-typescript-factories"

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

Enum Details Pattern

Somewhat tangentially, we've added first-class handling of 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:

Make your desired changes in the src directory
Adjust the example files under the integration directory to use your new feature.
Run npm run build, to create a build with your changes
Run npm run 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

Usage no npm install needed!