Replace state maps with decorators for mutation engine metadata

Author: FionaBronwen

packages/graphql/lib/main.tsp

@@ -1,4 +1,6 @@
 import "./interface.tsp";
+import "./nullable.tsp";
+import "./one-of.tsp";
 import "./operation-fields.tsp";
 import "./operation-kind.tsp";
 import "./scalars.tsp";

packages/graphql/lib/nullable.tsp

@@ -0,0 +1,22 @@
+import "../dist/src/lib/nullable.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec.GraphQL;
+
+/**
+ * Mark a field, operation, or type as nullable in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it strips `| null` from
+ * union types. The decorator's presence on the type's `decorators` array is
+ * the signal — the implementation is a no-op.
+ */
+extern dec nullable(target: ModelProperty | Operation | Union | Model);
+
+/**
+ * Mark a field as having nullable array elements in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it detects `Array<T | null>`
+ * patterns. Causes the emitter to emit `[T]` instead of `[T!]`.
+ */
+extern dec nullableElements(target: ModelProperty);

packages/graphql/lib/one-of.tsp

@@ -0,0 +1,16 @@
+import "../dist/src/lib/one-of.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec.GraphQL;
+
+/**
+ * Mark a model as a `@oneOf` input object in the emitted GraphQL schema.
+ *
+ * This decorator is applied automatically by the mutation engine when it converts
+ * a union type in input context to a synthetic input object (since GraphQL unions
+ * are output-only). The emitter uses this to emit the `@oneOf` directive.
+ *
+ * @see https://spec.graphql.org/September2025/#sec-OneOf-Input-Objects
+ */
+extern dec oneOf(target: Model);

packages/graphql/src/lib.ts

@@ -174,11 +174,6 @@ export const libDef = {
     interface: { description: "State for the @Interface decorator." },
     schema: { description: "State for the @schema decorator." },
     specifiedBy: { description: "State for the @specifiedBy decorator." },
-    oneOf: { description: "State for tracking @oneOf input objects created from input unions." },
-    nullable: {
-      description:
-        "State for tracking types that were determined to be nullable from null-variant stripping.",
-    },
   },
 } as const;
 

packages/graphql/src/lib/nullable.ts

@@ -1,21 +1,80 @@
-import type { Program, Type } from "@typespec/compiler";
-import { useStateSet } from "@typespec/compiler/utils";
-import { GraphQLKeys } from "../lib.js";
+import type {
+  DecoratedType,
+  DecoratorContext,
+  DecoratorFunction,
+  Model,
+  ModelProperty,
+  Operation,
+  Type,
+  Union,
+} from "@typespec/compiler";
+import { NAMESPACE } from "../lib.js";
 
-const [getNullableState, setNullableState] = useStateSet<Type>(GraphQLKeys.nullable);
+// This will set the namespace for decorators implemented in this file
+export const namespace = NAMESPACE;
 
 /**
- * Check if a type has been marked as nullable due to null-variant stripping.
- * For example, `Cat | Dog | null` becomes `union CatDog` marked as nullable.
+ * Decorator implementation for `@nullable`.
+ *
+ * No-op — the decorator's presence on the type's `decorators` array is the
+ * signal. No additional state storage is needed.
  */
-export function isNullable(program: Program, type: Type): boolean {
-  return getNullableState(program, type);
+export const $nullable: DecoratorFunction = (
+  _context: DecoratorContext,
+  _target: ModelProperty | Operation | Union | Model,
+) => {};
+
+/**
+ * Decorator implementation for `@nullableElements`.
+ *
+ * No-op — presence on the decorators array is the signal.
+ */
+export const $nullableElements: DecoratorFunction = (
+  _context: DecoratorContext,
+  _target: ModelProperty,
+) => {};
+
+/**
+ * Check whether a type was marked nullable after null-variant stripping.
+ *
+ * Marked on different targets depending on context:
+ * - **ModelProperty**: inline `T | null` (can't mark the shared scalar singleton)
+ * - **Operation**: return type `T | null`
+ * - **Union**: named unions like `Cat | Dog | null` (safe — new unique object)
+ */
+export function isNullable(type: Type): boolean {
+  if (!isDecoratedType(type)) return false;
+  return type.decorators.some((d) => d.decorator === $nullable);
+}
+
+/**
+ * Mark a type, property, or operation as nullable.
+ * Called by the mutation engine when null variants are stripped.
+ */
+export function setNullable(type: Type): void {
+  if (!isDecoratedType(type)) return;
+  if (type.decorators.some((d) => d.decorator === $nullable)) return;
+  type.decorators.push({ decorator: $nullable, args: [] });
 }
 
 /**
- * Mark a type as nullable. Called by the mutation engine when null variants
- * are stripped from a union during processing.
+ * Check whether a property's array elements were originally `T | null`.
+ *
+ * For `(string | null)[]`, marks the ModelProperty so components emit
+ * `[String]` instead of `[String!]`.
  */
-export function setNullable(program: Program, type: Type): void {
-  setNullableState(program, type);
+export function hasNullableElements(type: Type): boolean {
+  if (!isDecoratedType(type)) return false;
+  return type.decorators.some((d) => d.decorator === $nullableElements);
+}
+
+/** Mark a property as having nullable array elements. */
+export function setNullableElements(type: Type): void {
+  if (!isDecoratedType(type)) return;
+  if (type.decorators.some((d) => d.decorator === $nullableElements)) return;
+  type.decorators.push({ decorator: $nullableElements, args: [] });
+}
+
+function isDecoratedType(type: Type): type is Type & DecoratedType {
+  return "decorators" in type;
 }

packages/graphql/src/lib/one-of.ts

@@ -1,22 +1,34 @@
-import type { Model, Program } from "@typespec/compiler";
-import { useStateSet } from "@typespec/compiler/utils";
-import { GraphQLKeys } from "../lib.js";
+import type { DecoratorContext, DecoratorFunction, Model } from "@typespec/compiler";
+import { NAMESPACE } from "../lib.js";
 
-const [getOneOfState, setOneOfState] = useStateSet<Model>(GraphQLKeys.oneOf);
+// This will set the namespace for decorators implemented in this file
+export const namespace = NAMESPACE;
+
+/**
+ * Decorator implementation for `@oneOf`.
+ *
+ * No-op — the decorator's presence on the type's `decorators` array is the
+ * signal. No additional state storage is needed.
+ */
+export const $oneOf: DecoratorFunction = (
+  _context: DecoratorContext,
+  _target: Model,
+) => {};
 
 /**
  * Check if a model has been marked as a @oneOf input object.
  * These are synthetic models created by the union mutation when a union
  * is used in input context — GraphQL unions are output-only, so input
  * unions become @oneOf input objects.
  */
-export function isOneOf(program: Program, model: Model): boolean {
-  return getOneOfState(program, model);
+export function isOneOf(model: Model): boolean {
+  return model.decorators.some((d) => d.decorator === $oneOf);
 }
 
 /**
  * Mark a model as a @oneOf input object.
  */
-export function setOneOf(program: Program, model: Model): void {
-  setOneOfState(program, model);
+export function setOneOf(model: Model): void {
+  if (model.decorators.some((d) => d.decorator === $oneOf)) return;
+  model.decorators.push({ decorator: $oneOf, args: [] });
 }

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

@@ -112,7 +112,7 @@ export class GraphQLUnionMutation extends UnionMutation<MutationOptions, any, Mu
     const innerType = unwrapNullableUnion(this.sourceType);
     if (innerType) {
       this.#mutationNode.replace(innerType);
-      setNullable(this.engine.$.program, this.mutatedType);
+      setNullable(this.mutatedType);
       // Don't call super.mutate() — replace() swaps the union out of the
       // graph, so there are no variants to iterate.
       return;
@@ -173,7 +173,7 @@ export class GraphQLUnionMutation extends UnionMutation<MutationOptions, any, Mu
     }
 
     if (hasNull) {
-      setNullable(program, this.mutatedType);
+      setNullable(this.mutatedType);
     }
 
     // Wrap scalar variants in synthetic models (GraphQL unions can only contain object types)
@@ -246,10 +246,10 @@ export class GraphQLUnionMutation extends UnionMutation<MutationOptions, any, Mu
     });
 
     // Mark as @oneOf so the emitter can emit the directive
-    setOneOf(program, oneOfModel);
+    setOneOf(oneOfModel);
 
     if (hasNull) {
-      setNullable(program, oneOfModel);
+      setNullable(oneOfModel);
     }
 
     // Replace the union node with the model in the type graph.

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

@@ -499,7 +499,7 @@ describe("GraphQL Mutation Engine - Unions", () => {
     // T | null is replaced with the inner type (string scalar)
     expect(mutation.mutatedType.kind).toBe("Scalar");
     expect(mutation.wrapperModels).toHaveLength(0);
-    expect(isNullable(tester.program, mutation.mutatedType)).toBe(true);
+    expect(isNullable(mutation.mutatedType)).toBe(true);
   });
 
   it("replaces nullable model union with inner type", async () => {
@@ -516,7 +516,7 @@ describe("GraphQL Mutation Engine - Unions", () => {
     // Dog | null is replaced with the inner type (Dog model)
     expect(mutation.mutatedType.kind).toBe("Model");
     expect(mutation.wrapperModels).toHaveLength(0);
-    expect(isNullable(tester.program, mutation.mutatedType)).toBe(true);
+    expect(isNullable(mutation.mutatedType)).toBe(true);
   });
 
   it("creates wrapper models for scalar variants", async () => {
@@ -610,7 +610,7 @@ describe("GraphQL Mutation Engine - Unions", () => {
     expect(nameProp!.type.kind).toBe("Scalar");
 
     // The inner type should be marked as nullable
-    expect(isNullable(tester.program, nameProp!.type)).toBe(true);
+    expect(isNullable(nameProp!.type)).toBe(true);
   });
 });
 
@@ -770,7 +770,7 @@ describe("GraphQL Mutation Engine - Operation Context Propagation", () => {
     const unionMutation = engine.mutateUnion(Pet, GraphQLTypeContext.Input);
     expect(unionMutation.mutatedType.kind).toBe("Model");
     expect(unionMutation.mutatedType.name).toBe("PetInput");
-    expect(isOneOf(tester.program, unionMutation.mutatedType as Model)).toBe(true);
+    expect(isOneOf(unionMutation.mutatedType as Model)).toBe(true);
   });
 
   it("keeps union return type as union via operation mutation", async () => {
@@ -813,7 +813,7 @@ describe("GraphQL Mutation Engine - oneOf Input Objects", () => {
     // Union is replaced with a Model in the type graph
     expect(mutation.mutatedType.kind).toBe("Model");
     expect(mutation.mutatedType.name).toBe("PetInput");
-    expect(isOneOf(tester.program, mutation.mutatedType as Model)).toBe(true);
+    expect(isOneOf(mutation.mutatedType as Model)).toBe(true);
   });
 
   it("oneOf model has one field per variant, all optional", async () => {
@@ -914,7 +914,7 @@ describe("GraphQL Mutation Engine - oneOf Input Objects", () => {
     expect(mutatedUnion.variants.size).toBe(2);
 
     // The result should be marked as nullable
-    expect(isNullable(tester.program, mutatedUnion)).toBe(true);
+    expect(isNullable(mutatedUnion)).toBe(true);
   });
 
   it("strips null from multi-variant union in input context", async () => {
@@ -937,8 +937,8 @@ describe("GraphQL Mutation Engine - oneOf Input Objects", () => {
     expect(model.properties.has("dog")).toBe(true);
 
     // Should be marked as both @oneOf and nullable
-    expect(isOneOf(tester.program, model)).toBe(true);
-    expect(isNullable(tester.program, model)).toBe(true);
+    expect(isOneOf(model)).toBe(true);
+    expect(isNullable(model)).toBe(true);
   });
 
   it("non-nullable union is not marked as nullable", async () => {
@@ -953,7 +953,7 @@ describe("GraphQL Mutation Engine - oneOf Input Objects", () => {
     const engine = createTestEngine(tester.program);
     const mutation = engine.mutateUnion(Pet, GraphQLTypeContext.Output);
 
-    expect(isNullable(tester.program, mutation.mutatedType)).toBe(false);
+    expect(isNullable(mutation.mutatedType)).toBe(false);
   });
 
   it("exposes typeContext on union mutation", async () => {
@@ -971,4 +971,20 @@ describe("GraphQL Mutation Engine - oneOf Input Objects", () => {
     expect(inputMutation.typeContext).toBe(GraphQLTypeContext.Input);
     expect(outputMutation.typeContext).toBe(GraphQLTypeContext.Output);
   });
+
+  it("nullable decorator survives type cloning", async () => {
+    const { NullableString } = await tester.compile(
+      t.code`union ${t.union("NullableString")} { string, null }`,
+    );
+
+    const engine = createTestEngine(tester.program);
+    const mutation = engine.mutateUnion(NullableString, GraphQLTypeContext.Output);
+
+    // Mutation engine strips null and marks the result as nullable
+    expect(isNullable(mutation.mutatedType)).toBe(true);
+
+    // Simulate a downstream mutation stage cloning the type
+    const clone = tester.program.checker.cloneType(mutation.mutatedType);
+    expect(isNullable(clone)).toBe(true);
+  });
 });