@graphql-codegen/typescript

Releases

1. ▸▾4.0.1-alpha-20230612102009-94c1254c012 Jun 2023pre-release

   Nothing published for this version

2. ▸▾4.0.024 May 2023Breaking

   5c7592b4d: Introduces breaking changes to support react-query@4.0.0:

   Major Changes

   • 5c7592b4d: Introduces breaking changes to support react-query@4.0.0:

     • react query package is now @tanstack/react-query -> import changes
     • introduced a legacyMode flag (false by default)

     /!\ If you are using the 'react-query' package or react-query < 4, please set the legacyMode option to true. /!\

   Open source →

   Additional notes

   Major Changes

   • #9375 ba84a3a27 Thanks @eddeee888! - Implement Scalars with input/output types

     In GraphQL, Scalar types can be different for client and server. For example, given the native GraphQL ID:

     • A client may send string or number in the input
     • A client receives string in its selection set (i.e output)
     • A server receives string in the resolver (GraphQL parses string or number received from the client to string)
     • A server may return string or number (GraphQL serializes the value to string before sending it to the client )

     Currently, we represent every Scalar with only one type. This is what codegen generates as base type:

     export type Scalars = {
       ID: string
     }
     

     Then, this is used in both input and output type e.g.

     export type Book = {
       __typename?: 'Book'
       id: Scalars['ID'] // Output's ID can be `string` 👍
     }
     
     export type QueryBookArgs = {
       id: Scalars['ID'] // Input's ID can be `string` or `number`. However, the type is only `string` here 👎
     }
     

     This PR extends each Scalar to have input and output:

     export type Scalars = {
       ID: {
         input: string | number
         output: string
       }
     }
     

     Then, each input/output GraphQL type can correctly refer to the correct input/output scalar type:

     export type Book = {
       __typename?: 'Book'
       id: Scalars['ID']['output'] // Output's ID can be `string` 👍
     }
     
     export type QueryBookArgs = {
       id: Scalars['ID']['input'] // Input's ID can be `string` or `number` 👍
     }
     

     Note that for typescript-resolvers, the type of ID needs to be inverted. However, the referenced types in GraphQL input/output types should still work correctly:

     export type Scalars = {
       ID: {
         input: string;
         output: string | number;
       }
     }
     
     export type Book = {
       __typename?: "Book";
       id: Scalars["ID"]['output']; // Resolvers can return `string` or `number` in ID fields 👍
     };
     
     export type QueryBookArgs = {
       id: Scalars["ID"]['input']; // Resolvers receive `string` in ID fields 👍
     };
     
     export type ResolversTypes = {
       ID: ID: ResolverTypeWrapper<Scalars['ID']['output']>; // Resolvers can return `string` or `number` in ID fields 👍
     }
     
     export type ResolversParentTypes = {
       ID: Scalars['ID']['output']; // Resolvers receive `string` or `number` from parents 👍
     };
     

     ---

     Config changes:

     1. Scalars option can now take input/output types:

     config: {
       scalars: {
         ID: {
           input: 'string',
           output: 'string | number'
         }
       }
     }
     

     1. If a string is given (instead of an object with input/output fields), it will be used as both input and output types:

     config: {
       scalars: {
         ID: 'string' // This means `string` will be used for both ID's input and output types
       }
     }
     

     1. BREAKING CHANGE: External module Scalar types need to be an object with input/output fields

     config: {
       scalars: {
         ID: './path/to/scalar-module'
       }
     }
     

     If correctly, wired up, the following will be generated:

     // Previously, imported `ID` type can be a primitive type, now it must be an object with input/output fields
     import { ID } from './path/to/scalar-module'
     
     export type Scalars = {
       ID: { input: ID['input']; output: ID['output'] }
     }
     

     ---

     BREAKING CHANGE: This changes Scalar types which could be referenced in other plugins. If you are a plugin maintainer and reference Scalar, please update your plugin to use the correct input/output types.

   • bb66c2a31 Thanks @n1ru4l! - Require Node.js >= 16. Drop support for Node.js 14

   Minor Changes

   • #9196 3848a2b73 Thanks @beerose! - Add @defer directive support

     When a query includes a deferred fragment field, the server will return a partial response with the non-deferred fields first, followed by the remaining fields once they have been resolved.

     Once start using the @defer directive in your queries, the generated code will automatically include support for the directive.

     // src/index.tsx
     import { graphql } from './gql'
     
     const OrdersFragment = graphql(`
       fragment OrdersFragment on User {
         orders {
           id
           total
         }
       }
     `)
     const GetUserQuery = graphql(`
       query GetUser($id: ID!) {
         user(id: $id) {
           id
           name
           ...OrdersFragment @defer
         }
       }
     `)
     

     The generated type for GetUserQuery will have information that the fragment is incremental, meaning it may not be available right away.

     // gql/graphql.ts
     export type GetUserQuery = { __typename?: 'Query'; id: string; name: string } & ({
       __typename?: 'Query'
     } & {
       ' $fragmentRefs'?: { OrdersFragment: Incremental<OrdersFragment> }
     })
     

     Apart from generating code that includes support for the @defer directive, the Codegen also exports a utility function called isFragmentReady. You can use it to conditionally render components based on whether the data for a deferred fragment is available:

     const OrdersList = (props: { data: FragmentType<typeof OrdersFragment> }) => {
       const data = useFragment(OrdersFragment, props.data);
       return (
         // render orders list
       )
     };
     
     function App() {
       const { data } = useQuery(GetUserQuery);
       return (
         {data && (
           <>
             {isFragmentReady(GetUserQuery, OrdersFragment, data)
     					&& <OrdersList data={data} />}
           </>
         )}
       );
     }
     export default App;
     

   • #9339 50471e651 Thanks @AaronMoat! - Add excludeTypes config to resolversNonOptionalTypename

     This disables the adding of __typename in resolver types for any specified typename. This could be useful e.g. if you're wanting to enable this for all new types going forward but not do a big migration.

     Usage example:

     const config: CodegenConfig = {
       schema: 'src/schema/**/*.graphql',
       generates: {
         'src/schema/types.ts': {
           plugins: ['typescript', 'typescript-resolvers'],
           config: {
             resolversNonOptionalTypename: {
               unionMember: true,
               excludeTypes: ['MyType']
             }
           }
         }
       }
     }
     

   • #9229 5aa95aa96 Thanks @eddeee888! - Use generic to simplify ResolversUnionTypes

     This follows the ResolversInterfaceTypes's approach where the RefType generic is used to refer back to ResolversTypes or ResolversParentTypes in cases of nested Union types

   • #9304 e1dc75f3c Thanks @esfomeado! - Added support for disabling suffixes on Enums.

   • #9229 5aa95aa96 Thanks @eddeee888! - Extract interfaces to ResolversInterfaceTypes and add to resolversNonOptionalTypename

     1. ResolversInterfaceTypes is a new type that keeps track of a GraphQL interface and its implementing types.

     For example, consider this schema:

     extend type Query {
       character(id: ID!): CharacterNode
     }
     
     interface CharacterNode {
       id: ID!
     }
     
     type Wizard implements CharacterNode {
       id: ID!
       screenName: String!
       spells: [String!]!
     }
     
     type Fighter implements CharacterNode {
       id: ID!
       screenName: String!
       powerLevel: Int!
     }
     

     The generated types will look like this:

     export type ResolversInterfaceTypes<RefType extends Record<string, unknown>> = {
       CharacterNode: Fighter | Wizard
     }
     
     export type ResolversTypes = {
       // other types...
       CharacterNode: ResolverTypeWrapper<ResolversInterfaceTypes<ResolversTypes>['CharacterNode']>
       Fighter: ResolverTypeWrapper<Fighter>
       Wizard: ResolverTypeWrapper<Wizard>
       // other types...
     }
     
     export type ResolversParentTypes = {
       // other types...
       CharacterNode: ResolversInterfaceTypes<ResolversParentTypes>['CharacterNode']
       Fighter: Fighter
       Wizard: Wizard
       // other types...
     }
     

     The RefType generic is used to reference back to ResolversTypes and ResolversParentTypes in some cases such as field returning a Union. 2. resolversNonOptionalTypename also affects ResolversInterfaceTypes

     Using the schema above, if we use resolversNonOptionalTypename option:

     const config: CodegenConfig = {
       schema: 'src/schema/**/*.graphql',
       generates: {
         'src/schema/types.ts': {
           plugins: ['typescript', 'typescript-resolvers'],
           config: {
             resolversNonOptionalTypename: true // Or `resolversNonOptionalTypename: { interfaceImplementingType: true }`
           }
         }
       }
     }
     

     Then, the generated type looks like this:

     export type ResolversInterfaceTypes<RefType extends Record<string, unknown>> = {
       CharacterNode: (Fighter & { __typename: 'Fighter' }) | (Wizard & { __typename: 'Wizard' })
     }
     
     export type ResolversTypes = {
       // other types...
       CharacterNode: ResolverTypeWrapper<ResolversInterfaceTypes<ResolversTypes>['CharacterNode']>
       Fighter: ResolverTypeWrapper<Fighter>
       Wizard: ResolverTypeWrapper<Wizard>
       // other types...
     }
     
     export type ResolversParentTypes = {
       // other types...
       CharacterNode: ResolversInterfaceTypes<ResolversParentTypes>['CharacterNode']
       Fighter: Fighter
       Wizard: Wizard
       // other types...
     }
     

   Patch Changes

   • #9449 4d9ea1a5a Thanks @n1ru4l! - dependencies updates:
     • Updated dependency @graphql-tools/utils@^10.0.0 ↗︎ (from ^9.0.0, in dependencies)
   • Updated dependencies [4d9ea1a5a, 4d9ea1a5a, f46803a8c, 3848a2b73, ba84a3a27, 63827fabe, 50471e651, 5aa95aa96, ca02ad172, e1dc75f3c, bb66c2a31, 5950f5a68, 5aa95aa96]:
     • @graphql-codegen/plugin-helpers@5.0.0
     • @graphql-codegen/visitor-plugin-common@4.0.0
     • @graphql-codegen/typescript@4.0.0