[PROP] Improved names for List/Field graphql related methods

The List and Field methods which are used to build the graphQL schema and resolvers are confusing for developers (citation needed).

This proposal suggests a different set of method names which should make it easier to follow and understand the code.

To begin with, let’s look at the current names. This are grouped into graphQL type definition related methods, and resolver definition related methods.

Each List method calls zero or more Field methods, as listed.

Type definitions

• list.getAdminGraphqlTypes
  • field.getGraphqlOutputFields
  • field.getGraphqlQueryArgs
  • field.getGraphqlUpdateArgs
  • field.getGraphqlCreateArgs
  • field.getGraphqlAuxiliaryTypes
• list.getAdminGraphqlQueries
  • field.getGraphqlAuxiliaryQueries
• list.getAdminGraphqlMutations
  • field.getGraphqlAuxiliaryMutations

Resolvers

• list.getAuxiliaryTypeResolvers
  • field.getGraphqlAuxiliaryTypeResolvers
• list.getAdminFieldResolvers
  • field.getGraphqlOutputFieldResolvers
• list.getAuxiliaryQueryResolvers
  • field.getGraphqlAuxiliaryQueryResolvers
• list.getAdminQueryResolvers
• list.getAuxiliaryMutationResolvers
  • field.getGraphqlAuxiliaryMutationResolvers
• list.getAdminMutationResolvers

Proposed Changes

There are two groups of proposed changes below:

1. InList methods, getAdmin...() becomes get...(). The Admin token doesn’t have any meaning here and can be removed.
2. In Field methods, getGraphql...Resolvers becomes get...Resolvers. This makes them consistent with the related List methods, which do not contain the Graphql token in their names.

Also, rather than renaming getAdminFieldResolvers to getFieldResolvers, we call it getListTypeResolvers. This makes it more clear what it is doing when paired with getAuxiliaryTypeResolvers in Keystone/index.js.

Changes

• list.getAdminGraphqlTypes -> list.getGraphqlTypes
• list.getAdminGraphqlQueries -> list.getGraphqlQueries
• list.getAdminGraphqlMutations -> list.getGraphqlMutations
• list.getAdminFieldResolvers -> list.getListTypeResolvers
• list.getAdminQueryResolvers -> list.getQueryResolvers
• list.getAdminMutationResolvers -> list.getMutationResolvers
• field.getGraphqlOutputFieldResolvers -> field.getOutputFieldResolvers
• field.getGraphqlAuxiliaryTypeResolvers -> field.getAuxiliaryTypeResolvers
• field.getGraphqlAuxiliaryQueryResolvers -> field.getAuxiliaryQueryResolvers
• field.getGraphqlAuxiliaryMutationResolvers -> field.getAuxiliaryMutationResolvers

Type definitions

• list.getGraphqlTypes
  • field.getGraphqlOutputFields
  • field.getGraphqlQueryArgs
  • field.getGraphqlUpdateArgs
  • field.getGraphqlCreateArgs
  • field.getGraphqlAuxiliaryTypes
• list.getGraphqlQueries
  • field.getGraphqlAuxiliaryQueries
• list.getGraphqlMutations
  • field.getGraphqlAuxiliaryMutations

Resolvers

• list.getAuxiliaryTypeResolvers
  • field.getAuxiliaryTypeResolvers
• list.getListTypeResolvers
  • field.getOutputFieldResolvers
• list.getAuxiliaryQueryResolvers
  • field.getAuxiliaryQueryResolvers
• list.getQueryResolvers
• list.getAuxiliaryMutationResolvers
  • field.getAuxiliaryMutationResolvers
• list.getMutationResolvers

Pros

• All type definition methods follow the pattern getGraphql<plural>, indicating that they will return a list graphQL snippets.
• All resolver methods follow the pattern get...Resolvers, indicating that they return a collection of resolvers.
• The token Admin does not appear in any of the methods, which is as it should be, since these methods have nothing to do with the admin client.

Cons

• None 😉

[jesstelford]

It went through with the abbreviated names as proposed. I’m not that strongly opinionated, so am happy with the results in https://github.com/keystonejs/keystone-5/pull/284 👍

[molomby]

@jesstelford I’m generally not a fan of shortening words either but in cases like this, where there are so many constructs relating to a specific area (GraphQL), it does make the code significantly less verbose. I’m more comfortable about Aux; it’s so often abbreviated and, in this context, quite unambiguous.

Regardless, did you and @timleslie bottom out on this before the merge? I didn’t intend to ignore your feedback!