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")
npm -i @homebound/graphql-typescript-factories
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.
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 oftypesFilePath
. Otherwise, for projects that want the file extensions, i.e. to be fully ESM compliant, please keep the file extensions in the path.
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.
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
yarn build
, to create a build with your changes -
Run
yarn graphql-codegen
, and verify the output
- 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")
MIT