feat(graphql): add GraphQL mutation engine with name sanitization

Author: FionaBronwen

packages/graphql/package.json

@@ -38,6 +38,7 @@
   "dependencies": {
     "@alloy-js/core": "^0.11.0",
     "@alloy-js/typescript": "^0.11.0",
+    "change-case": "^5.4.4",
     "graphql": "^16.9.0"
   },
   "scripts": {
@@ -56,8 +57,9 @@
   ],
   "peerDependencies": {
     "@typespec/compiler": "workspace:~",
+    "@typespec/emitter-framework": "^0.5.0",
     "@typespec/http": "workspace:~",
-    "@typespec/emitter-framework": "^0.5.0"
+    "@typespec/mutator-framework": "workspace:~"
   },
   "devDependencies": {
     "@types/node": "~22.13.13",

packages/graphql/src/index.ts

@@ -1,3 +1,5 @@
 export { $onEmit } from "./emitter.js";
 export { $lib } from "./lib.js";
 export { $decorators } from "./tsp-index.js";
+
+export { createGraphQLMutationEngine } from "./mutation-engine/index.js";

packages/graphql/src/lib/type-utils.ts

@@ -25,12 +25,8 @@ import {
   type UnionStatementNode,
 } from "@typespec/compiler/ast";
 import { camelCase, constantCase, pascalCase, split, splitSeparateNumbers } from "change-case";
-import { GraphQLScalarType } from "graphql";
-
-export const ANY_SCALAR = new GraphQLScalarType({
-  name: "Any",
-});
 
+/** Generate a GraphQL type name for a templated model (e.g., `ListOfString`). */
 export function getTemplatedModelName(model: Model): string {
   const name = getTypeName(model, {});
   const baseName = toTypeName(name.replace(/<[^>]*>/g, ""));
@@ -56,12 +52,14 @@ function splitWithAcronyms(
   });
 }
 
+/** Convert a name to PascalCase for GraphQL type names. */
 export function toTypeName(name: string): string {
   return pascalCase(sanitizeNameForGraphQL(getNameWithoutNamespace(name)), {
     split: splitWithAcronyms.bind(null, split, false),
   });
 }
 
+/** Sanitize a name to be a valid GraphQL identifier. */
 export function sanitizeNameForGraphQL(name: string, prefix: string = ""): string {
   name = name.replace("[]", "Array");
   name = name.replaceAll(/\W/g, "_");
@@ -71,13 +69,15 @@ export function sanitizeNameForGraphQL(name: string, prefix: string = ""): strin
   return name;
 }
 
+/** Convert a name to CONSTANT_CASE for GraphQL enum members. */
 export function toEnumMemberName(enumName: string, name: string) {
   return constantCase(sanitizeNameForGraphQL(name, enumName), {
     split: splitSeparateNumbers,
     prefixCharacters: "_",
   });
 }
 
+/** Convert a name to camelCase for GraphQL field names. */
 export function toFieldName(name: string): string {
   return camelCase(sanitizeNameForGraphQL(name), {
     prefixCharacters: "_",
@@ -90,6 +90,7 @@ function getNameWithoutNamespace(name: string): string {
   return parts[parts.length - 1];
 }
 
+/** Generate a GraphQL type name for a union, including anonymous unions. */
 export function getUnionName(union: Union, program: Program): string {
   // SyntaxKind.UnionExpression: Foo | Bar
   // SyntaxKind.UnionStatement: union FooBarUnion { Foo, Bar }
@@ -169,33 +170,38 @@ function getUnionNameForOperation(program: Program, union: Union): string {
   return toTypeName(getTypeName(operation));
 }
 
+/** Convert a namespaced name to a single name by replacing dots with underscores. */
 export function getSingleNameWithNamespace(name: string): string {
   return name.trim().replace(/\./g, "_");
 }
 
-// TODO: To replace this with the type-utils isArrayModelType function
+/**
+ * Check if a model is an array type.
+ */
 export function isArray(model: Model): model is ArrayModelType {
   return Boolean(model.indexer && model.indexer.key.name === "integer");
 }
 
-// TODO: To replace this with the type-utils isRecordModelType function
-// The type-utils function takes an used program as an argument
-// and this function is used in the selector which does not have access to
-// the program
+/**
+ * Check if a model is a record/map type.
+ */
 export function isRecordType(type: Model): type is RecordModelType {
   return Boolean(type.indexer && type.indexer.key.name === "string");
 }
 
+/** Check if a model is an array of scalars or enums. */
 export function isScalarOrEnumArray(type: Model): type is ArrayModelType {
   return (
     isArray(type) && (type.indexer?.value.kind === "Scalar" || type.indexer?.value.kind === "Enum")
   );
 }
 
+/** Check if a model is an array of unions. */
 export function isUnionArray(type: Model): type is ArrayModelType {
   return isArray(type) && type.indexer?.value.kind === "Union";
 }
 
+/** Extract the element type from an array model, or return the model itself. */
 export function unwrapModel(model: ArrayModelType): Model | Scalar | Enum | Union;
 export function unwrapModel(model: Exclude<Model, ArrayModelType>): Model;
 export function unwrapModel(model: Model): Model | Scalar | Enum | Union {
@@ -212,6 +218,7 @@ export function unwrapModel(model: Model): Model | Scalar | Enum | Union {
   return model;
 }
 
+/** Unwrap array types to get the inner element type. */
 export function unwrapType(type: Model): Model | Scalar | Enum | Union;
 export function unwrapType(type: Type): Type;
 export function unwrapType(type: Type): Type {
@@ -221,6 +228,7 @@ export function unwrapType(type: Type): Type {
   return type;
 }
 
+/** Get the GraphQL description for a type from its doc comments. */
 export function getGraphQLDoc(program: Program, type: Type): string | undefined {
   // GraphQL uses CommonMark for descriptions
   // https://spec.graphql.org/October2021/#sec-Descriptions
@@ -239,11 +247,12 @@ ${getTypeName(type)}
 
   if (doc) {
     doc = doc.trim();
-    doc.replaceAll("\\n", "\n");
+    doc = doc.replaceAll("\\n", "\n");
   }
   return doc;
 }
 
+/** Generate a string representation of template arguments (e.g., `StringAndInt`). */
 export function getTemplateString(
   type: Type,
   options: { conjunction: string; prefix: string } = { conjunction: "And", prefix: "" },
@@ -264,6 +273,7 @@ function getTemplateStringInternal(
     : "";
 }
 
+/** Check if a model should be emitted as a GraphQL object type (not an array, record, or never). */
 export function isTrueModel(model: Model): boolean {
   /* eslint-disable no-fallthrough */
   switch (true) {

packages/graphql/src/mutation-engine/engine.ts

@@ -0,0 +1,112 @@
+import {
+  type Enum,
+  type Model,
+  type Namespace,
+  type Operation,
+  type Program,
+  type Scalar,
+} from "@typespec/compiler";
+import { $ } from "@typespec/compiler/typekit";
+import {
+  MutationEngine,
+  SimpleInterfaceMutation,
+  SimpleIntrinsicMutation,
+  SimpleLiteralMutation,
+  SimpleUnionMutation,
+  SimpleUnionVariantMutation,
+} from "@typespec/mutator-framework";
+import {
+  GraphQLEnumMemberMutation,
+  GraphQLEnumMutation,
+  GraphQLModelMutation,
+  GraphQLModelPropertyMutation,
+  GraphQLOperationMutation,
+  GraphQLScalarMutation,
+} from "./mutations/index.js";
+import { GraphQLMutationOptions } from "./options.js";
+
+/**
+ * Registry configuration for the GraphQL mutation engine.
+ * Maps TypeSpec type kinds to their corresponding GraphQL mutation classes.
+ */
+const graphqlMutationRegistry = {
+  // Custom GraphQL mutations for types we need to transform
+  Enum: GraphQLEnumMutation,
+  EnumMember: GraphQLEnumMemberMutation,
+  Model: GraphQLModelMutation,
+  ModelProperty: GraphQLModelPropertyMutation,
+  Operation: GraphQLOperationMutation,
+  Scalar: GraphQLScalarMutation,
+  // Use Simple* classes from mutator-framework for types we don't customize
+  Interface: SimpleInterfaceMutation,
+  Union: SimpleUnionMutation,
+  UnionVariant: SimpleUnionVariantMutation,
+  String: SimpleLiteralMutation,
+  Number: SimpleLiteralMutation,
+  Boolean: SimpleLiteralMutation,
+  Intrinsic: SimpleIntrinsicMutation,
+};
+
+/**
+ * GraphQL mutation engine that applies GraphQL-specific transformations
+ * to TypeSpec types, such as name sanitization.
+ */
+export class GraphQLMutationEngine {
+  /**
+   * The underlying mutation engine configured with GraphQL-specific mutation classes.
+   * Type is inferred from graphqlMutationRegistry to avoid complex generic constraints.
+   */
+  private engine;
+
+  constructor(program: Program, _namespace: Namespace) {
+    const tk = $(program);
+    this.engine = new MutationEngine(tk, graphqlMutationRegistry);
+  }
+
+  /**
+   * Mutate a model, applying GraphQL name sanitization.
+   */
+  mutateModel(model: Model): GraphQLModelMutation {
+    const mutation = this.engine.mutate(model, new GraphQLMutationOptions());
+    // Cast needed: engine returns base Mutation type, but registry ensures GraphQLModelMutation
+    return mutation as unknown as GraphQLModelMutation;
+  }
+
+  /**
+   * Mutate an enum, applying GraphQL name sanitization.
+   */
+  mutateEnum(enumType: Enum): GraphQLEnumMutation {
+    const mutation = this.engine.mutate(enumType, new GraphQLMutationOptions());
+    // Cast needed: engine returns base Mutation type, but registry ensures GraphQLEnumMutation
+    return mutation as unknown as GraphQLEnumMutation;
+  }
+
+  /**
+   * Mutate an operation, applying GraphQL name sanitization.
+   */
+  mutateOperation(operation: Operation): GraphQLOperationMutation {
+    const mutation = this.engine.mutate(operation, new GraphQLMutationOptions());
+    // Cast needed: engine returns base Mutation type, but registry ensures GraphQLOperationMutation
+    return mutation as unknown as GraphQLOperationMutation;
+  }
+
+  /**
+   * Mutate a scalar, applying GraphQL name sanitization.
+   */
+  mutateScalar(scalar: Scalar): GraphQLScalarMutation {
+    const mutation = this.engine.mutate(scalar, new GraphQLMutationOptions());
+    // Cast needed: engine returns base Mutation type, but registry ensures GraphQLScalarMutation
+    return mutation as unknown as GraphQLScalarMutation;
+  }
+}
+
+/**
+ * Creates a GraphQL mutation engine for the given program and namespace.
+ */
+export function createGraphQLMutationEngine(
+  program: Program,
+  namespace: Namespace,
+): GraphQLMutationEngine {
+  return new GraphQLMutationEngine(program, namespace);
+}
+

packages/graphql/src/mutation-engine/index.ts

@@ -0,0 +1,10 @@
+export { GraphQLMutationEngine, createGraphQLMutationEngine } from "./engine.js";
+export {
+  GraphQLEnumMemberMutation,
+  GraphQLEnumMutation,
+  GraphQLModelMutation,
+  GraphQLModelPropertyMutation,
+  GraphQLOperationMutation,
+  GraphQLScalarMutation,
+} from "./mutations/index.js";
+export { GraphQLMutationOptions } from "./options.js";

packages/graphql/src/mutation-engine/mutations/enum-member.ts

@@ -0,0 +1,56 @@
+import type { EnumMember, MemberType } from "@typespec/compiler";
+import {
+  EnumMemberMutation,
+  EnumMemberMutationNode,
+  MutationEngine,
+  type MutationInfo,
+  type MutationOptions,
+} from "@typespec/mutator-framework";
+import { sanitizeNameForGraphQL } from "../../lib/type-utils.js";
+
+/**
+ * GraphQL-specific EnumMember mutation.
+ */
+export class GraphQLEnumMemberMutation extends EnumMemberMutation<
+  MutationOptions,
+  any,
+  MutationEngine<any>
+> {
+  #mutationNode: EnumMemberMutationNode;
+
+  constructor(
+    engine: MutationEngine<any>,
+    sourceType: EnumMember,
+    referenceTypes: MemberType[],
+    options: MutationOptions,
+    info: MutationInfo,
+  ) {
+    super(engine, sourceType, referenceTypes, options, info);
+    this.#mutationNode = this.engine.getMutationNode(this.sourceType, {
+      mutationKey: info.mutationKey,
+      isSynthetic: info.isSynthetic,
+    }) as EnumMemberMutationNode;
+    // Register rename callback BEFORE any edge connections trigger mutation.
+    // whenMutated fires when the node is mutated (even via edge propagation),
+    // ensuring the name is sanitized before edge callbacks read it.
+    this.#mutationNode.whenMutated((member) => {
+      if (member) {
+        member.name = sanitizeNameForGraphQL(member.name);
+      }
+    });
+  }
+
+  get mutationNode() {
+    return this.#mutationNode;
+  }
+
+  get mutatedType() {
+    return this.#mutationNode.mutatedType;
+  }
+
+  mutate() {
+    // Trigger mutation if not already mutated (whenMutated callback will run)
+    this.#mutationNode.mutate();
+    super.mutate();
+  }
+}