small refactors

Author: danadajian

bun.lockb

@@ -5,5 +5,5 @@ sidebar_position: 3
 # Configuration
 
 ```ts reference title="Config Schema"
-https://github.com/ExpediaGroup/graphql-kotlin-codegen/blob/main/src/config.ts#L17-L100000
+https://github.com/ExpediaGroup/graphql-kotlin-codegen/blob/main/src/config.ts#L1-L100000
 ```

docs/docs/configuration.md

@@ -13,6 +13,7 @@ export default [
       },
     },
     rules: {
+      "no-console": "error",
       "@typescript-eslint/no-non-null-assertion": "error",
       "@typescript-eslint/no-unsafe-argument": "error",
       "@typescript-eslint/no-unsafe-call": "error",

eslint.config.js

@@ -28,7 +28,7 @@
     "@graphql-codegen/cli": "5.0.2",
     "@total-typescript/ts-reset": "0.5.1",
     "bun-types": "1.1.4",
-    "eslint": "9.1.0",
+    "eslint": "9.1.1",
     "husky": "9.0.11",
     "prettier": "3.2.5",
     "tsup": "8.0.2",
@@ -39,7 +39,7 @@
     "build": "tsup src/plugin.ts --clean --dts --external graphql",
     "format": "prettier --write .",
     "format-check": "prettier --check .",
-    "integration": "bun run build && graphql-codegen && ./gradlew compileTestKotlin",
+    "integration": "bun run build && graphql-codegen && ./gradlew build",
     "lint": "eslint .",
     "prepack": "bun run build",
     "prepare": "husky",

package.json

@@ -22,7 +22,6 @@ import {
   union,
 } from "valibot";
 import { Kind } from "graphql";
-import { buildConfigWithDefaults } from "./helpers/build-config-with-defaults";
 
 export const configSchema = object({
   /**
@@ -46,11 +45,11 @@ export const configSchema = object({
   dependentTypesInScope: optional(array(string())),
   /**
    * Denotes Kotlin classes representing union types to be treated as interfaces rather than annotation classes.
-   * This should be used for types outside `dependentTypesInScope` that are not generated by the plugin.
+   * @description This should be used for types outside `dependentTypesInScope` that are not generated by the plugin. Only use when unionGeneration is set to `ANNOTATION_CLASS`.
    */
   externalUnionsAsInterfaces: optional(array(string())),
   /**
-   * Additional imports to add to the generated file.
+   * Additional imports to add to the generated file. GraphQL Kotlin annotations are always imported.
    * @example ["com.example.additional.import.*"]
    */
   extraImports: optional(array(string())),
@@ -133,13 +132,12 @@ export const configSchema = object({
   ),
   /**
    * Denotes the generation strategy for union types. Defaults to `MARKER_INTERFACE`.
+   *
    * https://opensource.expediagroup.com/graphql-kotlin/docs/schema-generator/writing-schemas/unions/
+   *
+   * @description The `MARKER_INTERFACE` option is highly recommended, since it is slightly more type-safe than using annotation classes.
    */
   unionGeneration: optional(
     union([literal("ANNOTATION_CLASS"), literal("MARKER_INTERFACE")]),
   ),
 });
-
-export type CodegenConfigWithDefaults = ReturnType<
-  typeof buildConfigWithDefaults
->;

src/config.ts

@@ -15,7 +15,7 @@ import { EnumTypeDefinitionNode, EnumValueDefinitionNode } from "graphql";
 import { indentMultiline } from "@graphql-codegen/visitor-plugin-common";
 import { buildAnnotations } from "../helpers/build-annotations";
 import { shouldIncludeTypeDefinition } from "../helpers/should-include-type-definition";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "../helpers/build-config-with-defaults";
 
 export function buildEnumTypeDefinition(
   node: EnumTypeDefinitionNode,

src/definitions/enum.ts

@@ -16,7 +16,7 @@ import { shouldIncludeTypeDefinition } from "../helpers/should-include-type-defi
 import { buildTypeMetadata } from "../helpers/build-type-metadata";
 import { buildAnnotations } from "../helpers/build-annotations";
 import { indent } from "@graphql-codegen/visitor-plugin-common";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "../helpers/build-config-with-defaults";
 
 export function buildInputObjectDefinition(
   node: InputObjectTypeDefinitionNode,
@@ -47,7 +47,6 @@ export function buildInputObjectDefinition(
 
   const annotations = buildAnnotations({
     config,
-    inputDescription: node.description?.value,
     definitionNode: node,
   });
 

src/definitions/input.ts

@@ -17,7 +17,7 @@ import { indent } from "@graphql-codegen/visitor-plugin-common";
 import { buildTypeMetadata } from "../helpers/build-type-metadata";
 import { shouldIncludeTypeDefinition } from "../helpers/should-include-type-definition";
 import { buildFieldDefinition } from "../helpers/build-field-definition";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "../helpers/build-config-with-defaults";
 
 export function buildInterfaceDefinition(
   node: InterfaceTypeDefinitionNode,

src/definitions/interface.ts

@@ -23,7 +23,7 @@ import {
 import { isResolverType } from "../helpers/is-resolver-type";
 import { buildFieldDefinition } from "../helpers/build-field-definition";
 import { isExternalField } from "../helpers/is-external-field";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "../helpers/build-config-with-defaults";
 
 export function buildObjectTypeDefinition(
   node: ObjectTypeDefinitionNode,
@@ -42,27 +42,27 @@ export function buildObjectTypeDefinition(
   const dependentInterfaces = getDependentInterfaceNames(node);
   const dependentUnions = getDependentUnionsForType(schema, node);
   const interfacesToInherit =
-    config.unionGeneration === "ANNOTATION_CLASS"
-      ? dependentInterfaces
-      : dependentInterfaces.concat(dependentUnions);
+    config.unionGeneration === "MARKER_INTERFACE"
+      ? dependentInterfaces.concat(dependentUnions)
+      : dependentInterfaces;
   const interfaceInheritance = `${interfacesToInherit.length ? ` : ${interfacesToInherit.join(", ")}` : ""}`;
 
   if (isResolverType(node, config)) {
     return `${annotations}@GraphQLIgnore\ninterface ${name}${interfaceInheritance} {
-${getClassMembers({ node, schema, config })}
+${getDataClassMembers({ node, schema, config })}
 }
 
 ${annotations}@GraphQLIgnore\ninterface ${name}CompletableFuture {
-${getClassMembers({ node, schema, config, completableFuture: true })}
+${getDataClassMembers({ node, schema, config, completableFuture: true })}
 }`;
   }
 
   return `${annotations}data class ${name}(
-${getClassMembers({ node, schema, config })}
+${getDataClassMembers({ node, schema, config })}
 )${interfaceInheritance}`;
 }
 
-function getClassMembers({
+function getDataClassMembers({
   node,
   schema,
   config,

src/definitions/object.ts

@@ -13,8 +13,7 @@ limitations under the License.
 
 import { UnionTypeDefinitionNode } from "graphql";
 import { shouldIncludeTypeDefinition } from "../helpers/should-include-type-definition";
-import { buildDirectiveAnnotations } from "../helpers/build-directive-annotations";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "../helpers/build-config-with-defaults";
 import {
   buildAnnotations,
   trimDescription,
@@ -31,17 +30,16 @@ export function buildUnionTypeDefinition(
     config,
     definitionNode: node,
   });
-  if (config.unionGeneration === "ANNOTATION_CLASS") {
-    const directiveAnnotations = buildDirectiveAnnotations(node, config);
-    const possibleTypes =
-      node.types?.map((type) => `${type.name.value}::class`).join(", ") || "";
-    return `${directiveAnnotations}@GraphQLUnion(
+  if (config.unionGeneration === "MARKER_INTERFACE") {
+    return `${annotations}interface ${node.name.value}`;
+  }
+
+  const possibleTypes =
+    node.types?.map((type) => `${type.name.value}::class`).join(", ") || "";
+  return `${annotations}@GraphQLUnion(
     name = "${node.name.value}",
     possibleTypes = [${possibleTypes}],
     description = "${trimDescription(node.description?.value)}"
 )
 annotation class ${node.name.value}`;
-  }
-
-  return `${annotations}interface ${node.name.value}`;
 }

src/definitions/union.ts

@@ -11,26 +11,26 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "./build-config-with-defaults";
 import { getDependentTypeNames } from "./get-dependent-type-names";
-import { dependentTypeIsInScope } from "./dependent-type-is-in-scope";
 import { GraphQLSchema } from "graphql";
 
-export function addDependentTypes(
+export function addDependentTypesToOnlyTypes(
   config: CodegenConfigWithDefaults,
   schema: GraphQLSchema,
 ) {
   if (!config.onlyTypes) {
-    throw new Error(`config.onlyTypes is required to add dependent types`);
+    throw new Error(`onlyTypes config is required to add dependent types`);
   }
   const onlyTypesNodes = config.onlyTypes
     .map((typeName) => schema.getType(typeName)?.astNode)
     .filter(Boolean);
   const dependentTypeNames = onlyTypesNodes.flatMap((node) =>
     getDependentTypeNames(schema, node, config),
   );
-  const dependentTypesInScope = dependentTypeNames.filter((typeName) =>
-    dependentTypeIsInScope(typeName, config),
-  );
+  const typesInScope = config.dependentTypesInScope;
+  const dependentTypesInScope = typesInScope
+    ? dependentTypeNames.filter((typeName) => typesInScope.includes(typeName))
+    : dependentTypeNames;
   config.onlyTypes.push(...dependentTypesInScope);
 }

src/helpers/add-dependent-types.ts renamed to src/helpers/add-dependent-types-to-only-types.ts

@@ -18,8 +18,9 @@ import {
   InputValueDefinitionNode,
   TypeDefinitionNode,
 } from "graphql";
+import { buildDescriptionAnnotation } from "./build-description-annotation";
 import { buildDirectiveAnnotations } from "./build-directive-annotations";
-import { CodegenConfigWithDefaults } from "../config";
+import { CodegenConfigWithDefaults } from "./build-config-with-defaults";
 import { TypeMetadata } from "./build-type-metadata";
 
 export type DefinitionNode =
@@ -30,37 +31,24 @@ export type DefinitionNode =
 
 export function buildAnnotations({
   config,
-  inputDescription,
   definitionNode,
   resolvedType,
 }: {
   config: CodegenConfigWithDefaults;
-  inputDescription?: string;
-  definitionNode?: DefinitionNode;
+  definitionNode: DefinitionNode;
   resolvedType?: TypeMetadata;
 }) {
-  const description =
-    inputDescription ?? definitionNode?.description?.value ?? "";
-  const isDeprecated = isDeprecatedDescription(description, resolvedType);
-  const descriptionAnnotator = isDeprecated
-    ? "@Deprecated"
-    : "@GraphQLDescription";
-  const descriptionValue = isDeprecated
-    ? description.replace("DEPRECATED: ", "")
-    : description;
-  const trimmedDescription = trimDescription(descriptionValue);
-  const descriptionAnnotation = description
-    ? `${descriptionAnnotator}("${trimmedDescription}")\n`
-    : "";
-
-  const directiveAnnotations = definitionNode
-    ? buildDirectiveAnnotations(
-        definitionNode,
-        config,
-        description,
-        resolvedType,
-      )
-    : "";
+  const description = definitionNode?.description?.value ?? "";
+  const descriptionAnnotation = buildDescriptionAnnotation(
+    description,
+    definitionNode,
+    config,
+    resolvedType,
+  );
+  const directiveAnnotations = buildDirectiveAnnotations(
+    definitionNode,
+    config,
+  );
   const unionAnnotation = resolvedType?.unionAnnotation
     ? `@${resolvedType.unionAnnotation}\n`
     : "";
@@ -84,15 +72,6 @@ export function buildAnnotations({
   );
 }
 
-export function isDeprecatedDescription(
-  description?: string,
-  resolvedType?: TypeMetadata,
-) {
-  return (
-    description?.startsWith("DEPRECATED: ") && !resolvedType?.unionAnnotation
-  );
-}
-
 export function trimDescription(description?: string) {
   return (
     description

src/helpers/build-annotations.ts

@@ -13,7 +13,11 @@ export function buildConfigWithDefaults(
     ...config,
     extraImports: [
       "com.expediagroup.graphql.generator.annotations.*",
-      ...(config.extraImports ?? ([] satisfies string[])),
+      ...(config.extraImports ?? []),
     ],
   } as const;
 }
+
+export type CodegenConfigWithDefaults = ReturnType<
+  typeof buildConfigWithDefaults
+>;

src/helpers/build-config-with-defaults.ts

@@ -0,0 +1,60 @@
+import { CodegenConfigWithDefaults } from "./build-config-with-defaults";
+import { TypeMetadata } from "./build-type-metadata";
+import { indent } from "@graphql-codegen/visitor-plugin-common";
+import { Kind } from "graphql/index";
+import { DefinitionNode, trimDescription } from "./build-annotations";
+
+export function buildDescriptionAnnotation(
+  description: string,
+  definitionNode: DefinitionNode,
+  config: CodegenConfigWithDefaults,
+  resolvedType?: TypeMetadata,
+) {
+  const trimmedDescription = trimDescription(description);
+  const isDeprecatedDescription = trimmedDescription.startsWith(
+    deprecatedDescriptionPrefix,
+  );
+  if (isDeprecatedDescription && resolvedType?.unionAnnotation) {
+    return `@GraphQLDescription("${trimmedDescription}")\n`;
+  } else if (isDeprecatedDescription) {
+    const descriptionValue = description.replace(
+      deprecatedDescriptionPrefix,
+      "",
+    );
+    return `@Deprecated("${trimDescription(descriptionValue)}")\n`;
+  }
+
+  const deprecatedDirective = definitionNode.directives?.find(
+    (directive) => directive.name.value === "deprecated",
+  );
+  const deprecatedReasonNode = deprecatedDirective?.arguments?.find(
+    (arg) => arg.name.value === "reason",
+  )?.value;
+  const deprecatedReason =
+    deprecatedReasonNode?.kind === "StringValue"
+      ? deprecatedReasonNode.value
+      : "";
+  const trimmedDeprecatedReason = trimDescription(deprecatedReason);
+
+  if (deprecatedDirective && resolvedType?.unionAnnotation) {
+    return `@GraphQLDescription("${trimmedDeprecatedReason}")\n`;
+  } else if (deprecatedDirective) {
+    const graphqlDescription = trimmedDescription
+      ? `@GraphQLDescription("${trimmedDescription}")\n`
+      : "";
+    const deprecatedDescription = `@Deprecated("${trimmedDeprecatedReason}")\n`;
+    return `${graphqlDescription}${graphqlDescription ? indent(deprecatedDescription, 2) : deprecatedDescription}`;
+  }
+
+  if (
+    trimmedDescription &&
+    (config.unionGeneration === "MARKER_INTERFACE" ||
+      definitionNode?.kind !== Kind.UNION_TYPE_DEFINITION)
+  ) {
+    return `@GraphQLDescription("${trimmedDescription}")\n`;
+  }
+
+  return "";
+}
+
+const deprecatedDescriptionPrefix = "DEPRECATED: ";