[typescript-operations] Add declarationKind support (#10654)

* typescript-operations: Add support for declarationKind option

* Drive-by: add fixme

* Add changeset

Author: eddeee888

.changeset/beige-pets-talk.md

@@ -0,0 +1,11 @@
+---
+'@graphql-codegen/visitor-plugin-common': minor
+'@graphql-codegen/typescript-operations': minor
+---
+
+Add support for declarationKind for typescript-operations
+
+- Input: can only be `type` or  `interface`
+- Variables: no support. It must always be `type` because it's an alias e.g. `Variables = Exact<{ something: type }>`
+- Result: can only be `type` or `interface`
+  - Note: when `extractAllFieldsToTypes:true` or `extractAllFieldsToTypesCompact:true`, Results are used as type alias, so they are forced to be `type`. There is a console warning for users.

packages/plugins/other/visitor-plugin-common/src/base-documents-visitor.ts

@@ -13,6 +13,11 @@ import { SelectionSetToObject } from './selection-set-to-object.js';
 import { NormalizedScalarsMap, CustomDirectivesConfig } from './types.js';
 import { buildScalarsFromConfig, DeclarationBlock, DeclarationBlockConfig, getConfigValue } from './utils.js';
 import { OperationVariablesToObject } from './variables-to-object.js';
+import {
+  normalizeOperationDeclarationKind,
+  type OperationDeclarationKind,
+  type OperationDeclarationKindConfig,
+} from './operation-declaration-kinds.js';
 
 export interface ParsedDocumentsConfig extends ParsedConfig {
   extractAllFieldsToTypes: boolean;
@@ -30,6 +35,7 @@ export interface ParsedDocumentsConfig extends ParsedConfig {
   generateOperationTypes: boolean;
   importSchemaTypesFrom: string;
   namespacedImportName: string | null;
+  declarationKind: OperationDeclarationKindConfig;
 }
 
 export interface RawDocumentsConfig extends RawConfig {
@@ -248,6 +254,52 @@ export interface RawDocumentsConfig extends RawConfig {
    * When this option is enabled, `extractAllFieldsToTypes` is automatically enabled as well.
    */
   extractAllFieldsToTypesCompact?: boolean;
+  /**
+   * @description Overrides the default output for various GraphQL types.
+   * @default 'type'
+   * @exampleMarkdown
+   * ## Override all declarations
+   *
+   * ```ts filename="codegen.ts"
+   *  import type { CodegenConfig } from '@graphql-codegen/cli';
+   *
+   *  const config: CodegenConfig = {
+   *    // ...
+   *    generates: {
+   *      'path/to/file': {
+   *        // plugins...
+   *        config: {
+   *          declarationKind: 'interface'
+   *        },
+   *      },
+   *    },
+   *  };
+   *  export default config;
+   * ```
+   *
+   * ## Override only specific declarations
+   *
+   * ```ts filename="codegen.ts"
+   *  import type { CodegenConfig } from '@graphql-codegen/cli';
+   *
+   *  const config: CodegenConfig = {
+   *    // ...
+   *    generates: {
+   *      'path/to/file': {
+   *        // plugins...
+   *        config: {
+   *          declarationKind: {
+   *            input: 'interface',
+   *            result: 'type'
+   *          }
+   *        },
+   *      },
+   *    },
+   *  };
+   *  export default config;
+   * ```
+   */
+  declarationKind?: OperationDeclarationKind | Partial<OperationDeclarationKindConfig>;
 }
 
 export class BaseDocumentsVisitor<
@@ -266,6 +318,17 @@ export class BaseDocumentsVisitor<
     defaultScalars: NormalizedScalarsMap = DEFAULT_INPUT_SCALARS
   ) {
     const importSchemaTypesFrom = getConfigValue(rawConfig.importSchemaTypesFrom, '');
+    const extractAllFieldsToTypes =
+      getConfigValue(rawConfig.extractAllFieldsToTypes, false) ||
+      getConfigValue(rawConfig.extractAllFieldsToTypesCompact, false);
+    const declarationKind = normalizeOperationDeclarationKind(getConfigValue(rawConfig.declarationKind, 'type'));
+    if (extractAllFieldsToTypes) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "`declarationKind.result` has been set to `'type'` because `extractAllFieldsToTypes` or `extractAllFieldsToTypesCompact` is true"
+      );
+      declarationKind.result = 'type';
+    }
 
     super(rawConfig, {
       exportFragmentSpreadSubTypes: getConfigValue(rawConfig.exportFragmentSpreadSubTypes, false),
@@ -281,10 +344,9 @@ export class BaseDocumentsVisitor<
       generateOperationTypes: getConfigValue(rawConfig.generateOperationTypes, true),
       importSchemaTypesFrom,
       namespacedImportName: getConfigValue(rawConfig.namespacedImportName, importSchemaTypesFrom ? 'Types' : null),
-      extractAllFieldsToTypes:
-        getConfigValue(rawConfig.extractAllFieldsToTypes, false) ||
-        getConfigValue(rawConfig.extractAllFieldsToTypesCompact, false),
+      extractAllFieldsToTypes,
       extractAllFieldsToTypesCompact: getConfigValue(rawConfig.extractAllFieldsToTypesCompact, false),
+      declarationKind,
       ...((additionalConfig || {}) as any),
     });
 
@@ -404,7 +466,7 @@ export class BaseDocumentsVisitor<
       ? ''
       : new DeclarationBlock(this._declarationBlockConfig)
           .export()
-          .asKind('type')
+          .asKind(this.config.declarationKind.result)
           .withName(operationResultName)
           .withContent(selectionSetObjects.mergedTypeString).string;
 
@@ -413,7 +475,7 @@ export class BaseDocumentsVisitor<
       blockTransformer: t => this.applyVariablesWrapper(t, operationType),
     })
       .export()
-      .asKind('type')
+      .asKind('type') // Variables must always be `'type'` because it is an alias of `Exact<Something>`
       .withName(
         this.convertName(name, {
           suffix: operationTypeSuffix + 'Variables',
@@ -426,7 +488,7 @@ export class BaseDocumentsVisitor<
           i =>
             new DeclarationBlock(this._declarationBlockConfig)
               .export()
-              .asKind('type')
+              .asKind('type') // dependentTypes must always be `'type'` because they are alias types
               .withName(i.name)
               .withContent(i.content).string
         )

packages/plugins/other/visitor-plugin-common/src/index.ts

@@ -5,6 +5,7 @@ export * from './base-types-visitor.js';
 export * from './base-visitor.js';
 export * from './client-side-base-visitor.js';
 export * from './declaration-kinds.js';
+export * from './operation-declaration-kinds.js';
 export * from './enum-values.js';
 export * from './imports.js';
 export * from './mappers.js';

packages/plugins/other/visitor-plugin-common/src/operation-declaration-kinds.ts

@@ -0,0 +1,27 @@
+export type OperationDeclarationKind = 'type' | 'interface';
+
+export type OperationDeclarationKindConfig = {
+  input: OperationDeclarationKind;
+  result: OperationDeclarationKind; // Query, Mutation, Subscription
+};
+
+const DEFAULT_OPERATION_DECLARATION_KINDS: OperationDeclarationKindConfig = {
+  input: 'type',
+  result: 'type',
+};
+
+export function normalizeOperationDeclarationKind(
+  declarationKind: OperationDeclarationKind | Partial<OperationDeclarationKindConfig>
+): OperationDeclarationKindConfig {
+  if (typeof declarationKind === 'string') {
+    return {
+      input: declarationKind,
+      result: declarationKind,
+    };
+  }
+
+  return {
+    ...DEFAULT_OPERATION_DECLARATION_KINDS,
+    ...declarationKind,
+  };
+}

packages/plugins/typescript/operations/src/config.avoidOptionals.ts

@@ -9,6 +9,9 @@ export interface AvoidOptionalsConfig {
 }
 export type NormalizedAvoidOptionalsConfig = Required<AvoidOptionalsConfig>;
 
+// FIXME:
+// 1. bring this to visitor-plugin-common
+// 2. param should not be optional
 export const normalizeAvoidOptionals = (
   avoidOptionals?: boolean | AvoidOptionalsConfig
 ): NormalizedAvoidOptionalsConfig => {

packages/plugins/typescript/operations/src/visitor.ts

@@ -248,15 +248,15 @@ export class TypeScriptDocumentsVisitor extends BaseDocumentsVisitor<
     if (isOneOfInputObjectType(this._schema.getType(inputTypeName))) {
       return new DeclarationBlock(this._declarationBlockConfig)
         .export()
-        .asKind('type')
+        .asKind(this.config.declarationKind.input)
         .withName(this.convertName(node))
         .withComment(node.description?.value)
         .withContent(`\n` + (node.fields || []).join('\n  |')).string;
     }
 
     return new DeclarationBlock(this._declarationBlockConfig)
       .export()
-      .asKind('type')
+      .asKind(this.config.declarationKind.input)
       .withName(this.convertName(node))
       .withComment(node.description?.value)
       .withBlock((node.fields || []).join('\n')).string;